// The extension catalog WRITES (CV22.DS7.TS4 plateau 5). // // Port of `sync_extensions_for_runtime`, `install_extension`, // `uninstall_extension`, `expose_claude_runtime_skills`, and // `cleanup_claude_runtime_skills` from `src/memory/cli/extensions.py`. // // These are the first commands in the family that touch the filesystem, and // the corpus grades them by what they LEAVE ON DISK -- every file in the mirror // home, the runtime target root, and the Claude project root -- not by what // they print. Four measured facts shape the port: // // 1. **The catalog is written with Python's `json.dumps(doc, indent=2)`, so // non-ASCII is ESCAPED.** A summary reading `Café notes — a fixture` lands // as `Caf\u00e9 notes \u2014 a fixture`. `JSON.stringify` would write raw // UTF-8 and silently change a file both cores read. And the key order is // insertion order, not sorted. // 2. **A Claude command name contains `:`, which is illegal on Windows**, so // filesystem names go through `filesystemSkillDirName` while the CATALOG // keeps the runtime command unchanged. `ext:notes` lives in `ext-notes/`. // 3. **Install identifies an extension by its DIRECTORY NAME**, never by the // manifest id. An extension in `ext-mismatch/` whose manifest says // `id: mismatch` has its migrations checked against the prefix // `ext_ext_mismatch_` and fails. Reading the id from the manifest would // "fix" a behavior the installed world depends on. // 4. **Install rebuilds each runtime catalog from EVERY installed // extension**, not from the one being installed, while the printed report // stays focused on that one. Feeding the writer a single manifest would // drop every other extension from the catalog Pi and Claude discover // through, leaving their SKILL.md files orphaned on disk. import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs"; import { basename, dirname, join } from "node:path"; import type { WritableDatabase } from "#db/database.ts"; import { PROGRAM } from "#util/program.ts"; import { pythonJsonDumpsIndentedOrdered } from "#util/pyGenerators.ts"; import type { BindingDeps } from "./bindings.ts"; import { discoverExtensions, extensionsRootForHome, type RenderedCommand, runtimeSkillsRootForHome, } from "./catalog.ts"; import { readProvidersWithoutRuntime } from "./contextRuntime.ts"; import { readSubcommandListing } from "./dispatch.ts"; import { ExtensionError, ExtensionValidationError } from "./errors.ts"; import { type ExtensionManifest, loadExtensionManifest } from "./manifest.ts"; import { runMigrations } from "./migrations.ts"; import { extensionSettingsPath } from "./settings.ts"; /** Port of `_COPY_IGNORE_PATTERNS`: never shipped inside an installed tree. */ const COPY_IGNORE_EXACT = new Set([ ".git", "__pycache__", ".venv", ".pytest_cache", ".ruff_cache", ".mypy_cache", "node_modules", ".DS_Store", ]); const COPY_IGNORE_SUFFIX = ".pyc"; // A port of Python's `re.sub(r'[<>:"/\\|?*\x00-\x1f]', '-', ...)`, the rule that // keeps a runtime command name legal as a Windows path segment. Dropping the // control range would let a control character reach a directory name and // diverge from the oracle on the one platform this guard exists for. // biome-ignore lint/suspicious/noControlCharactersInRegex: the control range is the ported rule const ILLEGAL_PATH_CHARACTERS = /[<>:"/\\|?*\u0000-\u001f]/g; export interface CatalogEntry { id: string; name: string; category: string; kind: string; summary: string; runtime: string; command_name: string; source_extension_dir: string; manifest_path: string; source_skill_path: string; installed_skill_path: string; } /** Port of `_filesystem_skill_dir_name`. */ export function filesystemSkillDirName(commandName: string): string { const safe = pyStripSpacesAndDots(commandName.replace(ILLEGAL_PATH_CHARACTERS, "-")); return safe || "extension"; } /** Python's `str.strip(" .")`: both ends, any mix of the two characters. */ function pyStripSpacesAndDots(text: string): string { return text.replace(/^[ .]+/, "").replace(/[ .]+$/, ""); } /** Port of `_legacy_filesystem_skill_dir_names`. */ export function legacyFilesystemSkillDirNames(commandName: string): string[] { const safe = filesystemSkillDirName(commandName); return commandName === safe ? [] : [commandName]; } /** Port of `_skill_markdown_declares_command`. */ function skillMarkdownDeclaresCommand(skillPath: string, commandName: string): boolean { let content: string; try { content = readFileSync(skillPath, "utf8"); } catch { return false; } const names = new Set([commandName, filesystemSkillDirName(commandName)]); for (const name of names) { for (const marker of [`name: "${name}"`, `name: '${name}'`, `name: ${name}`]) { if (content.includes(marker)) return true; } } return false; } /** * Port of `_remove_legacy_skill_dir_if_owned`. * * Deliberately conservative, and the conservatism is the point: it deletes a * directory named after the raw command only when the SKILL.md inside declares * that same command. A `ext:notes/` directory a human wrote for something else * is left alone. */ export function removeLegacySkillDirIfOwned(root: string, commandName: string): string[] { const removed: string[] = []; for (const legacyName of legacyFilesystemSkillDirNames(commandName)) { const legacyDir = join(root, legacyName); if (!isDirectory(legacyDir)) continue; if (!skillMarkdownDeclaresCommand(join(legacyDir, "SKILL.md"), commandName)) continue; rmSync(legacyDir, { recursive: true, force: true }); removed.push(legacyDir); } return removed; } function isDirectory(path: string): boolean { try { return lstatSync(path).isDirectory(); } catch { return false; } } /** Port of `_catalog_entry_for_manifest`. */ function catalogEntryForManifest( manifest: ExtensionManifest, runtime: string, targetSkillPath: string, ): CatalogEntry { const runtimeData = manifest.runtimes[runtime]; return { id: manifest.id, name: manifest.name, category: manifest.category, kind: manifest.kind, summary: manifest.summary, runtime, command_name: runtimeData?.commandName ?? "", source_extension_dir: manifest.root, manifest_path: manifest.manifestPath, source_skill_path: runtimeData?.skillPath ?? "", installed_skill_path: targetSkillPath, }; } /** Port of `_write_catalog` + `_catalog_document`. */ function writeCatalog( path: string, runtime: string, targetRoot: string, items: readonly CatalogEntry[], deps: BindingDeps, ): void { mkdirSync(dirname(path), { recursive: true }); const document = { schema_version: "1", runtime, target_root: targetRoot, generated_at: deps.nowIso(), extensions: items, }; writeFileSync(path, `${pythonJsonDumpsIndentedOrdered(document)}\n`, "utf8"); } /** Port of `_load_catalog`: a missing or corrupt catalog is an EMPTY one. */ function loadCatalogItems(path: string): unknown[] { if (!existsSync(path)) return []; let data: unknown; try { data = JSON.parse(readFileSync(path, "utf8")); } catch { return []; } if (Array.isArray(data)) return data; if (typeof data !== "object" || data === null) return []; const extensions = (data as Record).extensions; return Array.isArray(extensions) ? extensions : []; } /** Port of `_prune_catalog_for_extension`. */ function pruneCatalogForExtension( catalogPath: string, extensionId: string, runtime: string, targetRoot: string, deps: BindingDeps, ): void { const items = loadCatalogItems(catalogPath).filter( (item) => typeof item === "object" && item !== null && !Array.isArray(item) && (item as Record).id !== extensionId, ) as CatalogEntry[]; writeCatalog(catalogPath, runtime, targetRoot, items, deps); } /** Port of `sync_extensions_for_runtime`. */ export function syncExtensionsForRuntime( manifests: readonly ExtensionManifest[], runtime: string, targetRoot: string, deps: BindingDeps, ): CatalogEntry[] { mkdirSync(targetRoot, { recursive: true }); const synced: CatalogEntry[] = []; for (const manifest of manifests) { const runtimeData = manifest.runtimes[runtime]; if (!runtimeData) continue; const skillPath = runtimeData.skillPath; if (!skillPath) continue; const commandName = runtimeData.commandName; const targetDir = join(targetRoot, filesystemSkillDirName(commandName)); mkdirSync(targetDir, { recursive: true }); const targetSkillPath = join(targetDir, "SKILL.md"); copyFileSync(skillPath, targetSkillPath); removeLegacySkillDirIfOwned(targetRoot, commandName); synced.push(catalogEntryForManifest(manifest, runtime, targetSkillPath)); } writeCatalog(join(targetRoot, "extensions.json"), runtime, targetRoot, synced, deps); return synced; } /** * Port of `_should_copy_source_tree`. * * The symlink branch is a refusal, not an optimization: the production layout * links an installed extension straight at its source repository, and * `copytree(dirs_exist_ok=True)` writes THROUGH such a link, mutating a * directory the user never asked to change. */ export function shouldCopySourceTree(sourceDir: string, targetDir: string): boolean { if (existsSync(targetDir) && realpathSync(sourceDir) === realpathSync(targetDir)) return false; if (isSymlink(targetDir)) { throw new ExtensionValidationError( `installed extension path is a symlink pointing outside the install ` + `source: ${targetDir} -> ${realpathSync(targetDir)}. Refusing to install ` + `through it, which would modify the link target. Remove the symlink ` + `first, or run \`${PROGRAM} ext ${basename(targetDir)} migrate\` to ` + `re-run migrations without copying.`, ); } return true; } function isSymlink(path: string): boolean { try { return lstatSync(path).isSymbolicLink(); } catch { return false; } } /** Port of `shutil.copytree(..., ignore=ignore_patterns(*_COPY_IGNORE_PATTERNS))`. */ function copyTreeIgnoring(sourceDir: string, targetDir: string): void { cpSync(sourceDir, targetDir, { recursive: true, force: true, filter: (source) => { const name = basename(source); return !COPY_IGNORE_EXACT.has(name) && !name.endsWith(COPY_IGNORE_SUFFIX); }, }); } export interface InstallReport { extensionId: string; sourceDir: string; installedDir: string; synced: Array; migrationsApplied: number; /** * Capabilities the manifest documents but declares no runtime for. * * Install SUCCEEDS with these present. A skill-only extension, or one being * migrated a capability at a time, is legal -- refusing here would block the * very incremental migration CV22.DS10.TS2 exists to enable. The report says * so out loud instead, because the alternative is a user discovering it at * the first refusal a week later. */ unmigrated: string[]; } export interface InstallOptions { extensionId: string; sourceRoot: string; mirrorHome: string; runtime: string | null; db: WritableDatabase; deps: BindingDeps; } /** Port of `install_extension` + `_post_install_command_skill`. */ export function installExtension(options: InstallOptions): InstallReport { const { extensionId, mirrorHome, deps } = options; const sourceDir = join(options.sourceRoot, extensionId); loadExtensionManifest(sourceDir); const targetExtensionsRoot = extensionsRootForHome(mirrorHome); const targetExtensionDir = join(targetExtensionsRoot, extensionId); mkdirSync(targetExtensionsRoot, { recursive: true }); if (shouldCopySourceTree(sourceDir, targetExtensionDir)) { copyTreeIgnoring(sourceDir, targetExtensionDir); } const installedManifest = loadExtensionManifest(targetExtensionDir); const runtimes = options.runtime !== null ? [options.runtime] : Object.keys(installedManifest.runtimes).sort(); // A prompt-skill has no Python at all: no migrations, no register. let migrationsApplied = 0; if (installedManifest.kind === "command-skill") { try { migrationsApplied = runMigrations( options.db, extensionId, join(targetExtensionDir, "migrations"), deps, ); } catch (error) { if (!(error instanceof ExtensionError)) throw error; throw new ExtensionValidationError( `migrations failed for extension/${extensionId}: ${error.message}`, ); } } // Fact 4: rebuild from everything installed, report only this one. const installed = discoverExtensions(targetExtensionsRoot).manifests; const synced: Array = []; for (const runtimeName of runtimes) { const runtimeTargetRoot = runtimeSkillsRootForHome(mirrorHome, runtimeName); const all = syncExtensionsForRuntime(installed, runtimeName, runtimeTargetRoot, deps); synced.push([runtimeName, all.filter((entry) => entry.id === extensionId)] as const); } return { extensionId, sourceDir, installedDir: targetExtensionDir, synced, migrationsApplied, unmigrated: unmigratedCapabilities(targetExtensionDir), }; } /** * What still needs a runtime, in one list, labelled by kind. * * Each module reads its own manifest section -- `dispatch` owns * `cli.subcommands[]`, `contextRuntime` owns `mirror_context_providers[]` -- * and install merely composes them. Putting a second manifest parser here is * how the three readers would drift. */ function unmigratedCapabilities(extensionDir: string): string[] { const subcommands = readSubcommandListing(extensionDir) .filter((entry) => !entry.hasRuntime) .map((entry) => `subcommand '${entry.name}'`); const providers = readProvidersWithoutRuntime(extensionDir).map( (id) => `context provider '${id}'`, ); return [...subcommands, ...providers]; } export interface UninstallReport { extensionId: string; installedDir: string; bindingsRemoved: number; removed: Array; sourceRemoved: boolean; /** * The settings file (CR145) a full uninstall found and left in place, or * null. Kept on purpose -- deleting configuration a person wrote is the * worse surprise -- and named on purpose: a credential that outlives the * extension it served must not be silent. */ settingsKept: string | null; } /** Port of `uninstall_extension`. */ export function uninstallExtension(options: { extensionId: string; mirrorHome: string; runtime: string | null; db: WritableDatabase; deps: BindingDeps; }): UninstallReport { const { extensionId, mirrorHome, deps } = options; const installedDir = join(extensionsRootForHome(mirrorHome), extensionId); if (!existsSync(installedDir)) { throw new ExtensionValidationError(`installed extension not found: ${installedDir}`); } const manifest = loadExtensionManifest(installedDir); const runtimes = options.runtime !== null ? [options.runtime] : Object.keys(manifest.runtimes).sort(); const removed: Array = []; for (const runtimeName of runtimes) { const runtimeData = manifest.runtimes[runtimeName]; if (!runtimeData) { removed.push([runtimeName, []] as const); continue; } const runtimeRoot = runtimeSkillsRootForHome(mirrorHome, runtimeName); const commandName = runtimeData.commandName; const targetDirs = [ join(runtimeRoot, filesystemSkillDirName(commandName)), ...legacyFilesystemSkillDirNames(commandName).map((name) => join(runtimeRoot, name)), ]; const removedPaths: string[] = []; for (const targetDir of targetDirs) { if (!existsSync(targetDir)) continue; rmSync(targetDir, { recursive: true, force: true }); removedPaths.push(targetDir); } pruneCatalogForExtension( join(runtimeRoot, "extensions.json"), extensionId, runtimeName, runtimeRoot, deps, ); removed.push([runtimeName, removedPaths] as const); } // D4: the code goes, the DATA stays. Bindings cannot resolve without the // source tree, so they are deleted; the extension's own `ext__*` tables // are deliberately preserved for a future purge command to decide about. let bindingsRemoved = 0; if (options.runtime === null) { if (manifest.kind === "command-skill") { const result = options.db .prepare("DELETE FROM _ext_bindings WHERE extension_id = ?") .run(extensionId); bindingsRemoved = Number(result.changes) || 0; } rmSync(installedDir, { recursive: true, force: true }); } const settingsPath = extensionSettingsPath(mirrorHome, extensionId); const settingsKept = options.runtime === null && existsSync(settingsPath) ? settingsPath : null; return { extensionId, installedDir, bindingsRemoved, removed, sourceRemoved: options.runtime === null, settingsKept, }; } export interface ClaudeCleanupReport { projectRoot: string; claudeSkillsRoot: string; overlayCatalogPath: string; removed: string[]; } export interface ClaudeExposeReport extends ClaudeCleanupReport { exposed: Array<{ commandName: string; sourceSkillPath: string; targetSkillPath: string }>; } function claudeSkillsRootFor(projectRoot: string): string { return join(projectRoot, ".claude", "skills"); } /** Port of `_load_claude_overlay_catalog`: a LIST, or nothing. */ function loadOverlayCatalog(path: string): unknown[] { if (!existsSync(path)) return []; try { const data = JSON.parse(readFileSync(path, "utf8")); return Array.isArray(data) ? data : []; } catch { return []; } } /** Port of `cleanup_claude_runtime_skills`. */ export function cleanupClaudeRuntimeSkills(projectRoot: string): ClaudeCleanupReport { const claudeSkillsRoot = claudeSkillsRootFor(projectRoot); const overlayCatalogPath = join(claudeSkillsRoot, "extensions.external.json"); const removed: string[] = []; for (const item of loadOverlayCatalog(overlayCatalogPath)) { if (typeof item !== "object" || item === null || Array.isArray(item)) continue; const targetSkillPath = (item as Record).target_skill_path; if (typeof targetSkillPath !== "string") continue; if (existsSync(targetSkillPath)) { rmSync(targetSkillPath); removed.push(targetSkillPath); } // Only an EMPTY parent is removed: a directory holding anything else is // not ours to delete. const parent = dirname(targetSkillPath); if (existsSync(parent) && readdirSync(parent).length === 0) rmSync(parent, { recursive: true }); } if (existsSync(overlayCatalogPath)) rmSync(overlayCatalogPath); return { projectRoot, claudeSkillsRoot, overlayCatalogPath, removed }; } /** Port of `expose_claude_runtime_skills`. */ export function exposeClaudeRuntimeSkills( projectRoot: string, catalog: { extensions: unknown[] }, ): ClaudeExposeReport { const claudeSkillsRoot = claudeSkillsRootFor(projectRoot); mkdirSync(claudeSkillsRoot, { recursive: true }); const cleanup = cleanupClaudeRuntimeSkills(projectRoot); const exposed: ClaudeExposeReport["exposed"] = []; for (const item of catalog.extensions) { if (typeof item !== "object" || item === null || Array.isArray(item)) continue; const record = item as Record; const commandName = record.command_name; const installedSkillPath = record.installed_skill_path; if (typeof commandName !== "string" || typeof installedSkillPath !== "string") continue; if (!existsSync(installedSkillPath)) continue; const targetDir = join(claudeSkillsRoot, filesystemSkillDirName(commandName)); mkdirSync(targetDir, { recursive: true }); const targetSkillPath = join(targetDir, "SKILL.md"); copyFileSync(installedSkillPath, targetSkillPath); cleanup.removed.push(...removeLegacySkillDirIfOwned(claudeSkillsRoot, commandName)); exposed.push({ commandName, sourceSkillPath: installedSkillPath, targetSkillPath }); } const overlayCatalogPath = join(claudeSkillsRoot, "extensions.external.json"); writeFileSync( overlayCatalogPath, `${pythonJsonDumpsIndentedOrdered( exposed.map((entry) => ({ command_name: entry.commandName, source_skill_path: entry.sourceSkillPath, target_skill_path: entry.targetSkillPath, })), )}\n`, "utf8", ); return { projectRoot, claudeSkillsRoot, overlayCatalogPath, removed: cleanup.removed, exposed, }; } /** Port of `load_runtime_catalog`: the STRICT reader, which refuses. */ export function loadRuntimeCatalog(runtime: string, mirrorHome: string): { extensions: unknown[] } { const catalogPath = join(runtimeSkillsRootForHome(mirrorHome, runtime), "extensions.json"); if (!existsSync(catalogPath)) { throw new ExtensionValidationError(`runtime catalog not found: ${catalogPath}`); } let parsed: unknown = {}; try { parsed = JSON.parse(readFileSync(catalogPath, "utf8")); } catch { parsed = { schema_version: "1", extensions: [] }; } const catalog = ( Array.isArray(parsed) ? { schema_version: "0", extensions: parsed } : typeof parsed === "object" && parsed !== null ? (parsed as Record) : { schema_version: "1", extensions: [] } ) as Record; if (catalog.schema_version !== "1") { throw new ExtensionValidationError( `unsupported runtime catalog schema '${String(catalog.schema_version)}' in ${catalogPath}`, ); } if (catalog.runtime !== runtime) { throw new ExtensionValidationError( `runtime catalog ${catalogPath} does not match runtime '${runtime}'`, ); } if (!Array.isArray(catalog.extensions)) { throw new ExtensionValidationError( `invalid runtime catalog extensions payload in ${catalogPath}`, ); } return { extensions: catalog.extensions }; } /** The `install` report, in Python's print order. */ export function renderInstallReport(report: InstallReport): RenderedCommand { const lines = [ `Installed extension/${report.extensionId}`, ` source: ${report.sourceDir}`, ` installed: ${report.installedDir}`, ]; for (const [runtimeName, items] of report.synced) { lines.push(` runtime ${runtimeName}:`); for (const item of items) { lines.push(` ${item.command_name} -> ${item.installed_skill_path}`); } } // On stderr, not stdout: the install SUCCEEDED, and a warning must not land // in the bytes a caller parses as the install report. const stderr = report.unmigrated.length === 0 ? "" : [ `Warning: extension/${report.extensionId} declares no runtime for ` + `${report.unmigrated.length} capability(ies):`, ...report.unmigrated.map((entry) => ` ${entry}`), "These will refuse until they declare a runtime. " + "See docs/releases/pending-cutoffs.md.", "", ].join("\n"); return { stdout: `${lines.join("\n")}\n`, stderr, exitCode: 0 }; } /** The `uninstall` report, in Python's print order. */ export function renderUninstallReport(report: UninstallReport): RenderedCommand { const lines = [ `Uninstalled extension/${report.extensionId}`, ` installed: ${report.installedDir}`, ]; if (report.sourceRemoved) lines.push(" source tree: removed"); if (report.settingsKept !== null) lines.push(` settings left in place: ${report.settingsKept}`); if (report.bindingsRemoved) { lines.push(` bindings: ${report.bindingsRemoved} row(s) removed`); } for (const [runtimeName, items] of report.removed) { lines.push(` runtime ${runtimeName}:`); for (const item of items) lines.push(` removed ${item}`); } return { stdout: `${lines.join("\n")}\n`, stderr: "", exitCode: 0 }; }