@letterstory/cli 0.176.27 → 0.176.28

package/lib/cli.mjs

@@ -78,11 +78,12 @@ import {
 	cmdVary,
 	cmdDomains,
 	cmdBench,
+	cmdDeploy,
 } from "./commands.mjs";
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.27";
+export const VERSION = "0.176.28";
 
 /** The exit code for a gate refusal (CARD_REQUIRED, PAYMENT_FAILED, OUT_OF_TOKENS): 1 is a plain error. */
 export const EXIT_PAYMENT_REQUIRED = 3;
@@ -93,6 +94,9 @@ export const EXIT_PAYMENT_REQUIRED = 3;
 export const BOOLEAN_FLAGS = new Set([
 	// build list: also move the builds' open changes along while polling.
 	"advance",
+	// build: a website or app of its own (deploy create's path). deploy create: hold until its build starts.
+	"new-site",
+	"wait",
 	// automations set: stop reading a data feed.
 	"no-reads",
 	// vary start: pause the test running on the page first.
@@ -1689,11 +1693,12 @@ Insights:
 Build (a change to your site, or launching what isn't code; the Build box's own door):
   build <words…> [--prompt <text>] [--site <host>] [--subject <host/path>]... [--action build|build_pr|build_merge|slack|linear]
              [--attach <path>]... [--attach-url <name>=<https url>]... [--attach-ref <path>]... [--attach-url-ref <name>=<https url>]...
-             [--harness letterpress-1|claude-code|codex] [--effort low|medium|high|xhigh] [--notify-slack] [--again]
+             [--harness letterpress-1|claude-code|codex] [--effort low|medium|high|xhigh] [--notify-slack] [--again] [--new-site]
                                                        Build from your words: "add a pricing page" opens a preview or PR;
                                                        "launch a phantom for us", "set up mailers" or "onboard my blog" is
                                                        done by Build itself (a phantom site buys its own domain), and the
-                                                       build reads Done with no PR to merge. --again repeats an open build's ask
+                                                       build reads Done with no PR to merge. --again repeats an open build's ask.
+                                                       --new-site: a website of its own, built and hosted (deploy create)
   build talk <words…> [--conversation <id>|--build <id>] [--site <host>] [--harness letterpress-1|claude-code|codex]
              [--repo owner/name] [--action build|build_pr|build_merge]
                                                        One turn of a conversation with Build (questions, follow-ups on a build)
@@ -1859,6 +1864,19 @@ Vary (A/B tests of a page's words and images on your own site):
   vary start <id> [--pause-running] | vary pause <id> | vary end <id> [--winner b]
   vary remove-variant <id> <key> | vary delete <id>
 
+Deploy (websites and apps Letter builds from your words and hosts on their own domains):
+  deploy [list] [--kind app|phantom|bench]             Everything deployed: apps, phantoms (and benches, for staff)
+  deploy create "<what it is and who it is for>" [--name <n>] [--domain <d>] [--wait]
+                                                       Named, given a domain (bought under $30 unless you name one),
+                                                       built by Letterpress-1 with Visitors in it, and put live
+  deploy show <id>                                     Where it stands, its domain, the records to set, recent events
+  deploy update <id> [--name <n>] [--domain <d>]       The domain only before it is built
+  deploy pause <id> | deploy resume <id> | deploy archive <id>
+  deploy advance <id> [--retry]                        Move it on now; --retry once blocked_on is done
+  deploy source <id>                                   A link to download its source, as Letter keeps it
+  deploy connect <id> <owner/name>                     Move its source to your GitHub repo (empty); it's
+                                                       pushed once the Letter GitHub App can reach it
+
 Bench (Benches: open-source benchmarks on their own domains, kept running; @letterstory.com only):
   bench [list]                                         Your benches: stage, what each waits on, domain
   bench create (--prompt "<what it is and how it works>"|--prompt-file <path>) [--name <n>] [--domain <d>]
@@ -1982,6 +2000,7 @@ const CLIENT_COMMANDS = {
 	vary: cmdVary,
 	domains: cmdDomains,
 	bench: cmdBench,
+	deploy: cmdDeploy,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,
 };

package/lib/commands/build.mjs

@@ -39,6 +39,8 @@ const ARGS = {
 		again: { flag: "again", type: "bool" },
 		// --recipe <id>: the recipe the build carries out (a Plan row's), recorded on it.
 		recipe: "recipe",
+		// --new-site: a website or app of its own, built and hosted on its own domain (deploy create's path).
+		new_site: { flag: "new-site", type: "bool" },
 		// --plan-only: answer what it would do and start nothing (--json for the plan to send back).
 		plan_only: { flag: "plan-only", type: "bool" },
 		// --plan-file <path>: build exactly the plan --plan-only answered.

package/lib/commands/deploy.mjs

@@ -0,0 +1,150 @@
+// `deploy` — Deployments from a terminal (docs/architecture/deployments.md): websites and apps Letter
+// builds from your words and hosts on their own domains, with your phantoms and benches in the list.
+// Thin wrappers over the deployment tools (create_deployment, list_deployments, get_deployment,
+// update_deployment, advance_deployment), the same lib functions the app calls.
+//
+//   letterstory deploy create "Build me a website for HVAC contractors to collect leads" [--name <n>] [--domain <d>] [--wait]
+//   letterstory deploy list [--kind app|phantom|bench]
+//   letterstory deploy show <id>
+//   letterstory deploy update <id> [--name <n>] [--domain <d>]
+//   letterstory deploy pause <id> | resume <id> | archive <id>
+//   letterstory deploy advance <id> [--retry]
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagStr, printResult, refuseUnknownFlags } from "./shared.mjs";
+
+const appId = { positional: 0, label: "app-id", required: true };
+
+/** `owner/name` from the command line, one part of it. */
+function repoPart(value, i) {
+	const parts = String(value ?? "").split("/");
+	if (parts.length !== 2 || !parts[0] || !parts[1])
+		throw new CliError("Name the repo as owner/name: deploy connect <id> acme/site");
+	return parts[i];
+}
+
+export const ARGS = {
+	create_deployment: {
+		// The words after `create`, or --prompt for a longer ask.
+		prompt: { value: (flags, positionals) => flagStr(flags.prompt) ?? (positionals.join(" ").trim() || undefined) },
+		name: "name",
+		domain: "domain",
+		wait: { flag: "wait", type: "bool" },
+	},
+	list_deployments: { kind: { flag: "kind", enum: ["app", "phantom", "bench"] } },
+	get_deployment: { id: appId },
+	update_deployment: {
+		id: appId,
+		name: "name",
+		domain: "domain",
+		status: { flag: "status", enum: ["live", "paused", "archived"] },
+	},
+	advance_deployment: { id: appId, retry: { flag: "retry", type: "bool" } },
+	connect_deployment_repo: {
+		id: appId,
+		repo_owner: { value: (_flags, positionals) => repoPart(positionals[1], 0) },
+		repo_name: { value: (_flags, positionals) => repoPart(positionals[1], 1) },
+	},
+	export_deployment_source: { id: appId },
+};
+
+function call(ctx, tool) {
+	return ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+}
+
+export async function cmdDeploy(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case undefined:
+		case "list":
+		case "ls":
+			return deployList(rest);
+		case "create": {
+			refuseUnknownFlags(rest, ARGS.create_deployment, ["prompt"]);
+			const args = argsFromFlags(ARGS.create_deployment, rest.flags, rest.positionals);
+			if (!args.prompt)
+				throw new CliError(
+					'Say what to build: letterstory deploy create "a website for HVAC contractors to collect leads"'
+				);
+			return deployShow(rest, await rest.client.callTool("create_deployment", args));
+		}
+		case "show":
+			return deployShow(rest, await call(rest, "get_deployment"));
+		case "update":
+			refuseUnknownFlags(rest, ARGS.update_deployment, []);
+			return deployShow(rest, await call(rest, "update_deployment"));
+		case "pause":
+		case "resume":
+		case "archive":
+			rest.flags = { ...rest.flags, status: { pause: "paused", resume: "live", archive: "archived" }[sub] };
+			return deployShow(rest, await call(rest, "update_deployment"));
+		case "advance":
+			refuseUnknownFlags(rest, ARGS.advance_deployment, []);
+			return deployShow(rest, await call(rest, "advance_deployment"));
+		case "connect":
+			return deployShow(rest, await call(rest, "connect_deployment_repo"));
+		case "source": {
+			const result = await call(rest, "export_deployment_source");
+			printResult(
+				rest.io,
+				rest.flags,
+				result,
+				(r) => `${r.url}\n(the source of main, ${r.sha.slice(0, 7)}, for an hour)`
+			);
+			return 0;
+		}
+		default:
+			throw new CliError("Usage: deploy [list|create|show|update|pause|resume|archive|advance|connect|source]");
+	}
+}
+
+async function deployList(ctx) {
+	const result = await call(ctx, "list_deployments");
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		if (!r.deployments?.length)
+			return 'Nothing deployed yet. Build a site: deploy create "<what it is and who it is for>"';
+		return r.deployments
+			.map(
+				(d) =>
+					`${d.id}  ${d.kind.padEnd(7)} ${d.name.slice(0, 28).padEnd(28)} ${(d.blocked ? "blocked" : d.status).padEnd(10)} ${d.url ?? d.domain ?? ""}`
+			)
+			.join("\n");
+	});
+	return 0;
+}
+
+function deployShow(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const a = r.app;
+		const lines = [
+			`${a.name} — ${a.status}, stage ${a.stage}`,
+			...(a.blocked_on ? [`  Blocked: ${a.blocked_on}`, `  Then: deploy advance ${a.id} --retry`] : []),
+			...(a.stage_note && !a.blocked_on ? [`  ${a.stage_note}`] : []),
+			...(a.domain ? [`  Domain  ${a.domain}${a.domain_set_by === "letter" ? " (chosen and bought)" : ""}`] : []),
+			...(a.url ? [`  Site    ${a.url}${a.site_ok === false ? " (not serving at the last check)" : ""}`] : []),
+			...(a.run_id ? [`  Run     ${a.run_id} (repo show ${a.run_id})`] : []),
+			...(a.deployed ? [`  Live    ${a.deployed.sha.slice(0, 7)} since ${a.deployed.at}`] : []),
+			...(a.last_deploy_error ? [`  Last release didn't start: ${a.last_deploy_error.message}`] : []),
+			...(a.source?.kept_by === "github"
+				? [`  Source  ${a.source.url}`]
+				: a.source?.repo
+					? [`  Source  kept by Letter (deploy source ${a.id}; deploy connect ${a.id} owner/name)`]
+					: []),
+			...(a.source?.pending
+				? [`  Moving to ${a.source.pending.repo}: ${a.source.pending.note ?? "trying now"}`]
+				: []),
+		];
+		if (a.dns?.to_set?.length) {
+			lines.push("", `Set these where ${a.domain}'s DNS is:`);
+			for (const rec of a.dns.to_set) lines.push(`  ${rec.type.padEnd(6)} ${rec.name.padEnd(6)} ${rec.value}`);
+		}
+		if (r.build_id) lines.push("", `Building: build show ${r.build_id}`);
+		if (r.events?.length) {
+			lines.push("", "Recent:");
+			for (const e of r.events.slice(0, 8)) lines.push(`  ${e.at}  ${e.message}`);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}

package/lib/commands.mjs

@@ -55,3 +55,4 @@ export * from "./commands/sim.mjs";
 export * from "./commands/vary.mjs";
 export * from "./commands/domains.mjs";
 export * from "./commands/bench.mjs";
+export * from "./commands/deploy.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.176.27",
+	"version": "0.176.28",
 	"description": "Spin up and manage Letter phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",