create-snipara 1.3.17 → 1.3.18

package/README.md

@@ -52,6 +52,7 @@ The default CLI path wires the local companion around those surfaces:
 
 - `snipara-companion` for local workflow commands and managed phase commits; legacy `rlm-hook` commands remain compatible
 - `snipara-sandbox` for optional local code execution
+- `snipara-orchestrator` only when explicitly requested with `--with-orchestrator`
 - local config, env files, hook scripts, and a project companion pack
 - `snipara-mcp` only for local stdio compatibility, development, or testing
 
@@ -59,12 +60,12 @@ The default CLI path wires the local companion around those surfaces:
 
 The CLI now works around explicit install profiles:
 
-| Profile            | What it installs                              | Best for                                            |
-| ------------------ | --------------------------------------------- | --------------------------------------------------- |
-| `hosted-companion` | MCP + `snipara-companion`                     | Default: hosted context plus managed local workflow |
-| `hosted-only`      | Hosted MCP config only                        | Locked-down or minimal environments                 |
-| `full-stack`       | MCP + `snipara-companion` + `snipara-sandbox` | Hosted context plus sandboxed local execution       |
-| `runtime-only`     | `snipara-sandbox` only                        | Local execution without hosted API                  |
+| Profile            | What it installs                              | Best for                                                                                                            |
+| ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `hosted-companion` | MCP + `snipara-companion`                     | Default: hosted context plus managed local workflow                                                                 |
+| `hosted-only`      | Hosted MCP config only                        | Locked-down or minimal environments                                                                                 |
+| `full-stack`       | MCP + `snipara-companion` + `snipara-sandbox` | Hosted context plus sandboxed local execution. Does not include orchestrator unless `--with-orchestrator` is passed |
+| `runtime-only`     | `snipara-sandbox` only                        | Local execution without hosted API                                                                                  |
 
 Default profile: `hosted-companion`
 
@@ -102,6 +103,7 @@ That distinction matters:
 - 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`
+- installs optional `snipara-orchestrator` for proof gates, drift checks, and htask workflows when requested
 - configures `.mcp.json`
 - generates merge-ready AI agent templates in `.snipara/templates/`, including Pro+ symbol-card, code-impact, and managed workflow guidance for paid Context plans
 - creates `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/snipara.mdc`, and `.codex/config.toml` when those files do not already exist
@@ -140,6 +142,8 @@ By default, this uses the recommended `hosted-companion` setup: hosted MCP plus
 the local `snipara-companion` workflow helper. Legacy `rlm-hook` commands remain
 compatible. Add `--advanced` when you want profile selection, project id entry,
 hook prompts, GitHub automation prompts, or sandbox provider prompts.
+Use `--with-orchestrator` only when you explicitly need the advanced production
+validation and htask package; it is not part of `full-stack` by default.
 
 The advanced flow asks for:
 
@@ -421,6 +425,16 @@ npx create-snipara --profile full-stack --advanced
 
 Best when the user also wants sandboxed `snipara-sandbox` execution.
 
+### Full local stack plus production orchestration
+
+```bash
+npx create-snipara --profile full-stack --with-orchestrator
+```
+
+Best when the user wants Hosted MCP, companion workflows, Sandbox execution, and
+the explicit `snipara-orchestrator` package for production gates, drift checks,
+or htask coordination.
+
 ### Connect the current repository
 
 ```bash

package/dist/index.js

@@ -9,7 +9,7 @@ import fs from "fs";
 import path from "path";
 import { execSync, spawn } from "child_process";
 import { homedir } from "os";
-var VERSION = "1.3.17";
+var VERSION = "1.3.18";
 var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
@@ -18,10 +18,12 @@ 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 ORCHESTRATOR_PACKAGE_NAME = "snipara-orchestrator";
 var SANDBOX_SERVER_NAME = "snipara-sandbox";
 var LEGACY_RUNTIME_SERVER_NAME = "rlm-runtime";
 var SANDBOX_COMMAND_NAME = "snipara-sandbox";
 var LEGACY_SANDBOX_COMMAND_NAME = "rlm";
+var ORCHESTRATOR_COMMAND_NAME = "snipara-orchestrator";
 var DEVICE_CLIENT_ID = "create-snipara";
 var DeviceAuthorizationAborted = class extends Error {
 };
@@ -94,7 +96,7 @@ function buildProgram() {
   program.command("init").description("Install and configure Snipara for this project").option("--api-key <key>", "Snipara API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option("--advanced", "Show advanced profile, project id, hooks, GitHub, and sandbox prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
-  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").option("-y, --yes", "Accept defaults without prompting").action(async (options) => {
+  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").option("-y, --yes", "Accept defaults without prompting").action(async (options) => {
     printBanner();
     await runInit(options);
   });
@@ -102,11 +104,11 @@ function buildProgram() {
     printBanner();
     await runDoctor(options);
   });
-  program.command("repair").description("Rebuild local Snipara config and re-run validation").option("--api-key <key>", "Snipara API key override").option("--slug <slug>", "Project slug override").option("--project-id <id>", "Project ID override").option("--profile <profile>", "Target install profile").option("--with-hooks", "Force hook generation").option("--with-runtime", "Force Snipara Sandbox server/config").option("--with-mcp", "Force MCP config").option("--with-companion", "Force companion pack generation").action(async (options) => {
+  program.command("repair").description("Rebuild local Snipara config and re-run validation").option("--api-key <key>", "Snipara API key override").option("--slug <slug>", "Project slug override").option("--project-id <id>", "Project ID override").option("--profile <profile>", "Target install profile").option("--with-hooks", "Force hook generation").option("--with-runtime", "Force Snipara Sandbox server/config").option("--with-mcp", "Force MCP config").option("--with-companion", "Force companion pack generation").option("--with-orchestrator", "Install optional snipara-orchestrator package").action(async (options) => {
     printBanner();
     await runRepair(options);
   });
-  program.command("upgrade").description("Upgrade installed Snipara local components").option("--with-hooks", "Refresh hooks after upgrade").option("--with-runtime", "Upgrade Snipara Sandbox even if not detected").option("--with-mcp", "Upgrade snipara-mcp even if not detected").option("--with-companion", "Upgrade companion even if not detected").action(async (options) => {
+  program.command("upgrade").description("Upgrade installed Snipara local components").option("--with-hooks", "Refresh hooks after upgrade").option("--with-runtime", "Upgrade Snipara Sandbox even if not detected").option("--with-mcp", "Upgrade snipara-mcp even if not detected").option("--with-companion", "Upgrade companion even if not detected").option("--with-orchestrator", "Upgrade snipara-orchestrator even if not detected").action(async (options) => {
     printBanner();
     await runUpgrade(options);
   });
@@ -125,7 +127,7 @@ function addSharedRootOptions(program) {
   program.option("--api-key <key>", "Snipara API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option("--advanced", "Show advanced profile, project id, hooks, GitHub, and sandbox prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
-  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").option("-y, --yes", "Accept defaults without prompting");
+  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").option("-y, --yes", "Accept defaults without prompting");
 }
 async function main() {
   const program = buildProgram();
@@ -157,6 +159,7 @@ function parseInitOptionsFromArgv(args) {
     "--skip-runtime": "skipRuntime",
     "--skip-hooks": "skipHooks",
     "--skip-test": "skipTest",
+    "--with-orchestrator": "withOrchestrator",
     "--runtime-only": "runtimeOnly",
     "--github": "github",
     "--skip-github": "skipGithub",
@@ -187,7 +190,7 @@ function parseInitOptionsFromArgv(args) {
 }
 async function runInit(options) {
   const answers = await gatherConfiguration(normalizeInitOptions(options));
-  if (answers.installMcp || answers.installRuntime) {
+  if (answers.installMcp || answers.installRuntime || answers.installOrchestrator) {
     await installPythonPackages(answers, false);
   }
   if (answers.installCompanion) {
@@ -225,7 +228,7 @@ async function runDoctor(options) {
 async function runRepair(options) {
   const answers = loadExistingAnswers(options);
   console.log(chalk.bold("\n\u{1F6E0}\uFE0F  Repairing Local Setup\n"));
-  if (answers.installMcp || answers.installRuntime) {
+  if (answers.installMcp || answers.installRuntime || answers.installOrchestrator) {
     await installPythonPackages(answers, true);
   }
   if (answers.installCompanion) {
@@ -248,10 +251,11 @@ async function runUpgrade(options) {
   const upgradedAnswers = {
     ...answers,
     installMcp: options.withMcp || answers.installMcp,
-    installRuntime: options.withRuntime || answers.installRuntime
+    installRuntime: options.withRuntime || answers.installRuntime,
+    installOrchestrator: options.withOrchestrator || answers.installOrchestrator
   };
   console.log(chalk.bold("\n\u2B06\uFE0F  Upgrading Local Components\n"));
-  if (options.withMcp || options.withRuntime || detection.existingConfig.hasRuntimeServer) {
+  if (options.withMcp || options.withRuntime || options.withOrchestrator || detection.existingConfig.hasRuntimeServer || detection.tooling.orchestratorCli) {
     await installPythonPackages(upgradedAnswers, true);
   }
   if (options.withCompanion || detection.tooling.companionCli || answers.installCompanion) {
@@ -264,8 +268,8 @@ async function runUpgrade(options) {
   if (options.withHooks || answers.installHooks) {
     await installClaudeCodeHooks({ ...answers, installHooks: true });
   }
-  await createCompanionPack(answers);
-  const report = await runValidation(answers, true);
+  await createCompanionPack(upgradedAnswers);
+  const report = await runValidation(upgradedAnswers, true);
   writeDoctorReport(report);
   printDoctorReport(detectEnvironment(), report);
 }
@@ -302,6 +306,7 @@ async function runPrintConfig(options) {
   );
   console.log(`   Local snipara-mcp package: ${answers.installMcp ? "enabled" : "disabled"}`);
   console.log(`   Snipara Sandbox: ${answers.installRuntime ? "enabled" : "disabled"}`);
+  console.log(`   Snipara Orchestrator: ${answers.installOrchestrator ? "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}`);
@@ -362,6 +367,7 @@ async function gatherConfiguration(options) {
       skipCompanion: !!options.skipCompanion,
       skipMcp: !!options.skipMcp,
       skipRuntime: !!options.skipRuntime,
+      withOrchestrator: !!options.withOrchestrator,
       skipHooks: !!options.skipHooks,
       configureGitHub: Boolean(options.github && detectedGitRepo && !options.skipGithub),
       githubRepo: detectedGitRepo || void 0,
@@ -426,6 +432,12 @@ async function gatherConfiguration(options) {
       ),
       choices: AI_CLIENT_CHOICES
     },
+    {
+      type: showAdvancedPrompts ? "confirm" : null,
+      name: "installOrchestrator",
+      message: "Install snipara-orchestrator for production gates, drift checks, or htask workflows?",
+      initial: Boolean(options.withOrchestrator)
+    },
     {
       type: showAdvancedPrompts ? "confirm" : null,
       name: "installHooks",
@@ -471,6 +483,7 @@ async function gatherConfiguration(options) {
     skipCompanion: !!options.skipCompanion,
     skipMcp: !!options.skipMcp,
     skipRuntime: !!options.skipRuntime,
+    withOrchestrator: Boolean(options.withOrchestrator || response.installOrchestrator),
     skipHooks: !!options.skipHooks || !response.installHooks,
     configureGitHub: Boolean(
       (response.configureGitHub || options.github) && detectedGitRepo && !options.skipGithub
@@ -602,6 +615,7 @@ function buildAnswersFromProfile(input) {
     installCompanion: selected.installCompanion && !input.skipCompanion,
     installMcp: selected.installMcp && !input.skipMcp,
     installRuntime: selected.installRuntime && !input.skipRuntime,
+    installOrchestrator: input.withOrchestrator,
     installHooks: selected.installHooks && !input.skipHooks,
     aiClient: input.aiClient,
     configureGitHub: Boolean(input.configureGitHub && input.githubRepo),
@@ -756,6 +770,9 @@ function detectSandboxCommand() {
   }
   return null;
 }
+function detectOrchestratorCommand() {
+  return commandExists(ORCHESTRATOR_COMMAND_NAME) ? ORCHESTRATOR_COMMAND_NAME : null;
+}
 async function installPythonPackages(answers, upgrade) {
   console.log(chalk.bold(`
 \u{1F4E6} ${upgrade ? "Upgrading" : "Installing"} Python Packages
@@ -769,6 +786,11 @@ async function installPythonPackages(answers, upgrade) {
     if (answers.installRuntime) {
       console.log(chalk.gray(`      pip install ${upgrade ? "-U " : ""}${SANDBOX_PACKAGE_NAME}`));
     }
+    if (answers.installOrchestrator) {
+      console.log(
+        chalk.gray(`      pip install ${upgrade ? "-U " : ""}${ORCHESTRATOR_PACKAGE_NAME}`)
+      );
+    }
     console.log("");
     return;
   }
@@ -779,6 +801,9 @@ async function installPythonPackages(answers, upgrade) {
   if (answers.installRuntime) {
     packages.push(SANDBOX_PACKAGE_NAME);
   }
+  if (answers.installOrchestrator) {
+    packages.push(ORCHESTRATOR_PACKAGE_NAME);
+  }
   if (packages.length === 0) return;
   const spinner = ora(
     `${upgrade ? "Upgrading" : "Installing"} ${packages.map(stripExtras).join(", ")}...`
@@ -1538,6 +1563,11 @@ 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."
     },
+    {
+      title: answers.installOrchestrator ? "Run an explicit production orchestration gate" : "Enable explicit production orchestration",
+      command: answers.installOrchestrator ? `${ORCHESTRATOR_COMMAND_NAME} check-drift --route /api/health` : "npx create-snipara repair --with-orchestrator",
+      purpose: answers.installOrchestrator ? "Use snipara-orchestrator only for proof-based validation, drift checks, htasks, or multi-agent coordination." : "Install snipara-orchestrator only when production gates, drift checks, htasks, or multi-agent coordination are required."
+    },
     githubAnswerPacksCommand,
     {
       title: "Upload or refresh a doc",
@@ -1715,6 +1745,7 @@ This project uses Snipara as a hosted-first context and memory layer with local
 - Generated hosted MCP config: \`${answers.profile !== "runtime-only" ? "yes" : "no"}\`
 - Installed local snipara-mcp package: \`${answers.installMcp ? "yes" : "no"}\`
 - Installed Snipara Sandbox: \`${answers.installRuntime ? "yes" : "no"}\`
+- Installed Snipara Orchestrator: \`${answers.installOrchestrator ? "yes" : "no"}\`
 - Generated hooks: \`${answers.installHooks ? "yes" : "no"}\`
 - GitHub repository: \`${answers.githubRepo ? answers.githubRepo.fullName : "not-detected"}\`
 
@@ -1725,6 +1756,7 @@ This project uses Snipara as a hosted-first context and memory layer with local
 - .env.local present: \`${detection.files.envLocal ? "yes" : "no"}\`
 - Companion CLI on PATH: \`${detection.tooling.companionCli ? "yes" : "no"}\`
 - Snipara Sandbox CLI on PATH: \`${detection.tooling.runtimeCli ? "yes" : "no"}\`
+- Snipara Orchestrator CLI on PATH: \`${detection.tooling.orchestratorCli ? "yes" : "no"}\`
 
 ## Client Guidance
 
@@ -1790,6 +1822,7 @@ ${item.purpose}`
     ai_client: answers.aiClient,
     profile: answers.profile,
     llm_provider: answers.llmProvider || null,
+    install_orchestrator: answers.installOrchestrator,
     github_repository: answers.githubRepo || null,
     github_automation_url: answers.githubRepo ? buildGitHubAutomationUrl(answers) : null,
     client_pack: clientPackFilename,
@@ -1895,6 +1928,11 @@ async function runValidation(answers, includeHostedCheck) {
     status: answers.installRuntime ? detection.tooling.runtimeCli ? "pass" : "warn" : "pass",
     detail: answers.installRuntime && !detection.tooling.runtimeCli ? `${SANDBOX_COMMAND_NAME} CLI not found on PATH` : "Snipara Sandbox CLI ready or not requested"
   });
+  checks.push({
+    name: "orchestrator_cli",
+    status: answers.installOrchestrator ? detection.tooling.orchestratorCli ? "pass" : "warn" : "pass",
+    detail: answers.installOrchestrator && !detection.tooling.orchestratorCli ? `${ORCHESTRATOR_COMMAND_NAME} CLI not found on PATH` : "Snipara Orchestrator ready or not requested"
+  });
   checks.push({
     name: "companion_pack",
     status: detection.files.sniparaCompanionPack ? "pass" : "warn",
@@ -2096,6 +2134,11 @@ function printSuccess(answers, report) {
       chalk.green(`   \u2713 ${stripExtras(SANDBOX_PACKAGE_NAME)}`) + chalk.dim(" - Safe code execution")
     );
   }
+  if (answers.installOrchestrator) {
+    console.log(
+      chalk.green(`   \u2713 ${ORCHESTRATOR_PACKAGE_NAME}`) + chalk.dim(" - Production gates, drift checks, and htask workflows")
+    );
+  }
   if (answers.installCompanion) {
     console.log(
       chalk.green(`   \u2713 ${COMPANION_PACKAGE_NAME}`) + chalk.dim(" - Local companion workflows and hook bootstrap")
@@ -2147,6 +2190,11 @@ function printSuccess(answers, report) {
       `Run ${SANDBOX_COMMAND_NAME} init when you want to choose sandbox/docker/local execution.`
     );
   }
+  if (answers.installOrchestrator) {
+    printNextStep(
+      `Use ${ORCHESTRATOR_COMMAND_NAME} explicitly for production proof gates, drift checks, or htask coordination.`
+    );
+  }
   if (answers.githubRepo) {
     printNextStep(
       `Connect GitHub automation for ${answers.githubRepo.fullName} from the generated Snipara link.`
@@ -2213,7 +2261,8 @@ function detectEnvironment() {
       docker: commandExists("docker"),
       git: commandExists("git"),
       companionCli: Boolean(detectCompanionCommand()),
-      runtimeCli: Boolean(detectSandboxCommand())
+      runtimeCli: Boolean(detectSandboxCommand()),
+      orchestratorCli: Boolean(detectOrchestratorCommand())
     },
     existingConfig: {
       slug: existingConfig?.slug,
@@ -2243,6 +2292,7 @@ function loadExistingAnswers(options) {
     skipCompanion: options.withCompanion === true ? false : !detection.tooling.companionCli && effectiveProfile !== "hosted-companion" && effectiveProfile !== "full-stack",
     skipMcp: options.withMcp === true ? false : !detection.existingConfig.hasSniparaServer && effectiveProfile === "runtime-only",
     skipRuntime: options.withRuntime === true ? false : !detection.existingConfig.hasRuntimeServer && effectiveProfile !== "full-stack" && effectiveProfile !== "runtime-only",
+    withOrchestrator: Boolean(options.withOrchestrator || detection.tooling.orchestratorCli),
     skipHooks: options.withHooks ? false : detection.aiClient !== "claude-code"
   });
 }

package/package.json

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