create-snipara 1.3.14 → 1.3.16

package/README.md

@@ -19,7 +19,7 @@ Use it for:
 - Hosted MCP onboarding for Codex, Claude Code, Cursor, ChatGPT Desktop, and similar clients
 - free account signup with reviewed Context + Memory
 - local project wiring, `doctor`, `repair`, and `upgrade`
-- GitHub repository sync approval when the current folder is a GitHub repo
+- GitHub repository sync and PR Answer Packs approval when the current folder is a GitHub repo
 
 ## Why It Exists
 
@@ -99,6 +99,7 @@ That distinction matters:
 - opens the browser device-flow free Context + Memory account flow when needed
 - writes Hosted MCP configuration
 - detects a GitHub remote and can open the Snipara GitHub App automation path
+- explains the GitHub PR Answer Packs path for AI-assisted pull request workflows
 - installs `snipara-companion` by default for local managed workflows
 - installs optional `snipara-sandbox`
 - configures `.mcp.json`
@@ -116,7 +117,7 @@ That distinction matters:
 Keep the package roles simple:
 
 - `create-snipara` = connect the user to Hosted MCP Context + Memory
-- `create-snipara --github` = connect the current GitHub repository through the browser approval flow
+- `create-snipara --github` = connect the current GitHub repository through the browser approval flow for repository sync and PR Answer Packs
 - `snipara-business` = prepare business context from local or mounted folders
 - Hosted MCP = the runtime surface the LLM actually uses after setup
 
@@ -347,12 +348,31 @@ The browser flow lets the user:
 - create or reuse the matching Snipara project
 - enable push sync
 - start the first documentation sync
+- enable PR Answer Packs for AI-assisted pull request workflows
 
 Hosted memory stays attached to the same Snipara account.
 
+### PR Answer Packs
+
+PR Answer Packs are generated by the hosted Snipara GitHub App, not by a local
+MCP command. Once the repository is connected, Snipara can attach scoped
+repository context to pull requests, including impacted symbols, architecture
+notes, related history, conventions, and linked documentation.
+
+Use this path for GitHub-native coding-agent workflows:
+
+```bash
+npx create-snipara --github
+```
+
+Keep using `snipara-companion` for local planning, code impact checks, and
+memory commits. Keep using Hosted MCP for agent context retrieval. Do not use
+`snipara-mcp` as a separate PR Answer Packs setup path unless Snipara exposes a
+dedicated MCP tool for it.
+
 Recommended explanation to users:
 
-> `create-snipara` connects your LLM from the terminal. GitHub sync is approved in the browser because GitHub requires the user to choose which account, organization, and repositories Snipara can read.
+> `create-snipara` connects your LLM from the terminal. GitHub sync and PR Answer Packs are approved in the browser because GitHub requires the user to choose which account, organization, and repositories Snipara can read.
 
 ## API Key Requirements
 
@@ -402,6 +422,9 @@ npx create-snipara --github
 
 Best when the current folder is a GitHub repository and the user wants code or docs sync through the GitHub App.
 
+PR Answer Packs are part of this hosted GitHub App path. They do not require a
+separate local MCP package.
+
 ### Connect the current repository with a path filter
 
 ```bash

package/dist/index.js

@@ -9,12 +9,13 @@ import fs from "fs";
 import path from "path";
 import { execSync, spawn } from "child_process";
 import { homedir } from "os";
-var VERSION = "1.3.14";
+var VERSION = "1.3.15";
 var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
 var COMPANION_COMMAND_NAME = "snipara-companion";
 var LEGACY_COMPANION_COMMAND_NAME = "rlm-hook";
+var GITHUB_ANSWER_PACKS_LABEL = "GitHub PR Answer Packs";
 var MCP_PACKAGE_NAME = "snipara-mcp";
 var SANDBOX_PACKAGE_NAME = "snipara-sandbox[all]";
 var SANDBOX_SERVER_NAME = "snipara-sandbox";
@@ -214,8 +215,23 @@ async function runUpgrade(options) {
 async function runPrintConfig(options) {
   const detection = detectEnvironment();
   const answers = loadExistingAnswers(options);
+  const githubRepo = detectGitRepository();
+  const githubAnswerPacks = githubRepo ? `${githubRepo.fullName} can be connected with npx create-snipara --github` : "requires a GitHub-backed git remote";
   if (options.json) {
-    console.log(JSON.stringify({ detection, inferredSetup: answers }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          detection,
+          github: {
+            repository: githubRepo,
+            answerPacks: githubAnswerPacks
+          },
+          inferredSetup: answers
+        },
+        null,
+        2
+      )
+    );
     return;
   }
   console.log(chalk.bold("\n\u{1F4E6} Current Setup\n"));
@@ -230,6 +246,8 @@ async function runPrintConfig(options) {
   console.log(`   Local snipara-mcp package: ${answers.installMcp ? "enabled" : "disabled"}`);
   console.log(`   Snipara Sandbox: ${answers.installRuntime ? "enabled" : "disabled"}`);
   console.log(`   Hooks: ${answers.installHooks ? "enabled" : "disabled"}`);
+  console.log(`   GitHub repo: ${githubRepo ? githubRepo.fullName : "not detected"}`);
+  console.log(`   ${GITHUB_ANSWER_PACKS_LABEL}: ${githubAnswerPacks}`);
   console.log(`   Existing .mcp.json: ${detection.files.mcpConfig ? "yes" : "no"}`);
   console.log(`   Companion pack: ${detection.files.sniparaCompanionPack ? "yes" : "no"}`);
   console.log("");
@@ -386,7 +404,7 @@ async function gatherConfiguration(options) {
     {
       type: (_, values) => detectedGitRepo && showAdvancedPrompts && !options.skipGithub && (values.profile || initialProfile) !== "runtime-only" ? "confirm" : null,
       name: "configureGitHub",
-      message: detectedGitRepo ? `Open GitHub automation setup for ${detectedGitRepo.fullName} after local config?` : "Open GitHub automation setup after local config?",
+      message: detectedGitRepo ? `Open GitHub automation and PR Answer Packs setup for ${detectedGitRepo.fullName} after local config?` : "Open GitHub automation setup after local config?",
       initial: true
     },
     {
@@ -956,9 +974,10 @@ Agent task lifecycle:
 11. If \`git status --short\` is dirty, warn that Snipara's indexed code graph may not include local edits; use local reads/tests for exact edits and Snipara for architecture/code graph context.
 12. Use Snipara Sandbox only when sandboxed execution, repeatable validation, or isolated transformations materially help.
 13. If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
-14. End each substantial phase with \`snipara_end_of_task_commit\` or \`snipara-companion workflow phase-commit\` when companion manages the plan. End the whole managed workflow with \`snipara-companion final-commit\`.
-15. Use \`snipara_remember_if_novel\` for one reusable memory while avoiding duplicates, and use \`snipara_remember\` for explicit direct memory writes.
-16. Do not store secrets, tokens, passwords, private keys, raw logs, transient command output, or unreviewed guesses in memory.
+14. When generated hooks are enabled, \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` provide runtime Rescue Pack checks for repeated failures, empty searches, and risky workflows.
+15. End each substantial phase with \`snipara_end_of_task_commit\` or \`snipara-companion workflow phase-commit\` when companion manages the plan. End the whole managed workflow with \`snipara-companion final-commit\`.
+16. Use \`snipara_remember_if_novel\` for one reusable memory while avoiding duplicates, and use \`snipara_remember\` for explicit direct memory writes.
+17. Do not store secrets, tokens, passwords, private keys, raw logs, transient command output, or unreviewed guesses in memory.
 `;
 }
 function buildClaudeMdTemplate(answers) {
@@ -979,6 +998,7 @@ Use Snipara Hosted MCP before answering project-specific questions.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings. Legacy \`rlm_code_*\` IDs return the same payloads.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact edits/current working tree; use Snipara for architecture and indexed code graph context.
 - When the plan is visible and \`snipara-companion\` is installed, use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` to keep phase state durable across compaction. Legacy \`rlm-hook\` commands remain compatible.
+- If generated hooks are enabled, \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` provide runtime Rescue Pack checks when the agent loops on failures or empty searches.
 - Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
 - End substantial work with \`snipara_end_of_task_commit\` when available; for managed workflows, end every phase with \`snipara-companion workflow phase-commit\` and the task with \`snipara-companion final-commit\`.
 - Use \`snipara_remember_if_novel\` or \`snipara_remember\` only for narrow durable memories.
@@ -1008,6 +1028,7 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 - Use \`snipara_plan\` or \`snipara_decompose\` only for complex work and only when available.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
 - When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` so the next phase survives compaction. Legacy \`rlm-hook\` commands remain compatible.
+- Generated hooks can call \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` so Rescue Packs are runtime-triggered rather than relying only on instructions.
 - Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
 - End substantial work with \`snipara_end_of_task_commit\` when available; for managed workflows, end every phase with \`snipara-companion workflow phase-commit\` and the task with \`snipara-companion final-commit\`. Use \`snipara_remember_if_novel\` or \`snipara_remember\` only for narrow durable memories. Never store secrets.
 `;
@@ -1103,6 +1124,10 @@ async function installClaudeCodeHooks(answers) {
     fs.mkdirSync(hooksDir, { recursive: true });
   }
   const hooks = [
+    {
+      name: "snipara-stuck-guard.sh",
+      content: createStuckGuardHook(answers)
+    },
     {
       name: "snipara-startup.sh",
       content: createStartupHook(answers)
@@ -1134,6 +1159,11 @@ async function installClaudeCodeHooks(answers) {
   settings.hooks = settings.hooks || {};
   const hooksConfig = settings.hooks;
   const hookEntries = [
+    {
+      event: "PreToolUse",
+      script: path.join(hooksDir, "snipara-stuck-guard.sh"),
+      matcher: { tool_name: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write" }
+    },
     {
       event: "PreToolUse",
       script: path.join(hooksDir, "snipara-startup.sh"),
@@ -1142,7 +1172,7 @@ async function installClaudeCodeHooks(answers) {
     {
       event: "PostToolUse",
       script: path.join(hooksDir, "snipara-session.sh"),
-      matcher: { tool_name: "Bash" }
+      matcher: { tool_name: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write" }
     },
     {
       event: "PreCompact",
@@ -1162,6 +1192,26 @@ async function installClaudeCodeHooks(answers) {
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   console.log(chalk.green("   \u2713 Updated ~/.claude/settings.json"));
 }
+function createStuckGuardHook(answers) {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+export SNIPARA_PROJECT_SLUG="${answers.projectSlug}"
+${answers.projectId ? `export SNIPARA_PROJECT_ID="${answers.projectId}"` : ""}
+
+SNIPARA_COMPANION_BIN=""
+if command -v ${COMPANION_COMMAND_NAME} >/dev/null 2>&1; then
+  SNIPARA_COMPANION_BIN="${COMPANION_COMMAND_NAME}"
+elif command -v ${LEGACY_COMPANION_COMMAND_NAME} >/dev/null 2>&1; then
+  SNIPARA_COMPANION_BIN="${LEGACY_COMPANION_COMMAND_NAME}"
+fi
+
+if [ -n "$SNIPARA_COMPANION_BIN" ]; then
+  INPUT=$(cat || true)
+  "$SNIPARA_COMPANION_BIN" pre-tool "$INPUT" || true
+fi
+`;
+}
 function createStartupHook(answers) {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -1200,7 +1250,8 @@ elif command -v ${LEGACY_COMPANION_COMMAND_NAME} >/dev/null 2>&1; then
 fi
 
 if [ -n "$SNIPARA_COMPANION_BIN" ]; then
-  "$SNIPARA_COMPANION_BIN" emit-event --event-type tool_result --json '{"source":"claude-code-hook"}' || true
+  INPUT=$(cat || true)
+  "$SNIPARA_COMPANION_BIN" post-tool "$INPUT" || true
 fi
 `;
 }
@@ -1341,6 +1392,15 @@ function getCompanionCommands(answers) {
       purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_COMMAND_NAME} onboard-folder without using the dashboard.`
     }
   ];
+  const githubAnswerPacksCommand = answers.githubRepo ? {
+    title: "Connect GitHub PR Answer Packs",
+    command: `npx create-snipara --github${answers.githubPath ? ` --github-path ${answers.githubPath}` : ""}`,
+    purpose: `Open the Snipara GitHub App flow for ${answers.githubRepo.fullName}. After the repo is connected, Snipara can generate scoped PR Answer Packs for GitHub-native agent workflows.`
+  } : {
+    title: "Connect a GitHub repo for PR Answer Packs",
+    command: "npx create-snipara --github",
+    purpose: "Run this from a GitHub-backed repository to approve the Snipara GitHub App and enable repository sync plus PR Answer Packs."
+  };
   return [
     {
       title: "Bootstrap local companion",
@@ -1387,6 +1447,7 @@ function getCompanionCommands(answers) {
       command: `${COMPANION_COMMAND_NAME} code impact --changed-files src/api/webhooks.ts tests/webhooks.test.ts --diff-summary "webhook retry hardening"`,
       purpose: "Use paid Context code impact analysis to surface likely tests, docs, routes, config, and risks."
     },
+    githubAnswerPacksCommand,
     {
       title: "Upload or refresh a doc",
       command: `${COMPANION_COMMAND_NAME} upload --path docs/local-playbook.md --file ./docs/local-playbook.md`,
@@ -1403,6 +1464,16 @@ function getCompanionCommands(answers) {
       command: `${COMPANION_COMMAND_NAME} session-bootstrap`,
       purpose: "Load durable decisions, learnings, and optional short-lived carryover at session start."
     },
+    {
+      title: "Check Stuck Guard status",
+      command: `${COMPANION_COMMAND_NAME} stuck-guard status`,
+      purpose: "Inspect whether recent tool failures, empty searches, or risky workflow signals should trigger a Rescue Pack."
+    },
+    {
+      title: "Simulate a Stuck Guard fixture",
+      command: `${COMPANION_COMMAND_NAME} stuck-guard simulate --fixture ./stuck-guard-fixture.json`,
+      purpose: "Replay canonical events against the hosted Stuck Guard decision API before enabling stricter modes."
+    },
     {
       title: "Ask memory about past decisions",
       command: `${COMPANION_COMMAND_NAME} recall --query "What did we decide about auth retries?" --type decision`,
@@ -1447,6 +1518,7 @@ This project uses Snipara as a hosted-first context and memory layer with local
 - Installed local snipara-mcp package: \`${answers.installMcp ? "yes" : "no"}\`
 - Installed Snipara Sandbox: \`${answers.installRuntime ? "yes" : "no"}\`
 - Generated hooks: \`${answers.installHooks ? "yes" : "no"}\`
+- GitHub repository: \`${answers.githubRepo ? answers.githubRepo.fullName : "not-detected"}\`
 
 ## Local Detection Snapshot
 
@@ -1476,6 +1548,15 @@ Apply only after reviewing the manifest:
 
 For source-code repositories, use the GitHub OAuth/code onboarding path instead of \`onboard-folder\`.
 
+## GitHub PR Answer Packs
+
+PR Answer Packs are generated by the hosted Snipara GitHub App, not by a local MCP command.
+They attach scoped repository context to pull requests so coding agents can load impacted symbols,
+architecture notes, related history, conventions, and linked documentation without rescanning the
+entire repository.
+
+${answers.githubRepo ? `This folder maps to \`${answers.githubRepo.fullName}\`. Use the GitHub App setup link below to connect the repo and enable PR Answer Packs for new or updated pull requests.` : `Run \`npx create-snipara --github\` from a GitHub-backed repository to open the approval flow for repository sync and PR Answer Packs.`}
+
 ## GitHub Repository Automation
 
 ${answers.githubRepo ? `Detected repository: \`${answers.githubRepo.fullName}\` on branch \`${answers.githubRepo.branch}\`.
@@ -1484,7 +1565,7 @@ Open the Snipara GitHub App setup and connect this repository:
 
 \`${buildGitHubAutomationUrl(answers)}\`
 
-After connection, Snipara creates or reuses the repository project, enables push sync, starts the first documentation sync, and keeps hosted memory available through the same account.` : `No GitHub repository was detected for this folder. Run \`npx create-snipara --github\` from a GitHub-backed git repository to open the repo automation path.`}
+After connection, Snipara creates or reuses the repository project, enables push sync, starts the first documentation sync, and can publish PR Answer Packs through GitHub-native PR surfaces. Hosted memory stays available through the same account.` : `No GitHub repository was detected for this folder. Run \`npx create-snipara --github\` from a GitHub-backed git repository to open the repo automation path.`}
 
 ## Suggested Commands
 
@@ -1565,7 +1646,7 @@ async function openGitHubAutomation(answers) {
   console.log(
     `   Opening Snipara GitHub setup for ${chalk.cyan(answers.githubRepo.fullName)} on branch ${chalk.cyan(
       answers.githubRepo.branch
-    )}.`
+    )}. This enables repository sync and PR Answer Packs after browser approval.`
   );
   console.log(chalk.dim(`   ${url}
 `));
@@ -1630,6 +1711,12 @@ async function runValidation(answers, includeHostedCheck) {
     status: answers.installHooks && answers.aiClient === "claude-code" ? detection.files.claudeDir ? "pass" : "warn" : "pass",
     detail: answers.installHooks && answers.aiClient === "claude-code" ? detection.files.claudeDir ? "~/.claude detected" : "~/.claude missing" : "Hooks not requested"
   });
+  const githubRepo = answers.githubRepo || detectGitRepository();
+  checks.push({
+    name: "github_answer_packs",
+    status: answers.configureGitHub ? "pass" : githubRepo ? "warn" : "pass",
+    detail: answers.configureGitHub ? `GitHub App setup link generated for ${githubRepo?.fullName || "detected repo"}; PR Answer Packs are enabled after browser approval` : githubRepo ? `GitHub repo ${githubRepo.fullName} detected; run npx create-snipara --github to connect PR Answer Packs` : "No GitHub repo detected; PR Answer Packs require the GitHub App setup path"
+  });
   if (includeHostedCheck && answers.apiKeyType !== "none" && !answers.apiKey.includes("YOUR_")) {
     checks.push(...await testHostedConnection(answers));
   } else if (includeHostedCheck) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",