@profullstack/timer 0.1.0

package/src/entries.mjs

@@ -0,0 +1,194 @@
+// The domain: what an entry is and the operations on a list of them.
+//
+// Pure functions over a plain array, deliberately. The store owns the file and
+// the lock; the CLI owns argv and printing; this owns the rules. That split is
+// what lets `billing --from-timer` reuse the selection logic without importing
+// a command.
+import { newId } from "./store.mjs";
+import { localDay, parseDuration } from "./time.mjs";
+
+/**
+ * A time entry.
+ *
+ * `end: null` is the running clock — there is no separate "running" record, so
+ * a crash mid-session leaves a recoverable open entry rather than a lost one.
+ * `agent` and `meta` exist because the second audience for this tool is a
+ * coding agent: it should be able to say which model logged the hours and hang
+ * its own identifiers off the entry without a schema change.
+ */
+export function makeEntry({
+  project,
+  task = "",
+  tags = [],
+  start,
+  end = null,
+  notes = "",
+  agent = null,
+  rate = null,
+  billable = true,
+  meta = {},
+}) {
+  if (!project) throw new Error("an entry needs a project");
+  return {
+    id: newId(),
+    project: String(project),
+    task: String(task || ""),
+    tags: [...new Set(tags.map((t) => String(t).trim()).filter(Boolean))],
+    start,
+    end,
+    notes: String(notes || ""),
+    agent: agent ? String(agent) : null,
+    rate: rate == null ? null : Number(rate),
+    billable: Boolean(billable),
+    meta: meta && typeof meta === "object" ? meta : {},
+  };
+}
+
+export const isRunning = (e) => !e.end;
+
+/** Seconds on the clock, counting a running entry up to `now`. */
+export function seconds(entry, now = new Date()) {
+  const start = new Date(entry.start).getTime();
+  const end = entry.end ? new Date(entry.end).getTime() : now.getTime();
+  return Math.max(0, Math.round((end - start) / 1000));
+}
+
+export function running(entries) {
+  return entries.filter(isRunning);
+}
+
+/**
+ * Resolve an id the way git resolves a sha: an unambiguous prefix is enough.
+ * Throws on ambiguity rather than picking one, because the wrong pick here
+ * edits somebody's billable hours.
+ */
+export function findById(entries, id) {
+  const want = String(id).toLowerCase();
+  const exact = entries.find((e) => e.id === want);
+  if (exact) return exact;
+  const hits = entries.filter((e) => e.id.startsWith(want));
+  if (hits.length === 1) return hits[0];
+  if (hits.length > 1) {
+    throw new Error(`id "${id}" is ambiguous (${hits.map((e) => e.id).join(", ")})`);
+  }
+  return null;
+}
+
+/**
+ * Every filter the commands share, in one place.
+ *
+ * A window bound compares against the entry's *start*, and `until` is
+ * exclusive. An entry that spans the boundary therefore belongs to the day it
+ * began on — which is the same rule a timesheet uses, and the only one that
+ * keeps a total from being counted twice.
+ */
+export function select(entries, {
+  project,
+  projects,
+  task,
+  tag,
+  tags,
+  agent,
+  since,
+  until,
+  billable,
+  ids,
+  runningOnly,
+  finishedOnly,
+} = {}) {
+  const wantProjects = [projects, project].flat().filter(Boolean).map((p) => String(p).toLowerCase());
+  const wantTags = [tags, tag].flat().filter(Boolean).map((t) => String(t).toLowerCase());
+  const idSet = ids ? new Set(ids.map(String)) : null;
+  return entries.filter((e) => {
+    if (idSet && !idSet.has(e.id)) return false;
+    if (wantProjects.length && !wantProjects.includes(e.project.toLowerCase())) return false;
+    if (task && !e.task.toLowerCase().includes(String(task).toLowerCase())) return false;
+    if (wantTags.length && !e.tags.some((t) => wantTags.includes(t.toLowerCase()))) return false;
+    if (agent && String(e.agent || "").toLowerCase() !== String(agent).toLowerCase()) return false;
+    if (billable === true && !e.billable) return false;
+    if (billable === false && e.billable) return false;
+    if (runningOnly && !isRunning(e)) return false;
+    if (finishedOnly && isRunning(e)) return false;
+    if (since && e.start < since) return false;
+    if (until && e.start >= until) return false;
+    return true;
+  });
+}
+
+const GROUPERS = {
+  project: (e) => e.project,
+  task: (e) => e.task || "(no task)",
+  tag: (e) => (e.tags.length ? e.tags[0] : "(untagged)"),
+  day: (e) => localDay(e.start),
+  agent: (e) => e.agent || "(human)",
+  none: () => "total",
+};
+
+export const GROUP_KEYS = Object.keys(GROUPERS);
+
+/**
+ * Totals by group, biggest first.
+ *
+ * `billableSeconds` is tracked alongside the total because "how long did this
+ * take" and "what can I charge for it" are different questions and a report
+ * that answers only one of them sends you back to the raw log.
+ */
+export function summarize(entries, { group = "project", now = new Date() } = {}) {
+  const keyOf = GROUPERS[group];
+  if (!keyOf) throw new Error(`unknown grouping "${group}" (${GROUP_KEYS.join(", ")})`);
+  const buckets = new Map();
+  for (const e of entries) {
+    const key = keyOf(e);
+    const secs = seconds(e, now);
+    const bucket = buckets.get(key) || { key, seconds: 0, billableSeconds: 0, entries: 0, running: 0 };
+    bucket.seconds += secs;
+    if (e.billable) bucket.billableSeconds += secs;
+    bucket.entries += 1;
+    if (isRunning(e)) bucket.running += 1;
+    buckets.set(key, bucket);
+  }
+  const rows = [...buckets.values()];
+  // Day groupings read as a chronology; everything else reads as a ranking.
+  if (group === "day") rows.sort((a, b) => a.key.localeCompare(b.key));
+  else rows.sort((a, b) => b.seconds - a.seconds || a.key.localeCompare(b.key));
+  return rows;
+}
+
+export function totals(entries, now = new Date()) {
+  let total = 0;
+  let billable = 0;
+  for (const e of entries) {
+    const s = seconds(e, now);
+    total += s;
+    if (e.billable) billable += s;
+  }
+  return { seconds: total, billableSeconds: billable, entries: entries.length };
+}
+
+/**
+ * Close an entry. `at` defaults to now; an explicit `at` before the start is
+ * refused rather than clamped, because a negative session is a typo and
+ * silently turning it into zero hides it.
+ */
+export function closeEntry(entry, at = new Date().toISOString()) {
+  if (!isRunning(entry)) throw new Error(`entry ${entry.id} is already stopped`);
+  if (at < entry.start) {
+    throw new Error(`cannot stop entry ${entry.id} at ${at}: it started later, at ${entry.start}`);
+  }
+  entry.end = at;
+  return entry;
+}
+
+/** `--duration 90m` on a manual entry, resolved against whichever bound is known. */
+export function boundsFromDuration({ start, end, duration, now = new Date() }) {
+  const secs = duration == null ? null : parseDuration(duration);
+  if (duration != null && secs == null) throw new Error(`cannot read "${duration}" as a duration`);
+  if (start && end) return { start, end };
+  if (start && secs != null) return { start, end: new Date(new Date(start).getTime() + secs * 1000).toISOString() };
+  if (end && secs != null) return { start: new Date(new Date(end).getTime() - secs * 1000).toISOString(), end };
+  if (secs != null) {
+    const endIso = now.toISOString();
+    return { start: new Date(now.getTime() - secs * 1000).toISOString(), end: endIso };
+  }
+  return { start, end };
+}

package/src/output.mjs

@@ -0,0 +1,64 @@
+// Printing. Two audiences, one code path.
+//
+// A human gets aligned columns; an agent gets `--json`. The contract that
+// makes the agent story work is that *every* command answers --json with a
+// single JSON document on stdout and nothing else — no progress lines, no
+// warnings, no colour. Anything advisory goes to stderr, which is why `warn`
+// exists separately.
+const CSI = `${String.fromCharCode(27)}[`;
+const NO_COLOR = Boolean(process.env.NO_COLOR) || !process.stdout.isTTY;
+
+const CODES = { dim: "2", bold: "1", red: "31", green: "32", yellow: "33", cyan: "36" };
+export function paint(style, text) {
+  if (NO_COLOR || !CODES[style]) return String(text);
+  return `${CSI}${CODES[style]}m${text}${CSI}0m`;
+}
+
+export function emit(text = "") {
+  process.stdout.write(`${text}\n`);
+}
+
+export function warn(text) {
+  process.stderr.write(`${text}\n`);
+}
+
+/** The single JSON document a --json run is allowed to print. */
+export function emitJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * An aligned table.
+ *
+ * Column widths come from the visible text, so a value that already carries
+ * colour codes would break alignment — which is why callers pass plain values
+ * and name the columns they want dimmed instead.
+ */
+export function table(rows, columns, { dimCols = [] } = {}) {
+  if (!rows.length) return "";
+  const widths = columns.map((col) =>
+    Math.max(col.header.length, ...rows.map((r) => String(col.get(r) ?? "").length)));
+  const pad = (text, i) => (columns[i].align === "right"
+    ? String(text).padStart(widths[i])
+    : String(text).padEnd(widths[i]));
+  const out = [paint("dim", columns.map((c, i) => pad(c.header, i)).join("  ").trimEnd())];
+  for (const row of rows) {
+    const cells = columns.map((c, i) => {
+      const cell = pad(String(c.get(row) ?? ""), i);
+      return dimCols.includes(c.header) ? paint("dim", cell) : cell;
+    });
+    out.push(cells.join("  ").trimEnd());
+  }
+  return out.join("\n");
+}
+
+/** RFC 4180-ish CSV, because a timesheet ends up in a spreadsheet eventually. */
+export function csv(rows, columns) {
+  const escape = (v) => {
+    const s = v == null ? "" : String(v);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  const lines = [columns.map((c) => escape(c.header)).join(",")];
+  for (const row of rows) lines.push(columns.map((c) => escape(c.get(row))).join(","));
+  return lines.join("\n");
+}

package/src/paths.mjs

@@ -0,0 +1,31 @@
+// Where the timesheet lives, on every platform.
+//
+// One path on all three OSes rather than the usual per-platform data dir
+// (%APPDATA%, ~/Library/Application Support, $XDG_DATA_HOME). That is a
+// deliberate trade: this file is a published contract. `billing --from-timer`
+// reads it, agents read it, and a human is expected to be able to `cat` it
+// while debugging. One documented location is worth more here than OS
+// convention, and homedir() is well defined on Windows too.
+import { homedir } from "node:os";
+import path from "node:path";
+
+/** The shared parent for every Profullstack CLI's state. */
+export function profullstackHome() {
+  return process.env.PROFULLSTACK_HOME || path.join(homedir(), ".profullstack");
+}
+
+/** The directory this CLI owns. */
+export function timerHome() {
+  return process.env.TIMER_HOME || path.join(profullstackHome(), "timer");
+}
+
+/**
+ * The timesheet file itself.
+ *
+ * TIMER_DATA points at a *file*, not a directory, so a test (or an agent
+ * wanting a scratch timesheet) can redirect the whole store with one variable
+ * and no mkdir dance.
+ */
+export function dataFile() {
+  return process.env.TIMER_DATA || path.join(timerHome(), "timesheet.json");
+}

package/src/store.mjs

@@ -0,0 +1,148 @@
+// Reading and writing the timesheet.
+//
+// Two things matter here and nothing else does:
+//
+//   1. A write must never leave a truncated file. Agents run this in the
+//      middle of other work and a half-written timesheet loses real hours,
+//      so every write is tmp-file + rename (atomic on all three platforms —
+//      Node's fs.rename maps to MoveFileEx/MOVEFILE_REPLACE_EXISTING on
+//      Windows, so it overwrites there like it does on POSIX).
+//
+//   2. Two processes must not interleave a read-modify-write. That is not
+//      hypothetical: the whole point of the agent story is several sessions
+//      clocking in at once. mkdir is the atomic primitive available on every
+//      filesystem we care about, so the lock is a directory.
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+
+import { dataFile } from "./paths.mjs";
+
+export const SCHEMA_VERSION = 1;
+
+/** A fresh, empty timesheet. */
+export function emptyStore() {
+  return { version: SCHEMA_VERSION, entries: [] };
+}
+
+/**
+ * A short, URL-safe, human-typeable id.
+ *
+ * Base32 without the letters that get misread aloud or in a terminal font
+ * (i, l, o, u), because these ids end up in `timer stop --id ...` typed by
+ * hand and in invoice line items read by a client.
+ */
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+export function newId(len = 8) {
+  const bytes = randomBytes(len);
+  let out = "";
+  for (const b of bytes) out += ALPHABET[b % ALPHABET.length];
+  return out;
+}
+
+function ensureDir(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+/**
+ * Read the timesheet, tolerating every "not there yet" case.
+ *
+ * A missing file is an empty timesheet, not an error: `timer status` on a
+ * fresh machine should say "nothing running", not crash. A *corrupt* file is
+ * a different matter and does throw — silently starting over would discard
+ * someone's billable hours.
+ */
+export function read(file = dataFile()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return emptyStore();
+    throw err;
+  }
+  if (!raw.trim()) return emptyStore();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `timesheet at ${file} is not valid JSON. Move it aside to start fresh — it has not been touched.`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.entries)) {
+    throw new Error(`timesheet at ${file} is missing its entries array`);
+  }
+  if (parsed.version > SCHEMA_VERSION) {
+    throw new Error(
+      `timesheet at ${file} was written by a newer timer (schema ${parsed.version}); upgrade with: npm install -g @profullstack/timer`,
+    );
+  }
+  return { version: SCHEMA_VERSION, ...parsed, entries: parsed.entries };
+}
+
+export function write(store, file = dataFile()) {
+  ensureDir(file);
+  const tmp = `${file}.${process.pid}.${newId(4)}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify({ ...store, version: SCHEMA_VERSION }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Hold an exclusive lock for the duration of fn.
+ *
+ * Stale locks are reclaimed after `staleMs` because the alternative is a
+ * killed agent wedging the timesheet for everyone until someone finds the
+ * directory by hand. Ten seconds is far longer than any operation here takes
+ * and far shorter than a human's patience.
+ */
+export function withLock(fn, { file = dataFile(), timeoutMs = 5000, staleMs = 10_000 } = {}) {
+  const lock = `${file}.lock`;
+  ensureDir(file);
+  const started = Date.now();
+  for (;;) {
+    try {
+      fs.mkdirSync(lock);
+      break;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      let age = 0;
+      try {
+        age = Date.now() - fs.statSync(lock).mtimeMs;
+      } catch {
+        continue; // vanished between the mkdir and the stat — try again
+      }
+      if (age > staleMs) {
+        try {
+          fs.rmSync(lock, { recursive: true, force: true });
+        } catch { /* someone else won the race; the next mkdir decides */ }
+        continue;
+      }
+      if (Date.now() - started > timeoutMs) {
+        throw new Error(
+          `another timer process is holding ${lock}. If nothing else is running, remove that directory.`,
+        );
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      fs.rmSync(lock, { recursive: true, force: true });
+    } catch { /* best effort — a stale lock is reclaimed above */ }
+  }
+}
+
+/** read → mutate → write, under the lock. Returns whatever fn returns. */
+export function update(fn, { file = dataFile() } = {}) {
+  return withLock(() => {
+    const store = read(file);
+    const result = fn(store);
+    write(store, file);
+    return result;
+  }, { file });
+}

package/src/time.mjs

@@ -0,0 +1,163 @@
+// Durations and dates, in the spellings people actually type.
+//
+// Everything stored is an ISO-8601 UTC instant. Everything *typed* is local
+// and loose — "1h30m", "90m", "1.5h", "yesterday", "2026-08-01", "09:15".
+// This module is the only place that converts between the two, so there is
+// one answer to "what does --since mean" rather than one per command.
+
+const UNITS = { w: 604800, d: 86400, h: 3600, m: 60, s: 1 };
+
+/**
+ * Parse a duration into seconds. Returns null when it is not a duration —
+ * callers decide whether that is an error, because "1h" and "an id" arrive
+ * through the same argument in a couple of places.
+ *
+ * Accepts "1h30m", "1h 30m", "90m", "1.5h", "45s", "2d4h", and a bare number
+ * (minutes — the unit people mean when they omit one for a work session).
+ */
+export function parseDuration(input) {
+  if (input == null) return null;
+  const text = String(input).trim().toLowerCase().replace(/\s+/g, "");
+  if (!text) return null;
+  if (/^\d+(\.\d+)?$/.test(text)) return Math.round(Number(text) * 60);
+  const re = /(\d+(?:\.\d+)?)([wdhms])/g;
+  let total = 0;
+  let matched = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    total += Number(m[1]) * UNITS[m[2]];
+    matched += m[0].length;
+  }
+  if (matched !== text.length || total <= 0) return null;
+  return Math.round(total);
+}
+
+/** "2h 15m" — the human spelling, for terminals. */
+export function formatDuration(seconds, { compact = false } = {}) {
+  const s = Math.max(0, Math.round(seconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  const parts = [];
+  if (h) parts.push(`${h}h`);
+  if (m) parts.push(`${m}m`);
+  // Seconds only matter when they are all there is — an 8-hour day reported
+  // to the second reads like a stopwatch, not a timesheet.
+  if (!h && (sec || !m)) parts.push(`${sec}s`);
+  return parts.join(compact ? "" : " ");
+}
+
+/** Decimal hours, rounded to 2dp — the number that goes on an invoice. */
+export function hours(seconds) {
+  return Math.round((seconds / 3600) * 100) / 100;
+}
+
+function startOfDay(d) {
+  const out = new Date(d);
+  out.setHours(0, 0, 0, 0);
+  return out;
+}
+
+/**
+ * Parse a moment. Local time in, UTC ISO string out.
+ *
+ * Handles the words ("now", "today", "yesterday"), a bare clock time ("09:15"
+ * — today at that time), a date ("2026-08-01"), a full ISO instant, and a
+ * negative offset ("-90m", "-2h") meaning "that long ago", which is how you
+ * fix a clock you forgot to start.
+ */
+export function parseMoment(input, { now = new Date() } = {}) {
+  if (input == null) return null;
+  const text = String(input).trim();
+  if (!text) return null;
+  const lower = text.toLowerCase();
+  if (lower === "now") return new Date(now).toISOString();
+  if (lower === "today") return startOfDay(now).toISOString();
+  if (lower === "yesterday") {
+    const d = startOfDay(now);
+    d.setDate(d.getDate() - 1);
+    return d.toISOString();
+  }
+  if (lower.startsWith("-")) {
+    const secs = parseDuration(lower.slice(1));
+    if (secs == null) return null;
+    return new Date(now.getTime() - secs * 1000).toISOString();
+  }
+  // A bare clock time means today. This is the common case for `--at 09:15`
+  // ("I actually started at quarter past") and would otherwise be a parse
+  // error or, worse, 1970.
+  const clock = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(text);
+  if (clock) {
+    const d = startOfDay(now);
+    d.setHours(Number(clock[1]), Number(clock[2]), Number(clock[3] || 0), 0);
+    return d.toISOString();
+  }
+  // A bare date is midnight local, not midnight UTC. `new Date("2026-08-01")`
+  // parses as UTC per the spec, which silently shifts a whole day's entries
+  // across the boundary for anyone west of Greenwich.
+  const ymd = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  if (ymd) {
+    const d = new Date(Number(ymd[1]), Number(ymd[2]) - 1, Number(ymd[3]), 0, 0, 0, 0);
+    return d.toISOString();
+  }
+  const parsed = new Date(text);
+  if (Number.isNaN(parsed.getTime())) return null;
+  return parsed.toISOString();
+}
+
+/**
+ * Turn --since/--until/--today/--week/--month/--period into a concrete window.
+ * Both bounds are ISO strings or null (unbounded). `until` is exclusive.
+ */
+export function resolveWindow(flags = {}, { now = new Date() } = {}) {
+  const period = flags.period
+    || (flags.today && "today")
+    || (flags.week && "week")
+    || (flags.month && "month")
+    || (flags.year && "year")
+    || null;
+
+  let since = flags.since ? parseMoment(flags.since, { now }) : null;
+  let until = flags.until ? parseMoment(flags.until, { now }) : null;
+  if (flags.since && !since) throw new Error(`--since: cannot read "${flags.since}" as a date`);
+  if (flags.until && !until) throw new Error(`--until: cannot read "${flags.until}" as a date`);
+
+  if (period) {
+    const from = startOfDay(now);
+    switch (period) {
+      case "today": break;
+      case "yesterday": {
+        from.setDate(from.getDate() - 1);
+        const to = new Date(from);
+        to.setDate(to.getDate() + 1);
+        return { since: from.toISOString(), until: to.toISOString() };
+      }
+      case "week": {
+        // Monday-based: a work week starts on Monday everywhere this is used.
+        const dow = (from.getDay() + 6) % 7;
+        from.setDate(from.getDate() - dow);
+        break;
+      }
+      case "month": from.setDate(1); break;
+      case "year": from.setMonth(0, 1); break;
+      default: throw new Error(`--period: unknown period "${period}" (today, yesterday, week, month, year)`);
+    }
+    since = since || from.toISOString();
+  }
+  return { since, until };
+}
+
+/** Local YYYY-MM-DD for an ISO instant — the key `report --group day` uses. */
+export function localDay(iso) {
+  const d = new Date(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/** Short local timestamp for tables: "Aug 29 14:05". */
+export function shortStamp(iso) {
+  const d = new Date(iso);
+  const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${months[d.getMonth()]} ${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}