@stkxp/cli 0.1.2

package/README.md

@@ -0,0 +1,273 @@
+# `@stkxp/cli` — `stkxp export` / `stkxp deploy`
+
+Take a Stack Expert **Team** out of a running `stkxp-app` instance as a single
+encrypted bundle file, and redeploy it — assistants, graphs, prompts, tools,
+platforms, credentials and all — standalone on any Elasticsearch cluster you
+control, with its inbound webhook served locally.
+
+```bash
+npm install -g @stkxp/cli
+```
+
+Four commands, two machines:
+
+| Command | Runs where | Talks to |
+|---------|------------|----------|
+| `stkxp export` | anywhere with network access to the source app | the source `stkxp-app` REST API (`POST /api/teams/:id/export-encrypted`) |
+| `stkxp deploy` | the target host | the target Elasticsearch cluster; bootstraps it, then serves the team webhook in the foreground |
+| `stkxp bootstrap` | the target host | the target Elasticsearch cluster; writes documents, mints the webhook token, exits |
+| `stkxp serve` | the target host | the target Elasticsearch cluster (read-only); serves the team webhook in the foreground forever |
+
+`stkxp deploy` is `bootstrap` + `serve` run back to back as one command — the
+simplest path for a manual, one-off deploy. Use `bootstrap`/`serve` as two
+separate steps instead when something needs to *restart* the webhook process
+without re-running the (ES-writing) bootstrap step every time — e.g. a
+`docker compose` one-shot init service plus a `restart: unless-stopped` long-running
+one, or a k8s Job/initContainer ahead of a Deployment. See
+[`stkxp bootstrap` / `stkxp serve`](#stkxp-bootstrap--stkxp-serve) below.
+
+---
+
+## `stkxp export`
+
+Exports the team and its full dependency closure. Every secret in the closure
+(platform auth keys, LLM provider API keys, tool credentials, the team's
+webhook token and MCP signing secret) is encrypted with your passphrase using
+AES-256-GCM under a single scrypt-derived, per-bundle key. Everything else —
+graph topology, prompts, tool definitions — stays plain, diffable JSON.
+
+```bash
+export STKXP_SECRET='…'           # or let the CLI prompt you
+stkxp export \
+  --source-url https://app.example.com \
+  --token "$STKXP_JWT" \
+  --team AbCdEf1234567890 \
+  --out ./ops-team.bundle.json
+```
+
+| Flag | Required | Description |
+|------|:--------:|-------------|
+| `--source-url <url>` | yes | Base URL of the source `stkxp-app` instance. |
+| `--token <jwt>` | yes | JWT bearer token of the team's owner. |
+| `--team <teamId>` | yes | Team ES document id to export. |
+| `--secret <passphrase>` | no\* | Passphrase to encrypt secrets with (min 8 chars). |
+| `--out <file>` | yes | Path to write the bundle to. Created with mode `0600`. |
+
+\* See [Providing secrets](#providing-secrets) — falls back to `STKXP_SECRET`,
+then an interactive prompt.
+
+## `stkxp deploy`
+
+Decrypts the bundle, bootstraps its documents into the target cluster's
+`.stkxp_*` indices, mints a **fresh** webhook token for the deployed team
+(the source instance's token is never reused), and stays in the foreground
+serving that team's webhook.
+
+```bash
+export STKXP_SECRET='…'
+export STKXP_ES_PASSWORD='…'
+stkxp deploy \
+  --team ./ops-team.bundle.json \
+  --es-url https://es.internal:9200 \
+  --es-user elastic \
+  --es-ca /etc/ssl/certs/internal-ca.pem \
+  --webhook-port 8081
+```
+
+| Flag | Required | Default | Description |
+|------|:--------:|---------|-------------|
+| `--team <bundlePath>` | yes | — | Path to the encrypted bundle file. |
+| `--secret <passphrase>` | no\* | — | Passphrase used at export time. |
+| `--es-url <url>` | yes | — | Target Elasticsearch URL. |
+| `--es-user <user>` | yes | — | Target Elasticsearch username. |
+| `--es-password <password>` | no\* | — | Target Elasticsearch password. |
+| `--es-ca <path>` | no | — | PEM CA bundle for the target's certificate chain. |
+| `--es-insecure` | no | off | Skip TLS certificate verification against the target. Opt-in escape hatch for self-signed clusters with no CA on hand; prefer `--es-ca`. |
+| `--webhook-port <port>` | no | `8081` | Port to serve the webhook listener on. |
+| `--webhook-host <host>` | no | `127.0.0.1` | Interface to bind the webhook to. Loopback-only by default; pass `0.0.0.0` to expose it (put a reverse proxy with TLS in front if you do). |
+
+On success it prints the webhook URL and the freshly minted webhook token
+(**shown once** — save it), then keeps running. Stopping the process stops the
+webhook; the deployed data stays in Elasticsearch.
+
+### Calling the deployed webhook
+
+Authenticate with the `x-stkxp-webhook-token` header — **not** `Authorization:
+Bearer`:
+
+```bash
+curl -X POST http://localhost:8081/api/webhooks/team/<teamId> \
+  -H "Content-Type: application/json" \
+  -H "x-stkxp-webhook-token: <token from the deploy output>" \
+  -d '{"message": "…"}'
+```
+
+A successful call returns `202 Accepted` with a `runId`/`chatId` — the team
+graph then runs in the background. **The deployed team must have a
+`graphId`** (a `.stkxp_graphs` coordination graph attached); a team with only
+`assistantIds` and no coordination graph will accept the call but the run
+fails immediately with `"... has no graphId — webhook runs require a
+coordination graph"`. Export a team that already has one attached, or attach
+one before exporting.
+
+---
+
+## `stkxp bootstrap` / `stkxp serve`
+
+The two halves of `stkxp deploy`, run as separate commands so a supervisor can
+restart the webhook process without re-touching Elasticsearch on every
+restart.
+
+**`stkxp bootstrap`** decrypts the bundle, writes its documents into the
+target's `.stkxp_*` indices, mints a webhook token if the target doesn't
+already have one, prints the result as JSON, and exits — it never opens a
+listener. **Idempotent**: re-running it against a target that's already
+bootstrapped (`webhookEnabled` + a `webhookToken` already present on the team
+doc) skips minting a new token — an existing secret is never re-shown — but
+still re-upserts the closure's documents (harmless, same `_id`s), so re-running
+it is the way to push an updated bundle's contents onto an already-deployed
+target without invalidating the webhook token callers already have.
+
+```bash
+export STKXP_SECRET='…'
+export STKXP_ES_PASSWORD='…'
+stkxp bootstrap \
+  --team ./ops-team.bundle.json \
+  --es-url https://es.internal:9200 \
+  --es-user elastic \
+  --es-ca /etc/ssl/certs/internal-ca.pem
+```
+
+| Flag | Required | Description |
+|------|:--------:|-------------|
+| `--team <bundlePath>` | yes | Path to the encrypted bundle file. |
+| `--secret <passphrase>` | no\* | Passphrase used at export time. |
+| `--es-url <url>` | yes | Target Elasticsearch URL. |
+| `--es-user <user>` | yes | Target Elasticsearch username. |
+| `--es-password <password>` | no\* | Target Elasticsearch password. |
+| `--es-ca <path>` | no | PEM CA bundle for the target's certificate chain. |
+| `--es-insecure` | no | Skip TLS certificate verification against the target. |
+
+**`stkxp serve`** starts the webhook listener against an already-bootstrapped
+target — it never writes to Elasticsearch itself, so it's safe to crash-loop
+or restart under a supervisor; it just reconnects and keeps serving whatever
+team(s) the target already has `webhookEnabled`. Run `stkxp bootstrap` first —
+`serve` does not create any documents.
+
+```bash
+export STKXP_ES_PASSWORD='…'
+stkxp serve \
+  --es-url https://es.internal:9200 \
+  --es-user elastic \
+  --es-ca /etc/ssl/certs/internal-ca.pem \
+  --port 8081 \
+  --host 0.0.0.0
+```
+
+| Flag | Required | Default | Description |
+|------|:--------:|---------|-------------|
+| `--es-url <url>` | yes | — | Target Elasticsearch URL. |
+| `--es-user <user>` | yes | — | Target Elasticsearch username. |
+| `--es-password <password>` | no\* | — | Target Elasticsearch password. |
+| `--es-ca <path>` | no | — | PEM CA bundle for the target's certificate chain. |
+| `--es-insecure` | no | off | Skip TLS certificate verification against the target. |
+| `--port <port>` | no | `8081` | Port to serve the webhook listener on. |
+| `--host <host>` | no | `127.0.0.1` | Interface to bind the webhook listener to. Pass `0.0.0.0` inside a container so Docker's published port mapping can reach it — `127.0.0.1` inside a container is unreachable from outside it even with `-p` published. |
+
+`serve` runs in the foreground and forwards `SIGINT`/`SIGTERM` to the
+underlying webhook process so a supervisor's normal stop signal triggers a
+graceful shutdown rather than an abrupt kill.
+
+### Multiple teams on one cluster
+
+Supported: `stkxp bootstrap` only creates a `.stkxp_*` index when it doesn't
+already exist, and its idempotent re-mint check is scoped to the one
+`teamId` being bootstrapped — running `stkxp bootstrap --team <bundle-a>`
+then `stkxp bootstrap --team <bundle-b>` against the same cluster adds
+team B's documents into the same indices without touching team A's. A single
+`stkxp serve` then answers `/api/webhooks/team/:teamId` for **every**
+`webhookEnabled` team on that cluster — the route isn't scoped to one team,
+so one running `serve` process is enough for all of them.
+
+The one thing this does *not* protect against: if two independently-exported
+bundles happen to share a document `_id` (e.g. the same platform/tool/LLM
+provider reused across both source teams) with genuinely *different*
+content, the second bootstrap silently overwrites the first's copy — see
+[the fresh-cluster limitation](#the-target-elasticsearch-cluster-must-be-freshempty)
+below. Sharing a dependency that's byte-identical in both exports is fine.
+
+---
+
+## Providing secrets
+
+`--secret` and `--es-password` are **optional flags**, because anything passed
+in `argv` is visible to every user on the box via `ps` / `/proc/<pid>/cmdline`
+and gets written into your shell history. Each is resolved in this order:
+
+1. the explicit CLI flag, if given;
+2. an environment variable — `STKXP_SECRET` for `--secret`, `STKXP_ES_PASSWORD`
+   for `--es-password`;
+3. an interactive, non-echoing prompt, if stdin is a TTY.
+
+If none of the three yields a value the command errors out and does nothing.
+
+---
+
+## Limitations
+
+### The target Elasticsearch cluster must be fresh/empty
+
+`stkxp deploy` writes every document in the bundle at its original `_id`.
+Deploying **twice**, or deploying against a cluster that already holds
+`.stkxp_*` data, **silently overwrites colliding documents by `_id`**. There is
+no merge, no dedup, no "already exists" detection, and no confirmation prompt —
+a second deploy of a modified bundle will clobber the first deploy's documents,
+and a deploy into a live cluster will clobber whatever shares an id with it.
+
+Treat each deploy as targeting a dedicated, empty cluster (or at minimum one
+with no existing Stack Expert data). Re-deploying an updated bundle onto a
+running deployment is **not** a supported upgrade path.
+
+### Indices are bootstrapped with dynamic mapping
+
+Deploy creates the `.stkxp_*` indices it needs with Elasticsearch's default
+dynamic mapping rather than the application's real per-entity mappings.
+Consequences on a standalone deploy:
+
+- **No semantic search.** Fields backed by `semantic_text` / ELSER-style
+  inference in a full `stkxp-app` install are plain text here; features that
+  depend on semantic retrieval degrade to lexical matching or return nothing.
+- **Approximate field typing.** Exact `keyword` vs `text` typing, analyzers,
+  `index: false` flags and other mapping details are inferred from the first
+  document seen instead of being declared, so some queries that rely on precise
+  typing (exact-term filters, sorting, aggregations on analyzed fields) may
+  behave differently than on the source instance.
+
+This is a deliberate v1 scope decision, not a bug: the team's runtime path
+(webhook → graph execution → tools) works, but the deployment is not a
+byte-for-byte replica of the source cluster's schema.
+
+### Other v1 scope notes
+
+- Neither `deploy` nor `serve` is supervised by this CLI itself — no PM2/systemd
+  unit, no Docker image shipped. Wrap `stkxp bootstrap` + `stkxp serve` in your
+  own supervisor (docker-compose, k8s, systemd) if you need survival across a
+  reboot or crash; `serve` is specifically designed be restart-safe for this
+  (see [`stkxp bootstrap` / `stkxp serve`](#stkxp-bootstrap--stkxp-serve)).
+- The webhook is served over plain HTTP on the bound interface. Front it with a
+  TLS-terminating reverse proxy before exposing it beyond loopback.
+- **Only the webhook façade exists.** The original design also envisioned MCP
+  and WebSocket façades (`--mcp-port` / `--ws-port`) for a fully protocol-agnostic
+  standalone deployment — neither is implemented; `stkxp deploy` has no such
+  flags. Not scheduled.
+
+---
+
+## Status
+
+Exercised end-to-end against a live source `stkxp-app` and a separate target
+Elasticsearch cluster (2026-09-16): export → deploy → bootstrap →
+authenticated webhook call → run accepted and logged. That run surfaced (and
+fixed) module-resolution and TLS-propagation bugs that only appeared once the
+CLI ran standalone rather than under unit tests — see the main repo's git
+history around `db62f56` if you hit something similar.

package/bin/stkxp.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// packages/cli/bin/stkxp.mjs
+import { Command } from "commander";
+import { runExport } from "../src/export.mjs";
+import { runDeployCommand } from "../src/deploy.mjs";
+import { runBootstrapCommand } from "../src/bootstrap.mjs";
+import { runServeCommand } from "../src/serve.mjs";
+import { resolveSecret } from "../src/secret-input.mjs";
+
+const program = new Command();
+program.name("stkxp").description("Export and deploy a Stack Expert Team standalone");
+
+program
+  .command("export")
+  .description("Export a Team and its whole dependency closure as an encrypted bundle file")
+  .requiredOption("--source-url <url>", "Base URL of the source stkxp-app instance")
+  .requiredOption("--token <jwt>", "JWT bearer token of the team's owner")
+  .requiredOption("--team <teamId>", "Team ES document id to export")
+  .option(
+    "--secret <passphrase>",
+    "Passphrase to encrypt secrets with (min 8 chars). Prefer the STKXP_SECRET env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .requiredOption("--out <file>", "Path to write the encrypted bundle to (created mode 0600)")
+  .action(async (opts) => {
+    try {
+      const secret = await resolveSecret({
+        flagValue: opts.secret,
+        envVar: "STKXP_SECRET",
+        promptLabel: "Bundle passphrase: ",
+        flagName: "--secret",
+      });
+      const result = await runExport({
+        sourceUrl: opts.sourceUrl,
+        token: opts.token,
+        teamId: opts.team,
+        secret,
+        outFile: opts.out,
+      });
+      console.log(`Exported "${result.rootName}" (${result.totalDocs} docs) to ${result.outFile}`);
+    } catch (e) {
+      console.error(`stkxp export failed: ${e.message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("deploy")
+  .description(
+    "Deploy an encrypted Team bundle onto a target Elasticsearch cluster and serve its webhook. " +
+      "The target must be a FRESH cluster — colliding .stkxp_* documents are overwritten by _id, with no merge or dedup (see README).",
+  )
+  .requiredOption("--team <bundlePath>", "Path to the encrypted bundle file")
+  .option(
+    "--secret <passphrase>",
+    "Passphrase used at export time. Prefer the STKXP_SECRET env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .requiredOption("--es-url <url>", "Target Elasticsearch URL")
+  .requiredOption("--es-user <user>", "Target Elasticsearch username")
+  .option(
+    "--es-password <password>",
+    "Target Elasticsearch password. Prefer the STKXP_ES_PASSWORD env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .option("--es-ca <path>", "Path to a PEM CA bundle for the target Elasticsearch certificate chain")
+  .option("--es-insecure", "Skip TLS certificate verification against the target Elasticsearch (not recommended)")
+  .option("--webhook-port <port>", "Port to serve the webhook listener on", "8081")
+  .option("--webhook-host <host>", "Interface to bind the webhook listener to", "127.0.0.1")
+  .action(async (opts) => {
+    try {
+      const secret = await resolveSecret({
+        flagValue: opts.secret,
+        envVar: "STKXP_SECRET",
+        promptLabel: "Bundle passphrase: ",
+        flagName: "--secret",
+      });
+      const esPassword = await resolveSecret({
+        flagValue: opts.esPassword,
+        envVar: "STKXP_ES_PASSWORD",
+        promptLabel: "Target Elasticsearch password: ",
+        flagName: "--es-password",
+      });
+      const result = await runDeployCommand({
+        bundlePath: opts.team,
+        secret,
+        esUrl: opts.esUrl,
+        esUser: opts.esUser,
+        esPassword,
+        esCaPath: opts.esCa,
+        esInsecure: opts.esInsecure === true,
+        webhookPort: parseInt(opts.webhookPort, 10),
+        webhookHost: opts.webhookHost,
+      });
+      console.log(`Deployed "${result.rootName}" — webhook listening at ${result.webhookUrl}`);
+      console.log(`Webhook token (save this, shown once): ${result.webhookToken}`);
+      console.log(`Indices created: ${result.indicesCreated.join(", ") || "(none, already existed)"}`);
+      console.log(`Documents indexed: ${result.docsIndexed}`);
+    } catch (e) {
+      console.error(`stkxp deploy failed: ${e.message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("bootstrap")
+  .description(
+    "Bootstrap an encrypted Team bundle onto a target Elasticsearch cluster WITHOUT serving the webhook. " +
+      "Idempotent — safe to re-run against an already-bootstrapped target (skips re-minting the webhook token). " +
+      "Pair with `stkxp serve` as separate init/long-running steps (e.g. a docker-compose one-shot service + a restart-safe service).",
+  )
+  .requiredOption("--team <bundlePath>", "Path to the encrypted bundle file")
+  .option(
+    "--secret <passphrase>",
+    "Passphrase used at export time. Prefer the STKXP_SECRET env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .requiredOption("--es-url <url>", "Target Elasticsearch URL")
+  .requiredOption("--es-user <user>", "Target Elasticsearch username")
+  .option(
+    "--es-password <password>",
+    "Target Elasticsearch password. Prefer the STKXP_ES_PASSWORD env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .option("--es-ca <path>", "Path to a PEM CA bundle for the target Elasticsearch certificate chain")
+  .option("--es-insecure", "Skip TLS certificate verification against the target Elasticsearch (not recommended)")
+  .action(async (opts) => {
+    try {
+      const secret = await resolveSecret({
+        flagValue: opts.secret,
+        envVar: "STKXP_SECRET",
+        promptLabel: "Bundle passphrase: ",
+        flagName: "--secret",
+      });
+      const esPassword = await resolveSecret({
+        flagValue: opts.esPassword,
+        envVar: "STKXP_ES_PASSWORD",
+        promptLabel: "Target Elasticsearch password: ",
+        flagName: "--es-password",
+      });
+      const result = await runBootstrapCommand({
+        bundlePath: opts.team,
+        secret,
+        esUrl: opts.esUrl,
+        esUser: opts.esUser,
+        esPassword,
+        esCaPath: opts.esCa,
+        esInsecure: opts.esInsecure === true,
+      });
+      if (result.alreadyBootstrapped) {
+        console.log(`Team ${result.teamId} was already bootstrapped on this target — skipped re-minting the webhook token.`);
+      } else {
+        console.log(`Bootstrapped "${result.rootName}" (team ${result.teamId})`);
+        console.log(`Webhook token (save this, shown once): ${result.webhookToken}`);
+      }
+      console.log(`Indices created: ${result.indicesCreated.join(", ") || "(none, already existed)"}`);
+      console.log(`Documents indexed: ${result.docsIndexed}`);
+    } catch (e) {
+      console.error(`stkxp bootstrap failed: ${e.message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("serve")
+  .description(
+    "Serve the standalone Team webhook against an already-bootstrapped target Elasticsearch cluster. " +
+      "Run `stkxp bootstrap` first. Long-running and restart-safe — never writes to ES, so a crash/restart is harmless.",
+  )
+  .requiredOption("--es-url <url>", "Target Elasticsearch URL")
+  .requiredOption("--es-user <user>", "Target Elasticsearch username")
+  .option(
+    "--es-password <password>",
+    "Target Elasticsearch password. Prefer the STKXP_ES_PASSWORD env var or the interactive prompt — an argv value is visible in `ps` and shell history",
+  )
+  .option("--es-ca <path>", "Path to a PEM CA bundle for the target Elasticsearch certificate chain")
+  .option("--es-insecure", "Skip TLS certificate verification against the target Elasticsearch (not recommended)")
+  .option("--port <port>", "Port to serve the webhook listener on", "8081")
+  .option("--host <host>", "Interface to bind the webhook listener to", "127.0.0.1")
+  .action(async (opts) => {
+    try {
+      const esPassword = await resolveSecret({
+        flagValue: opts.esPassword,
+        envVar: "STKXP_ES_PASSWORD",
+        promptLabel: "Target Elasticsearch password: ",
+        flagName: "--es-password",
+      });
+      await runServeCommand({
+        esUrl: opts.esUrl,
+        esUser: opts.esUser,
+        esPassword,
+        esCaPath: opts.esCa,
+        esInsecure: opts.esInsecure === true,
+        port: parseInt(opts.port, 10),
+        host: opts.host,
+      });
+    } catch (e) {
+      console.error(`stkxp serve failed: ${e.message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@stkxp/cli",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "description": "Export a Stack Expert Team as an encrypted, standalone-deployable bundle, and redeploy it on any Elasticsearch cluster.",
+  "bin": {
+    "stkxp": "./bin/stkxp.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "src",
+    "vendor"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.24",
+    "@asteasolutions/zod-to-openapi": "^7.3.4",
+    "@elastic/datemath": "5.0.3",
+    "@elastic/ebt": "^1.4.1",
+    "@elastic/ecs": "^8.11.5",
+    "@elastic/elasticsearch": "^8.19.1",
+    "@elastic/ems-client": "8.6.3",
+    "@elastic/filesaver": "1.1.2",
+    "@elastic/node-crypto": "^1.2.3",
+    "@elastic/numeral": "^2.5.1",
+    "@elastic/request-crypto": "^2.0.3",
+    "@h1deya/langchain-google-genai-ex": "^0.0.1",
+    "@langchain/anthropic": "^1.5.1",
+    "@langchain/community": "^1.1.13",
+    "@langchain/core": "^1.2.1",
+    "@langchain/google-genai": "^2.2.0",
+    "@langchain/langgraph": "^1.4.7",
+    "@langchain/langgraph-checkpoint": "^1.0.0",
+    "@langchain/langgraph-sdk": "^1.6.0",
+    "@langchain/mcp-adapters": "^1.1.3",
+    "@langchain/openai": "^1.5.3",
+    "@langchain/tavily": "^1.2.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@nats-io/nats-core": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jspdf": "^1.3.3",
+    "@types/leaflet": "^1.9.21",
+    "ai": "^4.3.19",
+    "archiver": "^8.0.0",
+    "axios": "^1.13.5",
+    "body-parser": "^2.2.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "convert": "^5.14.1",
+    "dagre": "^0.8.5",
+    "dotenv": "^17.2.4",
+    "echarts": "^6.0.0",
+    "elkjs": "0.9.3",
+    "express": "^5.2.1",
+    "happy-dom": "^20.6.0",
+    "html2canvas": "^1.4.1",
+    "i18next": "^25.8.13",
+    "ioredis": "^5.9.2",
+    "js-yaml": "^4.1.1",
+    "jsonata": "^2.0.6",
+    "jsonwebtoken": "^9.0.3",
+    "jspdf": "^3.0.4",
+    "juice": "^12.1.1",
+    "langchain": "^1.5.2",
+    "langfuse": "^3.38.6",
+    "langfuse-langchain": "^3.38.6",
+    "leaflet": "^1.9.4",
+    "lodash": "^4.17.23",
+    "luxon": "^3.7.2",
+    "moment": "2.30.1",
+    "moment-timezone": "^0.6.0",
+    "morgan": "^1.10.1",
+    "mysql2": "^3.16.3",
+    "nodemailer": "^7.0.13",
+    "partial-json": "^0.1.7",
+    "pdf-parse": "2.4.5",
+    "pg": "^8.18.0",
+    "resend": "^4.8.0",
+    "slugify": "^1.6.6",
+    "stream-json": "^1.9.1",
+    "stripe": "^22.0.1",
+    "swagger-ui-express": "^5.0.1",
+    "undici": "^7.21.0",
+    "uuid": "^11.1.0",
+    "winston": "^3.19.0",
+    "winston-daily-rotate-file": "^5.0.0",
+    "ws": "^8.19.0",
+    "zod": "^3.25.76",
+    "commander": "^12.0.0",
+    "tsx": "^4.19.0"
+  }
+}

package/src/bootstrap.mjs

@@ -0,0 +1,37 @@
+// packages/cli/src/bootstrap.mjs
+//
+// `stkxp bootstrap` — decrypts a bundle and bootstraps its closure onto a
+// target Elasticsearch cluster, WITHOUT serving the webhook. Meant for a
+// one-shot init step (docker-compose one-shot service, k8s Job/initContainer)
+// ahead of a separately-scheduled long-running `stkxp serve`. Idempotent: a
+// re-run against an already-bootstrapped target skips re-minting the webhook
+// token (see server/entrypoints/cli-deploy.ts's bootstrapTeam()).
+//
+// Spawns the vendored server/entrypoints/cli-bootstrap-run.js under tsx —
+// same rationale as packages/cli/src/deploy.mjs (see its header for why a
+// child process, and why tsx is resolved via require.resolve("tsx/cli")).
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnAndAwaitJsonResult, resolveTsxCli } from "./deploy.mjs";
+
+const CLI_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+/** Must stay byte-identical to RESULT_SENTINEL in server/entrypoints/cli-bootstrap-run.ts. */
+export const RESULT_SENTINEL = "__STKXP_BOOTSTRAP_RESULT__";
+
+export async function runBootstrapCommand({ bundlePath, secret, esUrl, esUser, esPassword, esCaPath, esInsecure }) {
+  const bundle = JSON.parse(await readFile(bundlePath, "utf8"));
+
+  const runnerScript = path.join(CLI_ROOT, "vendor", "dist-server", "entrypoints", "cli-bootstrap-run.js");
+
+  return spawnAndAwaitJsonResult(
+    process.execPath,
+    [resolveTsxCli(), runnerScript],
+    {
+      input: JSON.stringify({ bundle, secret, esUrl, esUser, esPassword, esCaPath, esInsecure }),
+    },
+    RESULT_SENTINEL,
+  );
+}

package/src/bootstrap.test.mjs

@@ -0,0 +1,73 @@
+// packages/cli/src/bootstrap.test.mjs
+//
+// spawnAndAwaitJsonResult's own resolution/rejection contract is already
+// covered end-to-end in deploy.test.mjs (bootstrap.mjs reuses that same
+// function, just parameterized with its own sentinel) — this file only
+// covers what's specific to runBootstrapCommand: reading the bundle file,
+// picking the right vendored runner script, and passing its own
+// RESULT_SENTINEL (not deploy.mjs's) through to the shared spawn helper.
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CLI_ROOT = path.dirname(fileURLToPath(new URL(".", import.meta.url)));
+
+vi.mock("node:fs/promises", () => ({
+  readFile: vi.fn(),
+}));
+
+const mockSpawnAndAwaitJsonResult = vi.hoisted(() => vi.fn());
+vi.mock("./deploy.mjs", () => ({
+  spawnAndAwaitJsonResult: mockSpawnAndAwaitJsonResult,
+  resolveTsxCli: () => "/fake/tsx/dist/cli.mjs",
+}));
+
+import { readFile } from "node:fs/promises";
+import { runBootstrapCommand, RESULT_SENTINEL } from "./bootstrap.mjs";
+
+describe("RESULT_SENTINEL", () => {
+  it("is its own sentinel, distinct from deploy.mjs's", () => {
+    expect(RESULT_SENTINEL).toBe("__STKXP_BOOTSTRAP_RESULT__");
+  });
+});
+
+describe("runBootstrapCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSpawnAndAwaitJsonResult.mockResolvedValue({ teamId: "team-1", alreadyBootstrapped: false });
+  });
+
+  it("reads the bundle file, spawns the bootstrap runner under tsx, and passes its own sentinel", async () => {
+    readFile.mockResolvedValue(JSON.stringify({ envelope: "v2" }));
+
+    const result = await runBootstrapCommand({
+      bundlePath: "./ops.bundle.json",
+      secret: "s3cr3t",
+      esUrl: "https://es:9200",
+      esUser: "elastic",
+      esPassword: "pw",
+      esCaPath: "/ca.pem",
+      esInsecure: false,
+    });
+
+    expect(readFile).toHaveBeenCalledWith("./ops.bundle.json", "utf8");
+    expect(result).toEqual({ teamId: "team-1", alreadyBootstrapped: false });
+
+    expect(mockSpawnAndAwaitJsonResult).toHaveBeenCalledTimes(1);
+    const [command, args, opts, sentinel] = mockSpawnAndAwaitJsonResult.mock.calls[0];
+    expect(command).toBe(process.execPath);
+    expect(args).toEqual(["/fake/tsx/dist/cli.mjs", path.join(CLI_ROOT, "vendor", "dist-server", "entrypoints", "cli-bootstrap-run.js")]);
+    expect(sentinel).toBe(RESULT_SENTINEL);
+
+    const payload = JSON.parse(opts.input);
+    expect(payload).toEqual({
+      bundle: { envelope: "v2" },
+      secret: "s3cr3t",
+      esUrl: "https://es:9200",
+      esUser: "elastic",
+      esPassword: "pw",
+      esCaPath: "/ca.pem",
+      esInsecure: false,
+    });
+  });
+});