@nurix/etna 0.19.64 → 0.19.65

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.65",
     "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": "b0d947332bf0"
 }