@runcofactor/cli 0.10.0

package/dist/chunk-4NRDONSC.js

@@ -0,0 +1,1048 @@
+import { createRequire as __cr } from "module"; const require = __cr(import.meta.url);
+
+// ../content/src/print-guide.ts
+function printGuide(allSections, section, json) {
+  const sections = section ? allSections.filter((s) => s.slug === section) : allSections;
+  if (section && sections.length === 0) {
+    console.error(
+      `Unknown guide section: "${section}". Available: ${allSections.map((s) => s.slug).join(", ")}`
+    );
+    process.exit(1);
+  }
+  if (json) {
+    console.log(JSON.stringify(sections, null, 2));
+    return;
+  }
+  for (const s of sections) {
+    console.log(`
+${"=".repeat(72)}`);
+    console.log(`  ${s.title}`);
+    console.log(`${"=".repeat(72)}
+`);
+    console.log(s.content);
+    console.log("");
+  }
+}
+
+// ../content/src/sandbox-guide.ts
+var GOAL = {
+  title: "Goal & Tools",
+  slug: "goal",
+  content: `
+Your goal is to turn a git repository into a running, containerized development
+environment. The end state is a sandbox URL that loads the app in a browser.
+
+WORKFLOW:
+  1. canary sandbox create <property>          Create a template + authoring instance
+  2. Research the app                          Read the codebase to understand what it needs
+  3. Set config values                         API keys, secrets \u2192 pushed to instance as .canary/.env
+  4. Upload artifacts                          Dockerfile, docker-compose, setup script, etc. \u2192 pushed to instance
+  5. canary sandbox build <instance-id>        Build images, start containers, generate nginx
+  6. Check diagnostics & logs                  Verify the app is running
+  7. Fix artifacts, re-upload, re-build        Iterate until the app loads in browser
+  8. Mark checklist items complete              Record what you did
+
+Each artifact upload and config set immediately pushes the file to the instance.
+The "build" command triggers the actual rebuild and restart.
+Batch your changes (upload all artifacts, set all config), then build once.
+
+YOUR TOOLS:
+
+  Config \u2014 set environment variables (pushed to instance .canary/.env immediately):
+    canary sandbox config set <template-id> <key> <value>
+    canary sandbox config list <template-id>
+
+    SANDBOX_URL is auto-injected \u2014 use it in compose for browser-facing URLs.
+
+  Artifacts \u2014 files that define the sandbox (pushed to instance on upload):
+    canary sandbox artifact create <template-id> <type> <file>
+    canary sandbox artifact get <template-id> <type>
+
+    Types: dockerfile, docker-compose, setup-script, startup-script, seed-script, file
+
+  Build \u2014 rebuild and start services:
+    canary sandbox build <instance-id>
+    canary sandbox build <instance-id> --no-wait
+
+    Generates nginx routing, injects Docker networking, writes file artifacts,
+    runs setup script, then runs compose up, then runs startup script.
+    Call this after uploading artifacts.
+
+    First builds on large projects may exceed gateway timeouts. The CLI handles
+    this automatically \u2014 it detects the timeout and polls diagnostics until
+    containers are healthy. Use --no-wait to fire-and-forget and poll manually.
+
+  Diagnostics & logs \u2014 check container health and read service output:
+    canary sandbox diagnostics <instance-id>
+    canary sandbox logs <instance-id> --service <name>
+
+  Run-command \u2014 escape hatch for debugging and one-off commands:
+    canary sandbox run-command <instance-id> "<command>"
+
+  Checklist \u2014 record your progress:
+    canary sandbox checklist <template-id>
+    canary sandbox checklist complete <template-id> <item-id> [options]
+    canary sandbox checklist skip <template-id> <item-id>
+
+PRINCIPLES:
+  - Artifacts are the source of truth. Every fix must update the artifact file and re-upload.
+  - Never patch source files. Use Docker env vars, CMD overrides, setup/startup scripts.
+  - Code is volume-mounted at /workspace, not baked into the image.
+  - The platform handles nginx routing and Docker networking \u2014 you don't need to.
+`.trim()
+};
+var RESEARCH = {
+  title: "Research the App",
+  slug: "research",
+  content: `
+Before writing any artifacts, research the application thoroughly.
+
+1. ENV VAR VALIDATION
+   Find the app's environment validation schema (Zod, Joi, dotenv, etc.).
+   List ALL required (non-optional) variables. Many apps fail fast on missing vars.
+
+   Common locations:
+     - src/env.ts, src/config.ts, src/environment.ts
+     - .env.example, .env.sample
+
+   Classify each var:
+     - AUTO-WIRED: Internal service URLs (DATABASE_URL, REDIS_URL) \u2014 hardcode in compose
+     - PLACEHOLDER: OAuth creds, S3 buckets \u2014 use dummy values, app boots without them
+     - SENSITIVE: API keys (ANTHROPIC_API_KEY) \u2014 goes in template configSchema
+     - DISABLED: Worker flags, schedulers \u2014 set to false in compose
+
+2. REQUIRED SERVICES
+   What databases, caches, queues does the app need?
+   Check: docker-compose.yml, package.json deps, infra/ configs, README
+   Common: PostgreSQL, Redis, MongoDB, RabbitMQ, Elasticsearch
+
+3. MIGRATION STRATEGY
+   Does the migrate script depend on cloud tooling (SST, AWS SDK, Terraform)?
+   If yes, use the ORM's CLI directly in the startup script via "sb-compose exec":
+     - Drizzle: sb-compose exec -T app-api bash -c 'cd /app/packages/db && bun run drizzle-kit migrate'
+     - Prisma:  sb-compose exec -T app-api bash -c 'bunx prisma migrate deploy'
+     - Rails:   sb-compose exec -T app-api rails db:migrate
+     - Django:  sb-compose exec -T app-api python manage.py migrate
+   Put migrations in the startup script, NOT as a compose service (see Artifacts).
+   Do NOT use bunx for JS migrations \u2014 it downloads a fresh copy. Use "bun run" instead.
+
+4. PACKAGE BUILD ORDER (monorepos)
+   Which workspace packages export from dist/ and must be pre-built?
+   Check package.json "main" or "exports" fields for "./dist/" references.
+   These builds go in the startup script via sb-compose exec, NOT the Dockerfile.
+   When running scripts via sb-compose exec, cd to the package directory
+   where the dependency is declared. Bun workspace module resolution won't
+   find deps from the monorepo root.
+
+5. DEV SERVER HOST RESTRICTIONS
+   Modern dev servers block unknown hostnames:
+     - Vite 5.4+: upload a wrapper config via "file" artifact with allowedHosts: true
+     - Vite 6+: --allowedHosts all works as a CLI flag in compose command
+     - Next.js: hostname config in next.config.js
+     - Webpack: allowedHosts in devServer config
+   Fix via file artifact or compose CMD override \u2014 never patch the config file.
+   Check the Vite version in package.json \u2014 if >= 5.4, create the allowedHosts
+   file artifact PROACTIVELY before the first build, not after a browser error.
+
+   GOTCHA \u2014 relative imports from the wrapper config:
+     File artifacts can only land under /workspace/.canary/ (see Artifacts \u2192
+     PLATFORM ARCHITECTURE). But Vite resolves esbuild imports inside a
+     --config file relative to the config file's *own location*, not the
+     working_dir. So if your wrapper does
+         import baseConfig from "./vite.config";
+     and you point vite at /app/.canary/vite.sandbox.config.ts, esbuild
+     looks for /app/.canary/vite.config.ts and fails.
+     Fix: stage the wrapper into the repo tree at setup time. Add a
+     setup-script artifact that does
+         cp /workspace/.canary/vite.sandbox.config.ts \\
+            /workspace/apps/web/vite.sandbox.config.ts
+     and reference the file via its repo-tree name in compose
+     (\`--config vite.sandbox.config.ts\` with working_dir /app/apps/web).
+     The .canary/ copy stays the source of truth; the staged copy is just
+     a build-time stamp.
+
+6. WORKERS & DAEMONS TO DISABLE
+   Sandbox typically only needs the API server + web frontend.
+   Disable: job runners, schedulers, stall detectors, cron, coordinators.
+   Look for env flags like WORKER_ENABLED, SCHEDULER_ENABLED, etc.
+`.trim()
+};
+var ARTIFACTS = {
+  title: "Artifacts",
+  slug: "artifacts",
+  content: `
+Artifacts are the files that define your sandbox. Write them locally, then upload:
+  canary sandbox artifact create <template-id> <type> <local-file>
+
+IMPORTANT \u2014 ARTIFACT SCOPE:
+  Artifact uploads are TEMPLATE-level, not instance-level. Uploading an artifact
+  updates the template definition and pushes the file to the AUTHORING instance
+  only. Running instances provisioned from the template are NOT updated \u2014 they
+  use whatever was baked in at provision time. To apply artifact changes to an
+  existing non-authoring instance, you must rebuild it:
+    canary sandbox build <instance-id>
+
+PLATFORM ARCHITECTURE:
+  The sandbox filesystem is split into two areas:
+    - /workspace           checked-out repo and user-owned files
+    - /workspace/.canary   platform-managed compose, config, and helper scripts
+
+  Your compose file is saved as /workspace/.canary/docker-compose.override.yml and
+  merged with the platform's base compose at /workspace/.canary/docker-compose.yml,
+  which provides:
+    - nginx-proxy: reverse proxy on port 80 (routes based on sandbox.route labels)
+    - sandbox-agent: platform agent on port 8080
+    - minio: S3-compatible object store at http://minio:9000 (creds:
+      minioadmin / minioadmin). See MINIO BUCKET below \u2014 the platform
+      doesn't auto-wire the endpoint env var or create buckets for you.
+
+  You do NOT need to declare any of these in your docker-compose.yml \u2014 the
+  platform injects them. Defining a service with one of these reserved
+  names is rejected at artifact-upload time with code
+  SANDBOX_RESERVED_SERVICE_NAME. The full reserved list is:
+    nginx-proxy
+    sandbox-agent
+    minio
+    minio-init
+    docker-socket-proxy
+
+  CONTAINER PATHS \u2014 the bind mount maps the repo root to /app inside
+  containers, while file artifacts are uploaded under /workspace/.canary
+  on the host. So the same file has two paths:
+    /workspace/.canary/foo.ts   \u2190 the path you upload to from the CLI
+    /app/.canary/foo.ts         \u2190 the path your compose command/services
+                                  reference inside the container
+  Reference the in-container path in any compose \`command\` array, exec
+  call, or script file path that runs inside a service. The host-side
+  /workspace path only appears in startup.sh / setup.sh (which run on
+  the host, not inside a container).
+
+  MINIO BUCKET (S3 emulation):
+  The platform provides a MinIO container at http://minio:9000 but does
+  NOT inject AWS_ENDPOINT_URL_S3 or create your bucket. You must:
+
+    1. Wire the endpoint into your service env in compose:
+         AWS_ENDPOINT_URL_S3: http://minio:9000
+         AWS_ACCESS_KEY_ID: minioadmin
+         AWS_SECRET_ACCESS_KEY: minioadmin
+         AWS_REGION: us-east-1
+         S3_BUCKET_NAME: <your-bucket>
+
+    2. Create the bucket on every build via a one-shot service:
+         mc-init:
+           image: minio/mc
+           restart: "no"
+           entrypoint:
+             - sh
+             - -c
+             - >
+               mc alias set local http://minio:9000 minioadmin minioadmin &&
+               mc mb -p local/\${S3_BUCKET_NAME:-app-bucket} ||
+               true
+
+  Most AWS SDK v3 clients honor AWS_ENDPOINT_URL_S3 natively. If your
+  app passes a custom S3 client, also set forcePathStyle: true (MinIO
+  doesn't support virtual-host-style bucket addressing).
+
+  Compose still runs with /workspace as the project directory. That means user
+  compose content keeps the same repo-root-relative behavior for build contexts,
+  bind mounts, and referenced files.
+
+  COMPOSE INVOCATION: use the pre-installed "sb-compose" wrapper on the host.
+  It expands to docker compose with the canonical flag set:
+      docker compose --project-directory /workspace \\
+        --env-file /workspace/.canary/.env \\
+        -f /workspace/.canary/docker-compose.yml \\
+        -f /workspace/.canary/docker-compose.override.yml \\
+        "$@"
+  Call it from startup scripts, action scripts, and run-command the same way:
+      sb-compose exec -T app-api bash -c 'bun run build'
+      sb-compose ps
+      sb-compose logs --tail 50 app-api
+  The wrapper is available as /usr/local/bin/sb-compose (symlink) and
+  /workspace/.canary/sb-compose. If you invoke raw "docker compose" yourself
+  you must pass the same flags \u2014 otherwise paths and variable interpolation
+  (\${SANDBOX_URL} et al.) will resolve incorrectly.
+
+  The platform injects a shared Docker network. On "build", the sequence is:
+    1. Write file artifacts to their destination paths
+    2. Run setup script (if present)
+    3. docker compose down (cleanup previous containers)
+    4. docker compose build + up
+    5. Reload nginx
+    6. Wait for long-running services to accept "sb-compose exec" before continuing
+    7. Run startup script (if present)
+
+  Step 6 is automatic. You don't need to add your own "wait for postgres"
+  loops at the top of startup.sh \u2014 by the time startup.sh runs, every
+  non-one-shot service is exec-able. Service healthchecks inside the
+  containers (e.g. postgres pg_isready) are still your responsibility if
+  your app needs to wait on them.
+
+  Do NOT define services named "nginx-proxy", "sandbox-agent", or "minio"
+  in your compose.
+
+DOCKERFILE (type: dockerfile)
+  A base image that provides the runtime. Source code is volume-mounted, NOT copied in.
+  Written to /workspace/.canary/Dockerfile.sandbox (avoids conflicting with the repo's own Dockerfile).
+  Reference it in compose as: build: { context: ., dockerfile: .canary/Dockerfile.sandbox }
+
+  Structure:
+    FROM <runtime-base>
+    RUN apt-get update && apt-get install -y <system-deps>
+    RUN npm install -g <global-tools>
+    WORKDIR /app
+
+  Rules:
+    - NO "COPY . ." \u2014 code comes via volume mount at /workspace
+    - NO "RUN npm build" \u2014 builds happen in the setup script
+    - Include ALL system deps (chromium, ffmpeg, python, etc.)
+    - For browser automation: use mcr.microsoft.com/playwright as base
+    - Do NOT use ENTRYPOINT \u2014 it breaks one-shot services (deps, migrate) whose
+      command gets passed as args to the entrypoint instead of running directly
+
+DOCKER COMPOSE (type: docker-compose)
+  Defines all services. Platform handles networking and nginx routing.
+
+  Typical services:
+    deps (one-shot)    \u2014 installs dependencies into named volume, restart: "no"
+    database           \u2014 official image with healthcheck (postgres, mysql, etc.)
+    cache              \u2014 redis/memcached with healthcheck
+    app-api            \u2014 application server in dev mode (hot reload)
+    app-web            \u2014 frontend dev server bound to 0.0.0.0
+
+  Do NOT use a migrate service in compose. If the migrate container fails once
+  (bad SQL, missing env var, wrong path), depends_on with
+  service_completed_successfully is permanently unmet \u2014 app-api will never
+  start, even after you fix the migration. "docker compose restart" and
+  "docker compose up" won't help; only "docker compose down" + fresh up works.
+  Put migrations in the startup script instead (runs after compose up).
+
+  ROUTING LABELS \u2014 declare how nginx should route to your services:
+    services:
+      app-api:
+        labels:
+          sandbox.route: "/api"
+          sandbox.port: "3000"
+      app-web:
+        labels:
+          sandbox.route: "/"
+          sandbox.port: "5173"
+
+    The platform reads these labels and generates nginx config on "build".
+    If no labels, all traffic routes to the first non-infrastructure service.
+
+    PREFIX STRIPPING: the generated nginx location uses a trailing-slash
+    proxy_pass (proxy_pass http://<service>:<port>/), so the matched prefix
+    is stripped from the upstream request. With sandbox.route: "/api", a
+    browser hit to "/api/health" is delivered to the upstream as "/health".
+    Pick VITE_API_URL, OAuth redirect URIs, etc. accordingly.
+
+  ENV VAR STRATEGY \u2014 use \${VAR} syntax, values come from config + .env:
+    - Auto-wired (hardcode):   DATABASE_URL=postgres://user:pass@postgres:5432/db
+    - From config:             ANTHROPIC_API_KEY=\${ANTHROPIC_API_KEY}
+    - Platform-injected:       VITE_API_URL=\${SANDBOX_URL}/api
+    - Disabled:                WORKER_ENABLED=false
+
+    SANDBOX_URL is auto-injected by the platform (e.g. https://<id>.env.trycanary.ai).
+    Use it for any URL a browser needs to reach the sandbox.
+
+  Rules:
+    - Use named volumes for data persistence (postgres-data, redis-data, etc.)
+    - Bind-mount the repo (.:/app) rather than using named volumes for
+      node_modules. Per-package node_modules named volumes silently shadow the
+      bind mount on any service that doesn't mount them \u2014 a common monorepo
+      trap where "bun run build" fails because tsup is nowhere to be found.
+      The sandbox host is Linux EC2; bind mounts are fast.
+    - DO NOT define networks \u2014 the platform handles networking
+    - DO NOT expose ports to the host \u2014 nginx handles routing
+    - Keep relative paths repo-root-relative; compose runs from /workspace even
+      though the platform-managed compose files live in /workspace/.canary
+    - Escape shell variables in "command:" strings with $$ so compose leaves
+      them for the shell (e.g. command: ["bash", "-c", "exec foo $$BAR"]).
+      Unescaped \${VAR} is substituted at compose-time from the env file.
+
+SETUP SCRIPT (type: setup-script)
+  Runs BEFORE docker compose up on every build. Runs on the HOST, not in a container.
+  Written to /workspace/.canary/setup.sh.
+
+  IMPORTANT: The host is a bare EC2 instance with only docker and basic linux tools.
+  App runtimes (node, bun, python, ruby) are NOT available on the host \u2014 they live
+  inside your Docker images. Do NOT run app commands directly here.
+
+  Script authoring rules:
+    - Treat /workspace as the repo root for any file access or repo command
+    - Do not assume the current directory matches the script's own path
+    - Use explicit paths or start with "cd /workspace" before repo-relative work
+
+  Use for host-level preparation only:
+    - Installing system packages (apt-get, yum)
+    - Downloading external tools or binaries
+    - Generating config files programmatically (prefer file artifacts for static files)
+
+  For most apps, you won't need a setup script \u2014 file artifacts and the startup
+  script cover the common cases. Skip this if you don't need host-level prep.
+
+  Rules:
+    - Must be idempotent \u2014 safe to run multiple times
+    - Never patch source files
+    - Non-zero exit is logged as a warning but does not block the build
+
+STARTUP SCRIPT (type: startup-script)
+  Runs AFTER docker compose up on every build. Runs on the HOST, not in a container.
+  Written to /workspace/.canary/startup.sh.
+
+  This is where most app setup happens. Containers are running, so you can use
+  "sb-compose exec" to run commands inside them with the app runtime.
+
+  Script authoring rules:
+    - Start with "cd /workspace" or use explicit /workspace/... paths
+    - Do not assume the script runs from /workspace/.canary
+    - Prefer sb-compose exec for anything that needs the app runtime
+    - Use -T with exec (no TTY allocation \u2014 startup runs headless)
+
+  Use for:
+    - DB migrations via ORM CLI (use "bun run", NOT bunx \u2014 bunx downloads fresh)
+    - Building workspace packages that export from dist/
+    - Waiting for services to be healthy
+    - Triggering initial data loads
+
+  POST-MIGRATION RESTART (REQUIRED for many ORMs):
+    ORMs that introspect the schema at boot (Drizzle/effect-sql, Prisma with
+    prepared statements, SQLAlchemy with autoload, etc.) cache the pre-migration
+    schema on the first query. After you run migrations, you MUST restart the
+    API service, otherwise you'll see errors like:
+      relation "<table>" does not exist
+    even though psql confirms the table is there. Add "sb-compose restart" for
+    any service whose client introspects the schema at boot.
+
+  Example (Bun monorepo with Drizzle):
+    #!/bin/bash
+    set -e
+    # Build dist-exporting workspace packages the app/web import from
+    sb-compose exec -T app-api bash -c \\
+      'cd /app/packages/ui && bun run build'
+    # Run DB migrations inside the API container
+    sb-compose exec -T app-api bash -c \\
+      'cd /app/packages/db && bun run drizzle-kit migrate'
+    # Restart services so they pick up the fresh schema + built UI
+    sb-compose restart app-api app-web
+    # Wait for API to be healthy
+    for i in $(seq 1 30); do
+      sb-compose exec -T app-api curl -sf http://localhost:3000/health && break
+      sleep 2
+    done
+
+  Rules:
+    - Must be idempotent \u2014 safe to run multiple times
+    - Never patch source files
+    - Don't pre-wait for services to START \u2014 the platform handles that before
+      startup.sh runs (see Compose Architecture section). Do wait for service
+      *readiness* (app health, schema migrations applied) when your app
+      depends on it.
+
+FILE (type: file)
+  Arbitrary sandbox-owned files written to the instance at a specific path.
+  Use for config files that need to exist before services start (e.g. Vite
+  wrapper configs, one-shot scripts that need app dependencies).
+
+  !!! File artifacts MUST be written under /workspace/.canary/ !!!
+    The repo tree (everything outside .canary/) is user-owned. Sandbox
+    helpers live in .canary/ so they never collide with real files and
+    are never committed back to the repo. The API will reject any
+    --path value outside /workspace/.canary/ with
+    SANDBOX_FILE_ARTIFACT_OUTSIDE_CANARY.
+
+    If your script needs app dependencies (e.g. \`postgres\` from the api
+    package), put a tiny package.json next to it in .canary/scripts/ and
+    \`bun install\` in the setup-script, OR invoke it via
+    \`sb-compose exec -T <svc> ...\` so it runs inside a container that
+    already has them.
+
+  Upload with --path to specify the destination:
+    canary sandbox artifact create <template-id> file <local-file> --path /workspace/.canary/<dest>
+
+  Example \u2014 Vite 5.x allowedHosts wrapper:
+    canary sandbox artifact create <template-id> file vite.sandbox.config.ts \\
+      --path /workspace/.canary/vite.sandbox.config.ts
+
+  ONE ROW PER FILENAME. File artifacts are keyed by (template, filename).
+  Uploading a file with the same filename as an earlier upload REPLACES
+  the earlier row. The CLI prints "(replaced)" on such uploads, and the
+  next build removes the previous destination path so the instance
+  filesystem mirrors the template set exactly.
+
+  If you want to retire a file, just upload something else with a
+  different filename \u2014 the stale file is cleaned up on next build via
+  .canary/.artifact-paths (a manifest the platform maintains).
+
+  File artifacts are written before the setup script runs, so they're
+  available for both setup and compose services.
+
+SEED SCRIPT (type: seed-script)
+  Runs once on first provision to populate demo data. Optional.
+  Written to /workspace/.canary/seed.sh.
+  Skipped on subsequent builds (checks /workspace/.canary/.seeded).
+
+CONFIG SCHEMA
+  Define which env vars need user input. Set when completing the docker-compose checklist item:
+    canary sandbox checklist complete <template-id> docker-compose-created \\
+      --status success \\
+      --summary "Compose with postgres, redis, api, web" \\
+      --config-schema '[
+        {"key": "ANTHROPIC_API_KEY", "required": true, "sensitive": true, "description": "Anthropic API key"},
+        {"key": "OPENAI_API_KEY", "required": false, "sensitive": true, "description": "OpenAI API key"}
+      ]'
+
+  Set defaults:
+    canary sandbox config set <template-id> <key> <value>
+    canary sandbox config list <template-id>
+`.trim()
+};
+var VERIFICATION = {
+  title: "Verification & Iteration",
+  slug: "verify",
+  content: `
+After running "canary sandbox build", verify the sandbox is working. The iteration loop:
+  upload artifacts \u2192 build \u2192 check diagnostics \u2192 read logs \u2192 fix \u2192 re-upload \u2192 rebuild
+
+COMMANDS:
+  # Check all container statuses at a glance
+  canary sandbox diagnostics <instance-id>
+
+  # Read logs for a specific service
+  canary sandbox logs <instance-id> --service app-api
+  canary sandbox logs <instance-id> --service app-web
+  canary sandbox logs <instance-id> --service postgres
+
+  # Run arbitrary commands on the instance (runs on the host VM by default)
+  canary sandbox run-command <instance-id> "docker compose ps"
+  canary sandbox run-command <instance-id> "echo hello"
+
+  # Run commands inside a specific Docker container
+  canary sandbox run-command <instance-id> --service app-api "bun --version"
+  canary sandbox run-command <instance-id> --service app-api "bun test"
+
+  # Test health endpoints
+  canary sandbox run-command <instance-id> "curl -s http://localhost:3000/health"
+  canary sandbox run-command <instance-id> "curl -s -o /dev/null -w '%{http_code}' http://localhost:80/"
+
+  # Test with sandbox hostname (for host-restriction issues)
+  canary sandbox run-command <instance-id> \\
+    "curl -s -H 'Host: <instance-id>.env.trycanary.ai' http://localhost:80/"
+
+SANDBOX URL:
+  https://<instance-id>.env.trycanary.ai
+
+IF SOMETHING FAILS:
+  1. Read the logs for the failing service
+  2. Diagnose the root cause (missing env var, failed build, wrong port, etc.)
+  3. Fix the ARTIFACT \u2014 not just the running container
+  4. Re-upload: canary sandbox artifact create <template-id> <type> <file>
+  5. Rebuild: canary sandbox build <instance-id>
+  6. Verify again
+
+WHEN A CLI COMMAND TIMES OUT AT 30s:
+  Long sandbox operations (build, edit, artifact create on first push,
+  occasionally diagnostics) can exceed the gateway window even though
+  the work is still running server-side. The CLI prints:
+    Error: Request to https://api.trycanary.ai/... timed out after 30000ms.
+
+  Don't retry blindly \u2014 a retry can spawn duplicate work (e.g. a second
+  authoring instance). Instead, poll for the actual state:
+
+    canary sandbox template <template-id>     # status: provisioning/authoring/verified
+    canary sandbox diagnostics <instance-id>  # container/app health
+    canary sandbox list                       # running instances
+
+  Only retry once you've confirmed via polling that the prior call
+  truly didn't take effect.
+
+WHEN VERIFY HANGS:
+  \`canary sandbox verify\` now streams container state and failing-service
+  log tails every ~30s while the probe's app is unreachable. If you see:
+
+    >> nginx-proxy is restart-looping because upstream '<service>' (...) is exited.
+       Read that service's logs above, not nginx's.
+
+  ignore nginx entirely and read the upstream's tail \u2014 nginx is the symptom,
+  not the cause. Common underlying causes:
+    - the upstream service crashed at startup (bad env var, missing file,
+      import error)
+    - a file artifact was lost because you re-uploaded over its filename
+      (shouldn't happen any more \u2014 the build-time reconcile handles this \u2014
+      but watch for it if you're on an old template)
+
+  On failure, the probe instance is preserved by default so you can
+  \`canary sandbox run-command <id>\` into it. Pass
+  --auto-terminate-on-failure for CI.
+
+COMMON ISSUES:
+
+  "Invalid environment" / env validation fails
+    App has strict env var validation. Read the env schema. Add ALL required vars to compose.
+
+  Migration fails with "SST links not active" / cloud SDK error
+    Migrate script depends on cloud tooling. Use the ORM CLI directly in the startup script
+    via sb-compose exec: sb-compose exec -T app-api bash -c 'bun run drizzle-kit migrate'
+    DATABASE_URL should be hardcoded in the compose environment section.
+
+  "Cannot find module" / package not built
+    Monorepo package exports from dist/ but hasn't been built.
+    Add build step to startup script via sb-compose exec (runs after compose up).
+
+  "Cannot find package 'X'" from a file-artifact script
+    Bun resolves node_modules starting from the script's directory. File
+    artifacts live under /workspace/.canary/ which has no node_modules by
+    default. Two fixes:
+      (a) add a /workspace/.canary/scripts/package.json declaring the
+          dep (e.g. "postgres") and run \`bun install\` from the
+          setup-script / inside a sb-compose exec.
+      (b) don't run the script on the host at all \u2014 invoke it via
+          \`sb-compose exec -T <app-service> bun /app/.canary/scripts/foo.ts\`
+          so it resolves against the workspace's own node_modules. Replace
+          <app-service> with your template's actual service name.
+
+  "This host is not allowed" (Vite, Next.js)
+    Dev server blocks requests from sandbox subdomain.
+    For Vite 5.x, upload a wrapper config as a file artifact (into .canary/).
+
+    IMPORTANT: the wrapper must be self-contained \u2014 DO NOT import 'vite' or
+    a sibling config file. Vite evaluates the config via Node CJS bundled
+    by esbuild; from /workspace/.canary/ Node can't resolve packages
+    through Bun's hoisted .bun/<pkg>@<ver>/... layout, so any 'import ... from
+    "vite"' in the wrapper fails with "Cannot find module 'vite'". The
+    'defineConfig' helper is just a typed identity, so plain object export
+    works fine.
+
+    Note: the file artifact is at /workspace/.canary/... but the bind mount
+    inside containers is /app, so reference it as /app/.canary/... in your
+    compose command.
+
+      # Create the wrapper locally \u2014 no imports
+      cat > vite.sandbox.config.ts <<'EOF'
+      // Mirror your apps/web/vite.config.ts settings inline here.
+      // Reference paths use the in-container path (/app/...), not /workspace.
+      export default {
+        root: '/app/apps/web',
+        server: {
+          host: '0.0.0.0',
+          port: 5173,
+          allowedHosts: true,
+        },
+        // ...copy 'define', 'optimizeDeps', 'resolve' from your base config
+      };
+      EOF
+      # Upload it into .canary/
+      canary sandbox artifact create <template-id> file vite.sandbox.config.ts \\
+        --path /workspace/.canary/vite.sandbox.config.ts
+    Then in compose:
+      command: ["bash","-c","cd /app/apps/web && bunx vite --host 0.0.0.0 --port 5173 --config /app/.canary/vite.sandbox.config.ts"]
+    For Vite 6+: --allowedHosts all works as a CLI flag (no wrapper needed).
+
+  Browser gets CORS / "loopback" error when frontend calls API
+    Frontend is trying to reach localhost:3000 instead of going through nginx.
+    Use \${SANDBOX_URL}/api as the API URL in compose env vars:
+      VITE_API_URL: \${SANDBOX_URL}/api
+
+  run-command times out
+    Long-running operation exceeds the 55s SSM command timeout. Write a script file and run in background:
+    canary sandbox run-command <id> "cat > /tmp/run.sh << 'SCRIPT'
+    #!/bin/bash
+    <commands>
+    SCRIPT
+    chmod +x /tmp/run.sh && nohup /tmp/run.sh > /tmp/run.log 2>&1 & echo started"
+    Then check: canary sandbox run-command <id> "tail -20 /tmp/run.log"
+
+  "Resolving dependencies" hangs in migration container
+    bunx/npx downloads a fresh copy instead of using project deps.
+    Use "bun run drizzle-kit migrate" instead of "bunx drizzle-kit migrate".
+
+  Containers can't resolve each other by name
+    Don't use docker run \u2014 use docker compose for everything.
+
+RUNNING TESTS:
+  Two approaches depending on your needs:
+
+  Option 1 \u2014 Install runtime on host (no Docker needed):
+    Use the setup script to install the runtime on the host VM, then run
+    tests directly. Good for unit tests that don't need services like a database.
+
+    Example setup-script artifact:
+      #!/bin/bash
+      curl -fsSL https://bun.sh/install | bash
+      export PATH="$HOME/.bun/bin:$PATH"
+
+    Then: canary sandbox run-command <instance-id> "bun test"
+
+  Option 2 \u2014 Run inside a container (--service flag):
+    Route commands into a running Docker container. Good for integration
+    tests that need access to the database or other services.
+
+    canary sandbox run-command <instance-id> --service app-api "bun test"
+    canary sandbox run-command <instance-id> --service app-api "bun test:integration"
+
+  \${SANDBOX_URL} is blank / env vars from config not in containers
+    The "build" command writes /workspace/.canary/.env (with SANDBOX_URL and all config values)
+    before running docker compose up. If the .env is missing or stale, re-run:
+      canary sandbox build <instance-id>
+    You can also trigger a .env refresh by setting any config value:
+      canary sandbox config set <template-id> <key> <value>
+
+  .env values look empty when I cat the file
+    Values are written single-quoted (KEY='value'). Short values can look like
+    KEY='' at a glance even when they have content \u2014 it's just the quotes. Run
+    "wc -c" on a line, or "docker compose exec app-api env | grep KEY", to
+    confirm the actual value landed.
+`.trim()
+};
+var CHECKLIST = {
+  title: "Checklist",
+  slug: "checklist",
+  content: `
+The checklist tracks your progress toward a working sandbox. View it with:
+  canary sandbox checklist <template-id>
+
+Each item has a status: pending, completed, skipped, or failed.
+Items marked with * are actionable (their dependencies are met).
+
+COMPLETING ITEMS:
+  canary sandbox checklist complete <template-id> <item-id> \\
+    --status <success|failure> \\
+    --summary "What you did"
+
+  Example:
+    canary sandbox checklist complete <template-id> environment-analyzed \\
+      --status success \\
+      --summary "Bun monorepo: Postgres, Redis. Vite frontend on 5173, API on 3000."
+
+SKIPPING ITEMS:
+  canary sandbox checklist skip <template-id> <item-id>
+
+  Use when an item doesn't apply (e.g., no seed data needed, no integration tests).
+
+SPECIAL: docker-compose-created accepts --config-schema to define user-configurable env vars:
+  canary sandbox checklist complete <template-id> docker-compose-created \\
+    --status success \\
+    --summary "Compose with postgres, redis, api, web" \\
+    --config-schema '[{"key": "ANTHROPIC_API_KEY", "required": true, "sensitive": true, "description": "API key"}]'
+
+TYPICAL CHECKLIST ORDER:
+  1. Provisioned          \u2014 done automatically when you create the template
+  2. Code Cloned          \u2014 done automatically
+  3. Environment Analyzed \u2014 complete after your research phase
+  4. Setup Script Created \u2014 complete after uploading setup-script artifact
+  5. Dockerfile Created   \u2014 complete after uploading dockerfile artifact
+  6. Docker Compose Created \u2014 complete after uploading docker-compose artifact (with config-schema)
+  7. Unit Tests Runnable  \u2014 complete or skip. Install runtime on host via setup script,
+                            or use --service to run inside a container
+  8. Integration Tests Runnable \u2014 complete or skip. Use --service to run inside a
+                            container with access to database and other services
+  9. Seed Script Created  \u2014 complete or skip
+  10. Server Running       \u2014 complete after API responds to health checks
+  11. Server Accessible   \u2014 complete after nginx routes to the app successfully
+  12. Template Verified   \u2014 provision a fresh instance and verify it comes up healthy
+
+TEMPLATE VERIFICATION (final step):
+  Run one command \u2014 it provisions a fresh instance, waits for the app to
+  come up, marks template-verified, and terminates the instance:
+    canary sandbox verify <template-id>
+
+  Pass --keep-instance to leave the instance running afterwards (useful if
+  you want to poke at it).
+
+  This catches issues that authoring hides:
+    - Config values set manually but not in configDefaults
+    - SANDBOX_URL or other platform vars not properly referenced
+    - Startup scripts that assume manual setup already happened
+
+  Template status flow:
+    provisioning \u2192 authoring \u2192 verified
+
+  'verify' is the one transition from authoring to verified, and it is one-way
+  \u2014 there is no re-authoring path back to 'authoring' from 'verified'. To make
+  an AI-assisted edit to a verified template's artifacts, provision a sandbox
+  with the agent attached:
+
+    canary sandbox provision <template-id> --with-agent
+
+  then iterate via in-sandbox agent chat or 'canary sandbox artifact create',
+  and re-run 'canary sandbox verify' against the same template id when you're
+  happy with the changes. To start over from scratch, use 'regenerate' to
+  delete existing artifacts, or create a new template.
+`.trim()
+};
+var ACTIONS = {
+  title: "Actions",
+  slug: "actions",
+  content: `
+Actions are template-defined, parameterized operations that run against sandbox
+instances. Unlike run-command (arbitrary shell), actions have typed input/output
+schemas, are reusable across instances, and produce an auditable execution log.
+
+USE CASES:
+  - Provision a user credential (username, password, role)
+  - Seed demo data for a specific scenario
+  - Run database migrations
+  - Reset application state
+  - Toggle feature flags
+
+MANAGING ACTIONS:
+
+  List actions on a template:
+    canary sandbox action list <template-id>
+
+  View an action definition (including script):
+    canary sandbox action get <template-id> <slug>
+
+  Create or update an action:
+    canary sandbox action create <template-id> <slug> \\
+      --label "Provision Credential" \\
+      --description "Create a user account in the sandbox app" \\
+      --icon UserPlus \\
+      --script ./scripts/provision-user.sh \\
+      --input-schema ./schemas/provision-user-input.json \\
+      --credential-output-config ./schemas/provision-user-credential.json
+
+  --credential-output-config is optional. When set, a successful execution
+  also creates/updates a credential in the property's vault \u2014 see "Linking
+  actions to Canary credentials" below.
+
+  Delete an action:
+    canary sandbox action delete <template-id> <slug>
+
+EXECUTING ACTIONS:
+
+  Execute against a running instance:
+    canary sandbox action execute <instance-id> <slug> \\
+      --param username=testuser \\
+      --param password=s3cret \\
+      --param role=admin
+
+  Or pass all params from a JSON file:
+    canary sandbox action execute <instance-id> <slug> \\
+      --params-file ./params.json
+
+  View execution history:
+    canary sandbox action executions <instance-id>
+
+SLUG NAMING:
+  Slugs must be lowercase alphanumeric with hyphens, starting with a letter:
+    provision-credential    \u2713
+    seed-demo-data          \u2713
+    reset-state             \u2713
+    123-bad                 \u2717
+    UPPER_CASE              \u2717
+
+INPUT SCHEMA:
+  A JSON Schema file defining the action's parameters. The schema drives
+  validation, CLI prompting, and UI form generation.
+
+  Example (provision-user-input.json):
+    {
+      "type": "object",
+      "properties": {
+        "username": {
+          "type": "string",
+          "description": "Username to create",
+          "minLength": 1
+        },
+        "password": {
+          "type": "string",
+          "description": "Password for the user",
+          "sensitive": true
+        },
+        "role": {
+          "type": "string",
+          "description": "Role to assign",
+          "enum": ["admin", "user", "viewer"],
+          "default": "user"
+        }
+      },
+      "required": ["username", "password"]
+    }
+
+  The "sensitive" extension marks params that should be masked in UI and
+  injected securely (via tempfile, not env var) on the instance.
+
+SCRIPT CONVENTIONS:
+  Action scripts are bash, executed on the instance via SSM. Parameters are
+  injected as INPUT_<KEY> environment variables, where <KEY> is the param
+  name uppercased with non-alphanumeric chars replaced by '_'. There is NO
+  camelCase \u2192 snake_case conversion. Examples:
+    orgName   \u2192 INPUT_ORGNAME    (NOT INPUT_ORG_NAME)
+    org_name  \u2192 INPUT_ORG_NAME
+    api-key   \u2192 INPUT_API_KEY
+  If you want INPUT_FOO_BAR, name the input schema key 'foo_bar' or 'foo-bar'.
+
+  The last line of stdout that is valid JSON is parsed as the structured result.
+
+  EXECUTION ENVIRONMENT \u2014 same architecture as startup scripts:
+    Scripts run on the HOST (bare EC2 instance). The host has docker, curl,
+    and basic linux tools \u2014 but NO app runtimes (node, bun, python, ruby).
+    Those live inside your Docker containers.
+
+    Use "docker compose exec" to run commands that need the app runtime:
+      sb-compose exec -T app-api node -e "..."     # Node.js
+      sb-compose exec -T app-api bun run seed.ts   # Bun
+      sb-compose exec -T app-db psql -U app -d db  # Database CLI
+
+    Use bare host commands for docker/system operations:
+      sb-compose restart app-api                    # Restart a service
+      curl -s http://localhost:3000/health              # Health check
+      cat /workspace/.canary/.env                       # Read config
+
+    The -T flag is required for docker compose exec in non-interactive (SSM)
+    contexts. Without it, exec tries to allocate a TTY and hangs.
+
+    Working directory is /workspace (the mounted repo root). Keep script logic
+    repo-root-relative by starting with "cd /workspace" when needed.
+
+  AVOID INLINE CODE IN ACTION SCRIPTS:
+    Never embed application-language code (JS, Python, etc.) directly in the
+    bash script via "bun -e" or "node -e". Shell escaping of quotes, template
+    literals, and variable interpolation is fragile and hard to debug.
+
+    Instead, write complex logic as a separate file artifact and execute it:
+      1. Write a script file (e.g. provision-user.ts)
+      2. Upload as a file artifact:
+           canary sandbox artifact create <template-id> file provision-user.ts \\
+             --path /workspace/scripts/provision-user.ts
+      3. Reference it from the action script:
+           sb-compose exec -T app-api bun /app/scripts/provision-user.ts
+
+    Parameters are available in the action script as INPUT_<KEY> env vars.
+    Pass them to the file artifact via env or args:
+      sb-compose exec -T -e EMAIL="$INPUT_EMAIL" app-api bun /app/scripts/provision-user.ts
+
+  Example \u2014 provision a user (two-file pattern):
+
+    Place the .ts file under the workspace whose node_modules has the deps
+    (e.g. apps/api when only apps/api depends on \`postgres\`). Bun resolves
+    modules from the script's directory walking up \u2014 if the dep isn't hoisted
+    to the repo-root node_modules, a script under /workspace/scripts/ will
+    fail with "Cannot find package 'postgres'". Use \`-w\` to set cwd inside
+    the right workspace.
+
+    Action script (provision-user.sh):
+      #!/bin/bash
+      set -euo pipefail
+      cd /workspace
+      sb-compose exec -T \\
+        -w /app/apps/api \\
+        -e EMAIL="$INPUT_EMAIL" \\
+        -e PASSWORD="$INPUT_PASSWORD" \\
+        -e NAME="$INPUT_NAME" \\
+        app-api bun /app/apps/api/scripts/provision-user.ts
+
+    File artifact (uploaded to /workspace/apps/api/scripts/provision-user.ts):
+      import postgres from "postgres";
+      const sql = postgres(process.env.DATABASE_URL!);
+      const hash = await Bun.password.hash(process.env.PASSWORD!, { algorithm: "argon2id" });
+      const email = process.env.EMAIL!.toLowerCase();
+      const [org] = await sql\`INSERT INTO organizations (name) VALUES (\${email + "'s Org"}) RETURNING id\`;
+      const [user] = await sql\`
+        INSERT INTO users (auth_provider, provider_id, primary_email, password_hash, email_verified_at)
+        VALUES ('email', \${email}, \${email}, \${hash}, now()) RETURNING id\`;
+      await sql\`INSERT INTO org_memberships (user_id, org_id, role) VALUES (\${user.id}, \${org.id}, 'admin')\`;
+      const loginUrl = \`\${process.env.SANDBOX_PUBLIC_URL ?? ''}/login\`;
+      // Echo password back so credentialOutputConfig (below) can resolve $output.password.
+      // Output keys referenced by credentialOutputConfig.fieldMapping are auto-redacted
+      // from stored stdout/logs by the platform \u2014 safe to include.
+      console.log(JSON.stringify({ ok: true, email, password: process.env.PASSWORD, userId: user.id, orgId: org.id, loginUrl }));
+      await sql.end();
+
+LINKING ACTIONS TO CANARY CREDENTIALS:
+
+  When you want a successful action to also produce a credential in the
+  property's vault (so it can drive browser logins, seed workflows, etc.),
+  attach a credentialOutputConfig. The platform resolves \`$output.<key>\`
+  tokens against the action's last-line JSON stdout, then upserts a
+  credential scoped to (sandboxActionId, environmentId) \u2014 re-running the
+  action replaces the credential rather than duplicating it.
+
+  Provide it with --credential-output-config on action create/update:
+
+    canary sandbox action create <template-id> provision-credential \\
+      --label "Provision Credential" \\
+      --script ./scripts/provision-user.sh \\
+      --input-schema ./schemas/provision-user-input.json \\
+      --credential-output-config ./schemas/provision-user-credential.json
+
+  Example provision-user-credential.json (matches the script above):
+    {
+      "fieldMapping": {
+        "username": "$output.email",
+        "password": "$output.password"
+      },
+      "loginUrl": "$output.loginUrl",
+      "loginInstructions": "Sign in via the email/password form."
+    }
+
+  Field-mapping values are either literal strings or \`$output.<key>\` tokens
+  resolved from the action's parsed JSON output. Output keys referenced by
+  fieldMapping/loginUrl are automatically masked in stored stdout and result.
+
+  After execution, \`canary sandbox action execute\` prints the linked
+  credentialId, and \`canary credential list --property <name>\` shows the
+  vault entry. \`canary credential test <credId>\` runs the browser login
+  against the sandbox URL.
+
+  Example \u2014 simple SQL-only action (inline is fine for short commands):
+    #!/bin/bash
+    set -euo pipefail
+    cd /workspace
+    sb-compose exec -T app-db psql -U app -d appdb -t --csv -c \\
+      "INSERT INTO users (username, password_hash, role)
+       VALUES ('$INPUT_USERNAME', crypt('$INPUT_PASSWORD', gen_salt('bf')), '$INPUT_ROLE')
+       RETURNING id" | while read -r user_id; do
+      echo "{\\"userId\\":\\"$user_id\\",\\"username\\":\\"$INPUT_USERNAME\\",\\"loginUrl\\":\\"https://$SANDBOX_PUBLIC_URL/login\\"}"
+    done
+
+  Example \u2014 seed data via app CLI:
+    #!/bin/bash
+    set -euo pipefail
+    cd /workspace
+    sb-compose exec -T app-api bun run scripts/seed.ts \\
+      --scenario "$INPUT_SCENARIO" \\
+      --count "$INPUT_COUNT"
+
+  Example \u2014 run migrations (no params needed):
+    #!/bin/bash
+    set -euo pipefail
+    cd /workspace
+    sb-compose exec -T app-api bash -c \\
+      'cd /app/packages/db && bun run drizzle-kit migrate'
+    echo '{"status":"completed"}'
+
+  Available context variables:
+    SANDBOX_PUBLIC_URL    \u2014 the instance's public URL
+    SANDBOX_INSTANCE_ID  \u2014 the instance UUID
+
+AGENT AUTHORING:
+  During template creation, the sandbox agent can publish actions alongside
+  artifacts using the publish_action tool. The agent analyzes the codebase
+  and generates action definitions for common operations (user creation,
+  data seeding, migrations, etc.). These are stored on the template and
+  available on all instances provisioned from it.
+
+  publish_action accepts an optional credentialOutputConfig \u2014 for any action
+  that provisions login material (e.g. a user with email/password), the agent
+  should set this so the resulting credential lands in the property vault and
+  can be exercised by browser automation.
+`.trim()
+};
+var SANDBOX_GUIDE_SECTIONS = [
+  GOAL,
+  RESEARCH,
+  ARTIFACTS,
+  ACTIONS,
+  VERIFICATION,
+  CHECKLIST
+];
+
+export {
+  printGuide,
+  SANDBOX_GUIDE_SECTIONS
+};
+//# sourceMappingURL=chunk-4NRDONSC.js.map