@kiroku-solutions/kiroku-ai 0.1.2

package/src/resolver.mjs

@@ -0,0 +1,141 @@
+/**
+ * Compatibility matrix resolver.
+ *
+ * Translates the answers collected by the interactive prompts into a concrete
+ * set of skill *selectors* (paths relative to `skills/` in the SSOT repo). A
+ * selector can be a directory ("frontend/astro") or a single file
+ * ("infra-and-db/supabase.md").
+ *
+ * The matching against the real repository tree happens later in `cli.mjs`;
+ * here we only express *intent*. This keeps the matrix declarative and testable.
+ */
+
+/**
+ * @typedef {Object} Stack
+ * @property {'fullstack'|'frontend'|'backend'|'infra'} scope
+ * @property {('nextjs'|'astro'|'sveltekit')=} frontend
+ * @property {string[]=} astroIntegrations  e.g. ['react','tailwind']
+ * @property {('python-fastapi'|'dotnet'|'java'|'none')=} backend
+ * @property {string[]=} databases  e.g. ['supabase','redis']
+ * @property {('vercel'|'cloudflare'|'docker')=} deploy
+ * @property {string[]=} devops  e.g. ['github-actions','rabbitmq']
+ */
+
+/**
+ * @param {Stack} stack
+ * @returns {string[]} sorted, de-duplicated skill selectors relative to `skills/`
+ */
+export function resolveSkillSelectors(stack) {
+  const selectors = new Set();
+
+  // Organization-wide rules are always included.
+  selectors.add('global');
+
+  const hasFrontend = stack.scope === 'fullstack' || stack.scope === 'frontend';
+  const hasBackend = stack.scope === 'fullstack' || stack.scope === 'backend';
+
+  // --- Frontend -----------------------------------------------------------
+  if (hasFrontend && stack.frontend) {
+    selectors.add('frontend/shared');
+    selectors.add(`frontend/${stack.frontend}`);
+
+    // Astro is a meta-framework: pull the UI integration rules it can host.
+    if (stack.frontend === 'astro') {
+      const integrations = stack.astroIntegrations ?? [];
+      if (integrations.includes('react')) selectors.add('frontend/react');
+      if (integrations.includes('svelte')) selectors.add('frontend/sveltekit');
+      // 'tailwind' is covered by frontend/shared/tailwind-rules.md (already in).
+    }
+  }
+
+  // --- Backend ------------------------------------------------------------
+  if (hasBackend && stack.backend) {
+    if (stack.backend === 'none') {
+      // "None (Supabase BaaS)" — no server framework, but Supabase rules apply.
+      selectors.add('infra-and-db/supabase.md');
+    } else {
+      selectors.add('backend/shared');
+      selectors.add(`backend/${stack.backend}`);
+    }
+  }
+
+  // --- Databases ----------------------------------------------------------
+  for (const db of stack.databases ?? []) {
+    selectors.add('infra-and-db/databases.md');
+    if (db === 'supabase') selectors.add('infra-and-db/supabase.md');
+  }
+
+  // --- Deployment ---------------------------------------------------------
+  switch (stack.deploy) {
+    case 'vercel':
+      selectors.add('infra-and-db/deploy-vercel.md');
+      break;
+    case 'cloudflare':
+      selectors.add('infra-and-db/deploy-cloudflare.md');
+      break;
+    case 'docker':
+      selectors.add('backend/shared/docker-containers.md');
+      break;
+    default:
+      break;
+  }
+
+  // --- DevOps & Queues ----------------------------------------------------
+  for (const tool of stack.devops ?? []) {
+    if (tool === 'rabbitmq') {
+      selectors.add('backend/shared/message-brokers.md');
+    } else {
+      // github-actions, n8n
+      selectors.add('infra-and-db/cicd-n8n-actions.md');
+    }
+  }
+
+  return [...selectors].sort();
+}
+
+/**
+ * Expand selectors against the real repository tree.
+ *
+ * @param {string[]} selectors  paths relative to `skills/`
+ * @param {Array<{path:string,type:string}>} tree  full recursive tree
+ * @param {string} skillsRoot  e.g. "skills"
+ * @returns {string[]} repo-relative blob paths to download (e.g. "skills/global/01-..md")
+ */
+export function expandSelectors(selectors, tree, skillsRoot) {
+  const blobs = tree.filter((n) => n.type === 'blob' && n.path.startsWith(`${skillsRoot}/`));
+  const wanted = new Set();
+
+  for (const sel of selectors) {
+    const full = `${skillsRoot}/${sel}`;
+    for (const blob of blobs) {
+      const isExactFile = blob.path === full;
+      const isInsideDir = blob.path.startsWith(`${full}/`);
+      if (isExactFile || isInsideDir) {
+        // Ignore placeholder files so empty skill folders don't pollute installs.
+        if (blob.path.endsWith('/.gitkeep')) continue;
+        wanted.add(blob.path);
+      }
+    }
+  }
+
+  return [...wanted].sort();
+}
+
+/**
+ * Collect agent persona blobs (the `agents/` folder). Agents are optional and
+ * orthogonal to the stack — included wholesale when the user opts in.
+ *
+ * @param {Array<{path:string,type:string}>} tree
+ * @returns {string[]} repo-relative blob paths under `agents/`
+ */
+export function collectAgentBlobs(tree) {
+  return tree
+    .filter(
+      (n) =>
+        n.type === 'blob' &&
+        n.path.startsWith('agents/') &&
+        !n.path.endsWith('/.gitkeep'),
+    )
+    .map((n) => n.path)
+    .sort();
+}

package/src/scaffold.mjs

@@ -0,0 +1,130 @@
+/**
+ * Filesystem scaffolding for the consumer project.
+ *
+ * Responsibilities:
+ *   - Materialize downloaded skill files under `.ai-skills/`, stripping the
+ *     remote `skills/` prefix so the local tree is clean.
+ *   - Create the governance folders `proposals/` and `local/` with READMEs.
+ *   - Inject the two-way sync GitHub Action.
+ */
+
+import { mkdir, writeFile, readFile, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOCAL_DIR, WORKFLOW_PATH, ORG, REPO, REF, REVIEW_TEAM } from './config.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(__dirname, '..', 'templates');
+
+/** Strip the remote `skills/` prefix to produce a local relative path. */
+function toLocalPath(repoPath) {
+  return repoPath.replace(/^skills\//, '');
+}
+
+async function writeFileEnsured(filePath, content) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, content, 'utf8');
+}
+
+/**
+ * Write all downloaded skills into `.ai-skills/`.
+ * @param {string} targetDir
+ * @param {Array<{ path: string, content: string }>} files
+ */
+export async function writeSkills(targetDir, files) {
+  const base = join(targetDir, LOCAL_DIR);
+  for (const file of files) {
+    await writeFileEnsured(join(base, toLocalPath(file.path)), file.content);
+  }
+}
+
+/**
+ * Delete skill files that are no longer part of the resolved set (used by
+ * `update`). Paths are local-relative (skills/ prefix already stripped). Only
+ * touches the managed skill tree — never `proposals/` or `local/`.
+ * @returns {Promise<number>} count of files removed
+ */
+export async function pruneStaleSkills(targetDir, staleLocalPaths) {
+  const base = join(targetDir, LOCAL_DIR);
+  const protectedRoots = ['proposals/', 'local/'];
+  let removed = 0;
+  for (const rel of staleLocalPaths) {
+    if (protectedRoots.some((p) => rel.startsWith(p)) || rel === 'lockfile.json') continue;
+    try {
+      await unlink(join(base, rel));
+      removed += 1;
+    } catch {
+      /* already gone */
+    }
+  }
+  return removed;
+}
+
+/** Create the proposals/ and local/ governance folders with guidance READMEs. */
+export async function scaffoldGovernanceFolders(targetDir) {
+  const base = join(targetDir, LOCAL_DIR);
+
+  const rootReadme = `# .ai-skills
+
+This folder is managed by the **Kiroku AI Standards** CLI (\`kiroku-ai\`).
+It carries the AI context (prompts, rules, skills) for this project.
+
+## Layout
+
+- **Downloaded skill folders** (\`global/\`, \`frontend/\`, \`backend/\`, \`infra-and-db/\`)
+  are pulled from the Single Source of Truth and **must not be edited locally** —
+  changes here are overwritten on the next sync.
+- **\`proposals/\`** — drop framework-agnostic skills you want to promote
+  company-wide. Pushing to \`main\` opens a PR in the SSOT repository automatically.
+- **\`local/\`** — project-specific AI rules. Ignored by syncing, never uploaded.
+
+> To propose a change to a downloaded skill, copy it into \`proposals/\` and edit
+> there. Architecture leads review every proposal before org-wide adoption.
+`;
+
+  const proposalsReadme = `# proposals/
+
+Place **new, framework-agnostic** skills here to propose them to the whole
+company. On push to \`main\`, the \`kiroku-ai-sync\` GitHub Action copies these
+files into the central \`${ORG}/${REPO}\` repository and opens a Pull Request for
+the ${REVIEW_TEAM} team to review.
+
+Naming: use a descriptive kebab-case filename, e.g. \`nextjs-routing.md\`.
+`;
+
+  const localReadme = `# local/
+
+Project-specific AI rules (local database schemas, internal conventions, etc.).
+These files are **never** synced to the central repository. Use them freely.
+`;
+
+  await writeFileEnsured(join(base, 'README.md'), rootReadme);
+  await writeFileEnsured(join(base, 'proposals', 'README.md'), proposalsReadme);
+  await writeFileEnsured(join(base, 'proposals', '.gitkeep'), '');
+  await writeFileEnsured(join(base, 'local', 'README.md'), localReadme);
+  await writeFileEnsured(join(base, 'local', '.gitkeep'), '');
+}
+
+/**
+ * Inject the two-way sync workflow, substituting org/repo/team placeholders.
+ * @returns {Promise<{ path: string, existed: boolean }>}
+ */
+export async function injectSyncWorkflow(targetDir) {
+  const template = await readFile(join(TEMPLATES_DIR, 'kiroku-ai-sync.yml'), 'utf8');
+  const rendered = template
+    .replaceAll('__ORG__', ORG)
+    .replaceAll('__REPO__', REPO)
+    .replaceAll('__REF__', REF)
+    .replaceAll('__REVIEW_TEAM__', REVIEW_TEAM);
+
+  const dest = join(targetDir, WORKFLOW_PATH);
+  let existed = false;
+  try {
+    await readFile(dest, 'utf8');
+    existed = true;
+  } catch {
+    /* file does not exist yet */
+  }
+  await writeFileEnsured(dest, rendered);
+  return { path: WORKFLOW_PATH, existed };
+}

package/src/source.mjs

@@ -0,0 +1,19 @@
+/**
+ * Source dispatcher. Resolves skills/agents from either GitHub (default) or the
+ * local filesystem when KIROKU_AI_SOURCE is set. Keeps a single import surface
+ * (`fetchTree`, `downloadFile`) for the rest of the CLI.
+ */
+
+import { SOURCE } from './config.mjs';
+import * as github from './github.mjs';
+import * as local from './local-source.mjs';
+
+const impl = SOURCE ? local : github;
+
+export const fetchTree = impl.fetchTree;
+export const downloadFile = impl.downloadFile;
+
+/** Human-readable description of where files come from (for logs). */
+export function sourceLabel() {
+  return SOURCE ? `local:${SOURCE}` : 'github';
+}

package/templates/kiroku-ai-sync.yml

@@ -0,0 +1,108 @@
+# Injected by the Kiroku AI Standards CLI (`kiroku-ai init`).
+#
+# Two-way sync: when a developer pushes a new skill into `.ai-skills/proposals/`,
+# this workflow forwards it to the central SSOT repository as a Pull Request so
+# the architecture leads can review it for company-wide adoption.
+#
+# Requirements:
+#   - Organization secret `KIROKU_AI_SYNC_TOKEN`: a token (PAT or GitHub App)
+#     with `contents:write` and `pull_requests:write` on __ORG__/__REPO__.
+name: Kiroku AI — Sync Proposals to SSOT
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.ai-skills/proposals/**'
+
+# Avoid racing PRs when several proposals land close together.
+concurrency:
+  group: kiroku-ai-sync
+  cancel-in-progress: false
+
+jobs:
+  propose:
+    name: Open proposal PR in __ORG__/__REPO__
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout this project
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Forward proposals as a Pull Request
+        env:
+          GH_TOKEN: ${{ secrets.KIROKU_AI_SYNC_TOKEN }}
+          CENTRAL_ORG: __ORG__
+          CENTRAL_REPO: __REPO__
+          REVIEW_TEAM: __REVIEW_TEAM__
+          SOURCE_REPO: ${{ github.repository }}
+          SOURCE_SHA: ${{ github.sha }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${GH_TOKEN:-}" ]; then
+            echo "::error::Missing KIROKU_AI_SYNC_TOKEN organization secret."
+            exit 1
+          fi
+
+          SOURCE_NAME="${SOURCE_REPO##*/}"
+          WORKDIR="$(mktemp -d)"
+          CENTRAL_SLUG="${CENTRAL_ORG}/${CENTRAL_REPO}"
+          BRANCH="proposal/${SOURCE_NAME}-${RUN_ID}"
+          DEST_DIR="proposals/incoming/${SOURCE_NAME}"
+
+          echo "Cloning ${CENTRAL_SLUG}..."
+          git clone --depth 1 \
+            "https://x-access-token:${GH_TOKEN}@github.com/${CENTRAL_SLUG}.git" \
+            "${WORKDIR}/central"
+
+          cd "${WORKDIR}/central"
+          git config user.name "kiroku-ai-bot"
+          git config user.email "kiroku-ai-bot@users.noreply.github.com"
+          git checkout -b "${BRANCH}"
+
+          mkdir -p "${DEST_DIR}"
+          # Copy every proposed file except placeholders/readmes.
+          rsync -a \
+            --exclude='.gitkeep' \
+            --exclude='README.md' \
+            "${GITHUB_WORKSPACE}/.ai-skills/proposals/" "${DEST_DIR}/"
+
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "No proposal changes to forward. Exiting cleanly."
+            exit 0
+          fi
+
+          git add "${DEST_DIR}"
+          git commit -m "proposal: incoming skills from ${SOURCE_REPO}@${SOURCE_SHA}"
+          git push origin "${BRANCH}"
+
+          PR_BODY="$(cat <<EOF
+          Automated proposal forwarded by the Kiroku AI Standards sync action.
+
+          - **Source repository:** ${SOURCE_REPO}
+          - **Source commit:** ${SOURCE_SHA}
+          - **Staged under:** \`${DEST_DIR}/\`
+
+          Please review and relocate the proposed skill(s) into the appropriate
+          curated folder (e.g. \`skills/frontend/...\`) before merging.
+          EOF
+          )"
+
+          gh pr create \
+            --repo "${CENTRAL_SLUG}" \
+            --base main \
+            --head "${BRANCH}" \
+            --title "Proposal: skills from ${SOURCE_NAME}" \
+            --body "${PR_BODY}" \
+            --reviewer "${REVIEW_TEAM}" || \
+          gh pr create \
+            --repo "${CENTRAL_SLUG}" \
+            --base main \
+            --head "${BRANCH}" \
+            --title "Proposal: skills from ${SOURCE_NAME}" \
+            --body "${PR_BODY}"