@letterstory/cli 0.98.1 → 0.98.3

package/lib/cli.mjs

@@ -51,6 +51,7 @@ import {
 	cmdMailers,
 	cmdAdmin,
 	cmdFeedback,
+	cmdRepo,
 	cmdEvals,
 	cmdOfferings,
 	cmdTargets,
@@ -58,7 +59,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.98.1";
+export const VERSION = "0.98.3";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value. Every `type: "bool"` flag (and its
@@ -144,6 +145,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"no-enrich",
 	// `offerings set-collection <id> --none` (the org itself is the subject again).
 	"none",
+	// `repo set-site --repo <owner/name> --site <host> --not` (the repo does not build that site).
+	"not",
 	// `prospects import|source --one-per-company`, `prospects source --enrich`, `prospects import --find-emails`.
 	"one-per-company",
 	"enrich",
@@ -1097,6 +1100,23 @@ Insights:
   insights access [--period 14d|30d|90d] [--collection <uuid>]
                                                        Page access: who's reading your phantom sites
 
+Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub App opens a PR):
+  repo repos                                           Repos the Letterstory GitHub App can reach
+  repo start --repo <owner/name> --instructions <text>|--instructions-file <path|->
+             [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]... [--wait]
+                                                       Start a change (attached files go to the sandbox);
+                                                       --wait follows it to the PR
+  repo fix-audit --issue <issue-type> [--audit <id>] [--branch <base>] [--wait]
+                                                       One PR fixing a site-audit issue on every affected page,
+                                                       in the repo verified to build the site
+  repo sites [--detect [--force]]                      Which website each repo builds, and the evidence
+  repo set-site --repo <owner/name> --site <host> [--not]
+                                                       Say which site a repo builds (--not: correct a wrong label)
+  repo reset-site --repo <owner/name> --site <host>    Back to automatic detection
+  repo status <run-id>                                 Phase, spend, PR link and Claude's summary
+  repo list [--status running|succeeded|no_changes|failed|cancelled] [--limit n] [--audit <id>]
+  repo cancel <run-id>                                 Stop it and delete the sandbox; no PR
+
 Feedback (tell us what's broken, missing, unclear, or wanted):
   feedback submit --category bug|missing_feature|unclear|feature_request|praise|other
                   [--message <text>|--body <text>|--file <path>|--file -] [--rating 1-5]
@@ -1201,6 +1221,7 @@ const CLIENT_COMMANDS = {
 	mail: cmdMail,
 	mailers: cmdMailers,
 	feedback: cmdFeedback,
+	repo: cmdRepo,
 	evals: cmdEvals,
 	visits: cmdVisits,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.

package/lib/commands/admin.mjs

@@ -3824,7 +3824,7 @@ async function cmdAdminFleetExperiments(ctx) {
 			const org = rest.find(Boolean);
 			if (!id || !org)
 				throw new CliError(
-					"Usage: admin fleet-experiments spin-up <experiment-id> <org-domain-or-id> [--no-control] [--own-beat] [--posts n]"
+					"Usage: admin fleet-experiments spin-up <experiment-id> <org-domain-or-id> [--no-control] [--own-beat] [--cadence n] [--posts n]"
 				);
 			const body = {
 				action: "spin_up",
@@ -3833,13 +3833,17 @@ async function cmdAdminFleetExperiments(ctx) {
 				control: !flagBool(flags["no-control"]),
 				match: flagBool(flags["own-beat"]) ? "own_beat" : "twin",
 				...(flagStr(flags.posts) ? { posts_to_seed: Number(flagStr(flags.posts)) } : {}),
+				...(flagStr(flags.cadence) ? { cadence_per_week: Number(flagStr(flags.cadence)) } : {}),
 			};
 			return out(await action(body), (r) =>
 				[
 					r.twins
 						? `launching twins for ${r.org.name} on "${r.sites[0]?.beat}":`
 						: `launching for ${r.org.name}:`,
-					...r.sites.map((s) => `  ${s.arm}: ${s.name ?? s.beat}  (onboarding ${s.jobId})`),
+					`  ${r.cadencePerWeek} posts a week each`,
+					...r.sites.map(
+						(s) => `  ${s.arm}: ${s.name ?? s.beat}  [${s.theme} template]  (onboarding ${s.jobId})`
+					),
 				].join("\n")
 			);
 		}
@@ -3855,7 +3859,7 @@ async function cmdAdminFleetExperiments(ctx) {
 		}
 		default:
 			throw new CliError(
-				'Usage: admin fleet-experiments list | articles [--experiment <id>] [--org <id>] [--filter all|assigned|unassigned] [--arm <arm>] [--q …] [--limit n] [--offset n] | mark <experiment-id> <article-id…> --arm <arm> | unmark <experiment-id> <article-id…> | new --template <key> | clients | spin-up <experiment-id> <org> [--no-control] [--own-beat] | start|stop <experiment-id> | decide <experiment-id> --decision "…"'
+				'Usage: admin fleet-experiments list | articles [--experiment <id>] [--org <id>] [--filter all|assigned|unassigned] [--arm <arm>] [--q …] [--limit n] [--offset n] | mark <experiment-id> <article-id…> --arm <arm> | unmark <experiment-id> <article-id…> | new --template <key> | clients | spin-up <experiment-id> <org> [--no-control] [--own-beat] [--cadence n] | start|stop <experiment-id> | decide <experiment-id> --decision "…"'
 			);
 	}
 }

package/lib/commands/repo.mjs

@@ -0,0 +1,305 @@
+// `repo` — changes to the org's own repos, made by Claude Code in a sandbox and opened as a
+// pull request by the Letterstory GitHub App (src/lib/repo-changes). One subcommand per tool:
+//   repo start   → start_repo_change     repo status → get_repo_change
+//   repo list    → list_repo_changes     repo cancel → cancel_repo_change
+//   repo repos   → list_github_app_repos
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { CliError } from "../client.mjs";
+import {
+	argsFromFlags,
+	flagList,
+	flagStr,
+	followJob,
+	ok,
+	printResult,
+	readTextInput,
+	refuseUnknownFlags,
+} from "./shared.mjs";
+
+/** `--repo owner/name` → the two schema keys; --owner/--name also work. */
+function splitRepo(flags) {
+	const full = flagStr(flags.repo);
+	if (full === undefined) return { owner: flagStr(flags.owner), name: flagStr(flags.name) };
+	const [owner, name, ...extra] = full.split("/");
+	if (!owner || !name || extra.length) throw new CliError("--repo must be owner/name");
+	return { owner, name };
+}
+
+const ARGS = {
+	start_repo_change: {
+		repo_owner: { value: (flags) => splitRepo(flags).owner },
+		repo_name: { value: (flags) => splitRepo(flags).name },
+		base_branch: "branch",
+		// --instructions, or a longer brief from --instructions-file <path> / - (stdin).
+		instructions: { value: (flags) => readTextInput(flags, "instructions", "instructions-file") },
+		// --attach <path> (uploaded first) and --attach-url <name>=<https url>, both repeatable.
+		files: { value: (_flags, _positionals, extra) => (extra.files?.length ? extra.files : undefined) },
+	},
+	create_repo_change_upload: { file_names: { internal: "the basenames of the --attach files" } },
+	list_repo_sites: {},
+	detect_repo_sites: { force: { flag: "force", type: "bool" } },
+	set_repo_site: {
+		repo_owner: { value: (flags) => splitRepo(flags).owner },
+		repo_name: { value: (flags) => splitRepo(flags).name },
+		site_host: { flag: "site", required: true },
+		builds: { flag: "not", type: "bool", invert: true },
+	},
+	reset_repo_site: {
+		repo_owner: { value: (flags) => splitRepo(flags).owner },
+		repo_name: { value: (flags) => splitRepo(flags).name },
+		site_host: { flag: "site", required: true },
+	},
+	fix_audit_issue: {
+		issue_type: { flag: "issue", required: true },
+		audit_id: "audit",
+		base_branch: "branch",
+	},
+	get_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
+	cancel_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
+	list_repo_changes: {
+		status: { flag: "status", enum: ["running", "succeeded", "no_changes", "failed", "cancelled"] },
+		limit: { flag: "limit", type: "num" },
+		audit_id: "audit",
+	},
+	list_github_app_repos: {},
+};
+
+const TERMINAL = new Set(["succeeded", "no_changes", "failed", "cancelled"]);
+
+function describe(run) {
+	const lines = [
+		`${run.id}  ${run.repo}@${run.baseBranch}  ${run.status} (${run.phase})  $${run.costUsd.toFixed(2)}`,
+	];
+	if (run.prUrl) lines.push(`  PR: ${run.prUrl}`);
+	if (run.errorCode) lines.push(`  Error (${run.errorCode}): ${run.errorDetail ?? ""}`);
+	if (run.summary) lines.push(...run.summary.split("\n").map((l) => `  ${l}`));
+	return lines.join("\n");
+}
+
+export async function cmdRepo(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "start":
+			return repoStart(rest);
+		case "status":
+			return repoStatus(rest);
+		case "fix-audit":
+			return repoFixAudit(rest);
+		case "sites":
+			return repoSites(rest);
+		case "set-site":
+			return repoSetSite(rest);
+		case "reset-site":
+			return repoResetSite(rest);
+		case "list":
+			return repoList(rest);
+		case "cancel":
+			return repoCancel(rest);
+		case "repos":
+			return repoRepos(rest);
+		default:
+			throw new CliError(
+				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, sites, set-site, reset-site, status, list, cancel, repos`
+			);
+	}
+}
+
+/** `--attach-url name=https://…` → `{ name, url }`. */
+function attachmentUrls(specs) {
+	return specs.map((spec) => {
+		const at = spec.indexOf("=");
+		if (at < 1) throw new CliError(`--attach-url must be name=https://… (got ${spec})`);
+		return { name: spec.slice(0, at), url: spec.slice(at + 1) };
+	});
+}
+
+/** Reserve an upload per --attach file, PUT the bytes, and return `{ name, upload_path }` for each. */
+async function uploadAttachments(ctx, paths) {
+	if (!paths.length) return [];
+	const names = paths.map((p) =>
+		basename(p)
+			.replace(/[^A-Za-z0-9._ -]/g, "-")
+			.replace(/^[^A-Za-z0-9]+/, "")
+	);
+	if (new Set(names).size !== names.length) throw new CliError("Two --attach files share a name; rename one.");
+	const bytes = paths.map((p) => {
+		try {
+			return readFileSync(p);
+		} catch (err) {
+			throw new CliError(`Could not read --attach ${p}: ${err.message}`);
+		}
+	});
+	const { uploads } = await ctx.client.callTool("create_repo_change_upload", { file_names: names });
+	for (const [i, slot] of uploads.entries()) {
+		const res = await fetch(slot.upload_url, {
+			method: "PUT",
+			headers: { "content-type": "application/octet-stream" },
+			body: bytes[i],
+		});
+		if (!res.ok) throw new CliError(`Uploading ${slot.name} failed (${res.status}).`);
+		ok(ctx, `Uploaded ${slot.name}`);
+	}
+	return uploads.map((slot) => ({ name: slot.name, upload_path: slot.path }));
+}
+
+async function repoStart(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, [
+		"repo",
+		"owner",
+		"name",
+		"branch",
+		"instructions",
+		"instructions-file",
+		"attach",
+		"attach-url",
+		"wait",
+	]);
+	const files = [
+		...(await uploadAttachments(ctx, flagList(flags.attach))),
+		...attachmentUrls(flagList(flags["attach-url"])),
+	];
+	const args = argsFromFlags(ARGS.start_repo_change, flags, ctx.positionals, { files });
+	if (!args.repo_owner || !args.repo_name) throw new CliError("Missing --repo owner/name");
+	if (!args.instructions) throw new CliError("Missing --instructions (or --instructions-file <path|->)");
+
+	const started = await client.callTool("start_repo_change", args);
+	ok(ctx, started.message);
+	if (!flags.wait) {
+		printResult(io, flags, started.run, describe);
+		return 0;
+	}
+	const { settled, value } = await followJob(
+		io,
+		async () => {
+			const polled = await client.callTool("get_repo_change", { run_id: started.run.id });
+			ok(ctx, `… ${polled.run.status} (${polled.run.phase})`);
+			return { done: TERMINAL.has(polled.run.status), value: polled.run };
+		},
+		{ intervalMs: 30000, ceilingMs: 60 * 60 * 1000 }
+	);
+	if (!settled) ok(ctx, `Still running; check later with: letterstory repo status ${started.run.id}`);
+	printResult(io, flags, value, describe);
+	return value.status === "failed" ? 1 : 0;
+}
+
+async function followRun(ctx, run) {
+	const { client, flags, io } = ctx;
+	const { settled, value } = await followJob(
+		io,
+		async () => {
+			const polled = await client.callTool("get_repo_change", { run_id: run.id });
+			ok(ctx, `… ${polled.run.status} (${polled.run.phase})`);
+			return { done: TERMINAL.has(polled.run.status), value: polled.run };
+		},
+		{ intervalMs: 30000, ceilingMs: 60 * 60 * 1000 }
+	);
+	if (!settled) ok(ctx, `Still running; check later with: letterstory repo status ${run.id}`);
+	printResult(io, flags, value, describe);
+	return value.status === "failed" ? 1 : 0;
+}
+
+/** `repo fix-audit --issue <type> [--audit <id>] [--wait]`: one audit issue → one PR, in the repo verified to build the site. */
+async function repoFixAudit(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["issue", "audit", "branch", "wait"]);
+	const result = await client.callTool(
+		"fix_audit_issue",
+		argsFromFlags(ARGS.fix_audit_issue, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	if (!flags.wait) {
+		printResult(io, flags, result.run, describe);
+		return 0;
+	}
+	return followRun(ctx, result.run);
+}
+
+/** `repo sites [--detect] [--force]`: which website each repo builds, and why. */
+async function repoSites(ctx) {
+	const { client, flags, io } = ctx;
+	const result = flags.detect
+		? await client.callTool("detect_repo_sites", argsFromFlags(ARGS.detect_repo_sites, flags))
+		: await client.callTool("list_repo_sites", argsFromFlags(ARGS.list_repo_sites, flags));
+	printResult(io, flags, result, (r) => {
+		const serving = r.sites.filter((s) => s.verdict === "serves");
+		const lines = serving.map((s) =>
+			s.decidedBy === "member"
+				? `${s.repo}  builds ${s.siteHost}  (set by a member)`
+				: `${s.repo}  builds ${s.siteHost}  (${Math.round(s.score * 100)}%: ${s.evidence.signals.join(", ")})`
+		);
+		if (r.failed?.length) lines.push(...r.failed.map((f) => `! ${f.repo}: ${f.error}`));
+		return lines.length ? lines.join("\n") : "No repo is verified to build any of this organization's sites yet.";
+	});
+	return 0;
+}
+
+/** `repo set-site --repo owner/name --site acme.com [--not]`: say which site a repo builds (or doesn't). */
+async function repoSetSite(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["repo", "owner", "name", "site", "not"]);
+	const result = await client.callTool("set_repo_site", argsFromFlags(ARGS.set_repo_site, flags));
+	ok(ctx, result.message);
+	printResult(io, flags, result.site);
+	return 0;
+}
+
+/** `repo reset-site --repo owner/name --site acme.com`: back to automatic detection. */
+async function repoResetSite(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["repo", "owner", "name", "site"]);
+	const result = await client.callTool("reset_repo_site", argsFromFlags(ARGS.reset_repo_site, flags));
+	ok(ctx, result.message);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function repoStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"get_repo_change",
+		argsFromFlags(ARGS.get_repo_change, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	printResult(io, flags, result.run, describe);
+	return 0;
+}
+
+async function repoList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"list_repo_changes",
+		argsFromFlags(ARGS.list_repo_changes, flags, ctx.positionals)
+	);
+	printResult(io, flags, result.runs, (runs) =>
+		runs.length ? runs.map(describe).join("\n") : "No repo changes yet."
+	);
+	return 0;
+}
+
+async function repoCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"cancel_repo_change",
+		argsFromFlags(ARGS.cancel_repo_change, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	printResult(io, flags, result.run, describe);
+	return 0;
+}
+
+async function repoRepos(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_github_app_repos", argsFromFlags(ARGS.list_github_app_repos, flags));
+	printResult(io, flags, result, (r) =>
+		r.repos.length
+			? r.repos.map((repo) => `${repo.fullName}  (default ${repo.defaultBranch})`).join("\n")
+			: r.message
+	);
+	return 0;
+}
+
+export { ARGS };

package/lib/commands.mjs

@@ -40,5 +40,6 @@ export * from "./commands/offerings.mjs";
 export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";
+export * from "./commands/repo.mjs";
 export * from "./commands/evals.mjs";
 export * from "./commands/visits.mjs";

package/lib/documents.mjs

@@ -61,6 +61,8 @@ export const DOCUMENT_FLAG_PAIRS = [
 	["text", "text-file"],
 	// An offering's (or the company's) manifesto is prose — a PDF or a .docx is fair game.
 	["manifesto", "manifesto-file"],
+	// A repo change's brief (repo.mjs `repo start`) — prose, so a .docx or PDF spec is fine.
+	["instructions", "instructions-file"],
 ];
 
 /**

package/package.json

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