@letterstory/cli 0.102.3 → 0.103.0

package/lib/cli.mjs

@@ -60,15 +60,16 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.102.3";
+export const VERSION = "0.103.0";
 
 // 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
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
 	"json",
-	// site tree: include children a fold-by-default family would hide.
+	// site tree: include children a fold-by-default family would hide; items over the whole subtree.
 	"unfold",
+	"subtree",
 	// site map: do not start an audit for a host that has none.
 	"no-audit",
 	// site refresh / observe: the loop's switches.
@@ -1169,14 +1170,20 @@ The Site (one model of your whole marketing site, keyed by host and path):
 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 branches --repo owner/name                      Branches a change can start from (default first)
+  repo suggestions                                     Fixes found and not acted on yet, and how to start each
+  repo settings [--action build|build_pr|slack] [--branch <name>|none] [--slack-agent <name|U…>|none]
+                                                       The org's defaults for every fix: build (preview first),
+                                                       build_pr, or slack (post it for your own agent, tagging
+                                                       --slack-agent), and the branch changes go to
   repo start --repo <owner/name> --instructions <text>|--instructions-file <path|->
-             [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]... [--preview] [--wait]
+             [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]...
+             [--action build|build_pr|slack] [--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>] [--preview] [--wait]
-                                                       One PR fixing a site-audit issue on every affected page,
+  repo fix-audit --issue <issue-type>... [--audit <id>] [--branch <base>] [--action build|build_pr|slack] [--wait]
+                                                       One PR fixing site-audit issues (repeat --issue to bundle) on every affected page,
                                                        in the repo verified to build the site
-  repo install-letterprove --repo <owner/name> [--branch <base>] [--wait]
+  repo install-letterprove --repo <owner/name> [--branch <base>] [--action build|build_pr|slack] [--wait]
                                                        One PR adding Letterprove's script and identify calls
                                                        (pick the repo where users sign in)
   repo sites [--detect [--force]]                      Which website each repo builds, and the evidence

package/lib/commands/repo.mjs

@@ -5,6 +5,8 @@
 //   repo publish → publish_repo_change (Make PR on a preview)
 //   repo repos   → list_github_app_repos  repo branches → list_repo_branches
 //   repo install-letterprove → letterprove_open_install_pr
+//   repo suggestions → list_suggested_fixes
+//   repo settings → get_repo_change_settings, or set_repo_change_settings with --action / --branch
 
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
@@ -29,6 +31,13 @@ function splitRepo(flags) {
 	return { owner, name };
 }
 
+function issueList(flags) {
+	return flagList(flags.issue)
+		.flatMap((v) => v.split(","))
+		.map((v) => v.trim())
+		.filter(Boolean);
+}
+
 const ARGS = {
 	start_repo_change: {
 		repo_owner: { value: (flags) => splitRepo(flags).owner },
@@ -38,6 +47,7 @@ const ARGS = {
 		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) },
+		action: { flag: "action", enum: ["build", "build_pr", "slack"] },
 		preview: { flag: "preview", type: "bool" },
 	},
 	create_repo_change_upload: { file_names: { internal: "the basenames of the --attach files" } },
@@ -55,21 +65,34 @@ const ARGS = {
 		site_host: { flag: "site", required: true },
 	},
 	fix_audit_issue: {
-		issue_type: { flag: "issue", required: true },
+		// --issue <type>, repeatable or comma-separated: several go into one PR (issue_types).
+		issue_type: { value: (flags) => (issueList(flags).length === 1 ? issueList(flags)[0] : undefined) },
+		issue_types: { value: (flags) => (issueList(flags).length > 1 ? issueList(flags) : undefined) },
 		audit_id: "audit",
 		base_branch: "branch",
+		action: { flag: "action", enum: ["build", "build_pr", "slack"] },
 		preview: { flag: "preview", type: "bool" },
 	},
 	letterprove_open_install_pr: {
 		repo_owner: { value: (flags) => splitRepo(flags).owner },
 		repo_name: { value: (flags) => splitRepo(flags).name },
 		base_branch: "branch",
+		action: { flag: "action", enum: ["build", "build_pr", "slack"] },
+	},
+	get_repo_change_settings: {},
+	list_suggested_fixes: {},
+	set_repo_change_settings: {
+		default_action: { flag: "action", enum: ["build", "build_pr", "slack"] },
+		// --branch <name>, or --branch none for each repo's own default.
+		default_branch: { value: (flags) => (flags.branch === "none" ? null : flagStr(flags.branch)) },
+		// --slack-agent Devin (or a U… member id), or --slack-agent none to tag nobody.
+		slack_agent: { value: (flags) => (flags["slack-agent"] === "none" ? null : flagStr(flags["slack-agent"])) },
 	},
 	get_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	cancel_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	publish_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	list_repo_changes: {
-		status: { flag: "status", enum: ["running", "succeeded", "no_changes", "failed", "cancelled"] },
+		status: { flag: "status", enum: ["running", "succeeded", "no_changes", "failed", "cancelled", "sent"] },
 		limit: { flag: "limit", type: "num" },
 		audit_id: "audit",
 		source_kind: { flag: "source", enum: ["site_audit_issue", "site_quick_check", "letterprove_install"] },
@@ -124,9 +147,13 @@ export async function cmdRepo(ctx) {
 			return repoRepos(rest);
 		case "branches":
 			return repoBranches(rest);
+		case "settings":
+			return repoSettings(rest);
+		case "suggestions":
+			return repoSuggestions(rest);
 		default:
 			throw new CliError(
-				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, install-letterprove, sites, set-site, reset-site, status, list, publish, cancel, repos, branches`
+				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, install-letterprove, sites, set-site, reset-site, status, list, publish, cancel, repos, branches, settings, suggestions`
 			);
 	}
 }
@@ -180,6 +207,7 @@ async function repoStart(ctx) {
 		"instructions-file",
 		"attach",
 		"attach-url",
+		"action",
 		"preview",
 		"wait",
 	]);
@@ -235,7 +263,9 @@ async function followRun(ctx, run) {
 /** `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", "preview", "wait"]);
+	refuseUnknownFlags(ctx, {}, ["issue", "audit", "branch", "action", "preview", "wait"]);
+	if (issueList(flags).length === 0)
+		throw new CliError("--issue <issue-type> is required (repeat it to fix several in one PR)");
 	const result = await client.callTool(
 		"fix_audit_issue",
 		argsFromFlags(ARGS.fix_audit_issue, flags, ctx.positionals)
@@ -251,7 +281,7 @@ async function repoFixAudit(ctx) {
 /** `repo install-letterprove --repo owner/name [--branch b] [--wait]`: Letterprove's script + identify calls → one PR. */
 async function repoInstallLetterprove(ctx) {
 	const { client, flags, io } = ctx;
-	refuseUnknownFlags(ctx, {}, ["repo", "owner", "name", "branch", "wait"]);
+	refuseUnknownFlags(ctx, {}, ["repo", "owner", "name", "branch", "action", "wait"]);
 	const result = await client.callTool(
 		"letterprove_open_install_pr",
 		argsFromFlags(ARGS.letterprove_open_install_pr, flags, ctx.positionals)
@@ -371,4 +401,44 @@ async function repoBranches(ctx) {
 	return 0;
 }
 
+/**
+ * `repo settings` shows the org's defaults; `--action build|build_pr` and/or `--branch <name>`
+ * (`--branch none`: each repo's own default) change them.
+ */
+async function repoSettings(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["action", "branch", "slack-agent"]);
+	const setting = flags.action !== undefined || flags.branch !== undefined || flags["slack-agent"] !== undefined;
+	const result = setting
+		? await client.callTool("set_repo_change_settings", argsFromFlags(ARGS.set_repo_change_settings, flags))
+		: await client.callTool("get_repo_change_settings", {});
+	ok(ctx, result.message);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `repo suggestions`: fixes found and not acted on yet, and the command that starts each. */
+async function repoSuggestions(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, []);
+	const result = await client.callTool("list_suggested_fixes", {});
+	printResult(io, flags, result, (r) =>
+		r.suggestions.length === 0
+			? "Nothing to fix right now."
+			: r.suggestions
+					.map((s) => {
+						const where = s.repo ? `${s.repo} → ${s.siteHost}` : `${s.siteHost} (pick a repo)`;
+						const start =
+							s.start.tool === "fix_audit_issue"
+								? `letterstory repo fix-audit --audit ${s.start.args.audit_id} --issue ${s.start.args.issue_type}`
+								: s.start.args
+									? `letterstory repo install-letterprove --repo ${s.start.args.repo_owner}/${s.start.args.repo_name}`
+									: "letterstory repo install-letterprove --repo <owner/name>";
+						return `[${s.severity}] ${s.title}  ${where}\n  ${start}`;
+					})
+					.join("\n")
+	);
+	return 0;
+}
+
 export { ARGS };

package/lib/commands/site.mjs

@@ -6,7 +6,7 @@
 //   site dismiss <host> <id> → dismiss_site_observation
 //   site families <host>     → list_site_families       site decide-family <id>    → decide_site_family
 //   site proposals <host>    → list_site_proposals      site propose <host>        → create_site_proposal
-//   site decide <proposal>   → decide_site_proposal
+//   site decide <proposal>   → decide_site_proposal    site fix <host> <id>…     → fix_site_observations
 
 import { CliError } from "../client.mjs";
 import { argsFromFlags, flagList, flagStr, ok, printResult, readTextInput, refuseUnknownFlags } from "./shared.mjs";
@@ -55,6 +55,7 @@ const ARGS = {
 		path: { positional: 1, label: "path" },
 		depth: { flag: "depth", type: "num" },
 		unfold: { flag: "unfold", type: "bool" },
+		subtree: { flag: "subtree", type: "bool" },
 	},
 	get_site_page: {
 		host: { positional: 0, required: true, label: "host" },
@@ -116,6 +117,18 @@ const ARGS = {
 		decision: { flag: "decision", required: true, enum: ["accept", "dismiss"] },
 		reason: "reason",
 	},
+	fix_site_observations: {
+		host: { positional: 0, required: true, label: "host" },
+		// Every positional after the host, plus --observation <id> (repeatable).
+		observation_ids: {
+			value: (flags, positionals) => {
+				const ids = [...positionals.slice(1), ...flagList(flags.observation)];
+				return ids.length ? ids : undefined;
+			},
+		},
+		base_branch: { flag: "base-branch" },
+		preview: { flag: "preview", type: "bool" },
+	},
 };
 
 export async function cmdSite(ctx) {
@@ -150,9 +163,11 @@ export async function cmdSite(ctx) {
 			return sitePropose(rest);
 		case "decide":
 			return siteDecide(rest);
+		case "fix":
+			return siteFix(rest);
 		default:
 			throw new CliError(
-				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, refresh, unmap, tree, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide`
+				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, refresh, unmap, tree, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide, fix`
 			);
 	}
 }
@@ -373,4 +388,21 @@ async function siteDecide(ctx) {
 	return 0;
 }
 
+async function siteFix(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.fix_site_observations, ["observation"]);
+	const args = argsFromFlags(ARGS.fix_site_observations, flags, ctx.positionals);
+	if (!args.observation_ids)
+		throw new CliError("Give at least one observation id: site fix <host> <id>… (or --observation <id>)");
+	const result = await client.callTool("fix_site_observations", args);
+	ok(ctx, result.message);
+	printResult(io, flags, result, (r) => {
+		const lines = [`${r.run.id}  ${r.run.repo}  [${r.run.status}]${r.reused ? "  (already running)" : ""}`];
+		for (const id of r.fixing) lines.push(`  fixing  ${id}`);
+		for (const s of r.skipped) lines.push(`  skipped ${s.id}  ${s.reason}`);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
 export { ARGS };

package/package.json

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