@ikie-dev/cli 9.8.7 → 9.9.1

package/src/extensions/skills-manager/skill-sanitizer.ts

@@ -0,0 +1,269 @@
+import { createHash } from "node:crypto"
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, extname, join } from "node:path"
+import { parse as parseYaml } from "yaml"
+
+/**
+ * Shared skill-name sanitizer for ikie.
+ *
+ * Mirrors the Agent Skills spec used by `@earendil-works/pi-coding-agent`:
+ *   - lowercase a-z, digits, hyphens only
+ *   - no leading/trailing hyphens
+ *   - no consecutive hyphens
+ *   - max 64 characters
+ */
+
+const MAX_NAME_LENGTH = 64
+const VALID_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/
+
+/**
+ * Normalize a raw skill name to a valid Agent Skills name.
+ * - lower-case
+ * - replace runs of invalid characters with a single hyphen
+ * - trim leading/trailing hyphens
+ * - truncate to 64 characters
+ * - fall back to `"skill"` if the result would be empty
+ */
+export function normalizeSkillName(raw: string): string {
+	const normalized = raw
+		.toLowerCase()
+		.replace(/[^a-z0-9-]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, MAX_NAME_LENGTH)
+		.replace(/^-+|-+$/g, "")
+
+	return normalized.length > 0 ? normalized : "skill"
+}
+
+/**
+ * True iff `name` is a valid Agent Skills name (matches the upstream regex and length limit).
+ */
+export function isValidSkillName(name: string): boolean {
+	if (typeof name !== "string") return false
+	if (name.length === 0 || name.length > MAX_NAME_LENGTH) return false
+	return VALID_NAME_RE.test(name)
+}
+
+/**
+ * Sanitize the frontmatter `name` field of a skill markdown file in-place.
+ *
+ * - If the content does not start with `---` frontmatter, return as-is.
+ * - Parse the frontmatter YAML and read the `name` field.
+ * - If `name` is missing or already valid, return the original content unchanged.
+ * - If `name` is invalid, rewrite the first top-level `name:` line to
+ *   `name: <normalized>` (the normalized value is JSON-quoted).
+ * - If frontmatter parsing fails, return the original content unchanged.
+ */
+export function sanitizeSkillMarkdown(content: string): string {
+	const match = FRONTMATTER_REGEX.exec(content)
+	if (!match) return content
+
+	const frontmatter = match[1]
+	const fmStart = match.index ?? 0
+	const fmEnd = fmStart + match[0].length
+
+	let parsed: unknown
+	try {
+		parsed = parseYaml(frontmatter)
+	} catch {
+		return content
+	}
+
+	if (typeof parsed !== "object" || parsed === null) {
+		return content
+	}
+
+	const record = parsed as Record<string, unknown>
+	const rawName = record.name
+	if (typeof rawName !== "string" || rawName.length === 0) {
+		return content
+	}
+	if (isValidSkillName(rawName)) {
+		return content
+	}
+
+	const normalized = normalizeSkillName(rawName)
+	const replacement = `name: ${JSON.stringify(normalized)}`
+
+	// match[1] is the inner frontmatter text between the two `---` markers.
+	// Its offset within `content` is right after the opening `---` line.
+	const openingPrefix = content.slice(fmStart, fmStart + 4) // "---\n" or "---\r\n"
+	const innerStart = fmStart + openingPrefix.length
+	const innerEnd = innerStart + match[1].length
+
+	const inner = content.slice(innerStart, innerEnd)
+	const lines = inner.split("\n")
+	let replaced = false
+	const newLines = lines.map((line) => {
+		if (replaced) return line
+		// Match top-level "name:" key (no leading whitespace).
+		if (/^name:\s*/.test(line)) {
+			replaced = true
+			return replacement
+		}
+		return line
+	})
+
+	if (!replaced) {
+		// No top-level `name:` line was found; insert one at the top of the frontmatter.
+		newLines.unshift(replacement)
+	}
+
+	const newInner = newLines.join("\n")
+	return content.slice(0, innerStart) + newInner + content.slice(innerEnd)
+}
+
+interface SkillSanitizer {
+	sanitizeDir(dir: string): string
+	sanitizePath(path: string): string
+	cleanup(): void
+}
+
+let cachedRoot: string | undefined
+let cleanupRegistered = false
+
+/**
+ * Create a process-lifetime skill sanitizer. It maintains a single temp
+ * directory and caches per-input sanitized copies so callers can re-use
+ * the result across invocations.
+ *
+ * The returned `sanitizeDir(dir)` copies `dir` (recursively) into the cache
+ * and rewrites every `SKILL.md` in place with `sanitizeSkillMarkdown`.
+ * The cached path is returned.
+ *
+ * `cleanup()` removes the temp directory; it is also registered as a
+ * process-exit handler on first invocation.
+ */
+export function createSkillSanitizer(): SkillSanitizer {
+	function getRoot(): string {
+		if (cachedRoot === undefined) {
+			cachedRoot = mkdtempSync(join(tmpdir(), "ikie-sanitized-skills-"))
+			if (!cleanupRegistered) {
+				cleanupRegistered = true
+				process.once("exit", () => {
+					if (cachedRoot) {
+						try {
+							rmSync(cachedRoot, { recursive: true, force: true })
+						} catch {
+							// best-effort cleanup
+						}
+					}
+				})
+			}
+		}
+		return cachedRoot
+	}
+
+	function sanitizeDir(dir: string): string {
+		const root = getRoot()
+		const key = createHash("sha256").update(dir).digest("hex").slice(0, 12)
+		const target = join(root, key)
+		rmSync(target, { recursive: true, force: true })
+		mkdirSync(target, { recursive: true })
+		cpSync(dir, target, { recursive: true, force: true })
+
+		rewriteSkillFiles(target)
+
+		return target
+	}
+
+	function sanitizePath(path: string): string {
+		if (!existsSync(path)) {
+			return path
+		}
+
+		try {
+			const stats = statSync(path)
+			if (stats.isDirectory()) {
+				return sanitizeDir(path)
+			}
+			if (stats.isFile() && extname(path).toLowerCase() === ".md") {
+				const root = getRoot()
+				const key = createHash("sha256").update(path).digest("hex").slice(0, 12)
+				const targetDir = join(root, key)
+				rmSync(targetDir, { recursive: true, force: true })
+				mkdirSync(targetDir, { recursive: true })
+
+				const stem = basename(path, ".md")
+				const skillDir = join(targetDir, stem)
+				mkdirSync(skillDir, { recursive: true })
+
+				const targetFile = join(skillDir, "SKILL.md")
+				const original = readFileSync(path, "utf-8")
+				const updated = sanitizeSkillMarkdown(original)
+				writeFileSync(targetFile, updated, "utf-8")
+
+				return skillDir
+			}
+		} catch {
+			// fall through to returning the original path
+		}
+
+		return path
+	}
+
+	function cleanup(): void {
+		if (cachedRoot !== undefined) {
+			try {
+				rmSync(cachedRoot, { recursive: true, force: true })
+			} catch {
+				// best-effort cleanup
+			}
+			cachedRoot = undefined
+		}
+	}
+
+	return { sanitizeDir, sanitizePath, cleanup }
+}
+
+function rewriteSkillFiles(dir: string): void {
+	let entries: import("node:fs").Dirent[]
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return
+	}
+
+	for (const entry of entries) {
+		const fullPath = join(dir, entry.name.toString())
+		if (entry.isDirectory()) {
+			rewriteSkillFiles(fullPath)
+			continue
+		}
+		const name = entry.name.toString()
+		if (entry.isFile() && name === "SKILL.md") {
+			try {
+				const original = readFileSync(fullPath, "utf-8")
+				const updated = sanitizeSkillMarkdown(original)
+				if (updated !== original) {
+					writeFileSync(fullPath, updated, "utf-8")
+				}
+			} catch {
+				// skip files we can't read/write
+			}
+		} else if (entry.isSymbolicLink() && name === "SKILL.md" && existsSync(fullPath)) {
+			try {
+				const original = readFileSync(fullPath, "utf-8")
+				const updated = sanitizeSkillMarkdown(original)
+				if (updated !== original) {
+					writeFileSync(fullPath, updated, "utf-8")
+				}
+			} catch {
+				// skip
+			}
+		}
+	}
+}

package/src/models.test.ts

@@ -190,7 +190,9 @@ describe("updateModelsConfig", () => {
 			json: async () => ({ models: [KIMI] }),
 		} as Response)
 
-		await updateModelsConfig(modelsJsonPath, "test-key", { endpoint: "https://custom.ikie.example/v1/chat/completions" })
+		await updateModelsConfig(modelsJsonPath, "test-key", {
+			endpoint: "https://custom.ikie.example/v1/chat/completions",
+		})
 
 		expect(fetch).toHaveBeenCalledWith(
 			"https://custom.ikie.example/models",

package/src/shared/planning/tool-catalog.test.ts

@@ -14,10 +14,20 @@ const namesOf = (entries: ToolEntry[]): string[] => entries.map((t) => t.name)
 const TODO_TOOL_NAMES = ["create_todos", "update_todos", "add_todo", "mark_todo", "clear_todos"]
 
 const TOOL_NAMES = {
-	sharedCore: ["read", "grep", "find", "ls", "web_fetch", "web_search", "mcp", ...TODO_TOOL_NAMES],
+	sharedCore: [
+		"read",
+		"grep",
+		"find",
+		"ls",
+		"web_fetch",
+		"web_search",
+		"mcp",
+		...TODO_TOOL_NAMES,
+		"set_phase",
+		"escalate_tools",
+	],
 	adhocOnly: ["questionnaire"],
 	fermentPlanningTools: [
-		"set_phase",
 		"propose_ferment_scoping",
 		"scope_ferment",
 		"update_ferment_scope_field",
@@ -44,7 +54,7 @@ const TOOL_NAMES = {
 
 describe("SHARED_CORE_TOOLS", () => {
 	it("contains the 6 read-only discovery tools, the mcp gateway, plus 5 todo lifecycle tools", () => {
-		expect(SHARED_CORE_TOOLS).toHaveLength(12)
+		expect(SHARED_CORE_TOOLS).toHaveLength(14)
 		for (const name of TOOL_NAMES.sharedCore) {
 			expect(SHARED_CORE_TOOLS).toContainEqual(expect.objectContaining({ name }))
 		}
@@ -60,7 +70,7 @@ describe("ADHOC_MODE_TOOLS", () => {
 	})
 
 	it("does not contain ferment-mode tools", () => {
-		const fermentTools = ["ask_user", "confirm_ferment_completion_criteria", "set_phase", "activate_ferment_phase"]
+		const fermentTools = ["ask_user", "confirm_ferment_completion_criteria", "activate_ferment_phase"]
 		for (const name of fermentTools) {
 			expect(namesOf(ADHOC_MODE_TOOLS)).not.toContain(name)
 		}
@@ -71,7 +81,6 @@ describe("FERMENT_MODE_TOOLS", () => {
 	const allNames = namesOf(FERMENT_MODE_TOOLS)
 
 	const expectedPlanningTools = [
-		"set_phase",
 		"propose_ferment_scoping",
 		"scope_ferment",
 		"update_ferment_scope_field",
@@ -116,7 +125,6 @@ describe("FERMENT_MODE_TOOLS", () => {
 		}
 
 		// planning-only
-		expect(byName("set_phase").phases).toEqual(["planning"])
 		expect(byName("propose_ferment_scoping").phases).toEqual(["planning"])
 		expect(byName("confirm_ferment_completion_criteria").phases).toEqual(["planning"])
 		expect(byName("activate_ferment_phase").phases).toEqual(["planning"])
@@ -156,7 +164,7 @@ describe("getToolsForProfile", () => {
 	describe("idle", () => {
 		it("returns only shared core tools", () => {
 			const result = getToolsForProfile("idle")
-			expect(result).toHaveLength(12)
+			expect(result).toHaveLength(14)
 			expect(namesOf(result)).toEqual(TOOL_NAMES.sharedCore)
 		})
 
@@ -205,7 +213,6 @@ describe("getToolsForProfile", () => {
 			const fermentOnly = [
 				"ask_user",
 				"confirm_ferment_completion_criteria",
-				"set_phase",
 				"propose_ferment_scoping",
 				"scope_ferment",
 				"activate_ferment_phase",

package/src/shared/planning/tool-catalog.ts

@@ -112,6 +112,10 @@ export const SHARED_CORE_TOOLS: ToolEntry[] = [
 	{ name: "add_todo", modes: ["shared"] },
 	{ name: "mark_todo", modes: ["shared"] },
 	{ name: "clear_todos", modes: ["shared"] },
+	// Phase tracker — always available so the agent can declare intent
+	{ name: "set_phase", modes: ["shared"] },
+	// Self-escalation — agent calls this when it needs write tools
+	{ name: "escalate_tools", modes: ["shared"] },
 ]
 
 /** Tools gated behind `--plan` (adhoc planning mode). */
@@ -134,9 +138,6 @@ export const ADHOC_MODE_TOOLS: ToolEntry[] = [
 export const FERMENT_MODE_TOOLS: ToolEntry[] = [
 	// -- planning phase (before any phase is activated) --
 
-	// Phase tracker injected by the ferment planner supplement
-	{ name: "set_phase", modes: ["ferment"], phases: ["planning"] },
-
 	// Draft scoping surface
 	{ name: "propose_ferment_scoping", modes: ["ferment"], phases: ["planning"] },
 	{ name: "scope_ferment", modes: ["ferment"], phases: ["planning"] },