@k2b/cloud 0.38.0 → 0.40.0

package/src/browser/panel.ts

@@ -0,0 +1,65 @@
+import type { PanelPageContext } from "../contracts/panel-context";
+import {
+  PAGE_CONTEXT_CHANGED,
+  PAGE_CONTEXT_COLLECT,
+  PANEL_CONTEXT_CHANGED,
+  type PageContextCollection,
+  type PageContextSource,
+  readProviderContext,
+} from "./panel-context-bridge";
+
+export type PanelRequest = { action: "open"; provider: string; search?: string; accepted: boolean } | { action: "close" | "toggle" };
+
+declare global {
+  interface WindowEventMap {
+    "cloud.panel.request": CustomEvent<PanelRequest>;
+  }
+}
+
+/** Opens a visible provider. False leaves navigation with the caller when this page has no matching slot. */
+export function openPanel(provider: string, options?: { search?: string }): boolean {
+  const detail: PanelRequest = {
+    action: "open",
+    provider,
+    search: typeof options?.search === "string" && options.search.length <= 2048 ? options.search : undefined,
+    accepted: false,
+  };
+  window.dispatchEvent(new CustomEvent("cloud.panel.request", { detail }));
+  return detail.accepted;
+}
+
+/** Closes the panel when it is open. */
+export function closePanel(): void {
+  if (window.parent !== window && document.querySelector("[data-cloud-panel-page]")) {
+    window.parent.postMessage({ type: "cloud.panel.close" }, location.origin);
+    return;
+  }
+  window.dispatchEvent(new CustomEvent<PanelRequest>("cloud.panel.request", { detail: { action: "close" } }));
+}
+
+/** Publish in a reactive effect; dispose the previous call when that source changes or unmounts. */
+export function publishPageContext(context: PageContextSource): () => void {
+  const source = { ...context, ...(context.scope ? { scope: { ...context.scope } } : {}) };
+  const collect = (event: Event) => (event as CustomEvent<PageContextCollection>).detail.sources.push(source);
+  window.addEventListener(PAGE_CONTEXT_COLLECT, collect);
+  window.dispatchEvent(new Event(PAGE_CONTEXT_CHANGED));
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    window.removeEventListener(PAGE_CONTEXT_COLLECT, collect);
+    window.dispatchEvent(new Event(PAGE_CONTEXT_CHANGED));
+  };
+}
+
+/** The validated URL snapshot, then the most recent accepted host message. */
+export function getContext(): PanelPageContext | null {
+  return readProviderContext();
+}
+
+/** Called on each accepted change, including null on close or withdrawal. */
+export function onContextChange(cb: (context: PanelPageContext | null) => void): () => void {
+  const changed = () => cb(getContext());
+  window.addEventListener(PANEL_CONTEXT_CHANGED, changed);
+  return () => window.removeEventListener(PANEL_CONTEXT_CHANGED, changed);
+}

package/src/browser/resource-picker.tsx

@@ -6,10 +6,14 @@ import { resourceSearchDialogOptions } from "./resource-search-dialog";
 import { resourceSearchMessages } from "./resource-search-messages";
 
 export type CloudResourcePickerItem = SearchItem;
+/** Narrows the search on the server to one app and, optionally, one of its search tags; shown as the removable chip. */
+export type CloudResourcePickerScope = { appId: string; tag?: string; label: string; icon?: string };
 export type CloudResourcePickerOptions = {
   title?: string;
   placeholder?: string;
   initialAppId?: string;
+  scope?: CloudResourcePickerScope;
+  query?: string;
   excludeRefs?: readonly CloudResourceRef[];
   requireReader?: boolean;
   resourceType?: string;
@@ -20,7 +24,14 @@ export const openCloudResourcePicker = (options: CloudResourcePickerOptions = {}
   const t = resourceSearchMessages.resolve([locale]).t;
   return dialogCore.open<CloudResourcePickerItem>(
     (close) => (
-      <CloudResourceSearch {...options} title={options.title ?? t.chooseResource} selectionMode onSelect={close} onClose={() => close()} />
+      <CloudResourceSearch
+        {...options}
+        request={options.scope !== undefined || options.query !== undefined ? { scope: options.scope, query: options.query } : undefined}
+        title={options.title ?? t.chooseResource}
+        selectionMode
+        onSelect={close}
+        onClose={() => close()}
+      />
     ),
     // A phone shows the picker as a full-screen sheet; global search keeps its floating card.
     {

package/src/browser/search-commands.ts

@@ -1,12 +1,15 @@
-import { z } from "zod";
 import type { SearchItem } from "../api/search/schemas";
 import { listCapabilityCatalog } from "../capabilities/client";
 import { LOCALE_HEADER } from "../shared/locale";
 import type { ContextAwareCommand } from "./command-bridge";
 
+import { discoverableCommandInput } from "./discoverable-command";
+import { navigationApps } from "./navigation-apps";
+
 export type PaletteCommand = ContextAwareCommand & { appName?: string; keywords?: readonly string[]; context?: boolean };
 export const loadSearchCommands = async (locale: string, signal: AbortSignal): Promise<PaletteCommand[]> => {
   const commands: PaletteCommand[] = [];
+  const { appIds } = navigationApps();
   let cursor: string | undefined;
   do {
     const result = await listCapabilityCatalog({ limit: 25, cursor, signal, headers: { [LOCALE_HEADER]: locale } });
@@ -14,8 +17,8 @@ export const loadSearchCommands = async (locale: string, signal: AbortSignal): P
     for (const app of result.data.apps) {
       for (const command of app.manifest.commands) {
         // Only Commands with a valid empty invocation are globally discoverable.
-        const input = z.fromJSONSchema(structuredClone(command.inputSchema)).safeParse({});
-        if (!input.success) continue;
+        const input = discoverableCommandInput(command, app.appId, appIds);
+        if (!input?.success) continue;
         const id = `${app.appId}.${command.localId}`;
         commands.push({
           id,

package/src/capabilities/client.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
-  CapabilityActionReviewSchema,
+  CapabilityActionReviewDataSchema,
   CapabilityCatalogSchema,
   capabilityResultSchema,
 } from "../contracts/capabilities";
@@ -142,7 +142,7 @@ export const reviewCapabilityAction = async <TInput = unknown>(
       body: JSON.stringify({ input: invocation.input }),
       signal: invocation.signal,
     });
-    return readCapabilityResponse(response, CapabilityActionReviewSchema);
+    return readCapabilityResponse(response, CapabilityActionReviewDataSchema);
   } catch (cause) {
     return unavailable(cause, undefined, clientLocale(options.headers));
   }
@@ -180,4 +180,10 @@ export const resolveCommand = async (
   }
 };
 
+export {
+  actionReview,
+  type CapabilityReviewForms,
+  capabilityReviewRememberScope,
+  capabilityReviewView,
+} from "./reviews";
 export { type CapabilityStreamVerb, transferCapabilityStream } from "./streams";

package/src/capabilities/reviews.ts

@@ -0,0 +1,205 @@
+import { capabilityPersonText, capabilityReviewSentence, capabilitySentenceText } from "../_internal/capability-sentences";
+import {
+  CAPABILITY_MAX_REVIEW_BYTES,
+  type CapabilityActionCallReview,
+  CapabilityActionCallReviewSchema,
+  type CapabilityActionReview,
+  type CapabilityActionReviewData,
+  type CapabilityPreview,
+  type CapabilitySemanticLink,
+  type CapabilitySlot,
+} from "../contracts/capabilities";
+import { canonicalLocale } from "../shared/locale";
+export const capabilityPreviewIssues = (
+  preview: CapabilityPreview | undefined,
+  links: readonly CapabilitySemanticLink[] | undefined,
+  sends = false,
+): string[] => {
+  if (!preview) return [];
+  const issues: string[] = [];
+  const open = links?.some((link) => link.rel === "open");
+  if ("truncated" in preview && preview.truncated && !open) issues.push("A truncated preview requires an open link");
+  if (preview.kind === "message") {
+    if ((Object.values(preview.more ?? {}).some((count) => count > 0) || (preview.moreAttachments ?? 0) > 0) && !open)
+      issues.push("Unlisted recipients or attachments require an open link");
+    if (sends && !preview.from) issues.push("A sends message requires from");
+  }
+  return issues;
+};
+/** Context-free rules shared by the builder and runtime validation. */
+export const capabilityReviewFormIssues = (review: CapabilityActionCallReview): string[] => {
+  const issues: string[] = [];
+  if (canonicalLocale(review.locale) !== review.locale) return ["locale must be a canonical BCP 47 tag"];
+  for (const form of ["confirm", "decline"] as const)
+    if (Array.from(capabilityReviewSentence(review, form, { timeZone: "UTC" })).length > 40)
+      issues.push(`${form} exceeds 40 rendered characters`);
+  issues.push(...capabilityPreviewIssues(review.preview, review.links, review.ask === "sends"));
+  try {
+    if (new TextEncoder().encode(JSON.stringify(review)).byteLength > CAPABILITY_MAX_REVIEW_BYTES) issues.push("Review exceeds 32 KiB");
+  } catch {
+    issues.push("Review is not JSON serializable");
+  }
+  return issues;
+};
+export type CapabilityReviewForms = Pick<CapabilityActionCallReview, "locale" | "sentence">;
+export type SlotNames<Text extends string> = string extends Text
+  ? string
+  : Text extends `${string}{${infer Name}}${infer Rest}`
+    ? Name | SlotNames<Rest>
+    : never;
+type FormNames<Forms extends CapabilityReviewForms> = SlotNames<Extract<Forms["sentence"][keyof Forms["sentence"]], string>>;
+type CheckedForms<Forms extends CapabilityReviewForms> =
+  string extends FormNames<Forms>
+    ? unknown
+    : Exclude<FormNames<Forms>, SlotNames<Forms["sentence"]["action"]>> extends never
+      ? unknown
+      : never;
+type ActionSlotNames<Forms extends CapabilityReviewForms> =
+  string extends FormNames<Forms> ? string : SlotNames<Forms["sentence"]["action"]>;
+/** Build a review without I/O. Literal forms enforce the exact slot set at compile time. */
+export const actionReview = <const Forms extends CapabilityReviewForms, const Slots extends Record<string, CapabilitySlot>>(
+  forms: Forms & CheckedForms<Forms>,
+  slots: Slots & Record<ActionSlotNames<Forms>, CapabilitySlot> & Record<Exclude<keyof Slots, ActionSlotNames<Forms>>, never>,
+  extra?: Omit<CapabilityActionCallReview, "locale" | "sentence" | "slots">,
+): CapabilityActionCallReview => {
+  const review = CapabilityActionCallReviewSchema.parse({ ...forms, slots, ...extra });
+  const issues = capabilityReviewFormIssues(review);
+  if (issues.length) throw new Error(`Invalid Action review:\n- ${issues.join("\n- ")}`);
+  return review;
+};
+export const capabilityReviewRememberScope = (
+  review: CapabilityActionReviewData,
+  approval: "rememberable" | "none" | undefined,
+): string | undefined =>
+  approval !== "rememberable"
+    ? undefined
+    : "sentence" in review
+      ? review.ask === undefined
+        ? review.scope
+        : undefined
+      : review.approvalScope;
+
+type Detail = NonNullable<CapabilityActionReview["details"]>[number];
+/** Today's surfaces read this view; storage and digests always retain the original review. */
+export const capabilityReviewView = (
+  review: CapabilityActionReviewData,
+  context: { timeZone: string },
+): Pick<CapabilityActionReview, "message" | "details" | "links"> => {
+  if (!("sentence" in review)) return review;
+  const de = review.locale.toLowerCase().startsWith("de");
+  const details: Detail[] = [];
+  const row = (en: string, german: string, value: string | number | boolean | undefined, format?: Detail["format"], block = false) => {
+    if (value !== undefined)
+      details.push({
+        label: de ? german : en,
+        value: String(value),
+        ...(format ? { format } : {}),
+        ...(block ? { display: "block" as const } : {}),
+      });
+  };
+  const people = (en: string, german: string, persons: Parameters<typeof capabilityPersonText>[0][] | undefined, more = 0) => {
+    if (persons === undefined && !more) return;
+    const values = (persons ?? []).map(capabilityPersonText);
+    if (more) values.push(de ? `und ${more} weitere` : `and ${more} more`);
+    row(en, german, values.join(", "));
+  };
+  const sentence = (value: { text: string; slots?: Readonly<Record<string, CapabilitySlot>> }) =>
+    capabilitySentenceText(value.text, value.slots ?? {}, { locale: review.locale, timeZone: context.timeZone });
+  const consequence = (value: NonNullable<CapabilityActionCallReview["consequences"]>[number]) =>
+    row(
+      value.mark === "added" ? "Added" : value.mark === "removed" ? "Removed" : "Consequence",
+      value.mark === "added" ? "Neu" : value.mark === "removed" ? "Entfernt" : "Folge",
+      sentence(value),
+    );
+  const p = review.preview;
+  if (p)
+    switch (p.kind) {
+      case "message": {
+        if (p.from) row("From", "Von", capabilityPersonText(p.from));
+        people("To", "An", p.to, p.more?.to);
+        people("Cc", "Cc", p.cc, p.more?.cc);
+        people("Bcc", "Bcc", p.bcc, p.more?.bcc);
+        row("Subject", "Betreff", p.subject);
+        const attachments = (p.attachments ?? []).map((a) => `${a.name}${a.size === undefined ? "" : ` (${a.size} B)`}`);
+        if (p.moreAttachments) attachments.push(de ? `und ${p.moreAttachments} weitere` : `and ${p.moreAttachments} more`);
+        if (p.attachments || p.moreAttachments) row("Attachments", "Anhänge", attachments.join(", "));
+        row("Send at", "Sendezeit", p.sendAt, "date-time");
+        for (const warning of p.warnings ?? []) row("Warning", "Warnung", warning);
+        row("Body", "Text", p.body, p.format === "markdown" ? "markdown" : undefined, true);
+        if (p.truncated)
+          row(
+            "Shortened",
+            "Gekürzt",
+            de ? "Den ganzen Text öffnest du über den Link unten." : "Open the full text through the link below.",
+          );
+        break;
+      }
+      case "event":
+        row("Title", "Titel", p.title);
+        row("Start", "Beginn", p.start, p.allDay || p.start.length === 10 ? "date" : "date-time");
+        row("End", "Ende", p.end, p.allDay || p.end?.length === 10 ? "date" : "date-time");
+        row("All day", "Ganztägig", p.allDay === undefined ? undefined : p.allDay ? (de ? "Ja" : "Yes") : de ? "Nein" : "No");
+        row("Time zone", "Zeitzone", p.timeZone);
+        row("Place", "Ort", p.place);
+        row("Location", "Adresse", p.location);
+        row("Recurrence", "Wiederholung", p.recurrence);
+        people("Attendees", "Teilnehmende", p.attendees);
+        row("Description", "Beschreibung", p.description, undefined, true);
+        break;
+      case "task":
+        row("Title", "Titel", p.title);
+        row("Place", "Ort", p.place);
+        row("Due", "Fällig", p.due, p.due?.length === 10 ? "date" : "date-time");
+        people("Assignees", "Zuständig", p.assignees);
+        row("Status", "Status", p.status);
+        for (const item of p.checklist ?? []) row(item.done ? "Done" : "Open", item.done ? "Erledigt" : "Offen", item.label);
+        if (p.tags) row("Tags", "Tags", p.tags.join(", "));
+        row("Description", "Beschreibung", p.description, undefined, true);
+        break;
+      case "page":
+        row("Title", "Titel", p.title);
+        row("Place", "Ort", p.place);
+        row("Body", "Text", p.body, p.format === "markdown" ? "markdown" : undefined, true);
+        if (p.truncated)
+          row(
+            "Shortened",
+            "Gekürzt",
+            de ? "Den ganzen Text öffnest du über den Link unten." : "Open the full text through the link below.",
+          );
+        for (const change of p.changes ?? [])
+          row(
+            change.change === "added" ? "Added" : "Removed",
+            change.change === "added" ? "Neu" : "Entfernt",
+            change.text,
+            undefined,
+            true,
+          );
+        break;
+      case "file":
+        row("Name", "Name", p.name);
+        row("Place", "Ort", p.place);
+        row("Path", "Pfad", p.path);
+        row("Size", "Größe", p.size);
+        row("Media type", "Medientyp", p.mediaType);
+        row("To", "Ziel", p.to);
+        break;
+      case "rule":
+        row("When", "Wenn", sentence(p.when));
+        row("Does", "Tut", p.does, undefined, true);
+        for (const right of p.may) consequence(right);
+        row("Sees this chat", "Kennt diesen Chat", p.seesChat ? (de ? "Ja" : "Yes") : de ? "Nein" : "No");
+        break;
+      case "fields":
+        for (const field of p.rows) {
+          row(field.label, field.label, field.value, field.format);
+          if (field.before !== undefined) row(`${field.label} (before)`, `${field.label} (vorher)`, field.before, field.format);
+        }
+        break;
+    }
+  for (const value of review.consequences ?? []) consequence(value);
+  return {
+    message: capabilitySentenceText(review.sentence.action, review.slots, { locale: review.locale, timeZone: context.timeZone }),
+    ...(details.length ? { details } : {}),
+    ...(review.links ? { links: review.links } : {}),
+  };
+};

package/src/capabilities/server.ts

@@ -6,7 +6,7 @@ import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabiliti
 import { env } from "../config/env";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
-  CapabilityActionReviewSchema,
+  CapabilityActionReviewDataSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
 } from "../contracts/capabilities";
@@ -263,7 +263,7 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         locale: caller.locale ?? undefined,
         origin: caller.origin ?? "app",
       });
-      return readCapabilityResponse(outcome, CapabilityActionReviewSchema);
+      return readCapabilityResponse(outcome, CapabilityActionReviewDataSchema);
     }
     const response = await (caller.transport ?? fetch)(
       new Request(
@@ -276,7 +276,7 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         { body: JSON.stringify({ input: invocation.input }) },
       ),
     );
-    return readCapabilityResponse(response, CapabilityActionReviewSchema);
+    return readCapabilityResponse(response, CapabilityActionReviewDataSchema);
   } catch (cause) {
     return unavailable(cause, undefined, caller.locale ?? undefined);
   }
@@ -312,3 +312,10 @@ export async function transferCapabilityStream(
   }
   return caller.transport ? caller.transport(request) : fetch(request, { redirect: "error" });
 }
+
+export {
+  actionReview,
+  type CapabilityReviewForms,
+  capabilityReviewRememberScope,
+  capabilityReviewView,
+} from "./reviews";

package/src/capabilities/testing.ts

@@ -1,9 +1,19 @@
 import { capabilityManifestEvolutionIssues, compileCapabilities } from "../_internal/capabilities";
 import {
+  type CapabilityReviewContext,
+  type CapabilityReviewForms,
+  capabilityActionReviewIssues,
+  capabilityReviewFormIssues,
+} from "../_internal/capability-reviews";
+import { capabilitySentenceParts } from "../_internal/capability-sentences";
+import {
+  CapabilityActionCallReviewSchema,
+  CapabilityActionReviewDataSchema,
   type CapabilityDefinitions,
   type CapabilityManifest,
   type CapabilityResult,
   CapabilitySemanticLinkSchema,
+  type CapabilitySlot,
 } from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
@@ -22,3 +32,40 @@ export const assertResourceOpenLink = (result: Pick<CapabilityResult<unknown>, "
   if (!link) throw new Error("Resource reader must return a top-level open link");
   return CapabilitySemanticLinkSchema.parse(link);
 };
+
+/** Validate each localized review in application tests, with optional declaration context. */
+export const assertCapabilityReview = (review: unknown, context?: CapabilityReviewContext): void => {
+  const parsed = CapabilityActionReviewDataSchema.safeParse(review);
+  const issues = context
+    ? capabilityActionReviewIssues(review, context)
+    : !parsed.success
+      ? parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      : "sentence" in parsed.data
+        ? capabilityReviewFormIssues(parsed.data)
+        : [];
+  if (issues.length) throw new Error(`Invalid Capability review:\n- ${issues.join("\n- ")}`);
+};
+
+/** Catalog check: the 80-character question bound is guidance for app messages, not a runtime restriction. */
+export const checkActionReviewMessages = (input: {
+  locales: readonly string[];
+  forms: (locale: string) => CapabilityReviewForms;
+  slots: Readonly<Record<string, CapabilitySlot>>;
+}): string[] =>
+  input.locales.flatMap((locale) => {
+    try {
+      const review = CapabilityActionCallReviewSchema.safeParse({ ...input.forms(locale), slots: input.slots });
+      if (!review.success) return review.error.issues.map((issue) => `${locale} ${issue.path.join(".")}: ${issue.message}`);
+      const issues = capabilityReviewFormIssues(review.data).map((issue) => `${locale}: ${issue}`);
+      const visible = capabilitySentenceParts(review.data.sentence.action, review.data.slots, {
+        locale: review.data.locale,
+        timeZone: "UTC",
+      })
+        .map((part) => (part.kind === "text" ? part.text : part.label))
+        .join("");
+      if (Array.from(`${visible}?`).length > 80) issues.push(`${locale}: question exceeds 80 visible characters`);
+      return issues;
+    } catch (error) {
+      return [`${locale}: ${error instanceof Error ? error.message : String(error)}`];
+    }
+  });

package/src/capabilities/types.ts

@@ -1,11 +1,11 @@
 import type { z } from "zod";
-import type { CapabilityActionReview, CapabilityCatalog, CapabilityErrorSchema, CapabilityResult } from "../contracts/capabilities";
+import type { CapabilityActionReviewData, CapabilityCatalog, CapabilityErrorSchema, CapabilityResult } from "../contracts/capabilities";
 
 export type CapabilityKind = "query" | "action";
 export type CapabilityClientError = z.infer<typeof CapabilityErrorSchema> & { status: number };
 export type CapabilityResultState<T> = { ok: true; data: T } | { ok: false; error: CapabilityClientError };
 export type CapabilityClientResult<T> = CapabilityResultState<CapabilityResult<T>>;
-export type CapabilityReviewClientResult = CapabilityResultState<CapabilityActionReview>;
+export type CapabilityReviewClientResult = CapabilityResultState<CapabilityActionReviewData>;
 export type CapabilityCatalogClientResult = CapabilityResultState<CapabilityCatalog>;
 export type CapabilityCatalogApp = CapabilityCatalog["apps"][number];
 export type CapabilityCatalogAppClientResult = CapabilityResultState<CapabilityCatalogApp | null>;

package/src/cli/account.ts

@@ -301,11 +301,21 @@ export default defineCliCommands({
         access: flag.enum(["full", "models"], { default: "full", description: "Full access or models-only inference access" }),
       },
       run: async ({ ctx, args, flags }) => {
-        const result = await readApi<{ credential: ApiKey; token: string }>(
-          ctx,
-          "/api-keys",
+        const response = await ctx.fetch(
+          apiPath("/api-keys"),
           jsonRequest("POST", { name: args.name, expiresAt: parseExpiry(flags.expires), access: flags.access }),
         );
+        if (response.status === 403) {
+          const body: unknown = await response
+            .clone()
+            .json()
+            .catch(() => null);
+          const code = body && typeof body === "object" && "code" in body ? body.code : null;
+          const href = new URL("/me/developer", ctx.options.server).href;
+          if (code === "BROWSER_SIGN_IN_REQUIRED") throw new Error(`Create API keys in the browser: ${href}`);
+          if (code === "REAUTHENTICATE") throw new Error(`Sign in again in the browser, then create the API key: ${href}`);
+        }
+        const result = await ctx.readJson<{ credential: ApiKey; token: string }>(response);
         const modelsOnly = isModelsOnlyApiKey(result.credential);
         if (flags.access === "models" && !modelsOnly) {
           try {

package/src/cli/admin/geoip.ts

@@ -0,0 +1,115 @@
+import type { GeoIpAdminStatus, GeoIpResetResult } from "../../contracts/geoip";
+import { arg, type CloudCliContext, cliText, command, confirmFlag, printStructured } from "../index";
+
+const path = "/api/admin/core/geoip";
+const messages = {
+  geoip_too_large: {
+    en: "The database exceeds 192 MiB unpacked. Try a smaller database.",
+    de: "Die Datenbank überschreitet 192 MiB entpackt. Nutze eine kleinere Datenbank.",
+  },
+  geoip_request_too_large: {
+    en: "The compressed upload exceeds 128 MiB. Try a smaller database.",
+    de: "Der komprimierte Upload überschreitet 128 MiB. Nutze eine kleinere Datenbank.",
+  },
+  geoip_empty: { en: "The uploaded file is empty.", de: "Die hochgeladene Datei ist leer." },
+  geoip_invalid: {
+    en: "Upload a valid IPv6 MMDB database with a build date.",
+    de: "Lade eine gültige IPv6-MMDB-Datenbank mit Erstellungsdatum hoch.",
+  },
+  geoip_unsupported_type: { en: "Only City and ASN databases are supported.", de: "Nur City- und ASN-Datenbanken werden unterstützt." },
+  geoip_upload_busy: {
+    en: "Another upload is running. Try again shortly.",
+    de: "Ein anderer Upload läuft. Versuche es gleich noch einmal.",
+  },
+} as const;
+const readStatus = async <T extends GeoIpAdminStatus = GeoIpAdminStatus>(ctx: CloudCliContext, response: Response): Promise<T> => {
+  if (!response.ok) {
+    const value: unknown = await response
+      .clone()
+      .json()
+      .catch(() => null);
+    if (typeof value === "object" && value !== null && "code" in value) {
+      for (const [code, message] of Object.entries(messages)) if (value.code === code) throw new Error(cliText(ctx, message));
+    }
+  }
+  return ctx.readJson<T>(response);
+};
+const printStatus = (ctx: CloudCliContext, status: GeoIpAdminStatus) => {
+  if (printStructured(ctx, status)) return;
+  ctx.table(
+    status.databases.map((database) => ({
+      type: database.kind,
+      source: database.source ?? "-",
+      databaseType: database.databaseType ?? "-",
+      built: database.buildDate ?? "-",
+      stale: database.stale,
+      uploadedBy: database.upload?.uploadedBy?.name ?? "-",
+      uploadedAt: database.upload?.uploadedAt ?? "-",
+    })),
+    [
+      { key: "type" },
+      { key: "source" },
+      { key: "databaseType" },
+      { key: "built" },
+      { key: "stale" },
+      { key: "uploadedBy" },
+      { key: "uploadedAt" },
+    ],
+  );
+  if (status.attribution) ctx.print(`${status.attribution.text} (${status.attribution.url}), ${status.attribution.license}`);
+};
+export const geoipCommands = [
+  command("geoip status", {
+    summary: "Show sign-in location databases and their build dates",
+    async run({ ctx }) {
+      printStatus(ctx, await readStatus(ctx, await ctx.fetch(path)));
+    },
+  }),
+  command("geoip upload", {
+    summary: "Replace a sign-in location database from an MMDB or gzip file",
+    args: { file: arg.required({ valueLabel: "file" }) },
+    async run({ ctx, args }) {
+      const file = Bun.file(args.file);
+      if (!(await file.exists())) throw new Error(cliText(ctx, { en: "File not found.", de: "Datei nicht gefunden." }));
+      // Refresh credentials on a replayable request before sending a one-shot stream. A token with only the write
+      // scope may not read the status; the upload's own answer reports whether it is allowed.
+      const preflight = await ctx.fetch(path);
+      if (preflight.status === 403) await preflight.body?.cancel();
+      else await readStatus(ctx, preflight);
+      const magic = new Uint8Array(await file.slice(0, 2).arrayBuffer());
+      const gzip = magic[0] === 0x1f && magic[1] === 0x8b;
+      const body = gzip ? file.stream() : file.stream().pipeThrough(new CompressionStream("gzip"));
+      try {
+        const init: RequestInit & { duplex: "half" } = {
+          method: "PUT",
+          headers: { "Content-Type": "application/gzip" },
+          body,
+          duplex: "half",
+        };
+        printStatus(ctx, await readStatus(ctx, await ctx.fetch(path, init)));
+      } finally {
+        if (!body.locked) await body.cancel().catch(() => {});
+      }
+    },
+  }),
+  command("geoip reset", {
+    summary: "Return one or both sign-in location databases to the bundled snapshot",
+    args: { kind: arg.optional({ valueLabel: "city|asn" }) },
+    flags: { yes: confirmFlag("Reset sign-in location databases") },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes) throw new Error(cliText(ctx, { en: "Refusing to reset without --yes.", de: "Ohne --yes wird nicht zurückgesetzt." }));
+      if (args.kind !== undefined && args.kind !== "city" && args.kind !== "asn")
+        throw new Error(cliText(ctx, { en: "Choose city or asn.", de: "Wähle city oder asn." }));
+      let status: GeoIpResetResult | undefined;
+      let changed = false;
+      for (const kind of args.kind ? [args.kind] : ["city", "asn"]) {
+        status = await readStatus<GeoIpResetResult>(ctx, await ctx.fetch(`${path}/${kind}`, { method: "DELETE" }));
+        changed ||= status.changed;
+      }
+      if (status) {
+        status.changed = changed;
+        printStatus(ctx, status);
+      }
+    },
+  }),
+];

package/src/cli/admin/index.ts

@@ -17,6 +17,7 @@ import { appSignInCommands } from "./app-sign-in";
 import { dataCommands } from "./data";
 import { documentationCommands } from "./documentation";
 import { gatewayCommands } from "./gateway";
+import { geoipCommands } from "./geoip";
 import { instanceCommands } from "./instance";
 import { jobCommands } from "./jobs";
 import { legalCommands } from "./legal";
@@ -49,6 +50,7 @@ export default defineCliCommands({
     "app-sign-in": "Manage app sign-in and pairing.",
     apps: "Inspect and remove registered apps.",
     documentation: "Manage the administration documentation website.",
+    geoip: "Replace and inspect sign-in location databases.",
     jobs: "Inspect background jobs and their runs.",
     logs: "Search, inspect, and clean up retained logs.",
     metrics: "Inspect collectors and manage metrics access.",
@@ -99,6 +101,7 @@ export default defineCliCommands({
     ...telemetryCommands,
     ...jobCommands,
     ...legalCommands,
+    ...geoipCommands,
     ...linuxCommands,
     ...workflowCommands,
     ...dataCommands,