@tricknowtech/context 0.1.0 → 0.2.0

package/dist/cli.cjs

@@ -36,6 +36,7 @@ __export(cli_exports, {
 module.exports = __toCommonJS(cli_exports);
 
 // src/commands.ts
+var import_node_child_process2 = require("child_process");
 var import_node_fs7 = __toESM(require("fs"), 1);
 var import_node_path6 = __toESM(require("path"), 1);
 
@@ -273,12 +274,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 = import_node_path3.default.basename(projectRoot);
+  const related = /* @__PURE__ */ new Set();
+  const stems = /* @__PURE__ */ new Set();
+  for (const abs of all) {
+    let text = "";
+    try {
+      text = import_node_fs3.default.readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (text.includes(projectRoot) || text.includes(projectName)) {
+      related.add(abs);
+      stems.add(planStem(import_node_path3.default.basename(abs)));
+    }
+  }
+  for (const abs of all) {
+    if (stems.has(planStem(import_node_path3.default.basename(abs)))) related.add(abs);
+  }
+  return [...related];
+}
 function push(out2, sourcePath, storePath, tier, sourceRoot, ctx) {
   let size = 0;
   try {
@@ -313,10 +343,24 @@ function collect(projectRoot, cfg, tiers) {
       }
       push(files, abs, `project/${rel}`, "core", "project", ctx);
     }
-    const memoryDir = import_node_path3.default.join(userClaude, "projects", key, "memory");
-    for (const abs of walk(memoryDir, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(memoryDir, abs));
-      push(files, abs, `memory/${rel}`, "core", "user", ctx);
+    const projectsDir = import_node_path3.default.join(userClaude, "projects");
+    let projectKeys = [];
+    try {
+      projectKeys = import_node_fs3.default.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 = import_node_path3.default.join(projectsDir, pk, "memory");
+      for (const abs of walk(memoryDir, { exclude })) {
+        const rel = toPosix(import_node_path3.default.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(import_node_path3.default.join(userClaude, "plans"), projectRoot, exclude)) {
+      const rel = toPosix(import_node_path3.default.relative(import_node_path3.default.join(userClaude, "plans"), abs));
+      push(files, abs, `plans/${rel}`, "core", "user", ctx);
     }
     const skillsDir = import_node_path3.default.join(userClaude, "skills");
     for (const abs of walk(skillsDir, { exclude })) {
@@ -352,6 +396,44 @@ function collect(projectRoot, cfg, tiers) {
   }
   return { files, skippedTracked, ctx };
 }
+function describeExcluded(projectRoot, tiers) {
+  const userClaude = userClaudeDir();
+  const key = cwdKey(projectRoot);
+  const out2 = [];
+  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 += import_node_fs3.default.statSync(abs).size;
+      } catch {
+      }
+    }
+    return { files, bytes };
+  };
+  if (!tiers.includes("transcripts")) {
+    const projDir = import_node_path3.default.join(userClaude, "projects", key);
+    const m = measure(projDir, (p) => !p.includes(`${import_node_path3.default.sep}memory${import_node_path3.default.sep}`));
+    if (m.files > 0) {
+      out2.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(import_node_path3.default.join(userClaude, dir));
+    if (m.files > 0) out2.push({ label, ...m, reason });
+  }
+  return out2.filter((g) => g.bytes > 0);
+}
 function summarize(files) {
   const empty = { count: 0, bytes: 0 };
   const out2 = {
@@ -367,6 +449,86 @@ function summarize(files) {
   return out2;
 }
 
+// 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
 var import_node_fs4 = __toESM(require("fs"), 1);
 var import_node_path4 = __toESM(require("path"), 1);
@@ -735,7 +897,28 @@ function cmdPush(opts = {}) {
   if (skippedTracked.length > 0) {
     lines.push("", `${skippedTracked.length} project files skipped \u2014 git already tracks them.`);
   }
+  const excluded = describeExcluded(root, tiers);
+  if (excluded.length > 0) {
+    lines.push("", "Not included (by design):");
+    for (const g of excluded) {
+      lines.push(`  ${g.label.padEnd(22)} ${formatBytes(g.bytes).padStart(9)}  ${g.reason}`);
+    }
+  }
   if (!opts.dryRun) {
+    const store = new LocalStore(root);
+    const raw = store.readHandoff();
+    const v = raw ? validateHandoff(raw) : null;
+    if (!raw) {
+      lines.push(
+        "",
+        "No handoff written \u2014 the other machine will get your project knowledge but",
+        "not where you left off. Use `/context push` in Claude Code to include one."
+      );
+    } else if (v && !v.ok) {
+      lines.push("", "Handoff present but malformed (it will be ignored):", ...v.errors.map((e) => `  \xB7 ${e}`));
+    } else if (v?.ok && isStale(v.handoff, Date.now())) {
+      lines.push("", `Handoff is ${handoffAge(v.handoff)} \u2014 re-run \`/context push\` to refresh it.`);
+    }
     lines.push("", "Commit .contextsync/ to carry this context with the repo.");
   }
   return ok(lines);
@@ -765,12 +948,108 @@ function cmdPull(opts = {}) {
       "Re-run with --force to overwrite them."
     );
   }
-  const handoff = store.readHandoff();
-  if (handoff) {
-    lines.push("", `Handoff (${handoff.updatedAt}):`, `  goal: ${handoff.goal}`, `  next: ${handoff.nextStep}`);
+  const raw = store.readHandoff();
+  if (!raw) {
+    lines.push(
+      "",
+      "No handoff in this store \u2014 you have the project knowledge, but not where the",
+      "last session stopped. Run `/context push` (not bare `ctx push`) on the other",
+      "machine: only the model can write the handoff, since only it has the conversation."
+    );
+    return ok(lines);
+  }
+  const check = validateHandoff(raw);
+  if (!check.ok) {
+    lines.push("", "A handoff exists but is malformed and was ignored:", ...check.errors.map((e) => `  \xB7 ${e}`));
+    return ok(lines);
   }
+  lines.push("", ...formatHandoff(check.handoff));
   return ok(lines);
 }
+function cmdHandoff(opts = {}) {
+  const found = requireProject();
+  if ("code" in found) return found;
+  const { root } = found;
+  const store = new LocalStore(root);
+  if (opts.set !== void 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(opts.set);
+    } catch (e) {
+      return fail([`Could not parse handoff JSON: ${e.message}`]);
+    }
+    const check2 = validateHandoff(parsed);
+    if (!check2.ok) return fail(["Handoff is not valid:", ...check2.errors.map((e) => `  \xB7 ${e}`)]);
+    store.writeHandoff(check2.handoff);
+    return ok([`Handoff saved (${import_node_path6.default.relative(root, storeDir(root))}/handoff.json).`, "", ...formatHandoff(check2.handoff)]);
+  }
+  const raw = store.readHandoff();
+  if (!raw) {
+    return ok([
+      "No handoff yet.",
+      "",
+      "Write one with `/context push` in Claude Code, or pipe JSON:",
+      `  ctx handoff --set '{"goal":"\u2026","nextStep":"\u2026"}'`
+    ]);
+  }
+  const check = validateHandoff(raw);
+  if (!check.ok) return fail(["Handoff is malformed:", ...check.errors.map((e) => `  \xB7 ${e}`)]);
+  return ok(formatHandoff(check.handoff));
+}
+function cmdDoctor() {
+  const root = findProjectRoot();
+  if (!root) return fail(["Not inside a project. Run `ctx init` first."]);
+  const lines = [];
+  let problems = 0;
+  const check = (okFlag, label, detail) => {
+    if (!okFlag) problems++;
+    lines.push(`  ${okFlag ? "\u2713" : "\u2717"} ${label.padEnd(28)} ${detail}`);
+  };
+  const cfg = loadConfig(root);
+  check(Boolean(cfg), "store initialised", cfg ? `${import_node_path6.default.relative(root, storeDir(root))}/` : "missing \u2014 run `ctx init`");
+  if (!cfg) return { code: 1, lines: ["Setup check", "", ...lines] };
+  const store = new LocalStore(root);
+  const manifest = store.readManifest();
+  check(Boolean(manifest), "pushed at least once", manifest ? `${manifest.entries.length} files` : "never \u2014 run `ctx push`");
+  check(
+    import_node_fs7.default.existsSync(import_node_path6.default.join(root, SLASH_COMMAND_PATH)),
+    "/context slash command",
+    import_node_fs7.default.existsSync(import_node_path6.default.join(root, SLASH_COMMAND_PATH)) ? SLASH_COMMAND_PATH : `missing \u2014 run \`ctx init --force\``
+  );
+  const inGit = isGitRepo(root);
+  check(inGit, "git repository", inGit ? "yes \u2014 store travels with the repo" : "no \u2014 the store will not sync anywhere");
+  let storeIgnored = false;
+  if (inGit) {
+    try {
+      (0, import_node_child_process2.execFileSync)("git", ["-C", root, "check-ignore", "-q", ".contextsync/config.json"], { stdio: "ignore" });
+      storeIgnored = true;
+    } catch {
+      storeIgnored = false;
+    }
+  }
+  check(!storeIgnored, "store is committable", storeIgnored ? "IGNORED by git \u2014 it will never reach another machine" : "not gitignored");
+  const ctx = templateContext(root);
+  const memEntry = manifest?.entries.find((e) => e.storePath.startsWith("memory/"));
+  if (memEntry) {
+    const dest = resolveTemplate(memEntry.restoreTemplate, ctx);
+    const expectedDir = import_node_path6.default.join(userClaudeDir(), "projects", cwdKey(root), "memory");
+    check(dest.startsWith(expectedDir), "memory restore path", dest.startsWith(expectedDir) ? expectedDir : `WRONG \u2192 ${dest}`);
+  } else {
+    check(false, "memory captured", "none found \u2014 is ~/.claude/projects/<key>/memory populated?");
+  }
+  const raw = store.readHandoff();
+  if (!raw) {
+    check(false, "handoff", "absent \u2014 `/context push` writes it; resume will have nothing to say");
+  } else {
+    const v = validateHandoff(raw);
+    check(v.ok, "handoff", v.ok ? `valid, ${handoffAge(v.handoff)}` : v.errors[0]);
+    if (v.ok && manifest && isStale(v.handoff, Date.parse(manifest.updatedAt))) {
+      lines.push("    ! handoff is much older than the last push \u2014 re-run `/context push`");
+    }
+  }
+  const header = problems === 0 ? "Setup check \u2014 all good" : `Setup check \u2014 ${problems} problem${problems === 1 ? "" : "s"}`;
+  return { code: problems === 0 ? 0 : 1, lines: [header, "", ...lines] };
+}
 function cmdStatus() {
   const found = requireProject();
   if ("code" in found) return found;
@@ -779,10 +1058,14 @@ function cmdStatus() {
   const manifest = store.readManifest();
   const { tiers } = effectiveTiers(cfg);
   const { files, skippedTracked } = collect(root, cfg, tiers);
+  const rawHandoff = store.readHandoff();
+  const hv = rawHandoff ? validateHandoff(rawHandoff) : null;
+  const handoffLabel = !rawHandoff ? "none \u2014 run `/context push` to record where you left off" : hv?.ok ? `${handoffAge(hv.handoff)}` : "malformed (will be ignored)";
   const lines = [
     `Project  ${cfg.name}`,
     `Store    ${import_node_path6.default.relative(root, storeDir(root))}/`,
     `Tiers    ${cfg.tiers.join(", ")}`,
+    `Handoff  ${handoffLabel}`,
     `Remotes  ${Object.keys(cfg.remotes).length > 0 ? Object.keys(cfg.remotes).join(", ") : "none (local only)"}`,
     ""
   ];
@@ -824,13 +1107,16 @@ function cmdStatus() {
 }
 
 // src/cli.ts
+var VERSION = "0.2.0";
 var USAGE = `tricknowtech context-sync \u2014 carry a project's LLM context between machines
 
 Usage
   ctx init [--artifacts] [--force]   Create the store and install /context
   ctx push [--dry-run]               Collect context into the store
-  ctx pull [--force]                 Restore context from the store
-  ctx status                         Show what has changed since the last push
+  ctx pull [--force]                 Restore context, and show where you left off
+  ctx status                         What has changed since the last push
+  ctx handoff [--set '<json>']       Show or write the session handoff
+  ctx doctor                         Check the setup is actually wired correctly
 
 Options
   --artifacts       Include derived indexes (graphify-out/, etc.)
@@ -841,20 +1127,38 @@ Options
   -v, --version     Show version
 
 The store lives in .contextsync/ and is meant to be committed, so context
-travels with the code. Session transcripts are excluded from local mode.`;
+travels with the code. Session transcripts are excluded from local mode.
+
+Prefer \`/context push\` inside Claude Code over bare \`ctx push\`: only the
+model can write the handoff that lets the next machine resume the work.`;
 function parseArgs(argv) {
   const flags = /* @__PURE__ */ new Set();
+  const values = /* @__PURE__ */ new Map();
   let command = "";
-  for (const arg of argv) {
-    if (arg.startsWith("-")) flags.add(arg.replace(/^-+/, ""));
-    else if (!command) command = arg;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("-")) {
+      const name = arg.replace(/^-+/, "");
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        values.set(name.slice(0, eq), name.slice(eq + 1));
+        continue;
+      }
+      if (name === "set" && i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        values.set(name, argv[++i]);
+        continue;
+      }
+      flags.add(name);
+    } else if (!command) {
+      command = arg;
+    }
   }
-  return { command, flags };
+  return { command, flags, values };
 }
 function run(argv) {
-  const { command, flags } = parseArgs(argv);
+  const { command, flags, values } = parseArgs(argv);
   if (flags.has("h") || flags.has("help")) return { code: 0, lines: [USAGE] };
-  if (flags.has("v") || flags.has("version")) return { code: 0, lines: ["0.1.0"] };
+  if (flags.has("v") || flags.has("version")) return { code: 0, lines: [VERSION] };
   switch (command) {
     case "init":
       return cmdInit({ artifacts: flags.has("artifacts"), force: flags.has("force") });
@@ -862,6 +1166,10 @@ function run(argv) {
       return cmdPush({ allowSecrets: flags.has("allow-secrets"), dryRun: flags.has("dry-run") });
     case "pull":
       return cmdPull({ force: flags.has("force") });
+    case "handoff":
+      return cmdHandoff({ set: values.get("set") });
+    case "doctor":
+      return cmdDoctor();
     case "status":
     case "":
       return cmdStatus();