@letterstory/cli 0.98.2 → 0.98.4

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.2";
+export const VERSION = "0.98.4";
 
 // 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/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/targets.mjs

@@ -8,7 +8,7 @@
 // routes and staff Fleet do.
 
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
+import { flagStr, flagNum, flagList, printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
 
 const STATUSES = ["active", "inactive", "achieved", "retired"];
 const PRIORITIES = ["high", "normal", "low"];
@@ -25,8 +25,9 @@ function readOffering(flags) {
 }
 const offering = { value: readOffering };
 
-// `--priority high|normal|low|default`: how much the target's questions count in share of
-// voice (high = 3 votes, normal = 2, low = 1); default = back to high, a target's default.
+// `--priority high|normal|low|default`: how often the target's ground is written across target
+// slots, and how much its questions count in share of voice (high = 3, normal = 2, low = 1);
+// default = back to high, a target's default.
 function readPriority(flags) {
 	const v = flagStr(flags.priority);
 	if (v === undefined) {
@@ -55,6 +56,8 @@ export const ARGS = {
 		mention_framing: "framing",
 		offering_id: offering,
 		priority,
+		// `--stance <text>`, repeatable: one point of view per flag.
+		stances: { flag: "stance", type: "list" },
 	},
 	update_ranking_target: {
 		target_id: { positional: 0, label: "target-id", required: true },
@@ -67,6 +70,14 @@ export const ARGS = {
 		offering_id: offering,
 		position: { flag: "position", type: "num" },
 		priority,
+		// `--stance <text>` (repeatable) REPLACES the list; `--clear-stances` empties it.
+		stances: {
+			value: (flags) => {
+				if (flags["clear-stances"] === true) return [];
+				const list = flagList(flags.stance);
+				return list.length ? list : undefined;
+			},
+		},
 	},
 	set_ranking_target_cap: {
 		offering_id: {
@@ -117,8 +128,10 @@ export const ARGS = {
 const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|subqueries|subquery>
   targets list [--offering <offering-id|company>]
   targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
+                 [--stance <s>]...                       points of view held on this target's ground only
   targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
                  [--position <n>] [--state active|inactive|achieved|retired] [--priority high|normal|low|default]
+                 [--stance <s>]... | --clear-stances      replaces the target's stances
   targets activate <target-id>
   targets deactivate <target-id>
   targets cap <offering-id|company> <n|default>
@@ -165,7 +178,8 @@ function formatScope(s) {
 function formatTarget(t) {
 	const framing = t.mention_framing ? ` — as ${t.mention_framing}` : "";
 	const prio = t.priority ? `  (${t.priority} priority)` : "";
-	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}${prio}`;
+	const stances = (t.stances ?? []).map((s) => `\n      · ${s}`).join("");
+	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}${prio}${stances}`;
 }
 
 // Targets grouped under their scope, each headed by its cap and usage. A target on an
@@ -223,7 +237,7 @@ async function update(ctx, flags) {
 	const args = argsFromFlags(ARGS.update_ranking_target, flags, positionals);
 	if (Object.keys(args).length === 1) {
 		throw new CliError(
-			"Nothing to update — pass --phrase, --framing, --clear-framing, --offering, --position, --state or --priority."
+			"Nothing to update — pass --phrase, --framing, --clear-framing, --stance, --clear-stances, --offering, --position, --state or --priority."
 		);
 	}
 	const result = await client.callTool("update_ranking_target", args);
@@ -233,7 +247,14 @@ async function update(ctx, flags) {
 }
 
 async function targetsUpdate(ctx) {
-	refuseUnknownFlags(ctx, ARGS.update_ranking_target, ["framing", "clear-framing", "offering", "priority"]);
+	refuseUnknownFlags(ctx, ARGS.update_ranking_target, [
+		"framing",
+		"clear-framing",
+		"stance",
+		"clear-stances",
+		"offering",
+		"priority",
+	]);
 	return update(ctx, ctx.flags);
 }
 

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.2",
+	"version": "0.98.4",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",