@nurix/etna 0.19.63 → 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.63",
+    "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": "b42bc499d0c7"
+    "etnaFingerprint": "b0d947332bf0"
 }

package/data/harnesses/code/rules/cloudflare.md

@@ -1,167 +0,0 @@
-# Cloudflare Worker
-
-Conventions for Cloudflare Workers — `wrangler.jsonc` setup, vars and secrets, and code shape (dispatch, errors, modules, WebSockets). Schema design doctrine is the `schema-design` skill.
-
-## 1. Project & wrangler.jsonc Setup
-
-### 1.1 Wrangler version
-
-- Use Wrangler **v4** — v3's bundled config schema is missing newer keys (e.g. `secrets_store_secrets`), so editors flag valid config as invalid.
-- **No `package.json`** (dep-free worker): use `npx wrangler@4` in every command and doc — the `@4` is the pin. Don't create a `package.json` just to record it.
-- **`package.json` exists**: pin wrangler to the exact version tested against (not `^4.0.0`), reinstall, and verify with `wrangler deploy --dry-run` before pushing.
-
-### 1.2 Config format
-
-- Use `wrangler.jsonc` (not `wrangler.toml`).
-- Include `"$schema": "node_modules/wrangler/config-schema.json"` so the editor validates against the exact installed wrangler version.
-
-### 1.3 Comments in jsonc
-
-None by default. Keep a comment only when it captures a non-obvious **WHY** — a hidden constraint, workaround, or account-specific quirk. Never narrate what a key already says.
-
-### 1.4 workers.dev URLs
-
-- Set `"workers_dev": false` once a custom domain is wired up, so the custom domain is the only entry point.
-- Pair with a `routes` entry using `custom_domain: true` so Cloudflare manages the DNS record and cert.
-
-### 1.5 Observability
-
-Default block for every Worker:
-
-```jsonc
-"observability": {
-    "logs": {
-        "enabled": false,
-        "invocation_logs": true
-    }
-}
-```
-
-`enabled: false` avoids per-log billing; `invocation_logs: true` keeps the cheap per-request audit trail. **Bootstrap override:** a new Worker (especially cron-only) runs with `enabled: true` until a few real runs look clean — with logs off, `console.log` is visible only live via `npx wrangler tail` and nothing persists after a failed run. Flip back once stable.
-
-### 1.6 Project structure & dependencies
-
-- Main entry file: `index.ts`. Reusable helpers: `helper.ts`.
-- TypeScript under `strict: true` — wrangler bundles it natively, no separate build step; a minimal `tsconfig.json` ships even in dep-free Workers.
-- Don't run `npm run build` or `npm run deploy` in examples.
-- **`package.json` / `package-lock.json` are opt-in, not default.** Create them only when code under `src/` imports an npm package at runtime — a Worker on built-in Web/Workers APIs alone needs no manifest; run wrangler, linters, and one-offs via `npx <tool>`. Add both files the moment the first real dep lands. `node_modules/` stays in `.gitignore` either way.
-
-### 1.7 Environment & configuration
-
-- Use the deployed Cloudflare URL in docs/tests, not `localhost`.
-- Prefer SQLite-based Durable Objects over in-memory-only designs; add classes under `migrations.new_sqlite_classes`.
-
-### 1.8 Cloudflare Secrets Store
-
-Use when the user mentions it. Use the same `binding` name as the `secret_name`.
-
-```jsonc
-"secrets_store_secrets": [
-    { "binding": "CLICKUP_KEY", "store_id": "792206780c0c46e8ba8ade3f21b44eac", "secret_name": "CLICKUP_KEY" }
-]
-```
-
-Access in code: `await env.CLICKUP_KEY.get()`.
-
-### 1.9 Naming
-
-- Repo/dir: `cf-<name>` (e.g. `cf-extract-design`).
-- Worker name: `<name>` — repo name minus the `cf-` prefix.
-- R2 bucket, D1 database, and KV namespace names: equal to the worker name. One name, one resource set.
-
-### 1.10 Vars & secrets
-
-**Non-secret vars live in the `vars` block in `wrangler.jsonc`** — checked in, one source of truth. Vars are configuration, not runtime state; do not move them to the dashboard. A single-tenant application Worker (one deployment — e.g. Apollo) declares them at the top level; a multi-tenant Worker declares per-tenant vars under each `env.<tenant>` block (§11).
-
-**Secrets never touch git.** Local dev: a gitignored `.dev.vars` (`KEY=VALUE` dotenv, auto-loaded by `wrangler dev`) with a committed `.dev.vars.example` listing the keys and placeholder values. Production: `wrangler secret put <NAME>`, a gitignored `.secrets` file pushed with `wrangler secret bulk .secrets` (or shipped with a deploy via `wrangler deploy --secrets-file .secrets`), or the Secrets Store (§1.8). Never log or echo a secret value.
-
-**No `keep_vars`.** Leave it unset (default `false`) — each deploy reconciles vars to exactly what the config declares. `keep_vars` only guards plaintext vars set out-of-band in the dashboard; it never touches secrets — `wrangler secret put` secrets survive every deploy regardless. Only the multi-tenant pattern sets `keep_vars: true` (§11).
-
-**Never name a deployed-value file `.env` or `.env.<anything>`** — `wrangler dev` auto-loads a root `.env` as local dev vars, so a prod-valued `.env` silently becomes the local environment on a fresh clone or in CI. Committed `*.example` files carry keys with placeholder values only.
-
-`.gitignore`: `.dev.vars`, `.secrets`, `.secrets.*`, `.env`, `.env.*`
-
-## 2. Code & Helpers
-
-- Use `generateUuidV7()` in `helper.ts` for IDs (time-sortable UUIDv7).
-- Only `await` what's needed (e.g. `request.json()`, `do.fetch(...)`).
-
-## 3. fetch() Structure
-
-`validateRequest()` first, then `switch (path)` for dispatch. Single `try/catch` wrapping the entire handler. No if-chains, no regex in fetch.
-
-```js
-export default {
-  async fetch(request, env, ctx) {
-    try {
-      const route = validateRequest(request);
-      switch (route.path) {
-        case "monitors":
-          return await handleMonitors({ ...route, env, ctx });
-        default:
-          throw { code: 404, message: "Route not found" };
-      }
-    } catch (error) {
-      console.error("Unhandled error in fetch()", error);
-      return createErrorResponse(
-        error.message || "Internal server error",
-        error.code || 500,
-      );
-    }
-  },
-};
-```
-
-No nested `try/catch` except around WebSocket `send`/`close` (see §9).
-
-## 4. validateRequest()
-
-Lives in `helper.ts`. Parses the URL in one place and returns `{ path, method, query, resourceId, subPath }`; throws `{ code: 400 }` when a path requires a resource ID and none is present.
-
-## 5. Validation
-
-Fail fast with thrown `{ code, message }` (`400` bad input, `401` missing/invalid auth). Validate required fields explicitly — no optional chaining for required fields.
-
-## 6. Errors & Responses
-
-- Throw structured errors: `{ code, message }`. Always `console.error()` with context (path, user, etc.). No empty catch blocks.
-- Response envelope `{ status: 1|0, message, data }` — the shared cross-service contract.
-- `createResponse(data, message, code)` in `helper.ts` bakes CORS in, returns a null body for 204/304, and uses proper HTTP codes; `createErrorResponse(message, code)` delegates to it.
-- CORS is passive: a `CORS_HEADERS` const in `helper.ts`, spread into `createResponse()` — no explicit OPTIONS handler, no wrapper functions. Origin-restricted CORS builds the headers from an allowlist (plus `localhost` in dev), still inside `createResponse()`.
-
-## 7. Handler Signatures
-
-Single destructured object — never positional args. Compose by spreading route with env/ctx: `handleGetStats({ request, env, resourceId })`, not `handleGetStats(request, id, env)`.
-
-## 8. Module Structure
-
-Feature-based folders with `handle.ts` + `helper.ts` pairs. `index.ts` only does dispatch.
-
-| Path | Role |
-| --- | --- |
-| `src/index.ts` | Entry point — dispatch only |
-| `src/helper.ts` | Shared CORS, responses, validation, utilities |
-| `src/database.ts` | Shared D1 queries |
-| `src/<feature>/handle.ts` | Route handlers |
-| `src/<feature>/helper.ts` | Feature-specific helpers & DB ops |
-
-## 9. WebSockets
-
-Standard `WebSocketPair` handshake (`server.accept()`, return 101 with `webSocket: client`). Check `readyState === WebSocket.OPEN` before sending. The only acceptable nested `try/catch`: wrap `send`; in its catch, `close(1011)` inside a bare inner try, then evict the session.
-
-## 10. D1 Schema
-
-Follows the shared database naming and column-type vocabulary; what earns a table and the rest of the design doctrine is the `schema-design` skill.
-
-## 11. Multi-tenant Workers (native environments)
-
-Rare — only when **one Worker codebase ships as several independent tenants** (separate Workers, domains, and data stores from a single `src/`, e.g. `~/dev/auth` → `auth-nuplay`, `auth-nustack`). Use **native wrangler environments**, never one Worker that switches tenant at runtime. For a single-tenant application Worker, §1.10 applies and this section does not.
-
-- **One config, `env.<tenant>` blocks.** The top-level block is **local dev** (`wrangler dev`): a `*-dev` name and placeholder D1/KV ids, simulated locally. Each `env.<tenant>` block is **one production tenant**; deploy it with `wrangler deploy --env <tenant>`.
-- **Named environments never inherit** `vars` / `d1_databases` / `kv_namespaces` / `routes` / `secrets_store_secrets` / `assets` from the top level — **each `env.<tenant>` declares them in full**. Dropping a binding from an env block disables that capability for that one tenant.
-- **Per-tenant non-secret vars live in `env.<tenant>.vars`** — still checked in; one file holds every tenant's config side by side.
-- **Local-dev vars** come from a gitignored `.vars.local`, injected as `--var` by the dev script (the top-level block carries no in-config `vars`).
-- **Per-tenant secrets, never in git** — `wrangler secret put <NAME> --env <tenant>`, or a gitignored per-tenant `.secrets` (e.g. `worker/tenants/<tenant>/.secrets`) pushed with `wrangler secret bulk --env <tenant>`, plus a committed `.secrets.example`. Secrets Store bindings are declared inside each env block.
-- **`keep_vars: true`** (top level) keeps a per-tenant deploy **additive**: tenants inject their non-secret vars via `--var` (or the dashboard), and without it a deploy would wipe them. On secrets it changes nothing (§1.10).
-
-`.gitignore`: `.vars.local`, `.secrets`, `.secrets.*`, `.env`, `.env.*`