@nurix/etna 0.18.10 → 0.18.12

package/data/harnesses/etna/rules/general.md

@@ -0,0 +1,86 @@
+# General Standards
+
+## Runtime Versions
+
+- **Node.js:** 22 LTS (latest)
+- **Package manager:** detect from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm). Don't hardcode one.
+- **PostgreSQL:** 17 · **Redis:** 7.x (latest)
+
+## Recommended Packages
+
+No alternatives. Just use these.
+
+| Package                  | Version   | Use                    | Don't use                  |
+| ------------------------ | --------- | ---------------------- | -------------------------- |
+| react                    | ^19.2.3   | UI components          | -                          |
+| vite                     | ^8.0.0    | Build tool, dev server | webpack, CRA               |
+| tailwindcss              | ^4.1.18   | Styling                | styled-components          |
+| @vitejs/plugin-react-swc | ^4.2.2    | JSX compilation        | @vitejs/plugin-react       |
+| react-router-dom         | ^7.11.0   | Routing                | -                          |
+| @reduxjs/toolkit         | ^2.11.2   | State management       | zustand, jotai             |
+| react-redux              | ^9.2.0    | Redux React bindings   | -                          |
+| axios                    | ^1.13.2   | HTTP requests          | fetch                      |
+| date-fns                 | ^4.1.0    | Date formatting        | moment, dayjs              |
+| @dnd-kit/core            | ^6.3.1    | Drag and drop          | react-beautiful-dnd        |
+| motion                   | ^12.23.26 | Animations             | react-spring               |
+| sonner                   | ^2.0.7    | Toast notifications    | react-toastify             |
+| react-window             | ^2.2.3    | List virtualization    | react-virtualized          |
+| nanoid                   | ^5.1.6    | ID generation          | uuid                       |
+| express                  | ^5.2.1    | HTTP server            | fastify, koa               |
+| drizzle-orm              | latest    | Database ORM           | prisma, sequelize, typeorm |
+| drizzle-kit              | latest    | Schema tooling         | -                          |
+| zod                      | ^4.2.1    | Schema validation      | yup, joi                   |
+| jose                     | ^6.1.3    | JWT handling           | jsonwebtoken               |
+| microdiff                | ^1.5.0    | JSON object diffing    | deep-diff, just-diff       |
+| react18-json-view        | ^0.2.9    | JSON tree view         | react-json-view            |
+| @tiptap/react            | ^3.11.1   | Rich text editor       | slate, quill, draft-js     |
+| shiki                    | ^3.22.0   | Syntax highlighting    | prism, highlight.js        |
+| lucide-react             | ^0.562.0  | Icons                  | react-icons, heroicons     |
+| @pdfme/generator         | ^5.5.8    | PDF generation         | jspdf, pdfkit              |
+| cmdk                     | ^1.1.1    | Command palette        | kbar, ninja-keys           |
+| @monaco-editor/react     | ^4.7.0    | Code editor            | codemirror, ace            |
+| localforage              | ^1.10.0   | Client-side storage    | idb, dexie                 |
+| react-markdown           | ^10.1.0   | Markdown rendering     | marked, markdown-it        |
+| fast-deep-equal          | ^3.1.3    | Deep equality checks   | lodash.isEqual             |
+| @ngneat/falso            | latest    | Fake data generation   | @faker-js/faker, chance    |
+| pino                     | ^10.1.0   | Logging                | winston                    |
+
+## Frontend
+
+Tailwind v4 + shadcn-based UI; conventions below.
+
+- **Build every UI through the `frontend-design` skill** — route the brief through it instead of hand-rolling layouts; it owns the archetype, personality tokens, and `@nurix/components` wiring.
+- **Light mode is the default** — design for the light theme as the default; dark mode is opt-in, never the default.
+- **@nurix/\* are restricted-scope npm packages** — installed from the npm registry, auto-authed by a read token in `~/.npmrc`. Just attempt the install; the token authenticates you automatically. Don't pre-empt or second-guess it. If the install actually fails, flag it to the user — never reach for alternatives, a substitute package, or `npm login`.
+- **@nurix/components** — the UI component library (restricted-scope npm package, pre-built); import by subpath, e.g. `@nurix/components/button`.
+- No components.json / shadcn CLI scaffold (.tsx, not .jsx) — consume the prebuilt library; never `npx shadcn add`.
+- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin react / react-dom / react/jsx-runtime / react/jsx-dev-runtime to the app's single copy via `resolve.alias` (@nurix/\* ship nested react — keep one hook dispatcher).
+- Tailwind v4, CSS-only (no tailwind.config.js, no PostCSS): styling runs through the `@tailwindcss/vite` plugin.
+- CSS entry `globals.css`, imports in order — `@import "./personality.css"` (token source) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
+- Tokens: CSS vars in `:root, :root[data-theme="light"]` + the archetype selector `[data-style="…"]` (personality.css), consumed as semantic Tailwind tokens (bg-card, text-foreground). Honor the archetype's radius/theme decisions (e.g. re-assert `--radius-*` to 0 for a flat archetype; add `@custom-variant dark` only if the project opts into dark mode, and keep light as the default). The library bundles class-variance-authority, clsx, tailwind-merge.
+- Plus general styling rules (spacing in 2/4/6/8, object-cover, truncate, motion, color tokens — never hardcoded hex in components).
+
+## Express 5.x
+
+```javascript
+app.use(cors({ origin: process.env.FRONTEND_URL }));
+app.use(compression());
+app.use(express.json({ limit: '10mb' }));
+app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+```
+
+- Middleware order: body parsers → custom middleware → routes → error handlers (centralized, last). Auth via middleware. Use Express Router for modular routes.
+
+## API Response Format
+
+```json
+{
+  "status": 1,
+  "message": "Message sent successfully",
+  "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+Error: `{ "status": 0, "message": "Error description", "data": null }`
+
+HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/etna/rules/kb.md

@@ -0,0 +1,13 @@
+# kb.md — Patterns for Obsidian-like Folders
+
+Conventions for any folder that is majority markdown — `docs/`, `research/`, an Obsidian vault, or any knowledge base. Rules grow over time; append new ones below.
+
+## Rules
+
+### 1. Every topic gets a `Readme.md`
+
+When you start documenting a topic, create `Readme.md` as the folder's landing page. Don't use `index.md` or unscoped filenames — `Readme.md` is what readers and tools (GitHub, Obsidian) look for first, and it makes the folder self-introducing.
+
+### 2. Always link documents to each other
+
+When one document references an idea, concept, or topic covered in another, link to it. Wikilinks (`[[other-doc]]`) inside Obsidian-native vaults; relative markdown links (`[label](../other-doc.md)`) elsewhere. If you mention it, you link it — that's how the folder becomes a knowledge graph instead of a pile of files.

package/data/harnesses/etna/rules/nomenclature.md

@@ -0,0 +1,41 @@
+# Nomenclature Guidelines
+
+## Naming Guidelines
+
+- Use descriptive names that reveal intent, purpose, and usage
+- Names should explain why something exists and how it's used
+- Favor clarity over brevity
+- Maintain consistency within the codebase
+- Avoid abbreviations unless they're universally understood
+
+## Naming Styles
+
+- Variables : Use nouns or noun phrases. Examples: `userData`, `firstName`, `paymentStatus`, `configOptions`
+- Functions & Methods : Use verbs or verb phrases that describe the action. Examples: `calculateTotal`, `getUserInfo`, `validateInput`, `sendNotification`
+- Boolean Variables : Prefix with is**, has**, can**, or should**. Examples: `isValid`, `hasPermission`, `canEdit`, `shouldRefresh`
+- Arrays : Use plural nouns. Examples: `users`, `productList`, `errorMessages`, `activeConnections`
+- Classes & Components : Use singular nouns or noun phrases. Examples: `RequestHandler`, `UserProfile`, `PaymentProcessor`, `DataValidator`
+- Constants : Use uppercase with meaningful names. Examples: `DEFAULT_TIMEOUT`, `API_BASE_URL`, `MAX_RETRY_COUNT`, `COLOR_PRIMARY`
+- Event Handlers : Use Prefix with handle or on. Examples: `handleSubmit`, `onUserLogin`, `handleInputChange`, `onPageLoad`
+- Interfaces & Types : Use Consider prefixing with I for interfaces (if preferred). Examples: `IUserData`, `IConfigOptions`, `AuthResponse`, `RequestParams`
+- Promises & Async Functions : Use Consider using future tense or suffixes like Async. Examples: `fetchUserData`, `getUserProfileAsync`, `loadConfigAsync`, `processPayment`
+- File & Folder Structure : Use lowercase with descriptive names. Group by feature or function type. Example: `auth/login_service.js`
+
+## Casing Styles
+
+- camelCase : Used in Variables, function names, method names, property names. Examples: `userData`, `calculateTotal`, `firstName`, `isValidEmail`
+- PascalCase : Used in Class names, component names, type definitions. Examples: `UserProfile`, `DataService`, `AuthProvider`, `RequestHandler`
+- snake_case : Used in File names, folder names. Examples: `user_service`, `api_utils`, `auth_middleware`, `data_models`
+- UPPER_SNAKE_CASE : Used in Constants, environment variables. Examples: `MAX_RETRY_COUNT`, `API_KEY`, `DEFAULT_TIMEOUT`, `COLOR_PRIMARY`
+- kebab-case : Used in URLs, CSS class names, HTML IDs. Examples: `nav-container`, `user-profile`, `button-primary`, `form-wrapper`
+
+## Database
+
+Naming for D1 tables, columns, indexes, and their Drizzle mirrors. (For column **types** — PK shape, timestamp columns — see the Cloudflare D1 Schema rule, not here; this section governs names only.)
+
+- **Tables** : snake_case. Entity / hub tables use the plural noun for the thing they hold. Examples: `users`, `apps`, `devices`, `services`.
+- **Junction (M:N) tables** : name a many-to-many join `<entityA>_<entityB>_map` — **always**, even when the join carries its own columns (a `role`, a secret, a status). The `_map` suffix is the signal that a row is a relationship, not an entity; extra attributes on the join do **not** earn it a standalone noun. Use the **singular** stem of each side, owning/anchor entity first (mirror the existing tables — `app_*`). Examples: `app_user_map` (apps ⨯ users), `app_device_map` (apps ⨯ devices), `app_service_map` (apps ⨯ services).
+  - ❌ Don't invent a "nice" noun for a junction — no `members`, `installs`, `memberships`, `enrolments`. A reviewer should read the table name and know both sides and that it's a join.
+- **Columns** : snake_case. Foreign keys are `<entity>_id` (`user_id`, `app_id`, `device_id`, `service_id`). Booleans follow the boolean rule (`is_*`/`has_*`); timestamps are `created_at` / `updated_at`.
+- **Indexes** : `<table>_<col(s)>_idx`; unique indexes `<table>_<col(s)>_unique`. The composite unique on a junction reads `<table>_<colA>_<colB>_unique` — e.g. `app_user_map_app_user_unique`, `app_device_map_device_app_unique`.
+- **Drizzle mirror** : the exported table object is the camelCase of the snake_case table name (`app_user_map` → `appUserMap`); column TS properties are the camelCase of the column (`created_at` → `createdAt`, `service_key` → `serviceKey`). The snake_case string passed to `sqliteTable("…")` and every index name must match `seed/init.sql` exactly (the G1 schema-parity boundary).

package/data/harnesses/etna/rules/npm-cli.md

@@ -0,0 +1,88 @@
+# npm CLI Design — the `@nurix/*` pattern
+
+Conventions for building a distributable Nurix command-line tool, distilled from the two we ship: **`@nurix/etna`** (`packages/cli/` here — the harness installer, plain ESM JS) and **`@nurix/apollo`** (`~/dev/apollo/packages/cli/` — the service-bootstrap CLI, TypeScript → `dist/`). When you build or change a `@nurix` CLI, follow these. Where the two diverge, both variants are noted as valid.
+
+## 1. Packaging
+
+- **Scoped + restricted.** Name is `@nurix/<tool>`; `"publishConfig": { "access": "restricted" }`. Never publish public.
+- **ESM only** — `"type": "module"`.
+- **`bin` maps the command to its entry** — `{ "etna": "bin/etna.js" }` / `{ "apollo": "dist/index.js" }`. The entry has a `#!/usr/bin/env node` shebang.
+- **`files` is an allowlist** — ship only the runnable artifact: `["bin/", "data/", "README.md"]` (etna) or `["dist"]` (apollo). Never ship `src/`, tests, or the repo.
+- **`engines.node` ≥ 22** for new CLIs (matches the workspace Node baseline).
+- **One version source** — read the running version from `package.json` at startup; don't hardcode it elsewhere.
+- **Minimal deps.** Both ship with essentially one runtime dep (`@clack/prompts`); apollo adds `commander` + `ajv`. Keep the dependency surface tiny — it's installed on every `npx` run.
+
+## 2. Distribution: `npx`-first, install into the project, never globally
+
+- The canonical entry is **`npx @nurix/<tool>`** — no global install step, no marketplace, no plugin-enablement dance. The user runs `npx`, the tool does its job in the current directory.
+- **The CLI writes ONLY inside the folder it was invoked in.** An installer run as `npx @nurix/etna` in a project must touch only that project tree — never `$HOME`, never `~/.claude`, never any shared/user-level location. Reaching outside the target folder is surprising, clobber-prone, and wrong. (This is a hard-won rule: an earlier etna build installed agents to `~/.claude/agents/` and it was reverted precisely for this reason.)
+- **Idempotent refresh.** Re-running the CLI re-pulls the latest and overwrites the files it owns (force), while leaving anything the user authored untouched. "Re-run anytime to refresh" must always be safe.
+
+## 3. Always run the latest — self-update by re-exec
+
+**The problem:** `npx` caches aggressively. A bare `npx @nurix/<tool>` can keep running a *stale* unpacked copy long after a newer version is published (npm's packument cache resolves an old `latest`, and npx reuses the matching install). Users shouldn't have to remember `@latest`.
+
+**The mechanism** (etna's `selfUpdateOrReexec()`, run before anything else): on startup, ask the registry for the latest version; if this copy is behind, re-exec the latest and hand off.
+
+```js
+function selfUpdateOrReexec() {
+    if (process.env.TOOL_SELFUPDATED || process.env.TOOL_NO_SELFUPDATE) return;
+    const here = readJson(join(pkgRoot, 'package.json')).version;
+    if (!here) return;
+    const view = spawnSync('npm', ['view', '@nurix/<tool>', 'version', '--prefer-online'], { encoding: 'utf8' });
+    const latest = view.status === 0 ? (view.stdout || '').trim() : null;
+    if (!latest || latest === here) return;                 // current, offline, or unauthed → run this copy
+    const child = spawnSync('npx', ['-y', '--prefer-online', `@nurix/<tool>@${latest}`, ...process.argv.slice(2)],
+        { stdio: 'inherit', env: { ...process.env, TOOL_SELFUPDATED: '1' } });
+    if (!child.error) process.exit(child.status ?? 0);      // re-exec ran → hand off complete
+    // npx unavailable (child.error) → fall through and run this (older) copy.
+}
+```
+
+Required properties:
+
+- **`--prefer-online`** on both the `npm view` and the `npx` re-exec — defeats the metadata cache so npx fetches the fresh tarball.
+- **Loop guard** — set `<TOOL>_SELFUPDATED=1` in the child's env so the re-exec'd process doesn't try to update again.
+- **Opt-out** — `<TOOL>_NO_SELFUPDATE=1` skips the whole thing (CI, offline, or running an intentionally pinned/local-dev build). This is also how you test a local build.
+- **Degrade gracefully** — *any* failure (offline, unauthed, `npm`/`npx` missing, timeout) falls through to running the current copy. The update is a convenience, never a gate.
+- **Reuse existing npm auth** — the `npm view` rides the caller's npm credentials (the same auth that installed the restricted package); never prompt for login.
+
+## 4. Editing the user's files: own a delimited block, idempotently
+
+When the CLI must modify a file it doesn't own (`.env`, `settings.json`, `.gitignore`), it **owns only a delimited region** and rewrites that region in place — never the whole file.
+
+- apollo wraps its `.env` writes in a managed block:
+  `# >>> apollo:managed — do not edit by hand; the apollo CLI rewrites this block >>>` … `# <<< apollo:managed <<<`. Reads/merges/removes happen *inside* the markers; everything outside belongs to the user.
+- etna merges its hooks into `.claude/settings.json` and migrates/retires only its own prior entries.
+- Rewrites are **idempotent** (re-running converges to the same block) and **reversible** (logout/uninstall removes exactly the managed region).
+- If the block holds secrets, ensure `.gitignore` covers the file so they're never committed.
+
+## 5. Interactive when it can, flag-driven when it can't
+
+- Use **`@clack/prompts`** for the interactive path (TTY): intro/outro, spinners, notes.
+- When **not a TTY**, require explicit flags and fail loudly with the correct syntax rather than guessing — e.g. etna needs `--name=<harness>` outside a TTY, and a removed/renamed flag (the dropped positional form in 0.18.0) errors with the new syntax instead of silently misfiring.
+- A bare invocation in a TTY may present a menu; the same invocation headless must error, not hang.
+
+## 6. Detect the package manager from the lockfile
+
+When the CLI installs packages or runs scripts on the user's behalf, detect the manager: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm. Never hardcode one. (apollo's `detectPackageManager()`.)
+
+## 7. Publishing is CI-owned
+
+Publish from CI on push to `dev`/`main`, path-filtered to the CLI package — never `npm publish` by hand for a routine change.
+
+- **Two valid version models:**
+  - **Fingerprint auto-bump (etna):** the build stamps a content hash (`fingerprint`) of the shipped payload; CI bumps the **patch** automatically when the fingerprint changed, publishes, and tags. Never hand-bump for a content change — let the fingerprint drive it; hand-edit the version only for a deliberate minor/major.
+  - **Manual bump input (apollo):** a `workflow_dispatch` `bump` input (`patch`/`minor`/`major`) drives `npm version`.
+- **Common to both:**
+  - The bump commit message carries **`[skip ci]`** so the publish workflow doesn't re-trigger itself.
+  - `npm version --no-git-tag-version` (file-only), then commit + tag separately — `npm version` skips the git step when run in a subdirectory of the repo root.
+  - Push the bump back to the branch and tag with a **package-scoped prefix** (`v…` for etna, `apollo-v…` for apollo) via `git push origin HEAD:<ref> --follow-tags`.
+  - `prepack` / `prepublishOnly` builds the shipped artifact (`data/` via `build-data.js`, or `dist/` via `tsc`) so what's published always matches source.
+  - `registry-url: https://registry.npmjs.org` in the Node setup so `.npmrc` uses `$NODE_AUTH_TOKEN`.
+
+## 8. Robustness defaults
+
+- **Never hard-block on an advisory/network check.** Version currency, registry lookups, telemetry — all degrade to a one-line notice and continue.
+- **Restricted-scope auth is ambient** — the read token in `~/.npmrc` (or `$NODE_AUTH_TOKEN` in CI) authenticates installs and `npm view`. Just attempt the operation; never prompt for `npm login` or reach for a substitute package.
+- **Keep the hot path fast** — everything runs on every `npx`, so avoid heavy startup work beyond the self-update check.

package/data/harnesses/etna/skills/boundary/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: boundary
+description: Boundary diagnostic for implementation plans. Given a plan file, reads the source files the plan touches, identifies the application boundaries they participate in — the cross-cutting contracts (db schema, wire envelope, auth, events, env/config, …) where editing one side silently breaks the other — and reports whether the planned changes would violate any of them, severity-ranked, with suggested plan amendments. Read-only; the report lands in chat. Can also run against a diff or named code area instead of a plan. Triggers on "boundary check", "check this plan", "what could break", "impact analysis", "/boundary".
+---
+
+# Boundary Diagnostic
+
+You diagnose whether a plan's changes would break an application boundary.
+
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no compile-time link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green and breaks the other silently. Your job is to find those edges in the plan's path _before_ execution.
+
+[`references/boundary-taxonomy.md`](references/boundary-taxonomy.md) is the catalog of boundary types (~170 across persistence, wire/API, frontend, auth/tenancy, async/messaging, config/build, runtime/infra), with per-type severities and safe-change checklists. Read it first — it tells you what to look for; the code tells you what exists.
+
+## Run
+
+**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff / named code area for non-plan work. Everything below is identical either way; a diff's hunks stand in for the plan's steps.
+
+1. **Build the touch list.** Parse the plan's Proposed Changes: files to be created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+
+2. **Identify the boundaries in the touched code.** Read each touched file (and its immediate imports). Against the taxonomy, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
+
+3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`.
+
+4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or add a new cross-module edge? Severity:
+   - **CRITICAL** — can corrupt persisted data, or open an auth/money path.
+   - **HIGH** — silent cross-module breakage that would ship green.
+   - **MEDIUM** — drift-prone coupling (string-matched, duplicated constants).
+   - **LOW** — smell. Loud, immediately-visible breakage caps at HIGH.
+
+5. **Report in chat:**
+
+   ```
+   # Boundary check — {plan}
+
+   Touched files read: {N} · Boundaries identified: {N}
+   Violations: {N} ({critical}/{high}/{medium}/{low})
+
+   | # | Boundary | Planned change | Other side (file:line) | Severity |
+
+   ## Suggested plan amendments
+   ## Missing plan subsections
+   ```
+
+## Rules
+
+- **Read-only.** You never edit the plan, the code, or any doc. The user folds your amendments into the plan.
+- **Verify in source.** Never flag from plan text alone — read both sides of every boundary you report, and cite both as `file:line`.
+- **No consumer, no finding.** An intersection with no traced other side isn't a violation; at most note it as a new edge the plan introduces.
+- **A clean report is valid.** Zero violations means say so — don't pad.