@letterstory/cli 0.76.1 → 0.81.0

package/README.md

@@ -630,6 +630,20 @@ letterstory enhance offer <collection-id> [--accept]          # our newer versio
 letterstory autopen run --article <id> --skip finish,metadata # leave passes out of one run
 ```
 
+## Org config
+
+An org's whole configuration as one JSON bundle (`export_org_config`; docs/architecture/org-config.md): settings, primitives and data, keyed by name, live primitive files, no runs or credentials.
+
+```bash
+letterstory org export > acme.json                 # the bundle — the same document MCP and the API return
+letterstory org export --sections primitives.kernels --sections data.collections
+letterstory org export --split acme/               # one file per record, for keeping config in git
+letterstory org join acme/ > acme.json             # rebuild the identical bundle from the directory
+letterstory org diff acme.json                     # what applying the bundle would change: + add, ~ change, - only in the org
+letterstory org apply acme.json --dry-run           # what apply would write; then drop --dry-run to apply
+letterstory org apply acme.json --prune --yes      # also delete records the bundle lacks
+```
+
 ## Seers — event-driven signals
 
 A **seer** watches an external source (a GitHub repo, a Notion workspace, a spec URL, a

package/lib/cli.mjs

@@ -37,6 +37,7 @@ import {
 	cmdKernel,
 	cmdOnboard,
 	cmdSeers,
+	cmdOrg,
 	cmdTemplates,
 	cmdCompositions,
 	cmdShredder,
@@ -56,7 +57,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.76.1";
+export const VERSION = "0.81.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.
@@ -368,12 +369,13 @@ Offerings (context layered org → offering → collection; a layer sets only wh
 
 Ranking targets (what the org wants to be THE answer for — company-wide or on one offering):
   targets list [--offering <offering-id|company>]      Targets grouped by scope, each with its active cap and usage
-  targets add <phrase> [--framing <f>] [--offering <offering-id|company>]
+  targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
                                                        Lands active while its scope has room, inactive after —
                                                        adding never fails on the cap
   targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
-                   [--position <n>] [--state active|inactive|achieved|retired]
-                                                       Moving an ACTIVE target needs room in the new scope
+                   [--position <n>] [--state active|inactive|achieved|retired] [--priority high|normal|low|default]
+                                                       Moving an ACTIVE target needs room in the new scope;
+                                                       --priority: how much it counts in share of voice
   targets activate | deactivate <target-id>            Switch a target on/off; activating is refused at the cap
   targets cap <offering-id|company> <n|default>        Active targets allowed in that scope (preset 5; default =
                                                        inherit the company's cap / back to the preset)
@@ -381,7 +383,7 @@ Ranking targets (what the org wants to be THE answer for — company-wide or on
 
 Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
   arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
-            [--gate] [--no-verify] [--provider native|exa|youcom|firecrawl] [--mention off|subtle|woven]
+            [--gate] [--no-verify] [--provider native|exa|youcom|context-dev] [--mention off|subtle|woven]
             [--context-file ctx.json] [--block <name> …] [--block-domain <domain> …]
             [--arena <arena-id>] [--article <uuid>] [--no-wait]
                                                         Start a run and follow it. --article makes
@@ -715,6 +717,11 @@ Seers (event-driven signals -> drafts):
   seers export [--file <path>]                         Dump the org's seers as a manifest
   seers apply --file <path> [--dry-run]                Idempotent, name-keyed upsert from a manifest
                                                        (never deletes; --dry-run prints the plan)
+  org export [--sections <s>…] [--file <path>]         The org's whole config as one JSON bundle
+  org export --split <dir>                             …as one file per record (for keeping config in git)
+  org join <dir> [--file <path>]                       Rebuild the bundle from a --split directory
+  org diff <file|dir>                                  What applying a bundle would change (reads only)
+  org apply <file|dir> [--dry-run] [--prune --yes]     Make the org match a bundle (adds/updates; --prune deletes)
 
 Content templates (compose structures seers bind via config.template_key):
   templates list                                       Custom + built-in catalog
@@ -1011,6 +1018,7 @@ const CLIENT_COMMANDS = {
 	kernel: cmdKernel,
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
+	org: cmdOrg,
 	templates: cmdTemplates,
 	compositions: cmdCompositions,
 	shredder: cmdShredder,

package/lib/commands/arena.mjs

@@ -64,7 +64,7 @@ function readJsonObjectFlag(flags, name) {
 const RUN_OPTIONS = {
 	depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
 	direction_gate: { flag: "gate", type: "bool" },
-	provider: { flag: "provider", enum: ["native", "exa", "youcom", "firecrawl"] },
+	provider: { flag: "provider", enum: ["native", "exa", "youcom", "context-dev"] },
 	// --no-verify turns the fact-check off; nothing sent otherwise (the default is on).
 	verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
 	mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },

package/lib/commands/org.mjs

@@ -0,0 +1,222 @@
+// `org` — the organization's whole configuration as one JSON bundle
+// (docs/architecture/org-config.md). `org export` prints the same document every door
+// returns (MCP `export_org_config`, REST, Settings' download); `--split <dir>` lays it out
+// as one file per record for keeping config in git, and `org join <dir>` rebuilds the
+// bundle from that directory, byte-for-byte the same JSON. `org diff <file|dir>` plans a
+// bundle against the live org (MCP `diff_org_config`) and changes nothing; `org apply`
+// executes that plan (`apply_org_config`), additive unless `--prune`.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagBool, flagStr, ok, printResult, refuseUnknownFlags, requirePositional } from "./shared.mjs";
+
+export const ARGS = {
+	export_org_config: {
+		sections: { flag: "sections", type: "list" },
+	},
+	diff_org_config: {
+		config: { value: (_flags, positionals) => readBundle(requirePositional(positionals, 0, "file|dir")) },
+	},
+	apply_org_config: {
+		config: { value: (_flags, positionals) => readBundle(requirePositional(positionals, 0, "file|dir")) },
+		dry_run: { flag: "dry-run", type: "bool" },
+		prune: { flag: "prune", type: "bool" },
+	},
+};
+
+export async function cmdOrg(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "export":
+			return orgExport(rest);
+		case "join":
+			return orgJoin(rest);
+		case "diff":
+			return orgDiff(rest);
+		case "apply":
+			return orgApply(rest);
+		default:
+			throw new CliError(`Unknown org subcommand: ${sub ?? "(none)"}. Try: export, join, diff, apply`);
+	}
+}
+
+const ROOT_FILE = "organization.json";
+
+function slug(name) {
+	return (
+		String(name)
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "") || "unnamed"
+	);
+}
+
+function writeJson(path, value) {
+	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** One file per record under `<group>/<section>/`, every other value in its own file. */
+export function splitBundle(bundle, dir) {
+	const { spec, ...root } = bundle;
+	mkdirSync(dir, { recursive: true });
+	writeJson(join(dir, ROOT_FILE), root);
+	let files = 1;
+	if (spec.settings) {
+		writeJson(join(dir, "settings.json"), spec.settings);
+		files++;
+	}
+	for (const group of ["primitives", "data", "tools"]) {
+		for (const [section, value] of Object.entries(spec[group] ?? {})) {
+			if (Array.isArray(value)) {
+				const sub = join(dir, group, section);
+				mkdirSync(sub, { recursive: true });
+				const used = new Map();
+				for (const record of value) {
+					const base = slug(record.name);
+					const n = (used.get(base) ?? 0) + 1;
+					used.set(base, n);
+					writeJson(join(sub, `${n === 1 ? base : `${base}-${n}`}.json`), record);
+					files++;
+				}
+			} else {
+				mkdirSync(join(dir, group), { recursive: true });
+				writeJson(join(dir, group, `${section}.json`), value);
+				files++;
+			}
+		}
+	}
+	return files;
+}
+
+export function joinBundle(dir) {
+	const rootPath = join(dir, ROOT_FILE);
+	if (!existsSync(rootPath))
+		throw new CliError(`${dir} has no ${ROOT_FILE} — produce one with \`org export --split\``);
+	const read = (p) => JSON.parse(readFileSync(p, "utf8"));
+	const root = read(rootPath);
+	const spec = {};
+	if (existsSync(join(dir, "settings.json"))) spec.settings = read(join(dir, "settings.json"));
+	for (const group of ["primitives", "data", "tools"]) {
+		spec[group] = {};
+		const gdir = join(dir, group);
+		if (!existsSync(gdir)) continue;
+		for (const entry of readdirSync(gdir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+			if (entry.isDirectory()) {
+				spec[group][entry.name] = readdirSync(join(gdir, entry.name))
+					.filter((f) => f.endsWith(".json"))
+					.map((f) => read(join(gdir, entry.name, f)))
+					.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+			} else if (entry.name.endsWith(".json")) {
+				spec[group][entry.name.slice(0, -5)] = read(join(gdir, entry.name));
+			}
+		}
+	}
+	return { ...root, spec };
+}
+
+async function orgExport(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS, ["split", "file"]);
+	const { config } = await client.callTool("export_org_config", argsFromFlags(ARGS.export_org_config, flags));
+	const split = flagStr(flags.split);
+	const file = flagStr(flags.file);
+	if (split) {
+		const n = splitBundle(config, split);
+		ok(ctx, `Exported ${config.metadata.org} to ${split}/ (${n} files).`);
+	} else if (file) {
+		writeJson(file, config);
+		ok(ctx, `Exported ${config.metadata.org} to ${file}.`);
+	} else {
+		io.log(JSON.stringify(config, null, 2));
+	}
+	for (const w of config.metadata.warnings ?? []) io.error?.(`warning: ${w}`);
+	return 0;
+}
+
+async function orgJoin(ctx) {
+	const { flags, io } = ctx;
+	const dir = requirePositional(ctx.positionals, 0, "dir");
+	const bundle = joinBundle(dir);
+	const file = flagStr(flags.file);
+	if (file) {
+		writeJson(file, bundle);
+		ok(ctx, `Joined ${dir}/ into ${file}.`);
+	} else io.log(JSON.stringify(bundle, null, 2));
+	return 0;
+}
+
+/** A bundle file, or a `--split` directory joined back into one. */
+export function readBundle(path) {
+	if (!existsSync(path)) throw new CliError(`${path} does not exist`);
+	if (statSync(path).isDirectory()) return joinBundle(path);
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (e) {
+		throw new CliError(`${path} is not JSON: ${e.message}`);
+	}
+}
+
+const SYMBOL = { add: "+", change: "~", remove: "-" };
+
+function show(v) {
+	const s = JSON.stringify(v) ?? "null";
+	return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+}
+
+export function formatPlan(plan) {
+	const lines = [];
+	for (const c of plan.changes) {
+		lines.push(
+			`${SYMBOL[c.op]} ${c.section}/${c.name}${c.op === "remove" ? "  (in the org only — kept unless pruning)" : ""}`
+		);
+		for (const f of c.fields) lines.push(`    ${f.path || "(value)"}: ${show(f.from)} → ${show(f.to)}`);
+	}
+	const s = plan.summary;
+	if (plan.changes.length) {
+		lines.push(
+			"",
+			`${plan.org}: ${s.add} to add, ${s.change} to change, ${s.remove} only in the org, ${s.unchanged} unchanged.`
+		);
+	} else lines.push(`${plan.org}: no changes — the live config matches the bundle (${s.unchanged} unchanged).`);
+	for (const w of plan.warnings) lines.push(`warning: ${w}`);
+	return lines.join("\n");
+}
+
+async function orgDiff(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS);
+	const { plan } = await client.callTool(
+		"diff_org_config",
+		argsFromFlags(ARGS.diff_org_config, flags, ctx.positionals)
+	);
+	printResult(io, flags, plan, formatPlan);
+	return 0;
+}
+
+export function formatApply(result) {
+	const lines = [result.dryRun ? "Dry run — nothing written. Would apply:" : "Applied:"];
+	for (const a of result.applied)
+		lines.push(`  ${SYMBOL[a.op]} ${a.section}/${a.name}${a.detail ? ` — ${a.detail}` : ""}`);
+	if (!result.applied.length) lines.push("  (nothing)");
+	if (result.skipped.length) lines.push("Skipped:");
+	for (const a of result.skipped) lines.push(`  ${SYMBOL[a.op]} ${a.section}/${a.name} — ${a.reason}`);
+	if (result.failed.length) lines.push("Failed:");
+	for (const a of result.failed) lines.push(`  ${SYMBOL[a.op]} ${a.section}/${a.name} — ${a.error}`);
+	for (const w of result.plan.warnings) lines.push(`warning: ${w}`);
+	return lines.join("\n");
+}
+
+async function orgApply(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS, ["yes"]);
+	if (flagBool(flags.prune) && !flagBool(flags["dry-run"]) && !flagBool(flags.yes))
+		throw new CliError("--prune deletes records missing from the bundle. Review with --dry-run, then add --yes.");
+	const { result } = await client.callTool(
+		"apply_org_config",
+		argsFromFlags(ARGS.apply_org_config, flags, ctx.positionals)
+	);
+	printResult(io, flags, result, formatApply);
+	return result.failed.length ? 1 : 0;
+}

package/lib/commands/targets.mjs

@@ -11,6 +11,7 @@ import { CliError } from "../client.mjs";
 import { flagStr, flagNum, printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
 
 const STATUSES = ["active", "inactive", "achieved", "retired"];
+const PRIORITIES = ["high", "normal", "low"];
 const COMPANY = "company";
 
 // `--offering <offering-id|company>`: company = the company layer (null). Absent = not sent.
@@ -24,6 +25,20 @@ function readOffering(flags) {
 }
 const offering = { value: readOffering };
 
+// `--priority high|normal|low|default`: how much the target's questions count in share of
+// voice (high = 2 votes, normal = 1, low = ½); default = back to the question-type default.
+function readPriority(flags) {
+	const v = flagStr(flags.priority);
+	if (v === undefined) {
+		if (flags.priority === true) throw new CliError("--priority takes high, normal, low or default");
+		return undefined;
+	}
+	if (v === "default") return null;
+	if (!PRIORITIES.includes(v)) throw new CliError("--priority must be one of: high, normal, low, default");
+	return v;
+}
+const priority = { value: readPriority };
+
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 // `scripts/parity-check.ts` compares these keys against each tool's published input schema.
 export const ARGS = {
@@ -39,6 +54,7 @@ export const ARGS = {
 		},
 		mention_framing: "framing",
 		offering_id: offering,
+		priority,
 	},
 	update_ranking_target: {
 		target_id: { positional: 0, label: "target-id", required: true },
@@ -50,6 +66,7 @@ export const ARGS = {
 		status: { flag: "state", enum: STATUSES },
 		offering_id: offering,
 		position: { flag: "position", type: "num" },
+		priority,
 	},
 	set_ranking_target_cap: {
 		offering_id: {
@@ -73,9 +90,9 @@ export const ARGS = {
 
 const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
   targets list [--offering <offering-id|company>]
-  targets add <phrase> [--framing <f>] [--offering <offering-id|company>]
+  targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
   targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
-                 [--position <n>] [--state active|inactive|achieved|retired]
+                 [--position <n>] [--state active|inactive|achieved|retired] [--priority high|normal|low|default]
   targets activate <target-id>
   targets deactivate <target-id>
   targets cap <offering-id|company> <n|default>
@@ -114,7 +131,8 @@ function formatScope(s) {
 
 function formatTarget(t) {
 	const framing = t.mention_framing ? ` — as ${t.mention_framing}` : "";
-	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}`;
+	const prio = t.priority ? `  (${t.priority} priority)` : "";
+	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}${prio}`;
 }
 
 // Targets grouped under their scope, each headed by its cap and usage. A target on an
@@ -151,7 +169,7 @@ async function targetsList(ctx) {
 
 async function targetsAdd(ctx) {
 	const { client, flags, positionals, io } = ctx;
-	refuseUnknownFlags(ctx, ARGS.add_ranking_target, ["offering"]);
+	refuseUnknownFlags(ctx, ARGS.add_ranking_target, ["offering", "priority"]);
 	const result = await client.callTool(
 		"add_ranking_target",
 		argsFromFlags(ARGS.add_ranking_target, flags, positionals)
@@ -172,7 +190,7 @@ async function update(ctx, flags) {
 	const args = argsFromFlags(ARGS.update_ranking_target, flags, positionals);
 	if (Object.keys(args).length === 1) {
 		throw new CliError(
-			"Nothing to update — pass --phrase, --framing, --clear-framing, --offering, --position or --state."
+			"Nothing to update — pass --phrase, --framing, --clear-framing, --offering, --position, --state or --priority."
 		);
 	}
 	const result = await client.callTool("update_ranking_target", args);
@@ -182,7 +200,7 @@ async function update(ctx, flags) {
 }
 
 async function targetsUpdate(ctx) {
-	refuseUnknownFlags(ctx, ARGS.update_ranking_target, ["framing", "clear-framing", "offering"]);
+	refuseUnknownFlags(ctx, ARGS.update_ranking_target, ["framing", "clear-framing", "offering", "priority"]);
 	return update(ctx, ctx.flags);
 }
 

package/lib/commands.mjs

@@ -31,6 +31,7 @@ export * from "./commands/lede.mjs";
 
 export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
+export * from "./commands/org.mjs";
 export * from "./commands/shredder.mjs";
 export * from "./commands/enhance.mjs";
 export * from "./commands/landings.mjs";

package/package.json

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