create-json

Collects your Git commits for a day into a commits.json file for the AI Timesheet Engine, and — via gen-timesheet — generates the timesheet itself in the same step. Uses only local Git data — no network access, no GitHub/GitLab credentials, beyond gen-timesheet's one call to whichever AI Timesheet Engine instance you point it at. Zero npm dependencies.

Usage

No install needed — run it with npx from inside any Git repository:

npx ai-timesheet-create-json

AI Timesheet - Commit Collector

✓ Git repository detected
✓ Developer: Sukanta
✓ Date: 2026-08-21
✓ Found 2 commits
✓ Generated commits.json

File: ./commits.json

Options:

npx ai-timesheet-create-json --date 2026-08-19   # a specific day, not today
npx ai-timesheet-create-json --force             # overwrite without asking
npx ai-timesheet-create-json --out report.json   # write somewhere else
npx ai-timesheet-create-json --help

If the day had no commits, the command still succeeds and writes an empty commits array. If the current directory isn't a Git repository, or the Git identity (git config user.name/user.email) isn't set, it explains what to do and exits non-zero without writing anything.

Note on npx <path-to-a-local-.tgz-file>: resolving a local tarball by file path is slow and can silently no-op in some npm versions — a known npx rough edge with local specs, not specific to this package. Installing or linking the package (npm install -g . / npm link) and then running npx create-json by name works immediately, as does running the published package by name.

Install (optional)

npx needs no install, but for repeated local use:

npm install -g ai-timesheet-create-json
create-json

Output

Written to the current working directory (wherever you ran the command from — not necessarily the repo root):

{
  "date": "2026-08-21",
  "developer": { "name": "Sukanta", "email": "[email protected]" },
  "commits": [
    {
      "hash": "1d2d64f3097a55819539a1f833dc8ea622e1b364",
      "message": "feat: add API endpoint",
      "author": "Sukanta",
      "timestamp": "2026-08-21T10:10:00+05:30",
      "files": ["src/api.ts"],
      "additions": 1,
      "deletions": 0
    }
  ],
  "options": { "taskCount": 2, "tone": "professional", "includeCommitReferences": true }
}

Feed this straight to the engine:

curl -X POST http://localhost:8000/api/v1/timesheets/generate \
  -H "Content-Type: application/json" \
  -d @commits.json

The bare command never calls the AI Timesheet Engine itself — collecting Git activity is its only job. gen-timesheet, below, does both in one step.

gen-timesheet: collect AND generate, in one step

npx ai-timesheet-create-json gen-timesheet --url https://your-deployment.example.com --api-key tsk_...

Writes commits.json exactly like the bare command, then immediately POSTs it to {url}/api/v1/timesheets/generate and prints the result — no separate curl call needed:

AI Timesheet - Generate

✓ Git repository detected
✓ Developer: Sukanta
✓ Date: 2026-08-21
✓ Found 2 commits
✓ Generated commits.json
File: ./commits.json

Calling https://your-deployment.example.com ...

Generated 2 timesheet tasks
Date: 2026-08-21   Developer: Sukanta

1. Design and Develop Result Analysis API Service Functionality
...

By default it calls http://localhost:8000. You only have to type --url/ --api-key once — a tsk_... token isn't something anyone is going to retype from memory, so the first time either is given, both are saved to ~/.ai-timesheet/config.json and every later run reuses them automatically:

npx ai-timesheet-create-json gen-timesheet --url https://your-deployment.example.com --api-key tsk_...
npx ai-timesheet-create-json gen-timesheet   # nothing to type from here on

npx ai-timesheet-create-json logout          # forget the saved url/key

Passing --url/--api-key again later overwrites just what was saved for that one, without needing to repeat the other. Environment variables ($AI_TIMESHEET_API_URL/$AI_TIMESHEET_API_KEY) still work too, and take priority over the saved file — handy for a one-off override, or CI, where nothing should be written to disk:

AI_TIMESHEET_API_URL=https://staging.example.com AI_TIMESHEET_API_KEY=tsk_ci_... \
  npx ai-timesheet-create-json gen-timesheet

The saved file holds the token in plain text, protected only by the file's 0600 permissions (owner read/write only — not meaningfully enforced on Windows) — reasonable for a personal machine, not for a shared one. Use logout there, or stick to the environment variable.

No tsk_... key? Log in with a password instead

A tsk_... API key needs an administrator to mint one (create-key, or database access). If you have an account with a password instead — the same one the web login page uses — login gets you a working session the same way, no admin needed:

npx ai-timesheet-create-json login --url https://your-deployment.example.com

Email: [email protected]
Password:
✓ Logged in as Sukanta <[email protected]>.
✓ Saved to ~/.ai-timesheet/config.json (used automatically next time, until it expires at 2026-08-25T11:34:20Z).

Saved the same way, in the same file, as --api-key — gen-timesheet reuses it automatically after this, no further flags needed. Unlike a tsk_... key, a login session expires (whatever JWT_EXPIRY_MINUTES the server is configured with, 24 hours by default); once it does, gen-timesheet fails fast with a clear message telling you to run login again, rather than a confusing generic authentication error.

Options (in addition to --date/--out/--force, which behave exactly as for the bare command): (in addition to --date/--out/--force, which behave exactly as for the bare command):

npx ai-timesheet-create-json gen-timesheet --url <url>       # saved after first use; see above
npx ai-timesheet-create-json gen-timesheet --api-key <key>   # saved after first use; see above
npx ai-timesheet-create-json gen-timesheet --tasks 3         # tasks to generate (1-10, default 2)
npx ai-timesheet-create-json gen-timesheet --persist         # ask the server to store the result
npx ai-timesheet-create-json gen-timesheet --json            # emit the full JSON response, not the summary
npx ai-timesheet-create-json gen-timesheet --timeout 30      # seconds to wait for a response (default 120)
npx ai-timesheet-create-json gen-timesheet --no-save         # don't write commits.json at all
npx ai-timesheet-create-json gen-timesheet --help
npx ai-timesheet-create-json logout                          # forget the saved --url/--api-key

Failures are reported the way a person reading a terminal wants them, never a raw Node stack trace — a non-2xx response's own structured error message is surfaced directly (the same {"error": {"message": ...}} shape every endpoint returns):

✗ Missing or invalid API key.
  Set --api-key or $AI_TIMESHEET_API_KEY to a valid token.

✗ Could not reach http://localhost:9: connect ECONNREFUSED 127.0.0.1:9. Is the server running and the URL correct?

Built on Node's built-in http/https modules, not a dependency (undici, axios, node-fetch, ...) — this keeps the package at zero npm dependencies, the same reasoning that keeps the rest of it dependency-free.

Implementation notes

• Full commit SHAs, not abbreviations.
• File paths are repository-relative, never absolute, regardless of which subdirectory the command runs from.
• Merge commits are included (if authored by you) but report no changed files — git diff-tree without -m/--cc produces no diff for a merge by default, which avoids double-counting lines already attributed to the commits the merge brought in. The root commit is the mirror-image case: --root is required so it correctly reports its files as additions instead of also coming back empty.
• Author matching compares email addresses exactly (case-insensitively) rather than treating git log --author= as a regular expression against an address that isn't guaranteed to be regex-safe.
• Date filtering uses --since-as-filter, not plain --since: the plain form stops walking history at the first out-of-order-dated commit (which a rebase or --date-amended commit can produce), silently under-reporting. Requires Git 2.28+ (2020).
• Every git invocation goes through one function using child_process.spawnSync with an argument array (shell: false) — never a string. A commit message containing quotes, $(), backticks, or ; is passed to the OS as a single argv entry and can never be reinterpreted as a shell command.

Development

npm test        # runs against real, disposable Git repositories and a real
                 # local http.Server standing in for the API (gen-timesheet)
npm pack        # produces a tarball for local install testing
npm link        # exposes `create-json` on PATH from this checkout

No dependencies, no build step — plain CommonJS, Node's built-in test runner.