@standards/cli 1.0.0-alpha.388 → 1.0.0-alpha.390

package/dist/bin.mjs

@@ -4,7 +4,7 @@ import { createRequire } from "node:module";
 import { styleText } from "node:util";
 import { StandardsRequestError, createTransport } from "@standards/client";
 import { Command } from "commander";
-import { DEVICE_CHANNEL_WORKER_CLOSE_PROTOCOL_VIOLATION, MEETING_RESPONSES, RECORDING_OVERRIDES, RECORD_ACCESS_ROLES, RESOURCE_VISIBILITIES, SchemaError, SchemaErrorCode, ValidationError, canonicalStringify, computeReconnectDelay, computeRetryDelay, deviceChannelUrl, diffSchemaState, formatByteSize, parseRecordAccessRole, parseSchemaState, parseServerFrame, schemaStateSourcePayload } from "@standards/schema";
+import { CATALOG_KINDS, CATALOG_LOCALES, COUNT_MODES, DEVICE_CHANNEL_WORKER_CLOSE_PROTOCOL_VIOLATION, MEETING_RESPONSES, RECORDING_OVERRIDES, RECORD_ACCESS_ROLES, RESOURCE_VISIBILITIES, SchemaError, SchemaErrorCode, ValidationError, canonicalStringify, computeReconnectDelay, computeRetryDelay, deviceChannelUrl, diffSchemaState, formatByteSize, parseRecordAccessRole, parseSchemaState, parseServerFrame, schemaStateSourcePayload } from "@standards/schema";
 import Table from "cli-table3";
 import { createAppClient } from "@standards/client/app";
 import { homedir, hostname } from "node:os";
@@ -94,6 +94,15 @@ function getFormat(cmd) {
 function parseCsvList(value) {
 	return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 }
+/**
+* The API opts out of totals by default: an absent `countMode` yields no total.
+* Reject unknown modes here so a typo surfaces as an error instead of a
+* silently missing total.
+*/
+function parseCountFlag(count) {
+	if (COUNT_MODES.includes(count)) return count;
+	throw new ValidationError(`Invalid --count value "${count}". Expected one of: ${COUNT_MODES.join(", ")}.`, []);
+}
 function getClientFromCommand(cmd) {
 	const root = getGlobalOptions(cmd);
 	if (!(root.apiUrl && root.apiKey)) throw new Error("No Standards instance configured. Run \"standards login\" or pass --api-key.");
@@ -209,6 +218,77 @@ function registerBundlesCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/catalog.ts
+/** Reject a typo instead of letting the API answer a 400 on a bare enum. */
+function parseChoice(flag, value, choices) {
+	if (choices.includes(value)) return value;
+	throw new ValidationError(`${flag} must be one of: ${choices.join(", ")}`, []);
+}
+/** An empty selection installs nothing, so it is refused before the request. */
+function parseSelection(opts) {
+	const selection = {};
+	if (opts.entries !== void 0) selection.entries = parseCsvList(opts.entries);
+	if (opts.packs !== void 0) selection.packs = parseCsvList(opts.packs);
+	if (!(selection.entries?.length || selection.packs?.length)) throw new ValidationError("Select at least one catalog entry (--entries) or pack (--packs)", []);
+	return selection;
+}
+/** `<entryId>=bind`, `<entryId>=skip` or `<entryId>=rename:<name>`, one per collision. */
+function collectDecision(value, decisions) {
+	const separator = value.indexOf("=");
+	const entryId = value.slice(0, separator);
+	const choice = value.slice(separator + 1);
+	if (separator > 0 && (choice === "bind" || choice === "skip")) return {
+		...decisions,
+		[entryId]: choice
+	};
+	if (separator > 0 && choice.startsWith("rename:") && choice.length > 7) return {
+		...decisions,
+		[entryId]: { rename: choice.slice(7) }
+	};
+	throw new ValidationError(`--decision must read <entryId>=bind, <entryId>=skip or <entryId>=rename:<name> (received: ${value})`, []);
+}
+/** The flags `preview` and `install` share — both take the same selection. */
+function withSelectionOptions(command) {
+	return command.option("--entries <ids>", "comma-separated catalog entry IDs to install").option("--packs <ids>", "comma-separated catalog pack IDs to install").option("--locale <locale>", `language to compile the pieces in (${CATALOG_LOCALES.join(", ")})`, "en").option("--with-samples", "also install the packs' sample records");
+}
+/**
+* The pre-built catalog: objects, views and agents installed as copies the
+* workspace owns. `preview` returns the plan and its fingerprint; `install`
+* applies that same plan, refused if the workspace changed since.
+*/
+function registerCatalogCommand(program) {
+	const catalog = program.command("catalog").description("Browse and install pre-built objects, views and agents");
+	catalog.command("list").description("List the catalog entries and packs, and whether each is installed").option("--kind <kind>", `restrict to one kind (${CATALOG_KINDS.join(", ")})`).option("--search <text>", "match labels and descriptions").option("--locale <locale>", `language of the labels (${CATALOG_LOCALES.join(", ")})`, "en").action(async (opts, cmd) => {
+		formatOutput(await getAppClientFromCommand(cmd).catalog.list({
+			locale: parseChoice("--locale", opts.locale, CATALOG_LOCALES),
+			...opts.kind !== void 0 && { kind: parseChoice("--kind", opts.kind, CATALOG_KINDS) },
+			...opts.search !== void 0 && { q: opts.search }
+		}), getFormat(cmd));
+	});
+	catalog.command("get").description("Get one catalog entry or pack, with the IDs it pulls in").argument("<id>", "catalog entry or pack ID").option("--locale <locale>", `language of the labels (${CATALOG_LOCALES.join(", ")})`, "en").action(async (id, opts, cmd) => {
+		formatOutput(await getAppClientFromCommand(cmd).catalog.read({
+			id,
+			locale: parseChoice("--locale", opts.locale, CATALOG_LOCALES)
+		}), getFormat(cmd));
+	});
+	withSelectionOptions(catalog.command("preview").description("Plan an install: what is new, what collides, and the plan's fingerprint")).action(async (opts, cmd) => {
+		formatOutput(await getAppClientFromCommand(cmd).catalog.preview({
+			selection: parseSelection(opts),
+			locale: parseChoice("--locale", opts.locale, CATALOG_LOCALES),
+			withSamples: opts.withSamples === true
+		}), getFormat(cmd));
+	});
+	withSelectionOptions(catalog.command("install").description("Install a previewed selection as workspace-owned copies").requiredOption("--fingerprint <fingerprint>", "the fingerprint `catalog preview` returned").option("--decision <entryId=choice>", "how to settle a collision: bind, skip or rename:<name> (repeatable)", collectDecision, {})).action(async (opts, cmd) => {
+		formatOutput(await getAppClientFromCommand(cmd).catalog.install({
+			selection: parseSelection(opts),
+			locale: parseChoice("--locale", opts.locale, CATALOG_LOCALES),
+			withSamples: opts.withSamples === true,
+			decisions: opts.decision,
+			fingerprint: opts.fingerprint
+		}), getFormat(cmd));
+	});
+}
+//#endregion
 //#region src/commands/codemod.ts
 /** Rewrites consumer code for a breaking SDK change. */
 function registerCodemodCommand(program) {
@@ -1644,11 +1724,12 @@ function registerMeetingsCommand(program) {
 	meetings.command("get").description("Get one meeting, with its participants and linked records").argument("<id>", "meeting ID").action(async (id, _opts, cmd) => {
 		formatOutput(await getAppClientFromCommand(cmd).meetings.get({ meetingId: id }), getFormat(cmd));
 	});
-	withQueryOptions(meetings.command("for-record").description("List the meetings a record's email addresses appear in").argument("<recordId>", "record ID").option("--email-attributes <ids>", "comma-separated email attribute IDs to match participants on")).action(async (recordId, opts, cmd) => {
+	withQueryOptions(meetings.command("for-record").description("List the meetings a record's email addresses appear in").argument("<recordId>", "record ID").option("--email-attributes <ids>", "comma-separated email attribute IDs to match participants on").option("--count <mode>", "total count mode (estimated, exact); omit for no total")).action(async (recordId, opts, cmd) => {
 		formatOutput(await getAppClientFromCommand(cmd).meetings.forRecord({
 			recordId,
 			...opts.emailAttributes !== void 0 && { emailAttributeIds: parseCsvList(opts.emailAttributes) },
-			query: buildQuery(opts)
+			query: buildQuery(opts),
+			...opts.count !== void 0 && { countMode: parseCountFlag(opts.count) }
 		}), getFormat(cmd));
 	});
 	meetings.command("transcript").description("Read a meeting's completed transcript").argument("<id>", "meeting ID").action(async (id, _opts, cmd) => {
@@ -1741,20 +1822,6 @@ function parseSortFlag(sort) {
 		direction
 	}];
 }
-const COUNT_MODES = [
-	"none",
-	"estimated",
-	"exact"
-];
-/**
-* The API opts out of totals by default: an absent or unrecognized `countMode`
-* yields `page.total: null`. Reject unknown modes here so a typo surfaces as an
-* error instead of a silently missing total.
-*/
-function parseCountFlag(count) {
-	if (COUNT_MODES.includes(count)) return count;
-	throw new Error(`Invalid --count value "${count}". Expected one of: ${COUNT_MODES.join(", ")}.`);
-}
 /** Build the shared list/search request body from common query flags. */
 function buildQueryBody(opts) {
 	const body = {};
@@ -2034,6 +2101,7 @@ function createProgram() {
 	registerInvitationsCommand(program);
 	registerAuthCommand(program);
 	registerBundlesCommand(program);
+	registerCatalogCommand(program);
 	registerSourcesCommand(program);
 	registerCodemodCommand(program);
 	registerConnectorsCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standards/cli",
-  "version": "1.0.0-alpha.388",
+  "version": "1.0.0-alpha.390",
   "description": "CLI tool to interact with Standards API",
   "type": "module",
   "bin": {
@@ -19,9 +19,9 @@
     "commander": "^13.1.0",
     "typescript": "^5.6.3",
     "ws": "8.21.1",
-    "@standards/client": "1.0.0-alpha.388",
-    "@standards/constants": "1.0.0-alpha.388",
-    "@standards/schema": "1.0.0-alpha.388"
+    "@standards/client": "1.0.0-alpha.390",
+    "@standards/constants": "1.0.0-alpha.390",
+    "@standards/schema": "1.0.0-alpha.390"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",