@kiroku-solutions/kiroku-ai 0.1.4 → 0.2.1

package/README.md

@@ -3,8 +3,23 @@
 Interactive CLI that bootstraps **Kiroku AI Standards** ("AI Context as Code")
 into any project. It asks a few questions about your stack, downloads only the
 relevant skill files from the central [`Kiroku-Solutions/kiroku-ai-standards`](https://github.com/Kiroku-Solutions/kiroku-ai-standards)
-repository into a local `.ai-skills/` folder, and wires up the two-way sync
-GitHub Action.
+repository into the folders your chosen AI tool expects, and wires up the
+two-way sync GitHub Action.
+
+## Private-by-design: the npm package is just a loader
+
+The package published to npm contains **only a bootstrap loader** (`bin/`), not
+the CLI source. On first run the loader:
+
+1. Asks for a GitHub token **first** (env `KIROKU_AI_TOKEN`/`GH_TOKEN`, or
+   `~/.npmrc`, or an interactive prompt — saved to `~/.npmrc`).
+2. Downloads the real CLI (`CLI/src/**`, `CLI/templates/**`, `CLI/package.json`)
+   from the private SSOT repo via the GitHub API.
+3. Caches it under `~/.kiroku-ai/runtime/<ref>/` and runs `npm install` once.
+4. Runs the CLI. Subsequent runs reuse the cache (no token needed) — pass
+   `KIROKU_AI_REFRESH=1` to force a re-download.
+
+The CLI code and skills therefore never live on npm.
 
 ## Usage
 
@@ -30,27 +45,66 @@ pnpm --dir CLI start init
 
 | Command          | Description                                                                 |
 | ---------------- | --------------------------------------------------------------------------- |
-| `init`           | Guided stack builder; downloads skills and scaffolds `.ai-skills/`.         |
+| `init`           | Pick a setup mode, then download skills into the engine's folders.          |
 | `update`         | Re-resolves the recorded stack, re-downloads, and prunes removed skills.    |
-| `env [tool]`     | Switches the AI tool and (re)generates its pointer file. Updates lockfile.  |
+| `env [tool]`     | Switches the AI tool: **migrates the folders** and regenerates its pointer. |
+
+### Setup modes
+
+`init` starts by asking how much control you want:
+
+| Mode          | What it asks                                                                      |
+| ------------- | --------------------------------------------------------------------------------- |
+| **Quickstart**| Pick one predefined stack (see presets below), then just the AI tool.             |
+| **Guided**    | The classic stack questionnaire (scope → frontend → backend → db → deploy → devops).|
+| **Modular**   | Guided **plus** Architecture, Methodology and Development practices, and per-agent selection. |
+
+#### Quickstart presets
+
+| Preset id           | Stack                                   |
+| ------------------- | --------------------------------------- |
+| `nextjs-supabase`   | Next.js + Supabase (fullstack, Vercel)  |
+| `astro-fastapi`     | Astro + FastAPI (fullstack, Postgres)   |
+| `fastapi-supabase`  | FastAPI + Supabase (backend API)        |
+| `sveltekit-postgres`| SvelteKit + Postgres (fullstack, Vercel)|
+| `dotnet-postgres`   | .NET API + Postgres (backend)           |
+
+Presets live in [`src/presets.mjs`](./src/presets.mjs) — add or edit entries there.
+
+#### Engineering approach (Modular mode)
+
+The Modular mode also captures, records (in the lockfile) and writes into the
+pointer file an **Engineering approach** the AI must follow:
+
+- **Architecture** (single): `layered`, `modular-monolith`, `hexagonal`, `clean`,
+  `microservices`, `event-driven`, `cqrs`, `serverless`, `mvc` (or none).
+- **Methodology** (single): `scrum`, `kanban`, `scrumban`, `waterfall`, `xp`, `lean` (or none).
+- **Development practices** (multi): `tdd`, `bdd`, `atdd`, `sdd`, `ddd`.
+
+The matching docs come from `skills/architecture/`, `skills/methodology/` and
+`skills/practices/` in the SSOT and install under your tool's skills folder.
 
 ### AI environments
 
-During `init` you pick the AI tool the project targets. The CLI generates the
-matching "pointer" file so the tool auto-loads `.ai-skills/`:
+During `init` you pick the AI tool the project targets. The CLI installs into
+**that tool's native folder convention** and generates the matching "pointer"
+file so the tool auto-loads its skills. Tools without their own convention
+(Cursor, Copilot, Windsurf) use the generic `.agents/` + `skills/` fallback.
 
-| Tool          | Generated file                     |
-| ------------- | ---------------------------------- |
-| Claude Code   | `CLAUDE.md`                        |
-| Cursor        | `.cursor/rules/kiroku-ai.mdc`      |
-| GitHub Copilot| `.github/copilot-instructions.md`  |
-| OpenCode      | `AGENTS.md`                        |
-| Antigravity   | `AGENTS.md`                        |
-| Windsurf      | `.windsurf/rules/kiroku-ai.md`     |
+| Tool          | Pointer file                       | Agents folder      | Skills folder       |
+| ------------- | ---------------------------------- | ------------------ | ------------------- |
+| Claude Code   | `CLAUDE.md`                        | `.claude/agents/`  | `.claude/skills/`   |
+| Cursor        | `.cursor/rules/kiroku-ai.mdc`      | `.agents/`         | `skills/`           |
+| GitHub Copilot| `.github/copilot-instructions.md`  | `.agents/`         | `skills/`           |
+| OpenCode      | `AGENTS.md`                        | `.opencode/agents/`| `.opencode/skills/` |
+| Antigravity   | `GEMINI.md`                        | `.agent/agents/`   | `.agent/skills/`    |
+| Windsurf      | `.windsurf/rules/kiroku-ai.md`     | `.agents/`         | `skills/`           |
 
 Pointer files carry a `kiroku-ai:managed` marker — the CLI never overwrites or
 deletes a hand-written file you already had. Switch tools anytime with
-`kiroku-ai env`.
+`kiroku-ai env <tool>`; the installed skill/agent folders are moved to the new
+tool's convention automatically. The lockfile always lives in the engine-stable
+`.kiroku-ai/` folder.
 
 ### Options
 
@@ -70,20 +124,27 @@ deletes a hand-written file you already had. Switch tools anytime with
 | `KIROKU_AI_ORG`    | Override the GitHub org (default: `Kiroku-Solutions`).      |
 | `KIROKU_AI_REPO`   | Override the repo (default: `kiroku-ai-standards`).         |
 | `KIROKU_AI_REF`    | Override the default git ref.                               |
-| `KIROKU_AI_TOKEN`  | Read token — **required if the SSOT repo is private**.      |
+| `KIROKU_AI_TOKEN`  | Read token — **required to fetch the private CLI + skills**. |
+| `KIROKU_AI_REFRESH`| Force the loader to re-download the cached CLI runtime.      |
 | `KIROKU_AI_SOURCE` | Local path to an SSOT checkout — reads from disk instead of GitHub (for testing). |
 
 ## What it generates
 
+Folder names depend on the chosen AI tool (see the table above). Example for
+**Claude Code**:
+
 ```text
 your-project/
-├── .ai-skills/
-│   ├── global/ frontend/ backend/ infra-and-db/   # downloaded skills (do not edit)
-│   ├── proposals/                                  # propose skills company-wide
-│   ├── local/                                      # project-only AI rules (never synced)
-│   ├── README.md
-│   └── lockfile.json                              # prevents duplicate installs
-└── .github/workflows/kiroku-ai-sync.yml           # two-way sync action
+├── .claude/
+│   ├── skills/
+│   │   ├── global/ frontend/ backend/ infra-and-db/  # downloaded skills (do not edit)
+│   │   ├── proposals/                                 # propose skills company-wide
+│   │   ├── local/                                     # project-only AI rules (never synced)
+│   │   └── README.md
+│   └── agents/                                        # agent personas (Security Auditor, …)
+├── CLAUDE.md                                          # pointer file (auto-loaded by the tool)
+├── .kiroku-ai/lockfile.json                           # engine-stable; prevents duplicate installs
+└── .github/workflows/kiroku-ai-sync.yml               # two-way sync action
 ```
 
 ## How the stack maps to skills
@@ -101,18 +162,18 @@ The compatibility matrix lives in [`src/resolver.mjs`](./src/resolver.mjs). In s
 ## Architecture
 
 ```text
-bin/kiroku-ai.mjs      # executable shim
-src/
-  cli.mjs              # arg parsing + init orchestration
-  config.mjs           # org/repo/ref constants (+ env overrides)
+bin/kiroku-ai.mjs      # PUBLISHED loader: token-first, fetches src/ from private GitHub, caches, runs
+src/                   # NOT published to npm — fetched at runtime from the SSOT repo
+  cli.mjs              # arg parsing + init/update/env orchestration
+  config.mjs           # org/repo/ref constants, CONFIG_DIR, token resolution (+ env overrides)
   prompts.mjs          # @clack/prompts guided flow & compatibility constraints
   resolver.mjs         # stack -> skill selectors -> repo blob paths
   source.mjs           # dispatch: GitHub or local filesystem (KIROKU_AI_SOURCE)
   github.mjs           # tree listing + raw file download (public/private)
   local-source.mjs     # read skills/agents from a local SSOT checkout (testing)
-  scaffold.mjs         # write .ai-skills/, governance folders, inject workflow, prune
-  integrations.mjs     # AI environment pointer files (CLAUDE.md, AGENTS.md, ...)
-  lockfile.mjs         # read/write/guard lockfile.json
+  scaffold.mjs         # write engine folders, governance, inject workflow, prune, migrateLayout
+  integrations.mjs     # per-engine pointer + agentsDir/skillsDir (CLAUDE.md, AGENTS.md, GEMINI.md, ...)
+  lockfile.mjs         # read/write/guard .kiroku-ai/lockfile.json
 templates/
   kiroku-ai-sync.yml   # workflow injected into consumer projects
 test/                  # node:test suite (run: pnpm test)
@@ -140,9 +201,9 @@ mkdir /tmp/demo-app && cd /tmp/demo-app
 KIROKU_AI_SOURCE=/path/to/kiroku-ai-standards \
   node /path/to/kiroku-ai-standards/CLI/bin/kiroku-ai.mjs init
 
-# 3. Inspect what came down
-ls -R .ai-skills
-cat .ai-skills/lockfile.json
+# 3. Inspect what came down (folder depends on the AI tool you picked)
+ls -R .claude .opencode .agent .agents skills 2>/dev/null
+cat .kiroku-ai/lockfile.json
 ```
 
 PowerShell:

package/bin/kiroku-ai.mjs

@@ -1,8 +1,236 @@
 #!/usr/bin/env node
-import { run } from '../src/cli.mjs';
+/**
+ * kiroku-ai — bootstrap loader.
+ *
+ * The published npm package contains ONLY this file (plus package.json). The
+ * real CLI implementation is never shipped to npm; instead this loader:
+ *
+ *   1. Asks for a GitHub token FIRST (env → ~/.npmrc → interactive prompt),
+ *      saving it to ~/.npmrc for next time.
+ *   2. Downloads the CLI source (`CLI/src/**`, `CLI/templates/**`,
+ *      `CLI/package.json`) from the private SSOT repo via the GitHub API.
+ *   3. Caches it under ~/.kiroku-ai/runtime/<ref>/ and runs `npm install` once
+ *      so its dependencies (@clack/prompts, picocolors) resolve.
+ *   4. Dynamically imports the cached `src/cli.mjs` and runs it.
+ *
+ * When run from a full checkout of this repo (dev/CI), the sibling `../src`
+ * exists and is used directly — no token or network required.
+ */
 
-run(process.argv.slice(2)).catch((err) => {
-  // Defensive top-level guard. Normal control flow handles its own errors.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, appendFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import os from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const ORG = process.env.KIROKU_AI_ORG ?? 'Kiroku-Solutions';
+const REPO = process.env.KIROKU_AI_REPO ?? 'kiroku-ai-standards';
+const REF = process.env.KIROKU_AI_REF ?? 'main';
+const REFRESH = !!process.env.KIROKU_AI_REFRESH;
+
+const API = 'https://api.github.com';
+const CACHE_ROOT = join(os.homedir(), '.kiroku-ai', 'runtime');
+// Subtree of the SSOT repo that holds the CLI, mapped onto the cache root.
+const SUBTREE = 'CLI/';
+
+/** Run the inner CLI from a given src directory. */
+async function runFrom(srcDir, argv) {
+  const mod = await import(pathToFileURL(join(srcDir, 'cli.mjs')).href);
+  return mod.run(argv);
+}
+
+// ---------------------------------------------------------------------------
+// Token handling (token first)
+// ---------------------------------------------------------------------------
+
+function tokenFromNpmrc(content) {
+  const match = content.match(
+    /\/\/(?:npm\.pkg\.github\.com|api\.github\.com)\/:_authToken=([^\s]+)/,
+  );
+  return match?.[1] ?? null;
+}
+
+async function resolveToken() {
+  if (process.env.KIROKU_AI_TOKEN) return process.env.KIROKU_AI_TOKEN;
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+  for (const rc of [join(process.cwd(), '.npmrc'), join(os.homedir(), '.npmrc')]) {
+    try {
+      if (existsSync(rc)) {
+        const t = tokenFromNpmrc(await readFile(rc, 'utf8'));
+        if (t) return t;
+      }
+    } catch {
+      /* ignore unreadable .npmrc */
+    }
+  }
+  return null;
+}
+
+/** Prompt for a secret without echoing it to the terminal. */
+function promptHidden(question) {
+  return new Promise((res) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const onData = (char) => {
+      // Re-clear the line so typed characters never render.
+      const s = char.toString('utf8');
+      if (s === '\n' || s === '\r' || s === '') return;
+      process.stdout.clearLine?.(0);
+      process.stdout.cursorTo?.(0);
+      process.stdout.write(question);
+    };
+    process.stdin.on('data', onData);
+    rl.question(question, (answer) => {
+      process.stdin.off('data', onData);
+      process.stdout.write('\n');
+      rl.close();
+      res(answer.trim());
+    });
+  });
+}
+
+async function saveTokenToNpmrc(token) {
+  try {
+    await appendFile(join(os.homedir(), '.npmrc'), `\n//api.github.com/:_authToken=${token}\n`, 'utf8');
+  } catch {
+    /* non-fatal: token still used for this run via env */
+  }
+}
+
+async function ensureToken() {
+  let token = await resolveToken();
+  if (token) return token;
+
+  process.stdout.write(
+    '\nKiroku AI Standards — authentication required to fetch the private CLI.\n' +
+      'Enter a GitHub token with read access to the SSOT repo (input hidden):\n',
+  );
+  token = await promptHidden('Token: ');
+  if (!token) {
+    console.error('No token provided. Aborting.');
+    process.exit(1);
+  }
+  await saveTokenToNpmrc(token);
+  process.stdout.write('Token saved to ~/.npmrc.\n');
+  return token;
+}
+
+// ---------------------------------------------------------------------------
+// GitHub download
+// ---------------------------------------------------------------------------
+
+function ghHeaders(token, accept) {
+  return {
+    Accept: accept,
+    'User-Agent': 'kiroku-ai-loader',
+    'X-GitHub-Api-Version': '2022-11-28',
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+async function ghJson(url, token, accept = 'application/vnd.github+json') {
+  const res = await fetch(url, { headers: ghHeaders(token, accept) });
+  if (!res.ok) {
+    const hint =
+      res.status === 401 || res.status === 403
+        ? ' (bad/expired token or rate-limited)'
+        : res.status === 404
+          ? ' (repo/ref not found or token lacks access)'
+          : '';
+    throw new Error(`GitHub ${res.status} ${res.statusText}${hint} — ${url}`);
+  }
+  return res;
+}
+
+async function fetchTree(token) {
+  const url = `${API}/repos/${ORG}/${REPO}/git/trees/${encodeURIComponent(REF)}?recursive=1`;
+  const data = await (await ghJson(url, token)).json();
+  if (data.truncated) throw new Error('GitHub tree truncated; cannot bootstrap CLI reliably.');
+  return data;
+}
+
+async function downloadBlob(repoPath, token) {
+  const url = `${API}/repos/${ORG}/${REPO}/contents/${repoPath
+    .split('/')
+    .map(encodeURIComponent)
+    .join('/')}?ref=${encodeURIComponent(REF)}`;
+  const res = await ghJson(url, token, 'application/vnd.github.raw+json');
+  return res.text();
+}
+
+/** Map a repo path under CLI/ to its path inside the runtime cache dir. */
+function cacheRelPath(repoPath) {
+  return repoPath.slice(SUBTREE.length);
+}
+
+async function downloadCli(runtimeDir, token) {
+  const tree = await fetchTree(token);
+  const wanted = (tree.tree ?? []).filter(
+    (n) =>
+      n.type === 'blob' &&
+      (n.path.startsWith(`${SUBTREE}src/`) ||
+        n.path.startsWith(`${SUBTREE}templates/`) ||
+        n.path === `${SUBTREE}package.json`),
+  );
+  if (wanted.length === 0) {
+    throw new Error(`No CLI files found under ${SUBTREE} at ${ORG}/${REPO}@${REF}.`);
+  }
+  for (const node of wanted) {
+    const content = await downloadBlob(node.path, token);
+    const dest = join(runtimeDir, cacheRelPath(node.path));
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content, 'utf8');
+  }
+  await writeFile(join(runtimeDir, '.kiroku-meta.json'), JSON.stringify({ sha: tree.sha, ref: REF }) + '\n', 'utf8');
+}
+
+function npmInstall(cwd) {
+  return new Promise((res, rej) => {
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(
+      npm,
+      ['install', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'],
+      { cwd, stdio: 'inherit', shell: process.platform === 'win32' },
+    );
+    child.on('error', rej);
+    child.on('close', (code) => (code === 0 ? res() : rej(new Error(`npm install exited ${code}`))));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  // Dev / full-checkout fast path: run the real source directly, no network.
+  const localSrc = resolve(__dirname, '..', 'src');
+  if (existsSync(join(localSrc, 'cli.mjs'))) {
+    return runFrom(localSrc, argv);
+  }
+
+  const runtimeDir = join(CACHE_ROOT, REF.replace(/[^a-zA-Z0-9._-]/g, '_'));
+  const cachedCli = join(runtimeDir, 'src', 'cli.mjs');
+  const cacheValid = existsSync(cachedCli) && existsSync(join(runtimeDir, 'node_modules')) && !REFRESH;
+
+  if (!cacheValid) {
+    const token = await ensureToken();
+    process.env.KIROKU_AI_TOKEN = token; // hand off to the inner CLI
+
+    process.stdout.write(`Fetching kiroku-ai CLI from ${ORG}/${REPO}@${REF}…\n`);
+    await mkdir(runtimeDir, { recursive: true });
+    await downloadCli(runtimeDir, token);
+
+    process.stdout.write('Installing CLI dependencies (first run only)…\n');
+    await npmInstall(runtimeDir);
+  }
+
+  return runFrom(join(runtimeDir, 'src'), argv);
+}
+
+main(process.argv.slice(2)).catch((err) => {
   console.error(err?.stack || String(err));
   process.exit(1);
 });

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@kiroku-solutions/kiroku-ai",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Interactive CLI to bootstrap Kiroku AI Standards (AI Context as Code) into any project.",
   "type": "module",
   "bin": {
     "kiroku-ai": "./bin/kiroku-ai.mjs"
   },
+  "comment:files": "Only the bootstrap loader is published to npm. The real CLI (src/, templates/) is fetched from the private SSOT repo at runtime; deps below are needed by that fetched runtime.",
   "files": [
-    "bin",
-    "src",
-    "templates"
+    "bin"
   ],
   "scripts": {
     "start": "node ./bin/kiroku-ai.mjs",