@catalyst-cloud/cli 0.9.4 → 0.13.0

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;
+}

package/dist/env/scan-workflow.js

@@ -0,0 +1,123 @@
+// scan-workflow.ts — names a GitHub Actions workflow declares or references, read with the real YAML
+// parser (`yaml`, D-2). A hand-written line scanner silently loses names written in flow style
+// (`env: { A: 1, B: 2 }`); `parseDocument` does not, and it hands back the exact file:line for every
+// key through `LineCounter`, plus the structural path (workflow env / a specific job) for free.
+import { LineCounter, isMap, isScalar, isSeq, parseDocument } from "yaml";
+const DEPLOY_JOB_ID_RE = /^(deploy|publish|release|cd)([-_].*)?$/i;
+const DEPLOY_COMMANDS = ["wrangler deploy", "wrangler versions upload", "npm publish", "pnpm publish", "bun publish", "gh release create", "flyctl deploy", "vercel deploy"];
+const SECRET_VAR_RE = /\$\{\{\s*(secrets|vars)\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+export function scanWorkflow(file, text) {
+    const lc = new LineCounter();
+    let doc;
+    try {
+        doc = parseDocument(text, { lineCounter: lc });
+    }
+    catch {
+        return { sightings: [], jobs: [] };
+    }
+    const lineOf = (offset) => lc.linePos(offset).line;
+    const root = doc.contents;
+    const sightings = [];
+    const jobs = [];
+    const jobRanges = [];
+    if (!isMap(root))
+        return { sightings, jobs };
+    const topEnv = root.get("env", true);
+    if (isMap(topEnv)) {
+        for (const pair of topEnv.items) {
+            if (!isScalar(pair.key))
+                continue;
+            const offset = pair.key.range?.[0] ?? 0;
+            sightings.push({
+                name: String(pair.key.value),
+                finding: { file, line: lineOf(offset), consumer: "workflow env", consumerKind: "workflow-env" },
+                localSource: ".env file or your shell",
+            });
+        }
+    }
+    const jobsNode = root.get("jobs", true);
+    if (isMap(jobsNode)) {
+        for (const jobPair of jobsNode.items) {
+            if (!isScalar(jobPair.key) || !isMap(jobPair.value))
+                continue;
+            const jobId = String(jobPair.key.value);
+            const jobMap = jobPair.value;
+            const jobKeyOffset = jobPair.key.range?.[0] ?? 0;
+            const jobRange = jobMap.range ?? [jobKeyOffset, jobKeyOffset, jobKeyOffset];
+            let deploy = jobMap.get("environment", true) !== undefined;
+            let why = deploy ? "has an environment:" : "";
+            if (!deploy && DEPLOY_JOB_ID_RE.test(jobId)) {
+                deploy = true;
+                why = "job id matches a deploy pattern";
+            }
+            const steps = jobMap.get("steps", true);
+            if (isSeq(steps)) {
+                for (const step of steps.items) {
+                    if (!isMap(step))
+                        continue;
+                    const run = step.get("run", true);
+                    if (isScalar(run) && typeof run.value === "string") {
+                        const cmd = DEPLOY_COMMANDS.find((c) => run.value.includes(c));
+                        if (cmd) {
+                            deploy = true;
+                            why = `a step runs ${cmd}`;
+                        }
+                    }
+                    const stepEnv = step.get("env", true);
+                    if (isMap(stepEnv)) {
+                        for (const pair of stepEnv.items) {
+                            if (!isScalar(pair.key))
+                                continue;
+                            const offset = pair.key.range?.[0] ?? 0;
+                            sightings.push({
+                                name: String(pair.key.value),
+                                finding: { file, line: lineOf(offset), consumer: `workflow job ${jobId}`, consumerKind: "workflow-job-env" },
+                                jobId,
+                                localSource: ".env file or your shell",
+                            });
+                        }
+                    }
+                }
+            }
+            const jobEnv = jobMap.get("env", true);
+            if (isMap(jobEnv)) {
+                for (const pair of jobEnv.items) {
+                    if (!isScalar(pair.key))
+                        continue;
+                    const offset = pair.key.range?.[0] ?? 0;
+                    sightings.push({
+                        name: String(pair.key.value),
+                        finding: { file, line: lineOf(offset), consumer: `workflow job ${jobId}`, consumerKind: "workflow-job-env" },
+                        jobId,
+                        localSource: ".env file or your shell",
+                    });
+                }
+            }
+            jobs.push({ id: jobId, file, line: lineOf(jobKeyOffset), deploy, why: why || "no deploy signal" });
+            jobRanges.push({ id: jobId, start: jobRange[0], end: jobRange[2] ?? jobRange[1], deploy });
+        }
+    }
+    // ${{ secrets.X }} / ${{ vars.X }} references, over the RAW TEXT rather than the parsed tree: GitHub
+    // Actions interpolates these anywhere, including inside a `run: |` block's shell text, and a plain
+    // shell assignment inside that same block (e.g. `NOT_A_NAME=1`) must NOT be mined as a name — the
+    // raw-text regex only ever matches the `${{ … }}` expression syntax, never bare shell.
+    SECRET_VAR_RE.lastIndex = 0;
+    let m;
+    while ((m = SECRET_VAR_RE.exec(text))) {
+        const name = m[2];
+        const offset = m.index;
+        const job = jobRanges.find((j) => offset >= j.start && offset < j.end);
+        sightings.push({
+            name,
+            finding: { file, line: lineOf(offset), consumer: job ? `workflow job ${job.id}` : "workflow", consumerKind: `${m[1]}-ref` },
+            jobId: job?.id,
+            jobDeploy: job?.deploy,
+            localSource: "CI secret",
+        });
+    }
+    for (const s of sightings) {
+        if (s.jobId !== undefined && s.jobDeploy === undefined)
+            s.jobDeploy = jobRanges.find((j) => j.id === s.jobId)?.deploy;
+    }
+    return { sightings, jobs };
+}