@jefuriiij/synthra 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -7,6 +7,47 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.1.18] — 2026-06-01
+
+### Fixed
+
+- **Stop hook on Linux/macOS no longer posts zero tokens to the dashboard.** The bash
+  `stop.sh` hook extracted `transcript_path` from the Claude Code Stop payload using a
+  greedy `sed` capture (`\(.*\)"`). Because the real payload has additional fields after
+  `transcript_path`, the capture grabbed those trailing fields and produced a
+  non-existent path string. The `-f` file check therefore always failed, totals were
+  never POSTed to `/log`, and the dashboard stayed stuck at 0 on every turn (GitHub
+  issue #1). Fixed by parsing with `jq -r '.transcript_path // empty'` and moving the
+  `command -v jq` guard above the parse so the hook exits cleanly when `jq` is absent.
+- **SessionStart/PreCompact primer hook (`prime.sh`) hardened the same way.** The
+  `/prime` response is `{"primer":"…","port":…}`, so the old greedy capture accidentally
+  injected trailing `","port":…` junk into the primer string. Because primer text can
+  contain inner quotes, a negated-class fix (`[^"]*`) would have truncated it at the
+  first quote — `jq -r '.primer // empty'` is the correct parse. Switched `printf '%b'`
+  to `printf '%s'` since `jq -r` already decodes JSON escapes.
+- Both fixes are **bash-only**. The Windows PowerShell hooks (`stop.ps1`, `prime.ps1`)
+  use `ConvertFrom-Json` and were already correct.
+
+---
+
+## [0.1.17] — 2026-05-29
+
+### Added
+
+- **`syn .` scaffolds an agent-onboarding CLAUDE.md on brand-new projects.**
+  When a project has no CLAUDE.md, Synthra now writes a lean skeleton —
+  `Build & test`, `Conventions`, `Key decisions`, `Gotchas` (with TODO
+  prompts) — *above* its managed policy block, instead of a bare policy
+  block. This is the durable "why/how" layer the graph can't infer; the
+  graph still owns "what/where." Fill it in, or run `/init` to auto-draft.
+  The skeleton is written **once** and lives outside the
+  `<!-- synthra-policy -->` markers, so re-running `syn .` (which
+  refreshes the policy block) never clobbers what you've written.
+  Projects that already have a CLAUDE.md are untouched — no skeleton is
+  injected.
+
+---
+
 ## [0.1.16] — 2026-05-29
 
 ### Changed

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.1.16",
+      version: "0.1.18",
       publishConfig: {
         access: "public"
       },
@@ -1466,12 +1466,18 @@ if [ ! -f "$PORT_FILE" ]; then exit 0; fi
 PORT=$(cat "$PORT_FILE" 2>/dev/null | tr -d '[:space:]')
 if [ -z "$PORT" ]; then exit 0; fi
 
+# Parse the primer with jq, not sed. Primer text legitimately contains quotes, so a
+# negated-class capture ([^"]*) would truncate it at the first inner quote, while the
+# old greedy capture (.*") over-ran into the trailing "port" field and injected junk.
+# jq -r also decodes JSON escapes, so we print with %s (not %b). No jq \u2192 no primer.
+if ! command -v jq >/dev/null 2>&1; then exit 0; fi
+
 PRIMER=$(curl -sS --max-time 3 "http://127.0.0.1:$PORT/prime" 2>/dev/null \\
-  | sed -n 's/.*"primer"[[:space:]]*:[[:space:]]*"\\(.*\\)".*/\\1/p' \\
+  | jq -r '.primer // empty' 2>/dev/null \\
   | head -c 8000)
 
 if [ -n "$PRIMER" ]; then
-  printf '%b\\n' "$PRIMER"
+  printf '%s\\n' "$PRIMER"
 fi
 exit 0
 `;
@@ -1564,7 +1570,13 @@ set +e\r
 INPUT=$(cat 2>/dev/null)\r
 if [ -z "$INPUT" ]; then exit 0; fi\r
 \r
-TRANSCRIPT=$(printf '%s' "$INPUT" | sed -n 's/.*"transcript_path"[[:space:]]*:[[:space:]]*"\\(.*\\)".*/\\1/p')\r
+# jq is required for the parsing below \u2014 bail early (silent no-op) if it's absent.\r
+if ! command -v jq >/dev/null 2>&1; then exit 0; fi\r
+\r
+# Extract transcript_path with jq, not sed. A greedy sed capture (\\(.*\\)") grabs the\r
+# trailing JSON fields after transcript_path and yields a path that doesn't exist, so\r
+# the -f check below always failed and totals were never POSTed to /log. (issue #1)\r
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)\r
 if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then exit 0; fi\r
 \r
 PORT_FILE="$PWD/.synthra-graph/mcp_port"\r
@@ -1572,8 +1584,6 @@ if [ ! -f "$PORT_FILE" ]; then exit 0; fi\r
 PORT=$(cat "$PORT_FILE" 2>/dev/null | tr -d '[:space:]')\r
 if [ -z "$PORT" ]; then exit 0; fi\r
 \r
-if ! command -v jq >/dev/null 2>&1; then exit 0; fi\r
-\r
 OFFSET_FILE="\${TRANSCRIPT}.stopoffset"\r
 START_OFFSET=0\r
 if [ -f "$OFFSET_FILE" ]; then\r
@@ -3198,9 +3208,11 @@ async function readSymbolIndex(path) {
 
 // src/cli/bootstrap.ts
 import { mkdir as mkdir5, readFile as readFile10, stat as stat2, writeFile as writeFile5 } from "fs/promises";
+import { basename as basename4 } from "path";
 
 // src/hooks/claude-md.ts
 import { readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
+import { basename as basename3, dirname as dirname6 } from "path";
 var POLICY_VERSION = 3;
 var POLICY_BEGIN = `<!-- synthra-policy v${POLICY_VERSION} BEGIN -->`;
 var POLICY_END = `<!-- synthra-policy v${POLICY_VERSION} END -->`;
@@ -3301,7 +3313,39 @@ function policyBlock() {
     POLICY_END
   ].join("\n");
 }
-async function patchClaudeMd(path) {
+function onboardingSkeleton(projectName) {
+  return [
+    `# ${projectName}`,
+    "",
+    "> Onboarding notes for AI coding agents. Synthra's graph already knows the",
+    "> code's *structure* (files, symbols, imports) \u2014 this file is for what the",
+    "> graph can't infer: how to run the project, its conventions, and the",
+    "> decisions behind them. Keep it lean and current; delete prompts you don't need.",
+    "",
+    "## Build & test",
+    "",
+    "- TODO: install deps / build",
+    "- TODO: run tests / lint / typecheck",
+    "- TODO: run the app locally",
+    "",
+    "## Conventions",
+    "",
+    "- TODO: code style, naming, file layout the agent should follow",
+    "",
+    "## Key decisions",
+    "",
+    '- TODO: non-obvious choices and *why* ("we use X not Y because \u2026")',
+    "",
+    "## Gotchas",
+    "",
+    `- TODO: traps, footguns, "don't touch X without Y"`,
+    "",
+    "_Tip: run `/init` in Claude Code to auto-draft the sections above, then trim",
+    "to the durable bits. Synthra manages its own block below \u2014 leave it._",
+    ""
+  ].join("\n");
+}
+async function patchClaudeMd(path, projectName) {
   let existing;
   try {
     existing = await readFile9(path, "utf8");
@@ -3310,7 +3354,8 @@ async function patchClaudeMd(path) {
   }
   const block = policyBlock();
   if (existing === null) {
-    await writeFile4(path, block + "\n", "utf8");
+    const name = projectName || basename3(dirname6(path)) || "this project";
+    await writeFile4(path, onboardingSkeleton(name) + "\n" + block + "\n", "utf8");
     return { created: true, updated: false, skipped: false };
   }
   const stripped = existing.replace(ANY_BLOCK_RE, "");
@@ -3367,7 +3412,7 @@ async function bootstrap(paths) {
   const contextCreated = await ensureDir(paths.contextDir);
   const gitignoreUpdated = await patchGitignore(paths.gitignore);
   const claudeMdExistedBefore = await exists(paths.claudeMd);
-  const patch = await patchClaudeMd(paths.claudeMd);
+  const patch = await patchClaudeMd(paths.claudeMd, basename4(paths.projectRoot));
   return {
     graphCreated,
     contextCreated,
@@ -3420,8 +3465,12 @@ async function scanProject(projectRootRaw, opts = {}) {
     if (boot.graphCreated) log.info("  created .synthra-graph/");
     if (boot.contextCreated) log.info("  created .synthra/");
     if (boot.gitignoreUpdated) log.info("  updated .gitignore");
-    if (boot.claudeMdCreated) log.info("  created CLAUDE.md");
-    else if (boot.claudeMdUpdated) log.info("  updated CLAUDE.md");
+    if (boot.claudeMdCreated) {
+      log.info("  created CLAUDE.md \u2014 onboarding skeleton for the agent");
+      log.info("    \u21B3 fill in Build / Conventions / Decisions (or run /init in Claude to auto-draft)");
+    } else if (boot.claudeMdUpdated) {
+      log.info("  updated CLAUDE.md");
+    }
   }
   const walked = [];
   for await (const file of walk(projectRoot)) walked.push(file);
@@ -3721,7 +3770,7 @@ function resolveBranchPaths(contextDir, branch, isDefault) {
 
 // src/memory/context-md.ts
 import { mkdir as mkdir6, readFile as readFile12, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname6 } from "path";
+import { dirname as dirname7 } from "path";
 var MAX_BULLETS = 3;
 function deriveContextMd(entries, branch) {
   const tasks = entries.filter((e) => e.type === "task").reverse();
@@ -3764,13 +3813,13 @@ function formatContextMd(ctx) {
   return lines.join("\n");
 }
 async function writeContextMd(path, ctx) {
-  await mkdir6(dirname6(path), { recursive: true });
+  await mkdir6(dirname7(path), { recursive: true });
   await writeFile6(path, formatContextMd(ctx), "utf8");
 }
 
 // src/memory/context-store.ts
 import { mkdir as mkdir7, readFile as readFile13, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 var SCHEMA_VERSION2 = 1;
 async function readEntries(path) {
   try {
@@ -3782,7 +3831,7 @@ async function readEntries(path) {
   }
 }
 async function writeEntries(path, entries) {
-  await mkdir7(dirname7(path), { recursive: true });
+  await mkdir7(dirname8(path), { recursive: true });
   const store = { schema_version: SCHEMA_VERSION2, entries };
   await writeFile7(path, JSON.stringify(store, null, 2) + "\n", "utf8");
 }
@@ -4477,7 +4526,7 @@ async function handleContextUpdate(req, ctx) {
 
 // src/server/routes/gate.ts
 import { appendFile as appendFile2, mkdir as mkdir8 } from "fs/promises";
-import { dirname as dirname8 } from "path";
+import { dirname as dirname9 } from "path";
 var BLOCKABLE_TOOLS = /* @__PURE__ */ new Set(["Grep", "Glob"]);
 var RECENT_ACTIVITY_WINDOW_MS = 5 * 60 * 1e3;
 function extractQuery(toolName, input) {
@@ -4507,7 +4556,7 @@ function recentlyTouchedMatchesQuery(recentPaths, queryTokens) {
 }
 async function logDecision(ctx, toolName, query, decision, reason) {
   try {
-    await mkdir8(dirname8(ctx.paths.gateLog), { recursive: true });
+    await mkdir8(dirname9(ctx.paths.gateLog), { recursive: true });
     const entry = {
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       tool: toolName,
@@ -4564,14 +4613,14 @@ async function handleGate(req, ctx) {
 
 // src/server/routes/log.ts
 import { appendFile as appendFile3, mkdir as mkdir9 } from "fs/promises";
-import { dirname as dirname9 } from "path";
+import { dirname as dirname10 } from "path";
 async function handleLog(entry, ctx) {
   if (!entry || typeof entry.input_tokens !== "number" || typeof entry.output_tokens !== "number") {
     throw new Error("log: input_tokens and output_tokens (number) are required");
   }
   const written_at = (/* @__PURE__ */ new Date()).toISOString();
   const record = { ...entry, written_at };
-  await mkdir9(dirname9(ctx.paths.tokenLog), { recursive: true });
+  await mkdir9(dirname10(ctx.paths.tokenLog), { recursive: true });
   await appendFile3(ctx.paths.tokenLog, JSON.stringify(record) + "\n", "utf8");
   return { ok: true, written_at };
 }