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/Frontmatter.CaseSensitive.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
SPECIFICATION Spec
CONSTANTS
Variant = "CaseSensitive"
INVARIANTS TypeOK NoExecutableEngine ValidDataAccepted
2 changes: 1 addition & 1 deletion docs/architecture/tla/Frontmatter.cfg
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
SPECIFICATION Spec
CONSTANTS
Variant = "Fixed"
INVARIANTS TypeOK NoExecutableEngine
INVARIANTS TypeOK NoExecutableEngine ValidDataAccepted
25 changes: 16 additions & 9 deletions docs/architecture/tla/Frontmatter.tla
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,34 @@
\* Callers: scanCommandDirectory, tryLoadCommand and SkillsManager (load, read, update). One guard serves all.
\* Source: the header language in a workspace command or skill file. Sink: the gray-matter engine call.
\* Failure: a 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.
\* Invariants: NoExecutableEngine and ValidDataAccepted. 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.
\* Expect: CaseSensitive fails ValidDataAccepted on an upper-case data header.
\* Result: Fixed holds in 8 states. CaseSensitive fails ValidDataAccepted in 1 state, with upper-case YAML.
\* Result: Before this change, Fixed held 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 file 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, 1 gap.
\* Gap: PR 2456 bot thread on uppercase YAML. The spec models safety only, not false rejects. A test covers it.
\* Review: 1 covered (bot thread on double BOM, PR 2455), 1 added, 0 gap.
\* Added: PR 2456 bot thread on uppercase YAML. ValidDataAccepted and the CaseSensitive config model it.
\* Gap: an upper-case JSON header passes the guard. gray-matter then throws "engine not registered". It is a safe false reject. The code is unchanged.
\* Gap: a YAML tag such as !!js/function is not a header language. The spec cannot express it. A test covers it.
\* Replay: two BOMs do not run code in gray-matter. It is a false alarm. A test case stays.
\* Skills: the skill caller is the same input domain. The skill path was unguarded before this change.
\* Property test: src/utils/__tests__/safeFrontmatter.spec.ts. Caller tests: SkillsManager.spec.ts, frontmatter-commands.spec.ts.

CONSTANT Variant \* "Fixed", "None" or "NoBomStrip"
CONSTANT Variant \* "Fixed", "None", "NoBomStrip" or "CaseSensitive"

VARIABLE in

\* "exec" = js or javascript in any case. "data" = yaml, yml, json or no language.
\* "exec" = js or javascript in any case. "data" = yaml, yml, json or no language, lower case.
\* "upper" = yaml or yml with an upper-case letter. gray-matter does not lowercase json.
\* "other" = any other name. gray-matter finds no engine for it.
Inputs == [bom : BOOLEAN, lang : {"data", "exec", "other"}]
Inputs == [bom : BOOLEAN, lang : {"data", "upper", "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"
GuardSeesHeader(i) == Variant \in {"Fixed", "CaseSensitive"} \/ (Variant = "NoBomStrip" /\ ~i.bom)
Rejected(i) == GuardSeesHeader(i) /\ i.lang # "data" /\ (i.lang # "upper" \/ Variant = "CaseSensitive")
Executed(i) == i.lang = "exec" /\ ~Rejected(i)

TypeOK == in \in Inputs
Expand All @@ -38,4 +42,7 @@ Spec == Init /\ [][Next]_in
\* Safety: no input reaches an executable engine.
NoExecutableEngine == ~Executed(in)

\* Liveness of valid files: a data header is never rejected.
ValidDataAccepted == in.lang \in {"data", "upper"} => ~Rejected(in)

====
37 changes: 24 additions & 13 deletions src/services/skills/__tests__/SkillsManager.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -218,19 +218,30 @@ describe("SkillsManager", () => {
}
})

it.each(["", "yaml", "json"])("accepts data-only %s metadata in skill operations", async (language) => {
mockDirectoryExists.mockImplementation(async (dir: string) => dir === projectSkillsDir)
mockRealpath.mockImplementation(async (value: string) => value)
mockReaddir.mockImplementation(async (dir: string) => (dir === projectSkillsDir ? ["example"] : []))
mockStat.mockResolvedValue({ isDirectory: () => true })
mockFileExists.mockResolvedValue(true)
const metadata =
language === "json" ? '{"name":"example","description":"Example"}' : "name: example\ndescription: Example"
mockReadFile.mockResolvedValue(`---${language}\n${metadata}\n---\nBody`)
await skillsManager.discoverSkills()
expect(skillsManager.getAllSkills()).toHaveLength(1)
expect((await skillsManager.getSkillContent("example"))?.instructions).toBe("Body")
})
it.each(["", "yaml", "YAML", "yml", "YML", "json"])(
"accepts data-only %s metadata in skill operations",
async (language) => {
const metadata =
language === "json"
? '{"name":"example","description":"Example skill"}'
: "name: example\ndescription: Example skill"
mockDirectoryExists.mockImplementation(async (dir: string) => dir === projectSkillsDir)
mockRealpath.mockImplementation(async (value: string) => value)
mockReaddir.mockImplementation(async (dir: string) => (dir === projectSkillsDir ? ["example"] : []))
mockStat.mockResolvedValue({ isDirectory: () => true })
mockFileExists.mockResolvedValue(true)
mockReadFile.mockResolvedValue(`---${language}\n${metadata}\n---\nInstructions`)
await skillsManager.discoverSkills()
expect(skillsManager.getSkillsMetadata().map((skill) => skill.name)).toEqual(["example"])
expect((await skillsManager.getSkillContent("example"))?.instructions).toBe("Instructions")
await skillsManager.updateSkillModes("example", "project", ["code"])
expect(mockWriteFile).toHaveBeenCalledWith(
p(projectSkillsDir, "example", "SKILL.md"),
expect.stringContaining("modeSlugs:"),
"utf-8",
)
},
)

describe("discoverSkills", () => {
it("should discover skills from global directory", async () => {
Expand Down
Loading