@kiroku-solutions/kiroku-ai 0.1.2

package/src/config.mjs

@@ -0,0 +1,83 @@
+/**
+ * Central configuration for the Kiroku AI Standards CLI.
+ *
+ * Everything points at the Single Source of Truth (SSOT) repository. Each value
+ * can be overridden through an environment variable so the same binary works
+ * for forks, staging mirrors, or local testing without code changes.
+ */
+
+export const ORG = process.env.KIROKU_AI_ORG ?? 'Kiroku-Solutions';
+export const REPO = process.env.KIROKU_AI_REPO ?? 'kiroku-ai-standards';
+
+/** Git ref (branch, tag or commit SHA) the skills are pulled from. */
+export const REF = process.env.KIROKU_AI_REF ?? 'main';
+
+/**
+ * Local source override (for testing without GitHub). When set to a path to a
+ * checkout of the SSOT repo, the CLI reads skills/agents straight from disk
+ * instead of calling the GitHub API.
+ */
+export const SOURCE = process.env.KIROKU_AI_SOURCE ?? null;
+
+/** Path prefix inside the SSOT repo where the curated skills live. */
+export const SKILLS_ROOT = 'skills';
+
+/** Local folder created inside the consumer project. */
+export const LOCAL_DIR = '.ai-skills';
+
+/** Workflow file injected into the consumer project. */
+export const WORKFLOW_PATH = '.github/workflows/kiroku-ai-sync.yml';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+function resolveToken() {
+  if (process.env.KIROKU_AI_TOKEN) return process.env.KIROKU_AI_TOKEN;
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+  
+  // Magia de DX: Lee el token automáticamente del archivo .npmrc (local o del usuario)
+  try {
+    const npmrcPaths = [
+      path.join(process.cwd(), '.npmrc'),
+      path.join(os.homedir(), '.npmrc')
+    ];
+
+    for (const rcPath of npmrcPaths) {
+      if (fs.existsSync(rcPath)) {
+        const content = fs.readFileSync(rcPath, 'utf-8');
+        const match = content.match(/\/\/npm\.pkg\.github\.com\/:_authToken=([^\s]+)/);
+        if (match && match[1]) {
+          return match[1];
+        }
+      }
+    }
+  } catch (e) {
+    // Ignorar errores de lectura
+  }
+  return null;
+}
+
+/**
+ * Optional GitHub token used for the API/raw downloads. Automatically extracted from .npmrc
+ */
+export let TOKEN = resolveToken();
+
+export function setToken(newToken) {
+  TOKEN = newToken;
+}
+
+export function saveTokenToNpmrc(newToken) {
+  try {
+    const npmrcPath = path.join(os.homedir(), '.npmrc');
+    const line = `\n//npm.pkg.github.com/:_authToken=${newToken}\n@kiroku-solutions:registry=https://npm.pkg.github.com/\n`;
+    fs.appendFileSync(npmrcPath, line, 'utf-8');
+  } catch (e) {
+    // Fail silently if we can't write to ~/.npmrc
+  }
+}
+
+/** Team that reviews proposed skills in the SSOT repository. */
+export const REVIEW_TEAM = `${ORG}/architecture-leads`;
+
+export const LOCKFILE_VERSION = 1;

package/src/github.mjs

@@ -0,0 +1,75 @@
+/**
+ * Thin GitHub client built on top of the global `fetch` (Node >= 18).
+ *
+ * Two responsibilities:
+ *   1. List the SSOT repository tree once (recursive) so we can resolve which
+ *      blobs match the user's stack without N round-trips.
+ *   2. Download individual blobs as raw text (works for private repos too when a
+ *      token is provided, via the Contents API `raw` media type).
+ */
+
+import { ORG, REPO, TOKEN } from './config.mjs';
+
+const API = 'https://api.github.com';
+
+function baseHeaders(accept) {
+  const headers = {
+    Accept: accept,
+    'User-Agent': 'kiroku-ai-cli',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (TOKEN) headers.Authorization = `Bearer ${TOKEN}`;
+  return headers;
+}
+
+async function fail(res, context) {
+  let detail = '';
+  try {
+    const body = await res.json();
+    detail = body?.message ? ` — ${body.message}` : '';
+  } catch {
+    /* ignore non-JSON bodies */
+  }
+  const hint =
+    res.status === 404
+      ? ' (repo/ref not found, or private repo without a token — set KIROKU_AI_TOKEN)'
+      : res.status === 401 || res.status === 403
+        ? ' (authentication failed or rate-limited — check KIROKU_AI_TOKEN)'
+        : '';
+  throw new Error(`GitHub ${context} failed: ${res.status} ${res.statusText}${detail}${hint}`);
+}
+
+/**
+ * Fetch the full recursive tree for a given ref.
+ * @param {string} ref branch, tag or commit SHA
+ * @returns {Promise<Array<{ path: string, type: 'blob' | 'tree' }>>}
+ */
+export async function fetchTree(ref) {
+  const url = `${API}/repos/${ORG}/${REPO}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
+  const res = await fetch(url, { headers: baseHeaders('application/vnd.github+json') });
+  if (!res.ok) await fail(res, 'tree listing');
+
+  const data = await res.json();
+  if (data.truncated) {
+    throw new Error(
+      'GitHub tree response was truncated (repository too large). Aborting to avoid a partial install.',
+    );
+  }
+  return (data.tree ?? []).map((node) => ({ path: node.path, type: node.type }));
+}
+
+/**
+ * Download a single file as raw text.
+ * @param {string} path repo-relative path
+ * @param {string} ref branch, tag or commit SHA
+ * @returns {Promise<string>}
+ */
+export async function downloadFile(path, ref) {
+  const url = `${API}/repos/${ORG}/${REPO}/contents/${path
+    .split('/')
+    .map(encodeURIComponent)
+    .join('/')}?ref=${encodeURIComponent(ref)}`;
+  const res = await fetch(url, { headers: baseHeaders('application/vnd.github.raw+json') });
+  if (!res.ok) await fail(res, `download of ${path}`);
+  return res.text();
+}

package/src/integrations.mjs

@@ -0,0 +1,104 @@
+/**
+ * AI environment integrations.
+ *
+ * Each supported AI tool discovers project context from a different file. This
+ * module maps an environment key to its canonical "pointer" file and renders a
+ * managed file that tells the tool to treat `.ai-skills/` as authoritative.
+ *
+ * Pointer files we generate carry a marker so we only ever delete/overwrite our
+ * own files — never a hand-written CLAUDE.md / AGENTS.md the user already had.
+ */
+
+import { mkdir, writeFile, readFile, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { LOCAL_DIR } from './config.mjs';
+
+const MARKER = '<!-- kiroku-ai:managed -->';
+
+/**
+ * Supported environments, in display order. `mdc` toggles Cursor's frontmatter.
+ */
+export const ENVIRONMENTS = {
+  'claude-code': { label: 'Claude Code', file: 'CLAUDE.md' },
+  cursor: { label: 'Cursor', file: '.cursor/rules/kiroku-ai.mdc', mdc: true },
+  copilot: { label: 'GitHub Copilot', file: '.github/copilot-instructions.md' },
+  opencode: { label: 'OpenCode (AGENTS.md)', file: 'AGENTS.md' },
+  antigravity: { label: 'Antigravity', file: 'AGENTS.md' },
+  windsurf: { label: 'Windsurf', file: '.windsurf/rules/kiroku-ai.md' },
+};
+
+export function isValidEnvironment(key) {
+  return Object.prototype.hasOwnProperty.call(ENVIRONMENTS, key);
+}
+
+export function environmentChoices() {
+  return Object.entries(ENVIRONMENTS).map(([value, { label }]) => ({ value, label }));
+}
+
+function renderBody(envKey) {
+  const env = ENVIRONMENTS[envKey];
+  const header = env.mdc
+    ? `---\ndescription: Kiroku AI Standards — project context\nalwaysApply: true\n---\n`
+    : '';
+
+  return `${header}# Kiroku AI Standards — Project Context
+${MARKER}
+
+This project follows Kiroku's shared AI standards. Treat the files inside
+\`${LOCAL_DIR}/\` as authoritative context and conventions for this codebase.
+
+- \`${LOCAL_DIR}/global/\` — organization-wide rules (always apply)
+- \`${LOCAL_DIR}/frontend/\`, \`${LOCAL_DIR}/backend/\`, \`${LOCAL_DIR}/infra-and-db/\` — stack-specific rules
+- \`${LOCAL_DIR}/local/\` — project-specific rules
+
+Before writing or refactoring code, load and respect the relevant skill files in
+\`${LOCAL_DIR}/\`. Do not edit the downloaded skill folders directly — propose
+changes by adding files to \`${LOCAL_DIR}/proposals/\`.
+
+> Managed by the \`kiroku-ai\` CLI. Run \`kiroku-ai env\` to switch AI tools.
+`;
+}
+
+/**
+ * Write the pointer file for an environment.
+ * @returns {Promise<{ file: string, overwritten: boolean, skipped: boolean }>}
+ */
+export async function writePointer(targetDir, envKey) {
+  const env = ENVIRONMENTS[envKey];
+  const dest = join(targetDir, env.file);
+
+  let existing = null;
+  try {
+    existing = await readFile(dest, 'utf8');
+  } catch {
+    /* no existing file */
+  }
+
+  // Never clobber a user-authored file that we didn't generate.
+  if (existing !== null && !existing.includes(MARKER)) {
+    return { file: env.file, overwritten: false, skipped: true };
+  }
+
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, renderBody(envKey), 'utf8');
+  return { file: env.file, overwritten: existing !== null, skipped: false };
+}
+
+/**
+ * Remove a previously generated pointer file (only if it carries our marker).
+ * @returns {Promise<boolean>} true if a managed file was removed
+ */
+export async function removeManagedPointer(targetDir, envKey) {
+  const env = ENVIRONMENTS[envKey];
+  const dest = join(targetDir, env.file);
+  try {
+    const content = await readFile(dest, 'utf8');
+    if (content.includes(MARKER)) {
+      await unlink(dest);
+      return true;
+    }
+  } catch {
+    /* nothing to remove */
+  }
+  return false;
+}

package/src/local-source.mjs

@@ -0,0 +1,46 @@
+/**
+ * Local filesystem source — mirrors the github.mjs interface so the CLI can be
+ * tested offline against a checkout of the SSOT repo (set KIROKU_AI_SOURCE).
+ *
+ * The `ref` argument is accepted for API parity but ignored: the local working
+ * tree is whatever is on disk.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { SOURCE } from './config.mjs';
+
+function toPosix(p) {
+  return p.split(sep).join('/');
+}
+
+async function walk(dir, root, out) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === 'node_modules') continue;
+    const abs = join(dir, entry.name);
+    const rel = toPosix(relative(root, abs));
+    if (entry.isDirectory()) {
+      out.push({ path: rel, type: 'tree' });
+      await walk(abs, root, out);
+    } else if (entry.isFile()) {
+      out.push({ path: rel, type: 'blob' });
+    }
+  }
+  return out;
+}
+
+/** @returns {Promise<Array<{ path: string, type: 'blob' | 'tree' }>>} */
+export async function fetchTree(_ref) {
+  return walk(SOURCE, SOURCE, []);
+}
+
+/** @returns {Promise<string>} */
+export async function downloadFile(path, _ref) {
+  return readFile(join(SOURCE, path), 'utf8');
+}

package/src/lockfile.mjs

@@ -0,0 +1,47 @@
+/**
+ * Lockfile management.
+ *
+ * `.ai-skills/lockfile.json` records what was installed and from which ref. Its
+ * presence is the guard that prevents a second `init` from duplicating data
+ * (unless `--force` is passed).
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { LOCAL_DIR, ORG, REPO, LOCKFILE_VERSION } from './config.mjs';
+
+function lockfilePath(targetDir) {
+  return join(targetDir, LOCAL_DIR, 'lockfile.json');
+}
+
+export function lockfileExists(targetDir) {
+  return existsSync(lockfilePath(targetDir));
+}
+
+export async function readLockfile(targetDir) {
+  try {
+    return JSON.parse(await readFile(lockfilePath(targetDir), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} targetDir
+ * @param {object} args
+ * @param {string} args.ref
+ * @param {import('./resolver.mjs').Stack} args.stack
+ * @param {string[]} args.files  repo-relative blob paths that were installed
+ */
+export async function writeLockfile(targetDir, { ref, stack, files }) {
+  const payload = {
+    lockfileVersion: LOCKFILE_VERSION,
+    generatedAt: new Date().toISOString(),
+    source: { org: ORG, repo: REPO, ref },
+    stack,
+    files: files.map((p) => p.replace(/^skills\//, '')).sort(),
+  };
+  await writeFile(lockfilePath(targetDir), JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return payload;
+}

package/src/prompts.mjs

@@ -0,0 +1,232 @@
+/**
+ * Interactive stack builder powered by @clack/prompts.
+ *
+ * The flow mirrors the Astro CLI feel: guided, conditional, and it enforces the
+ * compatibility matrix so users cannot assemble architecturally nonsensical
+ * stacks. Returns a `Stack` object consumed by `resolver.mjs`.
+ */
+
+import {
+  intro,
+  outro,
+  group,
+  select,
+  multiselect,
+  confirm,
+  note,
+  isCancel,
+  cancel,
+  text,
+  log,
+} from '@clack/prompts';
+import pc from 'picocolors';
+import { environmentChoices } from './integrations.mjs';
+
+function ensure(value) {
+  if (isCancel(value)) {
+    cancel('Setup cancelled. No files were written.');
+    process.exit(0);
+  }
+  return value;
+}
+
+export function showIntro() {
+  intro(pc.bgMagenta(pc.black(' kiroku-ai ')) + ' ' + pc.dim('AI Context as Code'));
+}
+
+export function showOutro(message) {
+  outro(message);
+}
+
+/**
+ * Runs the full guided flow.
+ * @returns {Promise<import('./resolver.mjs').Stack>}
+ */
+export async function collectStack() {
+  // --- Prompt 1: Project scope -------------------------------------------
+  const scope = ensure(
+    await select({
+      message: 'What is the scope of this project?',
+      options: [
+        { value: 'fullstack', label: 'Fullstack', hint: 'frontend + backend' },
+        { value: 'frontend', label: 'Frontend only' },
+        { value: 'backend', label: 'Backend only' },
+        { value: 'infra', label: 'Infra / Workers', hint: 'no app frameworks' },
+      ],
+    }),
+  );
+
+  const wantsFrontend = scope === 'fullstack' || scope === 'frontend';
+  const wantsBackend = scope === 'fullstack' || scope === 'backend';
+
+  /** @type {import('./resolver.mjs').Stack} */
+  const stack = { scope };
+
+  // --- Prompt 2: Frontend framework --------------------------------------
+  if (wantsFrontend) {
+    stack.frontend = ensure(
+      await select({
+        message: 'Choose your frontend framework',
+        options: [
+          { value: 'nextjs', label: 'Next.js', hint: 'App Router' },
+          { value: 'astro', label: 'Astro', hint: 'islands / content' },
+          { value: 'sveltekit', label: 'SvelteKit' },
+        ],
+      }),
+    );
+
+    // Astro sub-prompt: optional UI integrations.
+    if (stack.frontend === 'astro') {
+      const addIntegrations = ensure(
+        await confirm({
+          message: 'Add Astro UI integrations?',
+          initialValue: true,
+        }),
+      );
+      if (addIntegrations) {
+        stack.astroIntegrations = ensure(
+          await multiselect({
+            message: 'Select integrations (Space to toggle, Enter to confirm)',
+            required: false,
+            options: [
+              { value: 'react', label: 'React' },
+              { value: 'svelte', label: 'Svelte' },
+              { value: 'tailwind', label: 'Tailwind CSS' },
+            ],
+          }),
+        );
+      }
+    }
+  }
+
+  // --- Prompt 3: Backend technology --------------------------------------
+  if (wantsBackend) {
+    stack.backend = ensure(
+      await select({
+        message: 'Choose your backend technology',
+        options: [
+          { value: 'python-fastapi', label: 'Python (FastAPI)' },
+          { value: 'dotnet', label: '.NET' },
+          { value: 'java', label: 'Java' },
+          { value: 'none', label: 'None', hint: 'Supabase BaaS' },
+        ],
+      }),
+    );
+  }
+
+  // --- Prompt 4: Databases & state (multi-select) ------------------------
+  if (scope !== 'infra') {
+    stack.databases = ensure(
+      await multiselect({
+        message: 'Databases & state (Space to toggle)',
+        required: false,
+        options: [
+          { value: 'supabase', label: 'Supabase (Postgres)' },
+          { value: 'postgres', label: 'Custom Postgres' },
+          { value: 'mongodb', label: 'MongoDB' },
+          { value: 'redis', label: 'Redis' },
+        ],
+      }),
+    );
+  } else {
+    stack.databases = [];
+  }
+
+  // --- Prompt 5: Deployment target ---------------------------------------
+  // Compatibility constraint: Next.js defaults to Vercel.
+  const nextjsSelected = stack.frontend === 'nextjs';
+  stack.deploy = ensure(
+    await select({
+      message: nextjsSelected
+        ? 'Deployment target ' + pc.dim('(Vercel recommended for Next.js)')
+        : 'Deployment target',
+      initialValue: nextjsSelected ? 'vercel' : undefined,
+      options: [
+        {
+          value: 'vercel',
+          label: 'Vercel',
+          hint: nextjsSelected ? 'recommended' : undefined,
+        },
+        { value: 'cloudflare', label: 'Cloudflare', hint: 'Workers / Pages' },
+        { value: 'docker', label: 'Docker / Self-Hosted' },
+      ],
+    }),
+  );
+
+  // --- Prompt 6: DevOps & queues (multi-select) --------------------------
+  stack.devops = ensure(
+    await multiselect({
+      message: 'DevOps & queues (Space to toggle)',
+      required: false,
+      options: [
+        { value: 'github-actions', label: 'GitHub Actions' },
+        { value: 'n8n', label: 'n8n' },
+        { value: 'rabbitmq', label: 'RabbitMQ' },
+      ],
+    }),
+  );
+
+  // --- Prompt 7: Agent personas (optional) -------------------------------
+  stack.agents = ensure(
+    await confirm({
+      message: 'Include Kiroku agent personas? (e.g. Security Auditor)',
+      initialValue: true,
+    }),
+  );
+
+  // --- Prompt 8: AI environment (single select) --------------------------
+  // Determines which "pointer" file is generated so the chosen AI tool loads
+  // .ai-skills/ automatically. Switchable later via `kiroku-ai env`.
+  stack.environment = ensure(
+    await select({
+      message: 'Which AI tool will this project use?',
+      options: environmentChoices(),
+    }),
+  );
+
+  return stack;
+}
+
+/** Pretty-print the resolved stack as a summary note. */
+export function summarizeStack(stack, fileCount) {
+  const lines = [];
+  lines.push(`${pc.bold('Scope')}      ${stack.scope}`);
+  if (stack.frontend) {
+    const integ =
+      stack.astroIntegrations?.length ? ` (+ ${stack.astroIntegrations.join(', ')})` : '';
+    lines.push(`${pc.bold('Frontend')}   ${stack.frontend}${integ}`);
+  }
+  if (stack.backend) lines.push(`${pc.bold('Backend')}    ${stack.backend}`);
+  if (stack.databases?.length) lines.push(`${pc.bold('Database')}   ${stack.databases.join(', ')}`);
+  if (stack.deploy) lines.push(`${pc.bold('Deploy')}     ${stack.deploy}`);
+  if (stack.devops?.length) lines.push(`${pc.bold('DevOps')}     ${stack.devops.join(', ')}`);
+  if (stack.agents) lines.push(`${pc.bold('Agents')}     included`);
+  if (stack.environment) lines.push(`${pc.bold('AI tool')}    ${stack.environment}`);
+  lines.push('');
+  lines.push(pc.green(`${fileCount} skill file(s) will be installed.`));
+  note(lines.join('\n'), 'Resolved stack');
+}
+
+export async function confirmInstall() {
+  return ensure(
+    await confirm({
+      message: 'Install these skills into ./.ai-skills ?',
+      initialValue: true,
+    }),
+  );
+}
+
+export async function promptForToken() {
+  log.warn(pc.yellow('Authentication required to access private skills.'));
+  
+  const token = ensure(
+    await text({
+      message: 'Enter your GitHub PAT (with read:packages permission):',
+      placeholder: 'ghp_...',
+      validate(value) {
+        if (!value.trim()) return 'Token is required to download private skills.';
+      },
+    }),
+  );
+  return token.trim();
+}