chamba 0.0.1 → 0.1.0

package/dist/cli.js

@@ -0,0 +1,1190 @@
+#!/usr/bin/env node
+
+// packages/cli/src/index.ts
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+
+// packages/server/src/index.ts
+import { serve as honoServe } from "@hono/node-server";
+
+// packages/shared/src/annotations.ts
+import { z as z2 } from "zod";
+
+// packages/shared/src/messages.ts
+import { z } from "zod";
+var attachmentSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  relPath: z.string().min(1),
+  contentType: z.string().min(1),
+  size: z.number().int().nonnegative()
+});
+var messagePayloadSchema = z.object({
+  text: z.string().min(1).optional(),
+  attachments: z.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 = z.enum(["session-created", "user-moved-away", "session-ended"]);
+var systemPayloadSchema = z.object({
+  reason: systemReasonSchema,
+  to: z.string().min(1).optional()
+});
+
+// packages/shared/src/annotations.ts
+var ANNOTATION_BATCH = "annotation-batch";
+var annotationSourceSchema = z2.object({
+  file: z2.string().min(1),
+  line: z2.number().int().positive().optional(),
+  column: z2.number().int().positive().optional()
+});
+var annotationComponentSchema = z2.object({
+  name: z2.string().min(1),
+  source: annotationSourceSchema.optional()
+});
+var annotationTargetSchema = z2.object({
+  selector: z2.string().min(1),
+  pageUrl: z2.string().min(1),
+  viewport: z2.object({
+    width: z2.number().int().positive(),
+    height: z2.number().int().positive()
+  }),
+  label: z2.string().optional(),
+  component: annotationComponentSchema.optional()
+});
+var annotationItemSchema = z2.object({
+  note: z2.string().min(1).optional(),
+  target: annotationTargetSchema,
+  screenshot: attachmentSchema.optional()
+});
+var annotationBatchPayloadSchema = z2.object({
+  items: z2.array(annotationItemSchema).min(1)
+});
+
+// packages/shared/src/api.ts
+import { z as z7 } from "zod";
+
+// packages/shared/src/events.ts
+import { z as z3 } from "zod";
+var eventSourceSchema = z3.enum(["user", "agent", "system"]);
+var eventEnvelopeSchema = z3.object({
+  id: z3.string().uuid(),
+  seq: z3.number().int().nonnegative(),
+  sessionId: z3.string().min(1),
+  ts: z3.string().datetime(),
+  type: z3.string().min(1),
+  source: eventSourceSchema,
+  payload: z3.unknown()
+});
+
+// packages/shared/src/presence.ts
+import { z as z4 } from "zod";
+var presenceSchema = z4.enum(["listening", "away"]);
+
+// packages/shared/src/session.ts
+import { z as z5 } from "zod";
+var sessionKindSchema = z5.enum(["everyday", "spec"]);
+var sessionStatusSchema = z5.enum(["active", "ended"]);
+var sessionMetaSchema = z5.object({
+  id: z5.string().min(1),
+  kind: sessionKindSchema,
+  title: z5.string().optional(),
+  status: sessionStatusSchema,
+  createdAt: z5.string().datetime(),
+  updatedAt: z5.string().datetime()
+});
+
+// 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 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
+});
+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
+});
+
+// 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("ended"),
+    meta: sessionMetaSchema
+  })
+]);
+
+// packages/server/src/app.ts
+import { createNodeWebSocket } from "@hono/node-ws";
+import { Hono } from "hono";
+
+// packages/server/src/render.ts
+import { marked } from "marked";
+
+// packages/server/src/sessions/paths.ts
+import path from "node:path";
+function resolveHome() {
+  const override = process.env.CHAMBA_DIR;
+  return override && override.length > 0 ? path.resolve(override) : path.join(process.cwd(), ".chamba");
+}
+function sessionsDir(home) {
+  return path.join(home, "sessions");
+}
+function sessionDir(home, id) {
+  return path.join(sessionsDir(home), id);
+}
+function metaPath(home, id) {
+  return path.join(sessionDir(home, id), "meta.json");
+}
+function agentStatePath(home) {
+  return path.join(home, "agent-state.json");
+}
+
+// packages/server/src/port.ts
+var DEFAULT_PORT = 4319;
+function resolvePort(argv = process.argv.slice(2)) {
+  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 DEFAULT_PORT;
+}
+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 < 0 || port > 65535) {
+    throw new Error(`invalid ${source}: ${value}`);
+  }
+  return port;
+}
+
+// packages/server/src/version.ts
+import { existsSync, readFileSync } from "node:fs";
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+function chambaVersion() {
+  let dir = path2.dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    const manifest = path2.join(dir, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const { version } = JSON.parse(readFileSync(manifest, "utf8"));
+        if (typeof version === "string" && version) return version;
+      } catch {
+      }
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) return "0.0.0-dev";
+    dir = parent;
+  }
+}
+
+// packages/server/src/sessions/meta.ts
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+async function readMeta(home, id) {
+  try {
+    const raw = await readFile(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 readFile2 } from "node:fs/promises";
+import path3 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 readFile2(filePath);
+    const form = new FormData();
+    form.append("file", new Blob([bytes]), path3.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(path9, options, schema) {
+    const res = await this.fetch(path9, options);
+    if (!res.ok) throw await toError(res);
+    return schema.parse(await res.json());
+  }
+  async fetch(path9, 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(path9, 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 path4 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 formatEvent(event) {
+  if (event.source === "system") return `\xB7 ${eventText(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 = path4.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 = path4.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} -> ${path4.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}${title}`;
+}
+
+// packages/cli/src/commands/artifact.ts
+import { readFile as readFile4 } from "node:fs/promises";
+
+// packages/cli/src/state.ts
+import { mkdir, readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
+import path5 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 readFile3(agentStatePath(home), "utf8");
+    return agentStateSchema.parse(JSON.parse(raw));
+  } catch {
+    return { cursors: {} };
+  }
+}
+async function writeState(state, home = resolveHome()) {
+  const file = agentStatePath(home);
+  await mkdir(path5.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  await writeFile2(tmp, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+  await rename2(tmp, file);
+}
+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) {
+  if (ctx.flags.session) return ctx.flags.session;
+  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 readFile4(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 } from "node:crypto";
+import { readFile as readFile5 } 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 = randomUUID();
+  }
+  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 readFile5(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 id = ctx.positionals[0] ?? ctx.flags.session;
+  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 mkdir2, readFile as readFile6, writeFile as writeFile3 } from "node:fs/promises";
+import path6 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: path6.resolve(dest)
+  });
+  note(
+    `exported ${id} -> ${path6.resolve(dest)} (spec.md${summary.hasDraft ? "" : " placeholder"}, ${summary.assets.length} asset${summary.assets.length === 1 ? "" : "s"}, ${summary.decisions} decision${summary.decisions === 1 ? "" : "s"})`
+  );
+  out(path6.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 mkdir2(input.dest, { recursive: true });
+  const assetsDir = path6.join(input.dest, "assets");
+  const draftBody = canonicalDraft ? await readArtifact(input.sessionDir, canonicalDraft) : void 0;
+  await writeFile3(
+    path6.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 = path6.join(input.sessionDir, ref.relPath);
+    const base = path6.basename(ref.relPath);
+    try {
+      await mkdir2(assetsDir, { recursive: true });
+      await copyFile(src, path6.join(assetsDir, base));
+      assets.push(base);
+    } catch {
+    }
+  }
+  await writeFile3(path6.join(input.dest, "decisions.md"), renderDecisions(decisions), "utf8");
+  return { hasDraft: Boolean(draftBody), assets, decisions: decisions.length };
+}
+async function readArtifact(dir, ref) {
+  try {
+    return await readFile6(path6.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 open [--kind K]     start a session (K: everyday | spec), print its URL
+             [--title T]
+  chamba poll [--wait ms]    block for the next human/system events; a batch may
+                             include "user moved away" (hand off with attach) or
+                             "session ended" (stop polling, resume terminal work)
+  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
+
+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
+                             minted 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 or 4319)`;
+function help(_ctx) {
+  note(USAGE);
+  return Promise.resolve(0);
+}
+
+// packages/cli/src/launch.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { createRequire } from "node:module";
+import path7 from "node:path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+var require2 = createRequire(import.meta.url);
+async function ensureServer(client) {
+  if (await client.isUp()) return { spawned: false };
+  spawnServer();
+  await waitUntilUp(client);
+  return { spawned: true };
+}
+function spawnServer() {
+  const child = spawn(process.execPath, serverLaunchArgs(), {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+}
+function serverLaunchArgs() {
+  const here = path7.dirname(fileURLToPath2(import.meta.url));
+  const packagedServer = path7.join(here, "server.js");
+  if (existsSync2(packagedServer)) return [packagedServer];
+  const serverBin = require2.resolve("@chamba/server/bin");
+  const tsxLoader = pathToFileURL(require2.resolve("tsx")).href;
+  return ["--import", tsxLoader, serverBin];
+}
+async function waitUntilUp(client, timeoutMs = 1e4) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await client.isUp()) return;
+    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 open(ctx) {
+  const { spawned } = await ensureServer(ctx.client);
+  if (spawned) note("started chamba server");
+  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(`session ${id} - open the URL, then run \`chamba poll\` to wait for messages`);
+  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
+async function poll(ctx) {
+  const id = await resolveSessionId(ctx);
+  const wait = Math.min(intFlag(ctx.flags.wait, 25e3), 3e4);
+  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;
+}
+
+// packages/cli/src/commands/reply.ts
+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);
+  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 existsSync3 } from "node:fs";
+import { homedir } from "node:os";
+import path8 from "node:path";
+import { fileURLToPath as fileURLToPath3 } 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 = path8.join(base, ".claude", "skills", "chamba");
+  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 = path8.dirname(fileURLToPath3(import.meta.url));
+  const candidates = [
+    path8.resolve(here, "../skill"),
+    // packaged: dist/cli.js -> <pkg>/skill
+    path8.resolve(here, "../../../../skill")
+    // dev: packages/cli/src/commands -> <repo>/skill
+  ];
+  return candidates.find((dir) => existsSync3(path8.join(dir, "SKILL.md"))) ?? null;
+}
+
+// packages/cli/src/commands/status.ts
+async function status(ctx) {
+  const state = await readState(ctx.home);
+  const up = await ctx.client.isUp();
+  const rows = up ? await rowsFromServer(ctx) : await rowsFromDisk(ctx);
+  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 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/index.ts
+var COMMANDS = {
+  open,
+  poll,
+  reply,
+  end,
+  attach,
+  status,
+  // 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
+async function main(argv = process.argv.slice(2)) {
+  const port = resolvePort(argv);
+  const { positionals, flags } = parseArgs(argv);
+  if (flags.version && positionals.length === 0) {
+    out(chambaVersion());
+    return 0;
+  }
+  const command = positionals[0] ?? (flags.help ? "help" : "status");
+  const ctx = {
+    client: new Client(`http://127.0.0.1:${port}/`),
+    home: resolveHome(),
+    port,
+    flags,
+    positionals: positionals.slice(1)
+  };
+  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;
+  }
+  const cause = err.cause;
+  if (cause?.code === "ECONNREFUSED") {
+    note("cannot reach the chamba server - run `chamba open` first");
+    return 1;
+  }
+  note(`error: ${err.message}`);
+  return 1;
+}
+var invokedDirectly = process.argv[1] !== void 0 && pathToFileURL2(process.argv[1]).href === import.meta.url;
+if (invokedDirectly) {
+  main().then(
+    (code) => process.exit(code),
+    (err) => {
+      note(`fatal: ${err.message}`);
+      process.exit(1);
+    }
+  );
+}
+export {
+  main
+};