@k2b/cloud 0.33.0 → 0.34.0

package/src/api/resource-links.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { getCapability } from "../_internal/registry";
+import {
+  CapabilitySemanticLinkSchema,
+  type CloudResourceRef,
+  CloudResourceRefSchema,
+  capabilityResultSchema,
+  cloudResourceRefAppId,
+  resolveCapabilityResourceReader,
+} from "../contracts/capabilities";
+import type { RequestAuthority } from "../server";
+import { dispatchCapability } from "./capabilities";
+
+export const resolveCloudResourceHref = async (
+  params: { ref: CloudResourceRef; request: Request; authority: RequestAuthority; locale?: string },
+  dependencies: { getCapability?: typeof getCapability; dispatch?: typeof dispatchCapability } = {},
+): Promise<string | null> => {
+  const parsed = CloudResourceRefSchema.safeParse(params.ref);
+  if (!parsed.success) return null;
+  const ref = parsed.data;
+  const appId = cloudResourceRefAppId(ref);
+  const app = await (dependencies.getCapability ?? getCapability)(appId);
+  if (!app || app.appId !== appId) return null;
+  const reader = resolveCapabilityResourceReader(app.manifest, ref);
+  if (!reader) return null;
+  const response = await (dependencies.dispatch ?? dispatchCapability)({
+    request: params.request,
+    authority: params.authority,
+    locale: params.locale,
+    origin: "http",
+    kind: "queries",
+    appId,
+    capabilityId: reader.localId,
+    input: { id: ref.id },
+  });
+  if (!response.ok) return null;
+  const result = capabilityResultSchema(z.unknown(), { consumer: true }).safeParse(await response.json());
+  if (!result.success) return null;
+  const link = CapabilitySemanticLinkSchema.safeParse(
+    result.data.links?.find((link) => link.rel === "open") ?? result.data.links?.find((link) => link.rel === "edit"),
+  );
+  return link.success ? link.data.href : null;
+};

package/src/api/widgets.ts

@@ -1,18 +1,26 @@
 import { type Context, Hono, type MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { type DashboardWidget, listWidgets } from "../_internal/registry";
+import { parseWidgetSettings } from "../_internal/widget-settings";
 import {
   type DashboardWidgetSize,
   fitWidgetSize,
   isDashboardWidgetSize,
+  WIDGET_KEY_MAX_LENGTH,
   WIDGET_MAX_RESPONSE_BYTES,
+  WIDGET_REQUEST_MAX_BYTES,
+  WIDGET_REQUEST_MAX_ENTRIES,
+  WIDGET_REQUEST_MAX_ID_LENGTH,
+  WIDGET_SETTINGS_MAX_FIELDS,
   type WidgetResponse,
   WidgetResponseSchema,
   type WidgetStreamLine,
   widgetKey,
 } from "../contracts/widgets";
 import { type AuthContext, auth, preferredLocale, rejectReservedWorkloadCredential } from "../server";
-import { WIDGET_SIZE_PARAM } from "../server/widget-request";
+import { WIDGET_SETTINGS_PARAM, WIDGET_SETTINGS_PARAM_MAX_LENGTH, WIDGET_SIZE_PARAM } from "../server/widget-request";
 import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS } from "../services/identity/constants";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { widgetInvocationOperation } from "../services/identity/invocation-operations";
@@ -49,6 +57,7 @@ type WidgetRejectionReason =
   | "upstream_timeout"
   | "upstream_status"
   | "too_large"
+  | "settings_too_large"
   | "invalid_json"
   | "invalid_schema"
   | "deadline_exceeded"
@@ -84,6 +93,7 @@ const callProvider = async (options: {
   widget: DashboardWidget;
   /** What the browser asked for, fitted to the widget's declared sizes before it reaches the app. */
   size: unknown;
+  settings?: unknown;
   token: string;
   requestId: string | undefined;
   signal: AbortSignal;
@@ -105,6 +115,12 @@ const callProvider = async (options: {
 
     const targetUrl = new URL(`/api/_internal/widgets/v1/${encodeURIComponent(widget.widgetId)}`, widget.url);
     targetUrl.searchParams.set(WIDGET_SIZE_PARAM, fitWidgetSize(options.size, widget));
+    if (widget.settings) {
+      const json = JSON.stringify(parseWidgetSettings(widget.settings, options.settings));
+      const encodedLength = new URLSearchParams([[WIDGET_SETTINGS_PARAM, json]]).toString().length - WIDGET_SETTINGS_PARAM.length - 1;
+      if (encodedLength > WIDGET_SETTINGS_PARAM_MAX_LENGTH) return { status: "error", phase: "provider", reason: "settings_too_large" };
+      targetUrl.searchParams.set(WIDGET_SETTINGS_PARAM, json);
+    }
     signal.throwIfAborted();
     const response = await options.fetch(targetUrl, { headers, signal });
     if (response.status === 204 || response.status === 403) {
@@ -143,6 +159,30 @@ const parseRequestedWidget = (value: string, declared: ReadonlySet<string>): [st
   return isDashboardWidgetSize(size) && declared.has(value.slice(0, at)) ? [value.slice(0, at), size] : [value, undefined];
 };
 
+const WidgetEntriesSchema = z
+  .object({
+    widgets: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(WIDGET_REQUEST_MAX_ID_LENGTH),
+            key: z.string().min(1).max(WIDGET_KEY_MAX_LENGTH),
+            size: z.string().optional(),
+            settings: z
+              .record(z.string(), z.unknown())
+              .refine((values) => Object.keys(values).length <= WIDGET_SETTINGS_MAX_FIELDS)
+              .optional(),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(WIDGET_REQUEST_MAX_ENTRIES)
+      .refine((entries) => new Set(entries.map((entry) => entry.id)).size === entries.length, "Widget entry ids must be unique"),
+  })
+  .strict();
+
+type WidgetEntry = { widget: DashboardWidget; id?: string; size?: string; settings?: unknown };
+
 export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) => {
   const registry = dependencies.listWidgets ?? listWidgets;
   const fetchWidget = dependencies.fetch ?? globalThis.fetch;
@@ -167,6 +207,96 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
       issuer: signer.issuer,
     });
 
+  const stream = async (c: Context<AuthContext>, entries: WidgetEntry[], requestId: string | undefined) => {
+    const streamDeadline = AbortSignal.timeout(WIDGET_STREAM_DEADLINE_MS);
+    // A client that stops reading, such as a browser leaving the dashboard, ends every widget it still waits for.
+    const streamCancelled = new AbortController();
+    const fanoutSignal = AbortSignal.any([c.req.raw.signal, streamDeadline, streamCancelled.signal]);
+    // One signing guard for the whole dashboard, not one Postgres check per widget.
+    let tokens: PromiseSettledResult<Awaited<ReturnType<typeof signInvocationToken>>>[] = [];
+    try {
+      if (entries.length > 0) {
+        const signing = AbortSignal.any([fanoutSignal, AbortSignal.timeout(timeoutMs)]);
+        tokens = await waitWithin(
+          withActiveSigner(
+            "invocation",
+            (signer) =>
+              Promise.all(startBounded(entries, WIDGET_CONCURRENCY, async (entry) => sign(c, entry.widget, requestId, signer), signing)),
+            { signal: signing, timeoutMs },
+          ),
+          signing,
+        );
+      }
+    } catch {
+      log.warn("Widget invocation authority unavailable", { reason: fanoutSignal.aborted ? "deadline_exceeded" : "operation_failed" });
+      return c.json({ message: "Widget invocation authority is currently unavailable" }, 503);
+    }
+
+    const fanoutStarted = performance.now();
+    const settled = startBounded(
+      entries,
+      WIDGET_CONCURRENCY,
+      async (entry, index): Promise<WidgetStreamLine> => {
+        const { widget } = entry;
+        const identity = entry.id === undefined ? {} : { id: entry.id };
+        const key = widgetKey(widget.appId, widget.widgetId);
+        const started = performance.now();
+        const elapsed = () => Math.round(performance.now() - started);
+        const token = tokens[index];
+        if (token?.status !== "fulfilled") {
+          logRejection(widget, "signing", "operation_failed");
+          return { type: "widget", ...identity, key, status: "error", ms: elapsed() };
+        }
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const outcome = await callProvider({
+          c,
+          widget,
+          token: token.value.token,
+          requestId,
+          signal: AbortSignal.any([fanoutSignal, timeout]),
+          timeout,
+          fetch: fetchWidget,
+          size: entry.size,
+          settings: entry.settings,
+        });
+        if (outcome.status === "ok") return { type: "widget", ...identity, key, status: "ok", widget: outcome.widget, ms: elapsed() };
+        // A widget the stream itself stopped has already been settled, and is logged once, below.
+        if ("reason" in outcome && !fanoutSignal.aborted) logRejection(widget, outcome.phase, outcome.reason, outcome.upstreamStatus);
+        return { type: "widget", ...identity, key, status: outcome.status, ms: elapsed() };
+      },
+      fanoutSignal,
+    );
+
+    return ndjsonStream<WidgetStreamLine>({
+      first: { type: "start", widgets: entries.map((entry) => entry.id ?? widgetKey(entry.widget.appId, entry.widget.widgetId)) },
+      pending: settled.map((pending, index) =>
+        pending.then((result): WidgetStreamLine => {
+          if (result.status === "fulfilled") return result.value;
+          // Only the stream's own deadline or the browser leaving settles a widget this way. Leaving is not a
+          // failure of the widget, so only the deadline is logged.
+          const entry = entries[index]!;
+          const { widget } = entry;
+          const status = streamDeadline.aborted ? "timeout" : "error";
+          if (streamDeadline.aborted) logRejection(widget, "provider", "deadline_exceeded");
+          return {
+            type: "widget",
+            ...(entry.id === undefined ? {} : { id: entry.id }),
+            key: widgetKey(widget.appId, widget.widgetId),
+            status,
+            ms: Math.round(performance.now() - fanoutStarted),
+          };
+        }),
+      ),
+      last: (lines) => ({
+        type: "done",
+        status: lines.some((line) => line.type === "widget" && (line.status === "timeout" || line.status === "error"))
+          ? "partial"
+          : "complete",
+      }),
+      onCancel: () => streamCancelled.abort(),
+    });
+  };
+
   return (
     new Hono<AuthContext>()
       .use(dependencies.authenticate ?? auth.requireRole("authenticated"))
@@ -197,89 +327,40 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
           return c.json({ message: "Widget registry is currently unavailable" }, 503);
         }
 
-        const streamDeadline = AbortSignal.timeout(WIDGET_STREAM_DEADLINE_MS);
-        // A client that stops reading, such as a browser leaving the dashboard, ends every widget it still waits for.
-        const streamCancelled = new AbortController();
-        const fanoutSignal = AbortSignal.any([c.req.raw.signal, streamDeadline, streamCancelled.signal]);
-        // One signing guard for the whole dashboard, not one Postgres check per widget.
-        let tokens: PromiseSettledResult<Awaited<ReturnType<typeof signInvocationToken>>>[] = [];
-        try {
-          if (widgets.length > 0) {
-            const signing = AbortSignal.any([fanoutSignal, AbortSignal.timeout(timeoutMs)]);
-            tokens = await waitWithin(
-              withActiveSigner(
-                "invocation",
-                (signer) =>
-                  Promise.all(startBounded(widgets, WIDGET_CONCURRENCY, async (widget) => sign(c, widget, requestId, signer), signing)),
-                { signal: signing, timeoutMs },
-              ),
-              signing,
-            );
-          }
-        } catch {
-          log.warn("Widget invocation authority unavailable", { reason: fanoutSignal.aborted ? "deadline_exceeded" : "operation_failed" });
-          return c.json({ message: "Widget invocation authority is currently unavailable" }, 503);
-        }
-
-        const fanoutStarted = performance.now();
-        const settled = startBounded(
-          widgets,
-          WIDGET_CONCURRENCY,
-          async (widget, index): Promise<WidgetStreamLine> => {
-            const key = widgetKey(widget.appId, widget.widgetId);
-            const started = performance.now();
-            const elapsed = () => Math.round(performance.now() - started);
-            const token = tokens[index];
-            if (token?.status !== "fulfilled") {
-              logRejection(widget, "signing", "operation_failed");
-              return { type: "widget", key, status: "error", ms: elapsed() };
-            }
-            const timeout = AbortSignal.timeout(timeoutMs);
-            const outcome = await callProvider({
-              c,
-              widget,
-              token: token.value.token,
-              requestId,
-              signal: AbortSignal.any([fanoutSignal, timeout]),
-              timeout,
-              fetch: fetchWidget,
-              size: requested.get(key),
-            });
-            if (outcome.status === "ok") return { type: "widget", key, status: "ok", widget: outcome.widget, ms: elapsed() };
-            // A widget the stream itself stopped has already been settled, and is logged once, below.
-            if ("reason" in outcome && !fanoutSignal.aborted) logRejection(widget, outcome.phase, outcome.reason, outcome.upstreamStatus);
-            return { type: "widget", key, status: outcome.status, ms: elapsed() };
-          },
-          fanoutSignal,
+        return stream(
+          c,
+          widgets.map((widget) => ({ widget, size: requested.get(widgetKey(widget.appId, widget.widgetId)) })),
+          requestId,
         );
-
-        return ndjsonStream<WidgetStreamLine>({
-          first: { type: "start", widgets: widgets.map((widget) => widgetKey(widget.appId, widget.widgetId)) },
-          pending: settled.map((pending, index) =>
-            pending.then((result): WidgetStreamLine => {
-              if (result.status === "fulfilled") return result.value;
-              // Only the stream's own deadline or the browser leaving settles a widget this way. Leaving is not a
-              // failure of the widget, so only the deadline is logged.
-              const widget = widgets[index]!;
-              const status = streamDeadline.aborted ? "timeout" : "error";
-              if (streamDeadline.aborted) logRejection(widget, "provider", "deadline_exceeded");
-              return {
-                type: "widget",
-                key: widgetKey(widget.appId, widget.widgetId),
-                status,
-                ms: Math.round(performance.now() - fanoutStarted),
-              };
-            }),
-          ),
-          last: (lines) => ({
-            type: "done",
-            status: lines.some((line) => line.type === "widget" && (line.status === "timeout" || line.status === "error"))
-              ? "partial"
-              : "complete",
-          }),
-          onCancel: () => streamCancelled.abort(),
-        });
       })
+      .post(
+        "/widgets/v1",
+        bodyLimit({ maxSize: WIDGET_REQUEST_MAX_BYTES, onError: (c) => c.json({ message: "Widget request is too large" }, 400) }),
+        async (c) => {
+          let raw: unknown;
+          try {
+            raw = await c.req.json();
+          } catch {
+            return c.json({ message: "Invalid widget request JSON" }, 400);
+          }
+          const parsed = WidgetEntriesSchema.safeParse(raw);
+          if (!parsed.success) return c.json({ message: "Invalid widget request" }, 400);
+          const setup = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(timeoutMs)]);
+          let declared: DashboardWidget[];
+          try {
+            declared = await waitWithin(registry(), setup);
+          } catch {
+            log.warn("Widget registry unavailable", { reason: setup.aborted ? "deadline_exceeded" : "operation_failed" });
+            return c.json({ message: "Widget registry is currently unavailable" }, 503);
+          }
+          const byKey = new Map(declared.map((widget) => [widgetKey(widget.appId, widget.widgetId), widget]));
+          const entries = parsed.data.widgets.flatMap((entry) => {
+            const widget = byKey.get(entry.key);
+            return widget ? [{ ...entry, widget }] : [];
+          });
+          return stream(c, entries, normalizeInvocationRequestId(c.req.header("x-request-id")));
+        },
+      )
       .get("/widgets/v1/:appId/:widgetId", async (c) => {
         const timeout = AbortSignal.timeout(timeoutMs);
         const signal = AbortSignal.any([c.req.raw.signal, timeout]);

package/src/browser/CloudResourceSearch.tsx

@@ -1,9 +1,8 @@
 import { timed } from "@k2b/stdlib/solid";
-import { announce, Button, IconButton, ScrollArea, useLocale } from "@k2b/ui";
+import { announce, Button, IconButton, Kbd, ScrollArea, useLocale } from "@k2b/ui";
 import { createEffect, createMemo, createSignal, createUniqueId, For, on, onCleanup, onMount, Show } from "solid-js";
 import type { SearchApp, SearchItem } from "../api/search/schemas";
 import type { CloudResourceRef } from "../contracts";
-import { shortcutLabel } from "./command-shortcuts";
 import { matchNavigationSearchItems, type NavigationSearchItem } from "./navigation-search";
 import { cloudResourceSearchUrl, filterCloudResourceSearchItems } from "./resource-search";
 import { commitTypedTags, matchingSearchTags, searchTags, tagAtCursor } from "./resource-search-input";
@@ -39,6 +38,7 @@ export type CloudResourceSearchProps = {
   navigationError?: string;
   placeholder?: string;
   requireReader?: boolean;
+  resourceType?: string;
   navigationItems?: readonly NavigationSearchItem[];
   searchResources?: boolean;
   excludeRefs?: readonly CloudResourceRef[];
@@ -668,9 +668,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                             <span>{item.title}</span>
                             <small>{item.preview ?? item.appName}</small>
                           </span>
-                          <Show when={commandFor(item)?.shortcut}>
-                            {(shortcut) => <kbd class="shrink-0 text-xs text-dimmed">{shortcutLabel(shortcut())}</kbd>}
-                          </Show>
+                          <Show when={commandFor(item)?.shortcut}>{(shortcut) => <Kbd keys={shortcut()} />}</Show>
                           <Show when={props.selectionMode && selectedKey() === itemKey(item)}>
                             <i class="ti ti-check" aria-hidden="true" />
                           </Show>
@@ -792,7 +790,9 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                     (!activeItem() || !commandFor(activeItem()!) || isLinkableCommand(commandFor(activeItem()!)!))
                   }
                 >
-                  <span>⌘/Ctrl ↵ {t().newTab}</span>
+                  <span>
+                    <Kbd keys="mod+enter" /> {t().newTab}
+                  </span>
                 </Show>
               </div>
             }

package/src/browser/command-shortcuts.ts

@@ -1,6 +1,7 @@
+import { keyboardPlatform } from "@k2b/ui";
 import { COMMANDS_CHANGED, type ContextAwareCommand, collectContextAwareCommands } from "./command-bridge";
 
-const isMac = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
+const isMac = () => keyboardPlatform() === "apple";
 const modifiers = ["ctrl", "alt", "shift", "meta"] as const;
 type Combination = { key: string; ctrl: boolean; alt: boolean; shift: boolean; meta: boolean };
 
@@ -26,16 +27,6 @@ export const contextCommandsWithShortcuts = (): ContextAwareCommand[] => {
   }));
 };
 
-export const shortcutLabel = (shortcut: string): string => {
-  const combination = parse(shortcut);
-  if (!combination) return "";
-  const mac = isMac();
-  const names = { ctrl: mac ? "⌃" : "Ctrl", alt: mac ? "⌥" : "Alt", shift: mac ? "⇧" : "Shift", meta: mac ? "⌘" : "Meta" };
-  const arrows: Record<string, string> = { arrowup: "↑", arrowdown: "↓", arrowleft: "←", arrowright: "→" };
-  const key = arrows[combination.key] ?? combination.key.toUpperCase();
-  return [...modifiers.filter((name) => combination[name]).map((name) => names[name]), key].join(mac ? "" : "+");
-};
-
 const ARROWS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright"]);
 
 /**

package/src/browser/resource-picker.tsx

@@ -12,6 +12,7 @@ export type CloudResourcePickerOptions = {
   initialAppId?: string;
   excludeRefs?: readonly CloudResourceRef[];
   requireReader?: boolean;
+  resourceType?: string;
 };
 
 export const openCloudResourcePicker = (options: CloudResourcePickerOptions = {}): Promise<CloudResourcePickerItem | undefined> => {

package/src/browser/resource-search.ts

@@ -27,8 +27,13 @@ export const cloudResourceSearchUrl = (request: {
 
 export const filterCloudResourceSearchItems = (
   items: readonly SearchItem[],
-  options: { excludeRefs?: readonly CloudResourceRef[]; requireReader?: boolean },
+  options: { excludeRefs?: readonly CloudResourceRef[]; requireReader?: boolean; resourceType?: string },
 ): SearchItem[] => {
   const excluded = new Set((options.excludeRefs ?? []).map(refKey));
-  return items.filter((item) => (!options.requireReader || item.readable) && !excluded.has(refKey(item.ref)));
+  return items.filter(
+    (item) =>
+      (options.resourceType === undefined || item.ref.type === options.resourceType) &&
+      (!options.requireReader || item.readable) &&
+      !excluded.has(refKey(item.ref)),
+  );
 };

package/src/browser/widgets.ts

@@ -1,17 +1,29 @@
-import type { DashboardWidgetSize, WidgetStreamLine } from "../contracts/widgets";
+import type { DashboardWidgetSize, WidgetSettings, 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";
+export type {
+  DashboardWidgetSize,
+  WidgetResponse,
+  WidgetSettingField,
+  WidgetSettings,
+  WidgetSettingsDeclaration,
+  WidgetSettingValue,
+  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.
+ * stops every widget Core still waits for. When `requests` is given, POST sends one invocation per entry with its
+ * settings, ignoring `keys` and `sizes`; start and widget lines identify entries by id. Rejects when the request fails
+ * or the stream breaks off.
  */
 export const streamWidgets = async (options: {
+  requests?: readonly { id: string; key: string; size?: DashboardWidgetSize; settings?: WidgetSettings }[];
   keys?: readonly string[];
   sizes?: Readonly<Record<string, DashboardWidgetSize>>;
   signal: AbortSignal;
@@ -19,11 +31,17 @@ export const streamWidgets = async (options: {
   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);
+  for (const key of options.requests ? [] : (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}` : ""}`, {
+    ...(options.requests ? { method: "POST", body: JSON.stringify({ widgets: options.requests }) } : {}),
     signal: options.signal,
-    headers: { accept: NDJSON_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+    headers: {
+      accept: NDJSON_CONTENT_TYPE,
+      [LOCALE_HEADER]: options.locale,
+      ...(options.requests ? { "content-type": "application/json" } : {}),
+    },
   });
   if (!response.ok) throw new Error(`Widgets failed with ${response.status}`);
   await readNdjsonLines(response, options.onLine, "Widgets");

package/src/capabilities/testing.ts

@@ -1,5 +1,10 @@
 import { capabilityManifestEvolutionIssues, compileCapabilities } from "../_internal/capabilities";
-import type { CapabilityDefinitions, CapabilityManifest } from "../contracts/capabilities";
+import {
+  type CapabilityDefinitions,
+  type CapabilityManifest,
+  type CapabilityResult,
+  CapabilitySemanticLinkSchema,
+} from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
 export const compileCapabilityManifest = (appId: string, definitions: CapabilityDefinitions): CapabilityManifest =>
@@ -10,3 +15,10 @@ export const assertCapabilityManifestEvolution = (previous: CapabilityManifest,
   const issues = capabilityManifestEvolutionIssues(previous, next);
   if (issues.length > 0) throw new Error(`Breaking Capability manifest evolution:\n- ${issues.join("\n- ")}`);
 };
+
+/** Assert that a reader result exposes a valid destination for its resource permalink. */
+export const assertResourceOpenLink = (result: Pick<CapabilityResult<unknown>, "links">) => {
+  const link = result.links?.find((link) => link.rel === "open");
+  if (!link) throw new Error("Resource reader must return a top-level open link");
+  return CapabilitySemanticLinkSchema.parse(link);
+};

package/src/cli/capabilities.ts

@@ -6,6 +6,8 @@ import {
   CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
+  type CapabilityManifest,
+  CapabilitySemanticLinkSchema,
   CapabilityStreamSchema,
   CloudResourceRefSchema,
   capabilityResultSchema,
@@ -14,6 +16,7 @@ import {
 } from "../contracts/capabilities";
 import { saveCapabilityStream } from "./capability-streams";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, defineCliCommands, flag, readCliInput } from "./index";
+import { cloudResourceUrl } from "./resource-links";
 
 const parseInput = async (input: CliInputFlagValue): Promise<unknown> => {
   const raw = await readCliInput(input, {
@@ -65,6 +68,26 @@ const readCapabilityJson = async (response: Response, maxBytes: number): Promise
   return parsed.data;
 };
 
+const findCatalogApps = async (ctx: CloudCliContext, appIds: ReadonlySet<string>) => {
+  const wantedApps = new Set(appIds);
+  const apps: z.infer<typeof CapabilityCatalogSchema>["apps"] = [];
+  let cursor: string | undefined;
+  const seenCursors = new Set<string>();
+  while (wantedApps.size) {
+    const query = new URLSearchParams({ limit: "25" });
+    if (cursor) query.set("cursor", cursor);
+    const page = CapabilityCatalogSchema.parse(
+      await readCapabilityJson(await ctx.fetch(`/api/capabilities/v1/catalog?${query}`), CAPABILITY_MAX_CATALOG_BYTES),
+    );
+    for (const app of page.apps) if (wantedApps.delete(app.appId)) apps.push(app);
+    if (!wantedApps.size || !page.page.hasMore) break;
+    cursor = page.page.nextCursor;
+    if (seenCursors.has(cursor)) throw new Error("Capability catalog returned a repeated cursor.");
+    seenCursors.add(cursor);
+  }
+  return apps;
+};
+
 const invoke = async (config: {
   ctx: CloudCliContext;
   kind: "queries" | "actions";
@@ -72,6 +95,7 @@ const invoke = async (config: {
   capabilityId: string;
   input?: CliInputFlagValue;
   inputValue?: unknown;
+  manifest?: CapabilityManifest;
   idempotencyKey?: string;
 }) => {
   const headers = new Headers({ "content-type": "application/json" });
@@ -113,7 +137,40 @@ const invoke = async (config: {
     }
     throw error;
   }
-  printGenericResult(config.ctx, capabilityResultSchema(z.unknown()).parse(body));
+  const result = capabilityResultSchema(z.unknown()).parse(body);
+  const manifests = config.manifest ? [config.manifest] : [];
+  const wantedApps = new Set((result.refs ?? []).map(cloudResourceRefAppId));
+  for (const manifest of manifests) wantedApps.delete(manifest.appId);
+  if (wantedApps.size) {
+    try {
+      const apps = await findCatalogApps(config.ctx, wantedApps);
+      manifests.push(...apps.map((app) => app.manifest));
+    } catch {
+      config.ctx.error("The capability catalog is unavailable; some resource permalinks could not be added.");
+    }
+  }
+  const absoluteLinks = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(absoluteLinks);
+    if (!value || typeof value !== "object") return value;
+    const link = CapabilitySemanticLinkSchema.safeParse(value);
+    if (link.success) return { ...link.data, href: new URL(link.data.href, config.ctx.options.server).href };
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, absoluteLinks(nested)]));
+  };
+  printGenericResult(
+    config.ctx,
+    absoluteLinks({
+      ...result,
+      ...(result.refs
+        ? {
+            refs: result.refs.map((ref) =>
+              ref.id.isWellFormed() && manifests.some((manifest) => resolveCapabilityResourceReader(manifest, ref))
+                ? { ...ref, permalink: cloudResourceUrl(config.ctx, ref) }
+                : ref,
+            ),
+          }
+        : {}),
+    }),
+  );
 };
 
 export default defineCliCommands({
@@ -230,25 +287,12 @@ export default defineCliCommands({
       run: async ({ ctx, args }) => {
         const ref = CloudResourceRefSchema.parse({ type: args.type, id: args.id });
         const appId = cloudResourceRefAppId(ref);
-        let cursor: string | undefined;
-        const seenCursors = new Set<string>();
-        let app: z.infer<typeof CapabilityCatalogSchema>["apps"][number] | undefined;
-        do {
-          const query = new URLSearchParams({ limit: "25" });
-          if (cursor) query.set("cursor", cursor);
-          const page = CapabilityCatalogSchema.parse(
-            await readCapabilityJson(await ctx.fetch(`/api/capabilities/v1/catalog?${query}`), CAPABILITY_MAX_CATALOG_BYTES),
-          );
-          app = page.apps.find((candidate) => candidate.appId === appId);
-          const nextCursor = page.page.hasMore ? page.page.nextCursor : undefined;
-          if (nextCursor && seenCursors.has(nextCursor)) throw new Error("Capability catalog returned a repeated cursor.");
-          if (nextCursor) seenCursors.add(nextCursor);
-          cursor = nextCursor;
-        } while (!app && cursor);
+        const apps = await findCatalogApps(ctx, new Set([appId]));
+        const app = apps.find((candidate) => candidate.appId === appId);
         if (!app) throw new Error(`Capability app ${appId} is unavailable.`);
         const reader = resolveCapabilityResourceReader(app.manifest, ref);
         if (!reader) throw new Error(`Cloud resource type ${ref.type} is unknown or has no reader.`);
-        await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id } });
+        await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id }, manifest: app.manifest });
       },
     }),
     command("action", {

package/src/cli/index.ts

@@ -100,3 +100,5 @@ export * from "./commands";
 export * from "./locale";
 export * from "./output";
 export * from "./plugin";
+
+export * from "./resource-links";

package/src/cli/resource-links.ts

@@ -0,0 +1,13 @@
+import type { CloudResourceRef } from "../contracts/capabilities";
+import { cloudResourceHref } from "../contracts/resource-href";
+import type { CloudCliContext } from "./index";
+
+export const cloudResourceUrl = (ctx: Pick<CloudCliContext, "options">, ref: CloudResourceRef): string =>
+  new URL(cloudResourceHref(ref), ctx.options.server).href;
+
+/** The resource id must be the id its Type's reader accepts. */
+export const withCloudResourcePermalink = <T extends { id: string }>(
+  ctx: Pick<CloudCliContext, "options">,
+  type: CloudResourceRef["type"],
+  resource: T,
+) => ({ ...resource, permalink: cloudResourceUrl(ctx, { type, id: resource.id }) });