trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/claude/state.d.ts

@@ -0,0 +1,85 @@
+import type { AgentHost } from '../telemetry/contract.js';
+export { LOCK_STALE_MS, acquireLock, acquireLockIn, releaseLockIn, cacheDir, emptyStats, patchStats, readStats, releaseLock, resolveContextDir, writeJsonAtomic, writeStats, } from '../util/state.js';
+export type { Stats } from '../util/state.js';
+export interface SessionState {
+    /** Prompts the prompt hook asked the graph about this session. A count:
+     * nothing the person typed is kept (spec section 6). Optional so files
+     * written before it still parse. */
+    promptAsks?: number;
+    /** The repo skills this session used, by name, to when it last went to the workspace as a run (skill-use.ts). */
+    skillsUsed?: Record<string, number>;
+    graftReads: number;
+    sourceReads: number;
+    /** Cumulative tokens saved this session via `ask --source` retrieval (est.). */
+    savedTokens: number;
+    /** Pointers the prompt hook already injected this session (novelty gate:
+     * a hit whose pointer was shown once is never re-injected). Optional so
+     * session files written before this field still parse. */
+    injectedPointers?: string[];
+    /** Notes already put in front of the agent this session by the per-prompt
+     * hook, by path, so each is shown once (see `notesForPrompt`). */
+    injectedNotes?: string[];
+    /** `<branch> <function id>` pairs: a teammate's open branch on a function the agent edited, already put in front of it this session. */
+    injectedOverlaps?: string[];
+    /** Weak-match nudges spent this session, capped so the line stays signal.
+     * Optional for the same backwards-compatibility reason as above. */
+    nudges?: number;
+    /** Turns this session in which the agent used a graft retrieval tool — the
+     * denominator for "did it tell the user what that saved". Counted at Stop,
+     * and only for turns whose reply we could actually read (see claude/tally.ts). */
+    graftTurns?: number;
+    /** Of those turns, the ones whose reply carried a "graft saved ~N tokens"
+     * tally. `graftTurns - reportedTurns` is silent value: saved, never said. */
+    reportedTurns?: number;
+    /** Set by the tool-savings hook when the current turn touched graft, cleared
+     * at Stop once the turn has been counted. Transient, not a total. */
+    turnUsedGraft?: boolean;
+    /** `uuid` of the last assistant reply already examined, so a Stop that fires
+     * without new prose (or fires twice) can't count one reply as two turns. */
+    lastTallyUuid?: string;
+    /** Running micro-dollar cost of the input tokens this session has been billed
+     * for, and the tokens that bought. Their ratio is the blended price of one
+     * input token here — model and cache-hit ratio already folded in — which is
+     * what turns `savedTokens` into a dollar figure. Stored as the pair rather
+     * than the ratio so the rate re-blends as the session's cache warms rather
+     * than freezing at whatever turn one happened to pay. Optional: absent on a
+     * host that exposes no transcript, and on turn one of every session. */
+    inputCostMicros?: number;
+    inputTokensBilled?: number;
+    /** `uuid` of the last assistant entry already billed. Each response is
+     * billed once, by the Stop read that first sees it (claude/tally.ts); a read
+     * that has to start over (no cursor, a lost one, a replaced transcript)
+     * bills nothing up to this entry again. */
+    lastBillingUuid?: string;
+    /** The signs the Stop hook has asked the agent to save a learning about
+     * this session (note-signals.ts keys), so each is asked about once and a
+     * session at most NOTE_ASKS_PER_SESSION times. */
+    noteAsks?: string[];
+    /** Set once this session has been rolled up into a `session_summary`
+     * telemetry event, so a resumed or long-lived session is counted once.
+     * A flag rather than deleting the file: the file still holds
+     * `injectedPointers`, which a resumed session needs. */
+    summarized?: boolean;
+    /** Which host recorded this session, stamped on the first tool use. Lets the
+     * `session_summary` be attributed correctly even when Claude Code's idle sweep
+     * is what finally flushes a Cursor session. Optional: files written before
+     * host-stamping (or an empty session never touched by a tool) fall back to the
+     * flushing host. */
+    host?: AgentHost;
+}
+/** The per-repo session directory holding one `<id>.json` per agent session. */
+export declare function sessionDir(d: string): string;
+/** Every session id with a file on disk, or `[]` when none exist (never throws).
+ *  Shared by the telemetry rollup and `graft stats` so they agree on the set. */
+export declare function listSessionIds(d: string): string[];
+export declare function readSession(d: string, id: string): SessionState;
+export declare function writeSession(d: string, id: string, s: SessionState): void;
+/**
+ * Take the prompt out of every session file an older version wrote here.
+ * Once per repo: the marker skips the read of every file on later session
+ * starts. Each file keeps its mtime, since the idle sweep that rolls sessions
+ * up into telemetry judges a session closed by it. Best-effort: a file that
+ * can't be read or written is tried again next time.
+ */
+export declare function dropStoredPrompts(d: string): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/claude/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/claude/state.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,aAAa,EACb,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B;;wCAEoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iHAAiH;IACjH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IACxC,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB;;8DAE0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;sEACkE;IAClE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,wIAAwI;IACxI,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;wEACoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;sFAEkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;iFAC6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;yEACqE;IACrE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;gFAC4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;4EAMwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;+CAG2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;sDAEkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;4DAGwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;wBAIoB;IACpB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAkBD,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAyC;AAItF;iFACiF;AACjF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAK/D;AACD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,YAAY,GAAG,IAAI,CAIzE;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAmBjD"}

package/dist/claude/state.js

@@ -0,0 +1,88 @@
+/**
+ * Claude Code session state. The shared `graft/.cache/` pieces (the statusline's
+ * `Stats` snapshot and the build lock) live in `../util/state.js` so the graph's
+ * pre-query auto-refresh can take the same lock; they are re-exported here so
+ * every existing import path keeps working.
+ */
+import { existsSync, readdirSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cacheDir, readJson, writeJsonAtomic } from '../util/state.js';
+export { LOCK_STALE_MS, acquireLock, acquireLockIn, releaseLockIn, cacheDir, emptyStats, patchStats, readStats, releaseLock, resolveContextDir, writeJsonAtomic, writeStats, } from '../util/state.js';
+function emptySession() {
+    return { graftReads: 0, sourceReads: 0, savedTokens: 0, injectedPointers: [], nudges: 0 };
+}
+/** Where versions before 0.23 kept the prompt itself (`lastQuery`, and `perAgentQuery` by agent name). */
+const PROMPT_KEYS = ['lastQuery', 'perAgentQuery'];
+/** `s` without the prompt an older version stored in it. True when there was one. */
+function withoutPrompts(s) {
+    let had = false;
+    for (const key of PROMPT_KEYS) {
+        if (key in s) {
+            delete s[key];
+            had = true;
+        }
+    }
+    return had;
+}
+/** The per-repo session directory holding one `<id>.json` per agent session. */
+export function sessionDir(d) { return join(cacheDir(d), 'session'); }
+function sessionPath(d, id) { return join(sessionDir(d), `${id}.json`); }
+/** Every session id with a file on disk, or `[]` when none exist (never throws).
+ *  Shared by the telemetry rollup and `graft stats` so they agree on the set. */
+export function listSessionIds(d) {
+    try {
+        return readdirSync(sessionDir(d)).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -'.json'.length));
+    }
+    catch {
+        return [];
+    }
+}
+export function readSession(d, id) {
+    const s = readJson(sessionPath(d, id));
+    if (!s || typeof s !== 'object')
+        return emptySession();
+    withoutPrompts(s);
+    return s;
+}
+export function writeSession(d, id, s) {
+    const out = { ...s };
+    withoutPrompts(out);
+    writeJsonAtomic(sessionPath(d, id), out);
+}
+/** Left in the session dir once every file there is free of prompts. Not `.json`, so never read as a session. */
+const PROMPTS_DROPPED = '.prompts-dropped';
+/**
+ * Take the prompt out of every session file an older version wrote here.
+ * Once per repo: the marker skips the read of every file on later session
+ * starts. Each file keeps its mtime, since the idle sweep that rolls sessions
+ * up into telemetry judges a session closed by it. Best-effort: a file that
+ * can't be read or written is tried again next time.
+ */
+export function dropStoredPrompts(d) {
+    const dir = sessionDir(d);
+    const marker = join(dir, PROMPTS_DROPPED);
+    if (existsSync(marker))
+        return;
+    let clean = true;
+    for (const id of listSessionIds(d)) {
+        const path = sessionPath(d, id);
+        try {
+            const s = readJson(path);
+            if (!s || typeof s !== 'object' || !withoutPrompts(s))
+                continue;
+            const { atime, mtime } = statSync(path);
+            writeJsonAtomic(path, s);
+            utimesSync(path, atime, mtime);
+        }
+        catch {
+            clean = false;
+        }
+    }
+    if (!clean || !existsSync(dir))
+        return;
+    try {
+        writeFileSync(marker, '');
+    }
+    catch { /* swept again next time */ }
+}
+//# sourceMappingURL=state.js.map

package/dist/claude/state.js.map

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

package/dist/claude/stats.d.ts

@@ -0,0 +1,5 @@
+import type { GraphV1 } from '../graph/types.js';
+import type { Stats } from './state.js';
+export declare function readWiring(projectDir: string): GraphV1 | null;
+export declare function computeStats(w: GraphV1): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/claude/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/claude/stats.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAI7D;AAED,wBAAgB,YAAY,CAC1B,CAAC,EAAE,OAAO,GACT,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC,CAWpF"}

package/dist/claude/stats.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveContextDir } from '../util/state.js';
+export function readWiring(projectDir) {
+    try {
+        return JSON.parse(readFileSync(join(resolveContextDir(projectDir), '.graph', 'wiring.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function computeStats(w) {
+    const nodes = w.nodes ?? [];
+    const edges = w.edges ?? [];
+    const readyCount = nodes.filter((n) => n.summary_state === 'ready').length;
+    return {
+        nodeCount: w.meta?.nodeCount ?? nodes.length,
+        edgeCount: w.meta?.edgeCount ?? edges.length,
+        languages: w.meta?.languages ?? [],
+        totalCount: nodes.length,
+        readyCount,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/claude/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/claude/stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAY,CAAC;IACnH,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,CAAU;IAEV,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO;QACL,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,IAAI,KAAK,CAAC,MAAM;QAC5C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,IAAI,KAAK,CAAC,MAAM;QAC5C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE;QAClC,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/cli-epilogue.d.ts

@@ -0,0 +1,12 @@
+export interface InitEpilogueOptions {
+    /** Whether a graft graph exists on disk (built by this run, or a prior one). */
+    graphBuilt: boolean;
+    /** Node count from the built graph — only meaningful when `graphBuilt`. */
+    nodes?: number;
+    /** Edge count from the built graph — only meaningful when `graphBuilt`. */
+    edges?: number;
+}
+/** Renders the `graft init` next-steps epilogue (no trailing newline — the
+ * caller's `console.error` adds the one trailing newline). */
+export declare function formatInitEpilogue(opts: InitEpilogueOptions): string;
+//# sourceMappingURL=cli-epilogue.d.ts.map

package/dist/cli-epilogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-epilogue.d.ts","sourceRoot":"","sources":["../src/cli-epilogue.ts"],"names":[],"mappings":"AA2CA,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;8DAC8D;AAC9D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAyCpE"}

package/dist/cli-epilogue.js

@@ -0,0 +1,72 @@
+/**
+ * `init`'s closing epilogue: the ASCII wordmark (trail's or graft's, by the name it ran as) + numbered next steps,
+ * printed to stderr after the per-file ✓/·/⚠ lines. Extracted out of cli.ts
+ * so the exact text — spacing is hand-aligned, not incidental — can be
+ * unit-tested without spawning the CLI.
+ */
+import { brand, cmd } from "./brand.js";
+// The live node/edge stats go on the wordmark's bottom line of letters (index
+// 4 in both), when a graph exists. graft's stays byte for byte: its output is
+// read by scripts.
+const WORDMARKS = {
+    trail: [
+        "  _             _ _",
+        " | |_ _ __ __ _(_) |",
+        " | __| '__/ _` | | |",
+        " | |_| | | (_| | | |",
+        "  \\__|_|  \\__,_|_|_|",
+    ],
+    graft: [
+        "                   __ _",
+        "   __ _ _ __ __ _ / _| |_",
+        "  / _` | '__/ _` | |_| __|",
+        " | (_| | | | (_| |  _| |_",
+        "  \\__, |_|  \\__,_|_|  \\__|",
+        "  |___/",
+    ],
+};
+const STATS_LINE_INDEX = 4;
+// Nanonets indigo, and a muted grey for the secondary stats suffix — only
+// applied when stderr is a real TTY (tests spawn/call this without one, so
+// existing plain-text assertions keep passing).
+const indigo = (s) => `\x1b[38;2;84;111;255m${s}\x1b[0m`;
+const muted = (s) => `\x1b[38;5;244m${s}\x1b[0m`;
+/** Renders the `graft init` next-steps epilogue (no trailing newline — the
+ * caller's `console.error` adds the one trailing newline). */
+export function formatInitEpilogue(opts) {
+    const { graphBuilt, nodes, edges } = opts;
+    const tty = Boolean(process.stderr.isTTY);
+    const wordmark = WORDMARKS[brand()].map((l) => (tty ? indigo(l) : l));
+    if (graphBuilt && nodes !== undefined && edges !== undefined) {
+        const stats = `  ${nodes.toLocaleString("en-US")} nodes · ${edges.toLocaleString("en-US")} edges`;
+        wordmark[STATS_LINE_INDEX] += tty ? muted(stats) : stats;
+    }
+    const steps = [
+        ...(graphBuilt ? [] : [{ label: "build the graph", command: cmd("graft build") }]),
+        { label: "restart your agent", command: `a new session picks up ${brand()} automatically` },
+        {
+            label: "code as usual",
+            command: "ask your agent to fix a bug or explain a flow:",
+            extra: ["it now answers from the graph"],
+        },
+        {
+            label: "explore by hand",
+            command: `${cmd("graft ask")} "where is auth handled?" · ${cmd("graft callers")} <fn> · ${cmd("graft viz")}`,
+        },
+    ];
+    const indent = "  ";
+    const gap = "  ";
+    const labelWidth = Math.max(...steps.map((s, i) => `${i + 1}. ${s.label}`.length));
+    const columnWidth = indent.length + labelWidth + gap.length;
+    const stepLines = [];
+    steps.forEach((s, i) => {
+        const prefix = `${indent}${i + 1}. ${s.label}`;
+        stepLines.push(prefix.padEnd(columnWidth) + s.command);
+        for (const extra of s.extra ?? []) {
+            stepLines.push(" ".repeat(columnWidth) + extra);
+        }
+    });
+    const closing = `${indent}share it: git add AGENTS.md .trail && git commit; teammates run \`${cmd("graft build")}\` for their own local graph`;
+    return [...wordmark, "", ...stepLines, "", closing].join("\n");
+}
+//# sourceMappingURL=cli-epilogue.js.map

package/dist/cli-epilogue.js.map

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

package/dist/cli-meta.d.ts

@@ -0,0 +1,82 @@
+/** Locates package.json relative to a module URL (works for both `dist/cli.js`
+ * running one level under the published package root, and `src/cli.ts` running
+ * one level under the repo root via tsx). */
+export declare function resolvePackageJsonPath(moduleUrl: string): string;
+/**
+ * The npm package this code was installed as: `@trailhq/trail-code`, or
+ * `@nanonets/graft` (the same code under its old name). Upgrades and update
+ * checks go to the package actually installed, not to the name typed.
+ */
+export declare function readPackageName(moduleUrl: string): string;
+/** Reads the version of the graft package this module was loaded from. */
+export declare function readCurrentVersion(moduleUrl: string): string;
+/** True when the running module lives under an npx cache dir (e.g.
+ * `~/.npm/_npx/<hash>/node_modules/...`) rather than a regular global install.
+ *
+ * Normalized first: `fileURLToPath` returns the *platform* separator, so on
+ * Windows the cache path is `…\_npx\…` and a bare `includes("/_npx/")` is always
+ * false — `graft upgrade` would then run `npm install -g` on top of an npx run.
+ * Same hardcoded-`/` mistake as #33; `src/util/paths.ts` exists for exactly this. */
+export declare function isRunningViaNpx(moduleUrl: string): boolean;
+export interface NpmViewResult {
+    ok: boolean;
+    version?: string;
+}
+/** `npm view <pkg> version`, offline-safe: any failure (no npm, no network,
+ * timeout) resolves to `{ ok: false }` rather than throwing. */
+export declare function getNpmViewVersion(pkgName?: string, timeoutMs?: number): NpmViewResult;
+/** Pure formatter for `graft version` — no I/O, easy to unit-test. */
+export declare function formatVersionReport(current: string, latest: NpmViewResult): string;
+/** Reads the version actually sitting in the global install, straight from
+ * disk — more reliable right after `npm install -g` than re-querying the
+ * registry (which just tells you what "latest" is, not what landed locally). */
+export declare function readGlobalInstalledVersion(pkgName?: string): string | null;
+export interface UpgradeResult {
+    /** True when `npm install -g` actually ran (false for the npx no-op path). */
+    ran: boolean;
+    ok: boolean;
+    /** Present when ran=true and the install failed. */
+    errorMessage?: string;
+    oldVersion?: string;
+    newVersion?: string;
+    /** The `trail` package's version, when `graft upgrade` installed it alongside. */
+    trailVersion?: string;
+    /** A plain fix for a failure we recognise, shown instead of npm's error block. */
+    fix?: string;
+    /** npm's own error output, for a failure we don't recognise. */
+    npmError?: string;
+}
+/** Pure formatter for a finished upgrade — no I/O, easy to unit-test. */
+export declare function formatUpgradeReport(result: UpgradeResult): string;
+/** What npm's error block names: its code, and the path (and rename dest) it failed on. */
+export interface NpmProblem {
+    code: string;
+    path?: string;
+    dest?: string;
+}
+/** Reads npm's `npm error code …` and `npm error path …` lines (`npm ERR!` before npm 10). */
+export declare function parseNpmError(stderr: string): NpmProblem | null;
+/**
+ * Removes what an earlier npm run left behind that makes every later `npm i -g`
+ * fail, and says what it removed; null when it's nothing trail should touch.
+ *
+ *  - ENOTEMPTY: npm moves the old package aside to `.<name>-<hash of its path>`
+ *    before writing the new one. An install stopped midway leaves that folder,
+ *    and as the name comes from the path, every later install collides with it.
+ *  - EEXIST: a `trail` or `graft` link in npm's bin folder from another copy of
+ *    trail (a local build installed from a folder, say), which npm won't replace.
+ *    Only a link into a trail or graft install, or to nothing, is removed.
+ */
+export declare function clearNpmLeftover(problem: NpmProblem | null): string | null;
+/**
+ * The fix for a global folder only root can write to (Node from nodejs.org or a
+ * system package): an npm prefix in the home folder, set once. Not sudo: a sudo
+ * install works once, then every upgrade needs it too.
+ */
+export declare function noSudoFix(path: string, pkgs: string[], shell?: string, platform?: string): string;
+/** Runs `npm install -g @nanonets/graft@latest`, clearing npm leftovers that
+ * block it (`clearNpmLeftover`) and turning EACCES into the no-sudo fix, then
+ * re-reads the freshly installed version. No-ops with guidance when running
+ * via npx. */
+export declare function runUpgrade(moduleUrl: string): UpgradeResult;
+//# sourceMappingURL=cli-meta.d.ts.map

package/dist/cli-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-meta.d.ts","sourceRoot":"","sources":["../src/cli-meta.ts"],"names":[],"mappings":"AAcA;;6CAE6C;AAC7C,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOzD;AAID,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;;;qFAMqF;AACrF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;gEACgE;AAChE,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAiB,EAAE,SAAS,SAAO,GAAG,aAAa,CAc7F;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAUlF;AAeD;;gFAEgF;AAChF,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,MAAiB,GAAG,MAAM,GAAG,IAAI,CAWpF;AAED,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAcjE;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAI/D;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAW1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,GAAE,MAAgC,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAc5I;AAQD;;;cAGc;AACd,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CA6B3D"}

package/dist/cli-meta.js

@@ -0,0 +1,238 @@
+/**
+ * `graft version` / `graft --version` / `graft upgrade` support.
+ *
+ * Split out of cli.ts so the formatting helpers can be unit-tested with
+ * injected results instead of hitting the network from tests.
+ */
+import { WINHIDE } from "./util/child-process.js";
+import { existsSync, readFileSync, readlinkSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toPosixPath } from "./util/paths.js";
+import { brand, PACKAGE_FOR } from "./brand.js";
+/** Locates package.json relative to a module URL (works for both `dist/cli.js`
+ * running one level under the published package root, and `src/cli.ts` running
+ * one level under the repo root via tsx). */
+export function resolvePackageJsonPath(moduleUrl) {
+    const moduleDir = dirname(fileURLToPath(moduleUrl));
+    const candidates = [resolve(moduleDir, "..", "package.json"), resolve(moduleDir, "package.json")];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return candidates[0];
+}
+/**
+ * The npm package this code was installed as: `@trailhq/trail-code`, or
+ * `@nanonets/graft` (the same code under its old name). Upgrades and update
+ * checks go to the package actually installed, not to the name typed.
+ */
+export function readPackageName(moduleUrl) {
+    try {
+        const pkg = JSON.parse(readFileSync(resolvePackageJsonPath(moduleUrl), "utf8"));
+        return pkg.name ?? PACKAGE_FOR.graft;
+    }
+    catch {
+        return PACKAGE_FOR.graft;
+    }
+}
+const PKG_NAME = readPackageName(import.meta.url);
+/** Reads the version of the graft package this module was loaded from. */
+export function readCurrentVersion(moduleUrl) {
+    const raw = readFileSync(resolvePackageJsonPath(moduleUrl), "utf8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? "0.0.0";
+}
+/** True when the running module lives under an npx cache dir (e.g.
+ * `~/.npm/_npx/<hash>/node_modules/...`) rather than a regular global install.
+ *
+ * Normalized first: `fileURLToPath` returns the *platform* separator, so on
+ * Windows the cache path is `…\_npx\…` and a bare `includes("/_npx/")` is always
+ * false — `graft upgrade` would then run `npm install -g` on top of an npx run.
+ * Same hardcoded-`/` mistake as #33; `src/util/paths.ts` exists for exactly this. */
+export function isRunningViaNpx(moduleUrl) {
+    return toPosixPath(fileURLToPath(moduleUrl)).includes("/_npx/");
+}
+/** `npm view <pkg> version`, offline-safe: any failure (no npm, no network,
+ * timeout) resolves to `{ ok: false }` rather than throwing. */
+export function getNpmViewVersion(pkgName = PKG_NAME, timeoutMs = 2000) {
+    try {
+        const res = spawnSync("npm", ["view", pkgName, "version"], {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            windowsHide: true,
+        });
+        if (res.error || res.signal || res.status !== 0)
+            return { ok: false };
+        const version = res.stdout?.trim();
+        if (!version)
+            return { ok: false };
+        return { ok: true, version };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Pure formatter for `graft version` — no I/O, easy to unit-test. */
+export function formatVersionReport(current, latest) {
+    const lines = [`${brand()} ${current}`];
+    if (!latest.ok || !latest.version) {
+        lines.push("latest: unreachable (offline?)");
+    }
+    else if (latest.version === current) {
+        lines.push(`latest on npm: ${current} ✓ up to date`);
+    }
+    else {
+        lines.push(`latest on npm: ${latest.version}, run ${brand()} upgrade`);
+    }
+    return lines.join("\n");
+}
+/** The global npm node_modules dir (handles Homebrew/Windows/volta layouts). */
+function globalRoot() {
+    try {
+        const root = execFileSync("npm", ["root", "-g"], { ...WINHIDE, encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            shell: process.platform === "win32",
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads the version actually sitting in the global install, straight from
+ * disk — more reliable right after `npm install -g` than re-querying the
+ * registry (which just tells you what "latest" is, not what landed locally). */
+export function readGlobalInstalledVersion(pkgName = PKG_NAME) {
+    const root = globalRoot();
+    if (!root)
+        return null;
+    const pkgJson = join(root, ...pkgName.split("/"), "package.json");
+    if (!existsSync(pkgJson))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgJson, "utf8"));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pure formatter for a finished upgrade — no I/O, easy to unit-test. */
+export function formatUpgradeReport(result) {
+    if (!result.ran) {
+        return (`running via npx: npx already fetches the latest ${brand()} on every run.\n` +
+            `For a permanent install: npm install -g ${PKG_NAME}`);
+    }
+    if (!result.ok) {
+        if (result.fix)
+            return `✗ ${brand()} wasn't upgraded: ${result.fix}`;
+        const failed = `✗ npm install -g ${PKG_NAME}@latest failed${result.errorMessage ? `: ${result.errorMessage}` : ""}`;
+        return `${result.npmError?.trim() ? `${result.npmError.trim()}\n` : ""}${failed}`;
+    }
+    const line = `${brand()} ${result.oldVersion ?? "?"} → ${result.newVersion ?? result.oldVersion ?? "?"}`;
+    return result.trailVersion ? `${line}\n✓ trail ${result.trailVersion} installed too: graft keeps working, and trail is its new name` : line;
+}
+/** Reads npm's `npm error code …` and `npm error path …` lines (`npm ERR!` before npm 10). */
+export function parseNpmError(stderr) {
+    const field = (name) => stderr.match(new RegExp(`^npm (?:error|ERR!) ${name} (.+)$`, "m"))?.[1].trim();
+    const code = field("code");
+    return code ? { code, path: field("path"), dest: field("dest") } : null;
+}
+/** A link in npm's bin folder that points into a trail or graft install, or at nothing. */
+function isTrailLink(path) {
+    let target;
+    try {
+        target = resolve(dirname(path), readlinkSync(path));
+    }
+    catch {
+        return false; // not a link: someone else's file
+    }
+    return !existsSync(target) || /[\\/](@trailhq[\\/]trail-code|@nanonets[\\/]graft)[\\/]|[\\/]dist[\\/]bin[\\/](trail|graft)\.js$/.test(target);
+}
+/**
+ * Removes what an earlier npm run left behind that makes every later `npm i -g`
+ * fail, and says what it removed; null when it's nothing trail should touch.
+ *
+ *  - ENOTEMPTY: npm moves the old package aside to `.<name>-<hash of its path>`
+ *    before writing the new one. An install stopped midway leaves that folder,
+ *    and as the name comes from the path, every later install collides with it.
+ *  - EEXIST: a `trail` or `graft` link in npm's bin folder from another copy of
+ *    trail (a local build installed from a folder, say), which npm won't replace.
+ *    Only a link into a trail or graft install, or to nothing, is removed.
+ */
+export function clearNpmLeftover(problem) {
+    if (problem?.code === "ENOTEMPTY" && problem.path && problem.dest) {
+        if (dirname(problem.dest) !== dirname(problem.path) || !basename(problem.dest).startsWith("."))
+            return null;
+        rmSync(problem.dest, { recursive: true, force: true });
+        return `removed ${problem.dest}, left by an npm install that was stopped midway`;
+    }
+    if (problem?.code === "EEXIST" && problem.path && isTrailLink(problem.path)) {
+        rmSync(problem.path, { force: true });
+        return `removed ${problem.path}, a link to another copy of trail`;
+    }
+    return null;
+}
+/**
+ * The fix for a global folder only root can write to (Node from nodejs.org or a
+ * system package): an npm prefix in the home folder, set once. Not sudo: a sudo
+ * install works once, then every upgrade needs it too.
+ */
+export function noSudoFix(path, pkgs, shell = process.env.SHELL ?? "", platform = process.platform) {
+    const addToPath = shell.endsWith("fish")
+        ? "fish_add_path ~/.npm-global/bin"
+        : `echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ${shell.endsWith("zsh") ? "~/.zshrc" : platform === "darwin" ? "~/.bash_profile" : "~/.bashrc"}`;
+    return [
+        `npm needs sudo to write to ${path}.`,
+        "  Skip sudo: point npm at a folder in your home, once, and installs never need it again:",
+        "",
+        "    mkdir -p ~/.npm-global",
+        "    npm config set prefix ~/.npm-global",
+        `    ${addToPath}`,
+        "",
+        `  Then open a new terminal and run: npm i -g ${pkgs.join(" ")}`,
+    ].join("\n");
+}
+/** `npm <args>` with npm's stderr kept, to read its error code; stdout still shows. */
+function npmRun(args) {
+    const res = spawnSync("npm", args, { stdio: ["inherit", "inherit", "pipe"], encoding: "utf8" });
+    return { ok: !res.error && res.status === 0, stderr: res.stderr ?? "", error: res.error?.message };
+}
+/** Runs `npm install -g @nanonets/graft@latest`, clearing npm leftovers that
+ * block it (`clearNpmLeftover`) and turning EACCES into the no-sudo fix, then
+ * re-reads the freshly installed version. No-ops with guidance when running
+ * via npx. */
+export function runUpgrade(moduleUrl) {
+    const oldVersion = readCurrentVersion(moduleUrl);
+    if (isRunningViaNpx(moduleUrl)) {
+        return { ran: false, ok: true, oldVersion };
+    }
+    // `graft upgrade` is the handover: it also installs the `trail` command, once
+    // that package is published. One npm call, so the two land at one version.
+    const alongside = PKG_NAME === PACKAGE_FOR.graft && getNpmViewVersion(PACKAGE_FOR.trail).ok ? [PACKAGE_FOR.trail] : [];
+    const pkgs = [PKG_NAME, ...alongside];
+    const args = ["install", "-g", ...pkgs.map((p) => `${p}@latest`)];
+    console.error(`· npm ${args.join(" ")}`);
+    let res = npmRun(args);
+    // Two leftovers at most (graft upgrade installs two packages), then npm's own error stands.
+    for (let retries = 0; !res.ok && retries < 2; retries++) {
+        const cleared = clearNpmLeftover(parseNpmError(res.stderr));
+        if (!cleared)
+            break;
+        console.error(`· ${cleared}; trying again`);
+        res = npmRun(args);
+    }
+    if (!res.ok) {
+        const problem = parseNpmError(res.stderr);
+        if (problem?.code === "EACCES" && process.platform !== "win32") {
+            return { ran: true, ok: false, oldVersion, fix: noSudoFix(problem.path ?? "npm's global folder", pkgs) };
+        }
+        return { ran: true, ok: false, oldVersion, npmError: res.stderr, errorMessage: res.error };
+    }
+    const newVersion = readGlobalInstalledVersion(PKG_NAME) ?? getNpmViewVersion(PKG_NAME).version ?? oldVersion;
+    const trailVersion = alongside.length ? (readGlobalInstalledVersion(PACKAGE_FOR.trail) ?? undefined) : undefined;
+    return { ran: true, ok: true, oldVersion, newVersion, trailVersion };
+}
+//# sourceMappingURL=cli-meta.js.map