replen 0.4.1 → 1.0.1

package/dist/discover-roots.js

@@ -0,0 +1,169 @@
+// Layered project-root discovery. Tries cheap inference first, falls back
+// to interactive prompt if nothing works. Result is one or more root dirs
+// that the recursive walker in discover-projects.ts will then scan for
+// git repos.
+//
+// Order (cheapest / most-targeted first):
+//   1. Explicit --root flag(s)               → user-specified
+//   2. REPLEN_PROJECT_ROOTS env var          → scripted / dotfiles
+//   3. Saved ~/.replen/config.json roots     → previously confirmed
+//   4. cwd walk-up                           → "I'm in a repo right now"
+//   5. ~/.claude.json mining                 → "I use Claude Code regularly"
+//   6. Hardcoded ~/github, ~/code, ~/projects → conventional layout
+//   7. Interactive prompt                    → ask the user directly
+//
+// The orchestration in sync-projects.ts tries strategies in order and
+// keeps going until at least one git repo is found, then stops looking.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { readConfig } from "./config.js";
+/** From explicit `--root <path>` CLI flag(s), or empty if not passed. */
+export function rootsFromFlag(flagValues) {
+    return flagValues.map(expandTilde).filter(existsAndIsDir);
+}
+/** From `REPLEN_PROJECT_ROOTS` env var (colon-separated). */
+export function rootsFromEnv() {
+    const env = process.env.REPLEN_PROJECT_ROOTS;
+    if (!env)
+        return [];
+    return env.split(":").map((s) => s.trim()).filter(Boolean).map(expandTilde).filter(existsAndIsDir);
+}
+/** From the user's persisted ~/.replen/config.json `projectRoots`. */
+export async function rootsFromConfig() {
+    const cfg = await readConfig();
+    if (!cfg?.projectRoots?.length)
+        return [];
+    return cfg.projectRoots.map(expandTilde).filter(existsAndIsDir);
+}
+/**
+ * If `npx replen` was invoked from inside a git repo (or one of its
+ * subdirs), walk up to find the repo root, then return its parent dir
+ * as a candidate root. This catches the common "I'm sitting in one of
+ * my projects when I install Replen" case.
+ *
+ * Stops at `homedir()` and at `/` to avoid walking into system dirs.
+ */
+export function rootsFromCwdWalkUp() {
+    const cwd = process.cwd();
+    const home = homedir();
+    let dir = cwd;
+    // Walk up until we find a .git/ or hit home/root.
+    while (dir !== "/" && dir !== home && dir.length > 1) {
+        if (existsSync(join(dir, ".git"))) {
+            const parent = dirname(dir);
+            // Only suggest the parent if it's still inside home — never offer
+            // "/" or anything above $HOME as a scan root.
+            if (parent.startsWith(home) && parent !== home)
+                return [parent];
+            return [];
+        }
+        dir = dirname(dir);
+    }
+    return [];
+}
+/**
+ * Read ~/.claude.json (Claude Code's per-user config) and extract the
+ * project cwds it tracks. Group by parent dir. Return parents that
+ * contain ≥2 Claude Code projects — these are very likely the user's
+ * actual repo roots.
+ *
+ * Why this is high-signal: Claude Code only adds an entry when the user
+ * opens it inside a real project, so the cwd list is curated by their
+ * actual usage. Far more accurate than guessing dir names.
+ */
+export function rootsFromClaudeJson() {
+    const claudePath = join(homedir(), ".claude.json");
+    if (!existsSync(claudePath))
+        return [];
+    let data;
+    try {
+        data = JSON.parse(readFileSync(claudePath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!data || typeof data !== "object")
+        return [];
+    const projects = data.projects;
+    if (!projects || typeof projects !== "object")
+        return [];
+    const parentCounts = new Map();
+    for (const path of Object.keys(projects)) {
+        if (!path.startsWith("/"))
+            continue;
+        const parent = dirname(path);
+        if (!parent.startsWith(homedir()))
+            continue;
+        parentCounts.set(parent, (parentCounts.get(parent) ?? 0) + 1);
+    }
+    return Array.from(parentCounts.entries())
+        .filter(([, n]) => n >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([parent]) => parent)
+        .filter(existsAndIsDir);
+}
+/** Conventional layout: ~/github, ~/code, ~/projects. */
+export function rootsFromHardcoded() {
+    return ["github", "code", "projects", "Code", "Projects", "dev", "src", "work"]
+        .map((n) => join(homedir(), n))
+        .filter(existsAndIsDir);
+}
+/**
+ * Last-resort interactive prompt. Asks the user where they keep their
+ * code, with a sensible default. Returns null if the user is in a
+ * non-interactive context (stdin not a TTY) or hits Ctrl-C.
+ */
+export async function promptForRoot() {
+    if (!process.stdin.isTTY)
+        return null;
+    const home = homedir();
+    // Suggest the most common parent of any folder we know about, falling
+    // back to home itself.
+    const suggestion = pickPromptSuggestion() ?? home;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`\n  Where do you keep your code? [${suggestion}]: `)).trim();
+        const chosen = answer || suggestion;
+        const expanded = expandTilde(chosen);
+        if (!existsAndIsDir(expanded)) {
+            console.warn(`  ✗ Not a directory: ${expanded}`);
+            return null;
+        }
+        return expanded;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+function pickPromptSuggestion() {
+    const fromCwd = rootsFromCwdWalkUp();
+    if (fromCwd[0])
+        return fromCwd[0];
+    const fromClaude = rootsFromClaudeJson();
+    if (fromClaude[0])
+        return fromClaude[0];
+    const fromHard = rootsFromHardcoded();
+    if (fromHard[0])
+        return fromHard[0];
+    return null;
+}
+function expandTilde(p) {
+    if (p === "~" || p.startsWith("~/")) {
+        return p === "~" ? homedir() : join(homedir(), p.slice(2));
+    }
+    return resolve(p);
+}
+function existsAndIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/first-ingest.js

@@ -0,0 +1,140 @@
+// First-time ingest streamer used by `npx replen` after install.
+//
+// Triggers a pipeline run and tails progress until the discovered pool
+// is ready (event signal: `fetch_done` with "Discovered pool" message,
+// or candidates count crosses 0). Then exits cleanly. Stages 1+2 and
+// the scouted-pool fetcher continue server-side in the background;
+// the user can do `npx replen progress` later if they want to watch
+// the rest, or just open Claude Code and the agent will find whatever
+// landed.
+//
+// Why exit early instead of waiting for full pipeline completion: a
+// fresh install with 30+ projects can take 5-10 min for Stage 1+2
+// per-project LLM work to finish. The user shouldn't sit at a blank
+// terminal — they want to know "is there something I can look at now?"
+// and the answer becomes yes once the discovered pool lands (typically
+// 30-60s in).
+//
+// Tolerant of rate-limit and in-flight responses; never fails the
+// install flow on its own — worst case prints a "you can run
+// `npx replen progress` later" hint and returns.
+import { apiGet, apiPost } from "./api.js";
+const POLL_INTERVAL_MS = 2500;
+// Absolute cap on how long we sit in the streamer. Discovered pool
+// usually lands inside 60s but giving generous headroom for slow
+// fetcher tails. If we hit this, we exit with a hint rather than
+// blocking the install flow.
+const MAX_WAIT_MS = 180_000;
+export async function runFirstIngest(cfg) {
+    console.log("");
+    console.log("  Pulling first batch of candidates from your sources…");
+    console.log("  (This takes about a minute. You can `^C` here — ingest continues server-side.)");
+    console.log("");
+    // Step 1: trigger a run. Tolerant of in-flight / rate-limit.
+    let triggered = null;
+    try {
+        triggered = await apiPost(cfg, "/api/mcp/run-now", {});
+    }
+    catch (e) {
+        // Surface but don't fail install — the cron scheduler will pick
+        // up the new projects on its next tick.
+        console.log(`  · Couldn't trigger an immediate run (${e.message.slice(0, 80)}).`);
+        console.log(`    The cron scheduler will catch up shortly. Open Claude Code in a tracked repo`);
+        console.log(`    in a few minutes and the agent will mention any new matches.`);
+        return;
+    }
+    if (!triggered.ok && triggered.status !== "in_flight") {
+        console.log(`  · Run not started: ${triggered.reason ?? triggered.status}`);
+        console.log(`    The next scheduled run will pick up the new projects.`);
+        return;
+    }
+    // Step 2: poll status, print events, exit when discovered pool ready.
+    let since = 0;
+    let firstTick = true;
+    let lastCandidates = 0;
+    let startedAt = Date.now();
+    let discoveredReadyAnnounced = false;
+    while (true) {
+        if (Date.now() - startedAt > MAX_WAIT_MS) {
+            console.log("");
+            console.log("  · Ingest still going — exiting the streamer so you're not blocked.");
+            console.log("    Run `npx replen progress` to keep watching, or just open Claude Code.");
+            return;
+        }
+        let status;
+        try {
+            status = await apiGet(cfg, "/api/mcp/status", since ? { since } : undefined);
+        }
+        catch (e) {
+            console.log(`  · Lost connection to status endpoint: ${e.message.slice(0, 80)}`);
+            console.log(`    Ingest still running. Open Claude Code shortly to see matches.`);
+            return;
+        }
+        if (firstTick) {
+            const phase = status.phase ?? "starting";
+            console.log(`  Run #${status.runId ?? "?"} · ${status.inFlight ? `running · phase=${phase}` : "idle"}`);
+            firstTick = false;
+        }
+        for (const ev of status.events ?? []) {
+            console.log(`  ${marker(ev.kind)} ${ev.message}`);
+            if (ev.id > since)
+                since = ev.id;
+            // The Phase-1 completion signal: pipeline emits a `fetch_done`
+            // event whose message starts with "Discovered pool:". Once we
+            // see that, the discovered candidates are persisted and visible
+            // to replen_match.
+            if (ev.kind === "fetch_done" &&
+                ev.message.startsWith("Discovered pool:") &&
+                !discoveredReadyAnnounced) {
+                discoveredReadyAnnounced = true;
+                // Don't exit immediately — let the next poll catch any inline
+                // events so the user sees a coherent end state, then bail.
+            }
+        }
+        // Fallback signal: if candidates count crossed 0, the discovered
+        // pool is functionally ready even if the event ordering didn't
+        // emit the expected marker. Belt + suspenders.
+        if (!discoveredReadyAnnounced && (status.candidates ?? 0) > lastCandidates && (status.candidates ?? 0) > 0) {
+            discoveredReadyAnnounced = true;
+        }
+        lastCandidates = status.candidates ?? lastCandidates;
+        // If the whole pipeline already finished (e.g. existing user with
+        // cached vectors — runs end fast), exit cleanly.
+        if (!status.inFlight) {
+            console.log("");
+            console.log(`  ✓ Ingest complete · ${status.candidates ?? 0} candidate(s) in inventory.`);
+            return;
+        }
+        // If discovered pool is ready, exit and let the rest run server-
+        // side. Stage 1+2 + scouted pool take much longer; no point making
+        // the user watch them.
+        if (discoveredReadyAnnounced) {
+            console.log("");
+            console.log(`  ✓ First candidates ready (${status.candidates ?? "?"} so far).`);
+            console.log(`    Per-project relevance refinement continues in the background.`);
+            console.log(`    Run \`npx replen progress\` later to watch, or just open Claude Code.`);
+            return;
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+function marker(kind) {
+    switch (kind) {
+        case "fetch_start":
+        case "fetch_done":
+            return "›";
+        case "scan":
+            return "·";
+        case "match":
+            return "✓";
+        case "skip":
+            return "·";
+        case "error":
+            return "✗";
+        default:
+            return "·";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.js

@@ -12,6 +12,15 @@ Usage:
   npx replen mcp setup       Re-wire MCP using saved auth
   npx replen project-init    Print a prompt your AI coding tool uses to draft
                              a CLAUDE.md tuned for replen
+  npx replen inject [-y]     Append the "## Replen integration" section to
+                             every CLAUDE.md + AGENTS.md (Claude Code +
+                             Codex) under ~/github/, ~/code/, ~/projects/
+                             so the agent auto-surfaces matches on session
+                             start. Idempotent. Asks for consent unless -y.
+  npx replen sync-projects   Re-scan local repos for new GitHub remotes
+       [--root PATH ...]     and register them with Replen. Run after
+                             cloning a new repo, or pass --root to point
+                             at a non-conventional layout.
   npx replen logout          Forget saved auth
   npx replen --help          This help
 
@@ -39,6 +48,14 @@ Every data command accepts --json to dump raw JSON for scripting / jq.
 
 Env:
   REPLEN_BASE             Override dashboard URL (default https://app.replen.dev)
+  REPLEN_PROJECT_ROOTS    Colon-separated list of dirs to scan for git repos.
+                          Overrides auto-detection. e.g. ~/work:~/src
+
+Project discovery (when run without --root and REPLEN_PROJECT_ROOTS unset):
+  1. Walks up from the current dir to find a git repo, suggests its parent
+  2. Reads ~/.claude.json for tracked Claude Code project paths
+  3. Falls back to ~/github, ~/code, ~/projects, ~/dev, ~/src, ~/work
+  4. Prompts you interactively if none of the above turn up anything
 
 Learn more: https://replen.dev
 `;
@@ -92,6 +109,27 @@ async function main() {
         console.log(`Note: this only clears local auth. The token is still valid until you rotate it on /settings.`);
         return;
     }
+    if (cmd === "inject") {
+        const { injectInstructions, summariseOutcome } = await import("./inject-instruction.js");
+        const yes = argv.includes("--yes") || argv.includes("-y");
+        const explicitRoots = collectRootFlags(argv);
+        const outcome = await injectInstructions({ yes, explicitRoots });
+        const summary = summariseOutcome(outcome);
+        if (summary)
+            console.log(summary);
+        return;
+    }
+    if (cmd === "sync-projects" || cmd === "sync") {
+        const cfg = await readConfig();
+        if (!cfg) {
+            console.error("Not signed in. Run `npx replen` first.");
+            process.exit(1);
+        }
+        const explicitRoots = collectRootFlags(argv);
+        const { syncDiscoveredProjects } = await import("./sync-projects.js");
+        await syncDiscoveredProjects({ token: cfg.token, base: cfg.base, explicitRoots });
+        return;
+    }
     if (cmd === "run")
         return runRun(argv);
     if (cmd === "progress")
@@ -124,6 +162,24 @@ async function main() {
     console.error(HELP);
     process.exit(1);
 }
+/**
+ * Parse one or more `--root <path>` (or `--root=<path>`) flags out of
+ * the argv tail. Doesn't validate the path — discover-roots.ts handles
+ * existence + stat checks downstream.
+ */
+function collectRootFlags(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--root" && argv[i + 1]) {
+            out.push(argv[++i]);
+        }
+        else if (arg.startsWith("--root=")) {
+            out.push(arg.slice("--root=".length));
+        }
+    }
+    return out;
+}
 main().catch((e) => {
     console.error(`\n✗ ${e?.message ?? String(e)}`);
     process.exit(1);

package/dist/init.js

@@ -142,10 +142,30 @@ export async function runInit() {
     });
     console.log(`  ✓ Saved auth to ${configPath()}`);
     await setupMcp(exchange.token, exchange.base);
+    // Phase A: auto-discover the user's local projects, extract tags
+    // from manifests, and register them in one shot. Replaces the
+    // legacy "paste a GitHub PAT and let us call api.github.com" flow
+    // for project discovery.
     console.log("");
-    console.log("  All set. Restart Claude Code (or Codex) and try:");
-    console.log("    /replen-triage      → runs the morning triage protocol");
-    console.log("    use replen to replen_today → pulls today's matches");
+    console.log("  Scanning your local repos for projects…");
+    const { syncDiscoveredProjects } = await import("./sync-projects.js");
+    await syncDiscoveredProjects({ token: exchange.token, base: exchange.base });
+    // Phase B: trigger the first ingest and stream progress until the
+    // discovered pool is ready (~30-60s). Without this, a new user
+    // would open Claude Code and find replen_match returning nothing —
+    // the server-side cron hasn't run yet for the just-registered
+    // projects. Streaming gives them visible activity AND ensures
+    // there's something to surface by the time they get to Claude Code.
+    const { runFirstIngest } = await import("./first-ingest.js");
+    await runFirstIngest({ token: exchange.token, base: exchange.base, savedAt: "" });
+    console.log("");
+    console.log("  All set. Restart Claude Code and try:");
+    console.log("    /replen-match       → triage today's candidates against this repo,");
+    console.log("                         in-session, using your subscription tokens");
+    console.log("    (no LLM API keys needed — the agent does the reasoning)");
+    console.log("");
+    console.log("  Other MCP hosts (Codex / Cursor / Aider):");
+    console.log("    \"use replen_match\" — same tool, no slash command");
     console.log("");
     console.log(`  Dashboard: ${exchange.base}`);
     console.log("");