11 Commits
Author SHA1 Message Date
Willie 9c994faa17 fix(frontmatter): read and rewrite SKILL.md that starts with a UTF-8 BOM (#505)
* fix(frontmatter): read and rewrite SKILL.md that starts with a UTF-8 BOM

Windows editors such as Notepad write a BOM before the opening ---. The
lenient readers (ParseSkillName, ParseFrontmatterField/Fields/List, ReadSkillBody)
did not skip it, so under target_naming standard/prefixed the skill had no
readable name and was silently skipped. Strip the BOM in the shared frontmatter
locator and the line scanner, and in the hub, search, audit and sync/context
readers that split lines themselves (utils.TrimBOM).

The writers kept working on the unstripped text, so SetFrontmatterValue
prepended a second block and ToggleFrontmatterFlag/RewriteFrontmatterList
could leave a BOM in the middle of the file. They now split the BOM off and
put it back in front, rewriting only the name value (or flag/list) as before.

* fix(frontmatter): cover the dashboard parser and stop auditing a leading BOM

A consumer sweep after the first BOM commit found two more places that
mishandled a SKILL.md written by Notepad:

- audit reported the leading BOM as a HIGH hidden-unicode finding (U+FEFF is
  in the zero-width rule), so every such skill showed a risk score. A BOM at
  the very start of a file is its encoding mark and hides nothing; one past
  the start is still reported.
- the dashboard's parseSkillMarkdown saw no frontmatter, so the skill editor
  would treat the whole file as body and write a second block on save.

The audit-engine page and its four translations note the exemption.

* fix(ui): keep the BOM when the skill editor saves a SKILL.md

parseSkillMarkdown dropped the BOM so the editor could see the frontmatter,
but SkillEditor writes the composed text back through PUT .../content, so every
dashboard edit silently removed the marker from a Notepad-written file. The
parse result now carries the BOM and composeSkillMarkdown puts it back in front,
matching the Go rewrite paths.
2026-10-09 23:58:56 +08:00
Willie 4e850e5a3f fix(sync): decode the whole block when the name line is not a string
A multi-line quoted name such as "proto\ followed by an indented line
fails to decode alone, and the literal first line was returned, so the
skill was skipped. Decode the whole frontmatter whenever the name line
does not decode to a string; keep the literal only for frontmatter YAML
rejects.
2026-10-09 12:10:08 +08:00
Willie ca38177d25 fix(sync): decode the whole frontmatter when no plain name line is found
Each YAML form the line scanner did not know (explicit "? name" keys
this time, after aliases, merge keys and flow mappings) came back as an
empty name and the skill was skipped under standard and prefixed
naming. Keep the early stop for a plain name line and decode the whole
block otherwise, which also replaces the per-form special cases.
2026-10-09 12:03:11 +08:00
Willie 65f468c0fd fix(sync): resolve a skill name inherited through a YAML merge key
A name brought in by "<<: *defaults" has no literal top-level name line,
so ParseSkillName returned empty and naming validation skipped the
skill. When a merge key is present and no explicit name is found,
decode the whole block; an explicit name still wins.
2026-10-09 11:34:00 +08:00
Willie fae3439647 fix(sync): resolve a skill name given as a YAML alias
ParseSkillName decoded the name line alone, so "name: *anchor" lost the
anchor defined earlier and came back as the literal alias, which naming
validation rejected. Decode the whole frontmatter block for an alias.
2026-10-09 11:26:40 +08:00
Willie 04dacce117 fix(sync): read a block-scalar skill name
ParseSkillName stopped at "name: >-" and decoded only that header, so
the name was empty and the skill was skipped under standard and
prefixed naming. Keep reading the indented lines of a block scalar
before decoding it.
2026-10-09 11:07:11 +08:00
Willie c95e385698 fix(sync): read a skill's name from any valid YAML key form
Target naming resolution read name: by literal line prefix, so a quoted
key, "name :", a flow mapping or a trailing comment gave an empty or
wrong name and the skill was skipped under standard and prefixed naming;
an indented metadata.name could also win. Match only top-level keys,
decode the name line as YAML, and decode a flow mapping whole, while
still stopping at the name line.
2026-10-09 10:58:48 +08:00
Willie 279be8aba6 fix(utils): stream ParseSkillName and ParseFrontmatterField to their key
On main these two readers scanned SKILL.md line by line and returned at
the line they were looking for, keeping nothing. After the refactor they
first collected the whole frontmatter block, so a large block cost its
full size on every call even when name came first, and an unclosed one
cost the rest of the file. Sync, target naming and listing call them
once per skill or agent. Reported by Codex review on #457.

The per-line rule (which line opens and which closes the block) moves
into blockWalk, which locateFrontmatter and the new scanLenientBlock
both use, so the streaming path and the byte locator cannot drift.
ParseSkillName and ParseFrontmatterField stop at their key again; the
list and fields readers collect the block as they always did. Results
are unchanged for every entry point.

Refs #449
2026-10-07 00:34:47 +08:00
Willie 90f161fef0 perf(utils): keep only the frontmatter block when reading by path
Rebuilding the path readers on the shared locator made them read the
whole SKILL.md into memory, where they used to scan line by line and
stop at the closing delimiter. They run once per skill or agent during
sync and listing, so a large body, or a large file with no frontmatter
at all, now cost its full size on every call.

readHead goes back to a bufio.Scanner and keeps the lines from the
opening delimiter to the closing one, nothing before and nothing after.
Reading through the real Scanner also replaces the code that imitated
its quirks (64 KiB line cap, one \r dropped per line); ReadSkillBody,
which needs the body, takes them from scanLines. An unclosed block is
still kept to the end of the file, as the list and fields readers always
did.

Review follow-ups in the same files: RewriteFrontmatterList no longer
copies the content to a string and back, ParseFrontmatterField's two
loops no longer share an index, and the tests share one file helper.
Results are unchanged for every entry point.

Refs #449
2026-10-07 00:25:32 +08:00
Willie aeaa8337bc refactor(utils): locate frontmatter in one place under a named policy
Each reader in internal/utils found the --- delimiters with its own
loop, under four different rules that were only visible by reading all
of them, and the list reader existed twice with a path copy and a bytes
copy that had drifted apart. A fix to one reader, like the mcp serve
fixes to the strict one, did not reach the others, and nobody could say
which rule an entry point followed without tracing it.

locateFrontmatter now does the locating for every reader, and the rule
is a frontmatterPolicy value: strictBlock, lenientBlock, bodyBlock and
rewriteBlock name the rules that exist and the entry points that use
them. The rules themselves are not unified; every entry point returns
what it returned before, including the bufio.Scanner quirks of the
readers that take a path (a line of 64 KiB or more ends the content,
one \r is dropped per line), which now live in scannable. The strict
reader still walks only to the closing delimiter and copies nothing.

Two more cases found by comparing old and new code on random input are
pinned: a block scalar on the last frontmatter line, and \r\r\n endings.

Refs #449
2026-10-07 00:09:14 +08:00
Willie 8f2d4d12a7 test(utils): pin what each frontmatter entry point returns today
The readers in internal/utils locate the --- delimiters under different
rules, so the same SKILL.md can give different answers depending on the
entry point. Before they are rebuilt on one locator, these cases record
each entry point's current result on the inputs where the rules differ
(indented or late delimiters, unclosed and empty blocks, trailing
spaces, CRLF, BOM, delimiters in the body) and on a line longer than the
bufio.Scanner cap that the path readers silently stop at.

Refs #449
2026-10-06 23:59:56 +08:00