@alecsibilia/luca 13.0.0-alpha.1

package/dist/chunks/rules.mjs

@@ -0,0 +1,527 @@
+import { defineCommand } from 'citty';
+import { join as join$1 } from 'pathe';
+import '../shared/luca.CRmaAfXR.mjs';
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import 'node:fs/promises';
+import { isAbsolute, resolve, join, extname } from 'node:path';
+import 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import 'node:child_process';
+import { a as analyzeRun, g as gatherRunArtifacts } from '../shared/luca.C4gMUoBd.mjs';
+import { l as listRuns } from '../shared/luca.HZxBTBgD.mjs';
+import { l as logger } from '../shared/luca.dM-MKlNE.mjs';
+import 'zod';
+import 'node:os';
+import '../shared/luca.BmhNkYe2.mjs';
+import '../shared/luca.TSMg1t7I.mjs';
+import 'consola';
+
+let tsModuleCache = void 0;
+function resolveTypeScript() {
+  if (tsModuleCache !== void 0) return tsModuleCache;
+  try {
+    const req = createRequire(import.meta.url);
+    tsModuleCache = req("typescript");
+  } catch {
+    tsModuleCache = null;
+  }
+  return tsModuleCache;
+}
+function walkDir(dir, extensions, out = []) {
+  if (!existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    if (name.startsWith(".") || name === "node_modules") continue;
+    const full = join(dir, name);
+    let stats;
+    try {
+      stats = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      walkDir(full, extensions, out);
+    } else if (extensions.includes(extname(name))) {
+      if (name.endsWith(".test.ts")) continue;
+      if (name.endsWith(".test.js")) continue;
+      if (name.endsWith(".spec.ts")) continue;
+      if (name.endsWith(".spec.js")) continue;
+      out.push(full);
+    }
+  }
+  return out;
+}
+function isRuleDefinition(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.id === "string" && typeof v.severity === "string" && typeof v.description === "string" && typeof v.check === "function" && v.scope !== void 0 && v.scope !== null;
+}
+function extractRules(module) {
+  if (!module || typeof module !== "object") return [];
+  const collected = [];
+  const visit = (value) => {
+    if (isRuleDefinition(value)) {
+      collected.push(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const v of value) visit(v);
+      return;
+    }
+  };
+  for (const key of Object.keys(module)) {
+    visit(module[key]);
+  }
+  return collected;
+}
+async function loadRules(opts) {
+  const { rulesDir } = opts;
+  const loadErrors = [];
+  const files = walkDir(rulesDir, [".ts", ".mts", ".js", ".mjs"]);
+  const rules = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    try {
+      const url = pathToFileURL(file).href;
+      const mod = await import(url);
+      for (const rule of extractRules(mod)) {
+        if (seenIds.has(rule.id)) {
+          loadErrors.push({
+            file,
+            message: `duplicate rule id: ${rule.id} (already defined elsewhere)`
+          });
+          continue;
+        }
+        seenIds.add(rule.id);
+        rules.push(rule);
+      }
+    } catch (err) {
+      loadErrors.push({
+        file,
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return { rules, filesDiscovered: files.length, loadErrors };
+}
+function asArray(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function resolveScope(opts) {
+  const { repoRoot, scope, exclude } = opts;
+  if (scope === "repo") return [""];
+  const globs = asArray(scope);
+  if (globs.length === 0) return [];
+  const collected = /* @__PURE__ */ new Set();
+  const BunGlobal = globalThis.Bun;
+  if (!BunGlobal?.Glob) {
+    throw new Error(
+      "rules-runner: Bun runtime required for glob scope resolution"
+    );
+  }
+  for (const pattern of globs) {
+    const glob = new BunGlobal.Glob(pattern);
+    for (const match of glob.scanSync({ cwd: repoRoot, onlyFiles: true })) {
+      collected.add(match);
+    }
+  }
+  if (exclude.length > 0) {
+    const excludeMatches = /* @__PURE__ */ new Set();
+    for (const pattern of exclude) {
+      const glob = new BunGlobal.Glob(pattern);
+      for (const match of glob.scanSync({
+        cwd: repoRoot,
+        onlyFiles: true
+      })) {
+        excludeMatches.add(match);
+      }
+    }
+    for (const path of collected) {
+      if (excludeMatches.has(path)) collected.delete(path);
+    }
+  }
+  return [...collected];
+}
+function scriptKindFor(tsMod, path) {
+  const ext = extname(path).toLowerCase();
+  switch (ext) {
+    case ".ts":
+      return tsMod.ScriptKind.TS;
+    case ".tsx":
+      return tsMod.ScriptKind.TSX;
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return tsMod.ScriptKind.JS;
+    case ".jsx":
+      return tsMod.ScriptKind.JSX;
+    case ".json":
+      return tsMod.ScriptKind.JSON;
+    default:
+      return tsMod.ScriptKind.Unknown;
+  }
+}
+function makeRuleFile(opts) {
+  const { repoRoot, relPath, contentCache, astCache } = opts;
+  const absolutePath = resolve(repoRoot, relPath);
+  let content = contentCache.get(relPath);
+  if (content === void 0) {
+    try {
+      content = readFileSync(absolutePath, "utf-8");
+    } catch {
+      return null;
+    }
+    contentCache.set(relPath, content);
+  }
+  const fileContent = content;
+  return {
+    path: relPath,
+    absolutePath,
+    content: fileContent,
+    ast() {
+      if (astCache.has(relPath)) return astCache.get(relPath) ?? null;
+      const tsMod = resolveTypeScript();
+      if (!tsMod) {
+        astCache.set(relPath, null);
+        return null;
+      }
+      const kind = scriptKindFor(tsMod, relPath);
+      if (kind === tsMod.ScriptKind.Unknown) {
+        astCache.set(relPath, null);
+        return null;
+      }
+      try {
+        const sf = tsMod.createSourceFile(
+          relPath,
+          fileContent,
+          tsMod.ScriptTarget.Latest,
+          /* setParentNodes */
+          true,
+          kind
+        );
+        astCache.set(relPath, sf);
+        return sf;
+      } catch {
+        astCache.set(relPath, null);
+        return null;
+      }
+    }
+  };
+}
+function runRules(opts) {
+  const { repoRoot, rules } = opts;
+  const findings = [];
+  const executionErrors = [];
+  const timings = {};
+  const contentCache = /* @__PURE__ */ new Map();
+  const astCache = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    const start = performance.now();
+    const exclude = asArray(rule.exclude);
+    let candidates;
+    try {
+      candidates = resolveScope({ repoRoot, scope: rule.scope, exclude });
+    } catch (err) {
+      executionErrors.push({
+        ruleId: rule.id,
+        path: "",
+        message: `scope resolution failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+      timings[rule.id] = performance.now() - start;
+      continue;
+    }
+    for (const relPath of candidates) {
+      const file = relPath === "" ? {
+        path: "",
+        absolutePath: repoRoot,
+        content: "",
+        ast: () => null
+      } : makeRuleFile({
+        repoRoot,
+        relPath,
+        contentCache,
+        astCache
+      });
+      if (!file) continue;
+      try {
+        const ruleFindings = rule.check(file);
+        if (Array.isArray(ruleFindings)) {
+          for (const finding of ruleFindings) {
+            if (!finding.category && rule.category) {
+              finding.category = rule.category;
+            }
+            findings.push(finding);
+          }
+        }
+      } catch (err) {
+        executionErrors.push({
+          ruleId: rule.id,
+          path: relPath,
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    timings[rule.id] = performance.now() - start;
+  }
+  return { timings, findings, executionErrors };
+}
+async function discoverAndRun(opts) {
+  const repoRoot = isAbsolute(opts.repoRoot) ? opts.repoRoot : resolve(opts.repoRoot);
+  const rulesDir = opts.rulesDir ? isAbsolute(opts.rulesDir) ? opts.rulesDir : resolve(repoRoot, opts.rulesDir) : join(repoRoot, ".luca", "rules");
+  const { rules, filesDiscovered, loadErrors } = await loadRules({ rulesDir });
+  const { timings, findings, executionErrors } = runRules({ repoRoot, rules });
+  return {
+    rulesFilesDiscovered: filesDiscovered,
+    rulesLoaded: rules.length,
+    timings,
+    findings,
+    loadErrors,
+    executionErrors
+  };
+}
+
+const DEFAULT_THRESHOLD = 3;
+function codeToSlug(code) {
+  return code.toLowerCase().replace(/_/g, "-");
+}
+function detectRecurringPitfalls(opts) {
+  const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+  const stats = /* @__PURE__ */ new Map();
+  for (const report of opts.reports) {
+    for (const v of report.violations) {
+      let entry = stats.get(v.code);
+      if (!entry) {
+        entry = {
+          runIds: /* @__PURE__ */ new Set(),
+          occurrences: 0,
+          sampleMessage: v.message
+        };
+        stats.set(v.code, entry);
+      }
+      entry.runIds.add(report.runId);
+      entry.occurrences += 1;
+      entry.sampleMessage = v.message;
+    }
+  }
+  const recurring = [];
+  for (const [code, entry] of stats) {
+    if (entry.runIds.size < threshold) continue;
+    const slug = codeToSlug(code);
+    recurring.push({
+      code,
+      runCount: entry.runIds.size,
+      occurrences: entry.occurrences,
+      runIds: [...entry.runIds],
+      sampleMessage: entry.sampleMessage,
+      suggestedRuleId: `recurring/${slug}`,
+      pitfallConcept: `pitfall:${slug}`
+    });
+  }
+  recurring.sort((a, b) => b.runCount - a.runCount);
+  return { runsScanned: opts.reports.length, threshold, recurring };
+}
+function renderDraftRule(pitfall) {
+  const sample = pitfall.sampleMessage.replace(/\\/g, "\\\\").replace(/`/g, "\\`");
+  return `/**
+ * Auto-suggested rule from luca recurrence detection.
+ *
+ * This pitfall has appeared in ${pitfall.runCount} distinct run(s)
+ * (${pitfall.occurrences} total occurrence(s)).
+ *
+ * Sample violation message:
+ *   ${sample}
+ *
+ * NEXT STEPS:
+ *   1. Decide what code pattern this rule should catch.
+ *   2. Implement the matcher in the \`check\` function below.
+ *      - Use \`file.content\` for regex checks.
+ *      - Use \`file.ast()\` for AST-level matching.
+ *   3. Set \`scope\` to the glob of files this rule should run against.
+ *   4. Refine the severity (defaults to 'should-fix').
+ *   5. Delete this comment block once the rule is real.
+ *
+ * The rule is exported as a plain duck-typed object so it works in any
+ * consumer repo without a runtime dependency on the harness package.
+ */
+
+export default {
+    id: '${pitfall.suggestedRuleId}',
+    severity: 'should-fix',
+    description: '${pitfall.code}: ${sample.replace(/'/g, "\\'")}',
+    scope: 'src/**/*.ts',
+    category: 'recurring',
+    check: (file) => {
+        // TODO: implement the check.
+        // Example (regex):
+        //   const findings = []
+        //   const re = /badPattern/g
+        //   let match
+        //   while ((match = re.exec(file.content)) !== null) {
+        //       const line = file.content.slice(0, match.index).split('\\n').length
+        //       findings.push({
+        //           id: \`${pitfall.suggestedRuleId}:\${file.path}:\${line}\`,
+        //           path: file.path,
+        //           line,
+        //           severity: 'should-fix',
+        //           summary: 'Recurring pitfall detected',
+        //       })
+        //   }
+        //   return findings
+        return []
+    },
+}
+`;
+}
+function renderSuggestedRulesMarkdown(report) {
+  if (report.recurring.length === 0) {
+    return `# Suggested Rules
+
+No recurring pitfalls met the threshold (>= ${report.threshold} runs).
+Scanned ${report.runsScanned} run(s).
+`;
+  }
+  const sections = report.recurring.map(
+    (p) => `## ${p.code} \u2014 ${p.runCount} run(s), ${p.occurrences} occurrence(s)
+
+**Suggested rule id**: \`${p.suggestedRuleId}\`
+**Pitfall concept**: \`${p.pitfallConcept}\`
+**Sample message**: ${p.sampleMessage}
+
+**Runs where this appeared**:
+${p.runIds.map((id) => `- ${id}`).join("\n")}
+
+**Draft rule** \u2014 copy to \`.luca/rules/${codeToSlug(p.code)}.ts\` and fill in the matcher:
+
+\`\`\`ts
+${renderDraftRule(p)}\`\`\`
+`
+  );
+  return `# Suggested Rules
+
+Recurring pitfalls detected at threshold >= ${report.threshold} runs (out of ${report.runsScanned} scanned).
+
+These suggestions are **drafts**. Each is a starting template, not an automatic addition. Review the sample messages, decide whether the pattern is mechanically detectable, fill in the matcher, and commit the rule to \`.luca/rules/\`.
+
+---
+
+${sections.join("\n---\n\n")}`;
+}
+
+function reportFindings(report) {
+  logger.info(
+    `Discovered ${report.rulesFilesDiscovered} rule file(s), loaded ${report.rulesLoaded} rule(s).`
+  );
+  for (const e of report.loadErrors) {
+    logger.error(`load error in ${e.file}: ${e.message}`);
+  }
+  for (const e of report.executionErrors) {
+    logger.error(
+      `rule '${e.ruleId}' failed${e.path ? ` on ${e.path}` : ""}: ${e.message}`
+    );
+  }
+  for (const f of report.findings) {
+    const loc = f.line !== void 0 ? `${f.path || "<repo>"}:${f.line}` : f.path || "<repo>";
+    logger.info(`  ${f.severity}  ${loc}  ${f.summary}`);
+  }
+  if (report.findings.length === 0) {
+    logger.success("No rule findings.");
+  } else {
+    logger.warn(`${report.findings.length} rule finding(s).`);
+  }
+}
+const listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List the rules discovered under .luca/rules/."
+  },
+  async run() {
+    const { rules, filesDiscovered, loadErrors } = await loadRules({
+      rulesDir: join$1(process.cwd(), ".luca", "rules")
+    });
+    for (const e of loadErrors) {
+      logger.error(`load error in ${e.file}: ${e.message}`);
+    }
+    if (rules.length === 0) {
+      logger.info(
+        `No rules found (${filesDiscovered} file(s) under .luca/rules/).`
+      );
+      return;
+    }
+    for (const r of rules) {
+      logger.info(`${r.id}  [${r.severity}]  ${r.description}`);
+    }
+  }
+});
+const runCommand = defineCommand({
+  meta: {
+    name: "run",
+    description: "Run every repo-local rule pack and report its findings."
+  },
+  async run() {
+    reportFindings(await discoverAndRun({ repoRoot: process.cwd() }));
+  }
+});
+const gateCommand = defineCommand({
+  meta: {
+    name: "gate",
+    description: "Run every rule; exit non-zero if any must-fix finding is produced."
+  },
+  async run() {
+    const report = await discoverAndRun({ repoRoot: process.cwd() });
+    reportFindings(report);
+    const mustFix = report.findings.filter(
+      (f) => f.severity === "must-fix"
+    );
+    if (mustFix.length > 0) {
+      logger.error(
+        `${mustFix.length} must-fix finding(s) \u2014 rule gate failed.`
+      );
+      process.exitCode = 1;
+    }
+  }
+});
+const suggestCommand = defineCommand({
+  meta: {
+    name: "suggest",
+    description: "Surface postmortem pitfalls that recurred across runs as draft rules."
+  },
+  args: {
+    threshold: {
+      type: "string",
+      description: "Distinct-run recurrence threshold (default 3)."
+    }
+  },
+  run({ args }) {
+    const cwd = process.cwd();
+    const reports = listRuns({ cwd }).map(
+      (r) => analyzeRun(gatherRunArtifacts({ cwd, runId: r.runId }))
+    );
+    const threshold = args.threshold !== void 0 && Number.isFinite(Number(args.threshold)) ? Number(args.threshold) : void 0;
+    const recurrence = detectRecurringPitfalls({ reports, threshold });
+    process.stdout.write(
+      `${renderSuggestedRulesMarkdown(recurrence)}
+`
+    );
+  }
+});
+const rulesCommand = defineCommand({
+  meta: {
+    name: "rules",
+    description: "Repo-local rule packs (.luca/rules/)."
+  },
+  subCommands: {
+    list: listCommand,
+    run: runCommand,
+    gate: gateCommand,
+    suggest: suggestCommand
+  }
+});
+
+export { rulesCommand };

package/dist/chunks/stale-mcp-server.mjs

@@ -0,0 +1,90 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CHECK_NAME = "MCP server registration";
+function isLucaMcpEntry(entry) {
+  if (entry === null || typeof entry !== "object") return false;
+  const { command, args } = entry;
+  if (command !== "luca") return false;
+  return Array.isArray(args) && args.map(String).includes("mcp");
+}
+async function readJsonObject(path) {
+  try {
+    const file = Bun.file(path);
+    if (!await file.exists()) return null;
+    const parsed = JSON.parse(await file.text());
+    return parsed !== null && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function lucaServerKeys(mcpServers) {
+  if (mcpServers === null || typeof mcpServers !== "object") return [];
+  return Object.entries(mcpServers).filter(([, value]) => isLucaMcpEntry(value)).map(([key]) => key);
+}
+const staleMcpServerCheck = {
+  name: CHECK_NAME,
+  scope: "prerequisites",
+  async run() {
+    const cwd = process.cwd();
+    const findings = [];
+    let inertSettingsEntry = false;
+    const mcpJson = await readJsonObject(join(cwd, ".mcp.json"));
+    for (const key of lucaServerKeys(mcpJson?.mcpServers)) {
+      findings.push(`.mcp.json (mcpServers.${key})`);
+    }
+    const settings = await readJsonObject(
+      join(cwd, ".claude", "settings.json")
+    );
+    for (const key of lucaServerKeys(settings?.mcpServers)) {
+      findings.push(`.claude/settings.json (mcpServers.${key}, inert)`);
+      inertSettingsEntry = true;
+    }
+    const userConfig = await readJsonObject(join(homedir(), ".claude.json"));
+    for (const key of lucaServerKeys(userConfig?.mcpServers)) {
+      findings.push(`~/.claude.json (mcpServers.${key})`);
+    }
+    const projects = userConfig?.projects;
+    if (projects !== null && typeof projects === "object") {
+      const project = projects[cwd];
+      if (project !== null && typeof project === "object") {
+        for (const key of lucaServerKeys(
+          project.mcpServers
+        )) {
+          findings.push(
+            `~/.claude.json (projects[cwd].mcpServers.${key})`
+          );
+        }
+      }
+    }
+    if (findings.length === 0) {
+      return {
+        name: CHECK_NAME,
+        status: "pass",
+        message: "no stale luca MCP server registration",
+        fixCommand: null,
+        details: null
+      };
+    }
+    const detailLines = [
+      "`luca mcp serve` was removed in v13 \u2014 the write surface is now",
+      "the `luca` CLI plus the native Write tool. Stale registration in:",
+      ...findings.map((finding) => `- ${finding}`)
+    ];
+    if (inertSettingsEntry) {
+      detailLines.push(
+        "`claude mcp remove luca` clears .mcp.json and ~/.claude.json.",
+        "The .claude/settings.json block is inert \u2014 remove it by hand."
+      );
+    }
+    return {
+      name: CHECK_NAME,
+      status: "warning",
+      message: "stale luca MCP server still registered (removed in v13)",
+      fixCommand: "claude mcp remove luca",
+      details: detailLines.join("\n  ")
+    };
+  }
+};
+
+export { staleMcpServerCheck };

package/dist/chunks/state.mjs

@@ -0,0 +1,57 @@
+import { defineCommand } from 'citty';
+import 'zod';
+import '../shared/luca.CRmaAfXR.mjs';
+import 'node:fs';
+import 'node:fs/promises';
+import 'node:path';
+import 'node:crypto';
+import 'node:module';
+import 'node:url';
+import 'node:child_process';
+import { r as runWriteHandler, l as lucaStateAdvanceTool, a as lucaStateReadTool } from '../shared/luca.DjDTeDCi.mjs';
+import 'node:os';
+import '../shared/luca.CrXzXueR.mjs';
+import '../shared/luca.HZxBTBgD.mjs';
+import '../shared/luca.TSMg1t7I.mjs';
+import '../shared/luca.CQ3g1xrD.mjs';
+import '../shared/luca.B3Mimc0P.mjs';
+
+const readCommand = defineCommand({
+  meta: {
+    name: "read",
+    description: "Read the current workflow state from .luca/state.json \u2014 pipelineStep, currentPhase, iteration counters, and roadmap. Pure read; allowed in every pipelineStep."
+  },
+  async run() {
+    await runWriteHandler("state read", lucaStateReadTool, {});
+  }
+});
+const advanceCommand = defineCommand({
+  meta: {
+    name: "advance",
+    description: "Atomically advance the workflow pipelineStep. The transition is validated against the pipeline-transitions table; illegal jumps are rejected."
+  },
+  args: {
+    "to-step": {
+      type: "string",
+      required: true,
+      description: "Target pipelineStep (e.g. research, plan, execute). Must be a legal transition from the current step."
+    }
+  },
+  async run({ args }) {
+    await runWriteHandler("state advance", lucaStateAdvanceTool, {
+      toStep: args["to-step"]
+    });
+  }
+});
+const stateCommand = defineCommand({
+  meta: {
+    name: "state",
+    description: "Read and advance the Luca workflow state machine"
+  },
+  subCommands: {
+    read: readCommand,
+    advance: advanceCommand
+  }
+});
+
+export { stateCommand };