replen 0.4.1 → 1.0.1

package/dist/sync-projects.js

@@ -0,0 +1,195 @@
+// Orchestrates project discovery + server registration. Tries layered
+// inference strategies (cwd / Claude Code config / hardcoded roots /
+// interactive prompt) until at least one git repo is found, then walks
+// each root recursively to find every repo, then POSTs to
+// /api/projects/bulk for upsert.
+//
+// Persists the user's chosen root(s) to ~/.replen/config.json so future
+// `npx replen sync-projects` runs use the same set without re-prompting.
+import { readConfig, writeConfig } from "./config.js";
+import { discoverProjects } from "./discover-projects.js";
+import { promptForRoot, rootsFromClaudeJson, rootsFromConfig, rootsFromCwdWalkUp, rootsFromEnv, rootsFromFlag, rootsFromHardcoded, } from "./discover-roots.js";
+export async function syncDiscoveredProjects({ token, base, explicitRoots = [], }) {
+    const { result, source, prompted } = await resolveAndWalk(explicitRoots);
+    // Tell the user what we did, regardless of outcome.
+    reportDiscovery(result, source);
+    if (result.projects.length === 0) {
+        console.log(`  · No git repos with GitHub remotes were found. Run \`npx replen sync-projects --root <path>\` to point at a specific dir, or set REPLEN_PROJECT_ROOTS=...`);
+        return { discovered: 0, created: 0, updated: 0 };
+    }
+    // Persist ONLY when the user came in via the interactive prompt.
+    // Flags and env vars are deliberate per-invocation overrides — saving
+    // them to config creates a confusing dual source of truth and, worse,
+    // can lock subsequent commands (like `inject` with no args) into the
+    // narrow scope the user chose for a one-off `--root` use.
+    if (prompted) {
+        await persistRoots(result.scannedRoots);
+    }
+    const payload = {
+        projects: result.projects.map((p) => ({
+            slug: p.slug,
+            githubFullName: p.githubFullName, // null is impossible here — we filter above
+            name: p.name,
+            tags: p.tags,
+            primaryLanguage: p.primaryLanguage ?? undefined,
+        })),
+    };
+    let res;
+    try {
+        res = await fetch(`${base}/api/projects/bulk`, {
+            method: "POST",
+            headers: {
+                "x-digest-token": token,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (e) {
+        console.warn(`  ✗ Failed to reach ${base}/api/projects/bulk: ${e.message}`);
+        console.warn(`    Skipping project registration. Run \`npx replen sync-projects\` later to retry.`);
+        return { discovered: result.projects.length, created: 0, updated: 0 };
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(`  ✗ Project registration failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+        return { discovered: result.projects.length, created: 0, updated: 0 };
+    }
+    const body = (await res.json());
+    const created = body.created ?? 0;
+    const updated = body.updated ?? 0;
+    if (created > 0 || updated > 0) {
+        const parts = [];
+        if (created > 0)
+            parts.push(`${created} new`);
+        if (updated > 0)
+            parts.push(`${updated} updated`);
+        console.log(`  ✓ Registered with Replen: ${parts.join(", ")}`);
+    }
+    else {
+        console.log(`  · All ${result.projects.length} projects already up to date with Replen`);
+    }
+    return { discovered: result.projects.length, created, updated };
+}
+/**
+ * Try discovery strategies in priority order. The first strategy that
+ * yields ≥1 project's worth of repos wins; if none do, falls back to
+ * the interactive prompt.
+ *
+ * Returns the walked result, the strategy that supplied the roots,
+ * and a flag indicating whether the interactive prompt was used.
+ */
+async function resolveAndWalk(explicitRoots) {
+    // Strategies that take precedence and short-circuit on hit.
+    const ordered = [
+        { source: "flag", roots: () => rootsFromFlag(explicitRoots) },
+        { source: "env", roots: () => rootsFromEnv() },
+        { source: "config", roots: () => rootsFromConfig() },
+    ];
+    for (const { source, roots } of ordered) {
+        const r = await roots();
+        if (r.length > 0) {
+            const result = discoverProjects(r);
+            return { result, source, prompted: false };
+        }
+    }
+    // Inference strategies combine: walk the union of cwd / Claude / hardcoded.
+    // Any one of them surfacing repos is enough; we union to maximise the
+    // chance of catching the user's repos no matter where they live.
+    const inferred = Array.from(new Set([
+        ...rootsFromCwdWalkUp(),
+        ...rootsFromClaudeJson(),
+        ...rootsFromHardcoded(),
+    ]));
+    if (inferred.length > 0) {
+        const result = discoverProjects(inferred);
+        if (result.projects.length > 0) {
+            return { result, source: pickInferredSource(inferred), prompted: false };
+        }
+        // Inferred roots existed but contained no GitHub repos — fall
+        // through to prompt rather than reporting empty.
+    }
+    // Last resort: ask.
+    const chosen = await promptForRoot();
+    if (!chosen) {
+        return {
+            result: { projects: [], nonGithubSkipped: 0, scannedRoots: inferred },
+            source: "prompt",
+            prompted: true,
+        };
+    }
+    const result = discoverProjects([chosen]);
+    return { result, source: "prompt", prompted: true };
+}
+/**
+ * If the inferred-roots union turned up projects, pick the most
+ * specific source for the user-facing message. Order matches priority:
+ * cwd is most specific, hardcoded least.
+ */
+function pickInferredSource(roots) {
+    if (rootsFromCwdWalkUp().some((r) => roots.includes(r)))
+        return "cwd";
+    if (rootsFromClaudeJson().some((r) => roots.includes(r)))
+        return "claude-json";
+    return "hardcoded";
+}
+function reportDiscovery(result, source) {
+    const sourceLabel = {
+        flag: "from --root flag",
+        env: "from REPLEN_PROJECT_ROOTS env",
+        config: "from saved config",
+        cwd: "via cwd walk-up",
+        "claude-json": "via Claude Code's tracked projects",
+        hardcoded: "via conventional ~/github, ~/code, ~/projects",
+        prompt: "you specified",
+    };
+    console.log(`  · Scanning ${result.scannedRoots.length} root(s) (${sourceLabel[source]}):`);
+    for (const r of result.scannedRoots.slice(0, 5)) {
+        console.log(`      ${r}`);
+    }
+    if (result.scannedRoots.length > 5) {
+        console.log(`      … and ${result.scannedRoots.length - 5} more`);
+    }
+    if (result.projects.length === 0)
+        return;
+    console.log(`  ✓ Found ${result.projects.length} git repo(s) with GitHub remotes:`);
+    for (const p of result.projects.slice(0, 5)) {
+        const sampleTags = p.tags.slice(0, 3).join(", ") || "(no auto-tags)";
+        const localHint = pathHint(p);
+        console.log(`      • ${p.githubFullName} ${localHint}  →  ${sampleTags}`);
+    }
+    if (result.projects.length > 5) {
+        console.log(`      … and ${result.projects.length - 5} more`);
+    }
+    if (result.nonGithubSkipped > 0) {
+        console.log(`  · Skipped ${result.nonGithubSkipped} local repo(s) without a GitHub remote (nothing to match against)`);
+    }
+}
+/** Render "(at ~/projects/drone)" only when the dirname differs from the
+ * repo name — i.e. only when there's actual signal worth showing. */
+function pathHint(p) {
+    const repoName = (p.githubFullName ?? "").split("/")[1] ?? "";
+    const dirName = p.localPath.split("/").pop() ?? "";
+    if (!repoName || dirName.toLowerCase() === repoName.toLowerCase())
+        return "";
+    // Compress home prefix for readability.
+    const home = process.env.HOME ?? "";
+    const display = home && p.localPath.startsWith(home) ? "~" + p.localPath.slice(home.length) : p.localPath;
+    return ` (at ${display})`;
+}
+async function persistRoots(roots) {
+    const cfg = await readConfig();
+    if (!cfg)
+        return;
+    // Don't overwrite if config already had a roots list — leave the
+    // user's previous choice alone unless they re-prompt.
+    if (cfg.projectRoots && cfg.projectRoots.length > 0)
+        return;
+    await writeConfig({ ...cfg, projectRoots: roots });
+}
+// Returns just the discovered list without sending. Useful for the
+// CLI's `replen list-projects` subcommand (preview mode).
+export async function previewDiscovery(explicitRoots = []) {
+    const { result } = await resolveAndWalk(explicitRoots);
+    return result;
+}

package/extras/skills/replen-match/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: replen-match
+description: Triage today's Replen candidates against the open codebase, in-session, using subscription tokens. Pulls the day's inventory from Replen, reads the user's local source, produces per-candidate writeups with verdict + effort + concrete file-level impact, then captures star/hide/handoff actions back to Replen. Invoke with `/replen-match` or by saying "run replen on this repo" / "what's new from replen?".
+---
+
+# Replen Match — in-session candidate triage
+
+You are running the matching loop locally. Replen has fetched a list of
+plausible OSS candidates from the wider ecosystem; you've got the user's
+codebase open. Your job is to decide which (if any) are worth their
+attention, write up the strong ones, and capture what they want to do
+about them.
+
+**This runs entirely on the user's subscription tokens.** No API keys
+get used. Replen's hosted side did the cheap structural filtering; you
+do the expensive, code-grounded reasoning.
+
+## Protocol
+
+### Step 1 — Auth + context
+
+1. Read `~/.replen/config.json` to get the user's DIGEST_TOKEN and base
+   URL. If the file doesn't exist, stop and tell the user to run
+   `npx replen` first.
+2. Run `git remote get-url origin` to detect the repo. Extract
+   `owner/name` from the URL.
+3. Run `git log --oneline -20` to get a sense of recent activity (will
+   inform scoring — what's the user actively working on?).
+
+### Step 2 — Pull today's inventory
+
+Call:
+
+```bash
+curl -sS -H "x-digest-token: $TOKEN" \
+  "$BASE/api/inventory/today?repo=<owner/name>&days=2&limit=10"
+```
+
+Parse the JSON response. Note:
+
+- `filterMode` — `tags`, `zero-knowledge`, or `fingerprint`
+- `scopedTo` — confirms the project context the user has open
+- `candidates[]` — the actual list to triage
+
+If `candidates.length === 0`, tell the user "No new candidates today for
+`<owner/name>`. Calm-cadence working as designed — 1-3 actionable
+matches a month is the goal." Stop.
+
+If 1+ candidates, continue.
+
+### Step 3 — Per-candidate analysis
+
+**Cap at 5 candidates.** If the inventory returned more, take the top 5
+by `whyShortlisted` strength + stars + recency, defer the rest.
+
+For each candidate, do this loop:
+
+#### 3a. Gather signals
+
+- WebFetch `<candidate.url>` — the GitHub repo page. Pull description +
+  README.
+- If the README mentions specific files (e.g. `src/index.ts`), WebFetch
+  the raw file too (`https://raw.githubusercontent.com/<owner>/<name>/<default-branch>/<path>`).
+- Search the user's local codebase for related code:
+  - If the candidate is in a known package ecosystem, grep the user's
+    `package.json` / `pyproject.toml` / etc. for the candidate's name
+    or close variants (the user might already have a similar dep).
+  - If the candidate solves a problem area (e.g. "social card generator"),
+    grep the user's source for files that already do that work
+    (e.g. `grep -rln "Canvas\|imageRenderer\|OG"` under `lib/` and `src/`).
+  - If you find one, read the file to understand what the user has built.
+
+#### 3b. Form a verdict
+
+You're answering: **is this worth the user's attention right now?**
+
+Verdicts:
+
+- **adopt** — drop-in replacement / direct dep. The candidate does
+  something the user genuinely needs and isn't doing well. Wire up.
+- **port** — the candidate has an idea / pattern / algorithm worth
+  copying, but the candidate's runtime / language / license is
+  mismatched. Worth reading + adapting; not worth depending on.
+- **skip** — the candidate is a worse version of what the user has, the
+  candidate's runtime is incompatible, or the candidate's not actively
+  maintained. Honest skips are valuable signal; don't manufacture
+  reasons to keep something.
+
+Score the fit on a 0-100 scale:
+
+- 80-100 = high (strong fit, clear adopt or port path, no major blockers)
+- 50-79 = medium (real value, but caveats — port path required, or
+  partial overlap, or active-area-mismatched)
+- 0-49 = general-awareness or skip (interesting but not directly
+  actionable; or definitely skip)
+
+Estimate effort:
+
+- **quick** — <1 day. Single-file swap, drop a dep, copy a file.
+- **moderate** — 1-3 days. Real API delta, multi-site update, light port.
+- **deep** — 1+ week. Framework adoption, paradigm shift, full rewrite.
+
+#### 3c. Compose the writeup
+
+Format **exactly** like this for each candidate:
+
+```
+### owner/name — VERDICT (score) · effort
+
+**One-liner.** What the candidate is, in one sentence.
+
+**Why this could help.** 2-3 sentences. Be specific. Reference the
+user's actual files when possible:
+- "Could replace `lib/social/imageRenderer.ts` (180 LoC) with a 30-line
+  wrapper around X."
+- "Their `<approach>` is what `scripts/auto-process.ts:124` tries to do
+  in 80 lines; copying the algorithm saves ~50 lines and the buggy
+  edge cases."
+
+**Integration approach.** One of: cherry-pick / vendor /
+cleanroom-rebuild / depend-on-it / n/a. Plus a one-sentence note on what
+that means here.
+
+**Caveats.** Anything to watch for — license, abandonment, runtime
+mismatch, security flag. Empty list is fine; don't manufacture.
+```
+
+No marketing voice. No hype. The user is a working engineer; talk to
+them like a peer. Concrete > clever.
+
+### Step 4 — Present + capture actions
+
+After all writeups, summarise:
+
+```
+3 candidates triaged for tech-news-site:
+  ✓ adopt: kribblo/node-ffmpeg-installer (high · quick) — ffmpeg-static swap
+  ⏭ port:  tj/n (medium · moderate) — version-manager pattern
+  ✗ skip:  vercel/turbo (medium · deep) — wrong runtime, already have Vite
+
+For each, what would you like to do? (star / hide / handoff / skip)
+```
+
+Then, for each candidate, capture the user's choice. For each action,
+POST to `/api/state`:
+
+```bash
+curl -sS -X POST \
+  -H "x-digest-token: $TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"repo":"owner/name","status":"<star|hide|handed_off|surfaced>","projectId":<id-from-inventory-projectMatch-or-null>}' \
+  "$BASE/api/state"
+```
+
+Status values:
+
+- `starred` — user wants to come back to this. Won't re-surface.
+- `hidden` — user dismissed it. Never re-surface unless they clear it.
+- `handed_off` — user wants a handoff PR opened against their project.
+  Use the existing `mcp__replen__replen_handoff` MCP tool to actually
+  open the PR (server-side, needs write-scoped GitHub auth). Pass the
+  PR URL back to /api/state via `handoffPrUrl` so future sessions see
+  the status.
+- `surfaced` — neutral "I showed this, user neither stared nor hid."
+  Bumps the surface counter so the inventory deprioritises it next
+  call without locking it out. POST this for EVERY candidate you
+  presented, even the skips. It's the closing bookend of this skill.
+
+### Step 5 — Close out
+
+End with one line summarising what got actioned:
+
+```
+Done. 1 starred, 0 handoff PRs opened, 1 hidden, 1 skipped.
+Run /replen-match again tomorrow for the next batch (or whenever a
+fresh candidate shows up at session start via the hook).
+```
+
+## What to do if things go wrong
+
+**Inventory call returns 401.** User's token expired or got rotated.
+Tell them to run `npx replen` to re-auth.
+
+**Inventory returns `scopedTo: null` with a `note` about "repo not in
+your project list"**. The cwd isn't a known project. Ask the user:
+"This repo isn't in your Replen projects yet. Add it via /projects?"
+Then either stop or re-run with `?repo=` (empty) to see the global
+firehose.
+
+**Candidate's README is unreachable (WebFetch 404)**. Note it in the
+writeup (`Caveats: README unreachable; verdict based on description
+only`) and proceed with a more conservative score.
+
+**Local codebase is large / search is slow.** Don't do `grep -r` from
+the root; scope to `src/`, `lib/`, `app/`. Skip `node_modules`,
+`dist`, `build`, `.next`, `vendor`. If you genuinely can't find
+related code in 3 grep attempts, say so in the writeup ("No directly
+related code found in src/; verdict based on README + project shape
+only").
+
+**No project tags configured (inventory returns
+`whyShortlisted: "no project tags configured; showing unfiltered"`)**.
+The user hasn't set up filter-mode B's tag list. Mention it once: "Heads
+up — you'd get sharper matches if you set project tags at /settings.
+Continuing with unfiltered for now."
+
+## When NOT to run this skill
+
+- The user is mid-task and just wants help with the current thing. The
+  match flow is interruptive; don't volunteer it. Only run when invoked
+  via `/replen-match` or when the user explicitly asks.
+- The repo isn't a tracked Replen project. Tell them how to add it,
+  don't try to match against an unknown project.
+- The session-start hook already surfaced matches in the opening
+  context and the user hasn't asked for more. Don't double-deliver.
+
+## Voice guide
+
+- **Concrete.** "Replaces `lib/foo.ts:42-180`" beats "could simplify
+  your image pipeline."
+- **Honest.** Skip is a valid verdict, often the right one. Don't pad.
+- **One-block-per-candidate.** Don't sprawl. The user will read 1-3
+  candidates; if you write 9 paragraphs each, they bail.
+- **Show your work.** When the verdict is "adopt", say WHAT in the
+  user's code it replaces. When "port", say WHAT idea is worth
+  porting. When "skip", say WHY.
+- **No salesmanship.** Don't end with "would you like to learn more?"
+  The user will tell you what they want.
+- **Match the calm-cadence positioning.** Most days, no candidates.
+  When there are some, they're real. Treat them that way.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "replen",
-  "version": "0.4.1",
-  "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.",
+  "version": "1.0.1",
+  "description": "Make your AI coding tools smarter. One command, no API keys. Replen scouts the OSS firehose against your projects and surfaces drop-in libraries, ideas to port, and dead deps to swap — the match decision happens inside your AI tool's session on your subscription tokens. 1-3 actionable matches a month, by design.",
   "type": "module",
   "bin": {
     "replen": "dist/index.js"
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "extras",
     "README.md",
     "LICENSE"
   ],
@@ -38,5 +39,8 @@
     "@types/node": "^22.10.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "smol-toml": "^1.6.1"
   }
 }