@letterstory/cli 0.176.93 → 0.176.95

package/lib/cli.mjs

@@ -86,7 +86,7 @@ import {
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.93";
+export const VERSION = "0.176.95";
 
 /** 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;
@@ -563,6 +563,7 @@ Collections (the content engine as a primitive — one door, 'collection run'):
   collection run-status <run-id>                       Status, steps, constraints, verification
   collection runs [--collection <id>] [--status <s>] [--limit <n>]
   collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
+  collection start <run-id>                            Start a scheduled slot's writing now (it goes live at its slot)
   collection move <run-id> --date YYYY-MM-DD           Move a slot not yet written, or an approved written post, to another day
   collection cancel <run-id>
   collection inventory <id>                            Where every piece is; each finished draft's publish-on-its-own time
@@ -2031,15 +2032,17 @@ 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 (the Replicator: a website rebuilt as a native Next.js repo, page for page; free, within fair-use limits):
   replicate <https://site> [--max-pages <n>] [--refine-budget <usd>] [--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, preview link
+  replicate [list]                                     Your replications: stage, how closely each matches, preview link;
+                                                       the limits (in progress, pages this month, preview days)
   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] [--again] [--preview]
-                                                       Move it on now; --retry once blocked_on is done; --again replicates from the start;
-                                                       --preview deploys its staging link again
+  replicate advance <id> [--retry] [--again] [--preview] [--extend-preview <days>]
+                                                       Move it on now; --retry once blocked_on is done (checks the tag or TXT record);
+                                                       --again replicates from the start; --preview deploys its staging link again;
+                                                       --extend-preview keeps the preview up longer (Letter's team only)
   replicate archive <id>                               Stop it and take its preview down; 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):

package/lib/commands/collection.mjs

@@ -134,6 +134,9 @@ export const ARGS = {
 	cancel_collection_run: {
 		run_id: { positional: 0, label: "run-id", required: true },
 	},
+	start_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
 	reschedule_collection_run: {
 		run_id: { positional: 0, label: "run-id", required: true },
 		date: { flag: "date", required: true },
@@ -184,6 +187,8 @@ export async function cmdCollection(ctx) {
 			return collectionApprove(rest);
 		case "cancel":
 			return collectionCancel(rest);
+		case "start":
+			return collectionStart(rest);
 		case "move":
 		case "reschedule":
 			return collectionMove(rest);
@@ -197,7 +202,7 @@ export async function cmdCollection(ctx) {
 			return collectionMentions(rest);
 		default:
 			throw new CliError(
-				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, add, queue, headline, run-status, runs, approve, move, cancel, inventory, links, mentions`
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, add, queue, headline, run-status, runs, approve, start, move, cancel, inventory, links, mentions`
 			);
 	}
 }
@@ -395,6 +400,18 @@ async function collectionCancel(ctx) {
 	return 0;
 }
 
+// `collection start <run-id>` — a slot on the calendar starts writing now; it still goes live at its slot
+// (start_collection_run, the way a letterbase's writing automation starts its slot).
+async function collectionStart(ctx) {
+	const result = await ctx.client.callTool(
+		"start_collection_run",
+		argsFromFlags(ARGS.start_collection_run, ctx.flags, ctx.positionals)
+	);
+	ok(ctx, toolField(result, "started") ? "Started: it is being written." : "Not started yet: see its step.");
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
 // `collection move <run-id> --date YYYY-MM-DD` — a slot not yet written, or a written post
 // already approved, onto another day (reschedule_collection_run).
 async function collectionMove(ctx) {

package/lib/commands/replicate.mjs

@@ -1,6 +1,7 @@
 // `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
+// Who may use it is one switch in the app (lib/replicator/access.ts): until it opens, the tools answer
+// only a key an @letterstory.com person made. Free, within fair-use limits. 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.
@@ -9,7 +10,7 @@
 //   letterstory replicate list
 //   letterstory replicate show <id> [--failing]
 //   letterstory replicate attach <id> <repo-name> [--repo-owner <account>]
-//   letterstory replicate advance <id> [--retry] [--again] [--preview]
+//   letterstory replicate advance <id> [--retry] [--again] [--preview] [--extend-preview <days>]
 //   letterstory replicate archive <id>
 
 import { CliError } from "../client.mjs";
@@ -40,6 +41,7 @@ export const ARGS = {
 		retry: { flag: "retry", type: "bool" },
 		again: { flag: "again", type: "bool" },
 		preview: { flag: "preview", type: "bool" },
+		extend_preview_days: { flag: "extend-preview", type: "num" },
 	},
 	archive_replication: { replication_id: replicationId },
 };
@@ -81,7 +83,9 @@ export async function cmdReplicate(ctx) {
 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";
+		const limits = limitsLines(r.limits);
+		if (!r.replications?.length)
+			return ["No replications yet. Start one: replicate https://example.com", ...limits].join("\n");
 		return r.replications
 			.map(
 				(x) =>
@@ -91,17 +95,40 @@ async function replicationList(ctx) {
 							: ""
 					}${x.staging_url ? `  ${x.staging_url}` : ""}`
 			)
+			.concat(limits.length ? ["", ...limits] : [])
 			.join("\n");
 	});
 	return 0;
 }
 
+// The fair-use limits (replicating is free): in progress, pages this month, how long a preview stays up.
+function limitsLines(l) {
+	if (!l || l.exempt) return [];
+	const p = l.pages_this_month;
+	return [
+		`Limits  ${l.concurrent.used} of ${l.concurrent.max} in progress; ${p.used} of ${p.max} pages this month (resets ${p.resets_at.slice(0, 10)}); previews stay up ${l.preview_days} days`,
+	];
+}
+
+// What it used, in quantities (free: never a charge).
+function usageLine(u) {
+	if (!u) return [];
+	const parts = [
+		u.sandbox_minutes ? `${u.sandbox_minutes} sandbox min` : null,
+		u.pages_captured ? `${u.pages_captured} pages` : null,
+		u.preview_hours ? `${u.preview_hours} preview hours` : null,
+		u.media_bytes ? `${(u.media_bytes / 1e6).toFixed(1)} MB media` : null,
+	].filter(Boolean);
+	return parts.length ? [`  Used    ${parts.join(", ")} (free)`] : [];
+}
+
 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}`] : []),
 		...previewLines(x),
+		...usageLine(x.usage),
 		...(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)})`,
@@ -155,9 +182,11 @@ function motionLines(m) {
 
 // The staging link: the replica live on a Letter domain, to share before (or without) a repo.
 function previewLines(x) {
+	if (x.staging_state === "queued" || x.staging_state === "expired")
+		return [`  Preview ${x.staging_note ?? x.staging_state}`];
 	if (x.staging_url)
 		return [
-			`  Preview ${x.staging_url}${x.staging_state === "deploying" || x.staging_state === "pending" ? " (redeploying)" : ""}`,
+			`  Preview ${x.staging_url}${x.staging_state === "deploying" || x.staging_state === "pending" ? " (redeploying)" : ""}${x.staging_expires_at ? ` (online until ${x.staging_expires_at.slice(0, 10)})` : ""}`,
 			...(x.staging_state === "failed" && x.staging_error
 				? [`  Preview redeploy failed: ${x.staging_error}`]
 				: []),
@@ -173,7 +202,11 @@ function previewLines(x) {
 }
 
 function replicationShow(ctx, result) {
-	printResult(ctx.io, ctx.flags, result, (r) => headline(r.replication).join("\n"));
+	printResult(ctx.io, ctx.flags, result, (r) =>
+		[...headline(r.replication), ...(r.notice ? [`  Note    ${r.notice}`] : []), ...limitsLines(r.limits)].join(
+			"\n"
+		)
+	);
 	return 0;
 }
 
@@ -181,12 +214,20 @@ function replicationDetail(ctx, result) {
 	printResult(ctx.io, ctx.flags, result, (r) => {
 		const lines = headline(r.replication);
 		// Waiting for its domain to be verified: the tag for the homepage (then advance --retry checks it).
-		if (r.domain_verification)
+		if (r.domain_verification) {
 			lines.push(
 				"",
 				`Add this tag to the <head> of ${r.domain_verification.host}'s homepage:`,
 				r.domain_verification.tag
 			);
+			if (r.domain_verification.dns)
+				lines.push(
+					"",
+					"Or add this TXT record to its DNS:",
+					`  Name   ${r.domain_verification.dns.name}`,
+					`  Value  ${r.domain_verification.dns.value}`
+				);
+		}
 		if (r.pages?.length) {
 			lines.push("", "Pages:");
 			for (const p of r.pages) {

package/package.json

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