replen 1.3.1 → 1.5.0

package/dist/auto-register.js

@@ -148,6 +148,9 @@ async function postProjectsBulk(base, token, projects) {
                     name: p.name,
                     tags: p.tags,
                     primaryLanguage: p.primaryLanguage ?? undefined,
+                    // Absolute local checkout path — see sync-projects.ts. Inert unless
+                    // the server is a self-host install with Immersion enabled.
+                    localPath: p.localPath,
                 })),
             }),
             signal: ctrl.signal,

package/dist/immerse.js

@@ -0,0 +1,113 @@
+// `npx replen immerse` — hosted Immersion sender (M2).
+//
+// On the hosted service Replen can't read your disk, so to ground matching on
+// your actual code you opt in and this command does the transmit: for each
+// tracked repo it asks the server which grounded files to send (the manifest),
+// reads exactly those files locally, and POSTs them to the ingest endpoint —
+// which embeds them and keeps ONLY the vectors, discarding the source. Nothing
+// is read or sent for a repo whose tier is off.
+//
+//   npx replen immerse on       opt in (vectors-only) + send now
+//   npx replen immerse          send for an already-opted-in account
+//   npx replen immerse status   show the account default
+//   npx replen immerse off      opt out
+//
+// Self-host installs don't need this — they default on via REPLEN_SELF_HOST and
+// the pipeline reads local disk directly.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfigOrExit, apiGet, apiPost } from "./api.js";
+import { resolveAndWalk } from "./sync-projects.js";
+const MAX_FILE_BYTES = 1_000_000; // mirror the server per-file cap
+export async function runImmerse(argv) {
+    const sub = (argv[0] ?? "").toLowerCase();
+    const cfg = await loadConfigOrExit();
+    if (sub === "status") {
+        const { tier } = await apiGet(cfg, "/api/settings/immersion");
+        console.log(`Immersion (account default): ${tier}`);
+        if (tier === "off")
+            console.log("Run `npx replen immerse on` to enable it. Your code is embedded, then discarded — only vectors are kept.");
+        return;
+    }
+    if (sub === "off") {
+        await apiPost(cfg, "/api/settings/immersion", { tier: "off" });
+        console.log("Immersion turned OFF for your account. Existing code vectors are dropped on the next run.");
+        return;
+    }
+    if (sub === "on") {
+        await apiPost(cfg, "/api/settings/immersion", { tier: "embeddings" });
+        console.log("Immersion ON (vectors-only). Your code is embedded server-side and the source discarded — only the vectors persist.\n");
+        await send(cfg);
+        return;
+    }
+    // No subcommand: send for an already-opted-in account.
+    const { tier } = await apiGet(cfg, "/api/settings/immersion");
+    if (tier === "off") {
+        console.log("Immersion is off for your account. Run `npx replen immerse on` to enable it (vectors-only — your code is embedded, then discarded).");
+        return;
+    }
+    await send(cfg);
+}
+// Discover local repos, then for each tracked + opted-in repo: fetch the
+// manifest, read the listed files, and ingest them.
+async function send(cfg) {
+    console.log("Scanning local repos…");
+    const { result } = await resolveAndWalk([]);
+    const repos = result.projects.filter((p) => p.githubFullName && p.localPath);
+    if (repos.length === 0) {
+        console.log("  · No local git repos with GitHub remotes found. Nothing to send.");
+        return;
+    }
+    let grounded = 0, totalFiles = 0, totalChunks = 0, unchanged = 0;
+    for (const repo of repos) {
+        let manifest;
+        try {
+            manifest = await apiPost(cfg, "/api/immersion/manifest", { githubFullName: repo.githubFullName });
+        }
+        catch {
+            continue; // not tracked on this account (404) / transient — skip quietly
+        }
+        if (manifest.tier === "off" || !Array.isArray(manifest.paths) || manifest.paths.length === 0)
+            continue;
+        // Read exactly the grounded files the server asked for (size-capped).
+        const files = [];
+        for (const rel of manifest.paths) {
+            try {
+                const abs = join(repo.localPath, rel);
+                const st = statSync(abs);
+                if (!st.isFile() || st.size > MAX_FILE_BYTES)
+                    continue;
+                const content = readFileSync(abs, "utf8");
+                if (content.trim())
+                    files.push({ rel, content });
+            }
+            catch {
+                /* file gone / unreadable — skip */
+            }
+        }
+        if (files.length === 0)
+            continue;
+        let res;
+        try {
+            res = await apiPost(cfg, "/api/immersion/ingest", { githubFullName: repo.githubFullName, files });
+        }
+        catch (e) {
+            console.warn(`  ✗ ${repo.githubFullName}: ${e.message}`);
+            continue;
+        }
+        if (res.unchanged) {
+            unchanged++;
+            continue;
+        }
+        grounded++;
+        totalFiles += res.filesEmbedded ?? 0;
+        totalChunks += res.chunksEmbedded ?? 0;
+        console.log(`  ✓ ${repo.githubFullName}: ${res.chunksEmbedded ?? 0} chunk(s) from ${res.filesEmbedded ?? 0} file(s)`);
+    }
+    const parts = [];
+    if (grounded > 0)
+        parts.push(`grounded ${grounded} repo(s) — ${totalChunks} chunk(s) from ${totalFiles} file(s)`);
+    if (unchanged > 0)
+        parts.push(`${unchanged} unchanged`);
+    console.log(`\nImmersion: ${parts.length ? parts.join(", ") : "nothing to update"}.`);
+}

package/dist/index.js

@@ -30,6 +30,11 @@ Usage:
                                npx replen vault me/drone=~/graphs/drone
                              \`npx replen vault --list\` shows configured vaults.
                              (--vault PATH also works on \`npx replen\` + sync.)
+  npx replen immerse [on|off] Ground matching on your ACTUAL code, not just
+       [status]              its description (hosted opt-in; self-host has it
+                             on by default). \`on\` opts in and sends; bare
+                             sends for an opted-in account. Vectors-only: your
+                             code is embedded server-side, then discarded.
   npx replen atlas           Write your knowledge graph as an owned,
                              Obsidian-compatible markdown vault to
                              ~/.replen/atlas/ (projects, capabilities,
@@ -190,6 +195,10 @@ async function main() {
         await syncDiscoveredProjects({ token: cfg.token, base: cfg.base, explicitRoots });
         return;
     }
+    if (cmd === "immerse") {
+        const { runImmerse } = await import("./immerse.js");
+        return runImmerse(argv.slice(1));
+    }
     if (cmd === "run")
         return runRun(argv);
     if (cmd === "progress")

package/dist/sync-projects.js

@@ -38,6 +38,11 @@ export async function syncDiscoveredProjects({ token, base, explicitRoots = [],
             name: p.name,
             tags: p.tags,
             primaryLanguage: p.primaryLanguage ?? undefined,
+            // Absolute local checkout path. Used by Immersion on a self-host install
+            // (server == this machine) to ground on the actual source; inert on the
+            // hosted server, which can't read it. Always sent — it's identity, not
+            // code; nothing is read unless the operator enables Immersion.
+            localPath: p.localPath,
         })),
     };
     let res;
@@ -85,7 +90,7 @@ export async function syncDiscoveredProjects({ token, base, explicitRoots = [],
  * Returns the walked result, the strategy that supplied the roots,
  * and a flag indicating whether the interactive prompt was used.
  */
-async function resolveAndWalk(explicitRoots) {
+export async function resolveAndWalk(explicitRoots) {
     // Strategies that take precedence and short-circuit on hit.
     const ordered = [
         { source: "flag", roots: () => rootsFromFlag(explicitRoots) },

package/extras/skills/replen/SKILL.md

@@ -305,6 +305,28 @@ Continuing with unfiltered for now."
 - The session-start hook already surfaced matches in the opening
   context and the user hasn't asked for more. Don't double-deliver.
 
+## Immersion — grounding on the user's actual code
+
+By default Replen matches against each repo's *description* (docs, tags,
+extracted capabilities). **Immersion** is an opt-in mode that also grounds
+matching on the *actual source* behind each capability — embedded into vectors;
+the raw code is discarded after embedding, never retained. Self-host installs
+have it on by default; hosted is opt-in (`off` until the user enables it).
+
+When to act on it (don't volunteer otherwise):
+
+- The user asks to "use my actual code", "ground on the real implementation",
+  match more precisely, or asks why a match felt shallow → tell them Immersion
+  exists and, if they want it, run `npx replen immerse on` (opts in + sends).
+- Immersion is already on and the user has made material code changes this
+  session and wants the next matches to reflect them → run `npx replen immerse`
+  to refresh (cheap + a no-op when nothing changed — a content hash gates it).
+
+Keep it honest about the trust step: on hosted, enabling Immersion sends the
+grounded files to Replen to be embedded — same posture as the AI agent they're
+already using (transits, embedded, not kept), and strictly less exposure (only
+a vector persists). Never run `immerse on` for them without an explicit yes.
+
 ## Voice guide
 
 - **Concrete.** "Replaces `lib/foo.ts:42-180`" beats "could simplify

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replen",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Make your AI coding tools smarter. One command, no API keys, free. Replen watches what your projects actually do and surfaces a few things worth bringing in each month. Use one as is, port a piece of another, cherry pick an idea, or build it clean room. The match happens inside your AI tool's session. A few actionable matches a month, by design.",
   "type": "module",
   "bin": {