@letterstory/cli 0.4.0 → 0.4.1

package/README.md

@@ -236,6 +236,25 @@ letterstory kernel status <kernel-job-id>
 `phantom-job create --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
 end to end, with `phantom-job status <job-id>` to follow it.
 
+## Cover images
+
+Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`
+fans one headline out across up to four models and hands back a preview per model;
+`select` commits the one you want:
+
+```bash
+letterstory covers models                          # image models connected to this org
+letterstory covers variants --article <uuid> --model bloom --model openai
+letterstory covers select --article <uuid> --url <variant-url> --provider bloom
+
+# …or skip the comparison and let the server pick, using the collection's cover template:
+letterstory covers generate <article-id> [--regenerate] [--stock-only]
+```
+
+`--ref-url <url>` (repeatable) conditions the look on existing images — pair it with
+`extract_blog_reference_images` to match a site you're mirroring. Each variant costs one
+image generation, which is why the fan-out is capped at four models.
+
 ## Insights
 
 Search Console performance, network-wide, per post, or top posts:

package/lib/cli.mjs

@@ -27,12 +27,13 @@ import {
 	cmdOnboarding,
 	cmdInsights,
 	cmdResearch,
+	cmdCovers,
 	cmdKernel,
 	cmdPhantomJob,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.4.0";
+export const VERSION = "0.4.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -50,6 +51,13 @@ const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
+	// `covers generate <id> --regenerate` and `research start --gate --article <id>`
+	// both put a value-less flag next to a value: without these entries the parser
+	// hands the following token to the flag and the real argument disappears.
+	"regenerate",
+	"stock-only",
+	"gate",
+	"skip",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -198,6 +206,15 @@ Research agent (deep research -> outline written into the post):
                                                         Answer the --gate pause
   research cancel --article <uuid>                      Cancel a run in flight
 
+Cover images (which image model draws the post's cover):
+  covers models                                        Image models connected right now
+  covers variants --article <uuid> [--model <id> …] [--ref-url <url> …]
+                                                        One preview per model (max 4)
+  covers select --article <uuid> --url <url> --provider <p> [--model <id>]
+                                                        Commit a previewed variant
+  covers generate <article-id> [--regenerate] [--stock-only]
+                                                        Single-shot mint, default provider
+
 Writing kernels (kernels write the draft; they do not research — run research first):
   kernel list                                          List available writing kernels
   kernel run --article <uuid> --kernel <uuid> [--brief <text>|--brief-file <path>]
@@ -266,6 +283,7 @@ const CLIENT_COMMANDS = {
 	onboarding: cmdOnboarding,
 	insights: cmdInsights,
 	research: cmdResearch,
+	covers: cmdCovers,
 	kernel: cmdKernel,
 	"phantom-job": cmdPhantomJob,
 };

package/lib/commands/covers.mjs

@@ -0,0 +1,89 @@
+// `covers` — a post's cover image, including WHICH image model draws it. `models`
+// lists what's connected, `variants` fans a headline out across models and returns a
+// preview per model, `select` commits the one you want, and `generate` is the
+// single-shot headless mint (collection's template + the server's default provider).
+// Each variant costs one image generation, so the fan-out is capped at 4 models.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagBool, flagList, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdCovers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "models":
+			return coverModels(rest);
+		case "variants":
+		case "compare":
+			return coverVariants(rest);
+		case "select":
+		case "pick":
+			return coverSelect(rest);
+		case "generate":
+			return coverGenerate(rest);
+		default:
+			throw new CliError(
+				`Unknown covers subcommand: ${sub ?? "(none)"}. Try: models, variants, select, generate`
+			);
+	}
+}
+
+async function coverModels(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_image_models", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverVariants(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const modelIds = flagList(flags.model);
+	const refs = flagList(flags["ref-url"]);
+	const args = compact({
+		article_id: article,
+		model_ids: modelIds.length ? modelIds : undefined,
+		reference_image_urls: refs.length ? refs : undefined,
+	});
+	const result = await client.callTool("generate_cover_variants", args);
+	const first = (result?.variants ?? []).find((v) => v.url);
+	ok(
+		ctx,
+		first
+			? `Generated ${result.variants.length} variant(s). Commit one with: covers select --article ${article} --url <url> --provider <provider>`
+			: "No variant produced an image — see the per-model errors below."
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverSelect(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const args = compact({
+		article_id: article,
+		image_url: requireFlag(flags, "url"),
+		provider: requireFlag(flags, "provider"),
+		model: flagStr(flags.model),
+	});
+	const result = await client.callTool("select_cover_variant", args);
+	ok(ctx, "Cover set on the post.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverGenerate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	// `covers generate <article-id>` reads naturally, but --article keeps it
+	// consistent with every other post-scoped command; accept both.
+	const article = flagStr(flags.article) ?? requirePositional(positionals, 0, "article-id");
+	const args = compact({
+		article_id: article,
+		regenerate: flagBool(flags.regenerate) ? true : undefined,
+		stock_only: flagBool(flags["stock-only"]) ? true : undefined,
+	});
+	const result = await client.callTool("generate_article_cover", args);
+	ok(ctx, result?.generated ? "Cover generated and attached." : `No cover generated: ${result?.reason ?? "unknown"}`);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -15,6 +15,7 @@ export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/insights.mjs";
+export * from "./commands/covers.mjs";
 export * from "./commands/research.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";

package/package.json

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