@k2b/cloud 0.29.1 → 0.30.0

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/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 ?? [])],
-  });

package/src/contracts/capabilities.ts

@@ -349,6 +349,26 @@ export type CapabilityUniversalSearchDefinition = {
 
 export type CapabilitySchemaPresentation = Readonly<Record<string, string>>;
 
+/**
+ * What one Action does, in words people read in approvals, receipts, and step rows. Each sentence is a
+ * template: `{input.to}` inserts a field of the validated call input by its dotted schema path, and
+ * `done` may also read the Action's result data with `{data.id}`. Cloud inserts values as escaped,
+ * bounded plain text, formats fields with a `date` or `date-time` schema format for the reader, and
+ * names an object by its email, address, or path before its display name. A sentence whose value is
+ * missing falls back to the generic wording, so every sentence stays optional. A `done` sentence
+ * replaces the result's runtime summary in the receipt.
+ */
+export type CapabilityActionSentences = {
+  /** What will happen, as a short instruction: "Send email to {input.to}". */
+  approval?: string;
+  /** What happened after the Action ran: "Sent email to {input.to}". */
+  done?: string;
+  /** What did not happen because the person rejected it: "Did not send email to {input.to}". */
+  rejected?: string;
+  /** What did not happen because the turn ended first: "Email to {input.to} not sent". */
+  notRun?: string;
+};
+
 export type CapabilityOperationPresentationTranslation = {
   title?: string;
   description?: string;
@@ -358,6 +378,8 @@ export type CapabilityOperationPresentationTranslation = {
   data?: CapabilitySchemaPresentation;
   /** Search-tag presentation keyed by the stable tag token. */
   searchTags?: Readonly<Record<string, { title?: string; description?: string }>>;
+  /** Actions only: the complete set of sentences in this locale. */
+  sentences?: CapabilityActionSentences;
 };
 
 export type CapabilityPresentationTranslation = {
@@ -370,6 +392,8 @@ export type CapabilityPresentationTranslation = {
 export type CapabilityPresentationCatalog = {
   /** Locale of the complete Type, Query, Action, search-tag, and schema presentation. */
   baseLocale: string;
+  /** Optional Action sentences in the base locale, keyed by Action local ID. */
+  sentences?: Readonly<Record<string, CapabilityActionSentences>>;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, CapabilityPresentationTranslation>>;
 };

package/src/contracts/pwa-paths.ts

@@ -1,6 +1,11 @@
 /**
- * Paths of the installable mobile app, without schemas, so browser code that runs on every page can test for an
- * app page without loading the contract's validators.
+ * Paths and ids of the installable mobile app, without schemas, so browser code that runs on every page can test for
+ * an app page without loading the contract's validators.
  */
 export const PWA_SCOPE = "/pwa/";
 export const PWA_AUTH_PATH = "/pwa/_auth";
+export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
+/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
+export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
+/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
+export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);

package/src/contracts/pwa.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { PWA_AUTH_PATH, PWA_SCOPE } from "./pwa-paths";
+import { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "./pwa-paths";
 
-export { PWA_AUTH_PATH, PWA_SCOPE };
+export { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH };
 
 /**
  * The installable mobile app (preview). One shell application `pwa` owns the
@@ -11,11 +11,6 @@ export { PWA_AUTH_PATH, PWA_SCOPE };
 export const PWA_SHELL_APP_ID = "pwa";
 export const PWA_API_PATH = "/api/auth/pwa/v1";
 export const PWA_MANIFEST_PATH = "/pwa/manifest.webmanifest";
-export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
-/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
-export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
-/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
-export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);
 /**
  * The page canvas of the app (`--k2b-surface-canvas` of `@k2b/ui`) in light and dark. App documents paint it
  * before any stylesheet loads and give it to the status bar.

package/src/contracts/registry.ts

@@ -88,6 +88,7 @@ export type AppRegistryEntry = {
   adminNav?: AppAdminNavigationGroup[];
   capabilities?: AppRegistryCapabilitySummary;
   help?: AppRegistryHelpSummary;
+  skills?: { manifestHash: string };
   legalLinks?: AppRegistryLegalLink[];
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */

package/src/contracts/shared.ts

@@ -329,6 +329,11 @@ export const AccessEntrySchema = z.object({
   avatarHash: z.string().nullable().optional(),
   /** Kind of a `service_account` principal; presentation only, never authorization. */
   serviceAccountKind: ServiceAccountKindSchema.optional(),
+  /**
+   * A narrower part of the resource the grant covers, defined by the application, such as Mail's
+   * `assigned` conversations. Absent for a grant on the whole resource.
+   */
+  scope: z.string().min(1).max(64).optional(),
 });
 export type AccessEntry = z.infer<typeof AccessEntrySchema>;
 

package/src/contracts/widgets.ts

@@ -181,3 +181,23 @@ export const WidgetResponseSchema = z
   })
   .strip();
 export type WidgetResponse = z.infer<typeof WidgetResponseSchema>;
+
+/** A widget's stable key on the dashboard and in the widget stream: `<appId>/<widgetId>`. */
+export const widgetKey = (appId: string, widgetId: string): string => `${appId}/${widgetId}`;
+
+/**
+ * How one widget answered in the widget stream: `ok` carries its response, `empty` is a `204`, `forbidden` a `403`,
+ * `timeout` means it did not answer within its own budget, and `error` covers every other failure.
+ */
+export type WidgetStreamStatus = "ok" | "empty" | "forbidden" | "timeout" | "error";
+
+/**
+ * One line of `GET /api/widgets/v1` (`application/x-ndjson`): `start` names the widgets Core asks, in registry
+ * order; one `widget` line follows per widget in the order they finish; `done` closes the stream. Every widget named
+ * in `start` gets exactly one line.
+ */
+export type WidgetStreamLine =
+  | { type: "start"; widgets: string[] }
+  | { type: "widget"; key: string; status: "ok"; widget: WidgetResponse; ms: number }
+  | { type: "widget"; key: string; status: Exclude<WidgetStreamStatus, "ok">; ms: number }
+  | { type: "done"; status: "complete" | "partial" };

package/src/index.ts

@@ -35,6 +35,7 @@ export {
 export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibility";
 export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
 export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
+export { type AppSkillDefinition, skill } from "./ai/app-skills";
 export { defineCapabilities } from "./contracts/capabilities";
 export type {
   AnyBoundNotificationDefinition,

package/src/server/help.ts

@@ -3,6 +3,7 @@ import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
 import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+import { auth } from "./middleware/auth";
 
 const metadataSchema = z.object({
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
@@ -133,6 +134,9 @@ export const defineHelp = (
  * Define one app-owned help corpus. The explicit source list is deliberate:
  * IDs, ordering and ownership stay visible in code; no filesystem scanning or
  * build-time convention is required.
+ *
+ * @deprecated Declare Help with `defineHelp()` and pass it to `app.start({ help })`. This router only
+ * requires sign-in; it does not apply the app's Help visibility, so the mounting app's routes must guard it.
  */
 export const defineHelpCollection = (options: { basePath: string; sources: readonly string[] }): HelpCollection => {
   const basePath = options.basePath.replace(/\/$/, "");
@@ -151,7 +155,10 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
     url: `${basePath}/${encodeURIComponent(id)}`,
   }));
 
-  const router = new Hono()
+  // Help is for signed-in people wherever an app mounts this router; its own route policy may narrow it further.
+  const router = new Hono();
+  router.use(auth.requireRole("authenticated"), auth.requireUser());
+  router
     .get("/search", (context) => {
       const query = context.req.query("q")?.trim().toLocaleLowerCase().slice(0, 200) ?? "";
       const payload: HelpSearchPayload = {

package/src/services/accounts/users.ts

@@ -223,6 +223,21 @@ export const getMinimal = async (params: { id: string } | { uid: string }): Prom
   return buildUserMutationTarget(rows[0]!);
 };
 
+/** Audience roles for a resolved access subject, including delegated users and group managers. */
+export const getRoles = async (userId: string): Promise<Role[]> => {
+  const { groupsAdmin } = await getFreeIpaConfig();
+  const [row] = await sql<DbRow[]>`SELECT u.provider, u.profile,
+    CASE WHEN u.provider='local' THEN u.admin ELSE EXISTS (
+      SELECT 1 FROM auth.ipa_user_effective_groups eg WHERE eg.user_id=u.id
+        AND eg.group_name=ANY(${toPgTextArray(groupsAdmin)}::text[])
+    ) END AS effective_admin,
+    ARRAY(${managedGroupsNamesSubquery(sql`u.id`)}) AS manages
+    FROM auth.users u WHERE u.id=${userId}::uuid`;
+  if (!row) return [];
+  const { provider, profile } = resolveProviderProfile(row);
+  return buildRoles({ provider, profile, memberofGroup: [], manages: stringArray(row.manages), admin: Boolean(row.effective_admin) });
+};
+
 export const getByUid = async (params: { uid: string }): Promise<{ id: string; roles: Role[] } | null> => {
   const { groupsAdmin } = await getFreeIpaConfig();
   const rows = await sql<DbRow[]>`