@letterstory/cli 0.96.0 → 0.98.0

package/README.md

@@ -353,7 +353,7 @@ long-running agent can watch the fleet on a schedule without a browser.
 # every client against itself on share of voice, mention rate and page access, with what we
 # did for it. Needs fleet:read; `run` and `ask` spend Fable tokens and need fleet:query.
 letterstory admin patterns --period 30d
-letterstory admin patterns kernels --by version --outcome impressions14   # what each kernel/version change did
+letterstory admin patterns chain --dimension arenaVersion --outcome cited14   # what each kernel/arena/research change did
 letterstory admin patterns reports            # Fable's weekly reports and runs, newest first
 letterstory admin patterns report <id>        # one report's markdown
 letterstory admin patterns run                # a report now (takes minutes)

package/lib/cli.mjs

@@ -58,7 +58,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.96.0";
+export const VERSION = "0.98.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
@@ -660,10 +660,12 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        Client patterns: every client's share of voice,
                                                        mention rate and page access against itself, with
                                                        what we did for it. Needs fleet:read.
-  admin patterns kernels [--by version|family] [--outcome cited14|read14|named|impressions14|clicks14|cited28|impressions28]
-                                                       What each kernel and version change did: the client's
-                                                       change minus clients that held still, pooled by
-                                                       transition. Needs fleet:read.
+  admin patterns chain [--dimension kernel|kernelVersion|arena|arenaVersion|researchPrompt] [--outcome cited14|read14|named|impressions14|clicks14|cited28|impressions28]
+                                                       What each change to the writing chain did (kernel,
+                                                       version, research arena, arena version, research
+                                                       prompt): the client's change minus the comparison,
+                                                       what changed with it, pooled by transition.
+                                                       "kernels" = --dimension kernelVersion. Needs fleet:read.
   admin patterns reports [--kind reports|weekly|run|ask] | report <id>
                                                        Fable's weekly reports, runs and Ask Fable answers.
   admin patterns run | ask "<question>"                Run a Fable report now, or ask Fable a question

package/lib/commands/admin.mjs

@@ -4,7 +4,7 @@
 // routes, because they exist precisely to act BEFORE an org exists.
 //
 //   admin ask "which kernels are hooked up to the most clients?" [--sql] [--json]
-//   admin patterns [--period 14d|30d] [--segment "…"] | kernels [--by version|family] [--outcome cited14] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
+//   admin patterns [--period 14d|30d] [--segment "…"] | chain [--dimension kernel|kernelVersion|arena|arenaVersion|researchPrompt] [--outcome cited14] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
@@ -273,25 +273,25 @@ async function cmdAdminPatterns(ctx) {
 			}
 			return;
 		}
+		case "chain":
 		case "kernels": {
 			const params = new URLSearchParams();
-			if (flagStr(ctx.flags.by)) params.set("by", flagStr(ctx.flags.by));
+			const dimension = flagStr(ctx.flags.dimension) ?? (sub === "kernels" ? "kernelVersion" : undefined);
+			if (dimension) params.set("dimension", dimension);
 			if (flagStr(ctx.flags.outcome)) params.set("outcome", flagStr(ctx.flags.outcome));
-			const result = await staffRequest(ctx, "GET", `${PATTERNS}/kernels${params.size ? `?${params}` : ""}`);
+			const result = await staffRequest(ctx, "GET", `${PATTERNS}/chain${params.size ? `?${params}` : ""}`);
 			if (json) return printResult(ctx.io, ctx.flags, result);
 			const fmt = (v) => (v == null ? "—" : `${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(3)}`);
-			ctx.io.log(
-				`Kernel changes on ${result.outcome}, by ${result.by} (effect = change minus clients that held still):`
-			);
+			ctx.io.log(`Changes to ${result.dimension} on ${result.outcome} (effect = change minus the comparison):`);
 			for (const t of result.transitions)
 				ctx.io.log(
-					`  ${`${t.from} → ${t.to}`.padEnd(30)} ${fmt(t.effect)} (${fmt(t.lo)} to ${fmt(t.hi)})  ${t.verdict}  · ${t.swaps} swaps, ${t.clients} clients`
+					`  ${`${t.from} → ${t.to}`.padEnd(34)} ${fmt(t.effect)} (${fmt(t.lo)} to ${fmt(t.hi)})  ${t.verdict}  · ${t.swaps} changes${t.confounded ? `, ${t.confounded} with another` : ""}, ${t.clients} clients`
 				);
 			if (!result.transitions.length) ctx.io.log("  none yet");
-			ctx.io.log(`\n${result.by === "version" ? "Versions" : "Kernels"} (descriptive):`);
-			for (const k of result.kernels)
+			ctx.io.log(`\nEvery value (descriptive):`);
+			for (const k of result.values)
 				ctx.io.log(
-					`  ${k.label.padEnd(16)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
+					`  ${k.label.padEnd(26)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
 				);
 			return;
 		}
@@ -334,9 +334,7 @@ async function cmdAdminPatterns(ctx) {
 			return;
 		}
 		default:
-			throw new CliError(
-				'Usage: admin patterns [show] | kernels | reports | report <id> | run | ask "<question>"'
-			);
+			throw new CliError('Usage: admin patterns [show] | chain | reports | report <id> | run | ask "<question>"');
 	}
 }
 

package/lib/commands/outbound.mjs

@@ -241,6 +241,8 @@ export const ARGS = {
 	},
 	delete_dispatch: {
 		dispatch_id: { positional: 0, label: "dispatch-id", required: true },
+		pending: { flag: "pending", enum: ["move", "send"] },
+		move_to: { flag: "move-to" },
 	},
 	list_dispatch_links: {},
 	create_dispatch_link: {
@@ -393,14 +395,28 @@ export const ARGS = {
 	},
 };
 
+// `message` may be a function of the tool's result, for a line that reports what actually happened.
 async function run(ctx, tool, message) {
 	refuseUnknownFlags(ctx, ARGS[tool]);
 	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
-	if (message) ok(ctx, message);
+	const text = typeof message === "function" ? message(result) : message;
+	if (text) ok(ctx, text);
 	printResult(ctx.io, ctx.flags, result);
 	return 0;
 }
 
+/** What a desk delete did, in one line: sent and moved counts as the tool reported them. */
+function deleteDispatchLine(result) {
+	const sent = Number(result?.sent ?? 0);
+	const moved = Number(result?.moved ?? 0);
+	const n = (count) => `${count} queued email${count === 1 ? "" : "s"}`;
+	if (result?.pending === "send") {
+		const base = `Dispatch deleted; ${n(sent)} approved to send.`;
+		return moved > 0 ? `${base} ${n(moved)} couldn't be approved and moved to ${result.moved_to}.` : base;
+	}
+	return `Dispatch deleted; ${n(moved)} moved${moved > 0 ? ` to ${result.moved_to}` : ""}.`;
+}
+
 const SEQUENCES_USAGE = `Usage: sequences <list|get|create|update|pause|resume|enroll|stop|review|links|cakes|heyreach>`;
 const DISPATCHES_USAGE = `Usage: dispatches <list|create|rename|delete>`;
 
@@ -422,12 +438,16 @@ export async function cmdDispatches(ctx) {
 		case "delete": {
 			if (!ctx.flags.yes) {
 				const id = flagStr(rest.positionals[0]) ?? "<dispatch-id>";
+				const moveTo = flagStr(ctx.flags["move-to"]);
+				// The re-run command carries every option given, so copying it does what this line says.
 				ctx.io.error(
-					`Its queued emails move to the default desk. Re-run with --yes to confirm: ${ctx.bin} dispatches delete ${id} --yes`
+					ctx.flags.pending === "send"
+						? `Its queued emails will be SENT now. Re-run with --yes to confirm: ${ctx.bin} dispatches delete ${id} --pending send --yes`
+						: `Its queued emails move to ${moveTo ?? "the default desk"}. Re-run with --yes to confirm: ${ctx.bin} dispatches delete ${id}${moveTo ? ` --move-to ${moveTo}` : ""} --yes`
 				);
 				return 1;
 			}
-			return run(rest, "delete_dispatch", "Dispatch deleted; its queued emails moved to the default desk.");
+			return run(rest, "delete_dispatch", deleteDispatchLine);
 		}
 		default:
 			throw new CliError(`Unknown dispatches subcommand: ${sub}. ${DISPATCHES_USAGE}`);

package/package.json

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