@nurix/etna 0.19.64 → 0.19.66

package/lib/install/materialize.mjs

@@ -0,0 +1,402 @@
+// packages/cli/lib/install/materialize.mjs
+// Turn one bundled harness into an installed project tree. THE SINGLE AUTHORITY on where a
+// harness's files land — a bundle says `skills/design/SKILL.md`, a project says
+// `.claude/skills/design/SKILL.md`, and this module is the only place that mapping exists.
+//
+// TWO SHIPPERS, ONE MAPPING. `bin/etna.js` calls this against the user's cwd; the Apollo push
+// (`.github/scripts/push-harnesses.mjs`) calls it against a throwaway directory and ships the
+// result, so an App's export from Apollo extracts as the same tree `npx @nurix/etna` writes.
+// They diverged once — the push sent the BUNDLE layout, so a downloaded project had its
+// instruction tree at the archive root, no AGENTS.md, and no wired hooks, while the manifest
+// claimed otherwise. One function is what stops that recurring.
+//
+// ZERO DEPENDENCIES, BY NECESSITY. The push runs in CI without an `npm install` (that workflow
+// reaches `npm publish` → `prepack` and nothing else), so this module and everything it imports
+// may use only what Node ships. That rules out importing `bin/etna.js`, which pulls in
+// @clack/prompts for its UI — hence the extraction rather than a re-export.
+//
+// PURE FILE OPS, NO UI. Every human-facing string is RETURNED (installed/notices/warnings) and
+// printed by the caller, so the push can discard what the CLI renders.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  cpSync,
+  readdirSync,
+  lstatSync,
+  rmSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { planHarnessFiles, PRUNABLE_SUBDIRS, CODEX_REBUILT_DIRS } from './plan.mjs';
+
+// Hook scripts shipped by earlier harness versions (the legacy memory-ledger tier) and since retired.
+// mergeHooks is additive, so an upgrade must explicitly remove both the stale settings.json
+// entries pointing at these and the leftover script files they reference.
+const RETIRED_HOOKS = [
+  'session-stop.js',
+  'post-tool-failure.js',
+  'post-commit.js',
+  'generate-ownership-index.mjs', // folded into awareness.mjs — unretired, the index would inject twice
+];
+
+export function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+// Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
+function backupIfExists(path) {
+  if (!existsSync(path) && !isSymlink(path)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = `${path}.bak.${ts}`;
+  renameSync(path, backup);
+  return backup;
+}
+
+// Copy a directory to <path>.bak.<timestamp>, leaving the original in place. Returns the
+// backup path, or null. Used for .claude/, which is refreshed in place (not overwritten
+// wholesale), so the live tree must survive for the in-place update — snapshot, don't move.
+function snapshotDirIfExists(path) {
+  if (!existsSync(path)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = `${path}.bak.${ts}`;
+  cpSync(path, backup, { recursive: true });
+  return backup;
+}
+
+// Throws rather than exiting: the CLI turns this into its own `die`, and the push into a
+// non-zero exit naming the harness.
+export function readJson(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    throw new Error(`failed to parse ${path}: ${e.message}`);
+  }
+}
+
+// 2-space indent matches Claude Code's own writes to settings.json.
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+
+// Clean up any leftover marketplace/enabledPlugins entries from a previous 0.1.x
+// install. After 0.2.0 we don't use the marketplace flow at all — leaving stale
+// entries causes Claude Code to also resolve the plugin from the global cache,
+// double-loading the same skills under a different namespace.
+function migrateFromPluginInstall(targetDir, pluginName) {
+  const removed = [];
+  const projectSettingsPath = join(targetDir, '.claude', 'settings.json');
+  if (existsSync(projectSettingsPath)) {
+    const s = readJson(projectSettingsPath);
+    if (s.enabledPlugins) {
+      const keys = Object.keys(s.enabledPlugins).filter((k) => k.startsWith(`${pluginName}@`));
+      for (const k of keys) {
+        delete s.enabledPlugins[k];
+        removed.push(`enabledPlugins["${k}"] in ${projectSettingsPath}`);
+      }
+      if (Object.keys(s.enabledPlugins).length === 0) delete s.enabledPlugins;
+      writeJson(projectSettingsPath, s);
+    }
+  }
+  return removed;
+}
+
+// Remove settings.json hook entries and .claude/hooks/ files for retired hook scripts.
+// Bundle-aware: a name on the retired list is skipped while THIS bundle still ships it —
+// several harnesses share the list, and they retire the same script at different versions.
+function retireOldHooks(targetDir, bundledHarnessDir) {
+  const removed = [];
+  const bundledHooksDir = join(bundledHarnessDir, 'hooks');
+  const stillShipped = new Set(
+    existsSync(bundledHooksDir)
+      ? readdirSync(bundledHooksDir, { withFileTypes: true })
+          .filter((e) => e.isFile())
+          .map((e) => e.name)
+      : [],
+  );
+  const retired = RETIRED_HOOKS.filter((name) => !stillShipped.has(name));
+  const settingsPath = join(targetDir, '.claude', 'settings.json');
+  if (existsSync(settingsPath)) {
+    const settings = readJson(settingsPath);
+    const isRetired = (h) => retired.some((name) => (h.command || '').includes(`/hooks/${name}`));
+    let pruned = 0;
+    for (const [event, groups] of Object.entries(settings.hooks || {})) {
+      for (const group of groups) {
+        const before = (group.hooks || []).length;
+        group.hooks = (group.hooks || []).filter((h) => !isRetired(h));
+        pruned += before - group.hooks.length;
+      }
+      settings.hooks[event] = groups.filter((g) => (g.hooks || []).length > 0);
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
+    }
+    if (pruned > 0) {
+      writeJson(settingsPath, settings);
+      removed.push(`${pruned} retired hook entr${pruned === 1 ? 'y' : 'ies'} in settings.json`);
+    }
+  }
+  for (const name of retired) {
+    const file = join(targetDir, '.claude', 'hooks', name);
+    if (existsSync(file)) {
+      rmSync(file, { force: true });
+      removed.push(`stale hook script ${name}`);
+    }
+  }
+  return removed;
+}
+
+// Read the `owned` manifest the PREVIOUS install recorded in the project's harness.json.
+// Absent (first install, or pre-pruning version) ⇒ {} ⇒ nothing is pruned this round.
+function readInstalledOwned(targetDir) {
+  const path = join(targetDir, '.claude', 'harness.json');
+  if (!existsSync(path)) return {};
+  const owned = readJson(path).owned;
+  return owned && typeof owned === 'object' ? owned : {};
+}
+
+// Remove vendored components a prior harness version owned but this one no longer ships
+// (e.g. a retired agent like harness-manager). Only names present in the PRIOR `owned`
+// manifest are eligible, so a project's own components — never in that manifest — survive.
+function pruneOrphanedComponents(targetDir, priorOwned, newOwned) {
+  const removed = [];
+  for (const sub of PRUNABLE_SUBDIRS) {
+    const had = priorOwned[sub] || [];
+    const has = new Set(newOwned[sub] || []);
+    for (const name of had) {
+      if (has.has(name)) continue;
+      const target = join(targetDir, '.claude', sub, name);
+      if (existsSync(target)) {
+        rmSync(target, { recursive: true, force: true });
+        removed.push(`orphaned ${sub.replace(/s$/, '')} ${name}`);
+      }
+    }
+  }
+  return removed;
+}
+
+// Every file inside dir, as paths relative to dir.
+export function listFilesRecursive(dir, prefix = '') {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFilesRecursive(join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+// Remove directories left empty by a prune, depth-first.
+function removeEmptyDirs(dir) {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true }))
+    if (entry.isDirectory()) removeEmptyDirs(join(dir, entry.name));
+  if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true });
+}
+
+// Remove files inside an installed component that this bundle no longer ships. copyHarnessSubdir
+// merges, so a component that SURVIVES an upgrade while shedding a file keeps the stale copy
+// forever — that is how a retired reference file goes on being read as live doctrine. Scoped to
+// components the bundle still ships (a project's own components are never in that set, so they
+// are never touched), and needs no prior manifest, so one refresh clears orphans left by any
+// earlier version. Whole components that disappear are pruneOrphanedComponents' job.
+function pruneStaleComponentFiles(bundledSubdir, projectSubdir) {
+  const removed = [];
+  if (!existsSync(bundledSubdir)) return removed;
+  for (const entry of readdirSync(bundledSubdir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const shipped = new Set(listFilesRecursive(join(bundledSubdir, entry.name)));
+    const installedDir = join(projectSubdir, entry.name);
+    for (const rel of listFilesRecursive(installedDir)) {
+      if (shipped.has(rel)) continue;
+      rmSync(join(installedDir, rel), { force: true });
+      removed.push(`${entry.name}/${rel}`);
+    }
+    removeEmptyDirs(installedDir);
+  }
+  return removed;
+}
+
+// True if an event's matcher-group already carries a hook with this command string.
+function groupHasCommand(group, command) {
+  return (group.hooks || []).some((h) => h.command === command);
+}
+
+// Deep-merge the bundle's hooks.json object into <project>/.claude/settings.json under
+// "hooks", preserving every existing key. Idempotent: for each event, an incoming entry
+// merges into the matcher-group of the same matcher, skipping any hook whose command
+// already exists there; a new matcher creates a new group. Returns count of hooks added.
+function mergeHooks(targetDir, bundledHooksJson) {
+  if (!existsSync(bundledHooksJson)) return 0;
+  const bundled = readJson(bundledHooksJson);
+  const incoming = bundled.hooks || {};
+  const settingsPath = join(targetDir, '.claude', 'settings.json');
+  const settings = readJson(settingsPath);
+  settings.hooks = settings.hooks || {};
+  let added = 0;
+  // Harness-shipped permission defaults (e.g. Edit on docs/** flows without prompts —
+  // the deny hooks still hard-block frozen/protected paths underneath). Additive, idempotent.
+  for (const rule of bundled.permissions?.allow || []) {
+    settings.permissions = settings.permissions || {};
+    const allowList = (settings.permissions.allow = settings.permissions.allow || []);
+    if (!allowList.includes(rule)) {
+      allowList.push(rule);
+      added += 1;
+    }
+  }
+  for (const [event, groups] of Object.entries(incoming)) {
+    const existingGroups = (settings.hooks[event] = settings.hooks[event] || []);
+    for (const group of groups) {
+      const match = existingGroups.find((g) => g.matcher === group.matcher);
+      if (!match) {
+        existingGroups.push(group);
+        added += (group.hooks || []).length;
+        continue;
+      }
+      match.hooks = match.hooks || [];
+      for (const hook of group.hooks || []) {
+        if (groupHasCommand(match, hook.command)) continue;
+        match.hooks.push(hook);
+        added += 1;
+      }
+    }
+  }
+  if (added > 0) writeJson(settingsPath, settings);
+  return added;
+}
+
+/**
+ * Write one compiled harness into `targetDir` as an installed project tree.
+ *
+ * THE PLAN DECIDES WHAT AND WHERE; THIS DECIDES HOW IT MEETS AN EXISTING PROJECT. Placement lives
+ * in `plan.mjs` and is shared with the Apollo push, so the two shippers cannot disagree about a
+ * path. Everything here is the part a payload has no use for: backing up what git cannot recover,
+ * rebuilding the Codex mirrors wholesale, pruning components a prior version owned, retiring hook
+ * entries pointing at scripts this bundle no longer carries, and folding the harness's hooks into
+ * a settings.json that already belongs to somebody.
+ *
+ * `pluginName` is used only for the legacy marketplace cleanup. `projectHasGit` decides the backup
+ * policy for the harness-owned artifacts a refresh overwrites — git is the safety net when it is
+ * there, a `.bak.<timestamp>` copy when it is not.
+ *
+ * Returns the accounting the caller renders: `installed`, `notices`, `warnings`, plus `owned` (the
+ * manifest written into `.claude/harness.json`) and `meta` (the bundle marker).
+ */
+export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, projectHasGit }) {
+  const { files, owned, meta } = planHarnessFiles(bundledHarnessDir);
+
+  const installed = [];
+  const notices = [];
+  const warnings = [];
+
+  // Read BEFORE anything is written: this is what a prior install recorded as harness-owned, and
+  // the marker that holds it is one of the files about to be overwritten.
+  const priorOwned = readInstalledOwned(targetDir);
+
+  // The safety net, for the two artifacts a refresh overwrites outright. A git repo recovers them
+  // from history, so we only say so; without git there is no net, so we take a copy and warn. The
+  // .claude/ tree is SNAPSHOTTED rather than moved — it is refreshed in place, so the live tree has
+  // to survive for the writes below.
+  for (const [rel, kind] of [
+    ['CLAUDE.md', 'file'],
+    ['AGENTS.md', 'file'],
+  ]) {
+    const dest = join(targetDir, rel);
+    if (!existsSync(dest) && !isSymlink(dest)) continue;
+    if (projectHasGit) {
+      notices.push(
+        `Overwrote existing ${rel} (tracked by git — \`git checkout ${rel}\` to restore).`,
+      );
+    } else {
+      warnings.push(
+        `No .git here, so no version-control safety net — backed up existing ${rel} → ${backupIfExists(dest)}`,
+      );
+    }
+    void kind;
+  }
+  for (const rel of ['.claude', ...CODEX_REBUILT_DIRS]) {
+    const dest = join(targetDir, rel);
+    if (!existsSync(dest)) continue;
+    if (projectHasGit) {
+      notices.push(
+        `Refreshed existing ${rel}/ in place (tracked by git — \`git checkout ${rel}\` to restore).`,
+      );
+    } else {
+      const backup = snapshotDirIfExists(dest);
+      if (backup) {
+        warnings.push(
+          `No .git here, so no version-control safety net — snapshotted existing ${rel}/ → ${backup}`,
+        );
+      }
+    }
+  }
+
+  // The Codex mirrors are rebuilt wholesale, not merged: they are byte projections of the Claude
+  // tree, so a file left behind from a prior version is a skill Codex still sees after the harness
+  // dropped it. Removed before the writes, never after.
+  for (const rel of CODEX_REBUILT_DIRS)
+    rmSync(join(targetDir, rel), { recursive: true, force: true });
+
+  let written = 0;
+  let seeded = 0;
+  for (const file of files) {
+    const dest = join(targetDir, file.path);
+    // A seed is one-time scaffolding: once the path exists it is the project's living copy, and a
+    // refresh must not touch it. This is also the rule that lets an Apollo export carry an App's
+    // own `docs/history/backlog.md` instead of the harness's.
+    if (file.policy === 'seed') {
+      if (existsSync(dest)) continue;
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, file.content);
+      seeded += 1;
+      continue;
+    }
+    // settings.json belongs to the project, not the harness — it carries the user's own hooks and
+    // permissions. The plan's copy is what a FRESH install would hold; against an existing file the
+    // authority is mergeHooks below, which is additive and idempotent.
+    if (file.policy === 'merge') continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content);
+    written += 1;
+  }
+  installed.push(`${written} harness file(s) → ./ and .claude/`);
+  if (seeded > 0) installed.push(`${seeded} seed file(s) → ./ (only where absent)`);
+
+  // Prune components a prior harness version owned but this bundle no longer ships (e.g. a retired
+  // agent). Only prior-owned names are eligible, so the project's own files survive.
+  for (const r of pruneOrphanedComponents(targetDir, priorOwned, owned))
+    notices.push(`removed ${r}`);
+
+  // Then prune stale files INSIDE components the bundle still ships — the case the name-level diff
+  // above cannot see, since the component itself is still present. Without it, a component that
+  // survives an upgrade while shedding a file keeps the stale copy for ever, and a retired
+  // reference file goes on being read as live doctrine.
+  for (const sub of PRUNABLE_SUBDIRS) {
+    for (const stale of pruneStaleComponentFiles(
+      join(bundledHarnessDir, sub),
+      join(targetDir, '.claude', sub),
+    )) {
+      notices.push(`removed stale ${sub.replace(/s$/, '')} file ${stale}`);
+    }
+  }
+
+  // Retire hooks earlier harness versions shipped, before merging, so the additive merge never
+  // resurrects an entry pointing at a script this bundle no longer carries.
+  for (const r of retireOldHooks(targetDir, bundledHarnessDir)) notices.push(`removed ${r}`);
+
+  const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));
+  if (added > 0) installed.push(`${added} hook(s) → .claude/settings.json`);
+
+  for (const entry of migrateFromPluginInstall(targetDir, pluginName)) {
+    notices.push(`removed stale ${entry}`);
+  }
+
+  return { installed, notices, warnings, owned, meta };
+}

package/lib/install/plan.mjs

@@ -0,0 +1,271 @@
+// packages/cli/lib/install/plan.mjs
+// THE HARNESS COMPILER: one bundled harness definition in, the exact file list a fresh install
+// produces out. Pure — it reads the bundle and returns data, and writes nothing.
+//
+// This is the single authority on WHERE a harness's files land and WHAT is in them. Both shippers
+// consume it and neither re-derives it:
+//
+//   push-harnesses.mjs  → publishes the array to Apollo verbatim
+//   materializeHarness  → writes the array to a project, applying each entry's policy
+//
+// They diverged once, and that is the whole reason this file exists. The Apollo push used to walk
+// the BUNDLE directory and send those paths, so a project downloaded from Apollo Studio extracted
+// with its instruction tree at the archive root where no runtime looks for it, no AGENTS.md, and no
+// hooks wired into settings.json — while the export manifest claimed the folder was ready to open.
+// Nothing failed: every file was present, only its location was wrong.
+//
+// PURE, AND THAT IS THE POINT. Deriving the payload by installing into a temp directory and reading
+// it back works, but it is disk I/O to compute a mapping — and it hides the mapping inside a
+// sequence of file operations where no test can see it. As data, the mapping is a value you can
+// assert on.
+//
+// EVERY ENTRY CARRIES A POLICY, because "what a fresh install produces" and "what a refresh writes
+// over an existing project" differ for exactly two kinds of file. A payload flattens all three (an
+// empty target takes every write); an install honours them.
+//
+//   own   — harness-owned. Overwritten on every refresh.
+//   seed  — one-time scaffolding. Written only where the path is ABSENT; once present it is the
+//           project's living copy, never refreshed and never pruned.
+//   merge — folded into whatever the project already has, key by key. Only `.claude/settings.json`,
+//           which carries the user's own hooks and permissions beside the harness's.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { buildCodexAdapter } from '../codex/agents-md.mjs';
+import { toCodexCommand } from '../codex/hooks.mjs';
+
+// Subfolders bundled inside each harness payload that map 1:1 onto <project>/.claude/<name>/.
+// Order matches Claude Code's own folder layout. hooks/ carries the hook scripts + lib/ (and
+// hooks.json, shipped harmlessly — the settings merge reads it from the bundle, not this copy).
+export const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts', 'hooks'];
+
+// Component subdirs whose membership is tracked so a removed-from-the-harness component can be
+// pruned on refresh. Hooks are excluded — retireOldHooks owns them, because it must also prune the
+// matching settings.json entry, which a name-only diff cannot reach.
+export const PRUNABLE_SUBDIRS = ['skills', 'agents', 'rules', 'scripts'];
+
+// Codex targets rebuilt wholesale on every install rather than merged, so a refresh must delete
+// them first. Recorded in harness.json's `owned.codex` so a later version can prune one it drops.
+export const CODEX_REBUILT_DIRS = ['.agents/skills', '.codex/agents'];
+
+// Every file under dir, as posix paths relative to it. Posix regardless of host, because these
+// become ZIP entry names on Apollo's side and a backslash is a legal filename character on the
+// systems that extract them.
+function filesUnder(dir, prefix = '') {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...filesUnder(join(dir, entry.name), rel));
+    else if (entry.isFile()) out.push(rel);
+    // A dirent that is neither is almost certainly a symlink. Refusing beats skipping: Apollo
+    // stores content, so there is no link to follow on the other side, and a silently short
+    // payload is the exact failure mode this module exists to prevent.
+    else
+      throw new Error(
+        `${join(dir, entry.name)} is neither a file nor a directory — a harness may not ship one`,
+      );
+  }
+  return out;
+}
+
+// One bundle path → one or more entries. A `files:`/`seeds:` entry may legally name a directory
+// (the installer copies it with `recursive: true`), so a single declared path can expand.
+function entriesFor(bundleDir, rel, policy) {
+  const source = join(bundleDir, rel);
+  if (!existsSync(source)) return [];
+  if (statSync(source).isDirectory()) {
+    return filesUnder(source).map((child) => ({
+      path: `${rel}/${child}`,
+      content: readFileSync(join(source, child), 'utf8'),
+      policy,
+    }));
+  }
+  return [{ path: rel.split(sep).join('/'), content: readFileSync(source, 'utf8'), policy }];
+}
+
+// 2-space indent + trailing newline matches Claude Code's own writes to settings.json, and the
+// installed bytes must equal the payload's bytes or the two shippers disagree on content.
+function asJson(value) {
+  return JSON.stringify(value, null, 2) + '\n';
+}
+
+// Sorted base names of *.<ext> files directly under dir (e.g. rules/*.md → rule names).
+function listByExt(dir, ext) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(ext))
+    .map((f) => f.slice(0, -ext.length))
+    .sort();
+}
+
+// The manifest of what THIS harness owns, per prunable subdir — raw top-level entry names, which
+// is what the next refresh diffs against to find components the harness has since dropped.
+function bundledOwned(bundleDir) {
+  const owned = {};
+  for (const sub of PRUNABLE_SUBDIRS) {
+    const dir = join(bundleDir, sub);
+    owned[sub] = existsSync(dir) ? readdirSync(dir).sort() : [];
+  }
+  return owned;
+}
+
+// `.claude/settings.json` as a FRESH install writes it: the bundle's hooks.json folded into an
+// empty settings object. `hooks` is created before the permissions loop, so it comes first in key
+// order — and key order is part of the bytes, so it is part of the contract.
+function freshSettings(bundleDir) {
+  const hooksJson = join(bundleDir, 'hooks', 'hooks.json');
+  if (!existsSync(hooksJson)) return null;
+  const bundled = JSON.parse(readFileSync(hooksJson, 'utf8'));
+  const settings = { hooks: {} };
+  for (const rule of bundled.permissions?.allow || []) {
+    settings.permissions = settings.permissions || {};
+    settings.permissions.allow = settings.permissions.allow || [];
+    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
+  }
+  for (const [event, groups] of Object.entries(bundled.hooks || {})) {
+    settings.hooks[event] = groups;
+  }
+  if (!Object.keys(settings.hooks).length && !settings.permissions) return null;
+  return asJson(settings);
+}
+
+// `.codex/hooks.json` — the Claude hooks.json filtered to type:"command", the only kind Codex
+// executes, with each command prefixed so `$CLAUDE_PROJECT_DIR` resolves under a runtime that does
+// not export it. The translation itself is `toCodexCommand`, imported rather than restated.
+function codexHooks(bundleDir) {
+  const hooksJson = join(bundleDir, 'hooks', 'hooks.json');
+  if (!existsSync(hooksJson)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(hooksJson, 'utf8'));
+  } catch {
+    return null;
+  }
+  const out = {};
+  for (const [event, groups] of Object.entries(parsed.hooks || {})) {
+    const kept = [];
+    for (const group of groups) {
+      const hooks = (group.hooks || [])
+        .filter((h) => h.type === 'command')
+        .map((h) => ({ ...h, command: toCodexCommand(h.command) }));
+      if (hooks.length) kept.push({ ...group, hooks });
+    }
+    if (kept.length) out[event] = kept;
+  }
+  return Object.keys(out).length ? asJson({ hooks: out }) : null;
+}
+
+/**
+ * Compile one bundled harness into the file list a fresh install produces.
+ *
+ * Returns `{ files, owned, meta }` — `files` sorted by path, each with a policy; `owned` the
+ * manifest that goes into `.claude/harness.json`; `meta` the parsed bundle marker.
+ *
+ * Throws when the bundle has no CLAUDE.md: that is the one file every harness must carry, and a
+ * harness without a policy is not a harness.
+ */
+export function planHarnessFiles(bundleDir) {
+  const claudeMdPath = join(bundleDir, 'CLAUDE.md');
+  if (!existsSync(claudeMdPath)) {
+    throw new Error(`Bundled CLAUDE.md missing at ${claudeMdPath}. Rebuild package data.`);
+  }
+
+  const files = [];
+  const claudeMd = readFileSync(claudeMdPath, 'utf8');
+  files.push({ path: 'CLAUDE.md', content: claudeMd, policy: 'own' });
+
+  // The component subtrees. This is the mapping the whole module exists for: a bundle says
+  // `skills/design/SKILL.md`, a project says `.claude/skills/design/SKILL.md`.
+  for (const sub of PLUGIN_SUBDIRS) {
+    for (const rel of filesUnder(join(bundleDir, sub))) {
+      files.push({
+        path: `.claude/${sub}/${rel}`,
+        content: readFileSync(join(bundleDir, sub, rel), 'utf8'),
+        policy: 'own',
+      });
+    }
+  }
+
+  // Dual-runtime: the Codex artifacts the CLI derives at install time. A ZIP extract runs no
+  // installer, so if these are not in the payload a downloaded project has no Codex support at
+  // all and no way to generate it.
+  const owned = bundledOwned(bundleDir);
+  const codexOwned = [];
+
+  const adapter = buildCodexAdapter(bundleDir);
+  const separator = claudeMd.endsWith('\n') ? '\n' : '\n\n';
+  files.push({
+    path: 'AGENTS.md',
+    content: adapter ? claudeMd + separator + adapter : claudeMd,
+    policy: 'own',
+  });
+  codexOwned.push('AGENTS.md');
+
+  // `.agents/skills/` is Codex's official scan path and a byte mirror of `.claude/skills/`. Both
+  // runtimes require exactly name+description in SKILL.md frontmatter, so the mirrored files are
+  // valid for Codex unchanged.
+  const skillFiles = filesUnder(join(bundleDir, 'skills'));
+  if (skillFiles.length) {
+    for (const rel of skillFiles) {
+      files.push({
+        path: `.agents/skills/${rel}`,
+        content: readFileSync(join(bundleDir, 'skills', rel), 'utf8'),
+        policy: 'own',
+      });
+    }
+    codexOwned.push('.agents/skills');
+  }
+
+  const tomls = listByExt(join(bundleDir, 'codex', 'agents'), '.toml');
+  if (tomls.length) {
+    for (const name of tomls) {
+      files.push({
+        path: `.codex/agents/${name}.toml`,
+        content: readFileSync(join(bundleDir, 'codex', 'agents', `${name}.toml`), 'utf8'),
+        policy: 'own',
+      });
+    }
+    codexOwned.push('.codex/agents');
+  }
+
+  const hooks = codexHooks(bundleDir);
+  if (hooks) {
+    files.push({ path: '.codex/hooks.json', content: hooks, policy: 'own' });
+    codexOwned.push('.codex/hooks.json');
+  }
+
+  owned.codex = codexOwned;
+
+  // The marker, at the path the CLI writes and the maintenance agent resolves the installed
+  // version from — never at the bundle root, where nothing reads it.
+  const markerPath = join(bundleDir, 'harness.json');
+  const meta = existsSync(markerPath) ? JSON.parse(readFileSync(markerPath, 'utf8')) : {};
+  if (existsSync(markerPath)) {
+    files.push({
+      path: '.claude/harness.json',
+      content: asJson({ ...meta, owned }),
+      policy: 'own',
+    });
+  }
+
+  // Project-root config the harness owns outright (.prettierrc.json, .vscode/settings.json, …),
+  // then the one-time scaffolding it seeds. Same landing, opposite ownership.
+  for (const rel of meta.files || []) files.push(...entriesFor(bundleDir, rel, 'own'));
+  for (const rel of meta.seeds || []) files.push(...entriesFor(bundleDir, rel, 'seed'));
+
+  const settings = freshSettings(bundleDir);
+  if (settings) files.push({ path: '.claude/settings.json', content: settings, policy: 'merge' });
+
+  // Sorted so the plan is byte-stable across machines — readdir order is not guaranteed, and an
+  // unstable order would make two identical builds look different to anything comparing them.
+  files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+  const seen = new Set();
+  for (const file of files) {
+    if (seen.has(file.path)) throw new Error(`the harness plans ${file.path} twice`);
+    seen.add(file.path);
+  }
+
+  return { files, owned, meta };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.64",
+    "version": "0.19.66",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {
@@ -42,5 +42,5 @@
         "agent",
         "plugin"
     ],
-    "etnaFingerprint": "6b7cd94d8ed9"
+    "etnaFingerprint": "774efa3ae2da"
 }