@home-v0/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @home-v0/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a house in 3D in [home-v0](https://home-v0.com) from a folder of photos and floor plans, by hand or with an AI agent (Claude Code, Codex, Cursor…). An agent in home-v0 builds the model; the CLI uploads the house, follows the build, and saves the agent's chat, renders and 3D model next to your files.
+
+```sh
+npx @home-v0/cli login --token hv0_…                                  # API key from home-v0 → API keys
+npx @home-v0/cli init our-house --name "Our house" --place "Vrbnje 53, Radovljica"
+# put outside photos (Street View screenshots work) in our-house/photos, plans in our-house/drawings
+npx @home-v0/cli build our-house                                      # 10 to 40 minutes; results in our-house/runs/<time>/
+npx @home-v0/cli say our-house -m "The roof is steeper: the section shows 45 degrees"
+```
+
+| Command                                 | What it does                                                         |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| `login [--token]`, `logout`             | Save or forget an API key (or set `HOME_V0_API_KEY`)                 |
+| `init [dir] --name … --place …`          | Start a house folder: `house.json`, `photos/`, `drawings/`           |
+| `houses [dir]`                          | List the house folders below a folder                                |
+| `build [house]`                         | Make the house in home-v0, upload its files and follow the build     |
+| `say [house] -m …`                      | Tell the agent what to change and follow its answer                  |
+| `follow`, `pull`, `stop` `[house]`      | Keep following, save the latest files once, or stop the agent's turn |
+| `guide [--agents-md]`                   | The folder format, the workflow and how to review a build            |
+
+A house is a folder with a `house.json`, the current folder by default.
+
+## With an AI agent
+
+Tell your agent to run `npx @home-v0/cli guide` first: it explains the folder, the commands, how to review a build against the photos and drawings, and what each build costs. To make it stick, add the output of `npx @home-v0/cli guide --agents-md` to your project's `AGENTS.md` or `CLAUDE.md`, and give the agent your key as `HOME_V0_API_KEY`.
+
+Exit codes: 0 done, 1 the build failed or is waiting on a key or limit, 2 a mistake in the command, 3 not signed in or the key was refused, 4 a mistake in the house folder.
+
+## Developing
+
+From the repo root: `npm run home -- <command>` runs the source against `--api-url http://localhost:3000` or any home-v0. A local API needs no key: the CLI makes its own account there. `npm run build -w @home-v0/cli` bundles `dist/home-v0.js`, which is what gets published. To release, bump the version here, then `npm publish` from this folder.

package/dist/home-v0.js

@@ -0,0 +1,754 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { access, readdir as readdir3, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join4, relative as relative2 } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+
+// src/api.ts
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+var CONTENT_TYPES = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".heic": "image/heic",
+  ".heif": "image/heif",
+  ".pdf": "application/pdf"
+};
+var ApiError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+};
+var HomeApi = class {
+  baseUrl;
+  auth;
+  cookies = /* @__PURE__ */ new Map();
+  constructor(baseUrl, auth) {
+    this.baseUrl = baseUrl;
+    this.auth = auth;
+  }
+  async signIn() {
+    if ("apiKey" in this.auth) return;
+    const { email, password } = this.auth.devAccount;
+    try {
+      await this.request("POST", "auth/login", { json: { email, password }, retry: false });
+    } catch (error) {
+      if (!(error instanceof ApiError) || ![401, 404].includes(error.status)) throw error;
+      await this.request("POST", "auth/register", { json: { name: "home-v0 CLI", email, password }, retry: false });
+    }
+  }
+  /** Fails with 401 if the API doesn't know the key. */
+  async checkKey() {
+    await this.request("GET", "projects");
+  }
+  searchPlaces(query) {
+    return this.request("GET", `places/search?${new URLSearchParams({ q: query })}`);
+  }
+  createProject(name, place) {
+    return this.request("POST", "projects", { json: { name, kind: "house", place } });
+  }
+  deleteProject(id) {
+    return this.request("DELETE", `projects/${id}`);
+  }
+  spaces(projectId) {
+    return this.request("GET", `projects/${projectId}/spaces`);
+  }
+  space(id) {
+    return this.request("GET", `spaces/${id}`);
+  }
+  addPhotos(spaceId, files) {
+    return this.upload(`spaces/${spaceId}/photos`, "photos", files);
+  }
+  addDrawings(spaceId, files) {
+    return this.upload(`spaces/${spaceId}/drawings`, "files", files);
+  }
+  capture(spaceId) {
+    return this.request("POST", `spaces/${spaceId}/capture`);
+  }
+  conversation(spaceId) {
+    return this.request("GET", `spaces/${spaceId}/agent`);
+  }
+  send(sessionId, text) {
+    return this.request("POST", `agent-sessions/${sessionId}/messages`, { json: { text } });
+  }
+  stop(sessionId) {
+    return this.request("POST", `agent-sessions/${sessionId}/stop`);
+  }
+  /** A render or model the agent made. Media on the API's own host gets the credentials too. */
+  async download(url) {
+    const sameHost = new URL(url).host === new URL(this.baseUrl).host;
+    const response = await fetch(url, { headers: sameHost ? this.headers() : {} });
+    if (!response.ok) throw new ApiError(response.status, `Downloading ${url} failed with ${response.status}`);
+    return { body: new Uint8Array(await response.arrayBuffer()), contentType: response.headers.get("content-type") };
+  }
+  async upload(path, field, files) {
+    const form = new FormData();
+    for (const file of files) {
+      const type = CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+      form.append(field, new Blob([await readFile(file)], { type }), basename(file));
+    }
+    return this.request("POST", path, { form });
+  }
+  async request(method, path, options = {}) {
+    const headers = this.headers();
+    let body = options.form;
+    if (options.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.json);
+    }
+    const response = await fetch(new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`), {
+      method,
+      headers,
+      body
+    });
+    this.keepCookies(response);
+    if (response.status === 401 && "devAccount" in this.auth && options.retry !== false) {
+      await this.signIn();
+      return this.request(method, path, { ...options, retry: false });
+    }
+    if (!response.ok) throw new ApiError(response.status, await errorMessage(method, path, response));
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+  headers() {
+    if ("apiKey" in this.auth) return { Authorization: `Bearer ${this.auth.apiKey}` };
+    const cookie = [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; ");
+    return { "X-Requested-With": "XMLHttpRequest", ...cookie ? { Cookie: cookie } : {} };
+  }
+  keepCookies(response) {
+    for (const header of response.headers.getSetCookie()) {
+      const [pair] = header.split(";");
+      const at = pair.indexOf("=");
+      if (at > 0) this.cookies.set(pair.slice(0, at).trim(), pair.slice(at + 1).trim());
+    }
+  }
+};
+async function errorMessage(method, path, response) {
+  const text = await response.text();
+  let message = text;
+  try {
+    const json = JSON.parse(text);
+    if (json.message) message = Array.isArray(json.message) ? json.message.join("; ") : String(json.message);
+  } catch {
+  }
+  return `${method} /${path.split("?")[0]} failed with ${response.status}: ${message.slice(0, 500)}`;
+}
+
+// src/config.ts
+import { chmod, mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_API_URL = "https://api.home-v0.com";
+var configPath = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "home-v0", "config.json");
+var readSavedConfig = async () => {
+  try {
+    return JSON.parse(await readFile2(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+};
+var saveConfig = async (config) => {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+  await chmod(path, 384);
+  return path;
+};
+var clearConfig = async () => rm(configPath(), { force: true });
+var resolveConnection = async (flags) => {
+  const saved = await readSavedConfig();
+  return {
+    apiUrl: (flags.apiUrl || process.env.HOME_V0_API_URL || saved.apiUrl || DEFAULT_API_URL).replace(/\/$/, ""),
+    token: flags.token || process.env.HOME_V0_API_KEY || saved.token || ""
+  };
+};
+var isLocal = (url) => ["localhost", "127.0.0.1"].includes(new URL(url).hostname);
+var webUrlFor = (apiUrl) => {
+  const url = new URL(apiUrl);
+  if (isLocal(apiUrl)) return `${url.protocol}//${url.hostname}:5173`;
+  return `${url.protocol}//${url.host.replace(/^api\./, "")}`;
+};
+
+// src/guide.ts
+var guide = () => `# Building a house in home-v0 with the CLI
+
+home-v0 turns a house's photos and floor plans into a 3D model built by an AI agent, and suggests what the house
+could become. The \`home-v0\` CLI does what you'd do in the app: it makes the house, uploads its photos and drawings,
+starts the build, and saves the agent's chat, renders and 3D model in the house's folder. You (a person or an AI
+agent) prepare a folder; the CLI does the rest.
+
+## Sign in
+
+Create an API key in home-v0 (sidebar \u2192 API keys). It acts as you, in the workspace you made it in. Then either:
+
+- \`home-v0 login --token hv0_\u2026\` saves it in ~/.config/home-v0/config.json, or
+- set \`HOME_V0_API_KEY\` for each run.
+
+A key can create houses and talk to the agent that builds them. It can't change your account or your team.
+
+## The house folder
+
+\`\`\`
+my-house/
+  house.json
+  photos/          outside photos, up to 8 (JPEG, PNG, WebP, AVIF or HEIC, 15 MB each)
+  drawings/        floor plans, elevations, sections (PDF or images, 30 MB each, 12 pages in all)
+  runs/            written by the CLI: one folder per build
+\`\`\`
+
+\`home-v0 init my-house --name "Our house" --place "Vrbnje 53, Radovljica"\` starts one.
+
+\`house.json\`:
+
+\`\`\`json
+{
+  "name": "Our house",
+  "place": "Vrbnje 53, Radovljica",
+  "notes": "Two floors and an attic, gable roof, built in 1978."
+}
+\`\`\`
+
+- \`name\`: what the house is called in the app.
+- \`place\`: an address, searched like the app's address field. An exact address gives the agent the building's
+  outline from the map (for its size) and the real sun. A town alone works, without the outline.
+- \`photos\`, \`drawings\` (optional): lists of files, relative to the folder, when you don't want every file in
+  \`photos/\` or \`drawings/\` (which are taken in name order).
+- \`notes\` (optional): what you know about the house. The CLI doesn't send it; it's for whoever reviews the build.
+
+Photos: the whole outside of the house from eye level, each side if you can. Street View screenshots work well.
+At least one photo is required: the app reads the house from its photos. Drawings are optional but make the model
+much closer: plans decide wall lengths, rooms and openings on sides the photos don't show, and each floor with a
+plan is built inside too.
+
+## Workflow
+
+1. \`home-v0 build my-house\` makes the house in home-v0, uploads everything and follows the build, printing the
+   agent's chat. A first build takes 10 to 40 minutes. The command ends when the agent's turn ends, and leaves
+   everything in \`my-house/runs/<time>/\`: \`chat.md\` (the conversation, renders inline), \`NNNN-render.*\` (pictures
+   the agent rendered), \`NNNN-model.glb\` (the 3D model), \`messages.json\` and \`run.json\` (with the house's link in
+   the app).
+2. Look at the renders next to the photos and drawings (see Review below).
+3. \`home-v0 say my-house -m "The roof is steeper: the section shows 45 degrees"\` tells the agent what's wrong and
+   follows its answer. Name what's wrong and where you see it, one or two things per message.
+4. \`home-v0 follow my-house\` keeps watching if a command timed out; \`home-v0 pull my-house\` saves the latest files
+   without waiting; \`home-v0 stop my-house\` stops the agent's current turn.
+
+Open the link in \`run.json\` to see the model in 3D, peel it floor by floor, and try new directions in the app.
+
+## Review
+
+Compare each render with the photos and drawings, element by element:
+
+- the number of floors, and the footprint's shape and size
+- the roof: type, pitch, overhangs, which way the ridge runs, dormers and chimneys
+- openings on each side: how many, where, and how big
+- materials and colours
+- inside each floor that has a plan: walls, doors, stairs and room names
+
+Say which render and which photo or drawing each point comes from, and how sure you are when a render's angle hides
+something. Fix the biggest differences first.
+
+## For AI agents
+
+- Each build spends from the workspace's budget and counts against its daily house limit. Build each house once,
+  then correct it with \`say\`; don't build the same house again to fix it.
+- Run \`build\`, \`say\` and \`follow\` in the background and wait for them to finish instead of polling: they print
+  as they go and exit when the agent's turn ends.
+- Exit codes: 0 done, 1 the build failed or is waiting on a key or the plan's limit (the output says which),
+  2 a mistake in the command, 3 not signed in or the key was refused, 4 a mistake in the house folder.
+- \`--timeout <minutes>\` (default 45) is how long to follow; \`--detach\` starts a build without following it.
+- \`--api-url\` or \`HOME_V0_API_URL\` points the CLI at another home-v0 (default https://api.home-v0.com).
+`;
+var agentsSnippet = () => `## home-v0 houses
+
+Folders with a \`house.json\` are houses for home-v0, which builds them in 3D with an AI agent. Use the
+\`home-v0\` CLI (\`npx @home-v0/cli\`):
+
+- Run \`npx @home-v0/cli guide\` once to learn the folder format, the workflow and how to review a build.
+- \`npx @home-v0/cli build <folder>\` builds a house (10 to 40 minutes; run it in the background). Results land in
+  \`<folder>/runs/<time>/\`.
+- Correct a build with \`npx @home-v0/cli say <folder> -m "\u2026"\` instead of building it again: each build costs money.
+- Authenticate with the \`HOME_V0_API_KEY\` environment variable (an API key from home-v0 \u2192 API keys).
+`;
+
+// src/houses.ts
+import { mkdir as mkdir2, readdir, readFile as readFile3, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { extname as extname2, join as join2, relative, resolve } from "node:path";
+var MAX_PHOTOS = 8;
+var MAX_DRAWING_FILES_PER_UPLOAD = 5;
+var MAX_PHOTO_MB = 15;
+var MAX_DRAWING_MB = 30;
+var PHOTO_TYPES = [".jpg", ".jpeg", ".png", ".webp", ".avif", ".heic", ".heif"];
+var DRAWING_TYPES = [...PHOTO_TYPES, ".pdf"];
+var SKIP = /* @__PURE__ */ new Set(["node_modules", "runs", "dist", "photos", "drawings"]);
+var HouseError = class extends Error {
+};
+function parseManifest(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { problems: ["it must be an object"] };
+  const value = raw;
+  const problems = [];
+  const text = (key, required) => {
+    const field = value[key];
+    if (field === void 0 && !required) return;
+    if (typeof field !== "string" || !field.trim())
+      problems.push(`${key}: ${required ? "is required" : "must be text"}`);
+  };
+  const files = (key) => {
+    const field = value[key];
+    if (field !== void 0 && (!Array.isArray(field) || field.some((f) => typeof f !== "string"))) {
+      problems.push(`${key}: must be a list of file paths`);
+    }
+  };
+  text("name", true);
+  text("place", true);
+  text("notes", false);
+  files("photos");
+  files("drawings");
+  if (problems.length) return { problems };
+  const manifest = value;
+  return { manifest: { ...manifest, name: manifest.name.trim(), place: manifest.place.trim() }, problems };
+}
+async function loadHouse(folder) {
+  const file = join2(folder, "house.json");
+  let raw;
+  try {
+    raw = JSON.parse(await readFile3(file, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new HouseError(
+        `${folder} has no house.json. Start one with: home-v0 init ${folder} --name "\u2026" --place "\u2026"`
+      );
+    }
+    throw new HouseError(`${file} isn't valid JSON: ${error.message}`);
+  }
+  const { manifest, problems } = parseManifest(raw);
+  if (!manifest) throw new HouseError(`${file} has mistakes:
+  ${problems.join("\n  ")}`);
+  const photos = manifest.photos?.map((p) => join2(folder, p)) ?? await filesIn(join2(folder, "photos"), PHOTO_TYPES);
+  const drawings = manifest.drawings?.map((d) => join2(folder, d)) ?? await filesIn(join2(folder, "drawings"), DRAWING_TYPES);
+  if (photos.length > MAX_PHOTOS) {
+    throw new HouseError(
+      `${file}: a house takes up to ${MAX_PHOTOS} photos, and it has ${photos.length}. List the best ones in "photos".`
+    );
+  }
+  await checkFiles(photos, PHOTO_TYPES, MAX_PHOTO_MB, "photo");
+  await checkFiles(drawings, DRAWING_TYPES, MAX_DRAWING_MB, "drawing");
+  return { folder, name: manifest.name, place: manifest.place, photos, drawings, notes: manifest.notes ?? null };
+}
+async function checkFiles(files, types, maxMb, what) {
+  for (const file of files) {
+    if (!types.includes(extname2(file).toLowerCase())) {
+      throw new HouseError(`${file}: a ${what} must be one of ${types.join(", ")}`);
+    }
+    const info = await stat(file).catch(() => null);
+    if (!info?.isFile()) throw new HouseError(`${file} doesn't exist`);
+    if (info.size > maxMb * 1024 * 1024) throw new HouseError(`${file} is over ${maxMb} MB`);
+  }
+}
+async function filesIn(folder, types) {
+  const names = await readdir(folder).catch(() => []);
+  return names.filter((name) => types.includes(extname2(name).toLowerCase())).sort().map((name) => join2(folder, name));
+}
+async function findHouses(root) {
+  const folders = [];
+  const walk = async (dir, depth) => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    if (entries.some((e) => e.isFile() && e.name === "house.json")) folders.push(dir);
+    if (depth >= 6) return;
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith(".") && !SKIP.has(entry.name)) {
+        await walk(join2(dir, entry.name), depth + 1);
+      }
+    }
+  };
+  await walk(resolve(root), 0);
+  const houses = await Promise.all(folders.sort().map((folder) => loadHouse(folder)));
+  return houses;
+}
+var fold = (text) => text.normalize("NFD").replace(new RegExp("\\p{Diacritic}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+async function pickHouse(query, root) {
+  const asFolder = await stat(query).catch(() => null);
+  if (asFolder?.isDirectory()) return loadHouse(query);
+  const houses = await findHouses(root);
+  const words = fold(query).split(" ").filter(Boolean);
+  const matches = houses.filter(
+    (h) => words.every((word) => fold(`${relative(root, h.folder)} ${h.name} ${h.place}`).includes(word))
+  );
+  if (matches.length === 1) return matches[0];
+  const list = (matches.length ? matches : houses).map((h) => `  ${relative(root, h.folder) || "."}`).join("\n");
+  if (matches.length) throw new HouseError(`"${query}" matches more than one house:
+${list}`);
+  throw new HouseError(
+    houses.length ? `"${query}" isn't a folder, and no house here matches it. The houses are:
+${list}` : `"${query}" isn't a folder with a house.json in it.`
+  );
+}
+async function initHouse(folder, name, place, force) {
+  const file = join2(folder, "house.json");
+  if (!force && await stat(file).catch(() => null)) {
+    throw new HouseError(`${file} already exists. Pass --force to start it again.`);
+  }
+  await mkdir2(join2(folder, "photos"), { recursive: true });
+  await mkdir2(join2(folder, "drawings"), { recursive: true });
+  await writeFile2(file, `${JSON.stringify({ name, place }, null, 2)}
+`);
+  return file;
+}
+
+// src/runs.ts
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { extname as extname3, join as join3 } from "node:path";
+var runId = (date) => date.toISOString().slice(0, 16).replace(":", "").replace("T", "-");
+async function createRun(house, run) {
+  const folder = join3(house.folder, "runs", runId(new Date(run.startedAt)));
+  await mkdir3(folder, { recursive: true });
+  const saved = { folder, name: house.name, ...run };
+  await writeFile3(join3(folder, "run.json"), `${JSON.stringify({ ...saved, folder: void 0 }, null, 2)}
+`);
+  return saved;
+}
+async function loadRun(house, name) {
+  const runs = join3(house.folder, "runs");
+  let picked = name;
+  if (!picked) {
+    const all = (await readdir2(runs).catch(() => [])).filter((entry) => !entry.startsWith(".")).sort();
+    if (!all.length)
+      throw new HouseError(`${house.folder} hasn't been built yet. Start with: home-v0 build ${house.folder}`);
+    picked = all[all.length - 1];
+  }
+  const folder = join3(runs, picked);
+  const run = JSON.parse(
+    await readFile4(join3(folder, "run.json"), "utf8").catch(() => {
+      throw new HouseError(`${folder} isn't a run of this house`);
+    })
+  );
+  return { ...run, folder };
+}
+function mediaFile(message) {
+  if (!message.url || message.kind !== "render" && message.kind !== "model") return null;
+  const ext = extname3(new URL(message.url).pathname).toLowerCase() || (message.kind === "model" ? ".glb" : ".png");
+  return `${String(message.seq).padStart(4, "0")}-${message.kind}${ext}`;
+}
+function describe(message) {
+  const who = message.role === "user" ? "you" : "agent";
+  switch (message.kind) {
+    case "step":
+      return `  \xB7 ${message.text ?? ""}${message.seconds ? ` (${message.seconds}s)` : ""}`;
+    case "render":
+    case "model":
+      return `  [${message.kind}] ${mediaFile(message) ?? message.url ?? ""}${message.text ? ` ${message.text}` : ""}`;
+    case "notice":
+      return `  [notice] ${message.text ?? ""}`;
+    case "design":
+      return `  [design] ${message.text ?? ""}`;
+    default:
+      return `${who}: ${message.text ?? ""}`;
+  }
+}
+function chatMarkdown(run, messages) {
+  const lines = [
+    `# ${run.name}`,
+    "",
+    `Started ${run.startedAt} on ${run.apiUrl}. Open it in the app: ${run.webUrl}`,
+    ""
+  ];
+  for (const message of messages) {
+    const time = message.createdAt.slice(11, 19);
+    const file = mediaFile(message);
+    if (message.kind === "render" && file) lines.push(`![render ${message.seq}](${file})`, "");
+    else if (message.kind === "model" && file) lines.push(`*${time}* model: [${file}](${file})`, "");
+    else if (message.kind === "step") lines.push(`*${time}* \xB7 ${message.text ?? ""}`, "");
+    else if (message.kind === "text")
+      lines.push(`**${message.role === "user" ? "You" : "Agent"}** *${time}*`, "", message.text ?? "", "");
+    else lines.push(`*${time}* ${message.kind}: ${message.text ?? ""}`, "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+// src/main.ts
+var POLL_MS = 3e3;
+var HELD = ["failed", "needs-key", "plan-limit", "paused"];
+var HELP = `home-v0 v${VERSION}: build a house in 3D in home-v0 from a folder of photos and drawings.
+
+Usage
+  home-v0 login [--token hv0_\u2026]           Save an API key (home-v0 \u2192 API keys)
+  home-v0 logout                          Forget the saved key
+  home-v0 init [dir] --name "\u2026" --place "\u2026"
+                                          Start a house folder: house.json, photos/, drawings/
+  home-v0 houses [dir]                    List the house folders in a folder
+  home-v0 build [house]                   Make the house in home-v0, upload its files and follow the build
+  home-v0 say [house] -m "\u2026"              Tell the agent something and follow its answer
+  home-v0 follow [house]                  Keep following the latest build until the agent's turn ends
+  home-v0 pull [house]                    Save the latest build's chat, renders and model without waiting
+  home-v0 stop [house]                    Stop the agent's current turn
+  home-v0 guide [--agents-md]             How it all works (start here, agents)
+
+A house is a folder with a house.json, the current one by default, or words from the name of one below it.
+Each build is saved in <house>/runs/<time>/.
+
+Options
+  -m, --message <text>   say: what to tell the agent
+  --run <name>           Use this build (a folder in runs/) instead of the latest
+  --timeout <minutes>    Stop following after this long (default 45)
+  --detach               build: start it and exit without following
+  --api-url <url>        The home-v0 API (default https://api.home-v0.com, or HOME_V0_API_URL)
+  --token <key>          API key for this run (or HOME_V0_API_KEY)
+  --force                init: start again over an existing house.json
+  -h, --help             Show this help
+  -v, --version          Show the version`;
+var UsageError = class extends Error {
+};
+var AuthError = class extends Error {
+};
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      message: { type: "string", short: "m" },
+      run: { type: "string" },
+      timeout: { type: "string", default: "45" },
+      detach: { type: "boolean", default: false },
+      "api-url": { type: "string" },
+      token: { type: "string" },
+      name: { type: "string" },
+      place: { type: "string" },
+      force: { type: "boolean", default: false },
+      "agents-md": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false }
+    }
+  });
+  const [command, target = "."] = positionals;
+  if (values.version) return console.log(VERSION);
+  if (!command || command === "help" || values.help) return console.log(HELP);
+  const connection = await resolveConnection({ apiUrl: values["api-url"], token: values.token });
+  const timeoutMs = Number(values.timeout) * 6e4;
+  if (!(timeoutMs > 0)) throw new UsageError("--timeout is a number of minutes");
+  switch (command) {
+    case "guide":
+      return console.log(values["agents-md"] ? agentsSnippet() : guide());
+    case "login":
+      return login(connection.apiUrl, values.token, values["api-url"]);
+    case "logout":
+      await clearConfig();
+      return console.log("Signed out: the saved key is gone.");
+    case "init": {
+      if (!values.name || !values.place) throw new UsageError('init needs --name "\u2026" and --place "\u2026"');
+      const file = await initHouse(target, values.name, values.place, values.force);
+      return console.log(
+        `Wrote ${file}. Add outside photos to photos/ and any plans to drawings/, then: home-v0 build ${target}`
+      );
+    }
+    case "houses":
+      return listHouses(target);
+    case "build": {
+      const house = await pickHouse(target, ".");
+      const api = await signIn(connection.apiUrl, connection.token);
+      const run = await startBuild(api, house);
+      if (values.detach) return console.log(`Started. Follow it with: home-v0 follow ${house.folder}`);
+      return finish(await follow(api, run, 0, timeoutMs), run);
+    }
+    case "say":
+    case "follow":
+    case "pull":
+    case "stop": {
+      const house = await pickHouse(target, ".");
+      const run = await loadRun(house, values.run);
+      const api = await signIn(run.apiUrl, connection.token);
+      return afterBuild(command, api, run, values.message, timeoutMs);
+    }
+    default:
+      throw new UsageError(`Unknown command "${command}". Run: home-v0 --help`);
+  }
+}
+async function afterBuild(command, api, run, message, timeoutMs) {
+  if (command === "follow") return finish(await follow(api, run, 0, timeoutMs), run);
+  if (command === "pull") {
+    const { messages: messages2 } = await save(api, run, /* @__PURE__ */ new Set());
+    return console.log(`Saved ${messages2.length} messages to ${run.folder}`);
+  }
+  const { session, messages } = await api.conversation(run.spaceId);
+  if (!session) throw new UsageError("This house's agent hasn't started yet. Wait for it with: home-v0 follow");
+  if (command === "stop") {
+    const stopped = await api.stop(session.id);
+    return console.log(`Stopped. The agent is ${stopped.status}.`);
+  }
+  const text = message?.trim();
+  if (!text) throw new UsageError('What should I tell the agent? home-v0 say -m "the roof is steeper"');
+  const since = messages.at(-1)?.seq ?? 0;
+  await api.send(session.id, text);
+  return finish(await follow(api, run, since, timeoutMs), run);
+}
+async function login(apiUrl, flagToken, flagApiUrl) {
+  let token = flagToken ?? "";
+  if (!token) {
+    if (!process.stdin.isTTY) throw new UsageError("Pass the key: home-v0 login --token hv0_\u2026");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    token = (await rl.question(`API key (make one at ${webUrlFor(apiUrl)}/dashboard/api-keys): `)).trim();
+    rl.close();
+  }
+  if (!token.startsWith("hv0_")) throw new UsageError("That isn't a home-v0 API key: they start with hv0_");
+  const api = new HomeApi(apiUrl, { apiKey: token });
+  await api.checkKey().catch((error) => {
+    throw error instanceof ApiError && error.status === 401 ? new AuthError(`${apiUrl} doesn't accept that key: it may have been revoked. Make a new one.`) : error;
+  });
+  const path = await saveConfig({ token, ...flagApiUrl ? { apiUrl: flagApiUrl } : {} });
+  console.log(`Signed in to ${apiUrl}. The key is saved in ${path}.`);
+}
+async function listHouses(root) {
+  const houses = await findHouses(root);
+  if (!houses.length) {
+    return console.log(`No house folders in ${root === "." ? "this folder" : root}. Start one with: home-v0 init`);
+  }
+  for (const house of houses) {
+    const runs = (await readdir3(join4(house.folder, "runs")).catch(() => [])).filter((r) => !r.startsWith("."));
+    const files = house.photos.length ? `${count(house.photos.length, "photo")}, ${count(house.drawings.length, "drawing")}` : `${count(house.drawings.length, "drawing")}, needs photos`;
+    const built = runs.length ? `, ${count(runs.length, "build")}` : "";
+    console.log(`${relative2(root, house.folder) || "."}: ${house.name}, ${house.place} (${files}${built})`);
+  }
+}
+async function signIn(apiUrl, token) {
+  let api;
+  if (token) api = new HomeApi(apiUrl, { apiKey: token });
+  else if (isLocal(apiUrl)) {
+    api = new HomeApi(apiUrl, { devAccount: { email: "cli@home-v0.local", password: "home-v0-cli" } });
+  } else {
+    throw new AuthError(
+      `Not signed in. Make an API key at ${webUrlFor(apiUrl)}/dashboard/api-keys, then run home-v0 login or set HOME_V0_API_KEY.`
+    );
+  }
+  await api.signIn();
+  return api;
+}
+async function startBuild(api, house) {
+  if (!house.photos.length) {
+    throw new HouseError(
+      `${house.folder} has no photos, and home-v0 reads a house from its photos. Add some to photos/.`
+    );
+  }
+  console.log(`Building ${house.name} on ${api.baseUrl}`);
+  const [place] = await api.searchPlaces(house.place);
+  if (place) console.log(`  place: ${place.label}${place.footprint ? ", with its outline from the map" : ""}`);
+  else console.log(`  place: nothing found for "${house.place}", so it has no location`);
+  const startedAt = /* @__PURE__ */ new Date();
+  const project = await api.createProject(house.name, place);
+  let run;
+  try {
+    const exterior = (await api.spaces(project.id)).find((space2) => space2.kind === "exterior");
+    if (!exterior) throw new Error(`The new house ${project.id} has no exterior`);
+    let space = await api.addPhotos(exterior.id, house.photos);
+    for (let i = 0; i < house.drawings.length; i += MAX_DRAWING_FILES_PER_UPLOAD) {
+      space = await api.addDrawings(exterior.id, house.drawings.slice(i, i + MAX_DRAWING_FILES_PER_UPLOAD));
+    }
+    console.log(
+      `  uploaded ${count(space.photos.length, "photo")} and ${count(space.drawings.length, "page")} of drawings`
+    );
+    run = await createRun(house, {
+      apiUrl: api.baseUrl,
+      webUrl: `${webUrlFor(api.baseUrl)}/projects/${project.id}/exterior`,
+      projectId: project.id,
+      spaceId: exterior.id,
+      startedAt: startedAt.toISOString()
+    });
+    await api.capture(exterior.id);
+  } catch (error) {
+    await api.deleteProject(project.id).catch(() => void 0);
+    if (run) await rm2(run.folder, { recursive: true, force: true });
+    throw error;
+  }
+  console.log(`  in the app: ${run.webUrl}`);
+  console.log(`  results: ${run.folder}`);
+  return run;
+}
+async function follow(api, run, since, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const seen = /* @__PURE__ */ new Set();
+  let capture = "";
+  let status = "";
+  for (; ; ) {
+    const { session, messages } = await save(api, run, seen, (message) => {
+      if (message.seq > since) console.log(describe(message));
+    });
+    if (!session) {
+      const space = await api.space(run.spaceId);
+      const state = space.capture ? `${space.capture.status}${space.capture.progress ? `: ${space.capture.progress}` : ""}` : "";
+      if (state && state !== capture) console.log(`  reading photos: ${state}`);
+      capture = state;
+      if (space.capture?.status === "failed") throw new Error(`Reading the photos failed: ${space.capture.error}`);
+      if (space.capture?.status === "succeeded" && !messages.length) {
+        throw new Error("The photos were read but the agent didn't start. Try again later.");
+      }
+    } else {
+      if (session.status !== status) console.log(`  status: ${session.status}`);
+      status = session.status;
+      if (HELD.includes(session.status)) return session;
+      if (session.status === "waiting" && messages.some((m) => m.role === "agent" && m.seq > since)) return session;
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`Still going after ${timeoutMs / 6e4} minutes. Keep watching with: home-v0 follow`);
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, POLL_MS));
+  }
+}
+async function save(api, run, seen, onNew) {
+  const { session, messages } = await api.conversation(run.spaceId);
+  const fresh = messages.filter((m) => !seen.has(m.seq));
+  for (const message of fresh) {
+    const file = mediaFile(message);
+    if (file && message.url && !await exists(join4(run.folder, file))) {
+      const { body } = await api.download(message.url);
+      await writeFile4(join4(run.folder, file), body);
+    }
+    seen.add(message.seq);
+    onNew?.(message);
+  }
+  if (fresh.length || !await exists(join4(run.folder, "chat.md"))) {
+    await writeFile4(join4(run.folder, "chat.md"), chatMarkdown(run, messages));
+    await writeFile4(join4(run.folder, "messages.json"), `${JSON.stringify({ session, messages }, null, 2)}
+`);
+  }
+  return { session, messages };
+}
+function finish(session, run) {
+  console.log(
+    `
+The agent is ${session.status}. Spent $${session.spentUsd.toFixed(2)} of $${session.budgetUsd.toFixed(2)}.`
+  );
+  console.log(`Chat, renders and model: ${run.folder}`);
+  console.log(`In the app: ${run.webUrl}`);
+  if (HELD.includes(session.status) && session.status !== "paused") process.exitCode = 1;
+}
+var count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+var exists = (path) => access(path).then(
+  () => true,
+  () => false
+);
+var exitCode = (error) => {
+  if (error instanceof UsageError || error.code?.startsWith("ERR_PARSE_ARGS")) return 2;
+  if (error instanceof AuthError || error instanceof ApiError && (error.status === 401 || error.status === 403)) {
+    return 3;
+  }
+  if (error instanceof HouseError) return 4;
+  return 1;
+};
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = exitCode(error);
+});

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@home-v0/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Build a house in 3D in home-v0 from a folder of photos and floor plans. Made for people and AI agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simenravnik/home-v0.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://home-v0.com",
+  "type": "module",
+  "bin": {
+    "home-v0": "dist/home-v0.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "home-v0",
+    "house",
+    "renovation",
+    "floor-plan",
+    "3d",
+    "cli",
+    "ai-agents"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "format": "prettier . --write --ignore-unknown",
+    "test": "node --test --disable-warning=ExperimentalWarning 'src/*.test.ts'",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "esbuild": "^0.28.2",
+    "typescript": "~6.0.3"
+  }
+}