@prepcli/prepcli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhavik Devganiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# prepcli
+
+Persistent AI collaboration layer — structured prompts, project context, and decision records for Claude, Cursor, Windsurf, and more.
+
+---
+
+## What it does
+
+Most AI coding sessions start cold. The AI asks what your stack is. It suggests something you ruled out last week. It doesn't know about the deployment freeze. You spend the first 10 messages re-explaining context that hasn't changed.
+
+prepcli fixes this in three layers:
+
+**Layer 1 — Structured prompts.**
+Six workflow slash commands (`/debug`, `/plan`, `/prep`, etc.) that ask targeted questions before the AI starts working. Better questions → better output on the first attempt → less back-and-forth.
+
+**Layer 2 — Project context.**
+`prepcli init` scans your codebase, stores your stack and constraints in the cloud, and silently injects them at the start of every AI session. The AI already knows your stack, your hard limits, and what was decided last week — without you saying a word.
+
+**Layer 3 — Decision records.**
+Every AI session gets recorded as a structured Markdown document: what was done, why, what was ruled out, linked to the git commit. Records live in a hidden git branch that travels with every clone. No account needed to read history. Works offline.
+
+---
+
+## Quick start
+
+```bash
+npm install -g prepcli
+prepcli install        # copy workflow files to your AI tool
+prepcli auth login     # create free account (optional — enables cloud features)
+prepcli init           # scan project, push context, set up shadow branch
+```
+
+Open your AI tool and type `/debug`, `/plan`, or any workflow command.
+
+---
+
+## Workflow commands
+
+| Command | What it does |
+|---|---|
+| `/prep` | Universal session starter — ask targeted questions, build a structured prompt, execute on approval |
+| `/debug` | Turn a vague bug report into a precise debugging prompt |
+| `/plan` | Gather product and technical constraints, build a planning prompt |
+| `/refactor` | Gather constraints for a safe refactor |
+| `/review` | Gather review intent and constraints, build a focused code review |
+| `/write` | Gather audience and constraints, build a precise writing prompt |
+
+Each workflow follows the same structure:
+- **STEP 0** — silently reads project context before asking anything
+- **STEP 1–4** — asks one question at a time to fill critical gaps
+- **STEP 5** — builds and shows a structured prompt, executes on your approval
+- **FINAL STEP** — silently records what was done to the local session file
+
+---
+
+## Project context
+
+Run once per project:
+
+```bash
+cd your-project
+prepcli init
+```
+
+prepcli scans your codebase (reads `package.json`, lock files, config files, git remote) and asks three questions:
+
+1. **Hard limits** — things AI must never do (`never add console.log to production`)
+2. **Active constraints** — things that are true right now (`auth module is frozen until Dec 15`)
+3. **Conventions** — patterns AI would get wrong (`use AppError class, never throw raw strings`)
+
+This context is pushed to the cloud and injected silently at the start of every AI session via STEP 0. The AI knows your stack, your limits, and your conventions without you repeating them.
+
+```bash
+prepcli context             # show current context
+prepcli context --preview   # show exactly what STEP 0 injects
+prepcli context --edit      # open in $EDITOR and push changes
+```
+
+Stack detection covers: language, runtime, framework, database, auth, testing, API layer, styling, monorepo, i18n, CI, hosting, package manager.
+
+---
+
+## Decision records
+
+After every AI session, `prepcli` records what was done, why, and what was ruled out — linked to the git commit it produced.
+
+### How recording works
+
+During a session, the AI silently runs after each task:
+
+```bash
+prepcli session add \
+  --workflow=debug \
+  --what="replaced date-fns with custom UTC offset handler" \
+  --why="date-fns fails silently on UTC+5:30 half-hour offsets"
+```
+
+This writes to a local `.prepcli-session` file — no network, no auth, works offline.
+
+When you run `git push`, a pre-push hook fires:
+
+```
+[prepcli] 2 AI turns this session:
+  [debug]  identified date-fns as root cause
+  [debug]  replaced with custom UTC offset handler
+
+  Final summary? (Enter to skip): _
+```
+
+Type a one-line summary and press Enter. The push is never blocked — Enter skips recording entirely.
+
+### Where records live
+
+Records are stored in two places:
+
+| | Shadow Branch | Database |
+|---|---|---|
+| **Content** | Full Markdown — all turns, alternatives, constraints | Lean JSON — summary, key files, turn count |
+| **Needs account** | No | Yes |
+| **Works offline** | Yes | No |
+| **Travels with clone** | Yes | No |
+| **AI reads at STEP 0** | No | Yes — feeds `recent_decisions` |
+
+The shadow branch (`prepcli/shadow/v1`) is an orphan git branch — completely separate from your code history. It travels with every `git clone` and every `git fetch`.
+
+### Reading records
+
+```bash
+prepcli log                        # last 10 decisions
+prepcli log --workflow debug       # debug sessions only
+prepcli log --file src/auth.js     # decisions touching this file
+prepcli log --commit abc123        # specific commit
+```
+
+Or directly with git — no prepcli needed:
+
+```bash
+git show prepcli/shadow/v1:20260524-dec-a3f9c2b1.md
+```
+
+### How decisions get recorded
+
+There are two ways a decision lands in `prepcli log` — by the AI automatically, or by you manually.
+
+**Recorded by AI (automatic)**
+
+After every AI task, the workflow silently runs:
+
+```bash
+prepcli session add \
+  --workflow=debug \
+  --what="replaced date-fns with custom UTC offset handler" \
+  --why="date-fns fails silently on UTC+5:30 half-hour offsets"
+```
+
+Turns accumulate locally in `.prepcli-session`. When you run `git push`, the pre-push hook fires:
+
+```
+[prepcli] 2 AI turns this session:
+  [debug]  identified date-fns as root cause
+  [debug]  replaced with custom UTC offset handler
+
+  Final summary? (Enter to skip): rebuilt calendar with custom timezone handling
+```
+
+Type a one-line summary and press Enter. One decision record is written to the shadow branch covering the full session.
+
+---
+
+**Recorded manually**
+
+You don't have to wait for an AI session or a push. If you discover something — a production bug, an architectural decision made in a meeting, a constraint found in docs — record it immediately.
+
+```bash
+prepcli record
+```
+
+```
+[prepcli] Recording decision
+
+What did you decide or discover?
+> switched Upstash to paid tier after finding silent rate limiting in prod
+
+Why?
+> free tier drops requests above 100/min silently, no error returned
+
+What was ruled out? (Enter to skip)
+> self-hosted Redis — too much infra overhead at current scale
+
+Workflow? [manual/debug/plan/discovery] (Enter for manual)
+> discovery
+
+Writing to shadow branch... done.
+✓  Decision recorded (dec-3f9a1b2c)
+   View: prepcli log
+```
+
+**Inline mode** — no prompts:
+
+```bash
+prepcli record \
+  --what="switched Upstash to paid tier" \
+  --why="free tier silently drops requests above 100/min" \
+  --ruled-out="self-hosted Redis, Upstash Pro alternative plan" \
+  --workflow=discovery
+```
+
+Manual records are marked `ai_turn_count: 0` so you can distinguish them from AI session records in `prepcli log`. Records are written directly to the shadow branch — no push needed.
+
+### Accessing records on a fresh clone
+
+```bash
+git clone https://github.com/your/repo
+git fetch origin prepcli/shadow/v1:prepcli/shadow/v1
+prepcli log   # full decision history available immediately
+```
+
+No account required. The history is pure git objects.
+
+---
+
+## Installation options
+
+**Temporary (no global install):**
+```bash
+npx prepcli install
+```
+
+**Permanent global install:**
+```bash
+npm install -g prepcli
+prepcli install
+```
+
+When prompted, choose where to install:
+- **Claude Code** — personal (`~/.claude/commands`) or project (`.claude/commands`)
+- **Cursor** — `.cursor/prompts`
+- **Windsurf** — `.windsurf`
+
+---
+
+## Auth
+
+Login is via email OTP — no password required:
+
+```bash
+prepcli auth login     # sends a one-time code to your email
+prepcli auth status    # show current session and expiry
+prepcli auth logout    # invalidate session
+```
+
+Auth is optional. Without it:
+- Workflow commands work fully
+- `prepcli init` saves context locally in `.prepclirc`
+- Session recording writes to the shadow branch locally
+- Cloud sync and `recent_decisions` injection are disabled
+
+---
+
+## Commands reference
+
+```bash
+prepcli install                    # copy workflow files to AI tool directories
+prepcli uninstall                  # remove workflow files
+
+prepcli auth login                 # sign in with email OTP
+prepcli auth logout                # sign out
+prepcli auth status                # show current session
+
+prepcli init                       # scan project, push context, set up shadow branch
+prepcli context                    # show current project context
+prepcli context --preview          # show what STEP 0 injects
+prepcli context --edit             # edit and push context
+
+prepcli session add                # add a turn to the local session file (used by AI)
+prepcli session show               # inspect the current session
+prepcli session clear              # clear the session file
+
+prepcli log                        # browse decision records
+prepcli log --workflow <type>      # filter by workflow
+prepcli log --file <path>          # filter by file
+prepcli log --commit <hash>        # show decision for a specific commit
+
+prepcli record                     # manually save a decision (interactive)
+prepcli record --what "..." --why "..." --ruled-out "..." --workflow manual
+prepcli stats                      # show prompt quality scores and delta trends
+prepcli doctor                     # diagnose setup issues
+```
+
+---
+
+## Files created in your project
+
+| File | What it is | Safe to commit |
+|---|---|---|
+| `.prepclirc` | Project ID + git remote | Yes |
+| `.git/hooks/pre-push` | Hook installed by `prepcli init` | N/A (in .git) |
+| `.prepcli-session` | Local session accumulator | No (in .gitignore) |
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Git
+- Claude Code, Cursor, or Windsurf
+
+---
+
+## Self-hosting
+
+Run your own backend instead of using `api.prepcli.in`:
+
+1. Create a [Supabase](https://supabase.com) project
+2. Run `schema.sql` in the Supabase SQL editor
+3. Deploy `worker/` to [Cloudflare Workers](https://workers.cloudflare.com)
+4. Set Cloudflare secrets:
+   ```bash
+   wrangler secret put SUPABASE_URL
+   wrangler secret put SUPABASE_ANON_KEY
+   ```
+5. Point the CLI at your worker:
+   ```bash
+   PREPCLI_API_URL=https://your-worker.workers.dev prepcli init
+   ```
+
+---
+
+## Codebase structure
+
+```
+bin/
+  prepcli.js           CLI entry point
+
+src/
+  commands/
+    auth.js            login / logout / status
+    init.js            project setup
+    context.js         read and edit project context
+    session.js         local session accumulator
+    hook.js            pre-push hook handler
+    log.js             browse decision records
+    record.js          manual decision entry
+    install.js         workflow file installer
+    stats.js           quality scores (Phase 4)
+    team.js            team management (Phase 6)
+    doctor.js          setup diagnostics (Phase 6)
+
+  lib/
+    api.js             HTTP client → api.prepcli.in
+    config.js          auth token + .prepclirc helpers
+    detect.js          stack auto-detection
+    git.js             shadow branch plumbing
+    session-file.js    .prepcli-session read/write
+    decision.js        Markdown record builder
+    targets/           AI tool detection (Claude, Cursor, Windsurf)
+
+workflows/
+  prep.md              /prep workflow
+  debug.md             /debug workflow
+  plan.md              /plan workflow
+  refactor.md          /refactor workflow
+  review.md            /review workflow
+  write.md             /write workflow
+
+worker/
+  src/index.js         Cloudflare Worker (API layer)
+
+schema.sql             Supabase schema + RLS policies
+docs/
+  design.md            Visual design reference
+```
+
+---
+
+## License
+
+MIT

package/bin/prepcli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+"use strict";
+
+const { program } = require("commander");
+
+program
+  .name("prepcli")
+  .description("Persistent AI collaboration layer — context, decisions, and self-improving prompts")
+  .version("0.1.0");
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+program
+  .command("auth <action>")
+  .description("login | logout | status")
+  .action((action) => require("../src/commands/auth").run(action));
+
+// ── Init ──────────────────────────────────────────────────────────────────────
+program
+  .command("init")
+  .description("Scan codebase, create .prepclirc, push initial context to cloud")
+  .action(() => require("../src/commands/init").run());
+
+// ── Install ───────────────────────────────────────────────────────────────────
+program
+  .command("install")
+  .description("Copy workflow files to AI tool directories")
+  .option("--all", "Install to all detected tools")
+  .option("--tool <ids>", "Comma-separated tool ids (claude-project, cursor, windsurf…)")
+  .option("--yes, -y", "Skip confirmation prompt")
+  .action((opts) => require("../src/commands/install").run(opts));
+
+// ── Uninstall ─────────────────────────────────────────────────────────────────
+program
+  .command("uninstall")
+  .description("Remove workflow files from AI tool directories")
+  .option("--all", "Remove from all locations without prompting")
+  .option("--yes, -y", "Skip confirmation prompt")
+  .action((opts) => require("../src/commands/uninstall").run(opts));
+
+// ── Context ───────────────────────────────────────────────────────────────────
+program
+  .command("context")
+  .description("Show current project context from cloud")
+  .option("--preview", "Show exactly what STEP 0 would inject")
+  .option("--edit", "Open context in editor")
+  .action((opts) => require("../src/commands/context").run(opts));
+
+// ── Session (AI calls this silently) ─────────────────────────────────────────
+program
+  .command("session <action>")
+  .description("add | show | clear — manage the local AI session accumulator")
+  .option("--workflow <type>", "Workflow type (debug, plan, review, prep, refactor, write)")
+  .option("--what <text>",     "One sentence: what was done")
+  .option("--why <text>",      "One sentence: why this approach")
+  .action((action, opts) => require("../src/commands/session").run(action, opts));
+
+// ── Internal git hook handler ─────────────────────────────────────────────────
+program
+  .command("_hook <name>", { hidden: true })
+  .description("Internal: called by git hooks installed by prepcli init")
+  .action((name) => require("../src/commands/hook").run(name));
+
+// ── Decision log ──────────────────────────────────────────────────────────────
+program
+  .command("log")
+  .description("Browse AI decision records linked to commits")
+  .option("--workflow <type>", "Filter by workflow type (debug, plan, review…)")
+  .option("--file <path>", "Filter by file path")
+  .option("--commit <hash>", "Show decision for a specific commit")
+  .option("--last <period>", "Filter by time period (e.g. 30d)")
+  .action((opts) => require("../src/commands/log").run(opts));
+
+// ── Record ────────────────────────────────────────────────────────────────────
+program
+  .command("record")
+  .description("Manually save a decision to the shadow branch")
+  .option("--what <text>",        "What was decided or discovered")
+  .option("--why <text>",         "Why this approach over alternatives")
+  .option("--ruled-out <text>",   "What was considered and rejected (comma-separated)")
+  .option("--workflow <type>",    "Workflow type (manual, debug, plan, discovery)")
+  .action((opts) => require("../src/commands/record").run(opts));
+
+// ── Stats ─────────────────────────────────────────────────────────────────────
+program
+  .command("stats")
+  .description("Show prompt quality scores and delta trends")
+  .option("--workflow <type>", "Filter by workflow type")
+  .option("--last <period>", "Filter by time period (e.g. 30d)")
+  .option("--compare <period>", "Compare to an earlier period")
+  .action((opts) => require("../src/commands/stats").run(opts));
+
+// ── Team ──────────────────────────────────────────────────────────────────────
+program
+  .command("team <action> [email]")
+  .description("invite | list | remove")
+  .action((action, email) => require("../src/commands/team").run(action, email));
+
+// ── Doctor ────────────────────────────────────────────────────────────────────
+program
+  .command("doctor")
+  .description("Diagnose setup issues (auth, .prepclirc, git hooks, push refspec)")
+  .action(() => require("../src/commands/doctor").run());
+
+program.parse();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@prepcli/prepcli",
+  "version": "0.1.0",
+  "description": "Persistent AI collaboration layer — context, decisions, and self-improving prompts",
+  "bin": {
+    "prepcli": "./bin/prepcli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "workflows",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/tests/**/*.test.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "dotenv": "^17.4.2"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "claude",
+    "cursor",
+    "prompt",
+    "context",
+    "developer-tools",
+    "llm",
+    "workflow"
+  ],
+  "author": "Bhavik Devganiya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhavviik/prepcli.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/commands/auth.js

@@ -0,0 +1,125 @@
+"use strict";
+
+const readline = require("node:readline/promises");
+const api = require("../lib/api");
+const { writeConfig, deleteConfig, readConfig } = require("../lib/config");
+
+// ── Login ─────────────────────────────────────────────────────────────────────
+async function login() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    const email = (await rl.question("Email: ")).trim();
+
+    if (!email || !email.includes("@")) {
+      console.error("Enter a valid email address.");
+      process.exit(1);
+    }
+
+    try {
+      await api.post("/auth/otp", { email });
+    } catch (err) {
+      console.error("Failed to send code:", err.message);
+      process.exit(1);
+    }
+
+    console.log("\nCode sent to " + email);
+    console.log("Check your email and enter the code below.\n");
+
+    const code = (await rl.question("Enter code: ")).trim();
+
+    if (!code || !/^\d+$/.test(code)) {
+      console.error("Invalid code.");
+      process.exit(1);
+    }
+
+    let data;
+    try {
+      data = await api.post("/auth/verify", { email, token: code });
+    } catch {
+      console.error("Invalid or expired code. Run: prepcli auth login");
+      process.exit(1);
+    }
+
+    writeConfig({
+      access_token:  data.access_token,
+      refresh_token: data.refresh_token,
+      user_id:       data.user_id,
+      email:         data.email,
+      expires_at:    data.expires_at,
+    });
+
+    console.log("\nLogged in as " + data.email);
+    console.log("Run `prepcli init` inside your project to set it up.");
+
+  } finally {
+    rl.close();
+  }
+}
+
+// ── Logout ────────────────────────────────────────────────────────────────────
+async function logout() {
+  const cfg = readConfig();
+
+  if (!cfg) {
+    console.log("Already logged out.");
+    return;
+  }
+
+  try {
+    await api.post("/auth/logout", {}, cfg.access_token);
+  } catch {
+    // Local cleanup is what matters
+  }
+
+  deleteConfig();
+  console.log("Logged out.");
+}
+
+// ── Status ────────────────────────────────────────────────────────────────────
+async function status() {
+  const { refreshIfNeeded } = require("../lib/config");
+  let cfg = readConfig();
+
+  if (!cfg || !cfg.access_token) {
+    console.log("Not logged in.");
+    console.log("Run: prepcli auth login");
+    return;
+  }
+
+  const now  = Math.floor(Date.now() / 1000);
+  const ttl  = (cfg.expires_at || 0) - now;
+
+  if (ttl <= 300) {
+    const refreshed = await refreshIfNeeded();
+    if (refreshed) cfg = refreshed;
+  }
+
+  const expired    = cfg.expires_at && now >= cfg.expires_at;
+  const expiresStr = cfg.expires_at
+    ? new Date(cfg.expires_at * 1000).toLocaleString()
+    : "unknown";
+
+  const tokenStatus = expired
+    ? "EXPIRED — run: prepcli auth login"
+    : "valid until " + expiresStr;
+
+  console.log("Logged in as: " + cfg.email);
+  console.log("User ID:      " + cfg.user_id);
+  console.log("Token:        " + tokenStatus);
+  console.log("Auto-refresh: enabled");
+}
+
+// ── Router ────────────────────────────────────────────────────────────────────
+async function run(action) {
+  switch (action) {
+    case "login":  await login();  break;
+    case "logout": await logout(); break;
+    case "status": await status(); break;
+    default:
+      console.error("Unknown auth action: \"" + action + "\". Use: login | logout | status");
+      process.exit(1);
+  }
+}
+
+module.exports = { run };