@nurix/etna 0.17.1 → 0.18.0

package/README.md

@@ -6,17 +6,26 @@ A second install path also exists and is fully supported: `/plugin install <plug
 
 ## Usage
 
-From the root of the project you want to bootstrap:
+From the root of the project you want to bootstrap, pick a harness from the interactive menu:
 
 ```sh
-npx @nurix/etna code
+npx @nurix/etna
+```
+
+…or install one directly by name:
+
+```sh
+npx @nurix/etna --name=code
 ```
 
 After this completes:
 
 ```
 your-project/
-├── CLAUDE.md              ← harness policy (your existing file → CLAUDE.md.bak.<ISO>)
+├── CLAUDE.md              ← harness policy (non-git repo: existing file → CLAUDE.md.bak.<ISO>)
+├── .prettierrc.json       ← markdown formatting (proseWrap: never)
+├── .prettierignore
+├── .vscode/settings.json  ← editor settings (markdown formatter on save)
 └── .claude/
     ├── skills/            ← documentation, boundary, distiller, brainstorm, workflow-mapper
     ├── agents/            ← harness-manager, spec-mode, brainstorm, maintenance, change-review, performance-review
@@ -28,7 +37,7 @@ your-project/
 
 That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up the project-scoped agents/skills/rules on its next session start, and the hooks wire in through `.claude/settings.json`.
 
-Re-run `npx @nurix/etna code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. The previous `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>`. Because the new `harness.json` carries the installed `{version, epoch, digest}`, a re-run that's ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as an upgrade.
+Re-run `npx @nurix/etna --name=code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. In a git repo the previous `CLAUDE.md` is overwritten in place (recover it with `git checkout CLAUDE.md`); outside a git repo it's backed up to `CLAUDE.md.bak.<ISO-timestamp>`. Because the new `harness.json` carries the installed `{version, epoch, digest}`, a re-run that's ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as an upgrade.
 
 ## After install: bootstrap the harness
 

package/bin/etna.js

@@ -43,15 +43,16 @@ function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
-// Boxed list of installable harnesses, for --help and the non-interactive no-arg path.
+// Boxed list of installable harnesses (name + description), for --help and error paths.
 function printHarnessList(harnesses) {
     const entries = Object.entries(harnesses);
     if (!entries.length) {
         p.log.warn('No harnesses are bundled. Run `npm run build:data` from the package root.');
         return;
     }
+    const width = Math.max(...entries.map(([folder]) => folder.length));
     const lines = entries.map(
-        ([folder, plugin]) => `${folder}${plugin && plugin !== folder ? `  (plugin: ${plugin})` : ''}`,
+        ([folder, meta]) => `${folder.padEnd(width)}${meta?.description ? `  ${meta.description}` : ''}`,
     );
     p.note(lines.join('\n'), 'Available harnesses');
 }
@@ -216,35 +217,32 @@ function mergeHooks(targetDir, bundledHooksJson) {
     return added;
 }
 
-// Resolve the harness to install: the positional arg, or — in a TTY — an interactive
-// pick. Returns the chosen folder name, or null if the user cancels / can't be prompted.
-async function resolveHarnessName(positional, harnesses) {
+// Resolve the harness to install: the --name value, or — in a TTY — an interactive pick
+// showing each harness's description. Returns the chosen folder, or null on cancel.
+async function resolveHarnessName(name, harnesses) {
     const names = Object.keys(harnesses);
-    if (positional) {
-        if (!harnesses[positional]) {
-            p.log.error(`Unknown harness '${positional}'.`);
+    if (name !== null) {
+        if (!name || !harnesses[name]) {
+            p.log.error(name ? `Unknown harness '${name}'.` : 'Empty --name value.');
             printHarnessList(harnesses);
-            p.outro('Pick one of the harnesses above.');
+            p.outro('Pass --name=<harness> with one of the names above.');
             process.exit(1);
         }
-        return positional;
+        return name;
     }
     if (!isInteractive()) {
-        p.log.error('No harness specified, and not running in an interactive terminal.');
+        p.log.error('No --name given, and not running in an interactive terminal.');
         printHarnessList(harnesses);
-        p.outro('Re-run as `npx @nurix/etna <harness-name>`.');
+        p.outro('Re-run as `npx @nurix/etna --name=<harness>`.');
         process.exit(1);
     }
     const choice = await p.select({
         message: 'Which harness do you want to install here?',
-        options: names.map((folder) => {
-            const plugin = harnesses[folder];
-            return {
-                value: folder,
-                label: folder,
-                hint: plugin && plugin !== folder ? `plugin: ${plugin}` : undefined,
-            };
-        }),
+        options: names.map((folder) => ({
+            value: folder,
+            label: folder,
+            hint: harnesses[folder]?.description || undefined,
+        })),
     });
     if (p.isCancel(choice)) {
         p.cancel('Cancelled — nothing installed.');
@@ -273,7 +271,7 @@ async function installHarness(harnessName, harnesses) {
     const versionTag = harnessMeta.version ? ` v${harnessMeta.version}` : '';
     // The underlying plugin's name — may differ from the harness name, and several
     // harnesses may share it. Used only for legacy marketplace-entry cleanup.
-    const pluginName = harnessMeta.name || harnesses[harnessName] || harnessName;
+    const pluginName = harnessMeta.name || harnesses[harnessName]?.plugin || harnessName;
 
     const spin = p.spinner();
     spin.start(`Installing ${harnessName}${versionTag} into ${targetDir}`);
@@ -346,32 +344,62 @@ async function installHarness(harnessName, harnesses) {
 
     p.outro(
         `${harnessName}${versionTag} ready in ${targetDir}. ` +
-            `Re-run \`npx @nurix/etna ${harnessName}\` anytime to refresh harness content.`,
+            `Re-run \`npx @nurix/etna --name=${harnessName}\` anytime to refresh harness content.`,
     );
 }
 
+// Parse argv. `--name=<harness>` / `--name <harness>` selects a harness; -h/--help shows
+// help; any other bare token is the dropped positional form (a breaking change in 0.18.0).
+function parseArgs(args) {
+    let name = null;
+    let help = false;
+    let positional = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-h' || a === '--help') help = true;
+        else if (a.startsWith('--name=')) name = a.slice('--name='.length);
+        else if (a === '--name') name = args[++i] ?? '';
+        else if (!a.startsWith('-') && positional === null) positional = a;
+    }
+    return { name, help, positional };
+}
+
 async function main(args) {
     const idx = loadHarnessIndex();
     const harnesses = idx.harnesses || {};
+    const { name, help, positional } = parseArgs(args);
 
-    if (args.includes('-h') || args.includes('--help')) {
+    if (help) {
         p.intro('@nurix/etna — Nurix harness installer');
-        p.log.message('Usage: npx @nurix/etna [harness-name]');
+        p.log.message(
+            'Usage:\n' +
+                '  npx @nurix/etna                   pick a harness from the menu\n' +
+                '  npx @nurix/etna --name=<harness>  install that harness directly',
+        );
         printHarnessList(harnesses);
-        p.outro('Run with a name to install, or with no name to pick interactively.');
+        p.outro('No args → interactive menu. --name=<harness> → direct install.');
         return;
     }
 
-    const positional = args.find((a) => !a.startsWith('-'));
-
     p.intro('@nurix/etna — Nurix harness installer');
 
+    // Breaking change (0.18.0): the positional form `etna <harness>` was replaced by
+    // `--name=<harness>`. Fail loudly with the new syntax rather than silently misfiring.
+    if (positional && name === null) {
+        p.log.error(
+            `Positional arguments are no longer supported. Install with \`npx @nurix/etna --name=${positional}\`.`,
+        );
+        printHarnessList(harnesses);
+        p.outro('Use --name=<harness> to install, or no args to pick from the menu.');
+        process.exit(1);
+    }
+
     const boot = p.spinner();
     boot.start('Starting up');
     await sleep(2000);
     boot.stop('Ready');
 
-    const harnessName = await resolveHarnessName(positional, harnesses);
+    const harnessName = await resolveHarnessName(name, harnesses);
     if (!harnessName) return; // user cancelled the interactive pick
 
     await installHarness(harnessName, harnesses);

package/data/harness-index.json

@@ -1,10 +1,25 @@
 {
-    "fingerprint": "50dc8734b7ee",
+    "fingerprint": "2a8b6a3ea74d",
     "harnesses": {
-        "code": "code-fable",
-        "code-fable": "code-fable",
-        "discover": "discover",
-        "hr": "hr",
-        "kb-agi": "kb-agi"
+        "code": {
+            "plugin": "code-fable",
+            "description": "Nurix code-project harness"
+        },
+        "code-fable": {
+            "plugin": "code-fable",
+            "description": "Nurix code-project harness"
+        },
+        "discover": {
+            "plugin": "discover",
+            "description": "Product Discovery harness"
+        },
+        "hr": {
+            "plugin": "hr",
+            "description": "Hiring / AI-Steering Evaluation harness"
+        },
+        "kb-agi": {
+            "plugin": "kb-agi",
+            "description": "self-improving knowledge-base harness"
+        }
     }
 }

package/data/harnesses/code/agents/harness-manager.md

@@ -15,7 +15,7 @@ Reconcile is **declarative, not a migration ladder.** You converge to the *curre
 
 ## The two version layers (don't confuse them)
 
-- The **CLI** (`npx @nurix/etna code`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
+- The **CLI** (`npx @nurix/etna --name=code`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
 - **You** reconcile the *repo's authored data* — the `docs/` tree — to match that engine.
 
 The upgrade story is the two run back-to-back: install refreshes the engine → you reconcile the docs to it.
@@ -37,7 +37,7 @@ You never edit a doc for content fidelity (that is `maintenance`); `maintenance`
 ## Before starting
 
 1. Verify a **root `CLAUDE.md` exists** before any reconcile. If absent, **refuse** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconcile against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a gate.
-2. Resolve the **installed harness epoch** — read it from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx @nurix/etna code`, then retry. The resolved epoch is the target.
+2. Resolve the **installed harness epoch** — read it from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx @nurix/etna --name=code`, then retry. The resolved epoch is the target.
 3. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter. Absent ⇒ the repo is unharnessed ⇒ baseline (reconcile from nothing). Equal to installed ⇒ report and stop, **except** when re-invoked for the Step 6 module proposal: the version is already current from your first pass, so skip the stop and go straight to Step 6. (Health asked ⇒ run Health.) Behind ⇒ reconcile forward.
 4. If `docs/memory/harness-manager.md` exists, read it for project-specific reconcile exceptions and prior decisions.
 
@@ -158,7 +158,7 @@ Confirm all mandated files exist; `structure.md` carries the current `harness-ve
 Conformance, not fidelity. Report a table; fix nothing destructively without asking.
 
 - **Version currency** — `harness-version` present in `structure.md` and equal to installed? If behind/absent → recommend Reconcile. (This is the *repo-vs-installed* gap — it self-heals once the consumer reinstalls and re-runs you. The next two checks catch what reinstall *hasn't* happened yet, or was bypassed by a hand-edit.)
-- **Published-version currency** *(advisory, network)* — the installed `.claude/harness.json` records the kit's `version`; the published kit may have moved past it. Attempt `npm view @nurix/etna version` (the kit is a restricted package — needs npm auth + network). **Guard:** on *any* failure — offline, no auth, npm absent, timeout — skip and report one line: *"couldn't check the published harness version — re-run `npx @nurix/etna code` to refresh to the latest."* On success, compare the published version against `.claude/harness.json`'s `version`; if published is ahead, recommend re-running the CLI to pull the newer kit. Never a gate, never blocks.
+- **Published-version currency** *(advisory, network)* — the installed `.claude/harness.json` records the kit's `version`; the published kit may have moved past it. Attempt `npm view @nurix/etna version` (the kit is a restricted package — needs npm auth + network). **Guard:** on *any* failure — offline, no auth, npm absent, timeout — skip and report one line: *"couldn't check the published harness version — re-run `npx @nurix/etna --name=code` to refresh to the latest."* On success, compare the published version against `.claude/harness.json`'s `version`; if published is ahead, recommend re-running the CLI to pull the newer kit. Never a gate, never blocks.
 - **Kit build fingerprint (digest)** *(informational)* — `.claude/harness.json` carries a `digest`: a deterministic fingerprint of the exact kit **build** the consumer installed (`build-data` computes it over the shipped bundle). Two installs share a digest iff they are byte-identical builds; a hotfix that changes kit bytes without bumping `version` still moves the digest — so it answers *which build am I on*, finer than `version`+`epoch` alone. **Don't recompute it over `.claude/` to self-check:** the installed layout is a superset of the build (the project `CLAUDE.md` sits at the repo root, `.claude/` adds `settings.json`/`harness.json`/local rule files), so paths and file sets differ **by design** — a recompute would never match. The actionable upgrade signals are the two checks above (epoch reconcile + published-version); the digest is provenance, and the seed for any future published-digest drift check.
 - **Scaffold completeness** — every mandated file present.
 - **Dissolved-version residue** — any `operations/guardrails.md`, repo-wide `docs/pillars/`, `architecture/overview.md`, a persisted `docs/boundaries/` tree, or other old-shape artifact lingering.

package/data/harnesses/code/harness.json

@@ -8,5 +8,5 @@
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "da02e3f9ca11"
+  "digest": "a897772819ce"
 }

package/data/harnesses/code-fable/agents/harness-manager.md

@@ -15,7 +15,7 @@ Reconcile is **declarative, not a migration ladder.** You converge to the *curre
 
 ## The two version layers (don't confuse them)
 
-- The **CLI** (`npx @nurix/etna code`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
+- The **CLI** (`npx @nurix/etna --name=code`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
 - **You** reconcile the *repo's authored data* — the `docs/` tree — to match that engine.
 
 The upgrade story is the two run back-to-back: install refreshes the engine → you reconcile the docs to it.
@@ -37,7 +37,7 @@ You never edit a doc for content fidelity (that is `maintenance`); `maintenance`
 ## Before starting
 
 1. Verify a **root `CLAUDE.md` exists** before any reconcile. If absent, **refuse** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconcile against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a gate.
-2. Resolve the **installed harness epoch** — read it from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx @nurix/etna code`, then retry. The resolved epoch is the target.
+2. Resolve the **installed harness epoch** — read it from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx @nurix/etna --name=code`, then retry. The resolved epoch is the target.
 3. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter. Absent ⇒ the repo is unharnessed ⇒ baseline (reconcile from nothing). Equal to installed ⇒ report and stop, **except** when re-invoked for the Step 6 module proposal: the version is already current from your first pass, so skip the stop and go straight to Step 6. (Health asked ⇒ run Health.) Behind ⇒ reconcile forward.
 4. If `docs/memory/harness-manager.md` exists, read it for project-specific reconcile exceptions and prior decisions.
 
@@ -158,7 +158,7 @@ Confirm all mandated files exist; `structure.md` carries the current `harness-ve
 Conformance, not fidelity. Report a table; fix nothing destructively without asking.
 
 - **Version currency** — `harness-version` present in `structure.md` and equal to installed? If behind/absent → recommend Reconcile. (This is the *repo-vs-installed* gap — it self-heals once the consumer reinstalls and re-runs you. The next two checks catch what reinstall *hasn't* happened yet, or was bypassed by a hand-edit.)
-- **Published-version currency** *(advisory, network)* — the installed `.claude/harness.json` records the kit's `version`; the published kit may have moved past it. Attempt `npm view @nurix/etna version` (the kit is a restricted package — needs npm auth + network). **Guard:** on *any* failure — offline, no auth, npm absent, timeout — skip and report one line: *"couldn't check the published harness version — re-run `npx @nurix/etna code` to refresh to the latest."* On success, compare the published version against `.claude/harness.json`'s `version`; if published is ahead, recommend re-running the CLI to pull the newer kit. Never a gate, never blocks.
+- **Published-version currency** *(advisory, network)* — the installed `.claude/harness.json` records the kit's `version`; the published kit may have moved past it. Attempt `npm view @nurix/etna version` (the kit is a restricted package — needs npm auth + network). **Guard:** on *any* failure — offline, no auth, npm absent, timeout — skip and report one line: *"couldn't check the published harness version — re-run `npx @nurix/etna --name=code` to refresh to the latest."* On success, compare the published version against `.claude/harness.json`'s `version`; if published is ahead, recommend re-running the CLI to pull the newer kit. Never a gate, never blocks.
 - **Kit build fingerprint (digest)** *(informational)* — `.claude/harness.json` carries a `digest`: a deterministic fingerprint of the exact kit **build** the consumer installed (`build-data` computes it over the shipped bundle). Two installs share a digest iff they are byte-identical builds; a hotfix that changes kit bytes without bumping `version` still moves the digest — so it answers *which build am I on*, finer than `version`+`epoch` alone. **Don't recompute it over `.claude/` to self-check:** the installed layout is a superset of the build (the project `CLAUDE.md` sits at the repo root, `.claude/` adds `settings.json`/`harness.json`/local rule files), so paths and file sets differ **by design** — a recompute would never match. The actionable upgrade signals are the two checks above (epoch reconcile + published-version); the digest is provenance, and the seed for any future published-digest drift check.
 - **Scaffold completeness** — every mandated file present.
 - **Dissolved-version residue** — any `operations/guardrails.md`, repo-wide `docs/pillars/`, `architecture/overview.md`, a persisted `docs/boundaries/` tree, or other old-shape artifact lingering.

package/data/harnesses/code-fable/harness.json

@@ -8,5 +8,5 @@
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "c62c79b3aff1"
+  "digest": "7ce2d78b5ead"
 }

package/data/harnesses/hr/CLAUDE.md

@@ -24,7 +24,7 @@ mistake, the redirect that pulled it off a bad path. Turn count, prompt length,
 ## Step 0 — first run
 
 If the `interview-eval` skill isn't resolvable (no `.claude/skills/interview-eval/`), this project isn't set
-up — tell the user to run `npx @nurix/etna hr` (or point you at the skill) before continuing. Confirm
+up — tell the user to run `npx @nurix/etna --name=hr` (or point you at the skill) before continuing. Confirm
 `python3` is on PATH; the extractor is stdlib-only and needs nothing else.
 
 ## Step 1 — intake interview

package/data/harnesses/hr/harness.json

@@ -8,5 +8,5 @@
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "95bc2ce3024d"
+  "digest": "c1632f70fcdb"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.17.1",
+    "version": "0.18.0",
     "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": {