@sporhq/spor 0.2.6 → 0.2.7

package/.claude-plugin/plugin.json

@@ -2,6 +2,6 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "author": { "name": "losthammer" }
 }

package/README.md

@@ -24,21 +24,8 @@ Requires Node 20+ and nothing else — the client is zero-dependency. To run
 from a checkout instead (e.g. to hack on it), clone the repo and `npm link`
 from its root; that symlinks the same two commands onto your PATH.
 
-Then create the graph home (this is yours, kept outside any code repo):
-
-```bash
-spor init        # creates ~/.spor/nodes, git-inits it, writes .gitignore
-```
-
-`spor init` is idempotent. `spor status` then tells you the resolved mode,
-graph, project, and (in remote mode) server health and identity — run it any
-time you're unsure whether Spor is active or which graph you're on. (Without
-the `spor` CLI on your PATH the equivalent is
-`mkdir -p ~/.spor/nodes && git -C ~/.spor init && printf 'journal/\n' > ~/.spor/.gitignore`.)
-
-Then install for your agent. One verb wires up any supported host — it
-resolves the adapter manifest to this checkout and drops it into the host's
-config:
+Wire Spor into your agent. One verb resolves the adapter manifest to this
+install and drops it into the host's config:
 
 ```bash
 spor install claude     # Claude Code (via its plugin CLI — no marketplace browsing)
@@ -50,27 +37,33 @@ spor install            # no host => list the hosts detected on this machine
 per-repo config. `--all` installs every detected host, `--print` is a dry run,
 and `--server <url> --token <tok>` also points the client at a team graph in
 the same step. Re-running is idempotent — it refreshes the path and never
-duplicates your other hooks.
+duplicates your other hooks. (In Claude Code you can also install by hand:
+`/plugin marketplace add sporhq/spor` then `/plugin install spor@spor`.)
 
-In Claude Code you can still install from the marketplace by hand if you
-prefer:
+Then onboard a repo — one command, from inside it:
 
+```bash
+cd ~/my-repo && spor dispatch --backfill
 ```
-/plugin marketplace add sporhq/spor
-/plugin install spor@spor
-```
+
+That does the whole setup in one step: creates your graph home if it doesn't
+exist yet (`~/.spor/nodes`, git-initialised), registers the repo so Spor knows
+where it lives on this machine, makes sure Spor is enabled for it, and launches
+the `/spor:backfill` agent in a Claude Code background session — it mines git
+history, design docs, and issue trackers (edges first) and proposes how to
+group your repos into projects. Watch or attach to it with `claude agents`.
+Re-run it whenever you add a repo, or skip it entirely and just work —
+distillation grows the graph one session at a time.
+
+`spor status` tells you the resolved mode, graph, project, and (on a team
+graph) server health and identity — run it any time you're unsure whether Spor
+is active or which graph you're on. `spor init` does the graph-home setup on
+its own if you'd rather not dispatch anything yet.
 
 For the per-host event mapping, fidelity notes, distiller backend, and the
 `AGENTS.md` fallback for hosts with no hook support, see
 [adapters/](adapters/).
 
-To start with a populated graph, run `/spor:backfill` — the onboarding door. It
-dispatches the heavy mining (git history, design docs, issue trackers, edges
-first) to the bundled `spor-backfill` **subagent**, which runs in its own
-context, and then proposes how to group your repos into projects (re-run it as
-you add repos). Or skip it and just work — distillation grows the graph one
-session at a time.
-
 ## Dispatching background agents
 
 `spor dispatch` hands a task to Claude Code's background-agent machinery

package/bin/spor.js

@@ -101,7 +101,10 @@ function nodeCount(nodesDir) {
   }
 }
 
-function cmdInit(cfg) {
+// Idempotently create the local graph home (nodes/, git, .gitignore). Returns
+// { home, nodesDir, created } and prints nothing — callers do their own UX.
+// Shared by `spor init` and the `spor dispatch --backfill` onboarding path.
+function ensureGraphHome(cfg) {
   const home = cfg.graphHome();
   const nodesDir = path.join(home, "nodes");
   let created = false;
@@ -122,6 +125,11 @@ function cmdInit(cfg) {
       /* non-fatal */
     }
   }
+  return { home, nodesDir, created };
+}
+
+function cmdInit(cfg) {
+  const { home, nodesDir, created } = ensureGraphHome(cfg);
   out(`${created ? "Created" : "Graph already present at"} ${home}`);
   out(`  nodes:  ${nodesDir} (${nodeCount(nodesDir) ?? 0} nodes)`);
   out(`  mode:   ${cfg.mode()}`);
@@ -1004,6 +1012,45 @@ function shellQuote(s) {
   return /[^\w./:-]/.test(s) ? `'${String(s).replace(/'/g, "'\\''")}'` : s;
 }
 
+// Re-enable Spor for a repo by merging { enabled: true } into its committable
+// .spor.json (and clearing a `mode: off`, which also disables). Used by the
+// --backfill onboarding to repair a repo a prior `spor disable` turned off.
+function enableRepoAt(dir) {
+  const file = path.join(dir, ".spor.json");
+  let data = {};
+  try {
+    data = JSON.parse(fs.readFileSync(file, "utf8")) || {};
+  } catch {
+    /* absent or malformed — start fresh */
+  }
+  data.enabled = true;
+  if (data.mode === "off") delete data.mode;
+  try {
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+  } catch {
+    /* non-fatal */
+  }
+}
+
+// `spor dispatch --backfill` is the onboarding door (task-spor-cli-dispatch-
+// background-agents): set the repo up before launching its backfill agent.
+// Idempotent; prints what it did. The dir-registration happens in cmdDispatch
+// (it applies to every dispatch), this adds the init + enable steps.
+function onboardRepo(cfg, dir) {
+  // Init the local graph home — but only in local mode; remote mode keeps the
+  // graph on the server, so there is nothing to create locally.
+  if (cfg.mode() !== "remote") {
+    const r = ensureGraphHome(cfg);
+    out(r.created ? `initialized graph home at ${r.home}` : `graph home ready: ${r.home}`);
+  }
+  // Re-enable the repo if a prior `spor disable` turned it off, so onboarding a
+  // disabled repo actually works instead of silently launching into a no-op.
+  if (!cfg.enabled()) {
+    enableRepoAt(dir);
+    out(`re-enabled Spor for ${dir}`);
+  }
+}
+
 async function cmdDispatch(cfg, args) {
   const dryRun = args.includes("--print") || args.includes("--dry-run");
   const full = args.includes("--full");
@@ -1089,9 +1136,6 @@ async function cmdDispatch(cfg, args) {
     err(`target dir does not exist: ${res.dir}`);
     return 1;
   }
-  // Learn the mapping from this CLI use too.
-  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
-
   const prompt = brief
     ? `# Spor briefing (compiled for this task — your standing context)\n\n${brief}\n\n---\n\n# Task\n\n${instruction}\n`
     : instruction;
@@ -1106,12 +1150,26 @@ async function cmdDispatch(cfg, args) {
 
   if (dryRun) {
     out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
+    if (backfill) {
+      const steps = [];
+      if (cfg.mode() !== "remote") steps.push(fs.existsSync(cfg.nodesDir()) ? "graph home ready" : "init graph home");
+      steps.push(`register ${res.slug} → ${res.dir}`);
+      if (!cfg.enabled()) steps.push("re-enable repo (currently disabled)");
+      out(`onboard: ${steps.join("; ")}`);
+    }
     out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
     out(`run:    ${claudeBin} ${claudeArgs.slice(0, -1).map(shellQuote).join(" ")} <prompt>`);
     out(`\n--- prompt ---\n${prompt}`);
     return 0;
   }
 
+  // Side effects (real run only — --print writes nothing). --backfill is the
+  // onboarding door, so it sets the repo up (init + enable) first; every
+  // dispatch self-registers the dir it resolved.
+  if (backfill) onboardRepo(cfg, res.dir);
+  u.registerRepo(cfg.graphHome(), res.slug, res.dir);
+  if (backfill) out(`registered ${res.slug} → ${res.dir}; launching the backfill agent…`);
+
   if (claudeBin === "claude" && !hasCmd("claude")) {
     err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
     return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",