@hasna/skills 0.9.1 → 0.9.3

package/README.md

@@ -271,6 +271,15 @@ Vendor file restoration uses an exclusive hard link to preserve concurrent files
 Do not retry an interrupted operation until its journal and both paths have been
 reconciled; a failed final journal write may leave the earlier durable intent.
 
+For a reviewed migration that must retire one exact native copy, pass
+`--target-manifest <file>`. The JSON manifest uses schema
+`hasna.skills-native-migration-targets.v1` and binds each target to an agent,
+an existing absolute `projectRoot`, a normalized project-relative `path`, and
+the complete directory `treeSha256`. Exact-target mode refuses broad selector
+flags, protected or vendor entries, missing or ambiguous paths, symlinks,
+digest drift, and writes a manifest digest into the recovery journal. Every
+inventory entry outside the manifest remains untouched.
+
 `skills hook agents --json` reports the supported adapters and coverage limits.
 Claude and Codex have lifecycle context hooks; Gemini uses `BeforeAgent`, and
 OpenCode uses its awaited message plugin. Cursor receives selected context at
@@ -758,7 +767,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills sessions show <id> --json` | | Inspect one session's exact profile revision and receipt hash without loading payloads |
 | `skills sessions reconcile <id> --from-profile <id> --from-revision <rev> --receipt-sha256 <sha> --selection-profile <id> --profile-revision <rev>` | | Plan an explicit migration of one live session; `--apply --plan-digest <digest> --plan-issued-at <time> --plan-expires-at <time>` (within five minutes) preserves its old receipt and applies the reviewed replacement |
 | `skills hook agents --json` | | Report maintained adapters and explicit coverage limits |
-| `skills migrate native` | | Inventory native copies; `--apply` archives managed copies, with explicit `--include-unmanaged` and `--include-vendor` retirement options |
+| `skills migrate native` | | Inventory native copies; `--apply` archives managed copies, with explicit `--include-unmanaged`, `--include-vendor`, or reviewed `--target-manifest` selection |
 | `skills pull --all --selection-profile <id>` | | With CLI loading active, refresh the selected profile into the verified cache |
 | `skills sync --selection-profile <id> [--check] [--station <id>]` | | Sync or check the selected profile/cache; optionally record station state |
 | `skills station-state <id>` | | Read a station's sync receipt in the authenticated workspace |

package/bin/index.js

@@ -36868,7 +36868,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.9.1",
+    version: "0.9.3",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -36877,6 +36877,7 @@ var init_package = __esm(() => {
       "skills-serve": "bin/server.js",
       "skills-server": "bin/server.js",
       "skills-worker": "bin/worker.js",
+      "skills-maintenance": "bin/maintenance.js",
       "skills-migrate": "bin/migrate.js"
     },
     exports: {
@@ -36917,7 +36918,7 @@ var init_package = __esm(() => {
     types: "./dist/index.d.ts",
     scripts: {
       clean: "rm -rf bin/ dist/",
-      build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+      build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
       "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
       test: "bun test --timeout 30000",
       dev: "bun run ./src/cli/index.tsx",
@@ -55358,6 +55359,82 @@ function treeHash(root2) {
   visit2(root2);
   return hash2.digest("hex");
 }
+function parseNativeMigrationTargetManifest(input) {
+  const digest2 = sha(input);
+  let value;
+  try {
+    value = JSON.parse(input.toString());
+  } catch {
+    throw new Error("Invalid native migration target manifest JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid native migration target manifest");
+  const record2 = value;
+  if (record2.schema !== "hasna.skills-native-migration-targets.v1" || Object.keys(record2).some((key) => !["schema", "targets"].includes(key)))
+    throw new Error("Unsupported native migration target manifest schema");
+  if (!Array.isArray(record2.targets) || record2.targets.length === 0 || record2.targets.length > 1000)
+    throw new Error("Native migration target manifest must contain 1 to 1000 targets");
+  const targets = [];
+  const identities = new Set;
+  for (const target of record2.targets) {
+    if (!target || typeof target !== "object" || Array.isArray(target))
+      throw new Error("Invalid native migration target");
+    const item = target;
+    if (Object.keys(item).some((key) => !["agent", "projectRoot", "path", "treeSha256"].includes(key)) || typeof item.agent !== "string" || typeof item.projectRoot !== "string" || typeof item.path !== "string" || typeof item.treeSha256 !== "string")
+      throw new Error("Invalid native migration target fields");
+    if (!INTEGRATION_AGENTS.includes(item.agent))
+      throw new Error(`Unsupported native migration target agent: ${item.agent}`);
+    const projectRoot = resolve16(item.projectRoot);
+    if (!isAbsolute15(item.projectRoot) || projectRoot !== item.projectRoot || !existsSync15(projectRoot) || !lstatSync18(projectRoot).isDirectory())
+      throw new Error(`Native migration target project root must be an existing absolute directory: ${item.projectRoot}`);
+    assertSafePath(projectRoot);
+    if (isAbsolute15(item.path) || item.path.includes("\\") || item.path.length === 0 || item.path.includes("\x00"))
+      throw new Error(`Native migration target path must be normalized and project-relative: ${item.path}`);
+    const resolved = resolve16(projectRoot, item.path), normalized = relative5(projectRoot, resolved);
+    if (!normalized || normalized === ".." || normalized.startsWith(`..${sep6}`) || isAbsolute15(normalized) || normalized !== item.path)
+      throw new Error(`Native migration target path escapes or is not normalized: ${item.path}`);
+    if (!/^[0-9a-f]{64}$/.test(item.treeSha256))
+      throw new Error(`Invalid native migration tree digest for ${item.path}`);
+    const identity4 = `${item.agent}\x00${projectRoot}\x00${normalized}`;
+    if (identities.has(identity4))
+      throw new Error(`Duplicate native migration target: ${item.path}`);
+    identities.add(identity4);
+    targets.push({ agent: item.agent, projectRoot, path: normalized, treeSha256: item.treeSha256 });
+  }
+  return { schema: "hasna.skills-native-migration-targets.v1", targets, digest: digest2 };
+}
+function readNativeMigrationTargetManifest(path) {
+  return parseNativeMigrationTargetManifest(readNativeBytes(path, 4 * 1024 * 1024));
+}
+function selectNativeMigrationTargets(inventory, manifest) {
+  if (manifest.schema !== "hasna.skills-native-migration-targets.v1" || !/^[0-9a-f]{64}$/.test(manifest.digest) || !Array.isArray(manifest.targets) || manifest.targets.length === 0)
+    throw new Error("Invalid native migration target manifest");
+  const identities = new Set;
+  const selected = [];
+  for (const target of manifest.targets) {
+    const projectRoot = resolve16(target.projectRoot), normalized = relative5(projectRoot, resolve16(projectRoot, target.path));
+    if (!isAbsolute15(target.projectRoot) || projectRoot !== target.projectRoot || !existsSync15(projectRoot) || !lstatSync18(projectRoot).isDirectory())
+      throw new Error(`Native migration target project root must be an existing absolute directory: ${target.projectRoot}`);
+    assertSafePath(projectRoot);
+    if (isAbsolute15(target.path) || target.path.includes("\\") || target.path.includes("\x00") || !normalized || normalized === ".." || normalized.startsWith(`..${sep6}`) || normalized !== target.path || !/^[0-9a-f]{64}$/.test(target.treeSha256))
+      throw new Error(`Invalid native migration target: ${target.path}`);
+    const identity4 = `${target.agent}\x00${projectRoot}\x00${normalized}`;
+    if (identities.has(identity4))
+      throw new Error(`Duplicate native migration target: ${target.path}`);
+    identities.add(identity4);
+    const expected = resolve16(target.projectRoot, target.path);
+    const matches2 = inventory.filter((entry2) => entry2.agent === target.agent && resolve16(entry2.path) === expected);
+    if (matches2.length !== 1)
+      throw new Error(`Native migration target was not found exactly once: ${target.agent} ${target.projectRoot}/${target.path}`);
+    const entry = matches2[0];
+    if (entry.bridge || entry.system || entry.vendor)
+      throw new Error(`Native migration target is protected or vendor-owned: ${entry.path}`);
+    if (entry.hash !== target.treeSha256 || treeHash(entry.path) !== target.treeSha256)
+      throw new Error(`Native migration target changed after review: ${entry.path}`);
+    selected.push(entry);
+  }
+  return selected;
+}
 function projectAncestorDirectories(projects) {
   const directories = new Set;
   for (const project of projects) {
@@ -55375,10 +55452,12 @@ function projectAncestorDirectories(projects) {
 }
 function inventoryNativeSkills(home = homedir4(), options = {}) {
   const aliases = rootAliases(home, options.allowRootAliases);
-  const roots = ROOTS.map(([agent, path]) => [agent, canonicalAgentPath(join29(home, path), aliases)]);
+  const selectedAgents = options.agents ? new Set(options.agents) : undefined;
+  const rootDefinitions = selectedAgents ? ROOTS.filter(([agent, path]) => selectedAgents.has(agent) || selectedAgents.has("hermes") && agent === "codex" && path === ".agents/skills") : ROOTS;
+  const roots = rootDefinitions.map(([agent, path]) => [agent, canonicalAgentPath(join29(home, path), aliases)]);
   const bridgePaths = Object.values(AGENT_ADAPTERS).map((adapter) => canonicalAgentPath(join29(home, adapter.root, CLI_BRIDGE_NAME), aliases));
   for (const project of projectAncestorDirectories([...options.projectDirs ?? [], ...options.projectDir ? [options.projectDir] : []])) {
-    for (const [agent, path] of ROOTS)
+    for (const [agent, path] of rootDefinitions)
       roots.push([agent, canonicalAgentPath(join29(project, path), aliases)]);
   }
   const entries = [], seen = new Set;
@@ -55634,7 +55713,7 @@ function planAgentIntegration(options) {
     return [agent, { command, profileId: profileId2 }];
   }));
   const discoveries = [...new Set(options.agents)].map((agent) => resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, canonical: (path) => canonicalAgentPath(path, aliases) }));
-  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
+  const nativeSkills = inventoryNativeSkills(home, { includeVendor: true, guardHermes: options.agents.includes("hermes"), agents: options.agents, projectDir: options.projectDir, agentRoots: discoveries.flatMap((binding) => binding.roots.map((path) => ({ agent: binding.agent, path }))), allowRootAliases: options.allowRootAliases });
   const changes = [];
   for (const agent of [...new Set(options.agents)]) {
     if (!INTEGRATION_AGENTS.includes(agent))
@@ -55846,12 +55925,13 @@ function archiveNativeSkills(inventory, options) {
     if (!expected || treeHash(entry.path) !== entry.hash || !isOwnedCliBridge(entry.path, [expected]))
       throw new Error(`Skills bridge changed after planning: ${entry.path}`);
   }
-  const selected = inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
+  const selected = options.targetManifest ? selectNativeMigrationTargets(inventory, options.targetManifest) : inventory.filter((entry) => !entry.bridge && !entry.system && (entry.vendor ? options.includeVendor : entry.managed || options.includeUnmanaged));
   for (const entry of selected)
     if (treeHash(entry.path) !== entry.hash)
       throw new Error(`Native skill changed after planning: ${entry.path}`);
+  const targetManifest = options.targetManifest ? { schema: options.targetManifest.schema, digest: options.targetManifest.digest, targetCount: options.targetManifest.targets.length } : undefined;
   if (!selected.length)
-    return { entries: [], ...aliases.length ? { rootAliases: aliases } : {} };
+    return { entries: [], ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const operationId = randomUUID6(), archiveRoot = join29(options.dataDir ?? getDataDir(), "migration", operationId, "native"), receiptPath = join29(archiveRoot, "receipt.json");
   const entries = selected.map((entry, index) => ({
     source: entry.vendor ? join29(entry.path, "SKILL.md") : entry.path,
@@ -55860,7 +55940,7 @@ function archiveNativeSkills(inventory, options) {
     ...entry.vendor ? { discoveryOnly: true } : {},
     status: "planned"
   }));
-  const journal = { version: 2, operationId, status: "planned", entries, ...aliases.length ? { rootAliases: aliases } : {} };
+  const journal = { version: 2, operationId, status: "planned", entries, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
   const moved = [];
   const verifyArchive = (entry) => {
     assertSafePath(entry.archive);
@@ -55954,7 +56034,7 @@ function archiveNativeSkills(inventory, options) {
     } catch {}
     throw new Error(`Native archive failed; inspect the recovery journal at ${receiptPath} before retrying.`, { cause: error });
   }
-  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...aliases.length ? { rootAliases: aliases } : {} };
+  return { entries: entries.map(({ status, conflict, ...entry }) => entry), receiptPath, ...targetManifest ? { targetManifest } : {}, ...aliases.length ? { rootAliases: aliases } : {} };
 }
 function assertManagedAgentBridge(agent, options = {}) {
   const home = resolve16(options.home ?? homedir4()), dataDir3 = options.dataDir ?? getDataDirReadOnly();
@@ -56033,7 +56113,7 @@ function assertManagedAgentBridge(agent, options = {}) {
   } catch (error) {
     throw new Error(`NATIVE_SKILL_DRIFT: ${error.message}`);
   }
-  const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
+  const inventory = inventoryNativeSkills(home, { includeVendor: true, guardHermes: agent === "hermes", agents: [agent], projectDirs: [...roots], agentRoots: discovery.roots.map((path) => ({ agent, path })), allowRootAliases: aliases.length > 0 });
   const unexpected = inventory.filter((entry) => visible(entry) && !entry.bridge && !disabledBuiltin(entry));
   if (unexpected.length) {
     const paths = unexpected.slice(0, 3).map((entry) => {
@@ -107944,7 +108024,7 @@ async function connectCodexHookRpc(options) {
 }
 var SUPPORTED_CODEX_HOOK_VERSIONS;
 var init_codex_hook_rpc = __esm(() => {
-  SUPPORTED_CODEX_HOOK_VERSIONS = ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0"];
+  SUPPORTED_CODEX_HOOK_VERSIONS = ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0", "codex-cli 0.155.1"];
 });
 
 // src/lib/codex-hook-trust-layout.ts
@@ -108541,11 +108621,16 @@ function registerAgentIntegration(parent) {
     }
   });
   const migrate = parent.command("migrate").description("Preserve and retire native agent skill copies");
-  migrate.command("native").option("--project <directory>", "Also inventory a project and its ancestors (the current directory and its ancestors are always included)").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action(async (options) => {
+  migrate.command("native").option("--project <directory>", "Also inventory a project and its ancestors (the current directory and its ancestors are always included)").option("--include-unmanaged", "Archive user-authored skills as well as Skills-managed copies", false).option("--include-vendor", "Retire vendor SKILL.md discovery files while preserving plugin scripts and assets", false).option("--target-manifest <file>", "Reviewed exact native migration target manifest").option("--discovery-inputs <file>", "Advanced reviewed active plugin roots and source hashes").option("--allow-root-aliases", "Allow home .claude/.codex aliases to existing directories within this home", false).option("--apply", "Move selected skills to private archives outside agent discovery roots", false).option("--json", "Output inventory and archive receipt as JSON", false).description("Inventory native skill copies; preserve complete directories before retiring them").action(async (options) => {
     try {
       const discoveryInputs = options.discoveryInputs ? JSON.parse(readFileSync37(options.discoveryInputs, "utf8")) : undefined;
+      if (options.targetManifest && (options.includeUnmanaged || options.includeVendor))
+        throw new Error("--target-manifest cannot be combined with broad native migration selectors");
+      const targetManifest = options.targetManifest ? readNativeMigrationTargetManifest(options.targetManifest) : undefined;
       const inventory = inventoryNativeSkills(undefined, { projectDirs: [process.cwd(), ...options.project ? [options.project] : []], includeVendor: options.includeVendor, configured: options.includeVendor, discoveryInputs, allowRootAliases: options.allowRootAliases });
-      const result2 = options.apply ? archiveNativeSkills(inventory, { includeUnmanaged: options.includeUnmanaged, includeVendor: options.includeVendor, allowRootAliases: options.allowRootAliases }) : { entries: [] };
+      if (targetManifest)
+        selectNativeMigrationTargets(inventory, targetManifest);
+      const result2 = options.apply ? archiveNativeSkills(inventory, { includeUnmanaged: options.includeUnmanaged, includeVendor: options.includeVendor, allowRootAliases: options.allowRootAliases, targetManifest }) : { entries: [], ...targetManifest ? { targetManifest: { schema: targetManifest.schema, digest: targetManifest.digest, targetCount: targetManifest.targets.length } } : {} };
       if (options.json)
         await writeCliOutput(JSON.stringify({ applied: options.apply, inventory, ...result2 }));
       else