@profullstack/timer 0.1.0

package/AGENTS.md

@@ -0,0 +1,103 @@
+# timer, for agents
+
+`timer` is a time tracker whose second audience is a program. This file is the
+contract.
+
+## The rules
+
+1. **`--json` works on every command.** It prints one JSON document on stdout
+   and nothing else.
+2. **Advisories go to stderr.** `timer start` may warn that another clock is
+   running; that never appears on stdout.
+3. **A failed run prints nothing on stdout.** The error goes to stderr as
+   `{"error": "...", "kind": "..."}`. Parsing stdout can never give you a
+   success shape for a command that failed.
+4. **Exit codes mean something.**
+
+   | Code | Meaning |
+   | --- | --- |
+   | 0 | success |
+   | 1 | runtime failure (unreadable timesheet, locked file) |
+   | 2 | bad command line (unknown flag, missing argument, impossible range) |
+   | 3 | you named an entry that does not exist |
+
+5. **An unknown flag is an error**, never silently ignored. If `timer log
+   --bogus` exits 0 you are on a different tool.
+
+## The entry schema
+
+Everything `--json` returns is built from this shape:
+
+```json
+{
+  "id": "4f2ap8qk",
+  "project": "acme",
+  "task": "fix the login redirect",
+  "tags": ["dev", "api"],
+  "start": "2026-08-29T09:00:00.000Z",
+  "end": "2026-08-29T10:30:00.000Z",
+  "running": false,
+  "seconds": 5400,
+  "hours": 1.5,
+  "billable": true,
+  "rate": null,
+  "agent": "claude-opus-5",
+  "notes": "",
+  "meta": {}
+}
+```
+
+`end` is `null` while the clock runs, and `seconds` counts up to now.
+`hours` is rounded to two decimals — it is the number that goes on an invoice.
+
+## Clocking your own work
+
+```sh
+export TIMER_AGENT="claude-opus-5"
+ID=$(timer start acme --task "refactor auth" --json | jq -r .started.id)
+# ... do the work ...
+timer stop --id "$ID" --json
+```
+
+Several clocks may run at once, which is the point: parallel agents each track
+their own work and do not stop each other. Use `--switch` only if you mean to
+close everyone else's clock.
+
+If you did the work before you thought to time it, record it after the fact:
+
+```sh
+timer add acme --task "refactor auth" --duration 45m --json
+```
+
+## Attaching your own identifiers
+
+`--meta` takes a JSON object and stores it unchanged:
+
+```sh
+timer add acme --duration 20m --meta '{"repo":"acme/api","pr":42}' --json
+```
+
+Filter later with `timer log --agent claude-opus-5 --json`.
+
+## Reading the timesheet directly
+
+If you would rather not shell out, the file is plain JSON at
+`~/.profullstack/timer/timesheet.json` (or `$TIMER_DATA`):
+
+```json
+{ "version": 1, "entries": [ /* raw entries */ ] }
+```
+
+Two cautions. Raw entries have no `seconds`/`hours`/`running` — those are
+computed. And writes are locked: if you write the file yourself while a `timer`
+process is running you can lose an entry. Prefer the CLI for writes and the
+file for reads.
+
+## Billing the hours
+
+`@profullstack/billing` reads the same file and will not bill the same entry
+twice:
+
+```sh
+billing invoice new --client acme --from-timer --month --json
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# timer
+
+Track time against projects, from the terminal, on Linux, macOS and Windows.
+
+It is a stopwatch with a memory: start a clock on a project, stop it, and get
+billable hours back. Every command also speaks `--json`, so a coding agent can
+clock its own work the same way you do — and
+[`@profullstack/billing`](https://github.com/profullstack/billing) turns those
+hours into invoices.
+
+```sh
+npm install -g @profullstack/timer
+```
+
+Node 20.11 or newer. No runtime dependencies.
+
+## Use it
+
+```sh
+timer start acme fix the login redirect     # everything after the project is the task
+timer status                                # what is running, and today's total
+timer stop
+
+timer add acme code review --duration 45m   # time you forgot to clock
+timer add acme --from 09:00 --to 11:30
+
+timer log --week                            # what happened
+timer report --month --group project        # what it adds up to
+timer projects                              # everything you have ever tracked
+```
+
+Nothing is configured before first use. The timesheet appears the first time
+you start a clock.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `start <project> [task…]` | Start a clock. `--at 09:15`, `--at -20m`, `--tag`, `--note`, `--rate`, `--switch` |
+| `stop [id]` | Stop the newest clock, an id, `--project <p>`, or `--all` |
+| `status` | Running clocks and today's total |
+| `log [project]` | List entries in a window |
+| `add <project> [task…]` | Record untimed work from two of `--from` / `--to` / `--duration` |
+| `edit <id>` | Change any field of an entry |
+| `rm <id…>` | Delete entries (`--force` for a running one) |
+| `resume [id]` | Start a fresh clock like the last one |
+| `note <text…>` | Append a note to the running clock |
+| `report` | Totals, `--group project\|task\|tag\|day\|agent\|none` |
+| `projects` | Projects seen, with totals and last activity |
+| `export` | `--format json\|ndjson\|csv`, `--out <file>` |
+| `config` | Where the timesheet lives |
+
+`timer help <command>` prints the flags and examples for one command.
+
+### Windows of time
+
+`log`, `report`, `projects` and `export` all take the same window flags:
+`--today`, `--yesterday`, `--week` (from Monday), `--month`, `--year`, or an
+explicit `--since` / `--until`.
+
+Dates are loose on purpose: `09:15`, `2026-08-01`, `-2h`, `yesterday`, or a
+full ISO instant. A bare date means local midnight, not UTC midnight.
+
+A window compares against the entry's **start**, and `--until` is exclusive. An
+entry that runs past midnight therefore belongs to the day it began on — which
+is what keeps a total from being counted twice.
+
+### Billable and not
+
+Every entry is billable unless you say otherwise with `--no-billable`. Reports
+carry both numbers, because "how long did this take" and "what can I charge for
+it" are different questions:
+
+```sh
+timer add internal standup --duration 15m --no-billable
+timer report --month
+```
+
+## For agents
+
+Two things make this usable by an agentic CLI without a wrapper.
+
+**Every command answers `--json`** with a single JSON document on stdout and
+nothing else. Advisory lines go to stderr. A command that fails prints its
+error as JSON on **stderr** and leaves stdout empty, so parsing stdout can
+never yield a success shape for a failed run.
+
+**Exit codes are distinct**: `0` success, `1` a runtime failure, `2` a bad
+command line, `3` you named something that is not there. `timer stop` with no
+clock running is a `0` — that is an answer, not a failure.
+
+```sh
+export TIMER_AGENT="claude-opus-5"            # stamps every entry it creates
+timer start acme --task "refactor auth" --json
+timer stop --json
+timer log --today --json
+```
+
+`--meta '{"pr":42}'` hangs your own identifiers off an entry, and they survive
+round-trip unchanged.
+
+There is more detail, including the entry schema, in [AGENTS.md](AGENTS.md).
+
+## Where the data lives
+
+One JSON file, in one place on every platform:
+
+```
+~/.profullstack/timer/timesheet.json
+```
+
+| Variable | Overrides |
+| --- | --- |
+| `TIMER_DATA` | the timesheet file itself |
+| `TIMER_HOME` | the directory it sits in |
+| `PROFULLSTACK_HOME` | the parent shared with other Profullstack CLIs |
+| `TIMER_AGENT` | the agent name stamped on new entries |
+| `NO_COLOR` | turns off colour |
+
+`timer config` prints all of it. The file is plain JSON you can read and edit;
+writes are atomic and locked, so several agents can clock in at once without
+losing an entry.
+
+## With billing
+
+`@profullstack/billing` reads this file directly — it does not need `timer` on
+`PATH` — and turns unbilled hours into invoice line items:
+
+```sh
+billing invoice new --client acme --from-timer --month
+```
+
+## In moshcode
+
+[moshcode](https://github.com/moshcoder/moshcode) installs and fronts it:
+
+```
+moshcode install timer
+/timer start acme fix the login redirect
+```
+
+## Licence
+
+MIT © Profullstack, LLC

package/bin/timer.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+process.exitCode = main();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@profullstack/timer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A time tracker for the terminal and for agents — start a clock against a project, stop it, and get billable hours back as text or JSON.",
+  "keywords": ["timer", "time-tracking", "timesheet", "billable", "hours", "cli", "agent", "freelance"],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/timer.git" },
+  "homepage": "https://github.com/profullstack/timer#readme",
+  "bugs": { "url": "https://github.com/profullstack/timer/issues" },
+  "license": "MIT",
+  "author": "Profullstack, LLC",
+  "bin": { "timer": "bin/timer.mjs" },
+  "files": ["bin", "src", "README.md", "AGENTS.md", "LICENSE"],
+  "engines": { "node": ">=20.11" },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/timer.mjs"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,83 @@
+// A small argv parser, hand-rolled so the package stays dependency-free.
+//
+// The one rule worth stating: a flag only consumes the next token if it is
+// declared as taking a value. Guessing from the shape of the next token is
+// what makes `timer log --json acme` mean two different things on two
+// different days, and this tool is meant to be scripted by agents.
+export function parseArgs(argv, { booleans = [], values = [], multi = [], aliases = {} } = {}) {
+  const isBool = new Set(booleans);
+  const takesValue = new Set([...values, ...multi]);
+  const isMulti = new Set(multi);
+  const flags = Object.create(null);
+  const positional = [];
+  const rest = [];
+  const unknown = [];
+
+  const resolve = (name) => aliases[name] || name;
+  const set = (name, value) => {
+    if (isMulti.has(name)) (flags[name] ||= []).push(value);
+    else flags[name] = value;
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--") {
+      rest.push(...argv.slice(i + 1));
+      break;
+    }
+    if (token.startsWith("--")) {
+      let body = token.slice(2);
+      let inline = null;
+      const eq = body.indexOf("=");
+      if (eq !== -1) {
+        inline = body.slice(eq + 1);
+        body = body.slice(0, eq);
+      }
+      if (body.startsWith("no-")) {
+        const name = resolve(body.slice(3));
+        flags[name] = false;
+        continue;
+      }
+      const name = resolve(body);
+      if (isBool.has(name)) {
+        // `--json=false` is the one way to turn a boolean off inline; agents
+        // building command lines from templates rely on it.
+        flags[name] = inline == null ? true : !/^(0|false|no)$/i.test(inline);
+        continue;
+      }
+      if (takesValue.has(name)) {
+        const value = inline != null ? inline : argv[++i];
+        if (value === undefined) throw new Error(`--${body} needs a value`);
+        set(name, value);
+        continue;
+      }
+      unknown.push(`--${body}`);
+      continue;
+    }
+    if (token.length > 1 && token.startsWith("-") && !/^-\d/.test(token)) {
+      // Short flags, including bundles (-qj). A bundled flag that takes a
+      // value must be last, the way tar and grep do it.
+      const letters = token.slice(1).split("");
+      for (let j = 0; j < letters.length; j += 1) {
+        const name = resolve(letters[j]);
+        if (isBool.has(name)) { flags[name] = true; continue; }
+        if (takesValue.has(name)) {
+          const inline = letters.slice(j + 1).join("");
+          const value = inline || argv[++i];
+          if (value === undefined) throw new Error(`-${letters[j]} needs a value`);
+          set(name, value);
+          break;
+        }
+        unknown.push(`-${letters[j]}`);
+      }
+      continue;
+    }
+    positional.push(token);
+  }
+  return { flags, positional, rest, unknown };
+}
+
+/** Flags every command answers to, so they are declared once. */
+export const GLOBAL_BOOLEANS = ["json", "help", "version", "quiet"];
+export const GLOBAL_VALUES = ["data"];
+export const GLOBAL_ALIASES = { h: "help", v: "version", q: "quiet", j: "json" };