Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/architecture/tla/CommandFrontmatter.NoBomStrip.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
SPECIFICATION Spec
CONSTANTS
Variant = "NoBomStrip"
INVARIANTS TypeOK NoExecutableEngine
4 changes: 4 additions & 0 deletions docs/architecture/tla/CommandFrontmatter.None.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
SPECIFICATION Spec
CONSTANTS
Variant = "None"
INVARIANTS TypeOK NoExecutableEngine
4 changes: 4 additions & 0 deletions docs/architecture/tla/CommandFrontmatter.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
SPECIFICATION Spec
CONSTANTS
Variant = "Fixed"
INVARIANTS TypeOK NoExecutableEngine
37 changes: 37 additions & 0 deletions docs/architecture/tla/CommandFrontmatter.tla
Original file line number Diff line number Diff line change
@@ -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)

====
51 changes: 51 additions & 0 deletions src/services/command/__tests__/frontmatter-commands.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
})
})
})
Loading