@tricknowtech/context 0.1.0 → 0.2.0

package/README.md

@@ -18,10 +18,17 @@ Open the same project on a second machine and the assistant knows nothing. Your
 
 ```bash
 ctx push      # collect context into the store
-ctx pull      # restore it on another machine
+ctx pull      # restore it, and print where you left off
 ctx status    # what changed since the last push
+ctx handoff   # show or write the session handoff
+ctx doctor    # check the setup is actually wired correctly
 ```
 
+Start with `ctx doctor` if anything seems off — it verifies the pieces that
+fail silently, including whether your store is accidentally gitignored (in
+which case it never reaches the other machine) and whether restored memory
+lands where Claude Code actually reads it.
+
 Commit `.contextsync/` and your teammates — and your other laptop — get the same context on clone.
 
 ### It skips what git already carries
@@ -46,7 +53,25 @@ Claude Code names its per-project directories after the absolute project path
 
 `/context push` asks the model to write `.contextsync/handoff.json` first — goal, decisions made, open threads, files touched, next step. Only the model has the conversation; only the CLI has the disk, so the slash command is the one place both are available.
 
-On the other machine, `/context pull` restores everything and reads the handoff back, so the new session starts oriented instead of blank.
+On the other machine, `/context pull` restores everything and reads the handoff back, so the new session starts oriented instead of blank:
+
+```
+Where you left off  (2h ago)
+
+  Goal       Build the context-sync tool and publish it
+  Next step  Start the cloud remote, leading with the token-scoping fix
+
+  Decided:
+    · Local-first: store is committed to the repo, cloud is an optional remote
+  Still open:
+    · mcp:* token abilities are granted but never checked
+```
+
+The handoff is validated on write and on read — a model-authored file that's
+malformed is reported rather than silently ignored, since a handoff that looks
+present but says nothing is worse than an obviously absent one. `ctx push`
+tells you when no handoff was written, so you never discover it only after
+arriving on the other machine.
 
 ## Safety
 

package/dist/{chunk-DEH5MUFT.js → chunk-6GB2SN2L.js}

@@ -228,12 +228,41 @@ var PROJECT_CONTEXT_GLOBS = [
   ".cursorrules",
   ".github/copilot-instructions.md",
   ".claude/settings.json",
+  // `.local.json` variants are gitignored by default, so nothing else carries
+  // them — which makes them exactly the kind of file this tool exists for.
+  ".claude/settings.local.json",
   ".claude/memory/",
   ".claude/plans/",
   ".claude/commands/",
   ".claude/agents/",
   ".claude/skills/"
 ];
+function planStem(fileName) {
+  return fileName.replace(/\.md$/, "").replace(/-agent-[0-9a-f]+$/i, "");
+}
+function collectPlans(plansDir, projectRoot, exclude) {
+  const all = walk(plansDir, { exclude });
+  if (all.length === 0) return [];
+  const projectName = path3.basename(projectRoot);
+  const related = /* @__PURE__ */ new Set();
+  const stems = /* @__PURE__ */ new Set();
+  for (const abs of all) {
+    let text = "";
+    try {
+      text = fs3.readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (text.includes(projectRoot) || text.includes(projectName)) {
+      related.add(abs);
+      stems.add(planStem(path3.basename(abs)));
+    }
+  }
+  for (const abs of all) {
+    if (stems.has(planStem(path3.basename(abs)))) related.add(abs);
+  }
+  return [...related];
+}
 function push(out, sourcePath, storePath, tier, sourceRoot, ctx) {
   let size = 0;
   try {
@@ -268,10 +297,24 @@ function collect(projectRoot, cfg, tiers) {
       }
       push(files, abs, `project/${rel}`, "core", "project", ctx);
     }
-    const memoryDir = path3.join(userClaude, "projects", key, "memory");
-    for (const abs of walk(memoryDir, { exclude })) {
-      const rel = toPosix(path3.relative(memoryDir, abs));
-      push(files, abs, `memory/${rel}`, "core", "user", ctx);
+    const projectsDir = path3.join(userClaude, "projects");
+    let projectKeys = [];
+    try {
+      projectKeys = fs3.readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && (d.name === key || d.name.startsWith(key + "-"))).map((d) => d.name);
+    } catch {
+      projectKeys = [];
+    }
+    for (const pk of projectKeys) {
+      const memoryDir = path3.join(projectsDir, pk, "memory");
+      for (const abs of walk(memoryDir, { exclude })) {
+        const rel = toPosix(path3.relative(memoryDir, abs));
+        const storePath = pk === key ? `memory/${rel}` : `memory-sub/${pk.slice(key.length + 1)}/${rel}`;
+        push(files, abs, storePath, "core", "user", ctx);
+      }
+    }
+    for (const abs of collectPlans(path3.join(userClaude, "plans"), projectRoot, exclude)) {
+      const rel = toPosix(path3.relative(path3.join(userClaude, "plans"), abs));
+      push(files, abs, `plans/${rel}`, "core", "user", ctx);
     }
     const skillsDir = path3.join(userClaude, "skills");
     for (const abs of walk(skillsDir, { exclude })) {
@@ -307,6 +350,44 @@ function collect(projectRoot, cfg, tiers) {
   }
   return { files, skippedTracked, ctx };
 }
+function describeExcluded(projectRoot, tiers) {
+  const userClaude = userClaudeDir();
+  const key = cwdKey(projectRoot);
+  const out = [];
+  const measure = (dir, filter) => {
+    let files = 0;
+    let bytes = 0;
+    for (const abs of walk(dir, { exclude: [] })) {
+      if (filter && !filter(abs)) continue;
+      files++;
+      try {
+        bytes += fs3.statSync(abs).size;
+      } catch {
+      }
+    }
+    return { files, bytes };
+  };
+  if (!tiers.includes("transcripts")) {
+    const projDir = path3.join(userClaude, "projects", key);
+    const m = measure(projDir, (p) => !p.includes(`${path3.sep}memory${path3.sep}`));
+    if (m.files > 0) {
+      out.push({
+        label: "session transcripts",
+        ...m,
+        reason: "cloud-only \u2014 append-only logs this large would permanently bloat the repo"
+      });
+    }
+  }
+  for (const [dir, label, reason] of [
+    ["uploads", "pasted files/images", "session-scoped binaries; regenerate rather than sync"],
+    ["file-history", "edit-undo snapshots", "transient local undo state, not portable context"],
+    ["tasks", "task outputs", "session-scoped tool output"]
+  ]) {
+    const m = measure(path3.join(userClaude, dir));
+    if (m.files > 0) out.push({ label, ...m, reason });
+  }
+  return out.filter((g) => g.bytes > 0);
+}
 function summarize(files) {
   const empty = { count: 0, bytes: 0 };
   const out = {
@@ -322,6 +403,86 @@ function summarize(files) {
   return out;
 }
 
+// src/handoff.ts
+function asStringArray(value) {
+  if (value === void 0 || value === null) return [];
+  if (!Array.isArray(value)) return null;
+  if (!value.every((v) => typeof v === "string")) return null;
+  return value;
+}
+function validateHandoff(raw) {
+  const errors = [];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, errors: ["handoff must be a JSON object"] };
+  }
+  const o = raw;
+  const goal = typeof o.goal === "string" ? o.goal.trim() : "";
+  const nextStep = typeof o.nextStep === "string" ? o.nextStep.trim() : "";
+  if (!goal) errors.push("`goal` is required (what the session set out to do)");
+  if (!nextStep) errors.push("`nextStep` is required (the single next action)");
+  const decisions = asStringArray(o.decisions);
+  const openThreads = asStringArray(o.openThreads);
+  const filesTouched = asStringArray(o.filesTouched);
+  if (decisions === null) errors.push("`decisions` must be an array of strings");
+  if (openThreads === null) errors.push("`openThreads` must be an array of strings");
+  if (filesTouched === null) errors.push("`filesTouched` must be an array of strings");
+  let updatedAt = typeof o.updatedAt === "string" ? o.updatedAt : "";
+  if (!updatedAt || Number.isNaN(Date.parse(updatedAt))) updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (errors.length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    errors: [],
+    handoff: {
+      updatedAt,
+      goal,
+      decisions: decisions ?? [],
+      openThreads: openThreads ?? [],
+      filesTouched: filesTouched ?? [],
+      nextStep,
+      ...typeof o.notes === "string" && o.notes.trim() ? { notes: o.notes.trim() } : {}
+    }
+  };
+}
+function ago(iso) {
+  const ms = Date.now() - Date.parse(iso);
+  if (Number.isNaN(ms)) return "unknown";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+function formatHandoff(h) {
+  const lines = [`Where you left off  (${ago(h.updatedAt)})`, "", `  Goal       ${h.goal}`, `  Next step  ${h.nextStep}`];
+  if (h.decisions.length > 0) {
+    lines.push("", "  Decided:");
+    for (const d of h.decisions) lines.push(`    \xB7 ${d}`);
+  }
+  if (h.openThreads.length > 0) {
+    lines.push("", "  Still open:");
+    for (const t of h.openThreads) lines.push(`    \xB7 ${t}`);
+  }
+  if (h.filesTouched.length > 0) {
+    const shown = h.filesTouched.slice(0, 12);
+    lines.push("", "  Files touched:");
+    for (const f of shown) lines.push(`    ${f}`);
+    if (h.filesTouched.length > shown.length) {
+      lines.push(`    \u2026 and ${h.filesTouched.length - shown.length} more`);
+    }
+  }
+  if (h.notes) lines.push("", `  Notes: ${h.notes}`);
+  return lines;
+}
+function handoffAge(h) {
+  return ago(h.updatedAt);
+}
+function isStale(h, newestContentMs) {
+  const t = Date.parse(h.updatedAt);
+  if (Number.isNaN(t)) return true;
+  return newestContentMs - t > 60 * 60 * 1e3;
+}
+
 // src/scaffold.ts
 import fs4 from "fs";
 import path4 from "path";
@@ -606,7 +767,12 @@ export {
   loadConfig,
   saveConfig,
   collect,
+  describeExcluded,
   summarize,
+  validateHandoff,
+  formatHandoff,
+  handoffAge,
+  isStale,
   SLASH_COMMAND_PATH,
   SLASH_COMMAND_BODY,
   installSlashCommand,