@genn-inc/cluebase-cli 0.0.1

package/src/setup-step-commands.mjs

@@ -0,0 +1,427 @@
+// Slash command content generator for the Cluebase setup flow.
+//
+// Generates 9 step-level slash command files under `.claude/commands/`:
+//
+//   - cluebase-discover.md          — STEP 1: boundary discovery (AI grep + Read)
+//   - cluebase-discover-review.md   — STEP 2: self-review of STEP 1 output (AI)
+//   - cluebase-discover-context.md  — STEP 3: field-semantic enrichment (AI)
+//   - cluebase-discover-check.md    — STEP 4: bash validation of discoveries.json
+//   - cluebase-implement.md         — STEP 5: SDK call insertion + env file write
+//   - cluebase-implement-check.md   — STEP 6: bash static check + diff snapshot
+//   - cluebase-implement-review.md  — STEP 7: self-review of inserted code (AI)
+//   - cluebase-events.md            — STEP 8: guided business value event track (AI)
+//   - cluebase-doctor.md            — STEP 9: bash connectivity check
+//
+// The customer types ONE slash command at a time and the AI coding tool
+// performs a single, narrowly-scoped responsibility per turn. Each STEP
+// finishes with a Japanese one-line hand-off telling the user which
+// slash command to type next. State recovery is encoded directly in
+// each STEP so re-running a STEP after a crash resumes from the last
+// completed sub-task (per `_progress.completed_substeps` in
+// `.cluebase/discoveries.json` / `completed_files` in
+// `.cluebase/implementation.json`).
+//
+// One command = one responsibility: shorter prompts, sharper goal, fewer
+// cross-step responsibility leaks.
+//
+// =========================================================================
+// WHERE THE SETUP PROMPT CONTENT LIVES:
+//
+// The AI prompt content for STEP 1 / 2 / 3 / 5 / 7 below is written here and
+// nowhere else. The web setup surface does not carry it: what that surface
+// generates is the environment block and the CLI invocation
+// (`apps/web/src/features/setup/code-snippets.ts`), not these prompts. So a
+// customer who never runs the CLI never sees the load-bearing rules stated
+// below -- the two-argument `cluebase.identify` signature, the dict-only Python
+// `cluebase.init` signature, where the lifecycle call belongs, and the rule
+// against adding `cluebase.track`.
+//
+// Nothing checks that. There is no second copy to drift from and no test
+// comparing the two surfaces, so changing a rule here changes it for CLI
+// customers only, silently. Anyone adding these rules to the web surface has
+// to add the comparison at the same time, or the copies part without a
+// failure anywhere.
+//
+// =========================================================================
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import {
+  buildStep1Discover,
+  buildStep2SelfReview,
+  buildStep3DiscoverContext,
+  buildStep4DiscoverCheck,
+} from "./setup-step-builders-discover.mjs";
+import {
+  buildStep5Implement,
+  buildStep6SetupCheck,
+  buildStep7Review,
+  buildStep9SetupDoctor,
+} from "./setup-step-builders-implement.mjs";
+import { buildStep8ValueEvents } from "./setup-step-builders-events.mjs";
+
+// --- Step file definition ------------------------------------------------
+//
+// Each entry below produces ONE file under `.claude/commands/`. Each STEP
+// represents ONE atomic responsibility: the AI tool runs it, completes
+// the single goal, persists progress to
+// `.cluebase/discoveries.json:_progress.completed_substeps`, prints the
+// Japanese hand-off line for the next STEP, and stops.
+//
+// `kind`:
+//   - "ai"   = the prompt instructs the AI tool to perform Read / Grep /
+//              Glob / Write / Edit operations.
+//   - "bash" = the prompt instructs the AI to run a cluebase-cli helper
+//              command via Bash (setup-discover-check / setup-check /
+//              setup-doctor).
+//
+// `id` is the marker recorded in
+// `.cluebase/discoveries.json:_progress.completed_substeps`. Re-running a
+// STEP after a crash uses this id to skip already-completed work.
+
+const STEP_FILES = [
+  {
+    index: 1,
+    file: "cluebase-discover.md",
+    kind: "ai",
+    builder: buildStep1Discover,
+    id: "step1_discover",
+    title: "STEP 1 — Discover (boundary enumeration)",
+    singleGoal:
+      "The ONLY goal of this command is to grep + Read the customer codebase exhaustively and produce the initial `.cluebase/discoveries.json` (lifecycle boundary candidates + db_schema grounding + env file paths). SDK call insertion, env file writes, code changes, and connectivity checks are ALL out of scope.",
+    scopeOut: [
+      "STEP 2 (= /cluebase-discover-review): self-review / fix of discoveries.json",
+      "STEP 3 (= /cluebase-discover-context): field-semantic enrichment (`available_fields` / `organization_context`)",
+      "STEP 4 (= /cluebase-discover-check): bash schema validation",
+      "STEP 5+ (= /cluebase-implement and later): any source code change",
+    ],
+    completion:
+      "`.cluebase/discoveries.json` is written with all boundaries + db_schema + env_files populated, `_progress.completed_substeps` is patched with `step1_discover`, and the Japanese hand-off line for STEP 2 is printed.",
+    nextHandoff: "/cluebase-discover-review",
+  },
+  {
+    index: 2,
+    file: "cluebase-discover-review.md",
+    kind: "ai",
+    builder: buildStep2SelfReview,
+    id: "step2_review",
+    title: "STEP 2 — Self-review of discoveries.json",
+    singleGoal:
+      "The ONLY goal of this command is to re-examine the existing `.cluebase/discoveries.json` and apply the rubric (server-side handler exclusion, read-path re-check, completeness sweep, evidence integrity, cluebase_init_* file existence, sentinel guard safety). The file may be rewritten in place. NO other artifact is touched.",
+    scopeOut: [
+      "STEP 1 (= /cluebase-discover): initial boundary enumeration (do NOT re-grep the entire repo from scratch)",
+      "STEP 3 (= /cluebase-discover-context): adding `available_fields` / `organization_context` (left to STEP 3)",
+      "STEP 5+ (= /cluebase-implement and later): code changes",
+    ],
+    completion:
+      "`.cluebase/discoveries.json` converges (rubric clean within 3 iterations), `_progress.completed_substeps` is patched with `step2_review`, and the Japanese hand-off line for STEP 3 is printed.",
+    nextHandoff: "/cluebase-discover-context",
+  },
+  {
+    index: 3,
+    file: "cluebase-discover-context.md",
+    kind: "ai",
+    builder: buildStep3DiscoverContext,
+    id: "step3_context",
+    title: "STEP 3 — Field semantic context enrichment",
+    singleGoal:
+      "The ONLY goal of this command is to enrich `.cluebase/discoveries.json` with two new pieces: per-site `available_fields` (concrete variable paths reachable at each insertion line) + top-level `organization_context` (the customer's company/organization label) + `env_lines` pre-computed for STEP 5. The customer code is NOT modified.",
+    scopeOut: [
+      "STEP 1 (= /cluebase-discover): boundary discovery",
+      "STEP 2 (= /cluebase-discover-review): rubric-based self-review",
+      "STEP 4 (= /cluebase-discover-check): bash validation",
+      "STEP 5+ (= /cluebase-implement and later): code edits, env file writes",
+    ],
+    completion:
+      "`.cluebase/discoveries.json` gains `available_fields` / `organization_context` / `env_lines`, `_progress.completed_substeps` is patched with `step3_context`, and the Japanese hand-off line for STEP 4 is printed.",
+    nextHandoff: "/cluebase-discover-check",
+  },
+  {
+    index: 4,
+    file: "cluebase-discover-check.md",
+    kind: "bash",
+    builder: buildStep4DiscoverCheck,
+    id: "step4_check",
+    title: "STEP 4 — Bash validation of discoveries.json",
+    singleGoal:
+      "The ONLY goal of this command is to mechanically validate `.cluebase/discoveries.json` via the `setup-discover-check` CLI helper, surface any error/warning, and (when an error is found) instruct the user which earlier STEP to re-run by removing the matching substepId from `_progress.completed_substeps`. No AI judgment, no code edits.",
+    scopeOut: [
+      "STEP 1-3: writing or modifying `.cluebase/discoveries.json` itself (only substepId removal allowed when re-running an earlier STEP)",
+      "STEP 5+ (= /cluebase-implement and later): code edits, env file writes",
+    ],
+    completion:
+      "`setup-discover-check` reports passed=true, `_progress.completed_substeps` is patched with `step4_check`, and the Japanese hand-off line for STEP 5 is printed. On failure: the user is told exactly which earlier STEP to re-run.",
+    nextHandoff: "/cluebase-implement",
+  },
+  {
+    index: 5,
+    file: "cluebase-implement.md",
+    kind: "ai",
+    builder: buildStep5Implement,
+    id: "step5_implement",
+    title: "STEP 5 — Implement (SDK call insertion + env file write)",
+    singleGoal:
+      "The ONLY goal of this command is to insert Cluebase SDK lifecycle calls (cluebase.init / cluebase.identify / cluebase.group / cluebase.reset + observer wire-ups) at the file:line positions recorded in `.cluebase/discoveries.json`, add the SDK as a package-manifest dependency, run the install command, and write the pre-computed `env_lines` into the customer's frontend/backend env files. NO discoveries.json edits, NO bash validation, NO connectivity checks.",
+    scopeOut: [
+      "STEP 1-4: modifying `.cluebase/discoveries.json` (it is read-only here)",
+      "STEP 6 (= /cluebase-implement-check): bash static check + diff snapshot generation",
+      "STEP 7 (= /cluebase-implement-review): self-review of the inserted code",
+      "STEP 8 (= /cluebase-events): business value event track insertion (cluebase.track is added there, not here)",
+      "STEP 9 (= /cluebase-doctor): real-server connectivity check",
+    ],
+    completion:
+      "All lifecycle / observer call sites in discoveries.json are inserted via Edit, SDK install is run successfully, env files are upserted with `env_lines`, `_progress.completed_substeps` is patched with `step5_implement`, and the Japanese hand-off line for STEP 6 is printed.",
+    nextHandoff: "/cluebase-implement-check",
+  },
+  {
+    index: 6,
+    file: "cluebase-implement-check.md",
+    kind: "bash",
+    builder: buildStep6SetupCheck,
+    id: "step6_check",
+    title: "STEP 6 — Bash static check + diff snapshot",
+    singleGoal:
+      "The ONLY goal of this command is to run `setup-check --require-sdk-lifecycle --repo . --write-snapshot` via Bash. This writes `.cluebase/setup-check.json` (the report) and `.cluebase/setup-diff.patch` (the diff snapshot). The AI tool MUST NOT interpret the JSON here — STEP 7 owns interpretation + auto-fix.",
+    scopeOut: [
+      "STEP 5: inserting lifecycle calls (already done)",
+      "STEP 7 (= /cluebase-implement-review): interpreting setup-check.json, applying P0/P1 fixes, loop logic",
+      "STEP 9 (= /cluebase-doctor): connectivity check",
+    ],
+    completion:
+      "`.cluebase/setup-check.json` and `.cluebase/setup-diff.patch` are written, `_progress.completed_substeps` is patched with `step6_check`, and the Japanese hand-off line for STEP 7 is printed.",
+    nextHandoff: "/cluebase-implement-review",
+  },
+  {
+    index: 7,
+    file: "cluebase-implement-review.md",
+    kind: "ai",
+    builder: buildStep7Review,
+    id: "step7_review",
+    title: "STEP 7 — Self-review + Auto-fix loop",
+    singleGoal:
+      "The ONLY goal of this command is to audit the implementation diff against the P0/P1 rubric, surgically fix any P0/P1 issue via Edit, refresh setup-check.json via Bash, and loop up to 3 iterations until convergence. `.cluebase/setup-review-findings.md` is written with either `NO_P0_P1` or the residual table.",
+    scopeOut: [
+      "STEP 5: inserting lifecycle calls (already done)",
+      "STEP 6: running setup-check (already done; only re-runs are allowed inside the loop)",
+      "STEP 8 (= /cluebase-events): business value event track insertion",
+      "STEP 9 (= /cluebase-doctor): real-server connectivity check",
+      "Modifying `.cluebase/discoveries.json` (it is read-only here)",
+    ],
+    completion:
+      "Either no P0/P1 remains (`setup-review-findings.md` says `NO_P0_P1`) or 3 iterations completed with residual findings printed to the user, `_progress.completed_substeps` is patched with `step7_review`, and the Japanese hand-off line for STEP 8 is printed.",
+    nextHandoff: "/cluebase-events",
+  },
+  {
+    index: 8,
+    file: "cluebase-events.md",
+    kind: "ai",
+    builder: buildStep8ValueEvents,
+    id: "step8_events",
+    title: "STEP 8 — Business value events (guided cluebase.track)",
+    singleGoal:
+      "The ONLY goal of this command is to instrument the customer's selected business VALUE milestones (paid conversion / cancellation / plan change / signup / invite / activation / any custom milestone) with a single cluebase.track call at the authoritative site, verify arrival + account linkage via the existing setup doctor, and record the mapping in `.cluebase/business-events.json`. Business value events are the ONLY place cluebase.track is added; lifecycle wiring, env writes, and connectivity gating are out of scope.",
+    scopeOut: [
+      "STEP 1-4 (= /cluebase-discover .. /cluebase-discover-check): re-discovering or editing lifecycle boundaries in discoveries.json (read-only grounding here)",
+      "STEP 5 (= /cluebase-implement): cluebase.init / cluebase.identify / cluebase.group / cluebase.reset placement + env writes (already done; do NOT add track there)",
+      "STEP 9 (= /cluebase-doctor): the holistic production-level connectivity gate",
+    ],
+    completion:
+      "Every selected value milestone is either instrumented with one cluebase.track at its authoritative site, recorded as external-source-only, or the selection is empty; `.cluebase/business-events.json` records the mapping, at least one arrival verification is attempted via `setup-doctor --local` + published batch evidence, `_progress.completed_substeps` is patched with `step8_events`, and the Japanese hand-off line for STEP 9 is printed.",
+    nextHandoff: "/cluebase-doctor",
+  },
+  {
+    index: 9,
+    file: "cluebase-doctor.md",
+    kind: "bash",
+    builder: buildStep9SetupDoctor,
+    id: "step9_doctor",
+    title: "STEP 9 — Production-level setup verification",
+    singleGoal:
+      "The ONLY goal of this command is to run `setup-doctor --local` via Bash. It probes Cluebase token issue, browser ingest, and backend ingest with SDK-equivalent payloads from customer env files, checks downstream browser/backend batch publish evidence, scans for forbidden customer-backend Cluebase routes, and runs 30 data-quality checks. `/cluebase-doctor` is intentionally STATELESS — re-run any time after fixes.",
+    scopeOut: [
+      "STEP 1-8 (= /cluebase-discover .. /cluebase-events): anything that modifies discoveries.json, customer code, business-events.json, or runs the static check",
+      "Persisting progress (this STEP is stateless — DO NOT write to the `_progress` array; it is intentionally re-runnable)",
+    ],
+    completion:
+      "`setup-doctor --local` either passes (API/published checks + downstream browser/backend batch publish evidence + customer-backend Cluebase route scan + data-quality error checks green) and the Japanese success message is printed, or fails and the user is given concrete env-fix / dev-server-restart instructions plus the offer to re-run `/cluebase-doctor`.",
+    nextHandoff: null,
+  },
+];
+
+// State-recovery contract embedded at the top of every stateful STEP
+// (STEP 1-8). STEP 9 is stateless — see STATELESS_STATE_HEADER. The
+// contract MUST be small enough to keep the per-STEP prompt short, so we
+// keep it to the absolute essentials (skip-if-completed + patch-on-finish).
+const STATEFUL_STATE_HEADER = `## State recovery (read BEFORE doing anything)
+
+This command is **idempotent + resumable**. Before doing any work:
+
+1. Use the Read tool on \`.cluebase/discoveries.json\`. If \`_progress.completed_substeps\` exists and contains \`<SUBSTEP_ID>\`, this STEP has already finished — respond with the single Japanese line "STEP <STEP_INDEX> は完了済みです。 次は Claude Code で <NEXT_HANDOFF> を実行してください。" and STOP. Do NOT redo the work.
+2. If the substepId is NOT present (= first run, or a previous crash), proceed with the STEP body below.
+3. **After the STEP body completes successfully**, use the Write/Edit tool to patch \`.cluebase/discoveries.json\` so its top-level \`_progress\` field is:
+   \`\`\`jsonc
+   {
+     "_progress": {
+       "completed_substeps": ["<previously-completed ids>", "<SUBSTEP_ID>"],
+       "last_updated_at": "<ISO 8601 UTC timestamp>"
+     }
+   }
+   \`\`\`
+   Preserve every other top-level field. The array dedups — do not add a duplicate id.
+4. **STEP 5 only** — also append per-file completion to \`.cluebase/implementation.json\`'s \`completed_files\` array. Before re-inserting into a file, check the array; if the file is present, skip that insertion (the entry is the proof of prior work).
+5. **Customer escape hatch**: \`rm -rf .cluebase/\` followed by re-running the STEP gives a clean re-run.
+
+---
+
+`;
+
+const STATELESS_STATE_HEADER = `## Stateless health check (read BEFORE doing anything)
+
+\`/cluebase-doctor\` does NOT write to \`.cluebase/discoveries.json:_progress\` or \`.cluebase/implementation.json\`. Re-run it any time after env / dev-server / project-key changes — there is no "completed" state to skip.
+
+---
+
+`;
+
+// Compose a single STEP's slash command body by wrapping the existing
+// per-STEP builder output with:
+//   - a header that pins this STEP's single goal + scope-out items +
+//     completion criterion (so the AI tool sees the responsibility
+//     contract BEFORE the long instruction body),
+//   - the state-recovery contract,
+//   - the original per-STEP prompt body produced by `builder(...)`,
+//   - a small footer reminding the AI to record progress + print the
+//     hand-off line for the next STEP.
+function buildStepBody(step, { documentsUrl }) {
+  const goalLine = `## SINGLE GOAL (= this command's only purpose)\n\n${step.singleGoal}`;
+  const scopeOutBlock = step.scopeOut.length
+    ? `## SCOPE OUT (= DO NOT do these — they belong to other STEP commands)\n\n${step.scopeOut.map((line) => `- ${line}`).join("\n")}`
+    : "";
+  const completionBlock = `## Completion criterion\n\n${step.completion}`;
+  const handoffLine = step.nextHandoff
+    ? `Hand-off (last action of this STEP): print one Japanese line in this exact shape and STOP — \`<STEP ${step.index} completion summary>。 次は Claude Code で ${step.nextHandoff} を実行してください。\` Substitute concrete numbers / counts where the per-STEP body specifies them; the per-STEP body below provides the exact wording.`
+    : `Hand-off (last action of this STEP): print the STEP 9 success or failure block in Japanese exactly as specified by the per-STEP body below, then STOP.`;
+
+  const stateHeader =
+    step.id === "step9_doctor"
+      ? STATELESS_STATE_HEADER
+      : STATEFUL_STATE_HEADER.replaceAll("<SUBSTEP_ID>", step.id)
+          .replaceAll("<STEP_INDEX>", String(step.index))
+          .replaceAll("<NEXT_HANDOFF>", step.nextHandoff ?? "/cluebase-doctor");
+
+  const body = step.builder({ documentsUrl });
+
+  return `# ${step.title} (= ${step.file.replace(/\.md$/, "")})
+
+${goalLine}
+
+${scopeOutBlock}
+
+${completionBlock}
+
+${stateHeader}## STEP body
+
+${body}
+
+---
+
+${handoffLine}
+`;
+}
+
+const STEP_COMMAND_NAMES = STEP_FILES.map((step) =>
+  step.file.replace(/\.md$/, ""),
+);
+
+const toCodexStepInvocation = (commandName) => `$${commandName}`;
+
+const toCodexSkillText = (text) => {
+  let normalized = text
+    .replaceAll("Claude Code", "Codex")
+    .replaceAll("Claude writes", "Codex writes")
+    .replaceAll("Claude sets", "Codex sets")
+    .replaceAll("Claude setup", "Codex setup")
+    .replaceAll("Claude", "Codex")
+    .replaceAll("slash command", "Codex skill command")
+    .replaceAll("slash commands", "Codex skill commands");
+
+  for (const commandName of STEP_COMMAND_NAMES) {
+    normalized = normalized.replaceAll(
+      `/${commandName}`,
+      toCodexStepInvocation(commandName),
+    );
+  }
+
+  return normalized;
+};
+
+function buildCodexStepSkillBody(step, { documentsUrl }) {
+  const commandName = step.file.replace(/\.md$/, "");
+  const body = toCodexSkillText(buildStepBody(step, { documentsUrl }));
+  return `---
+name: ${commandName}
+description: Use in Codex when running Cluebase setup STEP ${step.index} (${step.title}).
+setup_step_id: ${step.id}
+---
+
+${body}`;
+}
+
+// Test hook: expose the step builders so external tests can assert the
+// generated prompt content (semantic-detection language, halt rules, db_schema
+// grounding instructions, etc.) without going through filesystem writes.
+// This is a documented internal surface — keep the keys stable.
+export const STEP_BUILDERS_FOR_TEST = {
+  step1Discover: buildStep1Discover,
+  step2SelfReview: buildStep2SelfReview,
+  step3DiscoverContext: buildStep3DiscoverContext,
+  step4DiscoverCheck: buildStep4DiscoverCheck,
+  step5Implement: buildStep5Implement,
+  step6SetupCheck: buildStep6SetupCheck,
+  step7Review: buildStep7Review,
+  step8ValueEvents: buildStep8ValueEvents,
+  step9SetupDoctor: buildStep9SetupDoctor,
+};
+
+// Test hook for the 8-file step layout. Returns the step definitions so
+// tests can assert single-goal headers / scope-out blocks / state-recovery
+// header presence / per-step file mapping without going through
+// filesystem writes.
+export const STEP_DEFINITIONS_FOR_TEST = STEP_FILES;
+export { buildStepBody as BUILD_STEP_BODY_FOR_TEST };
+export { buildCodexStepSkillBody as BUILD_CODEX_STEP_SKILL_BODY_FOR_TEST };
+
+export async function writeCluebaseStepCommands({ repoRoot, documentsUrl }) {
+  const commandsDir = join(repoRoot, ".claude", "commands");
+  await mkdir(commandsDir, { recursive: true });
+
+  const writtenAbs = [];
+  for (const step of STEP_FILES) {
+    const content = buildStepBody(step, { documentsUrl });
+    const absPath = join(commandsDir, step.file);
+    await writeFile(absPath, content, "utf8");
+    writtenAbs.push(absPath);
+  }
+
+  return writtenAbs.map((abs) => relative(repoRoot, abs));
+}
+
+export async function writeCodexStepSkills({ repoRoot, documentsUrl }) {
+  const skillsDir = join(repoRoot, ".agents", "skills");
+  await mkdir(skillsDir, { recursive: true });
+
+  const writtenAbs = [];
+  for (const step of STEP_FILES) {
+    const commandName = step.file.replace(/\.md$/, "");
+    const absPath = join(skillsDir, commandName, "SKILL.md");
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(
+      absPath,
+      buildCodexStepSkillBody(step, { documentsUrl }),
+      "utf8",
+    );
+    writtenAbs.push(absPath);
+  }
+
+  return writtenAbs.map((abs) => relative(repoRoot, abs));
+}

package/src/setup-tool.mjs

@@ -0,0 +1,27 @@
+import { resolve } from "node:path";
+
+/**
+ * Install the canonical nine setup commands for both supported coding tools.
+ * The setup flow owns one command per step; role-based skill bundles are not
+ * part of the customer-facing MVP contract.
+ */
+export const installSetupSteps = async ({ repoRoot, documentsUrl } = {}) => {
+	const resolvedRepoRoot = resolve(repoRoot ?? ".");
+	const { writeCluebaseStepCommands, writeCodexStepSkills } = await import(
+		"./setup-step-commands.mjs",
+	);
+
+	const setupCommands = await writeCluebaseStepCommands({
+		repoRoot: resolvedRepoRoot,
+		documentsUrl: documentsUrl ?? "",
+	});
+	const setupSkills = await writeCodexStepSkills({
+		repoRoot: resolvedRepoRoot,
+		documentsUrl: documentsUrl ?? "",
+	});
+
+	return {
+		setup_commands: setupCommands,
+		codex_setup_skills: setupSkills,
+	};
+};