@kiroku-solutions/kiroku-ai 0.1.2

package/README.md

@@ -0,0 +1,157 @@
+# kiroku-ai CLI
+
+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.
+
+## Usage
+
+```bash
+# Pre-requisite: ensure you have configured your .npmrc with your GitHub token.
+# (See .npmrc.example in the root directory for instructions).
+
+# From the root of the project you want to set up:
+pnpm dlx @kiroku-solutions/kiroku-ai init
+
+# Re-sync skills later (picks up new files, removes stale ones):
+pnpm dlx @kiroku-solutions/kiroku-ai update
+
+# Switch which AI tool this project targets:
+pnpm dlx @kiroku-solutions/kiroku-ai env            # interactive picker
+pnpm dlx @kiroku-solutions/kiroku-ai env cursor     # non-interactive
+
+# or, inside this monorepo for local development:
+pnpm --dir CLI start init
+```
+
+### Commands
+
+| Command          | Description                                                                 |
+| ---------------- | --------------------------------------------------------------------------- |
+| `init`           | Guided stack builder; downloads skills and scaffolds `.ai-skills/`.         |
+| `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.  |
+
+### 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/`:
+
+| 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`     |
+
+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`.
+
+### Options
+
+| Option         | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| `--dir <path>` | Target project directory (default: current directory).             |
+| `--ref <ref>`  | Git ref of the SSOT to pull from (default: `main`).                |
+| `--force`      | Re-run even if a lockfile exists (re-installs / overwrites skills). |
+| `--dry-run`    | Resolve the stack and list files without writing anything.          |
+| `-h, --help`   | Show help.                                                          |
+| `-v, --version`| Show version.                                                       |
+
+### Environment variables
+
+| Variable           | Purpose                                                     |
+| ------------------ | ----------------------------------------------------------- |
+| `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_SOURCE` | Local path to an SSOT checkout — reads from disk instead of GitHub (for testing). |
+
+## What it generates
+
+```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
+```
+
+## How the stack maps to skills
+
+The compatibility matrix lives in [`src/resolver.mjs`](./src/resolver.mjs). In short:
+
+- `global/` is **always** installed.
+- A frontend scope pulls `frontend/shared/` plus the chosen framework folder.
+  Astro additionally pulls UI-integration folders (React → `frontend/react`).
+- A backend scope pulls `backend/shared/` plus the chosen tech folder. Choosing
+  **None (Supabase BaaS)** pulls `infra-and-db/supabase.md` instead.
+- Databases, deployment target and DevOps tools pull their matching `infra-and-db/`
+  / `backend/shared/` documents.
+
+## Architecture
+
+```text
+bin/kiroku-ai.mjs      # executable shim
+src/
+  cli.mjs              # arg parsing + init orchestration
+  config.mjs           # org/repo/ref constants (+ 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
+templates/
+  kiroku-ai-sync.yml   # workflow injected into consumer projects
+test/                  # node:test suite (run: pnpm test)
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+node bin/kiroku-ai.mjs --help
+```
+
+## Testing from another repo (offline, no GitHub)
+
+You can verify the CLI downloads the right files **without pushing** the SSOT to
+GitHub by pointing it at this repo on disk with `KIROKU_AI_SOURCE`:
+
+```bash
+# 1. Create a throwaway target project somewhere else
+mkdir /tmp/demo-app && cd /tmp/demo-app
+
+# 2. Run init against the local SSOT checkout (PowerShell shown below)
+#    bash:
+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
+```
+
+PowerShell:
+
+```powershell
+$env:KIROKU_AI_SOURCE = "T:\Kiroku\kiroku-ai-standards"
+node "T:\Kiroku\kiroku-ai-standards\CLI\bin\kiroku-ai.mjs" init
+```
+
+When `KIROKU_AI_SOURCE` is set, the resolver reads from disk, so each folder's
+`README.md` (and the `infra-and-db/*.md` topic files) is what gets installed —
+confirming the stack → files mapping without any network access.

package/bin/kiroku-ai.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2)).catch((err) => {
+  // Defensive top-level guard. Normal control flow handles its own errors.
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kiroku-solutions/kiroku-ai",
+  "version": "0.1.2",
+  "description": "Interactive CLI to bootstrap Kiroku AI Standards (AI Context as Code) into any project.",
+  "type": "module",
+  "bin": {
+    "kiroku-ai": "./bin/kiroku-ai.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "start": "node ./bin/kiroku-ai.mjs",
+    "init": "node ./bin/kiroku-ai.mjs init",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "keywords": [
+    "kiroku",
+    "ai",
+    "skills",
+    "prompts",
+    "cli",
+    "ai-context-as-code"
+  ],
+  "author": "Kiroku Solutions",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kiroku-Solutions/kiroku-ai-standards.git",
+    "directory": "CLI"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,420 @@
+/**
+ * CLI entrypoint and command router for `kiroku-ai`.
+ *
+ *   kiroku-ai init   [--dir <path>] [--ref <git-ref>] [--force] [--dry-run]
+ *   kiroku-ai update [--dir <path>] [--ref <git-ref>]
+ *   kiroku-ai env    [tool] [--dir <path>]
+ *   kiroku-ai --help | --version
+ */
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spinner, log, intro, outro, select, isCancel, cancel } from '@clack/prompts';
+import pc from 'picocolors';
+
+import { REF, SKILLS_ROOT, LOCAL_DIR, ORG, REPO, TOKEN, setToken, saveTokenToNpmrc, SOURCE } from './config.mjs';
+import { fetchTree, downloadFile, sourceLabel } from './source.mjs';
+import { resolveSkillSelectors, expandSelectors, collectAgentBlobs } from './resolver.mjs';
+import {
+  showIntro,
+  showOutro,
+  collectStack,
+  summarizeStack,
+  confirmInstall,
+  promptForToken,
+} from './prompts.mjs';
+import { lockfileExists, readLockfile, writeLockfile } from './lockfile.mjs';
+import {
+  writeSkills,
+  scaffoldGovernanceFolders,
+  injectSyncWorkflow,
+  pruneStaleSkills,
+} from './scaffold.mjs';
+import {
+  ENVIRONMENTS,
+  isValidEnvironment,
+  environmentChoices,
+  writePointer,
+  removeManagedPointer,
+} from './integrations.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const args = { _: [], ref: REF, dir: process.cwd(), force: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-h':
+      case '--help':
+        args.help = true;
+        break;
+      case '-v':
+      case '--version':
+        args.version = true;
+        break;
+      case '--force':
+        args.force = true;
+        break;
+      case '--dry-run':
+        args.dryRun = true;
+        break;
+      case '--dir':
+        args.dir = resolve(argv[++i] ?? '.');
+        break;
+      case '--ref':
+        args.ref = argv[++i] ?? REF;
+        args.refExplicit = true;
+        break;
+      default:
+        if (a.startsWith('--dir=')) args.dir = resolve(a.slice(6));
+        else if (a.startsWith('--ref=')) {
+          args.ref = a.slice(6);
+          args.refExplicit = true;
+        } else args._.push(a);
+    }
+  }
+  return args;
+}
+
+async function readVersion() {
+  try {
+    const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function printHelp() {
+  console.log(`
+${pc.bold('kiroku-ai')} — Bootstrap Kiroku AI Standards into a project
+
+${pc.bold('Usage')}
+  kiroku-ai init [options]        Set up .ai-skills/ from a guided stack builder
+  kiroku-ai update [options]      Re-sync skills for the recorded stack (prunes stale)
+  kiroku-ai env [tool] [options]  Switch the AI tool / regenerate its pointer file
+
+${pc.bold('Environments')} (for ${pc.cyan('env')})
+  ${Object.entries(ENVIRONMENTS)
+    .map(([k, v]) => `${k} (${v.label})`)
+    .join(', ')}
+
+${pc.bold('Options')}
+  --dir <path>    Target project directory (default: current directory)
+  --ref <ref>     Git ref of the SSOT to pull from (default: ${REF})
+  --force         Re-run even if a lockfile already exists (overwrites skills)
+  --dry-run       Resolve the stack and list files without writing anything
+  -h, --help      Show this help
+  -v, --version   Show version
+
+${pc.bold('Source')}
+  ${ORG}/${REPO}  (override with KIROKU_AI_ORG / KIROKU_AI_REPO / KIROKU_AI_REF)
+  Private repos: set KIROKU_AI_TOKEN with a read token.
+`);
+}
+
+async function runInit(args) {
+  showIntro();
+
+  // Guard: refuse to clobber an existing install unless forced.
+  if (lockfileExists(args.dir) && !args.force && !args.dryRun) {
+    log.warn(
+      `A ${pc.cyan(`${LOCAL_DIR}/lockfile.json`)} already exists in this project.\n` +
+        `  Run with ${pc.cyan('--force')} to re-install, or delete it manually.`,
+    );
+    showOutro(pc.yellow('Nothing to do.'));
+    return 0;
+  }
+
+  // 1. Collect the stack interactively.
+  const stack = await collectStack();
+
+  // 1.5 Ask for token if missing (and not using local source)
+  if (!TOKEN && !SOURCE) {
+    const newToken = await promptForToken();
+    setToken(newToken);
+    saveTokenToNpmrc(newToken);
+    log.success('GitHub token saved securely to ~/.npmrc');
+  }
+
+  // 2. Resolve selectors and fetch the repository tree.
+  const selectors = resolveSkillSelectors(stack);
+
+  const s = spinner();
+  s.start(`Resolving skills from ${sourceLabel()} (${ORG}/${REPO}@${args.ref})`);
+  let blobPaths;
+  try {
+    const tree = await fetchTree(args.ref);
+    blobPaths = expandSelectors(selectors, tree, SKILLS_ROOT);
+    if (stack.agents) blobPaths = [...blobPaths, ...collectAgentBlobs(tree)];
+    s.stop(`Resolved ${blobPaths.length} file(s).`);
+  } catch (err) {
+    s.stop(pc.red('Failed to resolve skills.'));
+    log.error(err.message);
+    showOutro(pc.red('Aborted.'));
+    return 1;
+  }
+
+  if (blobPaths.length === 0) {
+    log.warn('No skill files matched your stack on the remote yet.');
+  }
+
+  summarizeStack(stack, blobPaths.length);
+
+  // Dry-run stops here.
+  if (args.dryRun) {
+    log.info('Dry run — files that would be installed:');
+    for (const p of blobPaths) console.log('  ' + pc.dim(p.replace(/^skills\//, '')));
+    showOutro(pc.cyan('Dry run complete. Nothing was written.'));
+    return 0;
+  }
+
+  if (!(await confirmInstall())) {
+    showOutro(pc.yellow('Cancelled. Nothing was written.'));
+    return 0;
+  }
+
+  // 3. Download the matched files.
+  const dl = spinner();
+  dl.start('Downloading skills');
+  const files = [];
+  try {
+    for (const path of blobPaths) {
+      const content = await downloadFile(path, args.ref);
+      files.push({ path, content });
+    }
+    dl.stop(`Downloaded ${files.length} file(s).`);
+  } catch (err) {
+    dl.stop(pc.red('Download failed.'));
+    log.error(err.message);
+    showOutro(pc.red('Aborted — no partial install was committed to the lockfile.'));
+    return 1;
+  }
+
+  // 4. Scaffold the local structure and inject the workflow.
+  const write = spinner();
+  write.start('Writing .ai-skills/ and injecting sync workflow');
+  try {
+    await writeSkills(args.dir, files);
+    await scaffoldGovernanceFolders(args.dir);
+    const wf = await injectSyncWorkflow(args.dir);
+    if (stack.environment) {
+      const pointer = await writePointer(args.dir, stack.environment);
+      if (pointer.skipped) {
+        log.warn(
+          `Kept your existing ${pc.cyan(pointer.file)} (not generated by kiroku-ai). ` +
+            `Add a reference to ${LOCAL_DIR}/ manually.`,
+        );
+      }
+    }
+    await writeLockfile(args.dir, { ref: args.ref, stack, files: blobPaths });
+    write.stop('Project scaffolded.');
+    if (wf.existed) {
+      log.warn(`Overwrote existing ${wf.path}.`);
+    }
+  } catch (err) {
+    write.stop(pc.red('Scaffolding failed.'));
+    log.error(err.message);
+    showOutro(pc.red('Aborted.'));
+    return 1;
+  }
+
+  // 5. Next steps.
+  log.success('Kiroku AI context installed.');
+  log.message(
+    [
+      `${pc.bold('Next steps')}`,
+      `  1. Reference ${pc.cyan(LOCAL_DIR + '/')} from your AI tool (Cursor / Copilot / Claude).`,
+      `  2. Propose skills by adding files to ${pc.cyan(LOCAL_DIR + '/proposals/')} and pushing to main.`,
+      `  3. Add the ${pc.cyan('KIROKU_AI_SYNC_TOKEN')} org secret so the sync workflow can open PRs.`,
+    ].join('\n'),
+  );
+  showOutro(pc.green('Done.'));
+  return 0;
+}
+
+async function runUpdate(args) {
+  intro(pc.bgMagenta(pc.black(' kiroku-ai update ')));
+
+  const lock = await readLockfile(args.dir);
+  if (!lock) {
+    log.warn(`No ${pc.cyan(`${LOCAL_DIR}/lockfile.json`)} found. Run ${pc.cyan('kiroku-ai init')} first.`);
+    outro(pc.yellow('Nothing to do.'));
+    return 0;
+  }
+
+  const stack = lock.stack;
+  const ref = args.refExplicit ? args.ref : lock.source?.ref ?? args.ref;
+  const selectors = resolveSkillSelectors(stack);
+
+  if (!TOKEN && !SOURCE) {
+    const newToken = await promptForToken();
+    setToken(newToken);
+    saveTokenToNpmrc(newToken);
+    log.success('GitHub token saved securely to ~/.npmrc');
+  }
+
+  const s = spinner();
+  s.start(`Re-resolving skills from ${sourceLabel()} (${ORG}/${REPO}@${ref})`);
+  let blobPaths;
+  try {
+    const tree = await fetchTree(ref);
+    blobPaths = expandSelectors(selectors, tree, SKILLS_ROOT);
+    if (stack.agents) blobPaths = [...blobPaths, ...collectAgentBlobs(tree)];
+    s.stop(`Resolved ${blobPaths.length} file(s).`);
+  } catch (err) {
+    s.stop(pc.red('Failed to resolve skills.'));
+    log.error(err.message);
+    outro(pc.red('Aborted — existing install untouched.'));
+    return 1;
+  }
+
+  // Download the fresh set.
+  const dl = spinner();
+  dl.start('Downloading latest skills');
+  const files = [];
+  try {
+    for (const path of blobPaths) {
+      files.push({ path, content: await downloadFile(path, ref) });
+    }
+    dl.stop(`Downloaded ${files.length} file(s).`);
+  } catch (err) {
+    dl.stop(pc.red('Download failed.'));
+    log.error(err.message);
+    outro(pc.red('Aborted — existing install untouched.'));
+    return 1;
+  }
+
+  // Compute and prune files that left the resolved set.
+  const newLocal = new Set(blobPaths.map((p) => p.replace(/^skills\//, '')));
+  const stale = (lock.files ?? []).filter((p) => !newLocal.has(p));
+
+  const w = spinner();
+  w.start('Applying update');
+  try {
+    await writeSkills(args.dir, files);
+    const removed = await pruneStaleSkills(args.dir, stale);
+    // Refresh the AI pointer file for the recorded environment.
+    if (stack.environment && isValidEnvironment(stack.environment)) {
+      await writePointer(args.dir, stack.environment);
+    }
+    await writeLockfile(args.dir, { ref, stack, files: blobPaths });
+    w.stop(`Updated ${files.length} file(s)${removed ? `, removed ${removed} stale` : ''}.`);
+  } catch (err) {
+    w.stop(pc.red('Update failed.'));
+    log.error(err.message);
+    outro(pc.red('Aborted.'));
+    return 1;
+  }
+
+  log.success('Skills are up to date.');
+  outro(pc.green('Done.'));
+  return 0;
+}
+
+async function runEnv(args) {
+  intro(pc.bgMagenta(pc.black(' kiroku-ai env ')));
+
+  const lock = await readLockfile(args.dir);
+  if (!lock) {
+    log.warn(`No ${pc.cyan(`${LOCAL_DIR}/lockfile.json`)} found. Run ${pc.cyan('kiroku-ai init')} first.`);
+    outro(pc.yellow('Nothing to do.'));
+    return 0;
+  }
+
+  const current = lock.stack?.environment ?? null;
+
+  // Allow a non-interactive form: `kiroku-ai env <tool>`.
+  let target = args._[1];
+  if (target && !isValidEnvironment(target)) {
+    log.error(`Unknown environment "${target}". Valid: ${Object.keys(ENVIRONMENTS).join(', ')}`);
+    outro(pc.red('Aborted.'));
+    return 1;
+  }
+
+  if (!target) {
+    const picked = await select({
+      message: 'Select the AI tool for this project',
+      initialValue: current ?? undefined,
+      options: environmentChoices().map((c) => ({
+        ...c,
+        hint: c.value === current ? 'current' : undefined,
+      })),
+    });
+    if (isCancel(picked)) {
+      cancel('No changes made.');
+      return 0;
+    }
+    target = picked;
+  }
+
+  if (target === current) {
+    // Still (re)generate in case the pointer file was deleted.
+    await writePointer(args.dir, target);
+    log.info(`Already using ${pc.cyan(ENVIRONMENTS[target].label)}. Pointer file refreshed.`);
+    outro(pc.green('Done.'));
+    return 0;
+  }
+
+  // Swap: remove the previous managed pointer, write the new one.
+  if (current && isValidEnvironment(current)) {
+    const removed = await removeManagedPointer(args.dir, current);
+    if (removed) log.message(`Removed ${pc.dim(ENVIRONMENTS[current].file)}`);
+  }
+  const pointer = await writePointer(args.dir, target);
+  if (pointer.skipped) {
+    log.warn(`Kept your existing ${pc.cyan(pointer.file)} (not generated by kiroku-ai).`);
+  } else {
+    log.success(`Switched AI tool to ${pc.cyan(ENVIRONMENTS[target].label)} → ${pointer.file}`);
+  }
+
+  // Persist the new environment in the lockfile.
+  const stack = { ...lock.stack, environment: target };
+  await writeLockfile(args.dir, {
+    ref: lock.source?.ref ?? REF,
+    stack,
+    files: (lock.files ?? []).map((p) => `skills/${p}`),
+  });
+
+  outro(pc.green('Done.'));
+  return 0;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (args.version) {
+    console.log(await readVersion());
+    return 0;
+  }
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+
+  const command = args._[0] ?? 'init';
+  switch (command) {
+    case 'init': {
+      const code = await runInit(args);
+      process.exitCode = code;
+      return code;
+    }
+    case 'update': {
+      const code = await runUpdate(args);
+      process.exitCode = code;
+      return code;
+    }
+    case 'env': {
+      const code = await runEnv(args);
+      process.exitCode = code;
+      return code;
+    }
+    default:
+      console.error(pc.red(`Unknown command: ${command}`));
+      printHelp();
+      process.exitCode = 1;
+      return 1;
+  }
+}