@trazum/cli 1.8.0

package/dist/suggest-cache.js

@@ -0,0 +1,225 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Not asking the model the same question twice.
+ *
+ * The roadmap item this answers was "prompt caching for `--suggest`", meaning
+ * the API feature: mark a stable prefix with `cache_control` and pay a tenth of
+ * the price for it on every later call. **That cannot work here, and the reason
+ * is a number rather than an opinion.**
+ *
+ * Prompt caching has a minimum cacheable prefix — 512 tokens on the newest
+ * models, 1,024 on most, 4,096 on some — and a prefix shorter than the minimum
+ * is *silently* not cached: no error, no warning, `cache_creation_input_tokens`
+ * comes back zero. Trazum's suggest prompt is **291 tokens**. Marking it would
+ * have looked like an optimisation, cost a line of code, changed nothing, and
+ * been impossible to notice. `suggest-cache.test.js` measures it against the
+ * published minima so that stays true, or stops being true loudly.
+ *
+ * The stable prefix is also the only thing that *could* be cached: the rest of
+ * the request is the author's prompt, which is different every time. So there
+ * is no arrangement of `cache_control` that helps.
+ *
+ * What does help is the observation behind the request — running `--suggest`
+ * over a directory asks the same questions again on every run, and most of the
+ * prompts have not changed since the last one. Answering those from disk is not
+ * a 90% saving on the call, it is the whole call. On a re-run after editing two
+ * files out of forty, thirty-eight requests do not happen.
+ *
+ * Three decisions worth arguing with:
+ *
+ * **The raw response is cached, not the parsed suggestions.** Everything
+ * `suggestRewrites` does after the model answers — checking each `before`
+ * appears byte for byte, refusing anything that touches protected content,
+ * dropping overlaps — is deterministic and lives in the core. Caching the text
+ * means a hit is re-validated by *today's* rules rather than replaying a
+ * verdict reached by an older version. Same reasoning as recomputing token
+ * counts on read instead of storing them.
+ *
+ * **It is opt-in.** A cache hit returns what the model said last time, and a
+ * model is not a pure function — silently answering from a week-old response
+ * would be a surprise, in a tool whose other model-touching features
+ * (`--suggest`, `--apply-suggestions`, `--reorder`) all require asking twice.
+ *
+ * **The files are 0600 in a 0700 directory.** The cache holds prompt text, and
+ * a prompt is the most sensitive thing this tool ever touches — it is somebody's
+ * unreleased product behaviour. A world-readable cache in a shared home
+ * directory would publish it to every account on the machine.
+ */
+/**
+ * Bumped when anything that shapes the answer changes and is not already in the
+ * key — the suggest system prompt, the response format, the checking rules.
+ * A stale entry answers a question that is no longer the one being asked.
+ *
+ * Exported so the test can derive a key independently rather than comparing
+ * `cacheKey` to itself.
+ */
+export const SCHEMA = 2;
+/** Seven days. Long enough for a working week, short enough that an alias that started pointing at a new model does not answer forever. */
+export const DEFAULT_TTL_DAYS = 7;
+/**
+ * Where the cache lives.
+ *
+ * `XDG_CACHE_HOME` first, because a user who set it meant it. Not the project
+ * directory: two checkouts of the same repository ask the same questions, and a
+ * per-checkout cache answers neither of them from the other.
+ */
+export function cacheDir(env = process.env) {
+    const base = env.XDG_CACHE_HOME?.trim() || join(homedir(), '.cache');
+    return join(base, 'trazum', 'suggestions');
+}
+/**
+ * The key: everything that changes the answer, and nothing that does not.
+ *
+ * `provider` and `model` are in here rather than only in the entry because two
+ * models answer differently — a hit from the wrong one is not a hit. The system
+ * prompt is in here rather than relying on `SCHEMA` alone, so a caller passing
+ * their own system prompt gets their own entries without anybody remembering to
+ * bump a constant.
+ */
+export function cacheKey(input) {
+    // Length-prefixed rather than delimiter-joined: a delimiter that can occur
+    // inside a prompt lets two different inputs produce one key.
+    const parts = [String(SCHEMA), input.provider, input.model, input.system, input.user];
+    const canonical = parts.map((part) => `${part.length}:${part}`).join('');
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function entryPath(dir, key) {
+    return join(dir, `${key}.json`);
+}
+export function readEntry(dir, key, now, ttlDays) {
+    let raw;
+    try {
+        raw = readFileSync(entryPath(dir, key), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let entry;
+    try {
+        entry = JSON.parse(raw);
+    }
+    catch {
+        // A truncated write from an interrupted run. Treated as a miss rather than
+        // an error: the answer is one API call away, and refusing to run because a
+        // cache file is corrupt would be worse than the problem.
+        return null;
+    }
+    if (entry.schema !== SCHEMA)
+        return null;
+    if (typeof entry.response !== 'string')
+        return null;
+    if (typeof entry.at !== 'number')
+        return null;
+    if (now - entry.at > ttlDays * 86_400_000)
+        return null;
+    return entry;
+}
+export function writeEntry(dir, key, entry) {
+    try {
+        // 0700: the cache holds prompt text. A default-permission directory in a
+        // shared home publishes it to every other account on the machine.
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(entryPath(dir, key), `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // A cache that cannot be written is a cache that is not used. Read-only
+        // home directory, full disk, hostile umask — none of them are reasons to
+        // fail a command that was going to work.
+    }
+}
+/** Delete every entry. Returns how many went. */
+export function clearCache(dir) {
+    let removed = 0;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    for (const name of names) {
+        // Only files this module wrote. A cache directory that deletes whatever it
+        // finds is a cache directory somebody eventually points at their home.
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
+            continue;
+        try {
+            unlinkSync(join(dir, name));
+            removed += 1;
+        }
+        catch {
+            // Already gone, or not ours to delete.
+        }
+    }
+    return removed;
+}
+/** Entry count and total bytes, so `--clear-suggestion-cache` can say what it emptied. */
+export function cacheStats(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return { entries: 0, bytes: 0 };
+    }
+    let entries = 0;
+    let bytes = 0;
+    for (const name of names) {
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
+            continue;
+        try {
+            bytes += statSync(join(dir, name)).size;
+            entries += 1;
+        }
+        catch {
+            // Raced with a clear. Not counted.
+        }
+    }
+    return { entries, bytes };
+}
+/**
+ * Wraps a provider so identical questions are asked once.
+ *
+ * A wrapper rather than a change inside `suggestRewrites`, for two reasons: the
+ * core stays free of `node:fs` (it is browser-safe, and a test asserts the
+ * import graph), and every command that reaches for an LLM gets the cache by
+ * passing through one function rather than by each remembering to.
+ */
+export function cachingProvider(inner, options) {
+    const { dir, ttlDays = DEFAULT_TTL_DAYS, now = Date.now } = options;
+    let hits = 0;
+    let misses = 0;
+    return {
+        name: inner.name,
+        model: inner.model,
+        get hits() {
+            return hits;
+        },
+        get misses() {
+            return misses;
+        },
+        async complete({ system, user }) {
+            const key = cacheKey({ provider: inner.name, model: inner.model, system, user });
+            const cached = readEntry(dir, key, now(), ttlDays);
+            if (cached) {
+                hits += 1;
+                return cached.response;
+            }
+            const response = await inner.complete({ system, user });
+            misses += 1;
+            // Written after the call succeeds, so a failed request is not remembered
+            // as an answer. A thrown error propagates untouched.
+            writeEntry(dir, key, {
+                schema: SCHEMA,
+                at: now(),
+                provider: inner.name,
+                model: inner.model,
+                response,
+            });
+            return response;
+        },
+    };
+}
+//# sourceMappingURL=suggest-cache.js.map

package/dist/suggest-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-cache.js","sourceRoot":"","sources":["../src/suggest-cache.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@trazum/cli",
+  "version": "1.8.0",
+  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
+  "license": "MIT",
+  "author": "David Mu\u00f1oz Rey",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davmunrey/Trazum.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "prompt",
+    "llm",
+    "tokens",
+    "cost",
+    "cli",
+    "ci"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "trazum": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@trazum/core": "1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/git.ts

@@ -0,0 +1,294 @@
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+/**
+ * The only place in this repository that runs another program.
+ *
+ * `trazum blame` needs a file's history, and the history lives in git. Nothing
+ * else here has ever shelled out, so this module is written as if it were the
+ * whole attack surface — because it is.
+ *
+ * The rules, and why each one is here rather than in a comment on the call site:
+ *
+ * - **No shell, ever.** `spawnSync` with an argv array and `shell: false`, which
+ *   is the default and is stated anyway. The moment a path reaches a shell
+ *   string, a file called `; rm -rf ~` is a command.
+ * - **Paths go after `--`.** Without it, a file named `--upload-pack=curl…` or
+ *   `--output=…` is read by git as an option, and git has options that run
+ *   programs. This is the specific reason `trazum blame -- <path>` is not
+ *   enough on its own: the separator has to be in *our* argv, not the user's.
+ * - **Object names are validated before they are used.** `git show <sha>:<path>`
+ *   glues two values into one argument, so the sha is checked against
+ *   `/^[0-9a-f]{40}$/` before it can contribute anything to it.
+ * - **Everything is bounded.** A timeout so a hung git does not wedge the CLI, a
+ *   `maxBuffer` so a large blob cannot exhaust memory, and a revision cap so
+ *   `blame` on a file with 40,000 commits terminates.
+ * - **The path must be inside the repository.** Reading history for
+ *   `../../elsewhere/secrets.txt` is not a thing this command exists to do.
+ *
+ * Failures are `null` or an empty array rather than exceptions with git's own
+ * wording. The caller turns them into a sentence in the reader's language.
+ */
+
+/** Ten seconds is a long time for `git log`; a hung one should not be forever. */
+const TIMEOUT_MS = 10_000;
+
+/** 32 MB. A prompt file this big is not a prompt file. */
+const MAX_BUFFER = 32 * 1024 * 1024;
+
+const SHA = /^[0-9a-f]{40}$/;
+
+export interface Revision {
+  sha: string;
+  shortSha: string;
+  author: string;
+  /** ISO 8601, author date. */
+  date: string;
+  subject: string;
+}
+
+/**
+ * Errors that mean *the process could not be started*, not that git said no.
+ *
+ * `EAGAIN` is the kernel refusing a fork because the process or thread limit is
+ * momentarily full; `ENOMEM` is the same story with memory. Both are properties
+ * of the machine at that instant and both are gone a moment later, which is
+ * exactly why they surface on a loaded CI runner and never on a laptop.
+ */
+const TRANSIENT = new Set(['EAGAIN', 'ENOMEM']);
+
+/**
+ * Why a git invocation produced nothing — which is not one question but two.
+ *
+ * `git log` exiting 0 with no output means *this file has no history*. Failing
+ * to spawn git at all means *we do not know what history this file has*. They
+ * had the same representation here — `null` — so `revisionsFor` returned `[]`
+ * for both and `blame` told the author "git has no commits touching p.txt",
+ * confidently, on the strength of never having asked.
+ *
+ * That is the shape of issue #58: zero rows, exit 0, only on CI, never
+ * reproducible. A fork that fails under load is invisible and looks like a fact
+ * about the repository.
+ */
+type GitOutcome =
+  | { ran: true; stdout: string }
+  | { ran: true; stdout: null }
+  | { ran: false; stdout: null; detail: string };
+
+/**
+ * The spawn, injectable — the same seam the LLM providers use for `fetch`.
+ *
+ * Exported because the retry below is otherwise untestable: provoking a real
+ * `EAGAIN` means exhausting the process table, which is not something a test
+ * suite should do to the machine running it. A retry nothing checks is a retry
+ * somebody deletes in a refactor, and mutation testing said exactly that.
+ *
+ * It widens nothing in practice: the CLI has no library entry, so this module
+ * is reachable only from inside this package and from its tests.
+ */
+export type SpawnLike = typeof spawnSync;
+
+function runGit(
+  args: readonly string[],
+  cwd: string,
+  spawn: SpawnLike = spawnSync,
+): GitOutcome {
+  /**
+   * Bounded by the loop, not by a condition inside it.
+   *
+   * Written as `for (;;)` with a `continue` guarded by `attempt === 0` first,
+   * which is one edit away from retrying for ever — and mutation testing does
+   * not report that as a surviving mutant, it reports it as the suite hanging
+   * until the runner is killed. In CI that is a job that burns its whole
+   * timeout instead of failing in a second.
+   *
+   * Two attempts, and only for a failure to *start* the process. A git that ran
+   * and exited non-zero is answering, and asking it twice would just re-run a
+   * command that already failed for a reason.
+   */
+  const ATTEMPTS = 2;
+  let last: GitOutcome = { ran: false, stdout: null, detail: 'not attempted' };
+
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const result = spawn('git', args, {
+      cwd,
+      // Stated rather than left to the default: this is the line that matters.
+      shell: false,
+      encoding: 'utf8',
+      timeout: TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      // No prompting for credentials, no pager waiting on a TTY that is not there.
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_PAGER: 'cat', PAGER: 'cat' },
+    });
+
+    if (result.error !== undefined) {
+      const code = (result.error as NodeJS.ErrnoException).code ?? '';
+      last = { ran: false, stdout: null, detail: code || result.error.message };
+      if (TRANSIENT.has(code)) continue;
+      return last;
+    }
+
+    if (result.status !== 0) return { ran: true, stdout: null };
+    return { ran: true, stdout: result.stdout };
+  }
+
+  // Every attempt was refused before git started. The machine is out of
+  // whatever it ran out of, and saying so beats a third try.
+  return last;
+}
+
+function git(args: readonly string[], cwd: string): string | null {
+  return runGit(args, cwd).stdout;
+}
+
+/**
+ * Thrown when git could not be run, as distinct from git having nothing to say.
+ *
+ * A distinct type rather than a message, so a caller cannot accidentally treat
+ * it as an empty result — which is the whole bug.
+ */
+export class GitUnavailableError extends Error {
+  constructor(detail: string) {
+    super(`could not run git (${detail})`);
+    this.name = 'GitUnavailableError';
+  }
+}
+
+/**
+ * Whether `git` can be run at all.
+ *
+ * Separate from `repositoryRoot` because the two failures need different
+ * advice: "install git" and "run this inside a repository" have nothing to do
+ * with each other, and a single "could not read history" would send half the
+ * readers looking in the wrong place.
+ */
+export function gitAvailable(cwd: string): boolean {
+  return git(['--version'], cwd) !== null;
+}
+
+/** The repository root containing `cwd`, or `null` if there is not one. */
+export function repositoryRoot(cwd: string): string | null {
+  const out = git(['rev-parse', '--show-toplevel'], cwd);
+  return out === null ? null : out.trim() || null;
+}
+
+/**
+ * The path as git knows it — relative to the repository root, forward slashes —
+ * or `null` when it falls outside the repository.
+ */
+export function pathInRepository(root: string, target: string): string | null {
+  const rel = relative(resolve(root), resolve(target));
+  // Empty means the target *is* the root, `..` at the front means it escaped,
+  // and an absolute result means the two are on different Windows drives. All
+  // three are "outside the repository".
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return null;
+  }
+  return rel.split(sep).join('/');
+}
+
+/**
+ * Commits that touched `repoPath`, newest first.
+ *
+ * `--follow` so a renamed prompt keeps its history: a file moved from
+ * `prompt.txt` to `prompts/support.txt` is the same prompt, and a cost history
+ * that restarts at the rename is telling you the growth began the day somebody
+ * tidied the directory.
+ */
+export function revisionsFor(
+  repoPath: string,
+  options: { cwd: string; max: number; spawn?: SpawnLike },
+): Revision[] {
+  // A unit separator between fields and a record separator between commits:
+  // both are characters git will not emit inside a name or a subject, unlike
+  // the tab and newline that a commit subject can absolutely contain.
+  // Written as escapes, not typed in. A raw control byte in a source file is
+  // how `scripts/measure-token-band.mjs` ended up with no reviewable diff for
+  // three commits, one of which was a security fix.
+  const FIELD = '\u001f';
+  const RECORD = '\u001e';
+  const format = ['%H', '%h', '%an', '%aI', '%s'].join(FIELD) + RECORD;
+
+  const outcome = runGit(
+    [
+      'log',
+      '--follow',
+      `--max-count=${Math.max(1, Math.floor(options.max))}`,
+      `--format=${format}`,
+      // Everything after this is a path, whatever it looks like.
+      '--',
+      repoPath,
+    ],
+    options.cwd,
+    options.spawn,
+  );
+
+  // The distinction this function used to lose. An empty list now means git
+  // looked and found nothing; being unable to look throws instead, so it can
+  // never be reported to somebody as a fact about their repository.
+  if (!outcome.ran) throw new GitUnavailableError(outcome.detail);
+  const out = outcome.stdout;
+  if (out === null) return [];
+
+  return out
+    .split(RECORD)
+    .map((record) => record.replace(/^\n/, ''))
+    .filter((record) => record.trim() !== '')
+    .map((record) => {
+      const [sha = '', shortSha = '', author = '', date = '', subject = ''] = record.split(FIELD);
+      return { sha, shortSha, author, date, subject };
+    })
+    .filter((revision) => SHA.test(revision.sha));
+}
+
+/**
+ * The file's content at a commit, or `null` if it did not exist there.
+ *
+ * `--follow` above means the path can differ from the one at that commit, so
+ * this asks git for the name it had rather than assuming today's.
+ */
+export function contentAt(sha: string, repoPath: string, cwd: string): string | null {
+  // The sha becomes part of a single `sha:path` argument, so it is checked
+  // before it can contribute anything to one.
+  if (!SHA.test(sha)) return null;
+  return git(['show', `${sha}:${repoPath}`], cwd);
+}
+
+/**
+ * The name the file had at each commit, keyed by sha.
+ *
+ * One `git log` rather than one per revision, and it replaces a version that
+ * asked per commit and got nothing back: `git log --follow --max-count=1 <sha>
+ * -- <today's name>` returns an empty list for every commit before a rename,
+ * because at those commits that name did not exist. The effect was that a
+ * renamed prompt showed "not present" for its entire history before the move —
+ * the data was there, under the old name, and the report said there was none.
+ *
+ * Asking once, without a starting commit, lets `--follow` do the mapping it
+ * exists for: the output pairs each sha with the path it touched.
+ */
+export function namesByRevision(repoPath: string, cwd: string, max: number): Map<string, string> {
+  const MARK = '\u001e';
+  const out = git(
+    [
+      'log',
+      '--follow',
+      '--name-only',
+      `--max-count=${Math.max(1, Math.floor(max))}`,
+      `--format=${MARK}%H`,
+      '--',
+      repoPath,
+    ],
+    cwd,
+  );
+
+  const names = new Map<string, string>();
+  if (out === null) return names;
+
+  for (const record of out.split(MARK)) {
+    const lines = record.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    const [sha, name] = lines;
+    if (sha !== undefined && name !== undefined && SHA.test(sha)) names.set(sha, name);
+  }
+  return names;
+}