* feat(#3841): assert gsd-tools identity before any state-mutating verb only this package publishes. The path-based branches — a project-local install, a runtime config directory — had no such guarantee; they trusted their configured location. This closes them. Mechanism: once resolution finishes, and before any verb runs, the preamble probes the tool it picked with `runtime-identity --raw` and matches the answer with a shell `case` pattern ANCHORED to the start of the compact payload (`{"packageName":"@opengsd/gsd-core"`). An unanchored substring match accepts the decoy `{"packageName":"get-shit-done-cc","note":"@opengsd/gsd-core"}`, which any colliding package could publish. The outcome is exported as the two-valued `GSD_IDENTITY_STATUS` (`ok`/`unverified`), so the gate is asserted on a VALUE rather than on warning prose. Rollout is warn-then-fail per the #3146 ruling: `unverified` prints one line naming BOTH causes and continues, because `no_identity_verb` cannot tell a foreign package from an `@opengsd/gsd-core` older than the verb, and at rollout the old-version case is the common one. The blocker was byte budget, not design. The preamble is inlined into 112 shipped files and several sat within single-digit bytes of frozen ceilings (`gsd-verifier.md` 16 bytes, `gsd-executor.md` 33, `execute-phase.md` 234); a first attempt broke five of them. What made room was collapsing the resolver's twenty near-identical `elif [ -f … ]` arms into one candidate-list helper (`_gsd_at`), which buys far more than the assertion costs. The preamble is now 2,624 bytes against 4,500 — a net 1,876 bytes SMALLER per inlined file, so every capped file moved away from its ceiling rather than toward it. No cap raised, no size-budget exception added, no override token emitted. Resolution order, every runtime-home probe, the `unset -f gsd_run` re-source fix, the fail-closed `exit 1`, and the `CLAUDE_ENV_FILE` persistence are all preserved byte-for-byte in substring terms; the snippet still begins with `_GSD_SHIM_NAME=` and still ends with `fi`, which the parity extractors anchor on. `gsd-core/references/gsd-run-resolver.md` is re-synced byte-equal. Also fixes two stale claims found in passing: CONTEXT.md and FEATURES.md both described an `[ -x ]` guard as the load-bearing re-source defense. That guard was tried and REMOVED in #3831 — it rejected the bare function name, fell through every branch, and hit `exit 1`, which kills a sourced caller's shell. `unset -f gsd_run` is the actual mechanism. Refs #3841 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3841): pair the anchor's brace by requiring a closed identity payload The matrix went red on `tests/new-project-mvp-prompt.test.cjs` — "new-project.md has unbalanced braces: net depth 2" — plus a knock-on report from its parent `bug #1516` describe, which is the same failure counted once at the child and once at the block. Root cause: that guard (:182-189, mirroring #3784 bd53925f) walks characters and increments on `{`, decrements on `}`, with no awareness of shell quoting. It scans `new-project.md` PLUS every `new-project/steps/*.md`, and both `new-project.md` and `steps/auto-mode-config.md` carry one inlined preamble copy — hence net 2 from a snippet that was off by exactly one. The unpaired brace was the `{` inside the single-quoted `case` pattern of the identity anchor, which is correct shell and invisible to a text scanner. Fix in the snippet, not the guard. The pattern now anchors at BOTH ends: `'{"packageName":"@opengsd/gsd-core"'*'}'`. That balances 51/51 with a brace that does real work rather than a cosmetic pair — a truncated payload whose prefix matches now fails too, where before it verified. Safe for any future additive field: a JSON object's own closing brace is always the last character, whatever type the last value has, which is pinned by two negative-space tests (a nested object and an array-valued last key must both still verify). Cost: +3 bytes, against the 1,873 the resolver fold already gave back. The alternative considered and rejected was dropping the literal `{` for a `?` glob. It balances too, but weakens the anchor from "must be an opening brace" to "must be any one character", and the anchor is the entire point. Two guards added so this cannot recur silently: - runtime-launcher-parity (F0) pins brace balance at the SNIPPET, so the next edit to that pattern fails on the file it broke instead of surfacing three files downstream in a test whose name mentions neither the launcher nor this issue. It also asserts depth never goes negative, since a `}` preceding its `{` nets to zero while being unbalanced at every prefix. - runtime-identity gains behavioral truncated-payload and trailing-garbage fixtures, so the added `}` is proven load-bearing rather than merely present. Verified: snippet 51/51 braces; new-project combined net depth 0; the seven other preamble-bearing files with nonzero depth are unchanged from merged next (their own prose, not the preamble, and not in any guard's scan set); all 112 inlined copies and the resolver reference re-synced byte-equal; sync:launcher idempotent on the second run. Refs #3841 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3841): backfill changeset PR number Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -27,7 +27,10 @@ const {
|
||||
classifyIdentityProbe,
|
||||
buildIdentityPayload,
|
||||
explainVerdict,
|
||||
statusForVerdict,
|
||||
EXPECTED_PACKAGE_NAME,
|
||||
IDENTITY_STATUS,
|
||||
IDENTITY_RAW_PREFIX,
|
||||
} = require('../gsd-core/bin/lib/runtime-identity.cjs');
|
||||
|
||||
const REPO_ROOT = path.join(__dirname, '..');
|
||||
@@ -339,3 +342,286 @@ describe('launcher resolver: PATH branch prefers the collision-free bin', () =>
|
||||
assert.notEqual(r.exitCode, 0, 'resolution must fail closed');
|
||||
});
|
||||
});
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// #3841 — the launcher preamble ASSERTS identity before any verb runs.
|
||||
//
|
||||
// #3831 closed the PATH route structurally (the resolver takes `gsd_run`, which
|
||||
// only this package publishes). The path-based branches — a project-local
|
||||
// install, a runtime config directory — had no such guarantee: they trusted
|
||||
// their configured location. These tests cover the assertion that closes them.
|
||||
//
|
||||
// Every shell assertion below reads the TYPED `GSD_IDENTITY_STATUS` value, never
|
||||
// the warning prose: CONTRIBUTING forbids `assert.match` on process output as
|
||||
// the proof a behavior fired.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
describe('statusForVerdict — the five-way reason collapses to two shell values', () => {
|
||||
test('only `ok` yields OK; every other reason yields UNVERIFIED', () => {
|
||||
const cases = [
|
||||
[{ stdout: JSON.stringify(buildIdentityPayload({ readVersion: () => '1.0.0' })), exitCode: 0 }, IDENTITY_STATUS.OK],
|
||||
[{ stdout: okStdout('get-shit-done-cc'), exitCode: 0 }, IDENTITY_STATUS.UNVERIFIED],
|
||||
[{ stdout: 'Usage: gsd-sdk', exitCode: 1 }, IDENTITY_STATUS.UNVERIFIED],
|
||||
[{ stdout: 'not json', exitCode: 0 }, IDENTITY_STATUS.UNVERIFIED],
|
||||
[{ stdout: '', exitCode: null, spawnFailed: true }, IDENTITY_STATUS.UNVERIFIED],
|
||||
];
|
||||
const seen = new Set();
|
||||
for (const [probe, expected] of cases) {
|
||||
const verdict = classifyIdentityProbe(probe);
|
||||
seen.add(verdict.reason);
|
||||
assert.equal(statusForVerdict(verdict), expected, `reason ${verdict.reason}`);
|
||||
}
|
||||
// Proof of coverage: all five reason codes were actually exercised above.
|
||||
assert.equal(seen.size, 5, `expected all five reasons, saw ${[...seen].join(',')}`);
|
||||
});
|
||||
|
||||
test('the status enum is frozen, so a test can bind to the value', () => {
|
||||
assert.equal(Object.isFrozen(IDENTITY_STATUS), true);
|
||||
assert.deepEqual(Object.values(IDENTITY_STATUS).sort(), ['ok', 'unverified']);
|
||||
});
|
||||
|
||||
test('is total: every classifier output maps to a declared status', () => {
|
||||
const STATUSES = new Set(Object.values(IDENTITY_STATUS));
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.string(),
|
||||
fc.oneof(fc.integer({ min: -8, max: 8 }), fc.constant(null)),
|
||||
fc.boolean(),
|
||||
fc.boolean(),
|
||||
(stdout, exitCode, spawnFailed, timedOut) => {
|
||||
const verdict = classifyIdentityProbe({ stdout, exitCode, spawnFailed, timedOut });
|
||||
const status = statusForVerdict(verdict);
|
||||
assert.ok(STATUSES.has(status));
|
||||
// OK is reachable only through a genuine match — fail-closed by default.
|
||||
if (status === IDENTITY_STATUS.OK) assert.equal(verdict.reason, 'ok');
|
||||
},
|
||||
),
|
||||
{ seed: 38410, numRuns: 300 },
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('IDENTITY_RAW_PREFIX — the anchor the shell matches on', () => {
|
||||
// Generative-divergence guard: the shell `case` pattern and the JS payload
|
||||
// builder are two surfaces that must agree byte-for-byte. If `--raw`'s key
|
||||
// order or serialization ever changed, the preamble would silently stop
|
||||
// verifying a legitimate install and warn on every run.
|
||||
test('the real --raw payload starts with the prefix', () => {
|
||||
const r = runNode([GSD_TOOLS, 'runtime-identity', '--raw'], { timeoutMs: PROBE_TIMEOUT_MS });
|
||||
assert.equal(r.exitCode, 0);
|
||||
assert.equal(r.stdout.startsWith(IDENTITY_RAW_PREFIX), true);
|
||||
});
|
||||
|
||||
test('the prefix names this package and closes the quoted value', () => {
|
||||
assert.equal(IDENTITY_RAW_PREFIX, `{"packageName":"${EXPECTED_PACKAGE_NAME}"`);
|
||||
});
|
||||
});
|
||||
|
||||
describe('launcher preamble: identity assertion on a path-based branch (#3841)', () => {
|
||||
let dir;
|
||||
let binDir;
|
||||
let toolsDir;
|
||||
|
||||
// Resolution here goes through the RUNTIME_DIR-local branch — the branch
|
||||
// #3831 could NOT make safe structurally, and therefore the one this
|
||||
// assertion exists for.
|
||||
const installFakeTool = (identityBody) => {
|
||||
fs.writeFileSync(
|
||||
path.join(toolsDir, 'gsd-tools.cjs'),
|
||||
'#!/usr/bin/env node\n' +
|
||||
"const a = process.argv.slice(2);\n" +
|
||||
"if (a[0] === 'runtime-identity') { " + identityBody + " }\n" +
|
||||
"process.stdout.write('RAN:' + a.join(',') + '\\n');\n",
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
};
|
||||
|
||||
const sourceAndReport = (extra = '') => {
|
||||
const harness = path.join(dir, 'harness.sh');
|
||||
fs.writeFileSync(
|
||||
harness,
|
||||
'#!/bin/sh\n' +
|
||||
`. "${SNIPPET}"\n` +
|
||||
"printf 'STATUS=%s\\n' \"$GSD_IDENTITY_STATUS\"\n" +
|
||||
extra +
|
||||
'\n',
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
return runHook(harness, [], {
|
||||
// Absolute interpreter: env.PATH below is restricted to the fixture bin,
|
||||
// so a bare `sh` would not resolve and every assertion would be vacuous.
|
||||
interpreter: '/bin/sh',
|
||||
cwd: dir,
|
||||
timeoutMs: PROBE_TIMEOUT_MS,
|
||||
// PATH holds only the fixture bin (plus a node symlink) so a real gsd_run
|
||||
// on the developer's machine cannot satisfy the resolver instead.
|
||||
env: { PATH: binDir, HOME: dir, RUNTIME_DIR: dir },
|
||||
});
|
||||
};
|
||||
|
||||
const skipOnWindows = (t) => {
|
||||
if (process.platform !== 'win32') return false;
|
||||
t.skip('POSIX shell preamble is not executed on Windows runtimes');
|
||||
return true;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
dir = createTempDir('gsd-3841-identity-');
|
||||
binDir = path.join(dir, 'bin');
|
||||
toolsDir = path.join(dir, 'gsd-core', 'bin');
|
||||
fs.mkdirSync(binDir, { recursive: true });
|
||||
fs.mkdirSync(toolsDir, { recursive: true });
|
||||
fs.symlinkSync(process.execPath, path.join(binDir, 'node'));
|
||||
});
|
||||
|
||||
afterEach(() => cleanup(dir));
|
||||
|
||||
const emit = (json) => `process.stdout.write(${JSON.stringify(json)} + '\\n'); process.exit(0);`;
|
||||
|
||||
test('a tool that proves it is this package reports status ok', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"9.9.9"}`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.exitCode, 0);
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.OK}`), true, r.stdout);
|
||||
});
|
||||
|
||||
// ── Anchor boundary: limit-1 / limit / limit+1 on the matched prefix ───────
|
||||
// The "limit" is IDENTITY_RAW_PREFIX itself. One byte short, exact, and one
|
||||
// byte long are the three cases a substring match would get wrong.
|
||||
test('a payload one byte SHORT of the anchor does not verify (limit-1)', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
// Truncate the expected name by one character, then close the JSON legally.
|
||||
const short = IDENTITY_RAW_PREFIX.slice(0, IDENTITY_RAW_PREFIX.length - 2) + '"';
|
||||
assert.notEqual(short, IDENTITY_RAW_PREFIX);
|
||||
installFakeTool(emit(`${short},"version":"9.9.9"}`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
test('the exact anchor verifies (limit)', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"0.0.0"}`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.OK}`), true, r.stdout);
|
||||
});
|
||||
|
||||
test('a payload one byte LONGER than the anchor does not verify (limit+1)', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
// An extra character inside the package name: `@opengsd/gsd-coreX`.
|
||||
const long = `{"packageName":"${EXPECTED_PACKAGE_NAME}X"`;
|
||||
installFakeTool(emit(`${long},"version":"9.9.9"}`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
// ── The closing brace in the pattern is load-bearing, not cosmetic ─────────
|
||||
// The `case` pattern is anchored at BOTH ends: it starts with the prefix and
|
||||
// requires the payload to be a closed object. The trailing `'}'` also happens
|
||||
// to balance the literal `{` for the raw-text brace guards the preamble is
|
||||
// inlined into (see runtime-launcher-parity (F0)) — but it is asserted here
|
||||
// because it does real work. Delete it and these two tests go red.
|
||||
test('a truncated payload does not verify even though its prefix matches', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"9.9.9"`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
test('trailing garbage after the closing brace does not verify', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"9.9.9"} and then some`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
// Negative space for the two above: closing-brace anchoring must not reject a
|
||||
// legitimate FUTURE payload. A JSON object's own `}` is always the last
|
||||
// character regardless of the last value's type, so additive fields are safe.
|
||||
for (const [label, extraKey] of [
|
||||
['a nested object', { extra: { a: [1, 2] } }],
|
||||
['an array-valued last key', { tags: ['x'] }],
|
||||
]) {
|
||||
test(`an additive payload ending in ${label} still verifies`, (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(JSON.stringify({
|
||||
packageName: EXPECTED_PACKAGE_NAME,
|
||||
version: '1.0.0',
|
||||
...extraKey,
|
||||
})));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.OK}`), true, r.stdout);
|
||||
});
|
||||
}
|
||||
|
||||
test('the anchor rejects a decoy that carries the name in a later field', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
// An UNANCHORED substring match accepts this. That is the whole point of
|
||||
// anchoring: the decoy is trivially publishable by a colliding package.
|
||||
installFakeTool(emit(JSON.stringify({ packageName: 'get-shit-done-cc', note: EXPECTED_PACKAGE_NAME })));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
test('a tool with no runtime-identity verb does not verify and does not kill the run', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
// Shape of the real predecessor: usage screen, exit 1. Also the shape of an
|
||||
// @opengsd/gsd-core older than the verb — which is why this WARNS rather
|
||||
// than failing during the warn-then-fail rollout (#3146 ruling).
|
||||
installFakeTool("process.stderr.write('Unknown command\\n'); process.exit(1);");
|
||||
|
||||
const r = sourceAndReport('gsd_run phases clear');
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
assert.equal(r.exitCode, 0, 'the warn phase must not stop the workflow');
|
||||
assert.equal(r.stdout.includes('RAN:phases,clear'), true, 'the verb must still run in the warn phase');
|
||||
});
|
||||
|
||||
test('a probe that prints nothing does not verify', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool('process.exit(0);');
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.includes(`STATUS=${IDENTITY_STATUS.UNVERIFIED}`), true, r.stdout);
|
||||
});
|
||||
|
||||
test('the probe writes nothing to the workflow stdout', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
// The preamble captures the probe in a command substitution. If it leaked,
|
||||
// every workflow that parses gsd_run output would read the payload first.
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"1.0.0"}`));
|
||||
|
||||
const r = sourceAndReport();
|
||||
|
||||
assert.equal(r.stdout.split('\n')[0], `STATUS=${IDENTITY_STATUS.OK}`, r.stdout);
|
||||
});
|
||||
|
||||
test('the status survives as an exported environment variable', (t) => {
|
||||
if (skipOnWindows(t)) return;
|
||||
installFakeTool(emit(`${IDENTITY_RAW_PREFIX},"version":"1.0.0"}`));
|
||||
|
||||
// A child process must see it — workflows spawn subshells between steps.
|
||||
// Absolute interpreter: PATH holds only the fixture bin, so a bare `sh`
|
||||
// would not resolve and the child would never run.
|
||||
const r = sourceAndReport('/bin/sh -c \'printf "CHILD=%s\\n" "$GSD_IDENTITY_STATUS"\'');
|
||||
|
||||
assert.equal(r.stdout.includes(`CHILD=${IDENTITY_STATUS.OK}`), true, r.stdout);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -608,6 +608,46 @@ describe('runtime-launcher-parity (#373)', () => {
|
||||
}
|
||||
});
|
||||
|
||||
// ─── (F0) Brace balance — the preamble is inlined into brace-counted files ──
|
||||
//
|
||||
// Regression for the #3841 red matrix run. The preamble is inlined into 112
|
||||
// shipped files, and several downstream guards balance braces by scanning raw
|
||||
// TEXT with no string-context awareness — tests/new-project-mvp-prompt.test.cjs's
|
||||
// "balanced braces" guard (mirroring #3784 bd53925f) counts every `{` and `}`
|
||||
// across new-project.md plus its steps/. new-project.md and
|
||||
// new-project/steps/auto-mode-config.md each carry one preamble copy, so a
|
||||
// snippet that is off by one reports a combined net depth of TWO, in a test whose
|
||||
// name mentions neither the launcher nor this issue.
|
||||
//
|
||||
// The identity assertion's `case` pattern legitimately contains a `{` inside a
|
||||
// single-quoted shell literal. It is paired by requiring the payload to be a
|
||||
// CLOSED object (`*'}'`) — which is also a real strengthening, since a truncated
|
||||
// payload then fails. Pin the balance HERE, at the snippet, so the next edit to
|
||||
// that pattern fails on the file it broke rather than three files downstream.
|
||||
test('(F0) the snippet has balanced braces (#3841 — inlined into brace-counted files)', () => {
|
||||
const snippetContent = fs.readFileSync(SNIPPET_FILE, 'utf8');
|
||||
let depth = 0;
|
||||
let minDepth = 0;
|
||||
for (const ch of snippetContent) {
|
||||
if (ch === '{') depth++;
|
||||
if (ch === '}') depth--;
|
||||
if (depth < minDepth) minDepth = depth;
|
||||
}
|
||||
assert.equal(
|
||||
depth,
|
||||
0,
|
||||
`_runtime-launcher.snippet.sh has unbalanced braces: net depth ${depth}. ` +
|
||||
`The preamble is inlined into 112 shipped files, and downstream guards ` +
|
||||
`(tests/new-project-mvp-prompt.test.cjs) balance braces over raw text with no ` +
|
||||
`awareness of shell quoting — an unpaired brace here fails there instead, ` +
|
||||
`multiplied by the number of inlined copies in the scanned file set. ` +
|
||||
`Pair the brace in the snippet; do not relax the downstream guard.`,
|
||||
);
|
||||
// Never dips below zero: a `}` that precedes its `{` would still net to 0 while
|
||||
// being unbalanced at every prefix, which is what a text scanner actually reports.
|
||||
assert.equal(minDepth, 0, `brace depth went negative (min ${minDepth}) — a closing brace precedes its opener`);
|
||||
});
|
||||
|
||||
// ─── (F) Regression locks: no /gsd-tools substring; no do.md dispatcher false-positive ──
|
||||
test('(F) snippet has no /gsd-tools substring; do.md has no /gsd[:-][a-z] matches', () => {
|
||||
// (F1) The snippet must not contain the literal substring /gsd-tools.
|
||||
|
||||
Reference in New Issue
Block a user