@letterstory/cli 0.82.4 → 0.83.0

package/lib/cli.mjs

@@ -57,7 +57,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.82.4";
+export const VERSION = "0.83.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
@@ -333,16 +333,20 @@ Collections:
   collections autopen <id> [--template <key>|none] [--kernel-family <name>|org]
                            [--mention off|subtle|woven] [--outline-depth barebones|fleshed_out]
                            [--direction-gate true|false] [--auto-start true|false]
-                           [--prefer <site> …|none]
+                           [--prefer <site> …|none] [--client-one-in <n>]
       The Auto-Pen settings the app's panel writes. --template binds a content
       template (from 'templates list') as this collection's default, which is how
       a template you author here actually gets used. A patch: unset flags are
       left alone. --prefer REPLACES the preferred sources: SITES research
       searches for every post's topic and reaches for first when a figure fits
       (a URL is saved as its site) — your own site included; 'none' clears them.
-  collections cite-preferred <id> [--limit <n>] [--dry-run]
-      Bring published posts up to the preferred sources: each eligible post gets
-      at most one preferred figure, linked on the figure, then republishes.
+  collections preview-preferred <id>
+      Step 1: check every published post with a Sources list against the
+      preferred sites — dry, nothing written. Proposals are judged by fit.
+  collections preferred-preview <id>
+      Step 2: the proposals ranked, what the ceiling chooses, and the 1-in-N.
+  collections cite-preferred <id>
+      Step 3: apply exactly the chosen sentences, then republish.
 
 Authors (the per-collection author bank — recurring bylines):
   authors list <collection-id>                        List the bank + byline distribution

package/lib/commands/collections.mjs

@@ -47,10 +47,14 @@ export const ARGS = {
 		regenerate_topic_map: { value: (flags) => (flags["no-topic-map"] === undefined ? undefined : false) },
 		stock_headlines: { value: (flags) => (flags["no-headlines"] === undefined ? undefined : false) },
 	},
+	preview_preferred_sources: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	get_preferred_sources_preview: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
 	cite_preferred_sources: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
-		limit: { flag: "limit", type: "num" },
-		dry_run: { value: (flags) => (flags["dry-run"] === true ? true : undefined) },
 	},
 	update_auto_pen_config: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
@@ -76,6 +80,8 @@ export const ARGS = {
 		auto_start_on_curate: stringBool("auto-start"),
 		// Replaces the collection's preferred sources; `--prefer none` clears them.
 		preferred_sources: { value: (flags) => preferredSourcesFlag(flags.prefer) },
+		// The ceiling on the client's own site: at most one in N published posts cites it.
+		client_one_in: { flag: "client-one-in", type: "num" },
 	},
 };
 
@@ -106,11 +112,15 @@ export async function cmdCollections(ctx) {
 			return collectionsAutoPen(rest);
 		case "activate":
 			return collectionsActivate(rest);
+		case "preview-preferred":
+			return collectionsPreviewPreferred(rest);
+		case "preferred-preview":
+			return collectionsReadPreferredPreview(rest);
 		case "cite-preferred":
 			return collectionsCitePreferred(rest);
 		default:
 			throw new CliError(
-				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen, activate, cite-preferred`
+				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen, activate, preview-preferred, preferred-preview, cite-preferred`
 			);
 	}
 }
@@ -139,10 +149,36 @@ async function collectionsActivate(ctx) {
 }
 
 /**
- * `collections cite-preferred <id> [--limit <n>] [--dry-run]` — bring the collection's published
- * posts up to its preferred sources: each eligible post places at most one preferred figure and
- * republishes. The same function as the app's "Apply to published posts".
+ * `collections preview-preferred <id>` — step 1: queue a dry proposal per eligible published post
+ * (nothing is written to a post). The same preview as the app's "Preview published posts".
  */
+async function collectionsPreviewPreferred(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.preview_preferred_sources, flags, positionals);
+	const result = await client.callTool("preview_preferred_sources", args);
+	ok(
+		ctx,
+		`Queued ${result?.queued ?? 0} post${result?.queued === 1 ? "" : "s"} for a proposal. Read it with \`collections preferred-preview ${args.collection_id}\`.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `collections preferred-preview <id>` — step 2: the latest preview, ranked, and the 1-in-N it projects. */
+async function collectionsReadPreferredPreview(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.get_preferred_sources_preview, flags, positionals);
+	const r = await client.callTool("get_preferred_sources_preview", args);
+	const oneIn = r?.projected?.one_in ? `1 in ${r.projected.one_in}` : "none";
+	ok(
+		ctx,
+		`Preview ${r?.status}: ${r?.checked ?? 0}/${r?.total ?? 0} checked; ${r?.chosen?.length ?? 0} chosen, ${r?.held_by_ceiling?.length ?? 0} held by the ceiling, ${r?.below_bar?.length ?? 0} below the bar. Client cited in ${r?.projected?.citing_client ?? 0} of ${r?.projected?.of ?? 0} (${oneIn}).`
+	);
+	printResult(io, flags, r);
+	return 0;
+}
+
+/** `collections cite-preferred <id>` — step 3: apply exactly the latest finished preview's chosen sentences. */
 async function collectionsCitePreferred(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const args = argsFromFlags(ARGS.cite_preferred_sources, flags, positionals);
@@ -150,9 +186,7 @@ async function collectionsCitePreferred(ctx) {
 	const n = result?.started?.length ?? 0;
 	ok(
 		ctx,
-		result?.dry_run
-			? `Would run ${n} post${n === 1 ? "" : "s"}; ${result?.skipped?.length ?? 0} skipped.`
-			: `Started ${n} post${n === 1 ? "" : "s"}${result?.republishes === false ? " (changes wait on the draft for approval)" : ""}; ${result?.skipped?.length ?? 0} skipped.`
+		`Started ${n} post${n === 1 ? "" : "s"}${result?.republishes === false ? " (changes wait on the draft for approval)" : ""}; ${result?.skipped?.length ?? 0} skipped.`
 	);
 	printResult(io, flags, result);
 	return 0;
@@ -195,7 +229,7 @@ async function collectionsAutoPen(ctx) {
 	const patch = argsFromFlags(ARGS.update_auto_pen_config, flags, positionals);
 	if (Object.keys(patch).length === 1) {
 		throw new CliError(
-			"Nothing to change. Pass at least one of --template, --kernel-family, --mention, --outline-depth, --direction-gate, --auto-start, --prefer."
+			"Nothing to change. Pass at least one of --template, --kernel-family, --mention, --outline-depth, --direction-gate, --auto-start, --prefer, --client-one-in."
 		);
 	}
 

package/package.json

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