@getpawl/setup 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @fixhbone/agentmap-setup
+
+One-shot setup for [AgentMap](https://github.com/0xfishbone/agentMap) + Claude Code hooks. Connects any repo to your AgentMap project so spec context is automatically synced during Claude Code sessions.
+
+## Usage
+
+```sh
+npx @fixhbone/agentmap-setup <PROJECT_KEY>
+```
+
+Get your `<PROJECT_KEY>` from the AgentMap web dashboard under **Settings > Setup**.
+
+## What it does
+
+1. Creates `.agentmap/.env` with API credentials
+2. Generates `.agentmap/sync.sh` — pull context + push diffs
+3. Configures `.claude/settings.json` with three lifecycle hooks:
+   - **SessionStart** — pulls latest project context
+   - **PostToolUse** (Write/Edit) — tracks modified files
+   - **Stop** — pushes session diff to AgentMap
+4. Adds sensitive paths to `.gitignore`
+
+## Requirements
+
+- Node.js >= 18
+- [Claude Code](https://claude.ai/claude-code) CLI installed
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,762 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/index.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function main() {
+  const arg = process.argv[2];
+  if (!arg) {
+    printUsage();
+    process.exit(0);
+  }
+  if (arg === "init") {
+    const key = process.argv[3];
+    pawlInit(key);
+  } else {
+    legacySetup(arg);
+  }
+}
+function printUsage() {
+  console.log(`
+Usage:
+  pawl init [PROJECT_KEY]   Initialize Pawl in this repo
+  pawl-setup <PROJECT_KEY>  Legacy setup (still supported)
+
+Get your project key at: https://pawl.dev/settings
+`);
+}
+function legacySetup(encoded) {
+  let config;
+  try {
+    const decoded = Buffer.from(encoded, "base64").toString("utf-8");
+    config = JSON.parse(decoded);
+  } catch {
+    console.error("Error: Invalid project key \u2014 could not decode.");
+    process.exit(1);
+  }
+  if (!config.apiKey || !config.projectId || !config.apiUrl) {
+    console.error(
+      "Error: Project key is missing required fields (apiKey, projectId, apiUrl)."
+    );
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  writeEnvFile(cwd, config);
+  writeSyncScript(cwd, config);
+  copyParserScript(cwd);
+  mergeClaudeSettings(cwd);
+  writeClaudeMd(cwd);
+  updateGitignore(cwd);
+  console.log("\n  Pawl setup complete!\n");
+  console.log(`  Project: ${config.apiUrl}/projects/${config.projectId}`);
+  console.log("  Created: .agentmap/.env, .agentmap/sync.sh, .agentmap/parse-cc-session.js");
+  console.log("  Updated: .claude/settings.json, CLAUDE.md, .gitignore\n");
+}
+function pawlInit(key) {
+  const cwd = process.cwd();
+  const detected = detectAgents(cwd);
+  migrateIfNeeded(cwd, detected.hasAgentMapDir);
+  (0, import_node_fs.mkdirSync)((0, import_node_path.join)(cwd, ".pawl"), { recursive: true });
+  if (key) {
+    let config;
+    try {
+      const decoded = Buffer.from(key, "base64").toString("utf-8");
+      config = JSON.parse(decoded);
+    } catch {
+      console.error("Error: Invalid project key \u2014 could not decode.");
+      process.exit(1);
+    }
+    writePawlEnvFile(cwd, config);
+  }
+  writePawlSyncScript(cwd);
+  copyParserScript(cwd, ".pawl");
+  if (detected.hasCC) {
+    mergeClaudeSettings(cwd, ".pawl");
+  }
+  if (detected.hasGemini) {
+    mergeGeminiSettings(cwd);
+  }
+  writeGitHook(cwd, detected.hasGitDir);
+  writePawlClaudeMd(cwd);
+  writeAgentsMd(cwd);
+  updateGitignore(cwd);
+  printSummary(detected, !!key);
+}
+function detectAgents(cwd) {
+  return {
+    hasCC: (0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".claude")),
+    hasGemini: (0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".gemini")),
+    hasAgentMapDir: (0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".agentmap")),
+    hasGitDir: (0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".git"))
+  };
+}
+function migrateIfNeeded(cwd, hasAgentMapDir) {
+  if (!hasAgentMapDir) return;
+  if ((0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".pawl"))) return;
+  console.log("  Migrating .agentmap/ \u2192 .pawl/...");
+  (0, import_node_fs.mkdirSync)((0, import_node_path.join)(cwd, ".pawl"), { recursive: true });
+  const filesToCopy = [".env", "sync.sh", "parse-cc-session.js", "context.md", "progress.md"];
+  for (const file of filesToCopy) {
+    const src = (0, import_node_path.join)(cwd, ".agentmap", file);
+    if ((0, import_node_fs.existsSync)(src)) {
+      (0, import_node_fs.copyFileSync)(src, (0, import_node_path.join)(cwd, ".pawl", file));
+    }
+  }
+  const specsDir = (0, import_node_path.join)(cwd, ".agentmap", "specs");
+  if ((0, import_node_fs.existsSync)(specsDir)) {
+    (0, import_node_fs.cpSync)(specsDir, (0, import_node_path.join)(cwd, ".pawl", "specs"), { recursive: true });
+  }
+  const envPath = (0, import_node_path.join)(cwd, ".pawl", ".env");
+  if ((0, import_node_fs.existsSync)(envPath)) {
+    let envContent = (0, import_node_fs.readFileSync)(envPath, "utf-8");
+    envContent = envContent.replace(/AGENTMAP_/g, "PAWL_");
+    (0, import_node_fs.writeFileSync)(envPath, envContent, "utf-8");
+  }
+  console.log("  .agentmap/ preserved \u2014 safe to delete manually when ready.\n");
+}
+function writePawlEnvFile(cwd, config) {
+  const content = [
+    `PAWL_API_KEY=${config.apiKey}`,
+    `PAWL_PROJECT_ID=${config.projectId}`,
+    `PAWL_API_URL=${config.apiUrl}`,
+    ""
+  ].join("\n");
+  (0, import_node_fs.writeFileSync)((0, import_node_path.join)(cwd, ".pawl", ".env"), content, "utf-8");
+}
+function writePawlSyncScript(cwd) {
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Pawl sync script \u2014 generated by pawl init
+# Do not edit manually; re-run pawl init to update.
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Source env only if it exists (pawl init without key skips .env)
+if [ -f "$SCRIPT_DIR/.env" ]; then
+  source "$SCRIPT_DIR/.env"
+fi
+
+BASE_URL="\${PAWL_API_URL:-}/api/projects/\${PAWL_PROJECT_ID:-}"
+
+# \u2500\u2500 pull mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+pull() {
+  if [ -z "\${PAWL_API_KEY:-}" ]; then
+    echo "Warning: PAWL_API_KEY not set \u2014 sync disabled" >&2
+    if [ -f "$SCRIPT_DIR/context.md" ]; then
+      cat "$SCRIPT_DIR/context.md"
+    fi
+    return 0
+  fi
+
+  # Recovery: if tracked-files exist from a previous incomplete session, push first
+  if [ -f "$SCRIPT_DIR/.tracked-files" ]; then
+    push >/dev/null 2>&1
+  fi
+
+  # Ensure specs directory exists
+  mkdir -p "$SCRIPT_DIR/specs"
+
+  # \u2500\u2500 Level 1: New file-based endpoint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  RESPONSE=$(curl -sf -X GET "$BASE_URL/context/files" \\
+    -H "Authorization: Bearer $PAWL_API_KEY" \\
+    -H "Accept: application/json" 2>/dev/null) || true
+
+  if [ -n "$RESPONSE" ] && echo "$RESPONSE" | jq -e '.files' >/dev/null 2>&1; then
+    echo "$RESPONSE" | jq -r '.files[] | @base64' | while read -r encoded; do
+      FILE_PATH=$(echo "$encoded" | base64 -d | jq -r '.path')
+      FILE_CONTENT=$(echo "$encoded" | base64 -d | jq -r '.content')
+
+      # Ensure parent directory exists
+      mkdir -p "$SCRIPT_DIR/$(dirname "$FILE_PATH")"
+      echo "$FILE_CONTENT" > "$SCRIPT_DIR/$FILE_PATH"
+    done
+
+    # Output context.md to stdout (for SessionStart hook)
+    if [ -f "$SCRIPT_DIR/context.md" ]; then
+      cat "$SCRIPT_DIR/context.md"
+    fi
+    return 0
+  fi
+
+  # \u2500\u2500 Level 2: Legacy monolithic endpoint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  RESPONSE=$(curl -sf -X GET "$BASE_URL/context" \\
+    -H "Authorization: Bearer $PAWL_API_KEY" \\
+    -H "Accept: application/json" 2>/dev/null) || true
+
+  if [ -n "$RESPONSE" ] && echo "$RESPONSE" | jq -e '.formatted_context' >/dev/null 2>&1; then
+    echo "$RESPONSE" | jq -r '.formatted_context // empty' > "$SCRIPT_DIR/context.md"
+    cat "$SCRIPT_DIR/context.md"
+    return 0
+  fi
+
+  # \u2500\u2500 Level 3: Cached file fallback \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  if [ -f "$SCRIPT_DIR/context.md" ]; then
+    echo "# (cached \u2014 API unreachable)" | cat - "$SCRIPT_DIR/context.md"
+    return 0
+  fi
+
+  echo "Warning: Pawl context unavailable" >&2
+  return 1
+}
+
+# \u2500\u2500 push mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+push() {
+  if [ -z "\${PAWL_API_KEY:-}" ]; then
+    return 0
+  fi
+
+  LAST_SHA=""
+  if [ -f "$SCRIPT_DIR/.last-sync-sha" ]; then
+    LAST_SHA=$(cat "$SCRIPT_DIR/.last-sync-sha")
+  fi
+
+  CURRENT_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+  # Compute diff
+  if [ -n "$LAST_SHA" ]; then
+    DIFF=$(git diff "$LAST_SHA"..HEAD 2>/dev/null || echo "")
+  else
+    DIFF=$(git diff HEAD~1..HEAD 2>/dev/null || echo "")
+  fi
+
+  # Collect tracked files (dedup)
+  FILES_CHANGED="[]"
+  if [ -f "$SCRIPT_DIR/.tracked-files" ]; then
+    FILES_CHANGED=$(sort -u "$SCRIPT_DIR/.tracked-files" | jq -R . | jq -s .)
+  fi
+
+  # Commit info
+  COMMIT_MSG=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "")
+
+  # Session ID from Claude Code (if available)
+  SESSION_ID="\${CLAUDE_SESSION_ID:-}"
+
+  # Repo root for CC session lookup
+  REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+  # Parse CC session data locally (if node + parser available)
+  CC_SESSION="{}"
+  if command -v node &> /dev/null; then
+    PARSER="$SCRIPT_DIR/parse-cc-session.js"
+    if [ -f "$PARSER" ]; then
+      CC_SESSION=$(node "$PARSER" "$REPO_PATH" 2>/dev/null || echo "{}")
+    fi
+  fi
+
+  # Extract cc_tasks from parser output
+  CC_TASKS=$(echo "$CC_SESSION" | jq -c '.tasks // []')
+
+  PAYLOAD=$(jq -n \\
+    --arg diff "$DIFF" \\
+    --arg branch "$BRANCH" \\
+    --arg commit_sha "$CURRENT_SHA" \\
+    --arg commit_message "$COMMIT_MSG" \\
+    --arg session_id "$SESSION_ID" \\
+    --arg last_sync_sha "$LAST_SHA" \\
+    --arg repo_path "$REPO_PATH" \\
+    --argjson files_changed "$FILES_CHANGED" \\
+    --argjson cc_session "$CC_SESSION" \\
+    --argjson cc_tasks "$CC_TASKS" \\
+    '{
+      diff: $diff,
+      branch: $branch,
+      commit_sha: $commit_sha,
+      commit_message: $commit_message,
+      session_id: $session_id,
+      last_sync_sha: $last_sync_sha,
+      repo_path: $repo_path,
+      files_changed: $files_changed,
+      cc_session: $cc_session,
+      cc_tasks: $cc_tasks
+    }')
+
+  RESPONSE=$(curl -sf -X POST "$BASE_URL/sync" \\
+    -H "Authorization: Bearer $PAWL_API_KEY" \\
+    -H "Content-Type: application/json" \\
+    -d "$PAYLOAD")
+
+  echo "$RESPONSE" | jq .
+
+  # Update last sync SHA
+  echo "$CURRENT_SHA" > "$SCRIPT_DIR/.last-sync-sha"
+
+  # Cleanup tracked files
+  rm -f "$SCRIPT_DIR/.tracked-files"
+}
+
+# \u2500\u2500 dispatch \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+case "\${1:-}" in
+  pull) pull ;;
+  push) push ;;
+  *)
+    echo "Usage: sync.sh [pull|push]"
+    exit 1
+    ;;
+esac
+`;
+  const scriptPath = (0, import_node_path.join)(cwd, ".pawl", "sync.sh");
+  (0, import_node_fs.writeFileSync)(scriptPath, script, "utf-8");
+  (0, import_node_fs.chmodSync)(scriptPath, 493);
+}
+function mergeGeminiSettings(cwd) {
+  const geminiDir = (0, import_node_path.join)(cwd, ".gemini");
+  (0, import_node_fs.mkdirSync)(geminiDir, { recursive: true });
+  const settingsPath = (0, import_node_path.join)(geminiDir, "settings.json");
+  let settings = {};
+  if ((0, import_node_fs.existsSync)(settingsPath)) {
+    try {
+      settings = JSON.parse((0, import_node_fs.readFileSync)(settingsPath, "utf-8"));
+    } catch {
+    }
+  }
+  const hooksToInstall = {
+    SessionStart: { command: ".pawl/sync.sh pull" },
+    AfterAgentLoop: { command: ".pawl/sync.sh push" }
+  };
+  const hooksObj = settings.hooks || {};
+  for (const [event, entry] of Object.entries(hooksToInstall)) {
+    const existing = hooksObj[event] || [];
+    const alreadyExists = existing.some((e) => e.command === entry.command);
+    if (!alreadyExists) {
+      existing.push(entry);
+    }
+    hooksObj[event] = existing;
+  }
+  settings.hooks = hooksObj;
+  (0, import_node_fs.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+function writeGitHook(cwd, hasGitDir) {
+  if (!hasGitDir) return;
+  const hooksDir = (0, import_node_path.join)(cwd, ".git", "hooks");
+  (0, import_node_fs.mkdirSync)(hooksDir, { recursive: true });
+  const hookPath = (0, import_node_path.join)(hooksDir, "post-commit");
+  const hookBlock = `#!/bin/sh
+# Pawl sync hook \u2014 fires after every commit
+# Provides universal sync fallback for agents without lifecycle hooks (Codex, etc.)
+if [ -f ".pawl/sync.sh" ]; then
+  .pawl/sync.sh push
+fi`;
+  if (!(0, import_node_fs.existsSync)(hookPath)) {
+    (0, import_node_fs.writeFileSync)(hookPath, hookBlock + "\n", "utf-8");
+    (0, import_node_fs.chmodSync)(hookPath, 493);
+    return;
+  }
+  const content = (0, import_node_fs.readFileSync)(hookPath, "utf-8");
+  if (content.includes("Pawl sync hook")) {
+    return;
+  }
+  (0, import_node_fs.writeFileSync)(hookPath, content.trimEnd() + "\n\n" + hookBlock + "\n", "utf-8");
+  (0, import_node_fs.chmodSync)(hookPath, 493);
+}
+function writePawlClaudeMd(cwd) {
+  const claudeMdPath = (0, import_node_path.join)(cwd, "CLAUDE.md");
+  const PAWL_START = "<!-- pawl:start -->";
+  const PAWL_END = "<!-- pawl:end -->";
+  const AGENTMAP_START = "<!-- agentmap:start -->";
+  const AGENTMAP_END = "<!-- agentmap:end -->";
+  const block = [
+    PAWL_START,
+    "# Pawl Context",
+    "",
+    "This project uses Pawl for spec management and AI session tracking.",
+    "",
+    "Context files are in `.pawl/`:",
+    "- `.pawl/context.md` \u2014 project index, spec map, health",
+    "- `.pawl/specs/` \u2014 individual spec files (one per feature area)",
+    "- `.pawl/progress.md` \u2014 last session summary",
+    "",
+    "Read `.pawl/context.md` at session start, then load relevant specs from `.pawl/specs/` based on the task.",
+    PAWL_END
+  ].join("\n");
+  if (!(0, import_node_fs.existsSync)(claudeMdPath)) {
+    (0, import_node_fs.writeFileSync)(claudeMdPath, block + "\n", "utf-8");
+    return;
+  }
+  let content = (0, import_node_fs.readFileSync)(claudeMdPath, "utf-8");
+  let startIdx = content.indexOf(PAWL_START);
+  let endIdx = content.indexOf(PAWL_END);
+  let endMarkerLen = PAWL_END.length;
+  if (startIdx === -1 || endIdx === -1) {
+    startIdx = content.indexOf(AGENTMAP_START);
+    endIdx = content.indexOf(AGENTMAP_END);
+    endMarkerLen = AGENTMAP_END.length;
+  }
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.slice(0, startIdx) + block + content.slice(endIdx + endMarkerLen);
+  } else {
+    content = content.trimEnd() + "\n\n" + block + "\n";
+  }
+  (0, import_node_fs.writeFileSync)(claudeMdPath, content, "utf-8");
+}
+function writeAgentsMd(cwd) {
+  const agentsMdPath = (0, import_node_path.join)(cwd, "AGENTS.md");
+  const START_MARKER = "<!-- pawl:start -->";
+  const END_MARKER = "<!-- pawl:end -->";
+  const block = [
+    START_MARKER,
+    "## Pawl Project Context",
+    "",
+    "This project uses Pawl for spec management and AI session tracking.",
+    "Structured context files are available at:",
+    "",
+    "- `.pawl/context.md` \u2014 project index, spec map, health overview",
+    "- `.pawl/specs/` \u2014 individual spec files (one per feature area)",
+    "- `.pawl/progress.md` \u2014 last session summary, recent decisions",
+    "",
+    "**Start here**: Read `.pawl/context.md` first, then load relevant",
+    "spec files from `.pawl/specs/` based on the task at hand.",
+    END_MARKER
+  ].join("\n");
+  if (!(0, import_node_fs.existsSync)(agentsMdPath)) {
+    (0, import_node_fs.writeFileSync)(agentsMdPath, block + "\n", "utf-8");
+    return;
+  }
+  let content = (0, import_node_fs.readFileSync)(agentsMdPath, "utf-8");
+  const startIdx = content.indexOf(START_MARKER);
+  const endIdx = content.indexOf(END_MARKER);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.slice(0, startIdx) + block + content.slice(endIdx + END_MARKER.length);
+  } else {
+    content = content.trimEnd() + "\n\n" + block + "\n";
+  }
+  (0, import_node_fs.writeFileSync)(agentsMdPath, content, "utf-8");
+}
+function printSummary(detected, hasKey) {
+  console.log("\n  Pawl initialized.\n");
+  console.log("  Detected agents:");
+  if (detected.hasCC) {
+    console.log("    Claude Code   \u2713  hooks installed (.claude/settings.json)");
+  }
+  if (detected.hasGemini) {
+    console.log("    Gemini CLI    \u2713  hooks installed (.gemini/settings.json)");
+  }
+  console.log("    Codex / other    no lifecycle hooks \u2014 git post-commit fallback active");
+  console.log("\n  Files written:");
+  console.log("    .pawl/sync.sh");
+  console.log("    .pawl/parse-cc-session.js");
+  console.log("    CLAUDE.md        (pawl context block updated)");
+  console.log("    AGENTS.md        (pawl context block \u2014 readable by Codex, Kiro, and others)");
+  if (detected.hasGitDir) {
+    console.log("    .git/hooks/post-commit  (universal sync fallback)");
+  }
+  console.log("    .gitignore       (updated)");
+  if (detected.hasGitDir) {
+    console.log("\n  Note: .git/hooks/post-commit is per-machine \u2014 not committed to the repo.");
+    console.log("        Each team member should run: pawl init");
+  } else {
+    console.log("\n  Note: git repo not detected \u2014 post-commit hook skipped.");
+  }
+  if (!hasKey) {
+    console.log("\n  Sync is not yet connected to the Pawl dashboard.");
+    console.log("  To enable: pawl init <YOUR_PROJECT_KEY>");
+    console.log("  Get your key at: https://pawl.dev/settings");
+  } else {
+    console.log("\n  .pawl/.env written \u2014 sync is connected.");
+  }
+  console.log("");
+}
+function writeEnvFile(cwd, config) {
+  const dir = (0, import_node_path.join)(cwd, ".agentmap");
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  const content = [
+    `AGENTMAP_API_KEY=${config.apiKey}`,
+    `AGENTMAP_PROJECT_ID=${config.projectId}`,
+    `AGENTMAP_API_URL=${config.apiUrl}`,
+    ""
+  ].join("\n");
+  (0, import_node_fs.writeFileSync)((0, import_node_path.join)(dir, ".env"), content, "utf-8");
+}
+function writeSyncScript(cwd, config) {
+  const dir = (0, import_node_path.join)(cwd, ".agentmap");
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Pawl sync script \u2014 generated by pawl-setup
+# Do not edit manually; re-run npx @getpawl/setup to update.
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/.env"
+
+BASE_URL="$AGENTMAP_API_URL/api/projects/$AGENTMAP_PROJECT_ID"
+
+# \u2500\u2500 pull mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+pull() {
+  # Recovery: if tracked-files exist from a previous incomplete session, push first
+  if [ -f "$SCRIPT_DIR/.tracked-files" ]; then
+    push >/dev/null 2>&1
+  fi
+
+  # Ensure specs directory exists
+  mkdir -p "$SCRIPT_DIR/specs"
+
+  # \u2500\u2500 Level 1: New file-based endpoint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  RESPONSE=$(curl -sf -X GET "$BASE_URL/context/files" \\
+    -H "Authorization: Bearer $AGENTMAP_API_KEY" \\
+    -H "Accept: application/json" 2>/dev/null) || true
+
+  if [ -n "$RESPONSE" ] && echo "$RESPONSE" | jq -e '.files' >/dev/null 2>&1; then
+    echo "$RESPONSE" | jq -r '.files[] | @base64' | while read -r encoded; do
+      FILE_PATH=$(echo "$encoded" | base64 -d | jq -r '.path')
+      FILE_CONTENT=$(echo "$encoded" | base64 -d | jq -r '.content')
+
+      # Ensure parent directory exists
+      mkdir -p "$SCRIPT_DIR/$(dirname "$FILE_PATH")"
+      echo "$FILE_CONTENT" > "$SCRIPT_DIR/$FILE_PATH"
+    done
+
+    # Output context.md to stdout (for SessionStart hook)
+    if [ -f "$SCRIPT_DIR/context.md" ]; then
+      cat "$SCRIPT_DIR/context.md"
+    fi
+    return 0
+  fi
+
+  # \u2500\u2500 Level 2: Legacy monolithic endpoint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  RESPONSE=$(curl -sf -X GET "$BASE_URL/context" \\
+    -H "Authorization: Bearer $AGENTMAP_API_KEY" \\
+    -H "Accept: application/json" 2>/dev/null) || true
+
+  if [ -n "$RESPONSE" ] && echo "$RESPONSE" | jq -e '.formatted_context' >/dev/null 2>&1; then
+    echo "$RESPONSE" | jq -r '.formatted_context // empty' > "$SCRIPT_DIR/context.md"
+    cat "$SCRIPT_DIR/context.md"
+    return 0
+  fi
+
+  # \u2500\u2500 Level 3: Cached file fallback \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  if [ -f "$SCRIPT_DIR/context.md" ]; then
+    echo "# (cached \u2014 API unreachable)" | cat - "$SCRIPT_DIR/context.md"
+    return 0
+  fi
+
+  echo "Warning: Pawl context unavailable" >&2
+  return 1
+}
+
+# \u2500\u2500 push mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+push() {
+  LAST_SHA=""
+  if [ -f "$SCRIPT_DIR/.last-sync-sha" ]; then
+    LAST_SHA=$(cat "$SCRIPT_DIR/.last-sync-sha")
+  fi
+
+  CURRENT_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+  # Compute diff
+  if [ -n "$LAST_SHA" ]; then
+    DIFF=$(git diff "$LAST_SHA"..HEAD 2>/dev/null || echo "")
+  else
+    DIFF=$(git diff HEAD~1..HEAD 2>/dev/null || echo "")
+  fi
+
+  # Collect tracked files (dedup)
+  FILES_CHANGED="[]"
+  if [ -f "$SCRIPT_DIR/.tracked-files" ]; then
+    FILES_CHANGED=$(sort -u "$SCRIPT_DIR/.tracked-files" | jq -R . | jq -s .)
+  fi
+
+  # Commit info
+  COMMIT_MSG=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "")
+
+  # Session ID from Claude Code (if available)
+  SESSION_ID="\${CLAUDE_SESSION_ID:-}"
+
+  # Repo root for CC session lookup
+  REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+  # Parse CC session data locally (if node + parser available)
+  CC_SESSION="{}"
+  if command -v node &> /dev/null; then
+    PARSER="$SCRIPT_DIR/parse-cc-session.js"
+    if [ -f "$PARSER" ]; then
+      CC_SESSION=$(node "$PARSER" "$REPO_PATH" 2>/dev/null || echo "{}")
+    fi
+  fi
+
+  # Extract cc_tasks from parser output (P14-02)
+  CC_TASKS=$(echo "$CC_SESSION" | jq -c '.tasks // []')
+
+  PAYLOAD=$(jq -n \\
+    --arg diff "$DIFF" \\
+    --arg branch "$BRANCH" \\
+    --arg commit_sha "$CURRENT_SHA" \\
+    --arg commit_message "$COMMIT_MSG" \\
+    --arg session_id "$SESSION_ID" \\
+    --arg last_sync_sha "$LAST_SHA" \\
+    --arg repo_path "$REPO_PATH" \\
+    --argjson files_changed "$FILES_CHANGED" \\
+    --argjson cc_session "$CC_SESSION" \\
+    --argjson cc_tasks "$CC_TASKS" \\
+    '{
+      diff: $diff,
+      branch: $branch,
+      commit_sha: $commit_sha,
+      commit_message: $commit_message,
+      session_id: $session_id,
+      last_sync_sha: $last_sync_sha,
+      repo_path: $repo_path,
+      files_changed: $files_changed,
+      cc_session: $cc_session,
+      cc_tasks: $cc_tasks
+    }')
+
+  RESPONSE=$(curl -sf -X POST "$BASE_URL/sync" \\
+    -H "Authorization: Bearer $AGENTMAP_API_KEY" \\
+    -H "Content-Type: application/json" \\
+    -d "$PAYLOAD")
+
+  echo "$RESPONSE" | jq .
+
+  # Update last sync SHA
+  echo "$CURRENT_SHA" > "$SCRIPT_DIR/.last-sync-sha"
+
+  # Cleanup tracked files
+  rm -f "$SCRIPT_DIR/.tracked-files"
+}
+
+# \u2500\u2500 dispatch \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+case "\${1:-}" in
+  pull) pull ;;
+  push) push ;;
+  *)
+    echo "Usage: sync.sh [pull|push]"
+    exit 1
+    ;;
+esac
+`;
+  const scriptPath = (0, import_node_path.join)(dir, "sync.sh");
+  (0, import_node_fs.writeFileSync)(scriptPath, script, "utf-8");
+  (0, import_node_fs.chmodSync)(scriptPath, 493);
+}
+function copyParserScript(cwd, destDir = ".agentmap") {
+  const src = (0, import_node_path.join)(__dirname, "parse-cc-session.js");
+  const dest = (0, import_node_path.join)(cwd, destDir, "parse-cc-session.js");
+  if ((0, import_node_fs.existsSync)(src)) {
+    (0, import_node_fs.copyFileSync)(src, dest);
+  }
+}
+function mergeClaudeSettings(cwd, basePath = ".agentmap") {
+  const claudeDir = (0, import_node_path.join)(cwd, ".claude");
+  (0, import_node_fs.mkdirSync)(claudeDir, { recursive: true });
+  const settingsPath = (0, import_node_path.join)(claudeDir, "settings.json");
+  let settings = {};
+  if ((0, import_node_fs.existsSync)(settingsPath)) {
+    try {
+      settings = JSON.parse((0, import_node_fs.readFileSync)(settingsPath, "utf-8"));
+    } catch {
+    }
+  }
+  const hooks = {
+    SessionStart: [
+      {
+        hooks: [
+          { type: "command", command: `${basePath}/sync.sh pull` }
+        ]
+      }
+    ],
+    PostToolUse: [
+      {
+        matcher: "Write|Edit",
+        hooks: [
+          {
+            type: "command",
+            command: `jq -r '.tool_input.file_path' >> ${basePath}/.tracked-files`
+          }
+        ]
+      }
+    ],
+    Stop: [
+      {
+        hooks: [
+          { type: "command", command: `${basePath}/sync.sh push` }
+        ]
+      }
+    ]
+  };
+  const hooksObj = settings.hooks || {};
+  for (const [event, entries] of Object.entries(hooks)) {
+    const existing = hooksObj[event] || [];
+    for (const entry of entries) {
+      const cmd = entry.hooks[0].command;
+      const alreadyExists = existing.some(
+        (e) => e.hooks?.[0]?.command === cmd
+      );
+      if (!alreadyExists) {
+        existing.push(entry);
+      }
+    }
+    hooksObj[event] = existing;
+  }
+  settings.hooks = hooksObj;
+  (0, import_node_fs.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+function writeClaudeMd(cwd) {
+  const claudeMdPath = (0, import_node_path.join)(cwd, "CLAUDE.md");
+  const START_MARKER = "<!-- agentmap:start -->";
+  const END_MARKER = "<!-- agentmap:end -->";
+  const block = [
+    START_MARKER,
+    "# Pawl Context",
+    "",
+    "This project uses Pawl for spec management. Context files are in `.agentmap/`.",
+    "",
+    "## Context Files",
+    "- `.agentmap/context.md` \u2014 Project index, spec map, work items",
+    "- `.agentmap/specs/*.md` \u2014 Individual spec files with vision, implementation, dependencies",
+    "- `.agentmap/progress.md` \u2014 Last session summary, project health, recent decisions",
+    "",
+    "Read these files at the start of a session for full project context.",
+    "When asked about a spec, read the corresponding file in `.agentmap/specs/`.",
+    END_MARKER
+  ].join("\n");
+  if (!(0, import_node_fs.existsSync)(claudeMdPath)) {
+    (0, import_node_fs.writeFileSync)(claudeMdPath, block + "\n", "utf-8");
+    return;
+  }
+  let content = (0, import_node_fs.readFileSync)(claudeMdPath, "utf-8");
+  const startIdx = content.indexOf(START_MARKER);
+  const endIdx = content.indexOf(END_MARKER);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.slice(0, startIdx) + block + content.slice(endIdx + END_MARKER.length);
+  } else {
+    content = content.trimEnd() + "\n\n" + block + "\n";
+  }
+  (0, import_node_fs.writeFileSync)(claudeMdPath, content, "utf-8");
+}
+function updateGitignore(cwd) {
+  const gitignorePath = (0, import_node_path.join)(cwd, ".gitignore");
+  let content = "";
+  if ((0, import_node_fs.existsSync)(gitignorePath)) {
+    content = (0, import_node_fs.readFileSync)(gitignorePath, "utf-8");
+  }
+  const lines = content.split("\n");
+  const toAdd = [
+    ".agentmap/.env",
+    ".agentmap/.tracked-files",
+    ".agentmap/.last-sync-sha",
+    ".agentmap/context.md",
+    ".agentmap/specs/",
+    ".agentmap/progress.md",
+    ".pawl/.env",
+    ".pawl/.tracked-files",
+    ".pawl/.last-sync-sha",
+    ".pawl/context.md",
+    ".pawl/specs/",
+    ".pawl/progress.md"
+  ];
+  const missing = toAdd.filter((line) => !lines.includes(line));
+  if (missing.length > 0) {
+    const section = [];
+    if (!lines.includes("# pawl")) {
+      section.push("", "# pawl");
+    }
+    section.push(...missing);
+    const newContent = content.trimEnd() + "\n" + section.join("\n") + "\n";
+    (0, import_node_fs.writeFileSync)(gitignorePath, newContent, "utf-8");
+  }
+}
+main();

package/dist/parse-cc-session.js

@@ -0,0 +1,214 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/parse-cc-session.ts
+var import_node_fs = require("fs");
+var import_node_readline = require("readline");
+var import_node_os = require("os");
+var import_node_path = __toESM(require("path"));
+var CC_MODEL_PRICING = {
+  "claude-opus-4-6": { input: 15, output: 75, cacheRead: 1.5 },
+  "claude-sonnet-4-5-20250929": { input: 3, output: 15, cacheRead: 0.3 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3 },
+  "claude-haiku-4-5-20251001": { input: 0.8, output: 4, cacheRead: 0.08 }
+};
+function getProjectDir(repoPath) {
+  const encoded = "-" + repoPath.slice(1).replace(/\//g, "-");
+  const projectDir = import_node_path.default.join((0, import_node_os.homedir)(), ".claude", "projects", encoded);
+  try {
+    const s = (0, import_node_fs.statSync)(projectDir);
+    if (s.isDirectory()) return projectDir;
+  } catch {
+  }
+  return null;
+}
+async function parseSessionFile(filePath) {
+  try {
+    const rl = (0, import_node_readline.createInterface)({
+      input: (0, import_node_fs.createReadStream)(filePath),
+      crlfDelay: Infinity
+    });
+    let model = "";
+    let firstTimestamp = "";
+    const seenMessageIds = /* @__PURE__ */ new Set();
+    const filesRead = /* @__PURE__ */ new Set();
+    const filesWritten = /* @__PURE__ */ new Set();
+    const tasks = /* @__PURE__ */ new Map();
+    const pendingCreates = /* @__PURE__ */ new Map();
+    let currentTaskId = null;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    for await (const line of rl) {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!firstTimestamp && parsed.timestamp) {
+        firstTimestamp = parsed.timestamp;
+      }
+      if (parsed.type === "assistant" && parsed.message) {
+        const msg = parsed.message;
+        const msgId = msg.id;
+        if (!model && msg.model) model = msg.model;
+        if (msgId && !seenMessageIds.has(msgId)) {
+          seenMessageIds.add(msgId);
+          const u = msg.usage;
+          if (u) {
+            totalInputTokens += u.input_tokens ?? 0;
+            totalOutputTokens += u.output_tokens ?? 0;
+            cacheReadTokens += u.cache_read_input_tokens ?? 0;
+            cacheWriteTokens += u.cache_creation_input_tokens ?? 0;
+          }
+        }
+        const content = msg.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type !== "tool_use") continue;
+            const fp = block.input?.file_path;
+            if (fp) {
+              if (block.name === "Read") {
+                filesRead.add(fp);
+              } else if (block.name === "Write" || block.name === "Edit") {
+                filesWritten.add(fp);
+              }
+            }
+            if (block.name === "TaskCreate") {
+              pendingCreates.set(block.id, {
+                subject: block.input?.subject || "",
+                description: block.input?.description || ""
+              });
+            }
+            if (block.name === "TaskUpdate") {
+              const taskId = block.input?.taskId;
+              const task = taskId ? tasks.get(taskId) : void 0;
+              if (task && block.input?.status) {
+                task.status = block.input.status;
+                if (block.input.status === "in_progress")
+                  currentTaskId = taskId;
+                if (block.input.status === "completed" || block.input.status === "deleted") {
+                  if (currentTaskId === taskId) currentTaskId = null;
+                }
+              }
+            }
+            if (currentTaskId && (block.name === "Write" || block.name === "Edit") && fp) {
+              tasks.get(currentTaskId)?.filesAssociated.add(fp);
+            }
+          }
+        }
+      }
+      if (parsed.type === "user" && parsed.toolUseResult?.task?.id) {
+        const tr = parsed.toolUseResult;
+        const content = parsed.message?.content;
+        const toolUseId = Array.isArray(content) ? content.find((b) => b.type === "tool_result")?.tool_use_id : void 0;
+        const pending = toolUseId ? pendingCreates.get(toolUseId) : void 0;
+        tasks.set(tr.task.id, {
+          id: tr.task.id,
+          subject: tr.task.subject || pending?.subject || "",
+          description: pending?.description || "",
+          status: "pending",
+          filesAssociated: /* @__PURE__ */ new Set()
+        });
+        if (toolUseId) pendingCreates.delete(toolUseId);
+      }
+    }
+    if (totalInputTokens === 0 && totalOutputTokens === 0) return null;
+    const pricing = CC_MODEL_PRICING[model] ?? {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3
+    };
+    const realCost = (totalInputTokens * pricing.input + totalOutputTokens * pricing.output + cacheReadTokens * pricing.cacheRead + cacheWriteTokens * pricing.input) / 1e6;
+    let sessionDurationMs = 0;
+    if (firstTimestamp) {
+      try {
+        const mtime = (0, import_node_fs.statSync)(filePath).mtime.getTime();
+        const start = new Date(firstTimestamp).getTime();
+        if (mtime > start) sessionDurationMs = mtime - start;
+      } catch {
+      }
+    }
+    return {
+      filesRead: [...filesRead],
+      filesWritten: [...filesWritten],
+      totalInputTokens,
+      totalOutputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      model,
+      realCost,
+      sessionDurationMs,
+      tasks: Array.from(tasks.values()).map((t) => ({
+        id: t.id,
+        subject: t.subject,
+        description: t.description,
+        status: t.status,
+        filesAssociated: [...t.filesAssociated]
+      }))
+    };
+  } catch {
+    return null;
+  }
+}
+async function getMostRecentSession(repoPath) {
+  const projectDir = getProjectDir(repoPath);
+  if (!projectDir) return null;
+  let entries;
+  try {
+    entries = (0, import_node_fs.readdirSync)(projectDir);
+  } catch {
+    return null;
+  }
+  const jsonlFiles = entries.filter((e) => e.endsWith(".jsonl"));
+  if (jsonlFiles.length === 0) return null;
+  const withStats = jsonlFiles.map((f) => {
+    const fp = import_node_path.default.join(projectDir, f);
+    try {
+      const s = (0, import_node_fs.statSync)(fp);
+      return { file: f, mtime: s.mtime.getTime(), path: fp };
+    } catch {
+      return null;
+    }
+  }).filter((x) => x !== null);
+  if (withStats.length === 0) return null;
+  withStats.sort((a, b) => b.mtime - a.mtime);
+  return parseSessionFile(withStats[0].path);
+}
+async function main() {
+  const repoPath = process.argv[2];
+  if (!repoPath) {
+    process.stdout.write("{}");
+    process.exit(0);
+  }
+  try {
+    const result = await getMostRecentSession(repoPath);
+    process.stdout.write(JSON.stringify(result ?? {}));
+  } catch {
+    process.stdout.write("{}");
+  }
+}
+main();

package/package.json

@@ -1,13 +1,36 @@
 {
   "name": "@getpawl/setup",
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "1.1.0",
+  "type": "commonjs",
+  "description": "One-shot setup for Pawl + Claude Code hooks",
+  "bin": {
+    "pawl": "./dist/index.js",
+    "pawl-setup": "./dist/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "test": "node --test test/e2e.test.mjs",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xfishbone/agentMap.git",
+    "directory": "packages/setup"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "license": "MIT"
 }