@letterstory/cli 0.176.43 → 0.176.44

package/lib/cli.mjs

@@ -78,12 +78,13 @@ import {
 	cmdVary,
 	cmdDomains,
 	cmdBench,
+	cmdReplicate,
 	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.43";
+export const VERSION = "0.176.44";
 
 /** 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;
@@ -109,6 +110,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"spec-changed",
 	// bench update: remove the README's disclosure.
 	"no-disclosure",
+	// replicate show: list only the pages below the bar.
+	"failing",
 	// sim create / resample / sample-key: keep the customer's sample key, or delete it now.
 	"keep-key",
 	"delete-key",
@@ -1915,6 +1918,15 @@ Bench (Benches: open-source benchmarks on their own domains, kept running; @lett
   bench cite <id>                                      The reference line a post cites
   bench replicate <id>                                 REPLICATE.md: how an agent reproduces the results
 
+Replicate (the Replicator: a website rebuilt as a native Next.js repo, page for page; @letterstory.com only):
+  replicate <https://site> [--max-pages <n>] [--repo-name <r>] [--repo-owner <o>]
+                                                       Capture every page, rebuild it, compare it pixel by pixel
+  replicate [list]                                     Your replications: stage, how closely each matches
+  replicate show <id> [--failing]                      Pages with their routes and pixel match; collections; events
+  replicate attach <id> <repo-name> [--repo-owner <o>] The repo to commit it into (yours; Letter never creates it)
+  replicate advance <id> [--retry]                     Move it on now; --retry once blocked_on is done
+  replicate archive <id>                               Stop it; the project stays in storage and in the repo
+
 Evals (how the pipeline is doing on your posts, and the regression cases captured from them):
   evals scoreboard [--collection <id>] [--days N]      Every measure by stage: posts, failing, rate
   evals cases [--status open|guarding|proposed|retired|rejected] [--stage research|brief|links|mentions|accuracy|pipeline|shred]
@@ -2021,6 +2033,7 @@ const CLIENT_COMMANDS = {
 	vary: cmdVary,
 	domains: cmdDomains,
 	bench: cmdBench,
+	replicate: cmdReplicate,
 	deploy: cmdDeploy,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,

package/lib/commands/replicate.mjs

@@ -0,0 +1,138 @@
+// `replicate` — the Replicator from a terminal (docs/architecture/replicator.md): a website rebuilt
+// as a native Next.js repo, page for page, and committed to a repo on your organization's GitHub.
+// Staff only: the tools answer only a key an @letterstory.com person made. Thin wrappers over the
+// replicator tools (create_replication, list_replications, get_replication,
+// attach_replication_repo, advance_replication, archive_replication), the same lib functions the
+// app calls.
+//
+//   letterstory replicate https://example.com [--max-pages 300] [--repo-name example-site] [--repo-owner <account>]
+//   letterstory replicate list
+//   letterstory replicate show <id> [--failing]
+//   letterstory replicate attach <id> <repo-name> [--repo-owner <account>]
+//   letterstory replicate advance <id> [--retry]
+//   letterstory replicate archive <id>
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, printResult, refuseUnknownFlags } from "./shared.mjs";
+
+const replicationId = { positional: 0, label: "replication-id", required: true };
+
+export const ARGS = {
+	create_replication: {
+		url: { positional: 0, label: "url", required: true },
+		max_pages: { flag: "max-pages", type: "num" },
+		repo_name: "repo-name",
+		repo_owner: "repo-owner",
+	},
+	list_replications: {},
+	get_replication: {
+		replication_id: replicationId,
+		pages: { value: (flags) => (flags.failing === true ? "failing" : undefined) },
+	},
+	attach_replication_repo: {
+		replication_id: replicationId,
+		repo_name: { positional: 1, label: "repo-name", required: true },
+		repo_owner: "repo-owner",
+	},
+	advance_replication: { replication_id: replicationId, retry: { flag: "retry", type: "bool" } },
+	archive_replication: { replication_id: replicationId },
+};
+
+function call(ctx, tool) {
+	return ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+}
+
+const pct = (x) => `${(x * 100).toFixed(2)}%`;
+
+export async function cmdReplicate(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	if (sub && /^https?:\/\//i.test(sub)) {
+		refuseUnknownFlags(ctx, ARGS.create_replication, []);
+		return replicationShow(ctx, await call(ctx, "create_replication"));
+	}
+	switch (sub) {
+		case undefined:
+		case "list":
+		case "ls":
+			return replicationList(rest);
+		case "show":
+			refuseUnknownFlags(rest, ARGS.get_replication, ["failing"]);
+			return replicationDetail(rest, await call(rest, "get_replication"));
+		case "attach":
+			refuseUnknownFlags(rest, ARGS.attach_replication_repo, []);
+			return replicationShow(rest, await call(rest, "attach_replication_repo"));
+		case "advance":
+			refuseUnknownFlags(rest, ARGS.advance_replication, []);
+			return replicationShow(rest, await call(rest, "advance_replication"));
+		case "archive":
+			return replicationShow(rest, await call(rest, "archive_replication"));
+		default:
+			throw new CliError("Usage: replicate <https://site> | replicate [list|show|attach|advance|archive]");
+	}
+}
+
+async function replicationList(ctx) {
+	const result = await call(ctx, "list_replications");
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		if (!r.replications?.length) return "No replications yet. Start one: replicate https://example.com";
+		return r.replications
+			.map(
+				(x) =>
+					`${x.id}  ${x.host.padEnd(28)} ${(x.blocked_on ? "blocked" : x.status).padEnd(10)} ${x.stage.padEnd(10)} ${
+						x.summary
+							? `${x.summary.passing}/${x.summary.replicated} pages match, mean ${pct(x.summary.meanPixel)}`
+							: ""
+					}`
+			)
+			.join("\n");
+	});
+	return 0;
+}
+
+function headline(x) {
+	return [
+		`${x.host} — ${x.status}, stage ${x.stage}`,
+		...(x.blocked_on ? [`  Blocked: ${x.blocked_on}`, `  Then: replicate advance ${x.id} --retry`] : []),
+		...(x.stage_note && !x.blocked_on ? [`  ${x.stage_note}`] : []),
+		...(x.summary
+			? [
+					`  ${x.summary.replicated} of ${x.summary.pages} pages replicated; ${x.summary.passing} match the original at every width (mean ${pct(x.summary.meanPixel)})`,
+				]
+			: []),
+		...x.collections.map(
+			(c) =>
+				`  Collection ${c.pattern}: ${c.items} items (${c.markdown_bodies} as Markdown) in ${c.content_path_template}`
+		),
+		...(x.repo_url
+			? [`  Repo    ${x.repo_url}${x.commit_sha ? ` @ ${x.commit_sha.slice(0, 7)}` : ""}`]
+			: x.repo_name
+				? [`  Repo    ${x.repo_owner ? `${x.repo_owner}/` : ""}${x.repo_name} (attached)`]
+				: []),
+		...(x.stage === "ready" && !x.repo_name ? [`  Ready: replicate attach ${x.id} <repo-name> to commit it`] : []),
+	];
+}
+
+function replicationShow(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => headline(r.replication).join("\n"));
+	return 0;
+}
+
+function replicationDetail(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const lines = headline(r.replication);
+		if (r.pages?.length) {
+			lines.push("", "Pages:");
+			for (const p of r.pages)
+				lines.push(
+					`  ${p.passing ? "✓" : "✗"} ${p.path.padEnd(48)} ${p.scores.map((s) => `${s.viewport} ${pct(s.pixel)}`).join("  ")}${p.error ? `  (${p.error})` : ""}`
+				);
+		}
+		if (r.dropped?.length)
+			lines.push("", `The site's own code left out (needs its builder's runtime): ${r.dropped.length}`);
+		if (r.events?.length)
+			lines.push("", "Recent:", ...r.events.slice(0, 8).map((e) => `  ${e.created_at}  ${e.message}`));
+		return lines.join("\n");
+	});
+	return 0;
+}

package/lib/commands.mjs

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

package/package.json

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