create-snipara 1.3.38 → 1.3.40

package/README.md

@@ -208,7 +208,7 @@ Writes `.snipara/companion/doctor.json` and validates:
 For Claude-specific support, run:
 
 ```bash
-npx create-snipara doctor --client claude
+npx create-snipara doctor --client claude-code
 ```
 
 This separates "Snipara config was written" from "Claude actually loaded the MCP

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "1.3.38",
+  version: "1.3.40",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -88,6 +88,8 @@ 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 COMPANION_NPX_COMMAND = "npx -y snipara-companion@latest";
+var MIN_COMPANION_VERSION = "1.1.37";
 var GITHUB_ANSWER_PACKS_LABEL = "GitHub PR Answer Packs";
 var MCP_PACKAGE_NAME = "snipara-mcp";
 var SANDBOX_PACKAGE_NAME = "snipara-sandbox[all]";
@@ -605,7 +607,10 @@ async function gatherConfiguration(options) {
   let signupResult = null;
   if (!apiKey && response.profile !== "runtime-only") {
     if (response.apiKeyType === "signup") {
-      signupResult = await handleSignup();
+      signupResult = await handleSignup({
+        projectHint: response.projectSlug,
+        repoHint: detectedGitRepo?.fullName
+      });
       apiKey = signupResult.apiKey;
       apiKeyType = "api";
     } else if (response.apiKeyType === "api") {
@@ -798,10 +803,10 @@ function buildAnswersFromProfile(input) {
     githubPath: input.githubPath
   };
 }
-async function handleSignup() {
+async function handleSignup(hints = {}) {
   console.log(chalk.bold("\n\u{1F510} Browser Account Authorization\n"));
   try {
-    return await runDeviceAuthorization();
+    return await runDeviceAuthorization(hints);
   } catch (error) {
     if (error instanceof DeviceAuthorizationAborted) {
       throw error;
@@ -829,7 +834,27 @@ async function handleManualSignup() {
   });
   return { apiKey: response.apiKey };
 }
-async function runDeviceAuthorization() {
+function normalizeDeviceFlowHint(value) {
+  const normalized = value?.trim();
+  return normalized && !normalized.includes("<") && !normalized.includes(">") ? normalized : null;
+}
+function appendDeviceFlowHints(url, hints) {
+  try {
+    const parsed = new URL(url);
+    const projectHint = normalizeDeviceFlowHint(hints.projectHint);
+    const repoHint = normalizeDeviceFlowHint(hints.repoHint);
+    if (projectHint) {
+      parsed.searchParams.set("project_hint", projectHint);
+    }
+    if (repoHint) {
+      parsed.searchParams.set("repo_hint", repoHint);
+    }
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+async function runDeviceAuthorization(hints = {}) {
   const codeResponse = await postJson(`${BASE_URL}/api/oauth/device/code`, {
     client_id: DEVICE_CLIENT_ID,
     scope: "mcp:read mcp:write",
@@ -838,11 +863,10 @@ async function runDeviceAuthorization() {
   if (codeResponse.error) {
     throw new Error(codeResponse.error_description || codeResponse.error);
   }
-  console.log(
-    chalk.cyan(`   Opening ${codeResponse.verification_uri_complete} in your browser...`)
-  );
+  const verificationUrl = appendDeviceFlowHints(codeResponse.verification_uri_complete, hints);
+  console.log(chalk.cyan(`   Opening ${verificationUrl} in your browser...`));
   console.log(chalk.dim(`   Device code: ${codeResponse.user_code}`));
-  openBrowser(codeResponse.verification_uri_complete);
+  openBrowser(verificationUrl);
   const spinner = ora("Waiting for Snipara authorization in the browser...").start();
   const startedAt = Date.now();
   let intervalMs = Math.max(1, codeResponse.interval || 5) * 1e3;
@@ -938,8 +962,40 @@ function isProvisionedApiKey(value) {
 function provisionedApiKeyValidationMessage() {
   return "New Snipara API keys should start with snp-";
 }
+function normalizeSemver(value) {
+  const match = value?.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}
+function getCompanionCommandVersion() {
+  if (!commandExists(COMPANION_COMMAND_NAME)) {
+    return null;
+  }
+  try {
+    return execSync(`${COMPANION_COMMAND_NAME} --version`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1e3
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function isSupportedCompanionVersion(version) {
+  const current = normalizeSemver(version);
+  return Boolean(current && compareSemver(current, MIN_COMPANION_VERSION) >= 0);
+}
+function getCompanionRequirementMessage() {
+  const version = getCompanionCommandVersion();
+  if (!version) {
+    return `${COMPANION_PACKAGE_NAME} not found on PATH`;
+  }
+  return `${COMPANION_PACKAGE_NAME} ${version} is older than required ${MIN_COMPANION_VERSION}`;
+}
 function detectCompanionCommand() {
-  if (commandExists(COMPANION_COMMAND_NAME)) {
+  if (isSupportedCompanionVersion(getCompanionCommandVersion())) {
     return COMPANION_COMMAND_NAME;
   }
   return null;
@@ -1033,11 +1089,11 @@ function detectNodePackageManagers() {
   }
   return managers;
 }
-function getCompanionInstallCommand(packageManager, upgrade) {
+function getCompanionInstallCommand(packageManager, _upgrade) {
   if (packageManager === "pnpm") {
-    return `pnpm add -g ${upgrade ? "--latest " : ""}${COMPANION_PACKAGE_NAME}`;
+    return `pnpm add -g ${COMPANION_PACKAGE_NAME}@latest`;
   }
-  return `npm install -g ${upgrade ? COMPANION_PACKAGE_NAME + "@latest" : COMPANION_PACKAGE_NAME}`;
+  return `npm install -g ${COMPANION_PACKAGE_NAME}@latest`;
 }
 async function installNodeCompanion(upgrade) {
   console.log(chalk.bold(`
@@ -1046,7 +1102,7 @@ async function installNodeCompanion(upgrade) {
   const packageManagers = detectNodePackageManagers();
   if (packageManagers.length === 0) {
     console.log(chalk.yellow("   \u26A0\uFE0F  npm/pnpm not found. Please install manually:\n"));
-    console.log(chalk.gray(`      npm install -g ${COMPANION_PACKAGE_NAME}
+    console.log(chalk.gray(`      npm install -g ${COMPANION_PACKAGE_NAME}@latest
 `));
     return;
   }
@@ -1082,12 +1138,8 @@ async function installNodeCompanion(upgrade) {
     console.log(chalk.gray(`   - ${failure}`));
   }
   console.log(chalk.yellow("\n   Install manually with:"));
-  console.log(
-    chalk.gray(
-      `   npm install -g ${upgrade ? COMPANION_PACKAGE_NAME + "@latest" : COMPANION_PACKAGE_NAME}
-`
-    )
-  );
+  console.log(chalk.gray(`   npm install -g ${COMPANION_PACKAGE_NAME}@latest
+`));
 }
 async function createMcpConfig(answers) {
   console.log(chalk.bold("\n\u2699\uFE0F  Creating Configuration\n"));
@@ -1793,7 +1845,7 @@ function getClientGuidance(client) {
   if (client === "windsurf") {
     return [
       "Windsurf should use the hosted MCP surface plus generated Windsurf automation bundles when available.",
-      "Use snipara-companion automations install --client windsurf when you want dashboard-managed hook files in the local project."
+      "Use npx -y snipara-companion@latest automations install --client windsurf when you want dashboard-managed hook files in the local project."
     ];
   }
   if (client === "codex") {
@@ -1843,19 +1895,19 @@ function getCompanionCommands(answers) {
   const businessOnboardingCommands = answers.installCompanion ? [
     {
       title: "Preview a business folder import",
-      command: `${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`,
+      command: `${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`,
       purpose: "Classify a local or LLM-materialized business folder and review the Snipara sync manifest before upload."
     },
     {
       title: "Apply a business folder import",
-      command: `${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply`,
+      command: `${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply`,
       purpose: "Upload approved business-context documents to hosted Snipara and trigger document reindexing."
     }
   ] : [
     {
       title: "Enable business folder onboarding",
       command: "npx create-snipara repair --with-companion",
-      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_COMMAND_NAME} onboard-folder without using the dashboard.`
+      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_NPX_COMMAND} onboard-folder without using the dashboard.`
     }
   ];
   const githubAnswerPacksCommand = answers.githubRepo ? {
@@ -1870,7 +1922,7 @@ function getCompanionCommands(answers) {
   return [
     {
       title: "Bootstrap local companion",
-      command: `${COMPANION_COMMAND_NAME} init${clientFlag}${projectFlag}`,
+      command: `${COMPANION_NPX_COMMAND} init${clientFlag}${projectFlag}`,
       purpose: "Re-run local companion setup if this workstation needs to refresh browser login or project selection."
     },
     {
@@ -1885,32 +1937,32 @@ function getCompanionCommands(answers) {
     },
     {
       title: "Run a focused hosted query",
-      command: `${COMPANION_COMMAND_NAME} query --query "how does auth middleware work?" --max-tokens 4000`,
+      command: `${COMPANION_NPX_COMMAND} query --query "how does auth middleware work?" --max-tokens 4000`,
       purpose: "Pull ranked source context before editing, reviewing, or drafting."
     },
     {
       title: "Load linked standards only when needed",
-      command: `${COMPANION_COMMAND_NAME} shared-context --categories MANDATORY BEST_PRACTICES`,
+      command: `${COMPANION_NPX_COMMAND} shared-context --categories MANDATORY BEST_PRACTICES`,
       purpose: "Fetch project-linked team or workspace guidance without treating it as memory."
     },
     {
       title: "Generate a hosted plan",
-      command: `${COMPANION_COMMAND_NAME} plan --query "Implement webhook retry hardening" --max-tokens 3000`,
+      command: `${COMPANION_NPX_COMMAND} plan --query "Implement webhook retry hardening" --max-tokens 3000`,
       purpose: "Produce a structured execution plan against indexed project knowledge."
     },
     {
       title: "Start a managed workflow from the visible plan",
-      command: `${COMPANION_COMMAND_NAME} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md`,
+      command: `${COMPANION_NPX_COMMAND} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md`,
       purpose: "Record the LLM-visible plan in .snipara/workflow/current.json so phase state survives compaction."
     },
     {
       title: "Start the current workflow phase",
-      command: `${COMPANION_COMMAND_NAME} workflow phase-start context`,
+      command: `${COMPANION_NPX_COMMAND} workflow phase-start context`,
       purpose: "Mark a phase active and print the required Snipara context gate for the agent."
     },
     {
       title: "Analyze code impact before a risky change",
-      command: `${COMPANION_COMMAND_NAME} code impact --changed-files src/api/webhooks.ts tests/webhooks.test.ts --diff-summary "webhook retry hardening"`,
+      command: `${COMPANION_NPX_COMMAND} 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."
     },
     {
@@ -1921,48 +1973,48 @@ function getCompanionCommands(answers) {
     githubAnswerPacksCommand,
     {
       title: "Upload or refresh a doc",
-      command: `${COMPANION_COMMAND_NAME} upload --path docs/local-playbook.md --file ./docs/local-playbook.md`,
+      command: `${COMPANION_NPX_COMMAND} upload --path docs/local-playbook.md --file ./docs/local-playbook.md`,
       purpose: "Push local notes or docs into hosted Snipara context."
     },
     ...businessOnboardingCommands,
     {
       title: "Inspect a specific chunk",
-      command: `${COMPANION_COMMAND_NAME} chunk get --chunk-id <chunk_id>`,
+      command: `${COMPANION_NPX_COMMAND} chunk get --chunk-id <chunk_id>`,
       purpose: "Open an exact chunk returned by references-based search."
     },
     {
       title: "Bootstrap the session memory view",
-      command: `${COMPANION_COMMAND_NAME} session-bootstrap`,
+      command: `${COMPANION_NPX_COMMAND} 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`,
+      command: `${COMPANION_NPX_COMMAND} 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`,
+      command: `${COMPANION_NPX_COMMAND} 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`,
+      command: `${COMPANION_NPX_COMMAND} recall --query "What did we decide about auth retries?" --type decision`,
       purpose: "Query durable memory for past decisions, preferences, or validated learnings."
     },
     {
       title: "Commit durable task memory",
-      command: `${COMPANION_COMMAND_NAME} task-commit --summary "Hardened webhook retries and updated tests" --category engineering --outcome completed --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} task-commit --summary "Hardened webhook retries and updated tests" --category engineering --outcome completed --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist reusable outcomes back into hosted memory after the work is done."
     },
     {
       title: "Commit a managed workflow phase",
-      command: `${COMPANION_COMMAND_NAME} workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist this phase through hosted memory and advance the local managed workflow state."
     },
     {
       title: "Commit the final managed workflow result",
-      command: `${COMPANION_COMMAND_NAME} final-commit --summary "Shipped webhook retry hardening and tests" --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} final-commit --summary "Shipped webhook retry hardening and tests" --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist the final workflow outcome and close the managed workflow after verification."
     }
   ];
@@ -2029,7 +2081,7 @@ function getClientConfigArtifacts(client) {
 }
 function getClientAutomationCommand(client) {
   const companionClient = getCompanionInitClientFlag(client).match(/--client\s+(\S+)/)?.[1];
-  return companionClient ? `${COMPANION_COMMAND_NAME} automations install --client ${companionClient}` : null;
+  return companionClient ? `${COMPANION_NPX_COMMAND} automations install --client ${companionClient}` : null;
 }
 function buildClientPackMarkdown(answers, commands, guidance) {
   const clientName = getClientDisplayName(answers.aiClient);
@@ -2054,7 +2106,7 @@ ${getClientConfigArtifacts(answers.aiClient).map((item) => `- \`${item}\``).join
 
 ## Recommended Setup
 
-${bootstrapCommand ? `1. Bootstrap companion: \`${bootstrapCommand.command}\`` : "1. Bootstrap companion with `snipara-companion init`."}
+${bootstrapCommand ? `1. Bootstrap companion: \`${bootstrapCommand.command}\`` : `1. Bootstrap companion with \`${COMPANION_NPX_COMMAND} init\`.`}
 2. Confirm the client can list or call the \`snipara_*\` MCP tools.
 3. Keep exact edits, tests, and dirty working-tree checks local; use Snipara for memory, source truth, and indexed code graph context.
 ${automationCommand ? `4. For generated local automations, run \`${automationCommand}\` when that client exposes usable automation files.` : "4. This client is treated as MCP-first; no local hook surface is assumed."}
@@ -2068,6 +2120,7 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 - Start substantial work with \`snipara_recall\` and \`snipara_context_query\`.
 - Use \`answer_pack\` facts, caveats, source maps, and verification checks before making claims.
 - Use \`snipara_code_symbol_card\` and \`snipara_code_impact\` for important symbols or risky multi-file changes when available.
+- Use the installed \`snipara-companion\` binary for low-latency hooks; use \`${COMPANION_NPX_COMMAND}\` for one-off terminal commands when freshness matters.
 - Use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` for multi-phase work.
 - Persist only durable decisions, learnings, preferences, workflows, and troubleshooting outcomes. Never persist secrets.
 `;
@@ -2118,11 +2171,11 @@ Use this when Claude, ChatGPT, Codex, or another LLM client has already material
 
 ${answers.installCompanion ? `Preview first:
 
-\`${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json\`
+\`${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json\`
 
 Apply only after reviewing the manifest:
 
-\`${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply\`` : `This setup did not install snipara-companion. Enable it before business folder imports:
+\`${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply\`` : `This setup did not install snipara-companion. Enable it before business folder imports:
 
 \`npx create-snipara repair --with-companion\``}
 
@@ -2427,7 +2480,7 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
   checks.push({
     name: "companion_cli",
     status: answers.installCompanion ? detection.tooling.companionCli ? "pass" : "fail" : "pass",
-    detail: answers.installCompanion && !detection.tooling.companionCli ? `${COMPANION_PACKAGE_NAME} not found on PATH` : "Companion CLI ready or not requested"
+    detail: answers.installCompanion && !detection.tooling.companionCli ? getCompanionRequirementMessage() : "Companion CLI ready or not requested"
   });
   checks.push({
     name: "sandbox_cli",
@@ -2735,7 +2788,9 @@ function printSuccess(answers, report) {
     printNextStep(
       "For Claude Code, start a new session and confirm Snipara appears in Settings -> MCP or ToolSearch."
     );
-    printNextStep("If Snipara tools are missing, run: npx create-snipara doctor --client claude");
+    printNextStep(
+      "If Snipara tools are missing, run: npx create-snipara doctor --client claude-code"
+    );
   }
   if (answers.aiClient === "claude-desktop") {
     printNextStep(
@@ -2753,15 +2808,17 @@ function printSuccess(answers, report) {
   printNextStep("Open .snipara/companion/README.md for local commands and repair flow.");
   printNextStep("Run create-snipara doctor anytime you want a fresh local validation report.");
   if (answers.installCompanion) {
-    printNextStep(`${COMPANION_COMMAND_NAME} is the companion command for local workflow helpers.`);
     printNextStep(
-      `Use ${COMPANION_COMMAND_NAME} query / plan / upload / task-commit for explicit local workflows.`
+      `${COMPANION_COMMAND_NAME} ${MIN_COMPANION_VERSION}+ is installed for low-latency local hooks.`
+    );
+    printNextStep(
+      `Use ${COMPANION_NPX_COMMAND} query / plan / upload / task-commit for explicit local workflows.`
     );
     printNextStep(
-      `For business folders, preview with: ${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`
+      `For business folders, preview with: ${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`
     );
     printNextStep(
-      `Apply after review with: ${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply`
+      `Apply after review with: ${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply`
     );
   } else if (answers.profile !== "runtime-only") {
     printNextStep(

package/package.json

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