@nurix/etna 0.1.1 → 0.1.2

package/README.md

@@ -1,35 +1,36 @@
 # @nurix/etna
 
-CLI to bootstrap a project with a Nurix harness. Installs a Claude Code plugin from the `nurixlabs/skills` marketplace and drops the harness's `CLAUDE.md` at the project root.
+CLI to bootstrap a project with a Nurix harness. Produces the same on-disk state as running
 
-See [`../../harness/README.md`](../../harness/README.md) for what a harness is.
+```
+/plugin marketplace add nurixlabs/skills
+/plugin install nurix-harness@nurixlabs
+```
+
+inside Claude Code, plus drops the harness's `CLAUDE.md` at the project root. See [`../../harness/README.md`](../../harness/README.md) for what a harness is and why the install model is designed this way.
 
 ## Usage
 
 From the root of the project you want to bootstrap:
 
 ```sh
-GITHUB_TOKEN=ghp_... npx @nurix/etna nurix-harness
+npx @nurix/etna nurix-harness
 ```
 
-After this completes, the directory contains:
+After this completes, three things have changed on disk:
 
 ```
 your-project/
-├── CLAUDE.md                              ← from harness/<folder>/CLAUDE.md (bundled in this package)
+├── CLAUDE.md                          ← bundled in this package; the harness's policy
 └── .claude/
-    ├── settings.json                      ← enabledPlugins updated
-    └── plugins/
-        └── nurix-harness/                 ← fetched from nurixlabs/skills/plugins/nurix-harness/
-            ├── .claude-plugin/plugin.json
-            ├── skills/{documentation, workflow-mapper, introspect}/
-            ├── agents/{change-review, contract-monitor, dep-health, git-history, maintenance, review, spec-mode}.md
-            ├── scripts/{build-ownership-index, check-doc-drift}.sh
-            ├── rules/{general, nomenclature}.md
-            └── README.md
+    └── settings.json                  ← enabledPlugins["nurix-harness@nurixlabs"] = true
+
+~/.claude/settings.json                ← extraKnownMarketplaces["nurixlabs"] registered
 ```
 
-Open Claude Code in the project; it will pick up the plugin on next start. If Claude Code is already running, run `/reload-plugins`.
+That's the entire footprint. Open Claude Code in the project; on next session start it resolves `nurix-harness@nurixlabs`, clones `nurixlabs/skills` into `~/.claude/plugins/marketplaces/`, fills the plugin cache at `~/.claude/plugins/cache/nurixlabs/nurix-harness/<version>/`, and loads the plugin. The CLI does not touch any of those Claude Code internals itself — that's deliberate (see [Installation goals](../../harness/README.md#installation-goals)).
+
+If Claude Code is already running, run `/reload-plugins`.
 
 ## Available harnesses
 
@@ -37,28 +38,21 @@ Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json
 
 | Plugin name | Harness folder in etna | What it ships |
 |---|---|---|
-| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — 7 audit agents, 3 workflow skills, 2 rules, 2 scripts |
-
-## Environment
-
-| Variable | Required | Purpose |
-|---|---|---|
-| `GITHUB_TOKEN` | Yes (while `nurixlabs/skills` is private) | Personal access token with `repo:read` scope. Access to `nurixlabs/skills` is the access control for the harness. |
-| `NURIX_SKILLS_REF` | No | Git ref to fetch from in `nurixlabs/skills`. Default `dev`. |
+| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — governance agents, baseline workflow skills, ownership/drift scripts |
 
 ## How it works
 
-1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder.
-2. Walks `nurixlabs/skills/plugins/<plugin-name>/` via the GitHub Contents API and downloads each file into `./.claude/plugins/<plugin-name>/`.
-3. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md`.
-4. Adds `<plugin-name>@nurixlabs: true` to `./.claude/settings.json` under `enabledPlugins`.
+1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder and the marketplace metadata.
+2. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md` (backing up any existing one to `CLAUDE.md.bak.<ISO-timestamp>`).
+3. Adds the marketplace entry to `~/.claude/settings.json` under `extraKnownMarketplaces`.
+4. Adds `<plugin-name>@<marketplace>: true` to `./.claude/settings.json` under `enabledPlugins`.
 
-Existing `CLAUDE.md` or plugin folder at the destination is renamed to `<name>.bak.<ISO-timestamp>` before install. Nothing is overwritten.
+No GitHub fetch. No `.claude/plugins/<name>/` folder. Claude Code's plugin resolver handles all of that on next launch.
 
 ## Why two sources
 
-- **Plugin content** comes from the marketplace (`nurixlabs/skills`) so it's always the latest CI-published version.
-- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. Harness policy changes warrant a package version bump.
+- **Plugin content** lives in the marketplace (`nurixlabs/skills`) and is fetched by Claude Code at session start — always the latest CI-published version.
+- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. A plugin cannot ship a project-root `CLAUDE.md` (Claude Code's plugin spec doesn't support it), so the CLI ships that half itself. Harness policy changes warrant a package version bump.
 
 ## Building / contributing
 
@@ -73,10 +67,4 @@ npm run build:data
 
 ## Publishing
 
-From `packages/cli/`:
-
-```sh
-npm publish --access restricted
-```
-
-The `publishConfig.access` is `restricted` so the scoped package is private by default.
+CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default.

package/bin/etna.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <plugin-name>` — install a Nurix harness into the current directory.
+// `npx @nurix/etna <plugin-name>` — bootstrap a Nurix harness in the current directory.
+// Produces the same on-disk state as running `/plugin marketplace add <repo>` followed by
+// `/plugin install <plugin>@<marketplace>` inside Claude Code, plus drops the harness's
+// CLAUDE.md at the project root. Claude Code's plugin resolver fills the cache on next launch.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -10,20 +14,17 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 const dataDir = join(pkgRoot, 'data');
 
-const SKILLS_REPO = 'nurixlabs/skills';
-const SKILLS_REF = process.env.NURIX_SKILLS_REF || 'dev';
-
 function usage() {
-    console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const idx = loadHarnessIndex();
+    console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const names = Object.keys(idx.plugins);
     if (names.length) {
-        console.log(`Available harnesses (plugin → harness folder):`);
-        for (const name of names) console.log(`  ${name.padEnd(20)} → harness/${idx.plugins[name]}`);
+        console.log(`Available harnesses (plugin → marketplace):`);
+        for (const name of names) {
+            console.log(`  ${name.padEnd(20)} → ${idx.marketplace.name}`);
+        }
     }
-    console.log(`\nEnvironment:`);
-    console.log(`  GITHUB_TOKEN          Required if ${SKILLS_REPO} is private (token with repo:read scope)`);
-    console.log(`  NURIX_SKILLS_REF      Git ref to fetch from (default: dev)`);
+    console.log(`\nMarketplace: ${idx.marketplace.source.repo} (github)`);
     console.log();
 }
 
@@ -40,54 +41,6 @@ function die(msg, code = 1) {
     process.exit(code);
 }
 
-function ghHeaders() {
-    const h = {
-        Accept: 'application/vnd.github+json',
-        'User-Agent': '@nurix/etna',
-        'X-GitHub-Api-Version': '2022-11-28',
-    };
-    if (process.env.GITHUB_TOKEN) h.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
-    return h;
-}
-
-// Recursively download a GitHub repo subdirectory into a local destination.
-async function fetchPluginFolder(pluginName, destDir) {
-    const apiUrl = `https://api.github.com/repos/${SKILLS_REPO}/contents/plugins/${pluginName}?ref=${SKILLS_REF}`;
-    await fetchDir(apiUrl, destDir);
-}
-
-async function fetchDir(apiUrl, destDir) {
-    const res = await fetch(apiUrl, { headers: ghHeaders() });
-    if (res.status === 401 || res.status === 403) {
-        die(
-            `GitHub returned ${res.status} for ${apiUrl}.\n` +
-                `${SKILLS_REPO} is private — set GITHUB_TOKEN (a personal access token with repo:read scope).\n` +
-                `  export GITHUB_TOKEN=ghp_...`,
-        );
-    }
-    if (res.status === 404) {
-        die(`Plugin not found in ${SKILLS_REPO}@${SKILLS_REF}. Has the marketplace publish pipeline run yet?`);
-    }
-    if (!res.ok) die(`GitHub API ${res.status}: ${await res.text()}`);
-
-    const items = await res.json();
-    mkdirSync(destDir, { recursive: true });
-
-    for (const item of items) {
-        const localPath = join(destDir, item.name);
-        if (item.type === 'dir') {
-            await fetchDir(item.url, localPath);
-        } else if (item.type === 'file') {
-            const dl = item.download_url;
-            if (!dl) die(`File ${item.path} has no download_url`);
-            const fileRes = await fetch(dl, { headers: ghHeaders() });
-            if (!fileRes.ok) die(`Failed to download ${item.path}: ${fileRes.status}`);
-            const buf = Buffer.from(await fileRes.arrayBuffer());
-            writeFileSync(localPath, buf);
-        }
-    }
-}
-
 // 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;
@@ -105,28 +58,42 @@ function isSymlink(path) {
     }
 }
 
-// Add pluginName to enabledPlugins in .claude/settings.json (creating the file if needed).
-// Uses the conventional shape `"plugin-name@marketplace": true`.
-function enablePlugin(targetDir, pluginName) {
-    const claudeDir = join(targetDir, '.claude');
-    mkdirSync(claudeDir, { recursive: true });
-    const settingsPath = join(claudeDir, 'settings.json');
-
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-        } catch (e) {
-            die(`Failed to parse existing ${settingsPath}: ${e.message}`);
-        }
+function readJson(path) {
+    if (!existsSync(path)) return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch (e) {
+        die(`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');
+}
+
+// Register the marketplace in ~/.claude/settings.json (extraKnownMarketplaces).
+// Mirrors what `/plugin marketplace add <owner>/<repo>` writes.
+function registerMarketplace(marketplace) {
+    const path = join(homedir(), '.claude', 'settings.json');
+    const settings = readJson(path);
+    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
+    settings.extraKnownMarketplaces[marketplace.name] = { source: marketplace.source };
+    writeJson(path, settings);
+    return path;
+}
+
+// Add `<plugin>@<marketplace>: true` to <target>/.claude/settings.json under enabledPlugins.
+// Mirrors what `/plugin install <plugin>@<marketplace>` writes at project scope.
+function enablePlugin(targetDir, pluginName, marketplaceName) {
+    const path = join(targetDir, '.claude', 'settings.json');
+    const settings = readJson(path);
     settings.enabledPlugins = settings.enabledPlugins || {};
-    const key = `${pluginName}@nurixlabs`;
+    const key = `${pluginName}@${marketplaceName}`;
     settings.enabledPlugins[key] = true;
-
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
-    return { settingsPath, key };
+    writeJson(path, settings);
+    return { path, key };
 }
 
 async function main(args) {
@@ -150,32 +117,28 @@ async function main(args) {
     }
 
     const targetDir = process.cwd();
-    const pluginDir = join(targetDir, '.claude', 'plugins', pluginName);
     const claudeMdDest = join(targetDir, 'CLAUDE.md');
+    const marketplace = idx.marketplace;
+    const fqKey = `${pluginName}@${marketplace.name}`;
 
-    console.log(`\nInstalling ${pluginName} (from harness/${harnessFolder}) into ${targetDir}`);
+    console.log(`\nInstalling ${fqKey} into ${targetDir}`);
 
-    // 1. Backup conflicts
-    const pluginBackup = backupIfExists(pluginDir);
-    if (pluginBackup) console.log(`  backed up existing plugin folder → ${pluginBackup}`);
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
 
-    // 2. Fetch plugin from nurixlabs/skills marketplace
-    console.log(`  fetching plugin from ${SKILLS_REPO}@${SKILLS_REF}…`);
-    await fetchPluginFolder(pluginName, pluginDir);
-    console.log(`  installed plugin → ${pluginDir}`);
-
-    // 3. Copy bundled CLAUDE.md to project root
     copyFileSync(bundledClaude, claudeMdDest);
     console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
 
-    // 4. Enable plugin in .claude/settings.json
-    const { settingsPath, key } = enablePlugin(targetDir, pluginName);
-    console.log(`  enabled '${key}' in ${settingsPath}`);
+    const marketplacePath = registerMarketplace(marketplace);
+    console.log(`  registered marketplace '${marketplace.name}' → ${marketplacePath}`);
+
+    const { path: enablePath } = enablePlugin(targetDir, pluginName, marketplace.name);
+    console.log(`  enabled '${fqKey}' → ${enablePath}`);
 
-    console.log(`\nDone. Open Claude Code in this directory; it will load the plugin on next start.`);
-    console.log(`Run /plugin to verify, or /reload-plugins if it's already running.\n`);
+    console.log(`\nDone. Open Claude Code in ${targetDir}.`);
+    console.log(
+        `It will fetch ${marketplace.source.repo}, install ${pluginName}, and load it on next session start.\n`,
+    );
 }
 
 main(process.argv.slice(2)).catch((e) => {

package/data/harness-index.json

@@ -1,4 +1,11 @@
 {
+    "marketplace": {
+        "name": "nurixlabs",
+        "source": {
+            "source": "github",
+            "repo": "nurixlabs/skills"
+        }
+    },
     "plugins": {
         "nurix-harness": "code"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Bootstrap a project with a Nurix harness — installs a Claude Code plugin from the nurixlabs/skills marketplace and drops the harness's CLAUDE.md at the project root.",
     "type": "module",
     "bin": {