@getpawl/setup 1.1.3 → 1.3.1

package/README.md

@@ -1,29 +1,78 @@
-# @fixhbone/agentmap-setup
+# @getpawl/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.
+One-shot setup for [Pawl](https://github.com/0xfishbone/agentMap) — connects any repo to your Pawl project so spec context is automatically synced during AI coding sessions.
 
-## Usage
+## Install
 
 ```sh
-npx @fixhbone/agentmap-setup <PROJECT_KEY>
+npm install -g @getpawl/setup
 ```
 
-Get your `<PROJECT_KEY>` from the AgentMap web dashboard under **Settings > Setup**.
+Then the `pawl` command will be available globally (`pawl sync`, `pawl connect`, `pawl migrate`).
+
+## Quick Start
+
+### 1. Initialize
+
+```sh
+npx @getpawl/setup init
+```
+
+Creates `.pawl/` directory with sync scripts, configures Claude Code hooks, and sets up git post-commit hook.
+
+### 2. Connect
+
+```sh
+npx @getpawl/setup connect
+```
+
+Opens your browser to link this repo to a Pawl project. Writes `.pawl/.env` automatically — no manual key copy-paste.
+
+### 3. Sync
+
+```sh
+pawl sync           # push current session to dashboard
+pawl sync --pull    # pull latest context from dashboard
+```
+
+Sync happens automatically via hooks. Use these commands for manual sync or agents without lifecycle hooks (Codex, etc.).
+
+## Legacy Setup
+
+Existing users can still use the one-step flow:
+
+```sh
+npx @getpawl/setup <PROJECT_KEY>
+```
+
+Get your `<PROJECT_KEY>` from the Pawl 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`
+1. Creates `.pawl/.env` with API credentials
+2. Generates `.pawl/sync.mjs` — Node.js sync script (no curl/jq needed)
+3. Generates `.pawl/track-file.mjs` — Node.js file tracker (replaces jq in PostToolUse hook)
+4. Generates `.pawl/sync.sh` — bash fallback for environments without Node.js
+5. Copies `.pawl/parse-cc-session.js` — extracts token usage and tasks from CC sessions
+6. Configures `.claude/settings.json` with lifecycle hooks (SessionStart, PostToolUse, Stop)
+7. Configures `.gemini/settings.json` with lifecycle hooks (if Gemini CLI detected)
+8. Installs `.git/hooks/post-commit` for universal agent support
+9. Updates `CLAUDE.md` and `AGENTS.md` with Pawl context blocks
+10. Adds sensitive paths to `.gitignore`
+
+## Supported Agents
+
+| Agent | Hook Method |
+|-------|-------------|
+| Claude Code | `.claude/settings.json` lifecycle hooks |
+| Gemini CLI | `.gemini/settings.json` lifecycle hooks |
+| Codex / Others | `git post-commit` hook fallback |
 
 ## Requirements
 
 - Node.js >= 18
-- [Claude Code](https://claude.ai/claude-code) CLI installed
+- Git repository
+- `curl` and `jq` are **no longer required** — `pawl init` generates Node.js sync scripts that use native `fetch()`. Bash scripts are kept as a fallback.
 
 ## License
 

package/dist/index.js

@@ -19,6 +19,8 @@ async function main() {
   } else if (arg === "init") {
     const key = process.argv[3];
     pawlInit(key);
+  } else if (arg === "migrate") {
+    pawlMigrate();
   } else {
     legacySetup(arg);
   }
@@ -29,6 +31,7 @@ Usage:
   pawl init                 Initialize Pawl in this repo
   pawl connect              Link this repo to a Pawl project (opens browser)
   pawl sync [--pull]        Sync with Pawl dashboard (push by default)
+  pawl migrate              Migrate .pawl/sync.sh from AGENTMAP_* to PAWL_* vars
   pawl-setup <PROJECT_KEY>  Legacy setup (still supported)
 
 Dashboard: https://pawl.dev
@@ -36,9 +39,10 @@ Dashboard: https://pawl.dev
 }
 function pawlSync(flag) {
   const cwd = process.cwd();
-  const syncScript = (0, import_node_path.join)(cwd, ".pawl", "sync.sh");
-  if (!(0, import_node_fs.existsSync)(syncScript)) {
-    console.error("Error: .pawl/sync.sh not found \u2014 run `pawl init` first.");
+  const syncMjs = (0, import_node_path.join)(cwd, ".pawl", "sync.mjs");
+  const syncSh = (0, import_node_path.join)(cwd, ".pawl", "sync.sh");
+  if (!(0, import_node_fs.existsSync)(syncMjs) && !(0, import_node_fs.existsSync)(syncSh)) {
+    console.error("Error: .pawl/sync.mjs not found \u2014 run `pawl init` first.");
     process.exit(1);
   }
   const envFile = (0, import_node_path.join)(cwd, ".pawl", ".env");
@@ -47,7 +51,43 @@ function pawlSync(flag) {
     process.exit(1);
   }
   const mode = flag === "--pull" ? "pull" : "push";
-  (0, import_node_child_process.execSync)(`.pawl/sync.sh ${mode}`, { stdio: "inherit", cwd });
+  if ((0, import_node_fs.existsSync)(syncMjs)) {
+    (0, import_node_child_process.execSync)(`node .pawl/sync.mjs ${mode}`, { stdio: "inherit", cwd });
+  } else {
+    (0, import_node_child_process.execSync)(`.pawl/sync.sh ${mode}`, { stdio: "inherit", cwd });
+  }
+}
+function pawlMigrate() {
+  const cwd = process.cwd();
+  const syncPath = (0, import_node_path.join)(cwd, ".pawl", "sync.sh");
+  if (!(0, import_node_fs.existsSync)(syncPath)) {
+    console.log("  Nothing to migrate \u2014 run `pawl init` first.");
+    process.exit(0);
+  }
+  let content = (0, import_node_fs.readFileSync)(syncPath, "utf-8");
+  if (!content.includes("AGENTMAP_")) {
+    console.log("  Already up to date.");
+    process.exit(0);
+  }
+  content = content.replace(/AGENTMAP_API_URL/g, "PAWL_API_URL").replace(/AGENTMAP_PROJECT_ID/g, "PAWL_PROJECT_ID").replace(/AGENTMAP_API_KEY/g, "PAWL_API_KEY");
+  (0, import_node_fs.writeFileSync)(syncPath, content, "utf-8");
+  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");
+    if (envContent.includes("AGENTMAP_")) {
+      envContent = envContent.replace(/AGENTMAP_API_URL/g, "PAWL_API_URL").replace(/AGENTMAP_PROJECT_ID/g, "PAWL_PROJECT_ID").replace(/AGENTMAP_API_KEY/g, "PAWL_API_KEY");
+      (0, import_node_fs.writeFileSync)(envPath, envContent, "utf-8");
+      console.log("  .pawl/.env also migrated.");
+    }
+  }
+  if (!(0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".pawl", "sync.mjs"))) {
+    writePawlSyncMjs(cwd);
+  }
+  if (!(0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, ".pawl", "track-file.mjs"))) {
+    writeTrackFileScript(cwd);
+  }
+  mergeClaudeSettings(cwd, ".pawl");
+  console.log("  Migration complete \u2014 .pawl/sync.sh updated to PAWL_* vars.");
 }
 function generateCode() {
   const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
@@ -185,6 +225,8 @@ function pawlInit(key) {
     writePawlEnvFile(cwd, config);
   }
   writePawlSyncScript(cwd);
+  writePawlSyncMjs(cwd);
+  writeTrackFileScript(cwd);
   copyParserScript(cwd, ".pawl");
   if (detected.hasCC) {
     mergeClaudeSettings(cwd, ".pawl");
@@ -416,6 +458,211 @@ esac
   (0, import_node_fs.writeFileSync)(scriptPath, script, "utf-8");
   (0, import_node_fs.chmodSync)(scriptPath, 493);
 }
+function writePawlSyncMjs(cwd) {
+  const script = `#!/usr/bin/env node
+// Pawl sync script (Node.js) \u2014 generated by pawl init
+// Do not edit manually; re-run pawl init to update.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+
+// Parse .env file (no dotenv dependency)
+function loadEnv() {
+  const envPath = join(SCRIPT_DIR, '.env');
+  if (!existsSync(envPath)) return {};
+  const env = {};
+  for (const line of readFileSync(envPath, 'utf-8').split('\\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+  }
+  return env;
+}
+
+const env = loadEnv();
+const API_KEY = env.PAWL_API_KEY || '';
+const PROJECT_ID = env.PAWL_PROJECT_ID || '';
+const API_URL = env.PAWL_API_URL || '';
+const BASE_URL = \`\${API_URL}/api/projects/\${PROJECT_ID}\`;
+
+async function pull() {
+  if (!API_KEY) {
+    process.stderr.write('Warning: PAWL_API_KEY not set \u2014 sync disabled\\n');
+    const cached = join(SCRIPT_DIR, 'context.md');
+    if (existsSync(cached)) process.stdout.write(readFileSync(cached, 'utf-8'));
+    return;
+  }
+
+  // Recovery: if tracked-files exist from a previous incomplete session, push first
+  if (existsSync(join(SCRIPT_DIR, '.tracked-files'))) {
+    try { await push(); } catch {}
+  }
+
+  mkdirSync(join(SCRIPT_DIR, 'specs'), { recursive: true });
+
+  // Level 1: File-based endpoint
+  try {
+    const res = await fetch(\`\${BASE_URL}/context/files\`, {
+      headers: { 'Authorization': \`Bearer \${API_KEY}\`, 'Accept': 'application/json' },
+    });
+    if (res.ok) {
+      const data = await res.json();
+      if (data.files) {
+        for (const file of data.files) {
+          const filePath = join(SCRIPT_DIR, file.path);
+          mkdirSync(dirname(filePath), { recursive: true });
+          writeFileSync(filePath, file.content, 'utf-8');
+        }
+        const ctxPath = join(SCRIPT_DIR, 'context.md');
+        if (existsSync(ctxPath)) process.stdout.write(readFileSync(ctxPath, 'utf-8'));
+        return;
+      }
+    }
+  } catch {}
+
+  // Level 2: Legacy monolithic endpoint
+  try {
+    const res = await fetch(\`\${BASE_URL}/context\`, {
+      headers: { 'Authorization': \`Bearer \${API_KEY}\`, 'Accept': 'application/json' },
+    });
+    if (res.ok) {
+      const data = await res.json();
+      if (data.formatted_context) {
+        writeFileSync(join(SCRIPT_DIR, 'context.md'), data.formatted_context, 'utf-8');
+        process.stdout.write(data.formatted_context);
+        return;
+      }
+    }
+  } catch {}
+
+  // Level 3: Cached fallback
+  const cached = join(SCRIPT_DIR, 'context.md');
+  if (existsSync(cached)) {
+    process.stdout.write('# (cached \u2014 API unreachable)\\n' + readFileSync(cached, 'utf-8'));
+    return;
+  }
+
+  process.stderr.write('Warning: Pawl context unavailable\\n');
+  process.exitCode = 1;
+}
+
+async function push() {
+  if (!API_KEY) return;
+
+  let lastSha = '';
+  const lastShaPath = join(SCRIPT_DIR, '.last-sync-sha');
+  if (existsSync(lastShaPath)) lastSha = readFileSync(lastShaPath, 'utf-8').trim();
+
+  const git = (cmd) => { try { return execSync(cmd, { encoding: 'utf-8' }).trim(); } catch { return ''; } };
+
+  const currentSha = git('git rev-parse HEAD');
+  const branch = git('git rev-parse --abbrev-ref HEAD') || 'unknown';
+
+  let diff = '';
+  if (lastSha) {
+    diff = git(\`git diff \${lastSha}..HEAD\`);
+  } else {
+    diff = git('git diff HEAD~1..HEAD');
+  }
+
+  // Cap diff at 500K
+  if (diff.length > 500000) diff = diff.slice(0, 500000);
+
+  // Collect tracked files
+  let filesChanged = [];
+  const trackedPath = join(SCRIPT_DIR, '.tracked-files');
+  if (existsSync(trackedPath)) {
+    filesChanged = [...new Set(readFileSync(trackedPath, 'utf-8').split('\\n').filter(Boolean))];
+  }
+
+  const commitMessage = git('git log -1 --pretty=format:"%s"');
+  const sessionId = process.env.CLAUDE_SESSION_ID || '';
+  const repoPath = git('git rev-parse --show-toplevel') || process.cwd();
+
+  // Parse CC session data
+  let ccSession = {};
+  const parserPath = join(SCRIPT_DIR, 'parse-cc-session.js');
+  if (existsSync(parserPath)) {
+    try {
+      const raw = execSync(\`node "\${parserPath}" "\${repoPath}"\`, { encoding: 'utf-8' });
+      ccSession = JSON.parse(raw);
+    } catch {}
+  }
+
+  const ccTasks = ccSession.tasks || [];
+
+  const payload = {
+    diff,
+    branch,
+    commit_sha: currentSha,
+    commit_message: commitMessage,
+    session_id: sessionId,
+    last_sync_sha: lastSha,
+    repo_path: repoPath,
+    files_changed: filesChanged,
+    cc_session: ccSession,
+    cc_tasks: ccTasks,
+  };
+
+  try {
+    const res = await fetch(\`\${BASE_URL}/sync\`, {
+      method: 'POST',
+      headers: {
+        'Authorization': \`Bearer \${API_KEY}\`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+    if (res.ok) {
+      const data = await res.json();
+      process.stdout.write(JSON.stringify(data, null, 2) + '\\n');
+    }
+  } catch {}
+
+  writeFileSync(lastShaPath, currentSha, 'utf-8');
+  if (existsSync(trackedPath)) unlinkSync(trackedPath);
+}
+
+// Dispatch
+const mode = process.argv[2];
+if (mode === 'pull') {
+  pull().catch(() => { process.exitCode = 1; });
+} else if (mode === 'push') {
+  push().catch(() => { process.exitCode = 1; });
+} else {
+  process.stderr.write('Usage: sync.mjs [pull|push]\\n');
+  process.exitCode = 1;
+}
+`;
+  const scriptPath = (0, import_node_path.join)(cwd, ".pawl", "sync.mjs");
+  (0, import_node_fs.writeFileSync)(scriptPath, script, "utf-8");
+}
+function writeTrackFileScript(cwd) {
+  const script = `// Pawl file tracker \u2014 reads tool JSON from stdin, appends file_path to .tracked-files
+import { appendFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let d = '';
+process.stdin.on('data', c => d += c);
+process.stdin.on('end', () => {
+  try {
+    const p = JSON.parse(d).tool_input.file_path;
+    if (p) {
+      const dir = dirname(fileURLToPath(import.meta.url));
+      appendFileSync(join(dir, '.tracked-files'), p + '\\n');
+    }
+  } catch {}
+});
+`;
+  const scriptPath = (0, import_node_path.join)(cwd, ".pawl", "track-file.mjs");
+  (0, import_node_fs.writeFileSync)(scriptPath, script, "utf-8");
+}
 function mergeGeminiSettings(cwd) {
   const geminiDir = (0, import_node_path.join)(cwd, ".gemini");
   (0, import_node_fs.mkdirSync)(geminiDir, { recursive: true });
@@ -428,12 +675,19 @@ function mergeGeminiSettings(cwd) {
     }
   }
   const hooksToInstall = {
-    SessionStart: { command: ".pawl/sync.sh pull" },
-    AfterAgentLoop: { command: ".pawl/sync.sh push" }
+    SessionStart: { command: "node .pawl/sync.mjs pull 2>/dev/null || .pawl/sync.sh pull" },
+    AfterAgentLoop: { command: "node .pawl/sync.mjs push 2>/dev/null || .pawl/sync.sh push" }
   };
+  const oldCommands = [".pawl/sync.sh pull", ".pawl/sync.sh push"];
   const hooksObj = settings.hooks || {};
   for (const [event, entry] of Object.entries(hooksToInstall)) {
-    const existing = hooksObj[event] || [];
+    let existing = hooksObj[event] || [];
+    existing = existing.map((e) => {
+      if (oldCommands.includes(e.command)) {
+        return { ...e, command: entry.command };
+      }
+      return e;
+    });
     const alreadyExists = existing.some((e) => e.command === entry.command);
     if (!alreadyExists) {
       existing.push(entry);
@@ -451,7 +705,9 @@ function writeGitHook(cwd, hasGitDir) {
   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
+if command -v node >/dev/null 2>&1 && [ -f ".pawl/sync.mjs" ]; then
+  node .pawl/sync.mjs push
+elif [ -f ".pawl/sync.sh" ]; then
   .pawl/sync.sh push
 fi`;
   if (!(0, import_node_fs.existsSync)(hookPath)) {
@@ -459,8 +715,20 @@ fi`;
     (0, import_node_fs.chmodSync)(hookPath, 493);
     return;
   }
-  const content = (0, import_node_fs.readFileSync)(hookPath, "utf-8");
+  let content = (0, import_node_fs.readFileSync)(hookPath, "utf-8");
   if (content.includes("Pawl sync hook")) {
+    const markerStart = content.indexOf("# Pawl sync hook");
+    if (markerStart !== -1) {
+      let blockStart = markerStart;
+      const before = content.lastIndexOf("\n", markerStart - 1);
+      const fiIdx = content.indexOf("\nfi", markerStart);
+      if (fiIdx !== -1) {
+        const blockEnd = fiIdx + "\nfi".length;
+        content = content.slice(0, blockStart) + hookBlock.slice(hookBlock.indexOf("# Pawl sync hook")) + content.slice(blockEnd);
+        (0, import_node_fs.writeFileSync)(hookPath, content, "utf-8");
+        (0, import_node_fs.chmodSync)(hookPath, 493);
+      }
+    }
     return;
   }
   (0, import_node_fs.writeFileSync)(hookPath, content.trimEnd() + "\n\n" + hookBlock + "\n", "utf-8");
@@ -482,6 +750,7 @@ function writePawlClaudeMd(cwd) {
     "- `.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",
+    "- `.pawl/decisions.json` \u2014 architectural decisions log (read before starting work)",
     "",
     "Read `.pawl/context.md` at session start, then load relevant specs from `.pawl/specs/` based on the task.",
     PAWL_END
@@ -520,6 +789,7 @@ function writeAgentsMd(cwd) {
     "- `.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",
+    "- `.pawl/decisions.json` \u2014 architectural decisions log, read before starting work",
     "",
     "**Start here**: Read `.pawl/context.md` first, then load relevant",
     "spec files from `.pawl/specs/` based on the task at hand.",
@@ -550,7 +820,9 @@ function printSummary(detected, hasKey) {
   }
   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/sync.mjs           (Node.js sync \u2014 no curl/jq needed)");
+  console.log("    .pawl/track-file.mjs     (Node.js file tracker)");
+  console.log("    .pawl/sync.sh            (bash fallback)");
   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)");
@@ -769,7 +1041,7 @@ function mergeClaudeSettings(cwd, basePath = ".agentmap") {
     SessionStart: [
       {
         hooks: [
-          { type: "command", command: `${basePath}/sync.sh pull` }
+          { type: "command", command: `node ${basePath}/sync.mjs pull 2>/dev/null || ${basePath}/sync.sh pull` }
         ]
       }
     ],
@@ -779,7 +1051,7 @@ function mergeClaudeSettings(cwd, basePath = ".agentmap") {
         hooks: [
           {
             type: "command",
-            command: `jq -r '.tool_input.file_path' >> ${basePath}/.tracked-files`
+            command: `node ${basePath}/track-file.mjs 2>/dev/null || jq -r '.tool_input.file_path' >> ${basePath}/.tracked-files`
           }
         ]
       }
@@ -787,18 +1059,30 @@ function mergeClaudeSettings(cwd, basePath = ".agentmap") {
     Stop: [
       {
         hooks: [
-          { type: "command", command: `${basePath}/sync.sh push` }
+          { type: "command", command: `node ${basePath}/sync.mjs push 2>/dev/null || ${basePath}/sync.sh push` }
         ]
       }
     ]
   };
+  const oldPatterns = [
+    `${basePath}/sync.sh pull`,
+    `${basePath}/sync.sh push`,
+    `jq -r '.tool_input.file_path' >> ${basePath}/.tracked-files`
+  ];
   const hooksObj = settings.hooks || {};
   for (const [event, entries] of Object.entries(hooks)) {
-    const existing = hooksObj[event] || [];
+    let existing = hooksObj[event] || [];
     for (const entry of entries) {
-      const cmd = entry.hooks[0].command;
+      const newCmd = entry.hooks[0].command;
+      existing = existing.map((e) => {
+        const existingCmd = e.hooks?.[0]?.command;
+        if (existingCmd && oldPatterns.includes(existingCmd)) {
+          return { ...e, hooks: [{ ...e.hooks[0], command: newCmd }] };
+        }
+        return e;
+      });
       const alreadyExists = existing.some(
-        (e) => e.hooks?.[0]?.command === cmd
+        (e) => e.hooks?.[0]?.command === newCmd
       );
       if (!alreadyExists) {
         existing.push(entry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpawl/setup",
-  "version": "1.1.3",
+  "version": "1.3.1",
   "type": "commonjs",
   "description": "One-shot setup for Pawl + Claude Code hooks",
   "bin": {