@letterstory/cli 0.176.48 → 0.176.49

package/lib/cli.mjs

@@ -80,11 +80,12 @@ import {
 	cmdBench,
 	cmdReplicate,
 	cmdDeploy,
+	cmdRefs,
 } 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.48";
+export const VERSION = "0.176.49";
 
 /** 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;
@@ -1723,6 +1724,7 @@ Build (a change to your site, or launching what isn't code; the Build box's own
                                                        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.
                                                        --new-site: a website of its own, built and hosted (deploy create)
+                                                       --look-like a.com,b.com (with --new-site): sites to model its look after
   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)
@@ -1891,9 +1893,10 @@ Vary (A/B tests of a page's words and images on your own site):
 
 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]
+  deploy create "<what it is and who it is for>" [--name <n>] [--domain <d>] [--ref <visual-ref-id>] [--wait]
                                                        Named, given a domain (bought under $30 unless you name one),
-                                                       built by Letterpress-1 with Visitors in it, and put live
+                                                       built by Letterpress-1 with Visitors in it, and put live;
+                                                       --ref designs it after a Visual Ref (refs create)
   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>
@@ -1902,6 +1905,17 @@ Deploy (websites and apps Letter builds from your words and hosts on their own d
   deploy connect <id> <owner/name>                     Move its source to your GitHub repo (empty); it's
                                                        pushed once the Letter GitHub App can reach it
 
+Refs (Visual Refs: other companies' brands to design something new after, apart from your own brand):
+  refs [list] [--archived]                             Your Visual Refs and their brands
+  refs create "<name>" --brand <host[=what to take]>… [--notes <n>]
+                                                       Each brand is learned from its site (a few minutes)
+  refs show <id>                                       Its brands, whether each is learned, their type
+  refs update <id> [--name <n>] [--notes <n>] [--brand <host[=note]>]… [--remove <host>]…
+  refs archive <id> | refs restore <id>
+  refs brief <id> "<what is being made, for whom>" [--wait]
+                                                       Every brand's direction for it, as one file
+  refs brief-show <brief-id>                           The brief, once ready
+
 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>]
@@ -2036,6 +2050,7 @@ const CLIENT_COMMANDS = {
 	bench: cmdBench,
 	replicate: cmdReplicate,
 	deploy: cmdDeploy,
+	refs: cmdRefs,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,
 };

package/lib/commands/build.mjs

@@ -16,7 +16,16 @@
 
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { argsFromFlags, flagList, flagStr, followJob, ok, printResult, refuseUnknownFlags } from "./shared.mjs";
+import {
+	argsFromFlags,
+	flagCsv,
+	flagList,
+	flagStr,
+	followJob,
+	ok,
+	printResult,
+	refuseUnknownFlags,
+} from "./shared.mjs";
 import { attachmentUrls, uploadAttachments } from "./repo.mjs";
 
 const ARGS = {
@@ -54,6 +63,8 @@ const ARGS = {
 		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" },
+		// --new-site --look-like linear.app,supabase.com: other companies' sites to model its look after.
+		look_like: { value: (flags) => (flagCsv(flags["look-like"]).length ? flagCsv(flags["look-like"]) : undefined) },
 		// --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-only always plans what it's given, as /plan does: it was asked for by name.

package/lib/commands/deploy.mjs

@@ -3,7 +3,7 @@
 // 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 create "Build me a website for HVAC contractors to collect leads" [--name <n>] [--domain <d>] [--ref <visual-ref-id>] [--wait]
 //   letterstory deploy list [--kind app|phantom|bench]
 //   letterstory deploy show <id>
 //   letterstory deploy update <id> [--name <n>] [--domain <d>]
@@ -29,6 +29,7 @@ export const ARGS = {
 		prompt: { value: (flags, positionals) => flagStr(flags.prompt) ?? (positionals.join(" ").trim() || undefined) },
 		name: "name",
 		domain: "domain",
+		visual_ref_id: { flag: "ref" },
 		wait: { flag: "wait", type: "bool" },
 	},
 	list_deployments: { kind: { flag: "kind", enum: ["app", "phantom", "bench"] } },

package/lib/commands/refs.mjs

@@ -0,0 +1,131 @@
+// `refs` — Visual Refs from a terminal (docs/architecture/visual-refs.md): sets of other companies'
+// brands to design something new after, kept apart from your own brand. Thin wrappers over the
+// Visual Ref tools (create_visual_ref, list_visual_refs, get_visual_ref, update_visual_ref,
+// brief_visual_ref, get_visual_ref_brief), the same lib functions the app calls.
+//
+//   letterstory refs list [--archived]
+//   letterstory refs create "Linear × Supabase" --brand linear.app --brand "supabase.com=the dark palette" [--notes <n>]
+//   letterstory refs show <id>
+//   letterstory refs update <id> [--name <n>] [--notes <n>] [--brand <host[=note]>]… [--remove <host>]…
+//   letterstory refs archive <id> | refs restore <id>
+//   letterstory refs brief <id> "<what is being made, for whom>" [--wait]
+//   letterstory refs brief-show <brief-id>
+//   letterstory deploy create "<the site>" --ref <id>     a new site designed after the ref
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagList, flagStr, printResult, refuseUnknownFlags } from "./shared.mjs";
+
+const refId = { positional: 0, label: "ref-id", required: true };
+
+/** `--brand host` or `--brand "host=what to take from it"`, repeatable. */
+function brandsOf(flags) {
+	const brands = flagList(flags.brand).map((raw) => {
+		const at = raw.indexOf("=");
+		const host = (at < 0 ? raw : raw.slice(0, at)).trim();
+		const note = at < 0 ? "" : raw.slice(at + 1).trim();
+		return note ? { host, note } : { host };
+	});
+	return brands.length ? brands : undefined;
+}
+
+export const ARGS = {
+	create_visual_ref: {
+		name: { value: (flags, positionals) => flagStr(flags.name) ?? (positionals.join(" ").trim() || undefined) },
+		notes: "notes",
+		brands: { value: (flags) => brandsOf(flags) },
+	},
+	list_visual_refs: { archived: { flag: "archived", type: "bool" } },
+	get_visual_ref: { ref_id: refId },
+	update_visual_ref: {
+		ref_id: refId,
+		name: "name",
+		notes: "notes",
+		add_brands: { value: (flags) => brandsOf(flags) },
+		remove_hosts: { value: (flags) => (flagList(flags.remove).length ? flagList(flags.remove) : undefined) },
+		archived: { internal: "refs archive / refs restore" },
+	},
+	brief_visual_ref: {
+		ref_id: refId,
+		task: {
+			value: (flags, positionals) => flagStr(flags.task) ?? (positionals.slice(1).join(" ").trim() || undefined),
+		},
+		wait: { flag: "wait", type: "bool" },
+	},
+	get_visual_ref_brief: { brief_id: { positional: 0, label: "brief-id", required: true } },
+};
+
+function call(ctx, tool, extra = {}) {
+	return ctx.client.callTool(tool, { ...argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals), ...extra });
+}
+
+export async function cmdRefs(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case undefined:
+		case "list":
+		case "ls": {
+			refuseUnknownFlags(rest, ARGS.list_visual_refs, []);
+			const result = await call(rest, "list_visual_refs");
+			printResult(rest.io, rest.flags, result, (r) => {
+				if (!r.refs?.length)
+					return 'No Visual Refs yet. Make one: refs create "Linear × Supabase" --brand linear.app --brand supabase.com';
+				return r.refs
+					.map((v) => `${v.id}  ${v.name.slice(0, 28).padEnd(28)} ${v.brands.map((b) => b.host).join(", ")}`)
+					.join("\n");
+			});
+			return 0;
+		}
+		case "create": {
+			refuseUnknownFlags(rest, ARGS.create_visual_ref, ["brand", "name"]);
+			const args = argsFromFlags(ARGS.create_visual_ref, rest.flags, rest.positionals);
+			if (!args.name || !args.brands)
+				throw new CliError('Name it and give its brands: refs create "Linear × Supabase" --brand linear.app');
+			return refShow(rest, await rest.client.callTool("create_visual_ref", args));
+		}
+		case "show":
+			return refShow(rest, await call(rest, "get_visual_ref"));
+		case "update":
+			refuseUnknownFlags(rest, ARGS.update_visual_ref, ["brand", "remove"]);
+			return refShow(rest, await call(rest, "update_visual_ref"));
+		case "archive":
+		case "restore":
+			return refShow(rest, await call(rest, "update_visual_ref", { archived: sub === "archive" }));
+		case "brief": {
+			refuseUnknownFlags(rest, ARGS.brief_visual_ref, ["task"]);
+			return briefShow(rest, await call(rest, "brief_visual_ref"));
+		}
+		case "brief-show":
+			return briefShow(rest, await call(rest, "get_visual_ref_brief"));
+		default:
+			throw new CliError("Usage: refs [list|create|show|update|archive|restore|brief|brief-show]");
+	}
+}
+
+function refShow(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const v = r.ref;
+		const lines = [`${v.name}${v.archivedAt ? " (archived)" : ""}  ${v.id}`, ...(v.notes ? [`  ${v.notes}`] : [])];
+		for (const b of v.brands) {
+			const state = b.brand ? b.brand.state : "";
+			lines.push(`  ${b.host.padEnd(28)} ${state.padEnd(12)} ${b.note ?? ""}`.trimEnd());
+			const type = b.brand?.profile?.type?.map((t) => t.family).filter(Boolean);
+			if (type?.length) lines.push(`    type: ${[...new Set(type)].join(", ")}`);
+		}
+		lines.push("", `Brief a task on it: refs brief ${v.id} "<what is being made, for whom>"`);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+function briefShow(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const b = r.brief;
+		if (b.status === "pending") {
+			const parts = b.parts.map((p) => `  ${p.host.padEnd(28)} ${p.status}`);
+			return [`Brief ${b.id}: pending`, ...parts, "", `Check again: refs brief-show ${b.id}`].join("\n");
+		}
+		return b.markdown ?? `Brief ${b.id}: ${b.status}`;
+	});
+	return 0;
+}

package/lib/commands.mjs

@@ -57,3 +57,4 @@ export * from "./commands/domains.mjs";
 export * from "./commands/bench.mjs";
 export * from "./commands/replicate.mjs";
 export * from "./commands/deploy.mjs";
+export * from "./commands/refs.mjs";

package/package.json

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