@warmhub/cli 0.55.0 → 0.56.0

package/README.md

@@ -59,8 +59,8 @@ Full command reference: https://docs.warmhub.ai/cli-reference/overview/
 ## Links
 
 - Documentation — https://docs.warmhub.ai
-- Report a bug — support@warmhub.com
+- Report a bug — support@warmhub.ai
 
 ## Security
 
-Report security issues to support@warmhub.com.
+Report security issues to support@warmhub.ai.

package/dist/wh.js

@@ -21441,7 +21441,7 @@ function findSystemComponent(componentId) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.55.0",
+  version: "0.56.0",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -21464,7 +21464,7 @@ var package_default = {
   },
   homepage: "https://docs.warmhub.ai/get-started/quickstart/#connect-via-sdk",
   bugs: {
-    email: "support@warmhub.com"
+    email: "support@warmhub.ai"
   },
   engines: {
     node: ">=22"
@@ -34183,6 +34183,264 @@ var NOTIFICATIONS_DOMAIN = defineDomain({
   handler: handleNotifications
 });
 
+// ../../packages/warmhub-cli/src/domains/onboard-adapters/claude.md
+var claude_default = `# Adapter: Claude Code
+
+**How to run this:** paste this whole document into Claude Code as your first
+message, or save it as a custom slash command and invoke it. Then follow the
+Conductor Script below, one step per turn.
+
+**Connecting WarmHub (Act 1 details):** add the MCP server, then complete the
+auth flow.
+
+\`\`\`bash
+claude mcp add --transport http warmhub https://api.warmhub.ai/mcp
+\`\`\`
+
+Or add it to \`.mcp.json\` in the project:
+
+\`\`\`json
+{ "mcpServers": { "warmhub": { "transport": "http", "url": "https://api.warmhub.ai/mcp" } } }
+\`\`\`
+
+After adding, open \`/mcp\` and complete the sign-in when prompted.
+`;
+
+// ../../packages/warmhub-cli/src/domains/onboard-adapters/codex.md
+var codex_default = `# Adapter: OpenAI Codex
+
+**How to run this:** paste this whole document into your Codex session as your
+first message, or save it to \`AGENTS.md\` (Codex reads \`AGENTS.md\` natively). Then
+follow the Conductor Script below, one step per turn.
+
+**Connecting WarmHub (Act 1 details):** Codex reads MCP servers from
+\`~/.codex/config.toml\`. Codex talks to MCP servers over stdio, so bridge the
+WarmHub HTTP endpoint with \`mcp-remote\`.
+
+Install a **pinned** bridge once (so a compromised future release can't be
+auto-run with your token in its env), and keep the token in your shell rather
+than on disk:
+
+\`\`\`bash
+npm i -g mcp-remote@<pinned-version>   # pin to the current stable release, not @latest
+export WH_TOKEN="Bearer <your-pat>"     # use a least-privilege, short-lived PAT
+\`\`\`
+
+Then point Codex at the pinned binary and reference the token by env var, so the
+literal never sits at rest in the synced config:
+
+\`\`\`toml
+[mcp_servers.warmhub]
+command = "mcp-remote"
+args = ["https://api.warmhub.ai/mcp", "--header", "Authorization:\${WH_TOKEN}", "--transport", "http-only"]
+\`\`\`
+
+Restart Codex after editing the config.
+`;
+
+// ../../packages/warmhub-cli/src/domains/onboard-adapters/cursor.md
+var cursor_default = '# Adapter: Cursor\n\n**How to run this:** paste this whole document into the Cursor chat as your first\nmessage, or save it to `.cursorrules` (or `.cursor/rules/`) so Cursor loads it\nautomatically. Then follow the Conductor Script below, one step per turn.\n\n**Connecting WarmHub (Act 1 details):** Cursor reads MCP servers from\n`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). Add WarmHub as an\nHTTP server:\n\n```json\n{ "mcpServers": { "warmhub": { "url": "https://api.warmhub.ai/mcp" } } }\n```\n\nOpen Cursor Settings → MCP and complete the sign-in when prompted — browser\nsign-in is the preferred path. Only if your setup blocks remote connectors, pass\na personal access token via a header instead. Put it in your **global**\n`~/.cursor/mcp.json`, not a project-local `.cursor/mcp.json` (which is easy to\ncommit by accident), and never commit a file holding a live token:\n\n```json\n{ "mcpServers": { "warmhub": { "url": "https://api.warmhub.ai/mcp", "headers": { "Authorization": "Bearer <your-pat>" } } } }\n```\n';
+
+// ../../packages/warmhub-cli/src/domains/onboard-adapters/gemini.md
+var gemini_default = '# Adapter: Gemini CLI\n\n**How to run this:** paste this whole document into your Gemini CLI session as\nyour first message, or save it to `GEMINI.md` in the project so Gemini loads it\nautomatically. Then follow the Conductor Script below, one step per turn.\n\n**Connecting WarmHub (Act 1 details):** Gemini CLI reads MCP servers from its\n`settings.json` (`~/.gemini/settings.json` or the project `.gemini/settings.json`).\nAdd WarmHub as an HTTP server:\n\n```json\n{ "mcpServers": { "warmhub": { "httpUrl": "https://api.warmhub.ai/mcp" } } }\n```\n\nWarmHub authenticates with a bearer token — the browser OAuth flow is the\npreferred path. Only if your Gemini version cannot complete it, pass a personal\naccess token explicitly. Put it in your **global** `~/.gemini/settings.json`, not\nthe project `.gemini/settings.json` (which is easy to commit by accident), and\nnever commit a file holding a live token:\n\n```json\n{ "mcpServers": { "warmhub": { "httpUrl": "https://api.warmhub.ai/mcp", "headers": { "Authorization": "Bearer <your-pat>" } } } }\n```\n\nRestart Gemini CLI after editing settings.\n';
+
+// ../../packages/warmhub-cli/src/domains/onboard-content.md
+var onboard_content_default = `# WarmHub Onboarding — Conductor Script
+
+> You are guiding a new user through their first hour in WarmHub, one step at
+> a time. They are somewhat technical and comfortable working with an AI agent,
+> but they are brand new to WarmHub. Your job is to walk them from "just signed
+> up" to "I wrote real data through my agent" — patiently, one step per message.
+
+## Operating rules (read before you start)
+
+- **ONE step per message.** Never combine two steps into one response.
+- **STOP and wait** after every step. Do not continue until the user responds.
+- **End every message with a question or a clear prompt** so the user knows it
+  is their turn. Never leave a message without something to respond to.
+- **Keep each message SHORT** — 3–5 sentences max. If it would be longer, split it.
+- **When you need the user to choose, {{ASK_PRIMITIVE}}**
+- **Run the real command yourself** when a step calls for it, then report what
+  came back in plain language. Do not ask the user to run CLI commands unless
+  they prefer the CLI path.
+- **No jargon.** Explain "thing", "shape", "assertion", and "commit" in plain
+  business language the first time each appears (definitions below).
+- **Confirm the "Done when" check** before moving to the next step. If it is not
+  met, help them fix it before advancing — do not skip ahead.
+
+## Plain-language glossary (use these, not jargon)
+
+- **Thing** — a named record in WarmHub (like a row with a name).
+- **Shape** — the template that says what fields a thing has (like a form).
+- **Assertion** — a claim *about* a thing, from a source, with a confidence.
+- **Commit** — one save. Every change is a commit, with who made it attached.
+- **Repo** — a workspace that holds your things, like a project folder.
+- **MCP** — the secure connection that lets your agent call WarmHub directly.
+
+---
+
+## The first hour — four acts
+
+Move through these in order. Each act has a single goal and a concrete
+"Done when" you must verify before continuing.
+
+### Act 1 — Get your agent talking to WarmHub (0–15 min)
+
+**Goal:** the wire is alive — your agent can call a WarmHub tool and get real
+data back. This is the single most important step; do not rush past a failure here.
+
+1. Welcome them in one short message. Tell them the first thing you'll do
+   together is connect this agent to their WarmHub account, and ask if they're
+   ready. **Wait.**
+2. Give them the MCP connection snippet for THIS agent (see the adapter header
+   at the top of this script for the exact config and where it goes). Tell them
+   to paste it, complete the auth flow their adapter described — pasting a
+   personal access token only if it asked for one — and restart the agent. Ask
+   them to tell you once they've done it. **Wait.**
+3. When they confirm, verify the wire yourself: call \`warmhub_doctor\` (or, if it
+   is unavailable, \`warmhub_org_list\`). Report in one sentence whether the
+   connection worked.
+
+**Done when:** a WarmHub tool call succeeds and returns real data. If it fails,
+the usual cause is the token or a missing restart — walk them through it again
+before moving on.
+
+### Act 2 — Explore a pre-seeded repo (15–30 min)
+
+**Goal:** they see what WarmHub stores and why — concretely, before they have
+data of their own. You read; they watch the data model become legible.
+
+1. Tell them WarmHub already has public example repos, and you'll explore one
+   together so the concepts are concrete. Ask which interests them more, or
+   offer to pick a good default. **Wait.**
+2. Describe the repo at a high level: call \`warmhub_repo_describe\` and summarize
+   what kinds of things it holds, in plain language (1–2 sentences). **Wait.**
+3. Pull a few real records: call \`warmhub_thing_query\` (filter by a shape) and
+   then \`warmhub_thing_get\` on one interesting result. Show them one concrete
+   thing and explain what its fields mean. **Wait.**
+4. The bridge moment: ask them a real question about the repo, then answer it by
+   querying — so they see the agent get an answer *they didn't have to write*.
+
+**Done when:** they've seen one real thing explained, and the agent has answered
+one real question against the repo by querying.
+
+### Act 3 — Their first write, through the agent (30–45 min)
+
+**Goal:** they cross from "I see what this is" to "I have one" — a commit
+authored by their agent lands in a repo of their own.
+
+1. Tell them it's time to make something of their own, and that you'll create a
+   small starter repo for them under their personal org. Confirm a simple name
+   (offer a default like \`scratch\`). **Wait.**
+2. Look up their personal org with \`warmhub_org_list\`, then create the repo as
+   \`<their-org>/<name>\`: \`warmhub_repo_create\` (or, for the CLI path,
+   \`wh init <org>/<repo>\`). Confirm in one sentence that the repo exists.
+3. Define a minimal shape first — a brand-new repo has none, and a thing needs a
+   shape to validate against. Check the repo's write contract
+   (\`warmhub_repo_describe\` → \`commitContract\`) for the exact operation format,
+   then prepare a shape-definition op (e.g. a \`Note\` with a single \`text\` field).
+   Explain in one line that a shape is just the form the data fills in.
+4. Write their first thing via \`warmhub_commit_submit\` — submit the shape
+   definition and a short note (a \`Note\` that says they finished onboarding)
+   together in one commit. Tell them what you're saving first, then save it.
+   **Wait** for their go-ahead before writing.
+5. Confirm the write: read it back (\`warmhub_thing_get\`) and tell them the commit
+   landed and that it's attributed to this agent.
+
+**Done when:** a commit authored by their connected agent exists on HEAD of a
+repo they own, and you've read it back to confirm.
+
+### Act 4 — Where to go next (45–60 min)
+
+**Goal:** leave them oriented and able to keep going on their own. (Workspaces —
+the publish/accept loop — are coming but not yet agent-callable, so don't promise
+to run them; describe the idea and point to what works today.)
+
+1. Recap in 2–3 sentences what they just did: connected an agent, explored real
+   data, and wrote their first thing — all through their agent.
+2. Offer concrete next steps and let them pick one: (a) write a few more things
+   in their repo, (b) explore another public repo, or (c) learn the full command
+   set. For (c), tell them to run \`wh prime\`, which loads WarmHub's command
+   reference into any agent's context.
+3. Close warmly in one short message and ask if they'd like to keep going with
+   any of those, or stop here for now.
+
+**Done when:** they know their three next options and have chosen to continue or
+to wrap up.
+
+---
+
+*This script is delivered by \`wh onboard\`. The pedagogy and steps above are
+identical for every agent; only the connection details in the header above differ.*
+`;
+
+// ../../packages/warmhub-cli/src/domains/onboard.ts
+var NEUTRAL_ASK = "present the options as a short numbered list and wait for the user to choose before continuing.";
+var ADAPTERS = {
+  claude: {
+    header: claude_default,
+    ask: "use the AskUserQuestion tool to present the options and wait for their selection."
+  },
+  gemini: {
+    header: gemini_default,
+    ask: NEUTRAL_ASK
+  },
+  codex: {
+    header: codex_default,
+    ask: NEUTRAL_ASK
+  },
+  cursor: {
+    header: cursor_default,
+    ask: NEUTRAL_ASK
+  }
+};
+var SUPPORTED_AGENTS = Object.keys(ADAPTERS);
+function buildOnboarding(opts = {}) {
+  const ask = opts.agent ? ADAPTERS[opts.agent].ask : NEUTRAL_ASK;
+  const body = onboard_content_default.trimEnd().replace("{{ASK_PRIMITIVE}}", ask);
+  if (!opts.agent)
+    return body;
+  const header = ADAPTERS[opts.agent].header.trimEnd();
+  return `${header}
+
+---
+
+${body}`;
+}
+var onboardFlags = {
+  agent: flag.string({
+    description: `Target agent for kickoff + MCP config (${SUPPORTED_AGENTS.join("|")})`
+  })
+};
+var handleOnboard = async (ctx, { flags }) => {
+  const agent = flags.agent;
+  if (agent !== undefined && !SUPPORTED_AGENTS.includes(agent)) {
+    throw new CliError(2 /* UserInput */, "USER_INPUT", `Unknown agent '${agent}'.`, undefined, `Supported agents: ${SUPPORTED_AGENTS.join(", ")}. Omit --agent for the model-agnostic script.`);
+  }
+  const script = buildOnboarding({ agent });
+  writeOutput(ctx, {
+    agent: agent ?? null,
+    supportedAgents: SUPPORTED_AGENTS,
+    script
+  }, () => {
+    ctx.out(script);
+  });
+};
+var ONBOARD_DOMAIN = defineDomain({
+  kind: "flat",
+  name: "onboard",
+  summary: "Output an agentic onboarding script for new users",
+  group: "workflow",
+  args: "",
+  flags: onboardFlags,
+  examples: [
+    "wh onboard",
+    "wh onboard --agent claude",
+    "wh onboard --agent gemini --json"
+  ],
+  handler: handleOnboard
+});
+
 // ../../packages/warmhub-cli/src/domains/org.ts
 var createFlags5 = {
   "display-name": flag.string({ description: "Display name for the org" }),
@@ -37358,6 +37616,7 @@ function registerAllDomains(registry2) {
   registry2.register(SHAPE_DOMAIN);
   registry2.register(DOCTOR_DOMAIN);
   registry2.register(PRIME_DOMAIN);
+  registry2.register(ONBOARD_DOMAIN);
   registry2.register(UPDATE_DOMAIN);
   registry2.register(CHANNEL_DOMAIN);
   registry2.register(NOTIFICATIONS_DOMAIN);
@@ -38477,7 +38736,7 @@ function resolveLogLevel(flags, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.55.0",
+  version: "0.56.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -38500,7 +38759,7 @@ var package_default3 = {
   },
   homepage: "https://docs.warmhub.ai/get-started/quickstart/#connect-via-cli",
   bugs: {
-    email: "support@warmhub.com"
+    email: "support@warmhub.ai"
   },
   engines: {
     node: ">=22"
@@ -39118,4 +39377,4 @@ if (!updateCheckSuppressedByArgv && shouldRunUpdateCheck(updateEligibility)) {
 var interceptedExitCode = await maybeHandleComponentShellBoundary(dispatchArgv);
 process.exitCode = interceptedExitCode === undefined ? await runCli(dispatchArgv, { version: package_default3.version }) : interceptedExitCode;
 
-//# debugId=DD2E54A9CAE4693764756E2164756E21
+//# debugId=6B58DF2D51FA9D1264756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -23,7 +23,7 @@
   },
   "homepage": "https://docs.warmhub.ai/get-started/quickstart/#connect-via-cli",
   "bugs": {
-    "email": "support@warmhub.com"
+    "email": "support@warmhub.ai"
   },
   "engines": {
     "node": ">=22"