@namzu/sdk 44.3.0 → 45.1.0

package/src/utils/frontmatter.ts

@@ -117,6 +117,36 @@ export type FrontmatterValue =
 	| { readonly kind: 'scalar'; readonly value: string }
 	| { readonly kind: 'mapping'; readonly entries: Readonly<Record<string, string>> }
 
+/** What a caller lets {@link parseFrontmatter} accept beyond flat scalars. */
+export interface FrontmatterOptions {
+	/**
+	 * Keys that may be written as a YAML list — a block sequence (`- item`
+	 * lines) or a flow sequence (`[a, b]`) — and come back as ONE scalar, the
+	 * items joined with `", "`.
+	 *
+	 * Opt-in per key, because a list is refused everywhere else for a reason:
+	 * a key the caller reads as a scalar would otherwise come back absent. A
+	 * caller names a key here only when a comma-separated scalar is already
+	 * a spelling it reads, so the joined value means what the list did.
+	 * `allowed-tools` is the case: the Agent Skills format writes it either
+	 * way.
+	 */
+	readonly lists?: readonly string[]
+	/**
+	 * The keys the caller reads. When given, a top-level key it answers
+	 * `false` for is skipped whole — its value and every indented line under
+	 * it — and does not appear in the result.
+	 *
+	 * The refusals in {@link UNSUPPORTED_YAML} exist so a value the caller
+	 * USES is never read wrongly. A key nobody reads cannot be read wrongly,
+	 * and refusing the whole file over it made a skill written for another
+	 * tool (`argument-hint: [file]`, a `hooks:` block with a list in it)
+	 * unusable here for the sake of a field this kernel ignores. Absent, every
+	 * key is parsed and refused exactly as before.
+	 */
+	readonly readsKey?: (key: string) => boolean
+}
+
 export interface ParsedFrontmatter {
 	/**
 	 * Every top-level key, in the order the file declared it.
@@ -136,17 +166,26 @@ export interface ParsedFrontmatter {
 	readonly body: string
 }
 
+/** Optional behaviour for {@link parseFrontmatter}: the same as {@link FrontmatterOptions}. */
+export type ParseFrontmatterOptions = FrontmatterOptions
+
 /**
  * Parse a markdown file's `---` frontmatter.
  *
  * @param raw The file's full contents. LF and CRLF both parse.
  * @param source A label for error messages — a path, or a phrase naming the
  *   file. Used verbatim, so the caller controls how its own errors read.
+ * @param options See {@link FrontmatterOptions}.
  * @throws If the frontmatter is absent, unclosed, or uses YAML this reader
- *   does not implement. It never returns a partial or empty result to stand in
- *   for a file it could not read.
+ *   does not implement in a key the caller reads. It never returns a partial
+ *   or empty result to stand in for a file it could not read.
  */
-export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter {
+export function parseFrontmatter(
+	raw: string,
+	source: string,
+	options: FrontmatterOptions = {},
+): ParsedFrontmatter {
+	const listKeys = new Set(options.lists ?? [])
 	const trimmed = raw.trimStart()
 
 	if (!trimmed.startsWith(FRONTMATTER_DELIMITER)) {
@@ -174,15 +213,20 @@ export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter
 	// round trip is safe at both ends.
 	const data = new Map<string, string>()
 	const blocks = new Map<string, Map<string, string>>()
+	const lists = new Map<string, string[]>()
 	let currentKey: string | undefined
+	// The current top-level key is one the caller does not read: its value
+	// and its indented lines are skipped rather than parsed or refused.
+	let skipping = false
 
 	for (const line of frontmatterRaw.split(LINE_SPLIT)) {
 		if (!line.trim() || line.trimStart().startsWith('#')) continue
 
 		if (/^\s/.test(line)) {
-			if (!currentKey) continue
+			if (!currentKey || skipping) continue
 
-			// A block sequence item. Refused, not skipped.
+			// A block sequence item. Read as a list when the caller named this
+			// key in `options.lists`; refused, not skipped, everywhere else.
 			//
 			// These lines carry no `:`, so the `continue` below used to drop them
 			// and the key — having no scalar value and no mapping entries — came
@@ -195,6 +239,18 @@ export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter
 			// and silently did not get it is indistinguishable from one that never
 			// asked. A capability quietly not granted is the worst thing this
 			// reader can produce.
+			if (listKeys.has(currentKey) && !data.has(currentKey) && /^\s*-(\s|$)/.test(line)) {
+				const item = normalizeScalar(line.replace(/^\s*-/, ''))
+				if (item) {
+					let list = lists.get(currentKey)
+					if (!list) {
+						list = []
+						lists.set(currentKey, list)
+					}
+					list.push(item)
+				}
+				continue
+			}
 			if (/^\s*-\s/.test(line)) {
 				throw new Error(
 					`${source}: "${currentKey}" uses a block sequence (a "- " list), which this reader does not support. Write it as a single-line value instead. Refusing rather than reading "${currentKey}" as absent, which is what silently dropping the list would mean.`,
@@ -218,8 +274,25 @@ export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter
 		const colonIdx = line.indexOf(':')
 		if (colonIdx === -1) continue
 		const key = line.slice(0, colonIdx).trim()
+		if (options.readsKey && !options.readsKey(key)) {
+			currentKey = key
+			skipping = true
+			continue
+		}
+		skipping = false
 		const value = normalizeScalar(line.slice(colonIdx + 1))
 
+		if (listKeys.has(key) && /^\[.*\]$/.test(value)) {
+			currentKey = key
+			const items = value
+				.slice(1, -1)
+				.split(',')
+				.map(normalizeScalar)
+				.filter((item) => item.length > 0)
+			// `[]` is a list the author declared empty, which is not absence.
+			data.set(key, items.join(', '))
+			continue
+		}
 		assertReadableScalar(key, value, source)
 
 		currentKey = key
@@ -230,6 +303,9 @@ export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter
 	// that — so refusing here is what makes the illegal state unrepresentable
 	// in the returned type rather than merely undocumented. The alternative,
 	// picking a precedence, would silently drop half of what the author wrote.
+	for (const [key, items] of lists) {
+		if (!data.has(key)) data.set(key, items.join(', '))
+	}
 	for (const key of blocks.keys()) {
 		if (!data.has(key)) continue
 		throw new Error(

package/src/utils/id.ts

@@ -197,6 +197,20 @@ export function generateDeliverableId(): DeliverableId {
 	return generateId()
 }
 
+/**
+ * The id of a scheduled job, for a host that stores schedules (the CLI's
+ * `NAMZU_HOME/schedule/`). A plain UUIDv7 string: jobs are the host's records,
+ * not a kernel entity, so there is no branded kind for them.
+ */
+export function generateScheduleJobId(): string {
+	return uuidv7()
+}
+
+/** The id of one run of a scheduled job. See {@link generateScheduleJobId}. */
+export function generateScheduleRunId(): string {
+	return uuidv7()
+}
+
 /** Entity kinds are supplied by a typed field or storage collection. */
 export interface EntityIdByKind {
 	turn: TurnId