chamba 0.0.1 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,1691 @@
+#!/usr/bin/env node
+
+// packages/cli/src/index.ts
+import { realpathSync as realpathSync2 } from "node:fs";
+import { fileURLToPath as fileURLToPath6 } from "node:url";
+
+// packages/server/src/index.ts
+import { serve as honoServe } from "@hono/node-server";
+
+// packages/shared/src/annotations.ts
+import { z as z3 } from "zod";
+
+// packages/shared/src/messages.ts
+import { z as z2 } from "zod";
+
+// packages/shared/src/session.ts
+import { z } from "zod";
+var sessionKindSchema = z.enum(["everyday", "spec"]);
+var sessionStatusSchema = z.enum(["active", "ended"]);
+var sessionMetaSchema = z.object({
+  id: z.string().min(1),
+  kind: sessionKindSchema.optional(),
+  title: z.string().optional(),
+  status: sessionStatusSchema,
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+
+// packages/shared/src/messages.ts
+var attachmentSchema = z2.object({
+  id: z2.string().min(1),
+  name: z2.string().min(1),
+  relPath: z2.string().min(1),
+  contentType: z2.string().min(1),
+  size: z2.number().int().nonnegative()
+});
+var messagePayloadSchema = z2.object({
+  text: z2.string().min(1).optional(),
+  attachments: z2.array(attachmentSchema).optional()
+}).refine((p) => (p.text?.length ?? 0) > 0 || (p.attachments?.length ?? 0) > 0, {
+  message: "a message needs text or at least one attachment"
+});
+var systemReasonSchema = z2.enum([
+  "session-created",
+  "user-moved-away",
+  "session-ended",
+  "kind-chosen"
+]);
+var systemPayloadSchema = z2.object({
+  reason: systemReasonSchema,
+  to: z2.string().min(1).optional(),
+  kind: sessionKindSchema.optional()
+});
+
+// packages/shared/src/annotations.ts
+var ANNOTATION_BATCH = "annotation-batch";
+var annotationSourceSchema = z3.object({
+  file: z3.string().min(1),
+  line: z3.number().int().positive().optional(),
+  column: z3.number().int().positive().optional()
+});
+var annotationComponentSchema = z3.object({
+  name: z3.string().min(1),
+  source: annotationSourceSchema.optional()
+});
+var annotationTargetSchema = z3.object({
+  selector: z3.string().min(1),
+  pageUrl: z3.string().min(1),
+  viewport: z3.object({
+    width: z3.number().int().positive(),
+    height: z3.number().int().positive()
+  }),
+  label: z3.string().optional(),
+  component: annotationComponentSchema.optional()
+});
+var annotationItemSchema = z3.object({
+  note: z3.string().min(1).optional(),
+  target: annotationTargetSchema,
+  screenshot: attachmentSchema.optional()
+});
+var annotationBatchPayloadSchema = z3.object({
+  items: z3.array(annotationItemSchema).min(1)
+});
+
+// packages/shared/src/api.ts
+import { z as z7 } from "zod";
+
+// packages/shared/src/events.ts
+import { z as z4 } from "zod";
+var eventSourceSchema = z4.enum(["user", "agent", "system"]);
+var eventEnvelopeSchema = z4.object({
+  id: z4.string().uuid(),
+  seq: z4.number().int().nonnegative(),
+  sessionId: z4.string().min(1),
+  ts: z4.string().datetime(),
+  type: z4.string().min(1),
+  source: eventSourceSchema,
+  payload: z4.unknown()
+});
+
+// packages/shared/src/presence.ts
+import { z as z5 } from "zod";
+var presenceSchema = z5.enum(["listening", "working", "away"]);
+
+// packages/shared/src/spec.ts
+import { z as z6 } from "zod";
+var QUESTION_CARD = "question-card";
+var DECISION = "decision";
+var ARTIFACT = "artifact";
+var questionOptionSchema = z6.object({
+  label: z6.string().min(1),
+  description: z6.string().min(1),
+  recommended: z6.boolean().optional()
+});
+var questionCardPayloadSchema = z6.object({
+  cardId: z6.string().uuid(),
+  question: z6.string().min(1),
+  options: z6.array(questionOptionSchema).min(2).max(6),
+  /** Optional custom wording for the stop-anytime affordance. */
+  stopHint: z6.string().min(1).optional()
+});
+var decisionStatusSchema = z6.enum(["confirmed", "assumed"]);
+var decisionPayloadSchema = z6.object({
+  summary: z6.string().min(1),
+  status: decisionStatusSchema,
+  detail: z6.string().min(1).optional()
+});
+var artifactKindSchema = z6.enum(["draft", "mock", "diagram"]);
+var artifactRefSchema = z6.object({
+  kind: artifactKindSchema,
+  name: z6.string().min(1),
+  relPath: z6.string().min(1),
+  contentType: z6.string().min(1),
+  size: z6.number().int().nonnegative()
+});
+var artifactPayloadSchema = z6.object({
+  artifact: artifactRefSchema
+});
+
+// packages/shared/src/api.ts
+var cursorSchema = z7.number().int().nonnegative();
+var createSessionReqSchema = z7.object({
+  kind: sessionKindSchema.optional(),
+  title: z7.string().min(1).optional()
+});
+var setSessionKindReqSchema = z7.object({
+  kind: sessionKindSchema
+});
+var messageBodySchema = z7.object({
+  text: z7.string().min(1).optional(),
+  attachmentIds: z7.array(z7.string().min(1)).optional()
+}).refine((r) => (r.text?.length ?? 0) > 0 || (r.attachmentIds?.length ?? 0) > 0, {
+  message: "a message needs text or at least one attachment"
+});
+var annotationItemReqSchema = z7.object({
+  note: z7.string().min(1).optional(),
+  target: annotationTargetSchema,
+  screenshotAttachmentId: z7.string().min(1).optional()
+});
+var postAnnotationsReqSchema = z7.object({
+  items: z7.array(annotationItemReqSchema).min(1)
+});
+var moveAwayReqSchema = z7.object({
+  to: z7.string().min(1).optional()
+});
+var postQuestionCardReqSchema = questionCardPayloadSchema;
+var postDecisionReqSchema = decisionPayloadSchema;
+var postArtifactReqSchema = z7.object({
+  kind: artifactKindSchema,
+  name: z7.string().min(1),
+  content: z7.string().min(1)
+});
+var attachmentResSchema = z7.object({
+  attachment: attachmentSchema
+});
+var eventResSchema = z7.object({
+  event: eventEnvelopeSchema
+});
+var pollResSchema = z7.object({
+  events: z7.array(eventEnvelopeSchema),
+  cursor: cursorSchema,
+  ended: z7.boolean().optional()
+});
+var fetchMoreSchema = z7.object({
+  hasMore: z7.boolean(),
+  earliestLoadedSeq: cursorSchema,
+  hint: z7.string()
+});
+var attachDigestSchema = z7.object({
+  meta: sessionMetaSchema,
+  presence: presenceSchema,
+  tail: z7.array(eventEnvelopeSchema),
+  cursor: cursorSchema,
+  fetchMore: fetchMoreSchema
+});
+var sessionSummarySchema = z7.object({
+  meta: sessionMetaSchema,
+  presence: presenceSchema
+});
+var listResSchema = z7.object({
+  sessions: z7.array(sessionSummarySchema)
+});
+var sessionResSchema = z7.object({
+  session: sessionSummarySchema
+});
+var healthResSchema = z7.object({
+  ok: z7.boolean(),
+  sessions: cursorSchema,
+  home: z7.string().min(1).optional(),
+  port: z7.number().int().positive().optional(),
+  version: z7.string().min(1).optional()
+});
+
+// packages/shared/src/issues.ts
+import { z as z8 } from "zod";
+var issueTypeSchema = z8.enum(["bug", "feature"]);
+var postIssueReqSchema = z8.object({
+  type: issueTypeSchema,
+  text: z8.string().min(1),
+  screenshotAttachmentIds: z8.array(z8.string().min(1)).optional()
+});
+var issueResSchema = z8.object({
+  id: z8.string().min(1),
+  path: z8.string().min(1)
+});
+
+// packages/shared/src/ws.ts
+import { z as z9 } from "zod";
+var wsServerMessageSchema = z9.discriminatedUnion("t", [
+  z9.object({
+    t: z9.literal("hello"),
+    meta: sessionMetaSchema,
+    presence: presenceSchema
+  }),
+  z9.object({
+    t: z9.literal("append"),
+    event: eventEnvelopeSchema
+  }),
+  z9.object({
+    t: z9.literal("presence"),
+    state: presenceSchema
+  }),
+  z9.object({
+    t: z9.literal("kind"),
+    meta: sessionMetaSchema
+  }),
+  z9.object({
+    t: z9.literal("ended"),
+    meta: sessionMetaSchema
+  })
+]);
+
+// packages/server/src/app.ts
+import { createNodeWebSocket } from "@hono/node-ws";
+import { Hono } from "hono";
+
+// packages/server/src/inject.ts
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveInjectDist() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const dev = path.resolve(here, "../../inject/dist");
+  const packaged = path.resolve(here, "../inject");
+  return [dev, packaged].find((dir) => existsSync(path.join(dir, "annotate.js"))) ?? dev;
+}
+
+// packages/server/src/render.ts
+import { marked } from "marked";
+
+// packages/server/src/static.ts
+import { existsSync as existsSync2 } from "node:fs";
+import path2 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+function resolveWebDist() {
+  const here = path2.dirname(fileURLToPath2(import.meta.url));
+  const dev = path2.resolve(here, "../../web/dist");
+  const packaged = path2.resolve(here, "../web");
+  return [dev, packaged].find((dir) => existsSync2(path2.join(dir, "index.html"))) ?? dev;
+}
+
+// packages/server/src/app.ts
+var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+
+// packages/server/src/lifecycle.ts
+import { open, readFile as readFile2, rm } from "node:fs/promises";
+
+// packages/server/src/sessions/paths.ts
+import { existsSync as existsSync3, realpathSync } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path3 from "node:path";
+function defaultContext() {
+  return { cwd: process.cwd(), env: process.env };
+}
+function resolveHome(ctx = defaultContext()) {
+  return findExistingHome(ctx) ?? plannedHome(ctx);
+}
+function findExistingHome(ctx = defaultContext()) {
+  const dir = ctx.env.CHAMBA_DIR;
+  if (dir && dir.length > 0) return canonicalize(dir);
+  const inside = enclosingChamba(ctx.cwd);
+  if (inside) return canonicalize(inside);
+  const root = gitRoot(ctx.cwd);
+  let cursor = path3.resolve(ctx.cwd);
+  while (true) {
+    if (existsSync3(path3.join(cursor, ".chamba"))) return canonicalize(path3.join(cursor, ".chamba"));
+    if (!root) break;
+    if (cursor === root) break;
+    const parent = path3.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+function plannedHome(ctx = defaultContext()) {
+  const root = gitRoot(ctx.cwd) ?? path3.resolve(ctx.cwd);
+  return canonicalize(path3.join(root, ".chamba"));
+}
+function gitRoot(cwd) {
+  let cursor = path3.resolve(cwd);
+  while (true) {
+    if (existsSync3(path3.join(cursor, ".git"))) return cursor;
+    const parent = path3.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+function enclosingChamba(cwd) {
+  const parts = path3.resolve(cwd).split(path3.sep);
+  const index = parts.lastIndexOf(".chamba");
+  if (index < 0) return null;
+  return parts.slice(0, index + 1).join(path3.sep) || path3.sep;
+}
+function canonicalize(p) {
+  const resolved = path3.resolve(p);
+  let existing = resolved;
+  const tail = [];
+  while (!existsSync3(existing)) {
+    tail.unshift(path3.basename(existing));
+    const parent = path3.dirname(existing);
+    if (parent === existing) return resolved;
+    existing = parent;
+  }
+  return path3.join(realpathSync(existing), ...tail);
+}
+function sessionsDir(home) {
+  return path3.join(home, "sessions");
+}
+function sessionDir(home, id) {
+  return path3.join(sessionsDir(home), id);
+}
+function metaPath(home, id) {
+  return path3.join(sessionDir(home, id), "meta.json");
+}
+function pidfilePath(home) {
+  return path3.join(home, "server.json");
+}
+function agentStatePath(home) {
+  return path3.join(home, "agent-state.json");
+}
+async function ensureChambaHome(home) {
+  await mkdir(sessionsDir(home), { recursive: true });
+  await ensureGitignored(home);
+}
+async function ensureGitignored(home) {
+  if (path3.basename(home) !== ".chamba") return;
+  const gitignore = path3.join(path3.dirname(home), ".gitignore");
+  const entry = ".chamba/";
+  try {
+    let content = "";
+    try {
+      content = await readFile(gitignore, "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT") return;
+    }
+    const already = content.split(/\r?\n/).some((line) => {
+      const trimmed = line.trim();
+      return trimmed === entry || trimmed === ".chamba";
+    });
+    if (already) return;
+    const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    await appendFile(gitignore, `${prefix}${entry}
+`, "utf8");
+  } catch {
+  }
+}
+
+// packages/server/src/lifecycle.ts
+function readServerInfo(home) {
+  return readPidfile(pidfilePath(home));
+}
+async function readPidfile(file) {
+  try {
+    const raw = await readFile2(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.port === "number") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// packages/server/src/port.ts
+var DEFAULT_PORT = 4319;
+var DEFAULT_BIND_HOST = "127.0.0.1";
+function resolveBindHost(argv = process.argv.slice(2)) {
+  const flag = readFlag(argv, "--host");
+  if (flag !== void 0 && flag.length > 0) return flag;
+  const env = process.env.CHAMBA_HOST;
+  if (env !== void 0 && env.length > 0) return env;
+  return DEFAULT_BIND_HOST;
+}
+function resolvePort(argv = process.argv.slice(2), home) {
+  const flag = readFlag(argv, "--port");
+  if (flag !== void 0) return parsePort(flag, "--port");
+  const env = process.env.CHAMBA_PORT;
+  if (env !== void 0 && env.length > 0) return parsePort(env, "CHAMBA_PORT");
+  return home !== void 0 ? derivePort(home) : DEFAULT_PORT;
+}
+function derivePort(home) {
+  let hash = 2166136261;
+  for (let i = 0; i < home.length; i++) {
+    hash ^= home.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return DEFAULT_PORT + Math.abs(hash) % 512;
+}
+function readFlag(argv, name) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === name) return argv[i + 1];
+    if (arg?.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+  }
+  return void 0;
+}
+function parsePort(value, source) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid ${source}: ${value}`);
+  }
+  return port;
+}
+
+// packages/server/src/version.ts
+import { existsSync as existsSync4, readFileSync } from "node:fs";
+import path4 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function chambaVersion() {
+  let dir = path4.dirname(fileURLToPath3(import.meta.url));
+  for (; ; ) {
+    const manifest = path4.join(dir, "package.json");
+    if (existsSync4(manifest)) {
+      try {
+        const { version } = JSON.parse(readFileSync(manifest, "utf8"));
+        if (typeof version === "string" && version) return version;
+      } catch {
+      }
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir) return "0.0.0-dev";
+    dir = parent;
+  }
+}
+
+// packages/server/src/sessions/meta.ts
+import { readdir, readFile as readFile3, rename, rm as rm2, writeFile } from "node:fs/promises";
+async function readMeta(home, id) {
+  try {
+    const raw = await readFile3(metaPath(home, id), "utf8");
+    return sessionMetaSchema.parse(JSON.parse(raw));
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function listSessionIds(home) {
+  try {
+    const entries = await readdir(sessionsDir(home), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+// packages/server/src/index.ts
+var DEFAULT_IDLE_MS = 5 * 6e4;
+
+// packages/cli/src/args.ts
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === void 0) continue;
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[arg.slice(2)] = next;
+      i++;
+    } else {
+      flags[arg.slice(2)] = "true";
+    }
+  }
+  return { positionals, flags };
+}
+
+// packages/cli/src/client.ts
+import { readFile as readFile4 } from "node:fs/promises";
+import path5 from "node:path";
+var ChannelError = class extends Error {
+  constructor(status2, message) {
+    super(message);
+    this.status = status2;
+    this.name = "ChannelError";
+  }
+};
+var Client = class {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+  /** Liveness probe with a short deadline; never throws - `false` means "spawn it". */
+  async isUp(timeoutMs = 800) {
+    try {
+      const res = await this.fetch("/api/health", { method: "GET", timeoutMs });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+  async health() {
+    return this.json("/api/health", { method: "GET", timeoutMs: 2e3 }, healthResSchema);
+  }
+  async create(req) {
+    const res = await this.json(
+      "/api/sessions",
+      { method: "POST", body: req, timeoutMs: 5e3 },
+      sessionResSchema
+    );
+    return res.session;
+  }
+  async list() {
+    const res = await this.json("/api/sessions", { method: "GET", timeoutMs: 5e3 }, listResSchema);
+    return res.sessions;
+  }
+  async get(id) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}`,
+      { method: "GET", timeoutMs: 5e3 },
+      sessionResSchema
+    );
+    return res.session;
+  }
+  async postMessage(id, body) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/messages`,
+      { method: "POST", body, timeoutMs: 5e3 },
+      eventResSchema
+    );
+    return res.event;
+  }
+  async reply(id, body) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/reply`,
+      { method: "POST", body, timeoutMs: 5e3 },
+      eventResSchema
+    );
+    return res.event;
+  }
+  /** Post a structured interview question card (spec sessions). Agent-sourced. */
+  async postQuestionCard(id, body) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/cards`,
+      { method: "POST", body, timeoutMs: 5e3 },
+      eventResSchema
+    );
+    return res.event;
+  }
+  /** Record a decision-log entry (confirmed vs. assumed). Agent-sourced. */
+  async postDecision(id, body) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/decisions`,
+      { method: "POST", body, timeoutMs: 5e3 },
+      eventResSchema
+    );
+    return res.event;
+  }
+  /** Author or revise a draft/mock/diagram artifact by posting its source text. */
+  async postArtifact(id, body) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/artifacts`,
+      { method: "POST", body, timeoutMs: 1e4 },
+      eventResSchema
+    );
+    return res.event;
+  }
+  /**
+   * Upload a local file into the session, returning its stored reference. The
+   * agent uses this to send an image back (`reply --image`); the returned id is
+   * then referenced from a `reply`. Multipart, so the server persists the raw
+   * bytes into the session directory rather than smuggling them through JSON.
+   */
+  async uploadAttachment(id, filePath) {
+    const bytes = await readFile4(filePath);
+    const form = new FormData();
+    form.append("file", new Blob([bytes]), path5.basename(filePath));
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/attachments`,
+      { method: "POST", body: form, timeoutMs: 3e4 },
+      attachmentResSchema
+    );
+    return res.attachment;
+  }
+  /**
+   * The blocking long-poll. The server parks for up to `waitMs`; the client
+   * deadline is a little longer so a healthy server always answers before the
+   * client gives up (a client timeout would look like a lost message).
+   */
+  async poll(id, since, waitMs) {
+    return this.json(
+      `/api/sessions/${encodeURIComponent(id)}/poll?since=${since}&wait=${waitMs}`,
+      { method: "GET", timeoutMs: waitMs + 5e3 },
+      pollResSchema
+    );
+  }
+  async events(id, since, limit) {
+    const query = limit === void 0 ? `since=${since}` : `since=${since}&limit=${limit}`;
+    return this.json(
+      `/api/sessions/${encodeURIComponent(id)}/events?${query}`,
+      { method: "GET", timeoutMs: 5e3 },
+      pollResSchema
+    );
+  }
+  async attach(id, tail) {
+    return this.json(
+      `/api/sessions/${encodeURIComponent(id)}/attach?tail=${tail}`,
+      { method: "GET", timeoutMs: 5e3 },
+      attachDigestSchema
+    );
+  }
+  async end(id) {
+    const res = await this.json(
+      `/api/sessions/${encodeURIComponent(id)}/end`,
+      { method: "POST", timeoutMs: 5e3 },
+      sessionResSchema
+    );
+    return res.session;
+  }
+  async json(path12, options, schema) {
+    const res = await this.fetch(path12, options);
+    if (!res.ok) throw await toError(res);
+    return schema.parse(await res.json());
+  }
+  async fetch(path12, options) {
+    const { method = "GET", body, timeoutMs } = options;
+    const controller = timeoutMs !== void 0 ? new AbortController() : void 0;
+    const timer = controller && timeoutMs !== void 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+    try {
+      return await fetch(new URL(path12, this.baseUrl), {
+        method,
+        signal: controller?.signal,
+        ...bodyInit(body)
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+};
+function bodyInit(body) {
+  if (body === void 0) return {};
+  if (body instanceof FormData) return { body };
+  return { headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+}
+async function toError(res) {
+  let message = `${res.status} ${res.statusText}`;
+  try {
+    const body = await res.json();
+    if (typeof body.error === "string") message = body.error;
+  } catch {
+  }
+  return new ChannelError(res.status, message);
+}
+
+// packages/cli/src/output.ts
+import path6 from "node:path";
+import { z as z10 } from "zod";
+function out(message) {
+  process.stdout.write(`${message}
+`);
+}
+function note(message) {
+  process.stderr.write(`${message}
+`);
+}
+function eventText(event) {
+  const payload = event.payload;
+  if (payload && typeof payload === "object") {
+    const record = payload;
+    if (typeof record.text === "string") return record.text;
+    if (typeof record.reason === "string") return record.reason;
+  }
+  return "";
+}
+function eventAttachments(event) {
+  if (!event.payload || typeof event.payload !== "object") return [];
+  const parsed = z10.array(attachmentSchema).safeParse(event.payload.attachments);
+  return parsed.success ? parsed.data : [];
+}
+function formatSystemEvent(event) {
+  const parsed = systemPayloadSchema.safeParse(event.payload);
+  if (!parsed.success) return `\xB7 ${eventText(event)}`;
+  const { reason, to, kind } = parsed.data;
+  switch (reason) {
+    case "user-moved-away":
+      return to ? `\xB7 You moved to another session (${to})` : "\xB7 The user moved away";
+    case "session-ended":
+      return "\xB7 Session ended";
+    case "session-created":
+      return "\xB7 Session created";
+    case "kind-chosen":
+      return kind ? `\xB7 Session set to ${kind}` : "\xB7 Session kind chosen";
+    default:
+      return `\xB7 ${reason}`;
+  }
+}
+function formatEvent(event) {
+  if (event.source === "system") return formatSystemEvent(event);
+  const who = event.source === "user" ? "you" : "agent";
+  const text = eventText(event);
+  return text ? `${who}: ${text}` : `${who}:`;
+}
+function annotationItems(event) {
+  const parsed = annotationBatchPayloadSchema.safeParse(event.payload);
+  return parsed.success ? parsed.data.items : [];
+}
+function formatAnnotationBatch(event, home) {
+  const items = annotationItems(event);
+  const who = event.source === "user" ? "you" : "agent";
+  const lines = [`${who} [${items.length} annotation${items.length === 1 ? "" : "s"}]:`];
+  items.forEach((item, index) => {
+    const { target } = item;
+    lines.push(`  ${index + 1}. ${item.note ?? "(no comment)"}`);
+    lines.push(`     element: ${target.label ?? target.selector}`);
+    lines.push(`     selector: ${target.selector}`);
+    lines.push(
+      `     page: ${target.pageUrl}   viewport: ${target.viewport.width}x${target.viewport.height}`
+    );
+    if (target.component) {
+      const source = target.component.source;
+      const at = source ? `  (${source.file}${source.line ? `:${source.line}` : ""})` : "";
+      lines.push(`     component: ${target.component.name}${at}`);
+    }
+    if (item.screenshot) {
+      const abs = path6.join(sessionDir(home, event.sessionId), item.screenshot.relPath);
+      lines.push(`     [shot] ${item.screenshot.name} -> ${abs}`);
+    }
+  });
+  return lines;
+}
+function formatQuestionCard(event) {
+  const parsed = questionCardPayloadSchema.safeParse(event.payload);
+  if (!parsed.success) return [formatEvent(event)];
+  const card = parsed.data;
+  const lines = [`agent [question]: ${card.question}`];
+  card.options.forEach((option, index) => {
+    const rec = option.recommended ? " (recommended)" : "";
+    lines.push(`  ${index + 1}. ${option.label}${rec} - ${option.description}`);
+  });
+  lines.push(
+    `  (the user can also type a custom answer${card.stopHint ? ` or ${card.stopHint}` : ", or stop anytime"})`
+  );
+  return lines;
+}
+function formatDecision(event) {
+  const parsed = decisionPayloadSchema.safeParse(event.payload);
+  if (!parsed.success) return formatEvent(event);
+  const { status: status2, summary, detail } = parsed.data;
+  return `agent [decision: ${status2}]: ${summary}${detail ? ` - ${detail}` : ""}`;
+}
+function formatArtifact(event, home) {
+  const parsed = artifactRefSchema.safeParse(
+    event.payload?.artifact
+  );
+  if (!parsed.success) return formatEvent(event);
+  const ref = parsed.data;
+  const abs = path6.join(sessionDir(home, event.sessionId), ref.relPath);
+  return `agent [artifact ${ref.kind} "${ref.name}"] -> ${abs}`;
+}
+function printEvents(events, home) {
+  for (const event of events) {
+    if (event.type === ANNOTATION_BATCH) {
+      for (const line of formatAnnotationBatch(event, home)) out(line);
+      continue;
+    }
+    if (event.type === QUESTION_CARD) {
+      for (const line of formatQuestionCard(event)) out(line);
+      continue;
+    }
+    if (event.type === DECISION) {
+      out(formatDecision(event));
+      continue;
+    }
+    if (event.type === ARTIFACT) {
+      out(formatArtifact(event, home));
+      continue;
+    }
+    out(formatEvent(event));
+    for (const att of eventAttachments(event)) {
+      out(`  [file] ${att.name} -> ${path6.join(sessionDir(home, event.sessionId), att.relPath)}`);
+    }
+  }
+}
+function formatSession(meta, presence, current) {
+  const marker = current ? "*" : " ";
+  const title = meta.title ? ` "${meta.title}"` : "";
+  const live = presence ? ` ${presence}` : "";
+  return `${marker} ${meta.id}  ${meta.status}${live}  ${meta.kind ?? "unset"}${title}`;
+}
+
+// packages/cli/src/commands/artifact.ts
+import { readFile as readFile6 } from "node:fs/promises";
+
+// packages/cli/src/state.ts
+import { randomUUID } from "node:crypto";
+import { mkdir as mkdir2, readFile as readFile5, rename as rename2, rm as rm3, writeFile as writeFile2 } from "node:fs/promises";
+import path7 from "node:path";
+import { z as z11 } from "zod";
+var agentStateSchema = z11.object({
+  currentSessionId: z11.string().optional(),
+  cursors: z11.record(z11.number().int().nonnegative()).default({})
+});
+async function readState(home = resolveHome()) {
+  try {
+    const raw = await readFile5(agentStatePath(home), "utf8");
+    return agentStateSchema.parse(JSON.parse(raw));
+  } catch {
+    return { cursors: {} };
+  }
+}
+async function writeState(state, home = resolveHome()) {
+  const file = agentStatePath(home);
+  await mkdir2(path7.dirname(file), { recursive: true });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile2(tmp, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+    await rename2(tmp, file);
+  } catch (err) {
+    await rm3(tmp, { force: true }).catch(() => void 0);
+    throw err;
+  }
+}
+function cursorFor(state, id) {
+  return state.cursors[id] ?? 0;
+}
+function withSession(state, id, cursor) {
+  return { currentSessionId: id, cursors: { ...state.cursors, [id]: cursor } };
+}
+
+// packages/cli/src/commands/context.ts
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+async function resolveSessionId(ctx) {
+  const flag = ctx.flags.session;
+  if (flag === "true" || flag === "") {
+    throw new UsageError("`--session` needs a session id, e.g. --session <id>");
+  }
+  if (flag) return flag;
+  const state = await readState(ctx.home);
+  if (state.currentSessionId) return state.currentSessionId;
+  throw new UsageError("no current session - run `chamba open` or pass --session <id>");
+}
+function intFlag(value, fallback) {
+  if (value === void 0) return fallback;
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+
+// packages/cli/src/commands/artifact.ts
+async function artifact(ctx) {
+  const kind = artifactKindSchema.safeParse(ctx.flags.kind);
+  if (!kind.success) {
+    throw new UsageError(
+      "usage: chamba artifact --kind draft|mock|diagram --name <name> --file <path>"
+    );
+  }
+  const name = ctx.flags.name?.trim();
+  if (!name || name === "true") throw new UsageError("chamba artifact needs --name <name>");
+  const file = ctx.flags.file;
+  if (!file || file === "true") throw new UsageError("chamba artifact needs --file <path>");
+  let content;
+  try {
+    content = await readFile6(file, "utf8");
+  } catch (err) {
+    throw new UsageError(`could not read ${file}: ${err.message}`);
+  }
+  const result = postArtifactReqSchema.safeParse({ kind: kind.data, name, content });
+  if (!result.success) {
+    throw new UsageError(
+      `invalid artifact: ${result.error.issues.map((i) => i.message).join("; ")}`
+    );
+  }
+  const id = await resolveSessionId(ctx);
+  const event = await ctx.client.postArtifact(id, result.data);
+  const ref = event.payload.artifact;
+  note(`posted ${kind.data} "${name}" to ${id}${ref?.relPath ? ` (${ref.relPath})` : ""}`);
+  return 0;
+}
+
+// packages/cli/src/commands/ask.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFile as readFile7 } from "node:fs/promises";
+async function ask(ctx) {
+  const source = await readCardSource(ctx);
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (err) {
+    throw new UsageError(`--json is not valid JSON: ${err.message}`);
+  }
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && !("cardId" in parsed)) {
+    parsed.cardId = randomUUID2();
+  }
+  const result = postQuestionCardReqSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new UsageError(
+      `invalid question card: ${result.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`
+    );
+  }
+  const id = await resolveSessionId(ctx);
+  await ctx.client.postQuestionCard(id, result.data);
+  note(`asked ${id}: "${result.data.question}" (${result.data.options.length} options)`);
+  return 0;
+}
+async function readCardSource(ctx) {
+  if (ctx.flags.json && ctx.flags.json !== "true") return ctx.flags.json;
+  const file = ctx.positionals[0];
+  if (file) {
+    try {
+      return await readFile7(file, "utf8");
+    } catch (err) {
+      throw new UsageError(`could not read card file ${file}: ${err.message}`);
+    }
+  }
+  throw new UsageError(
+    `usage: chamba ask --json '{"question":"...","options":[...]}' | <file.json>`
+  );
+}
+
+// packages/cli/src/commands/attach.ts
+async function attach(ctx) {
+  const flagId = ctx.flags.session === "true" ? void 0 : ctx.flags.session || void 0;
+  const id = ctx.positionals[0] ?? flagId;
+  if (!id) throw new UsageError("usage: chamba attach <session-id>");
+  const tail = intFlag(ctx.flags.tail, 20);
+  const digest = await ctx.client.attach(id, tail);
+  note(`session ${digest.meta.id} - ${digest.meta.status}, agent ${digest.presence}`);
+  if (digest.fetchMore.hasMore) note(`(${digest.fetchMore.hint})`);
+  printEvents(digest.tail, ctx.home);
+  const state = await readState(ctx.home);
+  await writeState(withSession(state, digest.meta.id, digest.cursor), ctx.home);
+  note(`now current - poll from cursor ${digest.cursor}`);
+  return 0;
+}
+
+// packages/cli/src/commands/decision.ts
+async function decision(ctx) {
+  const summary = ctx.flags.summary?.trim();
+  if (!summary || summary === "true") {
+    throw new UsageError(
+      'usage: chamba decision --status confirmed|assumed --summary "..." [--detail "..."]'
+    );
+  }
+  const detail = ctx.flags.detail && ctx.flags.detail !== "true" ? ctx.flags.detail : void 0;
+  const result = postDecisionReqSchema.safeParse({
+    summary,
+    status: ctx.flags.status,
+    ...detail ? { detail } : {}
+  });
+  if (!result.success) {
+    throw new UsageError("--status must be `confirmed` or `assumed`");
+  }
+  const id = await resolveSessionId(ctx);
+  await ctx.client.postDecision(id, result.data);
+  note(`recorded ${result.data.status} decision on ${id}`);
+  return 0;
+}
+
+// packages/cli/src/commands/end.ts
+async function end(ctx) {
+  const id = await resolveSessionId(ctx);
+  const summary = await ctx.client.end(id);
+  note(`session ${summary.meta.id} ended`);
+  return 0;
+}
+
+// packages/cli/src/commands/export.ts
+import { copyFile, mkdir as mkdir3, readFile as readFile8, rm as rm4, writeFile as writeFile3 } from "node:fs/promises";
+import path8 from "node:path";
+async function exportCmd(ctx) {
+  const dest = ctx.positionals[0];
+  if (!dest) throw new UsageError("usage: chamba export <dest> [--session <id>]");
+  const id = await resolveSessionId(ctx);
+  const { events } = await ctx.client.events(id, 0);
+  const summary = await assemblePackage({
+    events,
+    sessionDir: sessionDir(ctx.home, id),
+    dest: path8.resolve(dest)
+  });
+  note(
+    `exported ${id} -> ${path8.resolve(dest)} (spec.md${summary.hasDraft ? "" : " placeholder"}, ${summary.assets.length} asset${summary.assets.length === 1 ? "" : "s"}, ${summary.decisions} decision${summary.decisions === 1 ? "" : "s"})`
+  );
+  out(path8.resolve(dest));
+  return 0;
+}
+async function assemblePackage(input) {
+  const artifacts = /* @__PURE__ */ new Map();
+  let canonicalDraft;
+  const decisions = [];
+  for (const event of input.events) {
+    if (event.type === ARTIFACT) {
+      const parsed = artifactRefSchema.safeParse(
+        event.payload?.artifact
+      );
+      if (!parsed.success) continue;
+      const ref = parsed.data;
+      artifacts.set(`${ref.kind}:${ref.name}`, ref);
+      if (ref.kind === "draft") canonicalDraft = ref;
+    } else if (event.type === DECISION) {
+      const parsed = decisionPayloadSchema.safeParse(event.payload);
+      if (parsed.success) decisions.push(parsed.data);
+    }
+  }
+  await mkdir3(input.dest, { recursive: true });
+  const assetsDir = path8.join(input.dest, "assets");
+  await rm4(assetsDir, { recursive: true, force: true });
+  const draftBody = canonicalDraft ? await readArtifact(input.sessionDir, canonicalDraft) : void 0;
+  await writeFile3(
+    path8.join(input.dest, "spec.md"),
+    draftBody ?? "# Spec\n\n_No draft was authored in this session._\n",
+    "utf8"
+  );
+  const assets = [];
+  for (const ref of artifacts.values()) {
+    if (ref === canonicalDraft) continue;
+    const src = path8.join(input.sessionDir, ref.relPath);
+    const base = path8.basename(ref.relPath);
+    try {
+      await mkdir3(assetsDir, { recursive: true });
+      await copyFile(src, path8.join(assetsDir, base));
+      assets.push(base);
+    } catch {
+    }
+  }
+  await writeFile3(path8.join(input.dest, "decisions.md"), renderDecisions(decisions), "utf8");
+  return { hasDraft: Boolean(draftBody), assets, decisions: decisions.length };
+}
+async function readArtifact(dir, ref) {
+  try {
+    return await readFile8(path8.join(dir, ref.relPath), "utf8");
+  } catch {
+    return void 0;
+  }
+}
+function renderDecisions(decisions) {
+  const confirmed = decisions.filter((d) => d.status === "confirmed");
+  const assumed = decisions.filter((d) => d.status === "assumed");
+  const section = (items) => items.length === 0 ? "_None._\n" : `${items.map((d) => `- ${d.summary}${d.detail ? `
+  ${d.detail}` : ""}`).join("\n")}
+`;
+  return [
+    "# Decision log",
+    "",
+    "## Confirmed",
+    "",
+    section(confirmed),
+    "## Assumed / open questions",
+    "",
+    section(assumed)
+  ].join("\n");
+}
+
+// packages/cli/src/commands/help.ts
+var USAGE = `chamba - a browser companion for your terminal agent
+
+Usage:
+  chamba                     list sessions and show which is current
+  chamba init [dir]          create the .chamba workspace (at the git root, or
+             [--here]        <dir>, or the current dir with --here); prints its
+                             location and per-project port
+  chamba open [--kind K]     start a session (K: everyday | spec), print its URL
+             [--title T]     (creates the workspace at the repo root if none yet)
+  chamba poll                wait for the next human/system events, blocking across
+             [--wait ms]     quiet windows on its own until a batch arrives (it may
+             [--for ms]      include "user moved away" -> attach, or "session ended"
+             [--once]        -> stop). After a quiet stretch (--for, default 4m) it
+                             prints a heartbeat and exits 0 - just re-run. --once does
+                             one bounded check instead (scripts/tests); --wait is the
+                             per-request window (max 30s)
+  chamba reply <text>        send a line from the agent into the session
+             [--file a,b]    attach files by path (comma-separated); --image is
+             [--image a,b]   an alias. text is optional when files are attached
+  chamba attach <id>         load a session's recent tail and make it current
+             [--tail N]
+  chamba end                 end the current session
+  chamba stop                stop this project's server (it otherwise self-stops
+                             after an idle spell); the next open starts a fresh one
+
+Spec sessions (open with --kind spec):
+  chamba ask --json '{...}'  post a question card (question + 2-6 options with
+             | <file.json>   descriptions, optional "recommended"); a cardId is
+                             created for you. The answer returns as a message
+  chamba decision            record a decision: --status confirmed|assumed
+             --status S        --summary "..." [--detail "..."]
+             --summary T
+  chamba artifact            author/revise a draft (markdown), mock (HTML), or
+             --kind K          diagram (mermaid): --kind draft|mock|diagram
+             --name N          --name <name> --file <path>. Re-post to revise
+             --file P
+  chamba export <dest>       copy the finalized package (spec.md + decisions.md
+                             + assets/) to <dest> (e.g. docs/)
+
+  chamba skill install       install the chamba skill (/chamba) into
+             [--global]      ./.claude/skills, or ~/.claude/skills with --global
+  chamba --version           print the chamba version
+  chamba help                show this help
+
+Global:
+  --session <id>             act on a specific session instead of the current one
+  --port <n>                 server port (default: CHAMBA_PORT, else a per-project
+                             port derived from the workspace location)`;
+function help(_ctx) {
+  note(USAGE);
+  return Promise.resolve(0);
+}
+
+// packages/cli/src/commands/init.ts
+import path9 from "node:path";
+async function init(ctx) {
+  const target = resolveTarget(ctx);
+  const existing = findExistingHome({ cwd: target, env: {} });
+  if (existing && !ctx.flags.here) {
+    report("chamba workspace already exists", existing);
+    return 0;
+  }
+  if (existing && ctx.flags.here) {
+    note(`note: shadowing an existing workspace at ${existing}`);
+  }
+  await ensureChambaHome(path9.join(target, ".chamba"));
+  const home = findExistingHome({ cwd: target, env: {} }) ?? path9.join(target, ".chamba");
+  report("created chamba workspace", home);
+  if (path9.basename(home) !== ".chamba") {
+    note("warning: home is not a .chamba directory, so it will not be auto-gitignored");
+  }
+  return 0;
+}
+function resolveTarget(ctx) {
+  const explicit = ctx.positionals[0];
+  if (explicit) return path9.resolve(explicit);
+  const root = gitRoot(process.cwd());
+  if (root) return root;
+  if (ctx.flags.here) return path9.resolve(process.cwd());
+  throw new UsageError(
+    "no .git found here - pass a directory (`chamba init <dir>`) or `chamba init --here` to choose where .chamba lives"
+  );
+}
+function report(headline, home) {
+  note(headline);
+  note(`home: ${home}  port: ${derivePort(home)}`);
+  note("each project gets its own server on its own port; other projects are unaffected");
+}
+
+// packages/cli/src/launch.ts
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync as existsSync5 } from "node:fs";
+import { createRequire } from "node:module";
+import path10 from "node:path";
+import { fileURLToPath as fileURLToPath4, pathToFileURL } from "node:url";
+var require2 = createRequire(import.meta.url);
+async function ensureServer(client, target) {
+  if (await client.isUp()) {
+    await verifyHome(client, target);
+    return { spawned: false };
+  }
+  ensureDevBuilds();
+  spawnServer(target);
+  await waitUntilUp(client, target);
+  return { spawned: true };
+}
+async function verifyHome(client, target) {
+  const health = await client.health();
+  if (health.home === target.home) return;
+  if (health.home === void 0) {
+    throw new Error(
+      `a chamba server already owns port ${target.port} but predates workspace isolation - stop that process and retry`
+    );
+  }
+  throw new Error(
+    `port ${target.port} is serving a different chamba workspace (${health.home}); run from that project, or set --port / CHAMBA_PORT to run a separate server`
+  );
+}
+function spawnServer(target) {
+  const child = spawn(process.execPath, serverLaunchArgs(), {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, CHAMBA_DIR: target.home, CHAMBA_PORT: String(target.port) }
+  });
+  child.unref();
+}
+function serverLaunchArgs() {
+  const here = path10.dirname(fileURLToPath4(import.meta.url));
+  const packagedServer = path10.join(here, "server.js");
+  if (existsSync5(packagedServer)) return [packagedServer];
+  const serverBin = require2.resolve("@chamba/server/bin");
+  const tsxLoader = pathToFileURL(require2.resolve("tsx")).href;
+  return ["--import", tsxLoader, serverBin];
+}
+function ensureDevBuilds() {
+  const here = path10.dirname(fileURLToPath4(import.meta.url));
+  if (existsSync5(path10.join(here, "server.js"))) return;
+  const repoRoot = path10.resolve(path10.dirname(require2.resolve("@chamba/server/bin")), "../../..");
+  const deps = [
+    { label: "web UI", filter: "@chamba/web", dist: resolveWebDist(), marker: "index.html" },
+    {
+      label: "annotation client",
+      filter: "@chamba/inject",
+      dist: resolveInjectDist(),
+      marker: "annotate.js"
+    }
+  ];
+  for (const dep of deps) {
+    if (existsSync5(path10.join(dep.dist, dep.marker))) continue;
+    note(`building chamba ${dep.label} (first run in this environment)...`);
+    const result = spawnSync("pnpm", ["--filter", dep.filter, "build"], {
+      cwd: repoRoot,
+      encoding: "utf8"
+    });
+    if (result.error || result.status !== 0) {
+      const detail = `${result.stderr ?? ""}${result.stdout ?? ""}`.trim();
+      throw new Error(
+        `could not build ${dep.filter} (needed to serve the ${dep.label})${detail ? `:
+${detail}` : ""}`
+      );
+    }
+  }
+}
+async function waitUntilUp(client, target, timeoutMs = 1e4) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await client.isUp()) {
+      const health = await client.health();
+      if (health.home === target.home) return;
+      throw new Error(
+        `port ${target.port} was taken by a different chamba workspace (${health.home ?? "unknown"})`
+      );
+    }
+    await delay(150);
+  }
+  throw new Error("server did not become healthy in time");
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// packages/cli/src/commands/open.ts
+async function open2(ctx) {
+  if (!ctx.workspaceExists) {
+    if (!gitRoot(process.cwd())) {
+      throw new UsageError(
+        "no chamba workspace, and no .git here to anchor one - run `chamba init <dir>` or `chamba init --here` to choose where .chamba lives"
+      );
+    }
+    await ensureChambaHome(ctx.home);
+    note(`created chamba workspace at ${ctx.home}`);
+  }
+  note(`home: ${ctx.home}  port: ${ctx.port}`);
+  const { spawned } = await ensureServer(ctx.client, { home: ctx.home, port: ctx.port });
+  if (spawned) note(`started chamba server on :${ctx.port}`);
+  const req = {
+    ...ctx.flags.kind ? { kind: parseKind(ctx.flags.kind) } : {},
+    ...ctx.flags.title ? { title: ctx.flags.title } : {}
+  };
+  const summary = await ctx.client.create(req);
+  const id = summary.meta.id;
+  const digest = await ctx.client.attach(id, 0);
+  const state = await readState(ctx.home);
+  await writeState(withSession(state, id, digest.cursor), ctx.home);
+  out(`http://localhost:${ctx.port}/?s=${id}`);
+  note("  in a container? if this link is unreachable from your host:");
+  note(
+    `  - the server bound ${resolveBindHost([])}; set CHAMBA_HOST=0.0.0.0 so the host can reach it`
+  );
+  note(`  - forward port ${ctx.port} to the host (1:1); pin it with CHAMBA_PORT to keep it stable`);
+  note(`session ${id} - open the URL, then run \`chamba poll\` to wait for messages`);
+  if (!ctx.flags.kind) {
+    note(
+      "  no --kind given: the human picks spec or everyday in the browser; your next poll reports it as `\xB7 Session set to ...`"
+    );
+  }
+  return 0;
+}
+function parseKind(value) {
+  const parsed = sessionKindSchema.safeParse(value);
+  if (!parsed.success) throw new UsageError(`invalid --kind: ${value} (expected everyday or spec)`);
+  return parsed.data;
+}
+
+// packages/cli/src/commands/poll.ts
+var DEFAULT_WAIT_MS = 25e3;
+var MAX_WAIT_MS = 3e4;
+var DEFAULT_FOLLOW_MS = 4 * 6e4;
+var BACKOFF_START_MS = 500;
+var BACKOFF_MAX_MS = 5e3;
+var IDLE_GUARD_MS = 1e3;
+var realClock = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+async function poll(ctx, clock = realClock) {
+  const id = await resolveSessionId(ctx);
+  const wait = Math.min(intFlag(ctx.flags.wait, DEFAULT_WAIT_MS), MAX_WAIT_MS);
+  if (ctx.flags.once !== void 0) return pollOnce(ctx, id, wait);
+  const followMs = intFlag(ctx.flags.for, DEFAULT_FOLLOW_MS);
+  return follow(
+    {
+      now: clock.now,
+      sleep: clock.sleep,
+      cursor: async () => cursorFor(await readState(ctx.home), id),
+      poll: (since) => ctx.client.poll(id, since, wait),
+      deliver: async (res) => {
+        printEvents(res.events, ctx.home);
+        await writeState(withSession(await readState(ctx.home), id, res.cursor), ctx.home);
+      },
+      onError: (err, giveUp) => note(pollErrorMessage(err, giveUp)),
+      onHeartbeat: () => note("still listening - re-run chamba poll to keep waiting"),
+      onEnded: () => note("session has ended - nothing more to wait for"),
+      isFatal
+    },
+    // The park floor never drops below the guard sleep, so a small (or zero) `--wait`
+    // - which makes the server answer empty at once - cannot spin the loop hot.
+    {
+      deadline: clock.now() + followMs,
+      parkFloorMs: Math.max(IDLE_GUARD_MS, Math.floor(wait / 2))
+    }
+  );
+}
+async function pollOnce(ctx, id, wait) {
+  const state = await readState(ctx.home);
+  const since = cursorFor(state, id);
+  const res = await ctx.client.poll(id, since, wait);
+  if (res.events.length === 0) {
+    note("(no new messages)");
+    return 0;
+  }
+  printEvents(res.events, ctx.home);
+  await writeState(withSession(state, id, res.cursor), ctx.home);
+  return 0;
+}
+async function follow(io, cfg) {
+  let backoff = BACKOFF_START_MS;
+  while (true) {
+    const since = await io.cursor();
+    const start = io.now();
+    let res;
+    try {
+      res = await io.poll(since);
+    } catch (err) {
+      const giveUp = io.isFatal(err) || io.now() >= cfg.deadline;
+      io.onError(err, giveUp);
+      if (giveUp) return 1;
+      await io.sleep(backoff);
+      backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+      continue;
+    }
+    backoff = BACKOFF_START_MS;
+    if (res.events.length > 0) {
+      await io.deliver(res);
+      return 0;
+    }
+    if (res.ended) {
+      io.onEnded?.();
+      return 0;
+    }
+    if (io.now() >= cfg.deadline) {
+      io.onHeartbeat();
+      return 0;
+    }
+    if (io.now() - start < cfg.parkFloorMs) await io.sleep(IDLE_GUARD_MS);
+  }
+}
+function isFatal(err) {
+  if (err instanceof ChannelError) return err.status === 404;
+  if (err instanceof SyntaxError) return true;
+  return err instanceof Error && err.name === "ZodError";
+}
+function pollErrorMessage(err, giveUp) {
+  if (err instanceof ChannelError && err.status === 404) {
+    return "session not found - it may have been removed";
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  return giveUp ? `poll failed: ${detail}` : `poll failed, retrying: ${detail}`;
+}
+
+// packages/cli/src/commands/reply.ts
+import { stat } from "node:fs/promises";
+async function reply(ctx) {
+  const text = ctx.positionals.join(" ").trim();
+  const files = filePaths(ctx.flags);
+  if (!text && files.length === 0) {
+    throw new UsageError("usage: chamba reply <text> [--file a,b] [--image a,b]");
+  }
+  const id = await resolveSessionId(ctx);
+  for (const file of files) {
+    try {
+      const info = await stat(file);
+      if (!info.isFile()) throw new UsageError(`not a file: ${file}`);
+    } catch (err) {
+      if (err instanceof UsageError) throw err;
+      throw new UsageError(`file not found: ${file}`);
+    }
+  }
+  const attachmentIds = [];
+  for (const file of files) {
+    const attachment = await ctx.client.uploadAttachment(id, file);
+    attachmentIds.push(attachment.id);
+    note(`uploaded ${attachment.name}`);
+  }
+  await ctx.client.reply(id, {
+    ...text ? { text } : {},
+    ...attachmentIds.length > 0 ? { attachmentIds } : {}
+  });
+  note(`sent to ${id}`);
+  return 0;
+}
+function filePaths(flags) {
+  return [flags.file, flags.image].filter((value) => typeof value === "string" && value !== "true").flatMap((value) => value.split(",")).map((value) => value.trim()).filter((value) => value.length > 0);
+}
+
+// packages/cli/src/commands/skill.ts
+import { cpSync, existsSync as existsSync6, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import path11 from "node:path";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
+async function skill(ctx) {
+  if (ctx.positionals[0] !== "install") {
+    throw new UsageError("usage: chamba skill install [--global]");
+  }
+  const source = resolveSkillSource();
+  if (!source) {
+    note("bundled skill not found");
+    return 1;
+  }
+  const base = ctx.flags.global ? homedir() : process.cwd();
+  const target = path11.join(base, ".claude", "skills", "chamba");
+  rmSync(target, { recursive: true, force: true });
+  cpSync(source, target, { recursive: true });
+  note(`installed the chamba skill to ${target}`);
+  note("reload your agent's skills, then use /chamba");
+  return 0;
+}
+function resolveSkillSource() {
+  const here = path11.dirname(fileURLToPath5(import.meta.url));
+  const candidates = [
+    path11.resolve(here, "../skill"),
+    // packaged: dist/cli.js -> <pkg>/skill
+    path11.resolve(here, "../../../../skill")
+    // dev: packages/cli/src/commands -> <repo>/skill
+  ];
+  return candidates.find((dir) => existsSync6(path11.join(dir, "SKILL.md"))) ?? null;
+}
+
+// packages/cli/src/commands/status.ts
+async function status(ctx) {
+  if (!ctx.workspaceExists) {
+    note(
+      "no chamba workspace here - run `chamba open` to start one (creates .chamba at the repo root), or `chamba init` to choose where"
+    );
+    return 0;
+  }
+  const state = await readState(ctx.home);
+  const up = await serverOwnsHome(ctx);
+  const rows = up ? await rowsFromServer(ctx) : await rowsFromDisk(ctx);
+  note(`home: ${ctx.home}`);
+  if (rows.length === 0) {
+    note("no sessions yet - run `chamba open` to start one");
+    return 0;
+  }
+  note(up ? `chamba server up on :${ctx.port}` : "chamba server not running (disk state)");
+  for (const row of rows) {
+    out(formatSession(row.meta, row.presence, row.meta.id === state.currentSessionId));
+  }
+  return 0;
+}
+async function serverOwnsHome(ctx) {
+  if (!await ctx.client.isUp()) return false;
+  try {
+    return (await ctx.client.health()).home === ctx.home;
+  } catch {
+    return false;
+  }
+}
+async function rowsFromServer(ctx) {
+  const summaries = await ctx.client.list();
+  return summaries.map((s) => ({ meta: s.meta, presence: s.presence }));
+}
+async function rowsFromDisk(ctx) {
+  const ids = await listSessionIds(ctx.home);
+  const metas = await Promise.all(ids.map((id) => readMeta(ctx.home, id)));
+  return metas.filter((meta) => meta !== null).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).map((meta) => ({ meta }));
+}
+
+// packages/cli/src/commands/stop.ts
+async function stop(ctx) {
+  const info = await readServerInfo(ctx.home);
+  if (!info) {
+    note("no chamba server running here");
+    return 0;
+  }
+  const client = new Client(`http://127.0.0.1:${info.port}/`);
+  if (!await ownsHome(client, ctx.home)) {
+    note("no chamba server running here");
+    return 0;
+  }
+  try {
+    process.kill(info.pid, "SIGTERM");
+  } catch {
+    note("no chamba server running here");
+    return 0;
+  }
+  if (await waitUntilDown(client)) {
+    note(`stopped chamba server on :${info.port}`);
+    return 0;
+  }
+  note(`sent stop to the chamba server (pid ${info.pid}) but it did not exit in time`);
+  return 1;
+}
+async function ownsHome(client, home) {
+  if (!await client.isUp()) return false;
+  try {
+    return (await client.health()).home === home;
+  } catch {
+    return false;
+  }
+}
+async function waitUntilDown(client, timeoutMs = 5e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await client.isUp()) return true;
+    await delay2(150);
+  }
+  return false;
+}
+function delay2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// packages/cli/src/commands/index.ts
+var COMMANDS = {
+  init,
+  open: open2,
+  poll,
+  reply,
+  end,
+  attach,
+  status,
+  stop,
+  // Spec sessions: structured interview + live artifacts + export.
+  ask,
+  decision,
+  artifact,
+  export: exportCmd,
+  // Distribution: install the bundled skill into a Claude skills directory.
+  skill,
+  help,
+  "-h": help
+};
+function runCommand(name, ctx) {
+  const handler = COMMANDS[name];
+  if (!handler) {
+    note(`unknown command: ${name}`);
+    return help(ctx).then(() => 2);
+  }
+  return handler(ctx);
+}
+
+// packages/cli/src/index.ts
+var REQUIRES_WORKSPACE = /* @__PURE__ */ new Set([
+  "poll",
+  "reply",
+  "end",
+  "attach",
+  "ask",
+  "decision",
+  "artifact",
+  "export"
+]);
+async function main(argv = process.argv.slice(2)) {
+  const { positionals, flags } = parseArgs(argv);
+  if (flags.version && positionals.length === 0) {
+    out(chambaVersion());
+    return 0;
+  }
+  const command = positionals[0] ?? (flags.help ? "help" : "status");
+  const existing = findExistingHome();
+  const home = existing ?? plannedHome();
+  const port = resolvePort(argv, home);
+  const ctx = {
+    client: new Client(`http://127.0.0.1:${port}/`),
+    home,
+    port,
+    flags,
+    positionals: positionals.slice(1),
+    workspaceExists: existing !== null
+  };
+  if (!ctx.workspaceExists && REQUIRES_WORKSPACE.has(command)) {
+    note(
+      "no chamba workspace here - run `chamba open` to start one (creates .chamba at the repo root), or `chamba init` to choose where"
+    );
+    return 2;
+  }
+  try {
+    return await runCommand(command, ctx);
+  } catch (err) {
+    return reportError(err);
+  }
+}
+function reportError(err) {
+  if (err instanceof UsageError) {
+    note(err.message);
+    return 2;
+  }
+  if (err instanceof ChannelError) {
+    note(`error: ${err.message}`);
+    return 1;
+  }
+  if (errorCode(err) === "ECONNREFUSED") {
+    note("cannot reach the chamba server - run `chamba open` first");
+    return 1;
+  }
+  note(`error: ${err.message}`);
+  return 1;
+}
+function errorCode(err) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [err];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || typeof current !== "object" || seen.has(current)) continue;
+    seen.add(current);
+    const code = current.code;
+    if (typeof code === "string") return code;
+    const cause = current.cause;
+    if (cause) queue.push(cause);
+    const errors = current.errors;
+    if (Array.isArray(errors)) queue.push(...errors);
+  }
+  return void 0;
+}
+function invokedAsEntry() {
+  const entry = process.argv[1];
+  if (entry === void 0) return false;
+  try {
+    return realpathSync2(entry) === realpathSync2(fileURLToPath6(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (invokedAsEntry()) {
+  main().then(
+    (code) => process.exit(code),
+    (err) => {
+      note(`fatal: ${err.message}`);
+      process.exit(1);
+    }
+  );
+}
+export {
+  main
+};