npm package: @modunet/devtrack
Description: CLI wrapper that automatically records ModuNet time-tracking when starting a dev server
Author: Michael Bigalke
Latest version: 1.0.13

# @modunet/devtrack

Time tracking for developers—designed for freelancers and independents who want to capture their effective project time accurately. This CLI attaches your dev server (Nuxt, Vue, NestJS, etc.) to **ModuNet**: when you start your dev command, a session starts automatically, pings are sent while it runs, and time stops when the process exits.

**ModuNet:**  
Find more information at: **https://modunet.app**

---

## Features

 Create a `modunet.json` in your project root or use environment variables. The configuration can be generated via ModuNet — log in to ModuNet and use the configuration generator to obtain your token, projectId, and optional orgaId.
 - Optional fields: `comment`, `repoUrl`, `branch`, `noTracking`, `modunetUrl`
 - Default endpoint: `https://modunet.app`
 - Configurable via `modunet.json` or environment variables (`MODUNET_TOKEN`, `MODUNET_PROJECT_ID`, `MODUNET_ORGA_ID`, ...)
 - Detailed warnings when requests fail (e.g., wrong endpoint or invalid token)

---

## Installation

```bash
npm install --global @modunet/devtrack
# or
pnpm add --global @modunet/devtrack
```

If you prefer a project-local installation instead:

```bash
npm install --save-dev @modunet/devtrack
# or
pnpm add -D @modunet/devtrack
```

## Usage

Start your dev server through the wrapper:

```bash
export MODUNET_ORGA_ID=YOUR_ORGA_ID_OPTIONAL
modunet-devtrack -- npm run dev
# or
modunet-devtrack -- pnpm dev
```

If you installed the package locally in the project, use `npx modunet-devtrack -- npm run dev` or reference it through your package scripts.

To start the wrapper automatically every time, configure your `package.json` scripts so the original dev command is wrapped once:

```json
{
  "scripts": {
    "dev": "modunet-devtrack -- nest start --watch"
  }
}
```

If you want to keep the original command available as well, split it into a base script and a tracked script:

```json
{
  "scripts": {
    "dev:raw": "nest start --watch",
    "dev": "modunet-devtrack -- npm run dev:raw"
  }
}
```

Commands are executed directly without an intermediate shell. Standard commands such as `npm run dev`, `pnpm dev`, `node server.js`, or `nest start --watch` work as expected.

If you need shell features such as `&&`, `||`, pipes, redirects, or environment expansion, wrap the command explicitly:

```bash
modunet-devtrack -- sh -lc "npm run dev && npm run lint"
```

## Configuration

- On first run, a `modunet.json` file is created in your project root with sensible defaults.
- Required fields: 
    `token`   => Get it from https://modunet.app/profile
    `projectId` => Define it on your own, projects are grouped by this id (Can be changed on every startup)
- Optional fields: `comment`, `repoUrl`, `branch`, `noTracking`, `modunetUrl`.
- Possible environment overrides (take precedence over the file):
  - `MODUNET_TOKEN`, `MODUNET_PROJECT_ID`, `MODUNET_ORGA_ID`
  - `MODUNET_URL`, `MODUNET_COMMENT`, `MODUNET_REPO_URL`, `MODUNET_BRANCH`
  - `MODUNET_NO_TRACKING` (`true`/`false`)
- Branch and repository URL are auto-detected from git when not provided.
- Tracking is skipped automatically when `CI=true` or `noTracking=true`.

## Programmatic use

The package also exports the API client and types if you need to integrate manually:

```ts
import { ModuNetClient } from '@modunet/devtrack';

const client = new ModuNetClient({
  modunetUrl: 'https://modunet.app',
  token: 'token-from-modunet',
  projectId: 'project-id',
  orgaId: 'optional-orga-id'
});

await client.startSession({
  tool: 'custom-script'
});

```