@letterstory/cli 0.36.0 → 0.36.1

package/README.md

@@ -522,6 +522,22 @@ letterstory templates update <template-id> --angle "…"   # unset fields keep t
 letterstory templates delete <template-id> --yes   # bound seers fall back to defaults
 ```
 
+Primitive compositions (a named bundle of kernel/shredder/template/seer references —
+`docs/formats/compositions.md`; not a primitive, no endpoint or run. Needs
+`composition:read` / `composition:write`):
+
+```bash
+letterstory compositions list
+letterstory compositions create --name "Regulation-watch site kit" \
+  --content '{"kernel_family":"Cedar","shred":true,"template_key":"tmpl_howto"}' \
+  --phantom '{"theme":"gazette"}' \
+  --seer '{"name":"AI regulation watch","provider":"regulation_change","mode":"auto","config":{"query":"AI regulation"}}'
+letterstory compositions resolve comp_9f1a2b3c4d5e     # preview, read-only — costs nothing
+letterstory compositions update <composition-id> --clear-seer
+letterstory compositions delete <composition-id> --yes  # non-destructive to phantoms already built from it
+letterstory phantom create --name "EU AI Act Weekly" --composition '{"key":"comp_9f1a2b3c4d5e"}'
+```
+
 ## Cover images
 
 Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`

package/lib/cli.mjs

@@ -37,6 +37,7 @@ import {
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
+	cmdCompositions,
 	cmdShredder,
 	cmdLede,
 	cmdLandings,
@@ -46,7 +47,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.36.0";
+export const VERSION = "0.36.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.
@@ -564,6 +565,26 @@ Content templates (compose structures seers bind via config.template_key):
       for coverage in your own words and lets the engine pick the shape.
   templates delete <template-id> --yes
 
+Primitive compositions (named bundles of kernel/shredder/template/seer; not a primitive —
+no endpoint, no run. Applied on phantom create --composition '{"key":"..."}'):
+  compositions list                                     Org's compositions, by key
+  compositions show <composition-id>
+  compositions create --name <n> [--description <text>]
+      [--content '<json>'|--content-file <path>]        The collection's own content
+                                                       section (kernel_family, shred,
+                                                       shredder_endpoint_id, template_key,
+                                                       mention_degree, cover, visuals, verify).
+      [--phantom '<json>'|--phantom-file <path>]        Phantom-hosting defaults ({theme}).
+      [--seer '<json>'|--seer-file <path>]              Optional — the same shape
+                                                       'seers create' takes, minus
+                                                       collection/org (filled in once
+                                                       the phantom's collection exists).
+  compositions update <composition-id> [--name] [--description]
+      [--content ...] [--phantom ...] [--seer '<json>'|--seer-file <path>|--clear-seer]
+  compositions delete <composition-id> --yes
+  compositions resolve <composition-key>                Preview what create_phantom would
+                                                       merge in — read-only, costs nothing.
+
 Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder list                                        Your shredder endpoints + run counts
   shredder create --name <n>                           New endpoint (returns a callable public id)
@@ -696,6 +717,7 @@ const CLIENT_COMMANDS = {
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
+	compositions: cmdCompositions,
 	shredder: cmdShredder,
 	lede: cmdLede,
 	ledes: cmdLede,

package/lib/commands/compositions.mjs

@@ -0,0 +1,193 @@
+// `compositions` — Primitive Compositions, the FORMAT that bundles a kernel, a shredder, a
+// content template and a seer into one named, reusable reference (docs/formats/compositions.md).
+//
+// Not a primitive: no endpoint, no run, no balance. What it has instead of a door is a
+// RESOLUTION — `compositions resolve <key>` — and one consuming door, `phantom create
+// --composition '{"key":"..."}'` (see phantom.mjs), which resolves it exactly once and merges
+// it in. Authoring (list/show/create/update/delete) is CLI/REST parity work only; the mechanism
+// itself shipped with the format.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} catch (err) {
+			throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+			throw new CliError(`--${name} must be a JSON object`);
+		return parsed;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+
+// `--seer '<json>'`/`--seer-file <path>` sets it, `--clear-seer` sends null (the composition
+// stands up no seer), neither leaves it unchanged — same idiom as seers.mjs's clearableValue.
+function seerFromFlags(flags) {
+	if (flags["clear-seer"] === true) return null;
+	return readJsonObjectFlag(flags, "seer");
+}
+
+/**
+ * How this command sources its tool inputs — see `argsFromFlags` in shared.mjs and
+ * `scripts/parity-check.ts`. `content`/`phantom`/`seer` are each a JSON object (the collection
+ * content section, `{theme}`, and a create_seer-shaped spec, respectively) — the same
+ * `--flag '<json>'`/`--flag-file <path>` idiom `phantom create --composition` already uses,
+ * not decomposed field-by-field: they're bundles authored once and read back, not edited a
+ * field at a time from the CLI.
+ */
+export const ARGS = {
+	list_compositions: {},
+	get_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+	resolve_composition: {
+		key: { positional: 0, label: "composition-key", required: true },
+	},
+	create_composition: {
+		name: { flag: "name", required: true },
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => readJsonObjectFlag(flags, "seer") },
+	},
+	update_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+		name: "name",
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => seerFromFlags(flags) },
+	},
+	delete_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+};
+
+export async function cmdCompositions(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return compositionsList(rest);
+		case "show":
+		case "get":
+			return compositionsShow(rest);
+		case "create":
+		case "new":
+			return compositionsCreate(rest);
+		case "update":
+			return compositionsUpdate(rest);
+		case "delete":
+		case "rm":
+			return compositionsDelete(rest);
+		case "resolve":
+			return compositionsResolve(rest);
+		default:
+			throw new CliError(
+				`Unknown compositions subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete, resolve`
+			);
+	}
+}
+
+async function compositionsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_compositions", {});
+	printResult(io, flags, result, (r) =>
+		(r.compositions ?? []).length
+			? (r.compositions ?? [])
+					.map((c) => `  ${c.key}  ${c.name}${c.seer ? " (+seer)" : ""} — id ${c.id}`)
+					.join("\n")
+			: "No compositions yet."
+	);
+	return 0;
+}
+
+async function compositionsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool("get_composition", argsFromFlags(ARGS.get_composition, flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.create_composition, flags, []);
+	if (!args.name) throw new CliError("Missing required --name");
+	const result = await client.callTool("create_composition", args);
+	ok(ctx, `Composition created — key ${result.composition?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool(
+		"update_composition",
+		argsFromFlags(ARGS.update_composition, flags, positionals)
+	);
+	ok(ctx, "Composition updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	if (!flags.yes) {
+		throw new CliError(
+			"Non-destructive to phantoms already built from it (their resolved_from_composition becomes a name pointing at nothing). Re-run with --yes to delete."
+		);
+	}
+	const result = await client.callTool(
+		"delete_composition",
+		argsFromFlags(ARGS.delete_composition, flags, positionals)
+	);
+	ok(ctx, "Composition deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `compositions resolve <key>` — turn a composition into the sections `phantom create
+ * --composition` would merge in. Read-only, costs nothing. Preview a bundle, or build the
+ * sections yourself for a door that doesn't take `composition` directly yet (`collection
+ * config` / `seers create`).
+ */
+async function compositionsResolve(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-key");
+	const result = await client.callTool(
+		"resolve_composition",
+		argsFromFlags(ARGS.resolve_composition, flags, positionals)
+	);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -23,6 +23,7 @@ export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
 export * from "./commands/arena.mjs";
 export * from "./commands/templates.mjs";
+export * from "./commands/compositions.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/lede.mjs";

package/package.json

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