@prepcli/prepcli 0.1.0

package/src/commands/context.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const { execSync } = require("node:child_process");
+const { requireLoginFresh, readRC } = require("../lib/config");
+const api = require("../lib/api");
+
+function fmtContext(ctx) {
+  const lines = [];
+
+  if (ctx.stack && Object.keys(ctx.stack).length > 0) {
+    lines.push("Stack:");
+    for (const [k, v] of Object.entries(ctx.stack)) lines.push(`  ${k}: ${v}`);
+  }
+
+  if (ctx.hard_limits?.length) {
+    lines.push("\nHard limits:");
+    ctx.hard_limits.forEach(l => lines.push(`  • ${l}`));
+  }
+
+  if (ctx.active_constraints?.length) {
+    lines.push("\nActive constraints:");
+    ctx.active_constraints.forEach(l => lines.push(`  • ${l}`));
+  }
+
+  if (ctx.conventions && Object.keys(ctx.conventions).length > 0) {
+    lines.push("\nConventions:");
+    Object.values(ctx.conventions).forEach(v => lines.push(`  • ${v}`));
+  }
+
+  if (ctx.recent_decisions?.length) {
+    lines.push("\nRecent decisions:");
+    ctx.recent_decisions.slice(0, 5).forEach(d => {
+      lines.push(`  • ${d.what}${d.why ? ` — ${d.why}` : ""}`);
+    });
+  }
+
+  if (ctx.open_questions?.length) {
+    lines.push("\nOpen questions:");
+    ctx.open_questions.forEach(q => lines.push(`  ? ${q}`));
+  }
+
+  return lines.join("\n");
+}
+
+function fmtPreview(ctx) {
+  const parts = [];
+
+  if (ctx.stack && Object.keys(ctx.stack).length > 0) {
+    parts.push("Stack: " + Object.entries(ctx.stack).map(([k, v]) => `${k}=${v}`).join(", "));
+  }
+  if (ctx.hard_limits?.length) {
+    parts.push("Hard limits: " + ctx.hard_limits.join("; "));
+  }
+  if (ctx.active_constraints?.length) {
+    parts.push("Active constraints: " + ctx.active_constraints.join("; "));
+  }
+  if (ctx.conventions && Object.keys(ctx.conventions).length > 0) {
+    parts.push("Conventions: " + Object.values(ctx.conventions).join("; "));
+  }
+  if (ctx.recent_decisions?.length) {
+    const recent = ctx.recent_decisions.slice(0, 3).map(d => d.what).join("; ");
+    parts.push("Recent decisions: " + recent);
+  }
+
+  return parts.join("\n");
+}
+
+async function run(opts) {
+  const rc = readRC();
+
+  // ── Local fallback (not logged in / no project_id) ────────────────────────
+  if (!rc?.project_id) {
+    if (!rc?.context) {
+      console.error("No context found. Run: prepcli init");
+      process.exit(1);
+    }
+    const ctx = rc.context;
+
+    if (opts.preview) {
+      console.log(fmtPreview(ctx));
+      return;
+    }
+
+    console.log("\nProject context (local):\n");
+    console.log(fmtContext(ctx));
+    console.log("\nNote: context is local only. Log in with `prepcli auth login` to sync to cloud.");
+    return;
+  }
+
+  // ── Cloud ─────────────────────────────────────────────────────────────────
+  const cfg = await requireLoginFresh();
+
+  let ctx;
+  try {
+    const result = await api.get(`/projects/${rc.project_id}/context`, cfg.access_token);
+    ctx = result.context;
+  } catch (err) {
+    console.error(`Failed to fetch context: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!ctx) {
+    console.log("No context stored yet. Run: prepcli init");
+    return;
+  }
+
+  if (opts.preview) {
+    console.log(fmtPreview(ctx));
+    return;
+  }
+
+  if (opts.edit) {
+    const os   = require("node:os");
+    const fs   = require("node:fs");
+    const path = require("node:path");
+
+    const tmp = path.join(os.tmpdir(), `prepcli-ctx-${Date.now()}.json`);
+    fs.writeFileSync(tmp, JSON.stringify(ctx, null, 2));
+
+    const editor = process.env.EDITOR || process.env.VISUAL || "nano";
+    try {
+      execSync(`${editor} "${tmp}"`, { stdio: "inherit" });
+    } catch {
+      console.error("Editor closed with error. No changes saved.");
+      try { fs.unlinkSync(tmp); } catch {}
+      process.exit(1);
+    }
+
+    let updated;
+    try {
+      updated = JSON.parse(fs.readFileSync(tmp, "utf8"));
+    } catch {
+      console.error("File contains invalid JSON. No changes saved.");
+      try { fs.unlinkSync(tmp); } catch {}
+      process.exit(1);
+    }
+    try { fs.unlinkSync(tmp); } catch {}
+
+    await api.put(`/projects/${rc.project_id}/context`, updated, cfg.access_token);
+    console.log("✓  Context updated.");
+    return;
+  }
+
+  console.log(`\nProject context (${rc.project_id.slice(0, 8)}…):\n`);
+  console.log(fmtContext(ctx));
+  if (ctx.last_updated) {
+    console.log(`\nLast updated: ${new Date(ctx.last_updated).toLocaleString()}`);
+  }
+}
+
+module.exports = { run };

package/src/commands/doctor.js

@@ -0,0 +1,10 @@
+"use strict";
+// Phase 6 — Hardening
+
+function run() {
+  console.log("[Phase 6] doctor — not implemented yet.");
+  console.log("Coming in Phase 6: check auth token, .prepclirc, git hooks,");
+  console.log("push refspec, and cloud connectivity. Report all issues.");
+}
+
+module.exports = { run };

package/src/commands/hook.js

@@ -0,0 +1,131 @@
+"use strict";
+
+const fs       = require("node:fs");
+const readline = require("node:readline");
+
+const { readSession, clearSession, isSessionStale }        = require("../lib/session-file");
+const { generateId, getCurrentCommit, getChangedFiles, buildRecord, recordFilename } = require("../lib/decision");
+const {
+  shadowBranchExists, shadowBranchExistsOnRemote,
+  initShadowBranch, fetchShadowBranch,
+  writeDecisionRecord,
+} = require("../lib/git");
+const { isLoggedIn, requireLoginFresh, readRC } = require("../lib/config");
+const api = require("../lib/api");
+
+async function askSummary(prompt) {
+  // Git pipes push info through process.stdin — open /dev/tty directly for user input
+  let input = process.stdin;
+
+  if (!process.stdin.isTTY) {
+    try {
+      input = fs.createReadStream("/dev/tty");
+    } catch {
+      return ""; // No terminal available (CI) — skip silently
+    }
+  }
+
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input, output: process.stderr });
+    rl.question(prompt, answer => {
+      resolve(answer.trim());
+      rl.close();
+      if (input !== process.stdin) input.destroy();
+    });
+    rl.on("error", () => resolve(""));
+    rl.on("close", () => resolve(""));
+  });
+}
+
+async function handlePrePush() {
+  const cwd     = process.cwd();
+  const session = readSession(cwd);
+
+  // No session turns — nothing to record, push proceeds normally
+  if (!session?.turns?.length) return;
+
+  const turns = session.turns;
+
+  if (isSessionStale(cwd)) {
+    process.stderr.write("\n[prepcli] Warning: this session started >24 hours ago.\n");
+  }
+
+  // Show accumulated turns
+  process.stderr.write(`\n[prepcli] ${turns.length} AI turn${turns.length === 1 ? "" : "s"} this session:\n`);
+  for (const t of turns) {
+    process.stderr.write(`  [${t.workflow}]  ${t.what}\n`);
+  }
+  process.stderr.write("\n");
+
+  const summary = await askSummary("  Final summary? (Enter to skip): ");
+
+  if (!summary) {
+    clearSession(cwd);
+    process.stderr.write("\n");
+    return;
+  }
+
+  const id           = generateId();
+  const commitHash   = getCurrentCommit(cwd);
+  const filesChanged = getChangedFiles(cwd);
+  const content      = buildRecord({ id, session, commitHash, filesChanged, summary });
+  const filename     = recordFilename(id);
+
+  // Ensure shadow branch exists
+  if (!shadowBranchExists(cwd)) {
+    if (shadowBranchExistsOnRemote(cwd)) {
+      fetchShadowBranch(cwd);
+    } else {
+      initShadowBranch(cwd);
+    }
+  }
+
+  process.stderr.write("  Writing to shadow branch...");
+  try {
+    writeDecisionRecord(filename, content, cwd);
+  } catch(e) {
+    process.stderr.write(` failed (${e.message})\n`);
+    clearSession(cwd);
+    return;
+  }
+
+  process.stderr.write(" done.\n");
+
+  // Write lean summary to cloud if logged in
+  if (isLoggedIn()) {
+    try {
+      const cfg = await requireLoginFresh();
+      const rc  = readRC();
+      if (rc?.project_id) {
+        const lean = {
+          summary,
+          why:                  turns.filter(t => t.why).pop()?.why || "",
+          alternatives_rejected: turns.filter(t => t.why).map(t => t.why),
+          key_files:            filesChanged.slice(0, 10),
+          workflow:             [...new Set(turns.map(t => t.workflow))].join(","),
+          ai_turn_count:        turns.length,
+          commit_hash:          commitHash,
+          session_start:        session.started_at,
+          session_end:          new Date().toISOString(),
+        };
+        await api.post(`/projects/${rc.project_id}/sessions`, lean, cfg.access_token);
+      }
+    } catch { /* cloud write must never block push */ }
+  }
+
+  clearSession(cwd);
+  process.stderr.write(`  ✓  Decision recorded (${id})\n`);
+  process.stderr.write(`     View: prepcli log\n\n`);
+}
+
+function run(hookName) {
+  if (hookName === "pre-push") {
+    handlePrePush()
+      .catch(() => {})   // errors must never block push
+      .then(() => process.exit(0));
+  } else {
+    process.exit(0);
+  }
+}
+
+module.exports = { run };

package/src/commands/init.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const readline = require("node:readline/promises");
+const { detectStack }                              = require("../lib/detect");
+const { isLoggedIn, requireLoginFresh, readRC, writeRC } = require("../lib/config");
+const api = require("../lib/api");
+
+function displayStack(stack, gitRemote) {
+  const lines = Object.entries(stack).map(([k, v]) => `  ${k}: ${v}`);
+  if (gitRemote) lines.push(`  git_remote: ${gitRemote}`);
+  return lines.join("\n");
+}
+
+async function prompt(rl, question) {
+  return (await rl.question(question)).trim();
+}
+
+async function collectList(rl, header) {
+  console.log(`\n${header}`);
+  console.log("  Enter one per line. Press Enter on an empty line to finish.");
+  const items = [];
+  while (true) {
+    const line = (await rl.question("  > ")).trim();
+    if (!line) break;
+    items.push(line);
+  }
+  return items;
+}
+
+async function run() {
+  const existing = readRC();
+
+  if (existing?.project_id || existing?.context) {
+    const rl0 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const ans = await prompt(rl0, "\n.prepclirc already exists. Re-initialize? [y/N]: ");
+      if (!ans.toLowerCase().startsWith("y")) {
+        console.log("Nothing changed.");
+        return;
+      }
+    } finally {
+      rl0.close();
+    }
+  }
+
+  console.log("\nScanning project...\n");
+
+  const cwd = process.cwd();
+  const { stack, name, git_remote } = detectStack(cwd);
+
+  if (Object.keys(stack).length > 0) {
+    console.log("Detected stack:\n" + displayStack(stack, git_remote));
+  } else {
+    console.log("Could not auto-detect stack.");
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    // ── Confirm or edit stack ─────────────────────────────────────────────────
+    const confirm = await prompt(rl, "\nDoes this look right? [Y/n]: ");
+
+    let finalStack = { ...stack };
+
+    if (confirm.toLowerCase() === "n") {
+      console.log("\nEdit stack (press Enter to keep current value, type to override):");
+      const fields = ["language", "runtime", "framework", "db", "ci", "hosting", "package_manager"];
+      for (const field of fields) {
+        const current = finalStack[field] || "";
+        const val = await prompt(rl, `  ${field}${current ? ` [${current}]` : ""}: `);
+        if (val)       finalStack[field] = val;
+        else if (!current) delete finalStack[field];
+      }
+    }
+
+    // Strip empty values
+    finalStack = Object.fromEntries(Object.entries(finalStack).filter(([, v]) => v));
+
+    // ── 3 questions ───────────────────────────────────────────────────────────
+    const hardLimits = await collectList(rl,
+      'Hard limits — things AI must NEVER do.\n  e.g. "never add console.log to production", "all DB migrations need a rollback"'
+    );
+
+    const activeConstraints = await collectList(rl,
+      'Active constraints — things that are true RIGHT NOW.\n  e.g. "auth module is frozen", "deployment freeze until Dec 15"'
+    );
+
+    const conventionLines = await collectList(rl,
+      'Conventions — patterns AI would get wrong.\n  e.g. "use AppError class, never throw raw strings", "snake_case for DB columns"'
+    );
+
+    const conventions = conventionLines.length > 0
+      ? Object.fromEntries(conventionLines.map((v, i) => [String(i), v]))
+      : {};
+
+    const contextPayload = {
+      stack:               finalStack,
+      hard_limits:         hardLimits,
+      active_constraints:  activeConstraints,
+      conventions,
+      recent_decisions:    [],
+      open_questions:      [],
+    };
+
+    // ── Push to cloud if logged in ────────────────────────────────────────────
+    if (isLoggedIn()) {
+      try {
+        const cfg = await requireLoginFresh();
+        const projectName = name || cwd.split("/").pop();
+
+        process.stdout.write("\nPushing to cloud...");
+
+        const { project_id, already_existed } = await api.post("/projects", {
+          name:       projectName,
+          git_remote: git_remote || null,
+        }, cfg.access_token);
+
+        await api.put(`/projects/${project_id}/context`, contextPayload, cfg.access_token);
+
+        writeRC({ project_id, git_remote: git_remote || null });
+
+        console.log(" done.");
+        if (already_existed) {
+          console.log(`✓  Updated existing project (${project_id.slice(0, 8)}…)`);
+        } else {
+          console.log(`✓  Project created (${project_id.slice(0, 8)}…)`);
+        }
+        console.log("✓  Context pushed to cloud.");
+
+      } catch (err) {
+        console.error(`\nCloud sync failed: ${err.message}`);
+        console.log("Saving context locally only.");
+        writeRC({ project_id: null, git_remote: git_remote || null, context: contextPayload });
+      }
+    } else {
+      writeRC({ project_id: null, git_remote: git_remote || null, context: contextPayload });
+      console.log("\n✓  Context saved to .prepclirc (local only).");
+      console.log("   Log in with `prepcli auth login` to sync to cloud.");
+    }
+
+    // ── Shadow branch + git hooks ─────────────────────────────────────────────
+    const gitLib = require("../lib/git");
+
+    process.stdout.write("\nSetting up shadow branch...");
+    try {
+      if (gitLib.shadowBranchExists(cwd)) {
+        console.log(" already exists.");
+      } else if (gitLib.shadowBranchExistsOnRemote(cwd)) {
+        gitLib.fetchShadowBranch(cwd);
+        console.log(" fetched from remote.");
+      } else {
+        gitLib.initShadowBranch(cwd);
+        console.log(" created.");
+      }
+
+      gitLib.installPrePushHook(cwd);
+      console.log("✓  Pre-push hook installed.");
+
+      gitLib.configurePushRefspec(cwd);
+      console.log("✓  Push refspec configured.");
+
+      gitLib.ensureGitignoreEntry(cwd);
+      console.log("✓  .prepcli-session added to .gitignore.");
+    } catch (err) {
+      console.log(` skipped (${err.message})`);
+    }
+
+    console.log("\nDone. Run `prepcli context` to review.");
+
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = { run };

package/src/commands/install.js

@@ -0,0 +1,130 @@
+"use strict";
+
+const fs   = require("node:fs");
+const os   = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+
+const getClaudeTargets      = require("../lib/targets/claude");
+const getCursorTargets      = require("../lib/targets/cursor");
+const getWindsurfTargets    = require("../lib/targets/windsurf");
+const getAntigravityTargets = require("../lib/targets/antigravity");
+
+const WORKFLOW_DIR = path.resolve(__dirname, "../../workflows");
+
+function getTargets() {
+  const ctx = { cwd: process.cwd(), home: os.homedir() };
+  const all = [
+    ...getClaudeTargets(ctx),
+    ...getCursorTargets(ctx),
+    ...getWindsurfTargets(ctx),
+    ...getAntigravityTargets(ctx)
+  ];
+  return all.map((t) => {
+    const cmdFound  = t.commandNames.some(commandExists);
+    const pathFound = t.hintPaths.some(pathExists);
+    return { ...t, detected: cmdFound || pathFound };
+  });
+}
+
+function commandExists(cmd) {
+  return (process.env.PATH || "").split(path.delimiter).some((dir) => {
+    const exts = process.platform === "win32" ? ["", ".cmd", ".exe"] : [""];
+    return exts.some((ext) => {
+      try { fs.accessSync(path.join(dir, cmd + ext), fs.constants.X_OK); return true; }
+      catch { return false; }
+    });
+  });
+}
+
+function pathExists(p) {
+  try { fs.accessSync(p, fs.constants.F_OK); return true; } catch { return false; }
+}
+
+function listWorkflows() {
+  return fs.readdirSync(WORKFLOW_DIR).filter((f) => f.endsWith(".md")).sort();
+}
+
+function fmtDest(dest) {
+  const home = os.homedir();
+  if (dest.startsWith(home)) return `~${dest.slice(home.length)}`;
+  return path.relative(process.cwd(), dest) || ".";
+}
+
+async function chooseTargets(targets, opts) {
+  if (opts.all || opts.yes) return targets;
+
+  if (opts.tool) {
+    const ids = opts.tool.split(",").map((s) => s.trim());
+    const found = ids.map((id) => {
+      const t = targets.find((t) => t.id === id);
+      if (!t) { console.error(`Unknown tool id: ${id}`); process.exit(1); }
+      return t;
+    });
+    return found;
+  }
+
+  const recommended = targets.filter((t) => t.detected || t.defaultWhenUndetected);
+
+  if (!process.stdin.isTTY) return recommended;
+
+  console.log("\nWhere should prepcli install workflow files?\n");
+  targets.forEach((t, i) => {
+    const tag = t.detected ? "detected" : t.defaultWhenUndetected ? "default" : "not detected";
+    console.log(`  ${i + 1}. ${t.label} — ${tag}`);
+  });
+
+  const defaults = recommended.map((t) => targets.indexOf(t) + 1).join(",");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`\nChoose [${defaults || "none"}] or type all: `);
+    return parseSelection(answer.trim(), targets, recommended);
+  } finally {
+    rl.close();
+  }
+}
+
+function parseSelection(input, targets, recommended) {
+  if (!input || input === "") return recommended;
+  if (input === "all" || input === "a") return targets;
+  if (input === "none" || input === "n") return [];
+  const nums = input.split(/[,\s]+/).map(Number).filter((n) => Number.isInteger(n));
+  if (nums.length === 0) throw new Error("Enter numbers like 1,3 or 'all'.");
+  const invalid = nums.filter((n) => n < 1 || n > targets.length);
+  if (invalid.length > 0) throw new Error(`Out of range: ${invalid.join(", ")}`);
+  return [...new Set(nums)].map((n) => targets[n - 1]);
+}
+
+async function run(opts) {
+  const workflows = listWorkflows();
+  const targets   = getTargets();
+  const selected  = await chooseTargets(targets, opts);
+
+  if (selected.length === 0) { console.log("Nothing selected."); return; }
+
+  console.log(`\nInstalling ${workflows.length} workflow(s): ${workflows.join(", ")}\n`);
+
+  let failures = 0;
+  for (const t of selected) {
+    try {
+      fs.mkdirSync(t.destination, { recursive: true });
+      for (const file of workflows) {
+        fs.copyFileSync(path.join(WORKFLOW_DIR, file), path.join(t.destination, file));
+      }
+      console.log(`  ✓  ${t.label}  →  ${fmtDest(t.destination)}`);
+    } catch (err) {
+      failures++;
+      console.error(`  ✗  ${t.label}: ${err.message}`);
+    }
+  }
+
+  if (failures > 0) {
+    process.exitCode = 1;
+    console.error(`\n${failures} error(s). Check folder permissions.`);
+    return;
+  }
+
+  console.log("\nDone. Use /prep  /debug  /review  /plan  /refactor  /write in your AI tool.");
+}
+
+module.exports = { run };

package/src/commands/log.js

@@ -0,0 +1,65 @@
+"use strict";
+
+const { execSync } = require("node:child_process");
+const { shadowBranchExists, SHADOW_BRANCH, gitRoot } = require("../lib/git");
+
+function execSafe(cmd, cwd) {
+  try { return execSync(cmd, { cwd, stdio: ["pipe", "pipe", "pipe"] }).toString().trim(); }
+  catch { return null; }
+}
+
+function parseRecord(content) {
+  const get = re => { const m = content.match(re); return m ? m[1].trim() : null; };
+  return {
+    id:       get(/^id: (.+)$/m),
+    date:     get(/^date: (.+)$/m),
+    workflow: get(/^workflow: (.+)$/m),
+    commit:   get(/^commit: (.+)$/m),
+    turns:    parseInt(get(/^ai_turn_count: (\d+)$/m) || "0"),
+    files:    (get(/^files_changed: \[(.+)\]$/m) || "").split(",").map(f => f.trim()).filter(Boolean),
+    summary:  get(/## Summary\n(.+)/),
+    why:      get(/## Why This Approach\n(.+)/),
+  };
+}
+
+function run(opts = {}) {
+  const cwd  = process.cwd();
+  const root = gitRoot(cwd);
+
+  if (!shadowBranchExists(cwd)) {
+    console.log("No decision records found. Run `prepcli init` to set up the shadow branch.");
+    return;
+  }
+
+  const filesOut = execSafe(`git ls-tree --name-only ${SHADOW_BRANCH}`, root);
+  if (!filesOut) { console.log("No decisions recorded yet."); return; }
+
+  const filenames = filesOut.split("\n").filter(f => f.endsWith(".md")).reverse();
+
+  const records = filenames.map(filename => {
+    const content = execSafe(`git show ${SHADOW_BRANCH}:${filename}`, root);
+    if (!content) return null;
+    return { filename, ...parseRecord(content) };
+  }).filter(Boolean);
+
+  // Apply filters
+  let filtered = records;
+  if (opts.workflow) filtered = filtered.filter(r => r.workflow?.includes(opts.workflow));
+  if (opts.file)     filtered = filtered.filter(r => r.files.some(f => f.includes(opts.file)));
+  if (opts.commit)   filtered = filtered.filter(r => r.commit?.startsWith(opts.commit));
+
+  if (filtered.length === 0) { console.log("No matching decisions found."); return; }
+
+  for (const r of filtered) {
+    const date   = r.date ? new Date(r.date).toLocaleDateString("en-US", { month: "short", day: "numeric" }) : "?";
+    const commit = r.commit && r.commit !== "none" ? r.commit.slice(0, 7) : "none";
+
+    console.log(`\n${date}  •  ${r.workflow || "?"}  •  ${r.turns} AI turn${r.turns === 1 ? "" : "s"}  •  commit ${commit}`);
+    console.log(`  ${r.summary || r.filename}`);
+    if (r.why && r.why !== "Not recorded.") console.log(`  Why:   ${r.why}`);
+    if (r.files.length)                     console.log(`  Files: ${r.files.filter(f => f).join(", ")}`);
+  }
+  console.log("");
+}
+
+module.exports = { run };