@k2b/cloud 0.29.1 → 0.31.0

package/src/browser/spotlight-position.ts

@@ -1,4 +1,4 @@
-import type { DialogRender } from "@k2b/ui";
+import { type DialogRender, suppressTextSelection } from "@k2b/ui";
 
 export type SpotlightPosition = { x: number; y: number };
 const STORAGE_KEY = "cloud.spotlight.position.v1";
@@ -42,6 +42,7 @@ export const attachSpotlightPosition = (
     origin: SpotlightPosition;
     previous: SpotlightPosition | null;
     handle: HTMLElement;
+    releaseTextSelection: () => void;
   } | null = null;
 
   const home = document.createElement("div");
@@ -108,6 +109,7 @@ export const attachSpotlightPosition = (
     if (!drag) return;
     const handle = drag.handle;
     const id = drag.id;
+    drag.releaseTextSelection();
     drag = null;
     if (handle.hasPointerCapture(id)) handle.releasePointerCapture(id);
     delete host.dataset.dragging;
@@ -132,6 +134,7 @@ export const attachSpotlightPosition = (
       origin: { x: rect.x, y: rect.y },
       previous: position,
       handle,
+      releaseTextSelection: suppressTextSelection(event.pointerId),
     };
     handle.setPointerCapture(event.pointerId);
   };

package/src/browser/widgets.ts

@@ -0,0 +1,30 @@
+import type { DashboardWidgetSize, WidgetStreamLine } from "../contracts/widgets";
+import { LOCALE_HEADER } from "../shared/locale";
+import { NDJSON_CONTENT_TYPE, readNdjsonLines } from "./ndjson";
+
+export type { DashboardWidgetSize, WidgetResponse, WidgetStreamLine, WidgetStreamStatus } from "../contracts/widgets";
+
+/**
+ * Asks Core for dashboard widgets and hands over each one as soon as it answers: `start` names the widgets, one
+ * `widget` line follows per widget in the order they finish, then `done`. `keys` (`<appId>/<widgetId>`) limits the
+ * request, for example to retry one widget; without it Core asks every declared widget. `sizes` names the size to ask
+ * a widget for; a widget without one, or with a size it does not offer, answers in its default size. Aborting `signal`
+ * stops every widget Core still waits for. Rejects when the request fails or the stream breaks off.
+ */
+export const streamWidgets = async (options: {
+  keys?: readonly string[];
+  sizes?: Readonly<Record<string, DashboardWidgetSize>>;
+  signal: AbortSignal;
+  locale: string;
+  onLine: (line: WidgetStreamLine) => void;
+}): Promise<void> => {
+  const query = new URLSearchParams();
+  for (const key of options.keys ?? []) query.append("widget", options.sizes?.[key] ? `${key}@${options.sizes[key]}` : key);
+  const search = query.toString();
+  const response = await fetch(`/api/widgets/v1${search ? `?${search}` : ""}`, {
+    signal: options.signal,
+    headers: { accept: NDJSON_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+  });
+  if (!response.ok) throw new Error(`Widgets failed with ${response.status}`);
+  await readNdjsonLines(response, options.onLine, "Widgets");
+};

package/src/capabilities/executions.ts

@@ -1,5 +1,6 @@
 import { sql } from "bun";
 import type { CapabilityOrigin } from "../contracts/capabilities";
+import { pruneApprovalRequests } from "../services/approvals";
 import { logger } from "../services/logging";
 import { CAPABILITY_CLAIM_RETENTION_HOURS, pruneCapabilityIdempotencyClaims } from "./claims";
 
@@ -280,6 +281,8 @@ export const startCapabilityExecutionMaintenance = (): (() => void) => {
     try {
       const removed = await pruneCapabilityExecutions(new Date(Date.now() - CAPABILITY_EXECUTION_RETENTION_DAYS * 86_400_000));
       if (removed > 0) log.info("Pruned expired capability executions", { removed });
+      const requests = await pruneApprovalRequests(new Date(Date.now() - CAPABILITY_EXECUTION_RETENTION_DAYS * 86_400_000));
+      if (requests > 0) log.info("Pruned expired approval requests", { removed: requests });
       const claims = await pruneCapabilityIdempotencyClaims(new Date(Date.now() - CAPABILITY_CLAIM_RETENTION_HOURS * 3_600_000));
       if (claims > 0) log.info("Pruned expired capability idempotency claims", { removed: claims });
     } catch (error) {

package/src/capabilities/server.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { resolveCapabilityActionWording, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import type { CapabilityActionWording } from "../_internal/capability-sentences";
 import { getApp, getCapability } from "../_internal/registry";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
 import { env } from "../config/env";
@@ -14,7 +15,7 @@ import { get } from "../services/settings";
 import { resolveAppPresentation } from "../shared/app-presentation";
 import { publicCloudOrigin } from "../shared/app-url";
 import { capabilityMessages } from "../shared/capability-messages";
-import { LOCALE_HEADER } from "../shared/locale";
+import { DEFAULT_LOCALE, LOCALE_HEADER } from "../shared/locale";
 import { readCapabilityResponse } from "./response";
 import { combineCapabilitySignals } from "./signals";
 import type {
@@ -26,6 +27,7 @@ import type {
   CapabilityReviewClientResult,
 } from "./types";
 
+export type { CapabilityActionWording } from "../_internal/capability-sentences";
 export type {
   CapabilityCatalogApp,
   CapabilityCatalogAppClientResult,
@@ -225,6 +227,22 @@ export const getCapabilityCatalogApp = async (appId: string, locale?: string): P
   }
 };
 
+/**
+ * How people read calls of one Action in a locale, from the live registry like the Assistant's own calls: its title,
+ * the app's sentences, and the labelled fields of the generic sentence. Pass `sentences` and `fields` to the chat's
+ * approval card, so an approval a script or app asks for reads like the same call in a chat. `null` for an unknown
+ * app or Action.
+ */
+export const getCapabilityActionWording = async (
+  appId: string,
+  localId: string,
+  locale?: string,
+): Promise<CapabilityActionWording | null> => {
+  const capability = await getCapability(appId);
+  const action = capability?.manifest.actions.find((candidate) => candidate.localId === localId);
+  return capability && action ? resolveCapabilityActionWording(action, capability.presentation, locale ?? DEFAULT_LOCALE) : null;
+};
+
 export const reviewCapabilityAction = async <TInput = unknown>(
   invocation: Omit<CapabilityInvocation<TInput>, "kind" | "idempotencyKey">,
   caller: CapabilityCaller,

package/src/cli/access.ts

@@ -28,10 +28,24 @@ export type AccessCommandAdapter<TResource extends AccessResource> = {
   resourceArgDescription?: string;
   resolveResource: AccessCommandResourceResolver<TResource>;
   list: (ctx: CloudCliContext, resource: TResource) => Promise<AccessEntry[]>;
-  grant: (ctx: CloudCliContext, resource: TResource, principal: Principal, permission: AccessPermission) => Promise<AccessEntry>;
-  update: (ctx: CloudCliContext, resource: TResource, accessId: string, permission: AccessPermission) => Promise<void>;
+  /** `scope` is one of `scopes`, or undefined when the command line names none. */
+  grant: (
+    ctx: CloudCliContext,
+    resource: TResource,
+    principal: Principal,
+    permission: AccessPermission,
+    scope?: string,
+  ) => Promise<AccessEntry>;
+  /** `scope` is one of `scopes`, or undefined to keep the grant's scope. */
+  update: (ctx: CloudCliContext, resource: TResource, accessId: string, permission: AccessPermission, scope?: string) => Promise<void>;
   revoke: (ctx: CloudCliContext, resource: TResource, accessId: string) => Promise<void>;
   allowedPermissions?: readonly AccessPermission[];
+  /**
+   * Parts of the resource a grant can cover, as the resource's access API names them in `scope`:
+   * the whole resource first (shown for entries without a scope), then narrower parts. Adds
+   * `--scope` to `grant` and `set` and a SCOPE column to `list`.
+   */
+  scopes?: readonly [string, ...string[]];
   allowPublic?: boolean;
   allowAuthenticated?: boolean;
   allowServiceAccounts?: boolean;
@@ -243,7 +257,7 @@ const entryTypeLabel = (entry: AccessEntry): string => {
 };
 
 // Resource-bound service accounts back resource API keys, which are managed with those keys.
-const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean } = {}) =>
+const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean; scopes?: readonly string[] } = {}) =>
   entries
     .filter((entry) => options.includeServiceAccounts || entry.serviceAccountKind !== "resource_bound")
     .sort((a, b) => {
@@ -256,6 +270,7 @@ const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?:
       principal: entryDisplayName(entry),
       type: entryTypeLabel(entry),
       permission: entry.permission,
+      ...(options.scopes ? { scope: entry.scope ?? options.scopes[0] } : {}),
       createdAt: entry.createdAt,
     }));
 
@@ -269,7 +284,7 @@ const printStructured = (ctx: CloudCliContext, value: unknown): boolean => {
 export const printAccessEntries = (
   ctx: CloudCliContext,
   entries: AccessEntry[],
-  options: { includeServiceAccounts?: boolean; jsonValue?: unknown } = {},
+  options: { includeServiceAccounts?: boolean; jsonValue?: unknown; scopes?: readonly string[] } = {},
 ) => {
   if (printStructured(ctx, options.jsonValue ?? entries)) return;
   const rows = accessRows(entries, options);
@@ -281,6 +296,7 @@ export const printAccessEntries = (
     { key: "principal", label: "PRINCIPAL" },
     { key: "type", label: "TYPE" },
     { key: "permission", label: "PERMISSION" },
+    ...(options.scopes ? [{ key: "scope" as const, label: "SCOPE" }] : []),
     { key: "accessId", label: "ACCESS ID" },
   ]);
 };
@@ -349,6 +365,19 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
     includeServiceAccountFlag: adapter.allowServiceAccounts === true,
   };
   const resolve = (ctx: CloudCliContext, args: string[]) => adapter.resolveResource(ctx, args);
+  const scopeFlag: { scope?: ReturnType<typeof flag.string> } = adapter.scopes
+    ? {
+        scope: flag.string({
+          description: `Part of the ${adapter.resourceLabel} the grant covers. Allowed: ${adapter.scopes.join(", ")}`,
+        }),
+      }
+    : {};
+  const scopeSuffix = (scope: string | undefined): string => (scope && scope !== adapter.scopes?.[0] ? ` (${scope})` : "");
+  const scopeOf = (flags: { scope?: string }): string | undefined => {
+    if (flags.scope === undefined) return undefined;
+    if (!adapter.scopes?.includes(flags.scope)) throw new Error(`Scope must be one of: ${adapter.scopes?.join(", ") ?? "none"}.`);
+    return flags.scope;
+  };
   const resourceArgs = {
     args: arg.rest({
       valueLabel: adapter.resourceArgLabel ?? adapter.resourceLabel,
@@ -374,6 +403,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       printAccessEntries(ctx, entries, {
         includeServiceAccounts: flags.includeServiceAccounts,
         jsonValue: { resource, entries },
+        scopes: adapter.scopes,
       });
     },
   });
@@ -385,16 +415,18 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
     flags: {
       ...principalFlags(principalFlagOptions),
       permission: flag.enum(allowed, { required: true, description: `Permission to grant. Allowed: ${allowed.join(", ")}` }),
+      ...scopeFlag,
     },
     examples: adapter.examples?.grant,
     async run({ ctx, args, flags }) {
       const resource = await resolve(ctx, args.args);
       const permission = flags.permission as AccessPermission;
       assertAllowedPermission(permission, allowed);
+      const scope = scopeOf(flags);
       const principal = await resolveAccessPrincipal(ctx, flags as PrincipalFlags, adapter);
-      const entry = await adapter.grant(ctx, resource, principal, permission);
+      const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry }))
-        ctx.print(`Granted ${permission} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
     },
   });
 
@@ -407,17 +439,19 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       ...principalFlags(principalFlagOptions),
       ...accessIdFlag,
       permission: flag.enum(allowed, { required: true, description: `Permission to set. Allowed: ${allowed.join(", ")}` }),
+      ...scopeFlag,
     },
     examples: adapter.examples?.set,
     async run({ ctx, args, flags }) {
       const resource = await resolve(ctx, args.args);
       const permission = flags.permission as AccessPermission;
       assertAllowedPermission(permission, allowed);
+      const scope = scopeOf(flags);
 
       if (flags.accessId) {
-        await adapter.update(ctx, resource, flags.accessId, permission);
-        if (!printStructured(ctx, { resource, accessId: flags.accessId, permission, action: "updated" })) {
-          ctx.print(`Updated ${flags.accessId} to ${permission} on ${resource.label}.`);
+        await adapter.update(ctx, resource, flags.accessId, permission, scope);
+        if (!printStructured(ctx, { resource, accessId: flags.accessId, permission, scope, action: "updated" })) {
+          ctx.print(`Updated ${flags.accessId} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
         }
         return;
       }
@@ -426,15 +460,15 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       const entries = await adapter.list(ctx, resource);
       const existing = entries.find((entry) => principalKey(entry.principal) === principalKey(principal));
       if (existing) {
-        await adapter.update(ctx, resource, existing.id, permission);
-        if (!printStructured(ctx, { resource, accessId: existing.id, permission, action: "updated" })) {
-          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission} on ${resource.label}.`);
+        await adapter.update(ctx, resource, existing.id, permission, scope);
+        if (!printStructured(ctx, { resource, accessId: existing.id, permission, scope, action: "updated" })) {
+          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
         }
         return;
       }
-      const entry = await adapter.grant(ctx, resource, principal, permission);
+      const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry, action: "created" })) {
-        ctx.print(`Granted ${permission} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
       }
     },
   });

package/src/cli/admin/ai-skills.ts

@@ -4,7 +4,7 @@ import { apiGet, apiJson, queryString } from "./shared";
 
 export const aiSkillCommands = [
   command("ai skills list", {
-    summary: "List all Skills with template origin, version, status, and revision (platform admin)",
+    summary: "List all Skills with source app, availability, status, and revision (platform admin)",
     flags: {
       search: flag.string(),
       page: flag.int({ min: 1, default: 1 }),
@@ -15,49 +15,69 @@ export const aiSkillCommands = [
         ctx,
         `/api/admin/core/ai-skills${queryString(flags)}`,
       );
-      printRows(ctx, result, result.items, [
-        { key: "shortId" },
-        { key: "name" },
-        { key: "revision" },
-        { key: "templateId" },
-        { key: "templateVersion" },
-        { key: "currentTemplateVersion" },
-        { key: "templateStatus" },
-      ]);
-    },
-  }),
-  command("ai skills templates", {
-    summary: "List current trusted Skill template IDs and versions",
-    run: async ({ ctx }) => {
-      const result = await apiGet<{ templates: { templateId: string; name: string; version: number }[] }>(
+      printRows(
         ctx,
-        "/api/admin/core/ai-skills/templates",
+        result,
+        result.items.map((skill) => ({
+          ...skill,
+          app: skill.source?.appName ?? "",
+          status: skill.source?.status ?? "",
+          available: skill.source?.available ?? "",
+          appVersion: skill.source?.appVersion ?? "",
+        })),
+        [
+          { key: "shortId" },
+          { key: "name" },
+          { key: "revision" },
+          { key: "app" },
+          { key: "status" },
+          { key: "available" },
+          { key: "appVersion" },
+        ],
       );
-      printRows(ctx, result, result.templates, [{ key: "templateId" }, { key: "name" }, { key: "version" }]);
     },
   }),
-  ...(["associate", "reset"] as const).map((mode) =>
-    command(`ai skills ${mode}`, {
-      summary:
-        mode === "associate"
-          ? "Associate an existing Skill with a template, preserving all content"
-          : "Replace all linked Skill content and references with the current template",
-      args: { skillId: arg.required() },
-      flags: {
-        templateId: flag.string({ name: "template", required: true }),
-        templateVersion: flag.int({ name: "template-version", required: true, min: 1 }),
-        expectedRevision: flag.int({ name: "revision", required: true, min: 1 }),
-        yes: confirmFlag("Confirm the exact Skill and template; export customized content before resetting"),
-      },
+  command("ai skills reset", {
+    summary: "Replace Skill content and references with the owning app's current version",
+    args: { skillId: arg.required() },
+    flags: {
+      expectedRevision: flag.int({ name: "revision", required: true, min: 1 }),
+      expectedAppVersion: flag.string({ name: "app-version", required: true }),
+      yes: confirmFlag("Confirm resetting this Skill; export customized content first"),
+    },
+    run: async ({ ctx, args, flags }) => {
+      if (!flags.yes) throw new Error("Review the Skill first, then confirm with --yes.");
+      const result = await apiJson(ctx, "POST", `/api/admin/core/ai-skills/${encodeURIComponent(args.skillId)}/reset`, {
+        expectedRevision: flags.expectedRevision,
+        expectedAppVersion: flags.expectedAppVersion,
+        confirmed: true,
+      });
+      if (!printStructured(ctx, result)) ctx.print("Skill reset to the app version.");
+    },
+  }),
+  ...(
+    [
+      ["restore", "Install a deleted app Skill again from the app's version, when its name is free", "App Skill installed."],
+      [
+        "adopt",
+        "Link the existing Skill that holds an app Skill's name to that app, keeping its content",
+        "Existing Skill linked to the app.",
+      ],
+    ] as const
+  ).map(([action, summary, done]) =>
+    command(`ai skills ${action}`, {
+      summary,
+      args: { appId: arg.required(), name: arg.required() },
+      flags: { yes: confirmFlag(`Confirm the app and Skill name to ${action}`) },
       run: async ({ ctx, args, flags }) => {
-        if (!flags.yes) throw new Error("Review the Skill and template first, then confirm with --yes.");
-        const { yes: _yes, ...input } = flags;
-        const result = await apiJson(ctx, "POST", `/api/admin/core/ai-skills/${encodeURIComponent(args.skillId)}/template`, {
-          ...input,
-          mode,
-          confirmed: true,
-        });
-        if (!printStructured(ctx, result)) ctx.print("Skill template updated.");
+        if (!flags.yes) throw new Error("Review the app Skill first, then confirm with --yes.");
+        const result = await apiJson(
+          ctx,
+          "POST",
+          `/api/admin/core/ai-skills/apps/${encodeURIComponent(args.appId)}/skills/${encodeURIComponent(args.name)}/${action}`,
+          { confirmed: true },
+        );
+        if (!printStructured(ctx, result)) ctx.print(done);
       },
     }),
   ),

package/src/cli/commands.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import type { CloudCliContext, CloudCliFlagValue, CloudCliModule } from "./index";
+import { isCloudCliAlias, isCloudCliShortcuts } from "./plugin";
 
 type FlagKind = "string" | "boolean" | "int" | "enum" | "stringList" | "input";
 type ArgKind = "required" | "optional" | "rest";
@@ -155,6 +156,8 @@ type CommandNode = {
 type CliCommandsConfig = {
   name: string;
   summary: string;
+  alias?: string;
+  shortcuts?: Readonly<Record<string, string>>;
   requiresCloud?: boolean;
   groupSummaries?: Readonly<Record<string, string>>;
   commands: readonly CliCommandDefinition[];
@@ -241,10 +244,27 @@ export const readCliInput = async (input: CliInputFlagValue, options: ReadCliInp
 
 export const defineCliCommands = (config: CliCommandsConfig): CloudCliModule => {
   const root = buildCommandTree(config.commands, config.groupSummaries);
+  if (config.alias !== undefined && !isCloudCliAlias(config.alias, config.name)) {
+    throw new Error("CLI alias must be a lowercase kebab-case name different from the module name");
+  }
+  let shortcuts: Record<string, string> | undefined;
+  if (config.shortcuts !== undefined) {
+    if (!isCloudCliShortcuts(config.shortcuts, config.name, config.alias)) {
+      throw new Error("CLI shortcuts require unique kebab-case names and non-empty command paths without flags");
+    }
+    shortcuts = {};
+    for (const [name, target] of Object.entries(config.shortcuts)) {
+      const segments = target.trim().split(/\s+/);
+      if (!findNode(root, segments)?.command) throw new Error(`Unknown CLI shortcut command path: ${target}`);
+      shortcuts[name] = segments.join(" ");
+    }
+  }
 
   return {
     name: config.name,
     summary: config.summary,
+    ...(config.alias !== undefined ? { alias: config.alias } : {}),
+    ...(shortcuts !== undefined ? { shortcuts } : {}),
     requiresCloud: config.requiresCloud,
     requiresCloudFor: (args) => {
       const helpRequest = normalizeHelpRequest(args, {});

package/src/cli/index.ts

@@ -51,6 +51,12 @@ export type CloudCliContext = {
   profiles?: {
     saveClientCredentials: (input: CloudCliClientCredentialsProfile) => Promise<void>;
   };
+  /**
+   * Open an `http:` or `https:` URL in the user's browser, when the host can.
+   * Resolves `false` when nothing was opened, so the command still prints the
+   * link. Absent in hosts without a local browser.
+   */
+  openUrl?: (url: string) => Promise<boolean>;
 };
 
 /** A profile that signs in with the OAuth client-credentials grant. */
@@ -70,6 +76,16 @@ export type CloudCliClientCredentialsProfile = {
 export type CloudCliModule = {
   name: string;
   summary: string;
+  /**
+   * `cld <alias> …` runs `cld <name> …`. Names match CLOUD_CLI_MODULE_NAME;
+   * cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  alias?: string;
+  /**
+   * Top-level names mapped to space-separated command paths relative to this module, never preset flags or args.
+   * Names match CLOUD_CLI_MODULE_NAME; cld uses them only when exactly one installed module claims them and no built-in or module has that name.
+   */
+  shortcuts?: Readonly<Record<string, string>>;
   booleanFlags?: readonly string[];
   requiresCloud?: boolean;
   requiresCloudFor?: (args: string[], flags: CloudCliFlags) => boolean;

package/src/cli/plugin.ts

@@ -67,6 +67,27 @@ export const cloudCliPluginDigest = (files: readonly Pick<CloudCliPluginFile, "p
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
+/** Whether an alias is a valid extra name for this module. */
+export const isCloudCliAlias = (value: unknown, name: string): value is string =>
+  typeof value === "string" && CLOUD_CLI_MODULE_NAME.test(value) && value !== name;
+
+/** Validate short names and command-path syntax without loading a module's command tree. */
+export const isCloudCliShortcuts = (value: unknown, name: string, alias?: string): value is Record<string, string> =>
+  isRecord(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+  Object.entries(value).every(
+    ([key, target]) =>
+      CLOUD_CLI_MODULE_NAME.test(key) &&
+      key !== name &&
+      key !== alias &&
+      typeof target === "string" &&
+      target.trim() !== "" &&
+      target
+        .trim()
+        .split(/\s+/)
+        .every((segment) => !segment.startsWith("-")),
+  );
+
 /** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
 export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
   if (!isRecord(value)) throw new Error("plugin manifest is not an object");
@@ -111,6 +132,15 @@ export const validateCloudCliModule = (value: unknown): CloudCliModule => {
   if (typeof value.name !== "string" || !CLOUD_CLI_MODULE_NAME.test(value.name)) {
     throw new Error("default export needs a lowercase kebab-case name");
   }
+  if (value.alias !== undefined && !isCloudCliAlias(value.alias, value.name)) {
+    throw new Error("alias must be a lowercase kebab-case name different from the module name");
+  }
+  if (
+    value.shortcuts !== undefined &&
+    !isCloudCliShortcuts(value.shortcuts, value.name, typeof value.alias === "string" ? value.alias : undefined)
+  ) {
+    throw new Error("shortcuts must be a plain object with unique kebab-case names and non-empty command paths without flags");
+  }
   if (typeof value.summary !== "string") throw new Error("default export needs a string summary");
   if (typeof value.run !== "function") throw new Error("default export needs a run function");
   for (const key of ["help", "requiresCloudFor"] as const) {

package/src/contracts/announcement-cookie.ts

@@ -0,0 +1,62 @@
+/**
+ * The announcements cookie, without schemas: the shell reads and writes it on every page and must not load the
+ * announcement validators for that. `AnnouncementCookieStateSchema` in `./announcements` describes the same shape.
+ */
+export const ANNOUNCEMENTS_COOKIE = "cloud_announcements";
+export const ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+export const MAX_DISMISSED_BANNER_VERSIONS = 50;
+
+export type AnnouncementCookieState = {
+  seenAnnouncementVersion: number;
+  dismissedBannerVersions: number[];
+};
+
+export const DEFAULT_ANNOUNCEMENT_COOKIE_STATE: AnnouncementCookieState = {
+  seenAnnouncementVersion: 0,
+  dismissedBannerVersions: [],
+};
+
+const isVersion = (value: unknown, minimum: number): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+
+/** Any invalid field resets the whole state, as a failed schema parse did. */
+const normalizeCookieState = (value: unknown): AnnouncementCookieState => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const { seenAnnouncementVersion = 0, dismissedBannerVersions = [] } = value as Partial<Record<keyof AnnouncementCookieState, unknown>>;
+  if (!isVersion(seenAnnouncementVersion, 0)) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  if (!Array.isArray(dismissedBannerVersions) || !dismissedBannerVersions.every((version) => isVersion(version, 1)))
+    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const dismissed = [...new Set(dismissedBannerVersions)].sort((a, b) => b - a).slice(0, MAX_DISMISSED_BANNER_VERSIONS);
+
+  return {
+    seenAnnouncementVersion: Math.max(0, seenAnnouncementVersion),
+    dismissedBannerVersions: dismissed,
+  };
+};
+
+export const parseAnnouncementCookieValue = (value: string | null | undefined): AnnouncementCookieState => {
+  if (!value) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  try {
+    return normalizeCookieState(JSON.parse(decodeURIComponent(value)));
+  } catch {
+    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  }
+};
+
+export const parseAnnouncementCookieHeader = (cookieHeader: string | null | undefined): AnnouncementCookieState => {
+  if (!cookieHeader) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ANNOUNCEMENTS_COOKIE}=([^;]+)`));
+  return parseAnnouncementCookieValue(match?.[1]);
+};
+
+export const serializeAnnouncementCookieState = (state: AnnouncementCookieState): string =>
+  encodeURIComponent(JSON.stringify(normalizeCookieState(state)));
+
+export const mergeAnnouncementCookieState = (
+  current: AnnouncementCookieState,
+  patch: Partial<AnnouncementCookieState>,
+): AnnouncementCookieState =>
+  normalizeCookieState({
+    seenAnnouncementVersion: Math.max(current.seenAnnouncementVersion, patch.seenAnnouncementVersion ?? 0),
+    dismissedBannerVersions: [...current.dismissedBannerVersions, ...(patch.dismissedBannerVersions ?? [])],
+  });

package/src/contracts/announcements.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
-
-export const ANNOUNCEMENTS_COOKIE = "cloud_announcements";
-export const ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
-export const MAX_DISMISSED_BANNER_VERSIONS = 50;
+import type { AnnouncementCookieState } from "./announcement-cookie";
+
+export {
+  ANNOUNCEMENTS_COOKIE,
+  ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
+  type AnnouncementCookieState,
+  DEFAULT_ANNOUNCEMENT_COOKIE_STATE,
+  MAX_DISMISSED_BANNER_VERSIONS,
+  mergeAnnouncementCookieState,
+  parseAnnouncementCookieHeader,
+  parseAnnouncementCookieValue,
+  serializeAnnouncementCookieState,
+} from "./announcement-cookie";
 
 export const AnnouncementKindSchema = z.enum(["announcement", "banner"]);
 export type AnnouncementKind = z.infer<typeof AnnouncementKindSchema>;
@@ -13,13 +22,7 @@ export type AnnouncementTone = z.infer<typeof AnnouncementToneSchema>;
 export const AnnouncementCookieStateSchema = z.object({
   seenAnnouncementVersion: z.number().int().nonnegative().default(0),
   dismissedBannerVersions: z.array(z.number().int().positive()).default([]),
-});
-export type AnnouncementCookieState = z.infer<typeof AnnouncementCookieStateSchema>;
-
-export const DEFAULT_ANNOUNCEMENT_COOKIE_STATE: AnnouncementCookieState = {
-  seenAnnouncementVersion: 0,
-  dismissedBannerVersions: [],
-};
+}) satisfies z.ZodType<AnnouncementCookieState>;
 
 export const AnnouncementEntrySchema = z.object({
   id: z.uuid(),
@@ -78,44 +81,3 @@ export const ActiveAnnouncementsResponseSchema = z.object({
   latestAnnouncementVersion: z.number().int().nonnegative(),
 });
 export type ActiveAnnouncementsResponse = z.infer<typeof ActiveAnnouncementsResponseSchema>;
-
-const normalizeCookieState = (value: unknown): AnnouncementCookieState => {
-  const parsed = AnnouncementCookieStateSchema.safeParse(value);
-  if (!parsed.success) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  const dismissed = [...new Set(parsed.data.dismissedBannerVersions)]
-    .filter((version) => Number.isInteger(version) && version > 0)
-    .sort((a, b) => b - a)
-    .slice(0, MAX_DISMISSED_BANNER_VERSIONS);
-
-  return {
-    seenAnnouncementVersion: Math.max(0, parsed.data.seenAnnouncementVersion),
-    dismissedBannerVersions: dismissed,
-  };
-};
-
-export const parseAnnouncementCookieValue = (value: string | null | undefined): AnnouncementCookieState => {
-  if (!value) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  try {
-    return normalizeCookieState(JSON.parse(decodeURIComponent(value)));
-  } catch {
-    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  }
-};
-
-export const parseAnnouncementCookieHeader = (cookieHeader: string | null | undefined): AnnouncementCookieState => {
-  if (!cookieHeader) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
-  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ANNOUNCEMENTS_COOKIE}=([^;]+)`));
-  return parseAnnouncementCookieValue(match?.[1]);
-};
-
-export const serializeAnnouncementCookieState = (state: AnnouncementCookieState): string =>
-  encodeURIComponent(JSON.stringify(normalizeCookieState(state)));
-
-export const mergeAnnouncementCookieState = (
-  current: AnnouncementCookieState,
-  patch: Partial<AnnouncementCookieState>,
-): AnnouncementCookieState =>
-  normalizeCookieState({
-    seenAnnouncementVersion: Math.max(current.seenAnnouncementVersion, patch.seenAnnouncementVersion ?? 0),
-    dismissedBannerVersions: [...current.dismissedBannerVersions, ...(patch.dismissedBannerVersions ?? [])],
-  });