@catalyst-cloud/cli 0.9.5 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.13.0
+
+Catalyst's released pieces now share one version line, 0.13: `@catalyst-cloud/cli` and the deprecated `@catalyst-cloud/catalyst-skills` name, these skills, `@catalyst-cloud/sdk`, the installer, and the schema, replicate and read-model libraries. A CLI on 0.13.x belongs with a cloud whose tenant contract names `releaseLine` 0.13. The CLI moves from 0.9 straight to 0.13 and runs on `@catalyst-cloud/sdk` 0.13. The tenant contract keeps its own version, which tracks the document's shape.
+
+Ask your agent what a setting does and where it is set, and it names the screen, the route and the rule instead of guessing: connecting Linear, installing the GitHub App, registering a repository, the merge policy and its reviewers, secrets versus environment variables, and why routing has no write route yet all have a home in `how-catalyst-works`. `whats-happening` now maps every reason a ticket can be held to a next action and who takes it — the person with their own login, a tenant owner or admin in settings, an operator, or "no one acts" when it is genuinely just waiting — and three reasons that were missing from the stuck-state table (a live container holding a later phase, too many claims in an hour, and a repository at capacity) are documented for the first time. Connecting your own Linear account and being matched as a Linear identity are now explained as two different, sometimes disagreeing, facts, so "I connected Linear, why am I still not getting asks?" has a real answer. And the README says plainly what it still does not know: flow metrics — cycle time, throughput, how long a pull request has been open — are not computed yet, rather than counting something else and calling it that.
+
 ## 0.9.5
 
 The CLI calls itself `catalyst` everywhere: usage lines, every verb's `--help`, hints, remedies and errors. `catalyst-skills` still works as a deprecated alias. The npx form is `npx -p @catalyst-cloud/cli catalyst …`, because bare `npx @catalyst-cloud/cli` cannot pick a binary. A replica read on the `node:sqlite` fallback no longer prints a notice every time; `CATALYST_DEBUG=1` still shows it.
@@ -60,6 +66,22 @@ That one command is `catalyst-skills runtime install`. It downloads a pinned Nod
 
 ## 0.7.0
 
+`catalyst-skills env inventory [path]` scans a repository offline — no login, no network — and lists
+the environment variable NAMES it needs, never a value. Names are grouped build/test (needed to
+install, build and run the tests), deploy-only (a CI secret only a deploy job uses) and bindings (a
+Cloudflare or other platform binding, which is not an environment value). Each name shows where it
+was found (file:line), what uses it, and where a local value would come from — a `.env` file, your
+shell, a CI secret, or a Cloudflare binding. `--json` gives the same data in machine form. `env check
+<file>` validates a `catalyst.env.json` offline, against this bundle's own dated, cited copy of the
+cloud's validation rules (it does not compute the cloud's canonical hash — only a `valid` / `invalid`
+verdict and the refusal reasons). The new `what-this-repo-needs` skill explains why a cloud container
+needs these names before it scans, then asks you to review the list: keep, drop or move each one.
+
+Reading a GitHub Actions workflow now goes through a real YAML parser (`yaml`, now a runtime
+dependency of this package — it carries no transitive dependencies of its own) rather than a
+hand-written line scanner, so a workflow that declares its `env:` in flow style (`{ A: 1, B: 2 }`) is
+read correctly instead of silently missed.
+
 `explain` and `ready` now name a team that cannot start work even when the live read is not available. Your tenant's contract carries each team's dispatch gate, and this machine already keeps a copy of that contract on disk; until now only the live eligibility read could name the gate, so a network hiccup, or a cloud older than that read, left `explain` printing nothing at all. `explain` now leads with the gate and the fix from the cached contract when the live read is unavailable or sends no gate, and says which of the two it read; when both answer and disagree, the live read wins and the paragraph says the cached one disagreed. A refusal from the cloud — a credential that is not accepted, for instance — is still a refusal, never quietly replaced by a cached answer. `ready` now prints one dispatch-gate line per team: open teams read `ok`, and a team whose stages are not saved reads `FAIL` with the remedy your tenant sent and turns the verdict to NOT READY, because nothing in that team can start. A cloud that does not send the gate changes nothing.
 
 `catalyst-skills ready` now tells you when the skills on this machine, or the CLI itself, are behind the newest published release — it names the version you have, the version that is out, and the one command that updates each, as a note that never changes the verdict. Every skill file now records the bundle version it was vendored at, so a copy installed months ago is visible as such instead of only by diffing files. The check reads the npm registry's `dist-tags.latest`, capped at 1500ms and cached for six hours, and never blocks: an unreachable registry is one note that says so, and `--offline` (or `CATALYST_SKILLS_OFFLINE=1`) skips the lookup entirely.

package/README.md

@@ -162,14 +162,16 @@ The replica is a Node process, not a service: the supported path is the plain co
 | `how-catalyst-works` | "How does this work? Why did it do that? How does it prioritise?" | The execution model as references loaded on demand: the eight-phase ladder, the eleven board slots and this team's live stage map, what happens when a phase fails, how the queue is ordered and routed, every exclusion reason, and the coding-account model. Scripts explain one ticket's eligibility in plain English. | [`SKILL.md`](skills/how-catalyst-works/SKILL.md) |
 | `unstick` | "Why is this parked? Unpark it. Get things flowing again." | Reads why a ticket is not running and every park or hold on it, decides whether the recorded cause is fixed, previews the release and releases it the right way from your own login — or one failure class across a team — and raises an ask only for what a person has to do. | [`SKILL.md`](skills/unstick/SKILL.md) |
 | `connect-me` | "Connect this machine to my tenant." | Connects the machine to the tenant with your own personal key, caches the tenant contract, verifies, and offers to start the replica. | [`SKILL.md`](skills/connect-me/SKILL.md) |
+| `what-this-repo-needs` | "What env vars does this repo need? What does catalyst.env.json mean?" | Scans a repository offline — no login, no network — and lists the environment variable names it needs, grouped build/test, deploy-only and bindings, each with where it was found, what uses it, and where a local value would come from. Never reads or prints a value. Also validates a `catalyst.env.json` file with the same rules the cloud applies. | [`SKILL.md`](skills/what-this-repo-needs/SKILL.md) |
 
 Some of these only read; the ones that write anything — or that drive you through writes, as `catalyst-onboard` does — are marked so an agent cannot invoke them on its own, and you ask for them by name. Each skill's own `SKILL.md` says which it is, in its frontmatter; no count lives in this sentence, because a count in a sentence goes wrong the first time the table above gains a row. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
 
 ## What a key cannot see yet
 
-Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the tenant-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-setup` already reports on, is a separate thing. One thing it cannot do, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the tenant-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-setup` already reports on, is a separate thing. `catalyst env inventory` lists the environment variable names a repository needs — never a value — and `env check` validates a `catalyst.env.json` file offline; neither needs a login (the `what-this-repo-needs` skill walks through both). Two things it cannot do, and the skills say so by name rather than guess:
 
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
+- Compute a flow number — cycle time, throughput, or how long pull requests have been open. Nothing serves those yet, so say they are not computed rather than counting something else and calling it that.
 
 ## Versions and origins
 
@@ -198,7 +200,7 @@ A `customer.json` written by an older bundle is still read unchanged; it gains t
 
 ## Uninstalling
 
-Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the skill directories (`catalyst-github`, `catalyst-linear`, `catalyst-onboard`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `unstick`, `what-needs-me`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
+Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the skill directories (`catalyst-github`, `catalyst-linear`, `catalyst-onboard`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `unstick`, `what-needs-me`, `what-this-repo-needs`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
 
 ```sh
 catalyst replica stop

package/dist/args.js

@@ -111,6 +111,7 @@ export const FLAG_TABLES = {
         offline: { value: false, help: "skip the published-release check (no network)" },
     },
     accounts: {},
+    env: {},
     team: {
         all: { value: false, help: "check every team, one request at a time" },
         stage: { value: true, repeat: true, help: "map a role to a live Linear state name (role=StateName)" },
@@ -169,7 +170,8 @@ export const VERB_USAGE = {
     accounts: "accounts [--json]",
     mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",
     team: "team <list|check <KEY>|check --all|map <KEY> [--stage role=StateName]... [--yes --plan-hash H]|adopt <KEY> [--undo] [--yes --plan-hash H]|migrate <KEY> [--choice sourceId=destinationId]... [--retire] [--yes --plan-hash H]|checklist <KEY>> [--json]",
-    environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]",
+    env: "env <inventory [path] | check <file>> [--json]   (THIS repository, offline — no login, no network)",
+    environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]   (your ACCOUNT's declaration; needs login)",
     secret: "secret set <NAME> --repo <owner/name> [--command '<cmd>'] [--json]   (value from --command, stdin, or a hidden prompt) | secret import <file> --repo <owner/name> [--rotate NAME]... [--json]",
     identity: "identity linear <status|options|set> [<linearUserId>] [--json]",
     capabilities: "capabilities [--json]",

package/dist/cli.js

@@ -23,6 +23,7 @@ import { cmdAsk } from "./ask.js";
 import { cmdMcp } from "./mcp.js";
 import { cmdRelease } from "./release.js";
 import { cmdEnvironment } from "./environment.js";
+import { cmdEnv } from "./env.js";
 import { cmdSecret } from "./secret.js";
 import { cmdTeam } from "./team.js";
 import { cmdCapabilities } from "./capabilities.js";
@@ -39,6 +40,7 @@ export const CUSTOMER_SKILLS = [
     "run-this-project",
     "unstick",
     "what-needs-me",
+    "what-this-repo-needs",
     "whats-happening",
 ];
 /** `login` is the verb; `join` is the 0.1 name, kept as a deprecated alias for one minor version. */
@@ -67,7 +69,8 @@ export function usageText() {
         "  catalyst write <comment|state|label|create|reaction|attachment|session> ...",
         "  catalyst ask <raise|accept|list> ...",
         "  catalyst release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
-        "  catalyst environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve",
+        "  catalyst environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve   (your account; needs login)",
+        "  catalyst env <inventory [path] | check <file>>   (this repository, offline — no login, no network)",
         "  catalyst secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name>",
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",
         "  catalyst capabilities [--json]   (what this CLI can do, the role each verb needs, and whether this cloud serves it)",
@@ -245,6 +248,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdRelease(args, ctx);
             case "environment":
                 return await cmdEnvironment(args, ctx, deps.environment ?? {});
+            case "env":
+                return await cmdEnv(args, ctx, deps.env ?? {});
             case "secret":
                 return await cmdSecret(args, ctx, deps.secret ?? {});
             case "team":
@@ -278,7 +283,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         throw err;
     }
 }
-const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret", "environment", "connections", "identity", "mcp", "team", "capabilities"].map((v) => [v, true]));
+const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret", "env", "environment", "connections", "identity", "mcp", "team", "capabilities"].map((v) => [v, true]));
 async function cmdLogin(args, ctx, deps) {
     const manifest = readManifest();
     const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();

package/dist/env/declaration-rules.js

@@ -0,0 +1,163 @@
+// declaration-rules.ts — a vendored, dated copy of catalyst-cloud's rules for a repo-scope
+// `catalyst.env.json`, applied by `validateRepoEnvironmentDeclaration`
+// (packages/environment/src/contract.ts:416-493 on catalyst-cloud `main`; the ticket cites line 488,
+// which falls inside that range). That file lives in the PRIVATE `coalesce-labs/catalyst-cloud`
+// monorepo — no sibling checkout, no npm publication (its one customer, `apps/cli`, is itself
+// "private": true) and no network reachability from this session. Everything below is vendored
+// secondhand from two independent, dated thoughts-pool research passes (2026-09-10 and 2026-09-17)
+// that agreed with each other, following the same idiom this repository's own
+// `test/skills-content.test.ts` already uses to vendor catalyst-cloud's `READINESS_CHECK_IDS` (see
+// that file's `TEAM_CHECK_IDS` and its provenance comment): dated, cited, paired with a test, never
+// hand-copied and trusted on its own.
+//
+// What a parity test built against THIS copy can, and cannot, catch: it can catch this copy DRIFTING
+// FROM ITSELF — a rule dropped, loosened or tightened by a future edit here. It CANNOT notice a new
+// rule landing upstream, because nothing in this repository imports the real function — there is no
+// publish channel for it. The one fixture pinned by a real, run command transcript rather than by
+// prose (`valid-empty-provenance.json`, in `test/fixtures/env-declaration/`) is the strongest anchor
+// this vendored copy has; the rest are pinned by the two agreeing research passes.
+const MAX_ENV_REFS = 128;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// ⛔ A PREFIX ONLY COUNTS AT A TOKEN BOUNDARY (validate attempt 29, CR-6). These were matched with
+// `text.includes(p)`, and "sk-" is a SUBSTRING of "task-", "risk-" and "disk-" — so a declaration
+// whose setup step was `["npm","run","task-build"]` was refused as containing secret material. Every
+// prefix here is identifier-shaped, so a match is real only at the start of the text or after a
+// character that cannot be part of a token; PEM armour, which is not identifier-shaped and carries
+// its own unmistakable delimiter, keeps a plain substring match of its own.
+// `gho_`, `sk_live_` and `AIza` are in the 2026-09-10 pass's list of upstream's prefixes
+// (thoughts: repos/catalyst/shared/research/2026-09-10-CTC-2020-laptop-environment-inventory.md:65),
+// and `ghs_` is pinned as an upstream entry by the 2026-09-27 CTC-3378 plan v2 (:238). Validate
+// attempt 31 found the first three missing here (and noted `ghs_`), so `env check` said `valid`
+// where upstream's validator refuses.
+// That upstream list ends "and others": this copy still cannot claim to hold every entry.
+const KNOWN_SECRET_PREFIXES = ["ghp_", "gho_", "ghs_", "github_pat_", "sk-", "sk_live_", "AKIA", "AIza", "xoxb-", "xoxp-"];
+const PEM_ARMOUR = "-----BEGIN";
+const KNOWN_SECRET_PREFIX_RE = new RegExp(`(?:^|[^A-Za-z0-9_])(?:${KNOWN_SECRET_PREFIXES.map(escapeForRegExp).join("|")})`);
+function escapeForRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const SECRET_ASSIGNMENT_RE = /\b([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S{4,})/g;
+const SECRET_NAME_RE = /(_TOKEN|_SECRET|_KEY|_PASSWORD|_CREDENTIAL)$|^(TOKEN|SECRET|PASSWORD)$/i;
+const REQUIRED_ARRAY_FIELDS = ["toolchains", "systemPackages", "setup", "verify", "services", "environment", "agentAssets", "provenance"];
+const TOP_LEVEL_FIELDS = new Set(["version", ...REQUIRED_ARRAY_FIELDS]);
+/** Empty array = valid. Never reads, and never returns, a value — only field names and paths. */
+export function validateDeclaration(doc) {
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        return ["the declaration must be a JSON object"];
+    }
+    const rec = doc;
+    const errors = [];
+    for (const key of Object.keys(rec))
+        if (!TOP_LEVEL_FIELDS.has(key))
+            errors.push(`unknown key "${key}"`);
+    if (rec.version !== 1)
+        errors.push("version must be 1");
+    for (const field of REQUIRED_ARRAY_FIELDS)
+        if (!Array.isArray(rec[field]))
+            errors.push(`${field} must be an array`);
+    // The rules below assume the shape above holds; a missing/wrong-typed field is reported on its own.
+    if (errors.length > 0)
+        return errors;
+    const environment = rec.environment;
+    if (environment.length > MAX_ENV_REFS)
+        errors.push(`environment has ${environment.length} entries; at most ${MAX_ENV_REFS}`);
+    for (const [i, e] of environment.entries()) {
+        if (typeof e !== "object" || e === null) {
+            errors.push(`environment[${i}] must be an object`);
+            continue;
+        }
+        const rec2 = e;
+        if (typeof rec2.name !== "string" || !ENV_NAME_RE.test(rec2.name))
+            errors.push(`environment[${i}].name is not a valid name`);
+        if (typeof rec2.required !== "boolean")
+            errors.push(`environment[${i}].required must be a boolean`);
+        if (!Array.isArray(rec2.provenanceIds))
+            errors.push(`environment[${i}].provenanceIds must be an array`);
+    }
+    for (const field of ["setup", "verify"]) {
+        for (const [i, s] of rec[field].entries()) {
+            if (typeof s !== "object" || s === null) {
+                errors.push(`${field}[${i}] must be an object`);
+                continue;
+            }
+            const rec2 = s;
+            const command = rec2.command;
+            if (!Array.isArray(command) || command.length === 0 || !command.every((c) => typeof c === "string")) {
+                errors.push(`${field}[${i}].command must be an argv array (a bare shell string is refused; ["sh","-lc", …] is the explicit escape)`);
+            }
+            if (typeof rec2.timeoutSeconds !== "number")
+                errors.push(`${field}[${i}].timeoutSeconds must be a number`);
+            if (!Array.isArray(rec2.provenanceIds))
+                errors.push(`${field}[${i}].provenanceIds must be an array`);
+        }
+    }
+    // C-2: services / provenance / agentAssets had no element check at all, so a non-object element
+    // reached the free-text sweep below and threw instead of being reported. The rule is the same one
+    // `environment` and `setup`/`verify` already apply: an element that is not an object is an error.
+    for (const field of ["services", "provenance", "agentAssets"]) {
+        for (const [i, e] of rec[field].entries()) {
+            if (typeof e !== "object" || e === null || Array.isArray(e))
+                errors.push(`${field}[${i}] must be an object`);
+        }
+    }
+    // assertNoSecretMaterial, LAST — a value-SHAPE refusal over every free-text field (argv strings,
+    // service image names, provenance explanations, agent-asset references), never a classifier over
+    // environment[].name: there is nothing to classify there. The refusal names the FIELD, never the
+    // matched text, so this function never prints what it found.
+    for (const { path, text } of collectFreeText(rec)) {
+        if (text.includes(PEM_ARMOUR) || KNOWN_SECRET_PREFIX_RE.test(text)) {
+            errors.push(`${path} appears to contain secret material (matches a known credential prefix)`);
+            continue;
+        }
+        SECRET_ASSIGNMENT_RE.lastIndex = 0;
+        let m;
+        while ((m = SECRET_ASSIGNMENT_RE.exec(text))) {
+            if (SECRET_NAME_RE.test(m[1])) {
+                errors.push(`${path} appears to contain secret material (an assignment shaped like a secret name)`);
+                break;
+            }
+        }
+    }
+    return errors;
+}
+function collectFreeText(rec) {
+    const out = [];
+    for (const field of ["setup", "verify"]) {
+        for (const [i, s] of rec[field].entries()) {
+            const rec2 = asRecord(s);
+            if (rec2 === null)
+                continue;
+            if (Array.isArray(rec2.command)) {
+                for (const c of rec2.command)
+                    if (typeof c === "string")
+                        out.push({ path: `${field}[${i}].command`, text: c });
+            }
+        }
+    }
+    for (const [i, s] of rec.services.entries()) {
+        const rec2 = asRecord(s);
+        if (rec2 === null)
+            continue;
+        if (typeof rec2.image === "string")
+            out.push({ path: `services[${i}].image`, text: rec2.image });
+    }
+    for (const [i, p] of rec.provenance.entries()) {
+        const rec2 = asRecord(p);
+        if (rec2 === null)
+            continue;
+        if (typeof rec2.explanation === "string")
+            out.push({ path: `provenance[${i}].explanation`, text: rec2.explanation });
+    }
+    for (const [i, a] of rec.agentAssets.entries()) {
+        const rec2 = asRecord(a);
+        if (rec2 === null)
+            continue;
+        if (typeof rec2.reference === "string")
+            out.push({ path: `agentAssets[${i}].reference`, text: rec2.reference });
+    }
+    return out;
+}
+/** An element the caller may safely read properties off, or null — a non-object is reported above. */
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}

package/dist/env/group.js

@@ -0,0 +1,51 @@
+const GROUP_ORDER = ["build/test", "deploy-only", "bindings"];
+export function groupSightings(sightings) {
+    const byName = new Map();
+    for (const s of sightings) {
+        if (!byName.has(s.name))
+            byName.set(s.name, []);
+        byName.get(s.name).push(s);
+    }
+    const entries = [];
+    for (const [name, list] of byName) {
+        const binding = list.find((s) => s.isBinding);
+        const wranglerVar = list.find((s) => s.isWranglerVar);
+        let group;
+        let needsDeclaration = true;
+        let wranglerEnvironment;
+        if (binding) {
+            group = "bindings";
+            wranglerEnvironment = binding.wranglerEnvironment;
+        }
+        else if (wranglerVar) {
+            group = "build/test";
+            needsDeclaration = false;
+            wranglerEnvironment = wranglerVar.wranglerEnvironment;
+        }
+        else {
+            const allJobScoped = list.every((s) => s.jobId !== undefined);
+            const allDeploy = list.every((s) => s.jobDeploy === true);
+            group = allJobScoped && allDeploy ? "deploy-only" : "build/test";
+        }
+        const localSource = resolveLocalSource(group, list);
+        const found = list.map((s) => s.finding).sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)));
+        entries.push({ name, group, localSource, needsDeclaration, wranglerEnvironment, found });
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const groups = GROUP_ORDER.map((id) => ({
+        id,
+        names: entries.filter((e) => e.group === id).map((e) => e.name).sort(),
+    }));
+    return { entries, groups };
+}
+function resolveLocalSource(group, list) {
+    if (group === "bindings")
+        return "Cloudflare binding";
+    if (list.some((s) => s.isWranglerVar))
+        return "value committed in wrangler.toml — nothing to declare";
+    const hasEnvShell = list.some((s) => s.localSource === ".env file or your shell");
+    const hasCiSecret = list.some((s) => s.localSource === "CI secret");
+    if (group === "deploy-only")
+        return hasCiSecret ? "CI secret" : ".env file or your shell";
+    return hasEnvShell ? ".env file or your shell" : hasCiSecret ? "CI secret" : list[0].localSource;
+}

package/dist/env/inventory.js

@@ -0,0 +1,102 @@
+// inventory.ts — walks a repository once and dispatches each file to the scanner that understands it.
+// D-5: `.env` and `.dev.vars` are never opened — not filtered out after reading, never asked for at
+// all. Nothing in the dispatch table below names them, so the structural guarantee holds without a
+// separate exclusion list that could itself drift.
+//
+// ⛔ D-5 IS KEYED ON THE REAL PATH, NOT ON THE WALKED ONE (validate attempt 29, M-2). A basename is
+// exactly what a symlink controls: a committed `.env.example -> .env` used to route the REAL `.env`
+// into scanEnvExample, because the dispatch read the link's name rather than the file it opens.
+// Chained with the unquoted-PEM defect in scan-env-example.ts, that printed verbatim bytes of an
+// uncommitted private key as a variable NAME. So each file is resolved with `realpathSync` first,
+// the dispatch keys on the resolved basename, and NEVER_READ_BASENAMES refuses the two names D-5
+// promises are never opened — under either name, the link's or the target's.
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { groupSightings } from "./group.js";
+import { ENV_EXAMPLE_FILES, scanEnvExample } from "./scan-env-example.js";
+import { MAX_SOURCE_FILE_BYTES, SOURCE_EXTENSIONS, scanSource } from "./scan-source.js";
+import { scanWorkflow } from "./scan-workflow.js";
+import { scanWrangler } from "./scan-wrangler.js";
+import { walkRepo } from "./walk.js";
+/** D-5's promise, as a list: neither name is ever opened, by either route. */
+const NEVER_READ_BASENAMES = new Set([".env", ".dev.vars"]);
+/** Above this a file is not read at all, whatever it is. CR-7: a drop here is always noted. */
+export const HARD_READ_CAP_BYTES = MAX_SOURCE_FILE_BYTES * 4;
+function defaultReadFile(path) {
+    try {
+        if (statSync(path).size > HARD_READ_CAP_BYTES)
+            return undefined;
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The basename of the file `abs` really opens, or the walked basename when it cannot be resolved. */
+function resolvedBasename(abs, walked) {
+    try {
+        return basename(realpathSync(abs));
+    }
+    catch {
+        return walked;
+    }
+}
+export function inventoryRepo(root, deps = {}) {
+    const readFile = deps.readFile ?? defaultReadFile;
+    const listFiles = deps.listFiles ?? walkRepo;
+    const files = listFiles(root);
+    const sightings = [];
+    const jobs = [];
+    const notes = [];
+    for (const rel of files) {
+        const walkedBase = rel.split("/").pop() ?? rel;
+        const abs = join(root, rel);
+        const base = resolvedBasename(abs, walkedBase);
+        // M-2: refused under either name — the link's or the one it really opens.
+        if (NEVER_READ_BASENAMES.has(base) || NEVER_READ_BASENAMES.has(walkedBase))
+            continue;
+        if (ENV_EXAMPLE_FILES.includes(base)) {
+            const text = readFile(abs);
+            if (text !== undefined)
+                sightings.push(...scanEnvExample(rel, text));
+            continue;
+        }
+        if (rel.startsWith(".github/workflows/") && (rel.endsWith(".yml") || rel.endsWith(".yaml"))) {
+            const text = readFile(abs);
+            if (text !== undefined) {
+                const res = scanWorkflow(rel, text);
+                sightings.push(...res.sightings);
+                jobs.push(...res.jobs);
+            }
+            continue;
+        }
+        if (base === "wrangler.toml") {
+            const text = readFile(abs);
+            if (text !== undefined)
+                sightings.push(...scanWrangler(rel, text));
+            continue;
+        }
+        if (base === "wrangler.json" || base === "wrangler.jsonc") {
+            notes.push(`${rel} is a Cloudflare config this scan does not read yet (JSON/JSONC) — its vars and bindings are not reflected below.`);
+            continue;
+        }
+        if (SOURCE_EXTENSIONS.some((ext) => rel.endsWith(ext))) {
+            const text = readFile(abs);
+            // CR-7: the 512 KB band below emitted a note while the hard cap above it emitted NOTHING, so a
+            // file over 2 MB vanished from the inventory with no trace at all. Every drop is now named.
+            if (text === undefined) {
+                notes.push(`${rel} could not be read (unreadable, or over the ${HARD_READ_CAP_BYTES} byte hard cap) and was skipped`);
+                continue;
+            }
+            // CR-7: measured in BYTES. `text.length` counts UTF-16 code units, so a file of multi-byte
+            // characters was compared against the wrong number.
+            if (Buffer.byteLength(text, "utf8") > MAX_SOURCE_FILE_BYTES) {
+                notes.push(`${rel} is over 512 KB and was skipped`);
+                continue;
+            }
+            sightings.push(...scanSource(rel, text));
+        }
+    }
+    const { entries, groups } = groupSightings(sightings);
+    return { root, entries, groups, jobs, notes };
+}

package/dist/env/render.js

@@ -0,0 +1,39 @@
+const GROUP_BLURB = {
+    "build/test": "needed to install, build and run the tests in a container",
+    "deploy-only": "a CI secret used only by a deploy job",
+    bindings: "a Cloudflare (or other platform) binding — not an environment value",
+};
+export function renderInventory(inv) {
+    const lines = [];
+    for (const group of inv.groups) {
+        lines.push(`${group.id} — ${GROUP_BLURB[group.id]}`);
+        if (group.names.length === 0) {
+            lines.push("  (none found)");
+        }
+        else {
+            for (const name of group.names) {
+                const entry = inv.entries.find((e) => e.name === name);
+                if (!entry)
+                    continue;
+                const where = entry.found.map((f) => `${f.file}:${f.line}`).join(", ");
+                const consumers = [...new Set(entry.found.map((f) => f.consumer))].join(", ");
+                lines.push(`  ${name} — found ${where} · used by ${consumers} · value comes from ${entry.localSource}`);
+            }
+        }
+        lines.push("");
+    }
+    if (inv.notes.length > 0) {
+        lines.push("Notes:");
+        for (const n of inv.notes)
+            lines.push(`  ${n}`);
+    }
+    return lines;
+}
+export function inventoryToJson(inv) {
+    return { root: inv.root, groups: inv.groups, entries: inv.entries, jobs: inv.jobs, notes: inv.notes };
+}
+export function renderCheck(result, file) {
+    if (result.state === "valid")
+        return [`valid — ${file} passes this bundle's offline check`];
+    return [`invalid — ${file} failed this bundle's offline check:`, ...result.errors.map((e) => `  - ${e}`)];
+}

package/dist/env/scan-env-example.js

@@ -0,0 +1,62 @@
+export const ENV_EXAMPLE_FILES = [".env.example", ".env.sample", ".env.template", ".env.defaults", ".dev.vars.example"];
+const LINE_RE = /^\s*(#\s*)?(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const PEM_BEGIN = "-----BEGIN";
+const PEM_END = "-----END";
+export function scanEnvExample(file, text) {
+    const out = [];
+    const lines = text.split("\n");
+    // Non-null while a quoted value is still open. Lines inside one are skipped entirely: the name
+    // that opened the value was already recorded, and everything after it is value material.
+    let openQuote = null;
+    // True when the open quote was opened by a COMMENTED assignment — see shape 2 above.
+    let openQuoteCommented = false;
+    // True while a PEM armour block opened by a value half is still unterminated — see shape 1 above.
+    let openPem = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (openPem) {
+            if (line.includes(PEM_END))
+                openPem = false;
+            continue;
+        }
+        if (openQuote) {
+            if (openQuoteCommented && !line.trimStart().startsWith("#")) {
+                // The comment block ended, so the "value" ended with it. Fall through and read this line.
+                openQuote = null;
+                openQuoteCommented = false;
+            }
+            else {
+                if (line.includes(openQuote)) {
+                    openQuote = null;
+                    openQuoteCommented = false;
+                }
+                continue;
+            }
+        }
+        const m = LINE_RE.exec(line);
+        if (!m)
+            continue;
+        const value = m[3];
+        if (value.includes(PEM_BEGIN) && !value.includes(PEM_END)) {
+            openPem = true;
+        }
+        else {
+            openQuote = unclosedQuote(value);
+            openQuoteCommented = openQuote !== null && m[1] !== undefined;
+        }
+        out.push({
+            name: m[2],
+            finding: { file, line: i + 1, consumer: `a documented name in ${file}`, consumerKind: "env-example" },
+            localSource: ".env file or your shell",
+        });
+    }
+    return out;
+}
+/** The quote character this value half opens and does not close on its own line, or null. */
+function unclosedQuote(value) {
+    const v = value.trim();
+    const q = v[0];
+    if (q !== '"' && q !== "'")
+        return null;
+    return v.slice(1).includes(q) ? null : q;
+}

package/dist/env/scan-source.js

@@ -0,0 +1,43 @@
+export const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+export const MAX_SOURCE_FILE_BYTES = 512 * 1024;
+const PATTERNS = [
+    /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+    /\bprocess\.env\[["']([A-Za-z_][A-Za-z0-9_]*)["']\]/g,
+    /\bimport\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+    /\bDeno\.env\.get\(["']([A-Za-z_][A-Za-z0-9_]*)["']\)/g,
+];
+export function scanSource(file, text) {
+    const out = [];
+    const lineStarts = computeLineStarts(text);
+    for (const re of PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text))) {
+            out.push({
+                name: m[1],
+                finding: { file, line: lineOf(lineStarts, m.index), consumer: `read by ${file}`, consumerKind: "source" },
+                localSource: ".env file or your shell",
+            });
+        }
+    }
+    return out;
+}
+function computeLineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === "\n")
+            starts.push(i + 1);
+    return starts;
+}
+function lineOf(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}