candor-ts 0.5.0 → 0.5.1

package/AGENTS.md

@@ -9,6 +9,12 @@ chains by hand.
 > the *installed* version — always prefer that over a vendored or fetched copy, which can describe
 > a different candor-ts than the one you are running.
 
+> **Staying current is your job, not candor's.** candor never phones home — it audits and denies the
+> Net effect, so it will not reach the network to check itself. `candor-ts --version` prints the
+> installed build, the spec contract it speaks, and the upgrade line (`npm install -g
+> candor-ts@latest`) — fully offline. You have the network: read the installed version here, compare
+> it against npm, and upgrade if it is stale. Every command is offline.
+
 The language-agnostic consumption contract is
 [candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is
 the TypeScript-specific production + query surface.

package/README.md

@@ -20,6 +20,8 @@ node scan.mjs <project-dir>                 # tsconfig.json honored; tests exclu
                                             #   <dir>/.candor/report.json + .callgraph.json
 node scan.mjs . --policy .candor/policy     # the §6.2 gate: exit 1 on violation, 2 if unreadable
 
+node scan.mjs --version                     # installed build + spec contract (offline), + upgrade line
+
 node query.mjs show     .candor/report db.save 1   # a function's effects (match ladder)
 node query.mjs where    .candor/report Net 1       # direct sources vs inheritors
 node query.mjs callers  .candor/report db.save 1   # the blast radius (transitive callers)
@@ -28,6 +30,8 @@ node query.mjs whatif   .candor/report db.save Net policy  # pre-edit gate verdi
 node query.mjs diff     .candor/report baseline 1  # per-function effect delta (exit 1 on a gain)
 ```
 
+**Staying current:** check your installed version and upgrade — [candor/AGENTS.md §2a](https://github.com/tombaldwin/candor/blob/main/AGENTS.md#2a-staying-current--check-the-version-upgrade). `npx -y candor-ts --version` prints the build, the spec, and the upgrade one-liner (offline; candor never phones home).
+
 Function names are module-qualified with `.` segments (`src.db.save`), so policy scopes read
 naturally:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/scan.mjs

@@ -30,12 +30,29 @@ import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesI
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
+// The single version + spec sources, read once. PKG_VERSION is the bare semver from package.json
+// (e.g. "0.5.0"); ENGINE_VERSION (below) prefixes it for the report envelope's `version` field, and
+// `--version` prints the bare form. SPEC_VERSION is the spec contract this build speaks — the SAME
+// literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
+// Reused, never re-littered.
+const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
+const SPEC_VERSION = "0.5";
+
+// --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
+// Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
+// build + upgrade line here, then (the agent has the network) compare against npm and upgrade.
+if (process.argv.includes("--version")) {
+  console.log(`candor-ts ${PKG_VERSION} (spec ${SPEC_VERSION})`);
+  console.log("upgrade: npm install -g candor-ts@latest");
+  process.exit(0);
+}
+
 // ---- args ----------------------------------------------------------------------------------------
 // ONE pass: the first non-flag is the target; value-taking flags consume the next arg and FAIL on a
 // missing/flag-shaped value; an unknown flag fails; flags may precede the target. `--agents` is a
 // flag (a print-and-exit MODE) — it must NOT fire when it is the VALUE of --out/--policy, which the
 // value-consuming skip handles, nor produce a "lying unknown flag" error for a real flag given first.
-const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>] [--allow-js] [--agents]";
+const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>] [--allow-js] [--agents] [--version]";
 const argv = process.argv.slice(2);
 let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, allowJs = false, wantAgents = false;
 for (let i = 0; i < argv.length; i++) {
@@ -175,7 +192,7 @@ fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
 // ONE version source: package.json. A second hardcoded literal (the envelope's, the --agents
 // banner's) that drifted from this would make the engine distrust its OWN reports at the §2.1
 // staleness check (`d.candor?.version !== ENGINE_VERSION`), silently downgrading every chained dep.
-const ENGINE_VERSION = `candor-ts-${JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version}`;
+const ENGINE_VERSION = `candor-ts-${PKG_VERSION}`;
 const crossDeps = new Map(); // hash -> {inferred:Set, hosts:[], cmds:[], paths:[], tables:[]}
 // Packages a loaded sibling report COVERS — exempt from the κ ledger even when a call joins no
 // entry (reports omit pure functions: the silence is the purity claim, SPEC §2 rule 3 — the
@@ -822,7 +839,7 @@ for (const [name, rec] of fns) {
 }
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when
 // `functions` is empty (an all-pure package's report is its purity claim, SPEC §2 rule 3).
-const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: "0.5" },
+const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: SPEC_VERSION },
                    package: pkgName, functions };
 const cg = {};
 for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();