diff --git a/docs/architecture/tla/CommandFrontmatter.NoBomStrip.cfg b/docs/architecture/tla/CommandFrontmatter.NoBomStrip.cfg new file mode 100644 index 0000000000..9475a86d3c --- /dev/null +++ b/docs/architecture/tla/CommandFrontmatter.NoBomStrip.cfg @@ -0,0 +1,4 @@ +SPECIFICATION Spec +CONSTANTS + Variant = "NoBomStrip" +INVARIANTS TypeOK NoExecutableEngine diff --git a/docs/architecture/tla/CommandFrontmatter.None.cfg b/docs/architecture/tla/CommandFrontmatter.None.cfg new file mode 100644 index 0000000000..078db3c777 --- /dev/null +++ b/docs/architecture/tla/CommandFrontmatter.None.cfg @@ -0,0 +1,4 @@ +SPECIFICATION Spec +CONSTANTS + Variant = "None" +INVARIANTS TypeOK NoExecutableEngine diff --git a/docs/architecture/tla/CommandFrontmatter.cfg b/docs/architecture/tla/CommandFrontmatter.cfg new file mode 100644 index 0000000000..1401ce9132 --- /dev/null +++ b/docs/architecture/tla/CommandFrontmatter.cfg @@ -0,0 +1,4 @@ +SPECIFICATION Spec +CONSTANTS + Variant = "Fixed" +INVARIANTS TypeOK NoExecutableEngine diff --git a/docs/architecture/tla/CommandFrontmatter.tla b/docs/architecture/tla/CommandFrontmatter.tla new file mode 100644 index 0000000000..da5496a177 --- /dev/null +++ b/docs/architecture/tla/CommandFrontmatter.tla @@ -0,0 +1,37 @@ +---- MODULE CommandFrontmatter ---- +\* Models parseCommandFrontmatter (src/services/command/commands.ts). +\* Both callers, scanCommandDirectory and tryLoadCommand, use it. The property test covers both. +\* Source: the header language in a workspace command file. Sink: the gray-matter engine call. +\* Failure: a command file header selects an executable engine and the extension runs its code. +\* Invariant: NoExecutableEngine. gray-matter is an oracle. Only the header language is modeled. +\* Expect: Fixed holds. None fails at once. NoBomStrip fails with a BOM and an executable header. +\* Result: Fixed holds in 6 states. None fails in 1 state. NoBomStrip fails in 1 state, with a BOM. +\* Replay: gray-matter runs a js header in the real library. The guard in the code stops it. +\* Not modeled: the YAML and JSON parsers. The command body. +\* Cost: TLC runs in under 1 second. Agent time is not measured. +\* Review: 1 covered (bot thread on double BOM, PR 2455), 0 added, 0 gap. +\* Replay: two BOMs do not run code in gray-matter. It is a false alarm. A test case stays. + +CONSTANT Variant \* "Fixed", "None" or "NoBomStrip" + +VARIABLE in + +\* "exec" = js or javascript in any case. "data" = yaml, yml, json or no language. +\* "other" = any other name. gray-matter finds no engine for it. +Inputs == [bom : BOOLEAN, lang : {"data", "exec", "other"}] + +\* The guard reads the header language. Without the BOM strip it misses the header. +GuardSeesHeader(i) == Variant = "Fixed" \/ (Variant = "NoBomStrip" /\ ~i.bom) +Rejected(i) == GuardSeesHeader(i) /\ i.lang # "data" +Executed(i) == i.lang = "exec" /\ ~Rejected(i) + +TypeOK == in \in Inputs + +Init == in \in Inputs +Next == UNCHANGED in +Spec == Init /\ [][Next]_in + +\* Safety: no input reaches an executable engine. +NoExecutableEngine == ~Executed(in) + +==== diff --git a/src/services/command/__tests__/frontmatter-commands.spec.ts b/src/services/command/__tests__/frontmatter-commands.spec.ts index ecf1c5ffff..582e95cffa 100644 --- a/src/services/command/__tests__/frontmatter-commands.spec.ts +++ b/src/services/command/__tests__/frontmatter-commands.spec.ts @@ -515,3 +515,54 @@ Deploy the app.` }) }) }) + +// Invariant NoExecutableEngine (docs/architecture/tla/CommandFrontmatter.tla): no header runs code. +// Exercise the real parser through both public loading paths. +describe.each(["discovery", "individual"])("%s frontmatter security", (entryPoint) => { + async function load(content: string) { + mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true }) + mockFs.readdir = vi.fn().mockResolvedValue([{ name: "security-probe.md", isFile: () => true }]) + mockFs.readFile = vi.fn().mockResolvedValue(content) + return entryPoint === "discovery" + ? (await getCommands("/test/cwd")).find((command) => command.name === "security-probe") + : await getCommand("/test/cwd", "security-probe") + } + + it.each(["javascript", "js", "JS", "JavaScript", " javascript ", "\uFEFF---js", "\uFEFF\uFEFF---javascript"])( + "does not execute %s frontmatter", + async (header) => { + const execute = vi.fn(() => ({ description: "Executed" })) + vi.stubGlobal("__commandFrontmatterProbe", execute) + try { + const opening = header.startsWith("\uFEFF") ? header : `---${header}` + const content = `${opening}\n(globalThis.__commandFrontmatterProbe())\n---\nCommand body` + const result = await load(content) + expect(execute).not.toHaveBeenCalled() + expect(result?.description).toBeUndefined() + expect(result?.content).toBe(content.trim()) + } finally { + vi.unstubAllGlobals() + } + }, + ) + + it.each(["toml", "coffee", "constructor", "__proto__"])("keeps unsupported %s as text", async (header) => { + const content = `---${header}\ndescription: Test\n---\nCommand body` + const result = await load(content) + expect(result?.content).toBe(content) + expect(result?.description).toBeUndefined() + }) + + it.each(["", "yaml", "yml", "json"])("accepts data frontmatter %s", async (header) => { + const data = { description: "Test", "argument-hint": "value", mode: "code" } + const metadata = + header === "json" ? JSON.stringify(data) : "description: Test\nargument-hint: value\nmode: code" + const result = await load(`---${header}\r\n${metadata}\r\n---\r\nCommand body`) + expect(result).toMatchObject({ + description: "Test", + argumentHint: "value", + mode: "code", + content: "Command body", + }) + }) +})