replen 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # replen
 
-**Smart AI Development workflows.** One-command setup for [replen](https://replen.dev) - the AI that asks *"can we do this better?"* on your codebase, every morning.
+**Smarter AI Development workflows.** One-command setup for [replen](https://replen.dev) - the AI that asks *"can we do this better?"* on your codebase. Calm cadence: 1-3 actionable matches a month, not a daily feed.
 
 ```bash
 npx replen
@@ -24,6 +24,28 @@ npx replen mcp setup    # re-wire MCP using saved auth
 npx replen logout       # forget saved auth (token stays valid; rotate on /settings to revoke)
 ```
 
+## Plain-shell usage (no Claude Code / Codex needed)
+
+```bash
+npx replen run                  # trigger a pipeline run
+npx replen progress             # tail the run live; exits when done
+npx replen check-new            # one-shot: any new actionable matches since
+                                # you last engaged? (also runs automatically
+                                # at every Claude Code session start)
+npx replen feed                 # show recent matches (default 2 days)
+npx replen watch                # keep a terminal open — rings the bell when
+                                # a new match lands. Default poll 5min.
+npx replen search <query>       # full-text search past matches
+npx replen starred              # starred matches + handoff PR status
+npx replen handoff <matchId>    # open the handoff PR for a starred match
+```
+
+`watch` is the calm-utility companion: leave it running in a `tmux` pane and forget about it. The first poll establishes a baseline; existing matches don't ring.
+
+`check-new` is wired into Claude Code automatically by `npx replen` setup — it installs a SessionStart hook that runs `npx replen check-new --hook` whenever you open Claude Code. The hook is silent unless there's something new since you last engaged (across dashboard, email, or a prior session); when there is, the new matches show up in the agent's opening context without you having to ask. Calm-cadence by design.
+
+Every data command accepts `--json` for scripting.
+
 ## Self-host
 
 Pointing at your own replen instance:

package/dist/commands.js

@@ -2,6 +2,7 @@
 // terminal rather than returning JSON to an agent. `--json` flag on every
 // command dumps raw JSON for piping/scripting.
 import { apiGet, apiPost, loadConfigOrExit } from "./api.js";
+import { configPath } from "./config.js";
 function hasFlag(argv, flag) {
     return argv.includes(flag);
 }
@@ -169,6 +170,154 @@ export async function runStarred(argv) {
         handleApiError(e);
     }
 }
+// One-shot "is there anything new" check. Used in two modes:
+//   1. interactive (`replen check-new`): always prints — useful for ad-hoc
+//      "did anything land?" before opening Claude Code.
+//   2. hook (`replen check-new --hook`): SILENT when nothing's new. Tight
+//      timeout so a slow API can't stall every Claude Code session opening.
+//      Errors are swallowed and never fail the session. Output is shaped
+//      so Claude Code's SessionStart-hook stdout injection naturally
+//      surfaces the matches in the agent's opening context.
+export async function runCheckNew(argv) {
+    const hookMode = hasFlag(argv, "--hook");
+    const json = hasFlag(argv, "--json");
+    const repo = getFlag(argv, "--repo");
+    // Hook mode runs on every Claude Code session for every user — including
+    // users who installed Claude Code but never ran `npx replen`. Silent exit
+    // (not the "Not signed in" prompt loadConfigOrExit prints) is required.
+    const { readConfig } = await import("./config.js");
+    const cfg = await readConfig();
+    if (!cfg) {
+        if (hookMode)
+            return;
+        console.error("Not signed in. Run `npx replen` first.");
+        process.exit(1);
+    }
+    const query = {};
+    if (repo !== undefined)
+        query.repo = repo;
+    let r;
+    try {
+        if (hookMode) {
+            // Tight timeout so a slow API never blocks a session open. AbortSignal
+            // would be cleaner but apiGet doesn't surface it; race a manual timer.
+            r = await Promise.race([
+                apiGet(cfg, "/api/mcp/check-new", query),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("hook-timeout")), 2000)),
+            ]);
+        }
+        else {
+            r = await apiGet(cfg, "/api/mcp/check-new", query);
+        }
+    }
+    catch (e) {
+        if (hookMode) {
+            // Silent failure: never disrupt a session for a non-critical signal.
+            // Trace goes to a log so we can debug if needed.
+            try {
+                const { appendFile } = await import("node:fs/promises");
+                await appendFile(configPath().replace(/config\.json$/, "check-new-hook.log"), `${new Date().toISOString()} ${e.message ?? String(e)}\n`);
+            }
+            catch {
+                // intentionally ignore — diagnostic only
+            }
+            return;
+        }
+        handleApiError(e);
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(r, null, 2));
+        return;
+    }
+    if (!r.hasNew) {
+        if (!hookMode) {
+            // Interactive: tell the user explicitly. In hook mode silence is the
+            // correct response (calm-cadence principle).
+            const scope = r.scopedTo ? ` for ${r.scopedTo}` : "";
+            console.log(`No new actionable matches${scope} since you last engaged.`);
+        }
+        return;
+    }
+    // hasNew: print a tight block. Same shape in hook + interactive — Claude
+    // Code's SessionStart hook injects stdout verbatim into the agent's
+    // opening context, so the agent sees this and naturally surfaces it.
+    const scope = r.scopedTo ?? "your projects";
+    const banner = `Replen: ${r.count} new actionable match${r.count === 1 ? "" : "es"} for ${scope} since you last engaged.`;
+    console.log(banner);
+    console.log("");
+    for (const m of r.matches ?? []) {
+        const effort = m.effortBand ? ` · ${m.effortBand}` : "";
+        const score = m.relevanceScore != null ? ` ${m.relevanceScore}` : "";
+        const repoName = m.repo ?? "(no repo)";
+        console.log(`  • ${repoName} (${m.relevance}${score}${effort})`);
+        if (m.oneLine)
+            console.log(`    ${m.oneLine}`);
+    }
+    console.log("");
+    console.log("Call replen_today for the full writeups.");
+}
+// Watch for new matches in the background. Polls /api/mcp/today, diffs against
+// the matchIds seen on the previous poll, prints anything new, and rings the
+// terminal bell (\x07). First poll establishes a baseline — existing matches
+// don't ring. Default interval 5 minutes (the pipeline runs daily by default,
+// so polling tighter is pure overhead).
+export async function runWatch(argv) {
+    const cfg = await loadConfigOrExit();
+    const json = hasFlag(argv, "--json");
+    const noBell = hasFlag(argv, "--no-bell");
+    const intervalSec = Math.max(30, Number(getFlag(argv, "--interval") ?? 300));
+    const days = Number(getFlag(argv, "--days") ?? 2);
+    const project = getFlag(argv, "--project");
+    const relevance = getFlag(argv, "--relevance") ?? "high,medium";
+    const seen = new Set();
+    let firstPass = true;
+    if (!json) {
+        const target = project ? ` · project=${project}` : "";
+        console.log(`Watching for new ${relevance} matches${target} · poll every ${intervalSec}s · Ctrl-C to stop.`);
+    }
+    while (true) {
+        let r;
+        try {
+            r = await apiGet(cfg, "/api/mcp/today", {
+                days,
+                relevance,
+                project,
+            });
+        }
+        catch (e) {
+            // Don't kill the watcher on a transient network blip — just log + retry.
+            console.error(`✗ ${e.message ?? String(e)} (retrying in ${intervalSec}s)`);
+            await sleep(intervalSec * 1000);
+            continue;
+        }
+        const fresh = [];
+        for (const m of r.matches) {
+            if (!seen.has(m.matchId)) {
+                if (!firstPass)
+                    fresh.push(m);
+                seen.add(m.matchId);
+            }
+        }
+        if (json) {
+            // Emit one JSON line per poll, regardless of new/no-new — easy to pipe.
+            console.log(JSON.stringify({ ts: new Date().toISOString(), new: fresh.length, matches: fresh }));
+        }
+        else if (fresh.length > 0) {
+            const stamp = new Date().toISOString().slice(11, 19);
+            console.log(`\n[${stamp}] ${fresh.length} new:`);
+            for (const m of fresh)
+                renderMatchLine(m);
+            if (!noBell)
+                process.stdout.write("\x07");
+        }
+        else if (firstPass) {
+            console.log(`Baseline: ${seen.size} match(es) already in feed; will alert on anything new.`);
+        }
+        firstPass = false;
+        await sleep(intervalSec * 1000);
+    }
+}
 // Open a handoff PR for a starred match in the matched project's own repo.
 export async function runHandoff(argv) {
     const cfg = await loadConfigOrExit();

package/dist/index.js

@@ -3,8 +3,8 @@ import { runInit } from "./init.js";
 import { setupMcp } from "./mcp-setup.js";
 import { readConfig, configPath } from "./config.js";
 import { runProjectInit } from "./project-init.js";
-import { runFeed, runHandoff, runProgress, runRun, runSearch, runStarred } from "./commands.js";
-const HELP = `replen: Smart AI Development workflows
+import { runCheckNew, runFeed, runHandoff, runProgress, runRun, runSearch, runStarred, runWatch } from "./commands.js";
+const HELP = `replen: Smarter AI Development workflows
 
 Usage:
   npx replen                 Sign up / sign in + wire MCP into Claude Code
@@ -18,9 +18,19 @@ Usage:
 Use replen from a plain shell (no Claude Code / Codex needed):
   npx replen run                       Trigger a fresh pipeline run
   npx replen progress                  Live tail of the current run; exits when done
+  npx replen check-new                 One-shot: any new actionable matches
+                  [--repo OWNER/NAME]  since you last engaged? Used by the
+                                       SessionStart hook to surface new
+                                       matches automatically in Claude Code.
   npx replen feed [--days N]           Today's matches (default 2 days)
                   [--project SLUG]     Limit to one project
                   [--relevance high,medium]
+  npx replen watch                     Long-running poll: rings the terminal bell
+                  [--interval SEC]     when a new match lands (default 300s).
+                  [--days N]           First poll establishes baseline; existing
+                  [--project SLUG]     matches don't ring. Ctrl-C to stop.
+                  [--relevance high,medium]
+                  [--no-bell]
   npx replen search <query>            Full-text search across past matches
   npx replen starred                   Starred matches + handoff PR status
   npx replen handoff <matchId>         Open the handoff PR for a starred match
@@ -88,6 +98,10 @@ async function main() {
         return runProgress(argv);
     if (cmd === "feed")
         return runFeed(argv);
+    if (cmd === "watch")
+        return runWatch(argv);
+    if (cmd === "check-new")
+        return runCheckNew(argv);
     if (cmd === "search")
         return runSearch(argv);
     if (cmd === "starred")

package/dist/init.js

@@ -55,7 +55,15 @@ function waitForCallback(port, expectedState) {
                 res.end("state mismatch");
                 return;
             }
-            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            // Referrer-Policy: no-referrer means anything rendered in SUCCESS_HTML
+            // (even if a future maintainer adds an external <img>, <link>, or fetch)
+            // cannot leak the callback URL — which carries the exchange code in
+            // its query string — via an outbound Referer header.
+            res.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "referrer-policy": "no-referrer",
+                "cache-control": "no-store",
+            });
             res.end(SUCCESS_HTML);
             // Give the response a tick to flush before we shut down the listener.
             setTimeout(() => server.close(), 100);

package/dist/mcp-setup.js

@@ -59,6 +59,39 @@ export async function setupMcp(token, base) {
             DIGEST_TOKEN: token,
         },
     };
-    writeJsonAtomic(CONFIG_PATH, { ...config, mcpServers });
+    const hooks = installSessionStartHook(config.hooks ?? {});
+    writeJsonAtomic(CONFIG_PATH, { ...config, mcpServers, hooks });
     console.log(`  ✓ ${overwrite ? "Updated" : "Added"} "${SERVER_NAME}" in ${CONFIG_PATH}`);
+    console.log(`  ✓ Installed SessionStart hook (surfaces new matches automatically)`);
+}
+// SessionStart hook: on every Claude Code session, runs `replen check-new
+// --hook`, which prints a one-block summary to stdout if (and only if)
+// new actionable matches landed since the user last engaged. Claude Code
+// injects that stdout into the agent's opening context, so the agent
+// surfaces the matches to the user without anyone having to ask.
+//
+// When nothing's new the command prints nothing — silence is the calm-
+// cadence position. The 2-second timeout (handled inside check-new --hook)
+// ensures a slow API can't stall session opening.
+//
+// We use the command string `npx --quiet replen check-new --hook` as our
+// idempotency marker: if a SessionStart entry already contains that
+// substring we replace it; otherwise we append. Any other SessionStart
+// hooks the user has are preserved verbatim.
+const HOOK_COMMAND = "npx --quiet replen check-new --hook";
+const HOOK_MARKER = "replen check-new --hook";
+function installSessionStartHook(existing) {
+    const sessionStart = (existing.SessionStart ?? []).slice();
+    const ours = {
+        matcher: "*",
+        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    };
+    const idx = sessionStart.findIndex((entry) => (entry.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)));
+    if (idx >= 0) {
+        sessionStart[idx] = ours;
+    }
+    else {
+        sessionStart.push(ours);
+    }
+    return { ...existing, SessionStart: sessionStart };
 }

package/dist/project-init.js

@@ -21,7 +21,18 @@ Be specific. Use the project's actual domain vocabulary, not generic abstraction
 
 When you're done, print the draft in chat and ask me to confirm before writing the file. If a CLAUDE.md already exists, don't overwrite it without my explicit say-so.
 
-Total length target: 200-500 words, bullet points over paragraphs.`;
+Total length target: 200-500 words, bullet points over paragraphs.
+
+Also append a short "## Replen integration" section with this exact guidance:
+
+  At the start of every session, if the \`replen_check_new\` tool is
+  available, call it once before asking the user what to work on.
+  If \`hasNew\` is true, summarise the count + repos in 1-2 lines and
+  ask if the user wants the full writeups (which they get via
+  \`replen_today\`). If \`hasNew\` is false, say nothing — silence is
+  the correct response, not "no new matches found".
+
+This instruction is a fallback for AI tools that don't run Claude Code's SessionStart hooks (e.g. Codex, Cursor, Aider). For Claude Code users the hook calls \`replen check-new\` automatically and Claude Code injects the result into the opening context — but the CLAUDE.md guidance is durable across tools and survives hook misconfiguration.`;
 export function runProjectInit() {
     console.log("");
     console.log("Copy the prompt below into your AI coding tool (Claude Code / Codex / Cursor / Aider).");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "replen",
-  "version": "0.2.1",
-  "description": "Smart AI Development workflows. The AI that asks 'can we do this better?' - replen reads your codebase against the live ecosystem every morning, surfaces drop-in libraries, ideas to port, and patterns to learn from. A proactive layer for your AI coding workflow. One-command setup: opens a browser to sign in, then wires the MCP server into Claude Code / Codex.",
+  "version": "0.4.0",
+  "description": "Smarter AI Development workflows. The AI that asks 'can we do this better?' - replen reads your codebase against the live ecosystem and surfaces drop-in libraries, ideas to port, and patterns to learn from. Calm cadence: 1-3 actionable matches a month. One-command setup: opens a browser to sign in, then wires the MCP server into Claude Code / Codex.",
   "type": "module",
   "bin": {
     "replen": "dist/index.js"