npm - @jefuriiij/synthra - Versions diffs - 0.1.4 → 0.1.6 - Mend

@jefuriiij/synthra 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/cli/index.js +93 -33
package/dist/cli/index.js.map +1 -1
package/dist/dashboard/index.js +1 -1
package/dist/dashboard/index.js.map +1 -1
package/dist/server/index.js +88 -28
package/dist/server/index.js.map +1 -1
package/package.json +1 -1

package/dist/cli/index.js CHANGED Viewed

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.1.4",
+      version: "0.1.6",
       publishConfig: {
         access: "public"
       },
@@ -864,7 +864,7 @@ var public_default = `<!doctype html>
   <!-- ============ Footer ============ -->
   <footer class="foot">
-    <div>Synth<em>ra</em> \xB7 v0.1.4</div>
+    <div>Synth<em>ra</em> \xB7 v0.1.6</div>
     <div>Cost figures approximate \xB7 @jefuriiij</div>
   </footer>
@@ -3031,7 +3031,7 @@ import { mkdir as mkdir5, readFile as readFile10, stat as stat2, writeFile as wr
 // src/hooks/claude-md.ts
 import { readFile as readFile9, writeFile as writeFile4 } 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;
@@ -3040,33 +3040,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._",
@@ -3097,8 +3148,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);
@@ -3118,11 +3177,12 @@ async function patchGitignore(path) {
     existing = await readFile10(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 writeFile5(path, existing + appendix, "utf8");
   return true;
 }
@@ -4744,10 +4804,10 @@ function runClaude(bin, args, cwd, stdio = "pipe") {
 }
 async function registerMcp(bin, mcpPort, cwd) {
   const url = `http://127.0.0.1:${mcpPort}/mcp`;
-  await runClaude(bin, ["mcp", "remove", MCP_NAME, "--scope", "local"], cwd).catch(() => void 0);
+  await runClaude(bin, ["mcp", "remove", MCP_NAME, "--scope", "project"], cwd).catch(() => void 0);
   const reg = await runClaude(
     bin,
-    ["mcp", "add", MCP_NAME, "--transport", "http", "--scope", "local", url],
+    ["mcp", "add", MCP_NAME, "--transport", "http", "--scope", "project", url],
     cwd
   );
   if (reg.code !== 0) {
@@ -4759,7 +4819,7 @@ async function registerMcp(bin, mcpPort, cwd) {
   return true;
 }
 async function unregisterMcp(bin, cwd) {
-  const r = await runClaude(bin, ["mcp", "remove", MCP_NAME, "--scope", "local"], cwd);
+  const r = await runClaude(bin, ["mcp", "remove", MCP_NAME, "--scope", "project"], cwd);
   if (r.code === 0) log.debug("unregistered MCP server");
 }
 async function spawnClaude(bin, opts) {