@tokenoftrust/cli 2.0.3 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/machine-id.mjs

@@ -0,0 +1,72 @@
+/**
+ * A stable per-machine identifier, persisted in `~/.tot/config.json` alongside
+ * whatever else already lives there. Read/write is additive — we merge just the
+ * `machineId` key in, so other tools' fields (e.g. `runtimes`) ride along
+ * untouched, same philosophy as token-store's schema-free credential file.
+ *
+ * Not a secret, but kept 0600 in a 0700 dir like the rest of `~/.tot` for
+ * consistency. `TOT_HOME` overrides the home dir (tests point it at a temp dir),
+ * like activity-log and token-store.
+ *
+ * Best-effort by contract: never throws. A persist failure still returns a
+ * usable (if unpersisted) id for the current call.
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir, hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+
+/** Absolute path to the machine-level config for this environment. */
+export function configPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "config.json");
+}
+
+/** Read the parsed config, or {} if absent/unreadable/malformed. Never throws. */
+export function readConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(env), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge `patch` into the existing config and write it back atomically (temp-file
+ * rename, 0600), preserving keys `patch` doesn't mention. Returns the merged
+ * config, or null on failure. Never throws.
+ */
+export function writeConfig(patch, env = process.env) {
+  try {
+    const filePath = configPath(env);
+    const merged = { ...readConfig(env), ...patch };
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, filePath);
+    chmodSync(filePath, 0o600);
+    return merged;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This machine's stable id: read from config if present, else generate a UUID
+ * and persist it for next time. Never throws.
+ */
+export function ensureMachineId(env = process.env) {
+  const existing = readConfig(env).machineId;
+  if (typeof existing === "string" && existing) return existing;
+  const id = randomUUID();
+  const written = writeConfig({ machineId: id }, env);
+  return (written && written.machineId) || id;
+}
+
+/** This machine's hostname (not persisted — just os.hostname()). */
+export function host() {
+  return hostname();
+}

package/src/telemetry.mjs

@@ -0,0 +1,126 @@
+/**
+ * Git-ops telemetry — a durable, queryable record of fold/reap/sync/deploy stage
+ * transitions, so "what's slow / what's failing / what keeps needing a human" is
+ * answerable without a manual digging session after the fact.
+ *
+ * A SIBLING to activity-log.mjs, not an extension of it: activity-log is a
+ * 300-line RING (correct for its feedback-breadcrumb use case — bounded, most
+ * recent wins). Telemetry needs the opposite shape — unbounded, longitudinal
+ * history — so it uses a separate, date-partitioned, append-only stream:
+ * `~/.tot/telemetry/YYYY-MM.jsonl` (one file per UTC calendar month, partitioned
+ * by the entry's own `ts`), never truncated. Retention is "delete whole expired
+ * partitions" (see pruneOldPartitions), not the ring's overwrite-oldest-entry.
+ *
+ * Kept deliberately generic and self-describing: no coupling to
+ * workstream_analytics' event-journal shape. Callers own their own event schema
+ * (op/stage/reason codes are a separate concern — see the git-ops-telemetry
+ * handoff's U2 — not this module's).
+ *
+ * Append strategy differs from activity-log's temp+rename-the-whole-file (right
+ * for a small bounded ring, wrong here — it would mean rewriting a growing
+ * multi-KB month file on every single stage transition). Instead this appends
+ * with a single O_APPEND write() per entry: POSIX guarantees a single write()
+ * below PIPE_BUF is atomic, so concurrent writers (several git-ops scripts
+ * running at once, on one machine) can't interleave partial lines.
+ *
+ * NEVER throws / never blocks the caller — same best-effort contract as
+ * activity-log. `TOT_HOME` overrides the home dir (tests).
+ *
+ * A parallel POSIX-shell implementation lives at `scripts/lib/telemetry.sh` for
+ * the bash git-ops scripts this feeds — shelling out to `node` per stage
+ * transition would add measurement noise to the durations being measured. The
+ * two are separate, from-scratch implementations (no way to share code across
+ * languages); `scripts/lib/telemetry-cross-impl.test.mjs` exercises both against
+ * the same inputs and asserts schema-identical output as a drift guard. Any
+ * change to the on-disk shape here must be mirrored there.
+ */
+import {
+  appendFileSync, mkdirSync, chmodSync, readdirSync, rmSync, existsSync, readFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { redactArgs } from "./activity-log.mjs";
+import { ensureMachineId, host } from "./machine-id.mjs";
+
+/** Keep telemetry partitions for this many days; whole months older than this are pruned. */
+export const RETENTION_DAYS = 90;
+
+/** Directory holding all telemetry partitions for this environment. */
+export function telemetryDir(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "telemetry");
+}
+
+/** The `YYYY-MM` partition key for a Date, in UTC. */
+export function monthKey(date) {
+  return date.toISOString().slice(0, 7);
+}
+
+/** Absolute path to the partition file a given Date's entries land in. */
+export function telemetryPath(date, env = process.env) {
+  return join(telemetryDir(env), `${monthKey(date)}.jsonl`);
+}
+
+function stamped(entry, env) {
+  const out = { ...entry };
+  if (!out.ts) out.ts = new Date().toISOString();
+  if (!out.host) out.host = host();
+  if (!out.machineId) out.machineId = ensureMachineId(env);
+  if (Array.isArray(out.args)) out.args = redactArgs(out.args);
+  return out;
+}
+
+/**
+ * Delete partitions wholly older than `retentionDays`. Cheap to run on every
+ * write: partition files number in the dozens at most (one per month), so a
+ * full directory listing per call is fine — no separate prune entrypoint or
+ * schedule to forget to run.
+ */
+export function pruneOldPartitions(env = process.env, { retentionDays = RETENTION_DAYS, now = new Date() } = {}) {
+  try {
+    const dir = telemetryDir(env);
+    if (!existsSync(dir)) return;
+    const cutoff = monthKey(new Date(now.getTime() - retentionDays * 24 * 60 * 60 * 1000));
+    for (const name of readdirSync(dir)) {
+      const match = name.match(/^(\d{4}-\d{2})\.jsonl$/);
+      if (match && match[1] < cutoff) {
+        rmSync(join(dir, name), { force: true });
+      }
+    }
+  } catch {
+    /* best-effort: never throw */
+  }
+}
+
+/**
+ * Append one telemetry entry to its month partition. Stamps `ts`/`host`/
+ * `machineId` when the caller omits them (never overrides an explicit value),
+ * redacts `args` if present (same secret flags as activity-log), and prunes
+ * expired partitions after a successful write. Returns the entry actually
+ * written, or null on failure. Never throws.
+ */
+export function recordTelemetry(entry, env = process.env) {
+  try {
+    const full = stamped(entry, env);
+    const dir = telemetryDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const filePath = telemetryPath(new Date(full.ts), env);
+    appendFileSync(filePath, `${JSON.stringify(full)}\n`, { mode: 0o600, flag: "a" });
+    chmodSync(filePath, 0o600);
+    pruneOldPartitions(env);
+    return full;
+  } catch {
+    return null;
+  }
+}
+
+/** Read parsed entries from one month's partition (default: current UTC month). Never throws. */
+export function readTelemetry(env = process.env, { month = "" } = {}) {
+  const key = month || monthKey(new Date());
+  const filePath = join(telemetryDir(env), `${key}.jsonl`);
+  try {
+    return readFileSync(filePath, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}