@jefuriiij/synthra 0.1.4 → 0.1.6

package/dist/server/index.js

@@ -1443,7 +1443,7 @@ import { mkdir as mkdir3, readFile as readFile7, stat as stat2, writeFile as wri
 
 // src/hooks/claude-md.ts
 import { readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-var POLICY_VERSION = 1;
+var POLICY_VERSION = 2;
 var POLICY_BEGIN = `<!-- synthra-policy v${POLICY_VERSION} BEGIN -->`;
 var POLICY_END = `<!-- synthra-policy v${POLICY_VERSION} END -->`;
 var ANY_BLOCK_RE = /<!--\s*synthra-policy\s+v\d+\s+BEGIN\s*-->[\s\S]*?<!--\s*synthra-policy\s+v\d+\s+END\s*-->\s*/g;
@@ -1452,33 +1452,84 @@ function policyBlock() {
     POLICY_BEGIN,
     "## Synthra context policy",
     "",
-    "Synthra has pre-loaded a structured context pack into this session and",
-    "exposes the project's code graph through three MCP tools. **Prefer these",
-    "tools over Grep / Glob** \u2014 they are faster, cheaper, and already filtered",
+    "Synthra has pre-loaded structured context into this session and exposes",
+    "the project's code graph through MCP tools. **Prefer these tools over",
+    "Grep / Glob / Read** \u2014 they are faster, cheaper, and already filtered",
     "to relevant files.",
     "",
+    "> **Tool namespace.** Synthra's MCP tools are exposed as",
+    "> `mcp__synthra__graph_continue`, `mcp__synthra__graph_read`, and",
+    "> `mcp__synthra__graph_register_edit`. Below they are referred to by",
+    "> their short names (`graph_continue` etc.) for readability \u2014 use the",
+    "> full namespaced form when actually invoking them.",
+    "",
     "### Tools",
     "",
-    "- **`graph_continue(query)`** \u2014 your default first move when you need",
-    "  project context. Returns signatures + top function bodies + linked test",
-    '  files, with a `confidence` label. If `confidence === "high"`, **stop**:',
-    "  do not call Grep/Glob for the same query.",
-    '- **`graph_read(target)`** \u2014 fetch source for a specific `"file/path.ts"`',
-    '  or `"file/path.ts::SymbolName"`. Use this once you know what you want.',
+    "- **`graph_continue(query)`** \u2014 returns a `Confidence` label, the list",
+    "  of relevant `Files`, and signatures + top function bodies for those",
+    "  files. Your default first move when you need project context.",
+    "- **`graph_read(target)`** \u2014 fetch source. Prefer the",
+    '  `"file/path.ts::SymbolName"` form over a bare file path \u2014 reading one',
+    "  symbol is ~50 tokens, reading a whole file is thousands.",
     "- **`graph_register_edit(files)`** \u2014 after you edit files, call this so",
-    "  Synthra ranks them higher and avoids surfacing stale snapshots.",
+    "  subsequent turns weight your changes and avoid stale snapshots.",
+    "",
+    "### When to call `graph_continue` \u2014 and when to skip",
+    "",
+    "**Call `graph_continue` only when you do NOT already know the relevant",
+    "files.**",
+    "",
+    "Call it when:",
+    "- This is the first message of a new task or conversation",
+    "- The task shifts to a different area of the codebase",
+    "- You need files you haven't seen yet in this session",
+    "",
+    "**Skip `graph_continue` when:**",
+    "- You already identified the relevant files earlier in this conversation",
+    "- You are doing follow-up work on files already read (verify, refactor,",
+    "  test, docs, cleanup, commit)",
+    "- The task is pure text (commit message, explanation, summary)",
+    "",
+    'If skipping, go directly to `graph_read("file.ts::symbol")` on what',
+    "you already know.",
+    "",
+    "### Confidence caps",
+    "",
+    "When `graph_continue` returns:",
+    "",
+    "- **`Confidence: high`** \u2192 Stop. Do NOT Grep, Glob, or further explore",
+    "  for this query. The graph already has it.",
+    "- **`Confidence: medium`** \u2192 Read the listed `Files` directly via",
+    '  `graph_read("file::symbol")` *before* trying Grep. The graph has',
+    "  narrowed the search space \u2014 use it, don't bypass it.",
+    "- **`Confidence: low`** \u2192 You may use Grep / Glob, but the PreToolUse",
+    "  hook may still block redundant calls.",
+    "",
+    "### Reading code",
+    "",
+    "- **Always use `file::symbol` notation** with `graph_read`. Whole-file",
+    "  reads should be rare \u2014 only when you genuinely need the full file.",
+    "- If `graph_continue`'s `Files` list contains a `::` entry, pass it",
+    "  verbatim to `graph_read`.",
     "",
-    "### Rules",
+    "### Don'ts",
     "",
-    "1. Call `graph_continue` **before** Grep / Glob for any question about",
-    "   project code. Grep / Glob calls for the same query may be blocked at",
-    "   the hook layer when the graph already has a confident answer.",
-    '2. When `graph_continue` returns `confidence: "high"`, treat the pack as',
-    "   authoritative \u2014 don't second-guess it with a Grep.",
-    "3. Use `graph_read` instead of `Read` when you only need a specific symbol",
-    "   from a file (you get less noise + line numbers).",
-    "4. After editing files, call `graph_register_edit(files)` so subsequent",
-    "   turns weight your changes correctly.",
+    "- Don't Grep / Glob before calling `graph_continue` when required \u2014 the",
+    "  PreToolUse hook may block it.",
+    "- Don't call `graph_continue` more than once per turn.",
+    "- Don't read whole files when a symbol-level read would suffice.",
+    "",
+    "### Session-end resume note",
+    "",
+    `When the user signals they're done (e.g. "bye", "wrap up", "done"),`,
+    "proactively update `.synthra/CONTEXT.md` with:",
+    "",
+    "- **Current Task**: one sentence on what was being worked on",
+    "- **Key Decisions**: bullet list, max 3 items",
+    "- **Next Steps**: bullet list, max 3 items",
+    "",
+    "Keep `CONTEXT.md` under 20 lines total. Don't summarise the conversation",
+    "\u2014 write only what's needed to resume next session.",
     "",
     "_This block is managed by Synthra. Edits inside the BEGIN/END markers",
     "are overwritten on every `syn .` run._",
@@ -1509,8 +1560,16 @@ async function patchClaudeMd(path) {
 }
 
 // src/cli/bootstrap.ts
-var GITIGNORE_MARKER = "# added by synthra";
-var GITIGNORE_ENTRY = ".synthra-graph/";
+var GITIGNORE_ENTRIES = [
+  {
+    comment: "added by synthra (heavy generated state \u2014 gitignored by design)",
+    entry: ".synthra-graph/"
+  },
+  {
+    comment: "added by synthra \u2014 MCP registration. Remove this line if you want to share the synthra MCP entry with teammates via committed .mcp.json",
+    entry: ".mcp.json"
+  }
+];
 async function exists(path) {
   try {
     await stat2(path);
@@ -1530,11 +1589,12 @@ async function patchGitignore(path) {
     existing = await readFile7(path, "utf8");
   } catch {
   }
-  const lines = existing.split(/\r?\n/);
-  if (lines.some((l) => l.trim() === GITIGNORE_ENTRY)) return false;
-  const appendix = (existing.length === 0 || existing.endsWith("\n") ? "" : "\n") + (existing.length ? "\n" : "") + `${GITIGNORE_MARKER}
-${GITIGNORE_ENTRY}
-`;
+  const trimmed = new Set(existing.split(/\r?\n/).map((l) => l.trim()));
+  const missing = GITIGNORE_ENTRIES.filter((e) => !trimmed.has(e.entry));
+  if (missing.length === 0) return false;
+  const block = missing.map((m) => `# ${m.comment}
+${m.entry}`).join("\n") + "\n";
+  const appendix = (existing.length === 0 || existing.endsWith("\n") ? "" : "\n") + (existing.length ? "\n" : "") + block;
   await writeFile3(path, existing + appendix, "utf8");
   return true;
 }