@k2b/cloud 0.7.0 → 0.9.0

package/src/api/capabilities.ts

@@ -1,11 +1,10 @@
-import { sealCapabilityStream, dispatchCapabilityStream } from "./capability-streams";
-import { CapabilityStreamSchema } from "../contracts/capability-streams";
 import { Hono, type MiddlewareHandler } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { getCapability, listApps } from "../_internal/registry";
+import { resolveCommandLink } from "../capabilities/command-link";
 import {
   type CapabilityClaimScope,
   type CapabilityExecutionStatus,
@@ -34,6 +33,8 @@ import {
   type CapabilityOrigin,
   capabilityResultJsonSchema,
 } from "../contracts/capabilities";
+import { CapabilityStreamSchema } from "../contracts/capability-streams";
+import { CommandLinkSchema, CommandRequestSchema } from "../contracts/commands";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import {
   type AuthContext,
@@ -48,8 +49,6 @@ import {
   v,
 } from "../server";
 import { logger, settings } from "../services";
-import { resolveCommandLink } from "../capabilities/command-link";
-import { CommandRequestSchema, CommandLinkSchema } from "../contracts/commands";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
 import type { InvocationAuthority } from "../services/identity/invocation-token";
@@ -58,6 +57,7 @@ import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { withMandateIssueAuthority } from "../services/mandates";
 import { resolveAppPresentation } from "../shared/app-presentation";
 import { capabilityMessages } from "../shared/capability-messages";
+import { dispatchCapabilityStream, sealCapabilityStream } from "./capability-streams";
 
 const log = logger("capabilities");
 const QUERY_TIMEOUT_MS = 15_000;
@@ -340,7 +340,8 @@ const runCapabilityDispatch = async (
     return invalid;
   }
 
-  if (params.mandate && operation.stream) return errorResponse("STREAM_UNSUPPORTED_AUTHORITY", "Streams require an interactive user or service-account request", 403);
+  if (params.mandate && operation.stream)
+    return errorResponse("STREAM_UNSUPPORTED_AUTHORITY", "Streams require an interactive user or service-account request", 403);
 
   let requestBody: string;
   try {
@@ -626,12 +627,31 @@ const runCapabilityDispatch = async (
   const body = upstreamBody.data as Record<string, unknown>;
   if (!params.review && body.stream !== undefined) {
     const stream = CapabilityStreamSchema.safeParse(body.stream);
-    if (!stream.success || !operation.stream || stream.data.direction !== operation.stream.direction || stream.data.size > operation.stream.maxBytes || Date.parse(stream.data.expiresAt) <= Date.now() || Date.parse(stream.data.expiresAt) > Date.now() + 86_400_000 || !params.authority)
+    if (
+      !stream.success ||
+      !operation.stream ||
+      stream.data.direction !== operation.stream.direction ||
+      stream.data.size > operation.stream.maxBytes ||
+      Date.parse(stream.data.expiresAt) <= Date.now() ||
+      Date.parse(stream.data.expiresAt) > Date.now() + 86_400_000 ||
+      !params.authority
+    )
       return settle(errorResponse("INVALID_APP_RESPONSE", "Invalid stream offer", 502), "uncertain");
     try {
-      body.stream = await sealCapabilityStream(stream.data, { appId: params.appId, kind: params.kind, capabilityId: params.capabilityId, schemaHash: operation.schemaHash, authority: params.authority, requestId, origin: params.origin, continuation: params.continuation });
+      body.stream = await sealCapabilityStream(stream.data, {
+        appId: params.appId,
+        kind: params.kind,
+        capabilityId: params.capabilityId,
+        schemaHash: operation.schemaHash,
+        authority: params.authority,
+        requestId,
+        origin: params.origin,
+        continuation: params.continuation,
+      });
       if (Buffer.byteLength(JSON.stringify(body)) > CAPABILITY_MAX_RESULT_BYTES) throw new Error("Stream result too large");
-    } catch { return settle(errorResponse("INVALID_APP_RESPONSE", "Invalid stream offer", 502), "uncertain"); }
+    } catch {
+      return settle(errorResponse("INVALID_APP_RESPONSE", "Invalid stream offer", 502), "uncertain");
+    }
   }
   return settle({ body, status: 200 }, "succeeded");
 };
@@ -722,11 +742,23 @@ export const createCapabilityRoutes = (dependencies: CapabilityRouteDependencies
   return new Hono<AuthContext>()
     .use("/capabilities/v1/*", dependencies.authenticate ?? auth.requireRole("authenticated"))
     .use("/capabilities/v1/*", rejectReservedWorkloadCredential)
-    .post("/capabilities/v1/streams/:verb", describeRoute({
-      tags:["Capabilities"],summary:"Transfer or inspect one authorized binary stream",...requiresAuth,
-      description:"POST read/write/status/abort with x-cloud-stream-id. Write sends raw bytes; read returns raw bytes. Status and abort return the upload state. No automatic retries.",
-      responses:{200:{description:"Binary content, write receipt, or transfer state"},403:{description:"Stream does not belong to this caller"},409:{description:"Transfer or contract changed"},410:{description:"Stream expired"}},
-    }), async c => dispatchCapabilityStream(c.req.raw, auth.getAuthority(c), c.req.param("verb"), dependencies))
+    .post(
+      "/capabilities/v1/streams/:verb",
+      describeRoute({
+        tags: ["Capabilities"],
+        summary: "Transfer or inspect one authorized binary stream",
+        ...requiresAuth,
+        description:
+          "POST read/write/status/abort with x-cloud-stream-id. Write sends raw bytes; read returns raw bytes. Status and abort return the upload state. No automatic retries.",
+        responses: {
+          200: { description: "Binary content, write receipt, or transfer state" },
+          403: { description: "Stream does not belong to this caller" },
+          409: { description: "Transfer or contract changed" },
+          410: { description: "Stream expired" },
+        },
+      }),
+      async (c) => dispatchCapabilityStream(c.req.raw, auth.getAuthority(c), c.req.param("verb"), dependencies),
+    )
     .get(
       "/capabilities/v1/catalog",
       describeRoute({

package/src/api/index.ts

@@ -1,4 +1,3 @@
-import adminAiQuotaRoutes from "./admin-ai-quotas";
 /**
  * Core platform API surface — owned by cloud-lib, mounted by the core-app.
  *
@@ -17,23 +16,24 @@ import adminAiQuotaRoutes from "./admin-ai-quotas";
 import { Hono } from "hono";
 import { prettyJSON } from "hono/pretty-json";
 import { createAiApprovalPreferenceRoutes } from "../ai/approval-routes";
-import { aiProjectsRoutes } from "../ai/projects-routes";
 import { createCodeCapabilityRoutes } from "../ai/code-capability-routes";
+import { aiProjectsRoutes } from "../ai/projects-routes";
 import { aiRoutes } from "../ai/routes";
 import { aiSkillsRoutes } from "../ai/skills-routes";
 import accountsEntitiesRoutes from "./accounts-entities";
-import adminAiUsageRoutes from "./admin-ai-usage";
 import adminAiProjectsRoutes from "./admin-ai-projects";
+import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
-import adminRailRoutes from "./admin-rail";
+import adminAiUsageRoutes from "./admin-ai-usage";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminIdentityRoutes from "./admin-identity";
 import adminLifecycleRoutes from "./admin-lifecycle";
 import adminLinuxIdentityRoutes from "./admin-linux-identities";
+import adminRailRoutes from "./admin-rail";
 import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
+import { createAppApprovalRoutes } from "./app-approval";
 import { appDiscoveryRoutes } from "./apps";
 import { createAuthRoutes } from "./auth";
-import { createAppApprovalRoutes } from "./app-approval";
 import { createCapabilityRoutes } from "./capabilities";
 import { createHelpRoutes } from "./help";
 import { createMcpRoutes } from "./mcp";

package/src/api/mcp.ts

@@ -1,4 +1,3 @@
-import { createHelpReader, type HelpReader, type HelpReaderFactory, type HelpMetadata, type HelpArticle } from "../services/help";
 import { createHash } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -16,12 +15,7 @@ import {
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
-import {
-  HELP_SEARCH_MAX_LIMIT,
-  helpResourceUri,
-  parseHelpResourceUri,
-  readHelpArticle,
-} from "../_internal/help-catalog";
+import { HELP_SEARCH_MAX_LIMIT, helpResourceUri, parseHelpResourceUri, readHelpArticle } from "../_internal/help-catalog";
 import { getCapability, listApps } from "../_internal/registry";
 import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
 import {
@@ -39,6 +33,7 @@ import {
 } from "../contracts/capabilities";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import { type AuthContext, auth, type RequestAuthority, rateLimit, rejectReservedWorkloadCredential, resolveLocale } from "../server";
+import { createHelpReader, type HelpArticle, type HelpMetadata, type HelpReader, type HelpReaderFactory } from "../services/help";
 import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
 import { logger } from "../services/logging";
 import { get } from "../services/settings";
@@ -485,7 +480,8 @@ const createMcpServer = (
     (helpLocale ??= (dependencies.getOperatorLocale ?? (() => get<string>("app.locale")))().then((operatorDefault) =>
       resolveLocale(request.headers, operatorDefault),
     ));
-  const helpReader = async () => (dependencies.help ?? ((locale) => createHelpReader(locale, { listApps: registry })))(await resolveHelpLocale());
+  const helpReader = async () =>
+    (dependencies.help ?? ((locale) => createHelpReader(locale, { listApps: registry })))(await resolveHelpLocale());
   const hasScope = (scope: "read" | "write"): boolean =>
     oauthScopes === null || oauthScopes.includes(scope) || oauthScopes.includes("admin");
   const requireScope = (scope: "read" | "write"): void => {
@@ -567,10 +563,7 @@ const createMcpServer = (
         return (await callHelpTool(message.params.name, message.params.arguments, await helpReader()))!;
       } catch (error) {
         log.error("Failed to call MCP Help tool", { error: error instanceof Error ? error.message : String(error) });
-        return boundedToolResult(
-          { code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Help is currently unavailable" },
-          true,
-        );
+        return boundedToolResult({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Help is currently unavailable" }, true);
       }
     }
     let selected: CapabilityTool | null;

package/src/browser/CloudResourceSearch.tsx

@@ -1,10 +1,10 @@
-import { shortcutLabel } from "./command-shortcuts";
 import { query, timed } from "@k2b/stdlib/solid";
 import { Button, IconButton, ScrollArea, useLocale } from "@k2b/ui";
 import { createEffect, createMemo, createSignal, createUniqueId, For, on, onCleanup, onMount, Show } from "solid-js";
 import type { SearchItem, SearchResponse } from "../api/search/schemas";
 import type { CloudResourceRef } from "../contracts";
 import { LOCALE_HEADER } from "../shared/locale";
+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";

package/src/browser/command-bridge.ts

@@ -1,6 +1,6 @@
-import type { GlobalSearchOptions } from "./search-bridge";
 import type { z } from "zod";
 import type { CommandOptions } from "../contracts/commands";
+import type { GlobalSearchOptions } from "./search-bridge";
 
 export type CommandTarget = { command: string; input: unknown; options?: CommandOptions };
 export type ContextAwareCommand = {

package/src/browser/command-shortcuts.ts

@@ -1,4 +1,4 @@
-import { COMMANDS_CHANGED, collectContextAwareCommands, type ContextAwareCommand } from "./command-bridge";
+import { COMMANDS_CHANGED, type ContextAwareCommand, collectContextAwareCommands } from "./command-bridge";
 
 const isMac = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
 const modifiers = ["ctrl", "alt", "shift", "meta"] as const;

package/src/browser/commands.ts

@@ -1,17 +1,18 @@
-import { requestGlobalSearch } from "./search-bridge";
 import { toast } from "@k2b/ui";
 import { resolveCommand } from "../capabilities/client";
-import { clearCommand, CommandOptionsSchema, readCommand, type CommandOptions } from "../contracts/commands";
-import { resourceSearchMessages } from "./resource-search-messages";
+import { type CommandOptions, CommandOptionsSchema, clearCommand, readCommand } from "../contracts/commands";
 import {
-  collectContextAwareCommands,
-  requestContextCommandExecution,
   type ContextAwareCommand,
+  collectContextAwareCommands,
   requestCommandHandling,
+  requestContextCommandExecution,
 } from "./command-bridge";
-export { registerCommandHandler, registerContextAwareCommand } from "./command-bridge";
-export type { CommandTarget, ContextAwareCommand } from "./command-bridge";
+import { resourceSearchMessages } from "./resource-search-messages";
+import { requestGlobalSearch } from "./search-bridge";
+
 export type { CommandOptions } from "../contracts/commands";
+export type { CommandTarget, ContextAwareCommand } from "./command-bridge";
+export { registerCommandHandler, registerContextAwareCommand } from "./command-bridge";
 
 /** Opens locally only when a mounted owner explicitly accepts; otherwise follows the app's URL. */
 export const openCommand = async (command: string, input: unknown = {}, options: CommandOptions = {}): Promise<void> => {

package/src/browser/testing.ts

@@ -1,5 +1,6 @@
 /** Browser-only test probes. Mount and dispose application islands through their public APIs. */
+
+export { readWorkspaceNavigation } from "../ssr/workspace-navigation";
 export { collectContextAwareCommands } from "./command-bridge";
 export { contextCommandsWithShortcuts } from "./command-shortcuts";
 export { registerGlobalSearchHost } from "./search-bridge";
-export { readWorkspaceNavigation } from "../ssr/workspace-navigation";

package/src/capabilities/client.ts

@@ -180,4 +180,4 @@ export const resolveCommand = async (
   }
 };
 
-export { transferCapabilityStream, type CapabilityStreamVerb } from "./streams";
+export { type CapabilityStreamVerb, transferCapabilityStream } from "./streams";

package/src/capabilities/command-link.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { CapabilityCommandManifest } from "../contracts/capabilities";
-import { commandPath, CommandLinkSchema, type CommandOptions } from "../contracts/commands";
+import { CommandLinkSchema, type CommandOptions, commandPath } from "../contracts/commands";
 import { publicCloudOrigin } from "../shared/app-url";
 
 export const resolveCommandLink = (

package/src/capabilities/server.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { getApp, getCapability } from "../_internal/registry";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
+import { env } from "../config/env";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CapabilityActionReviewSchema,
@@ -54,7 +55,7 @@ export type CapabilityCaller = {
 };
 
 const coreOrigin = async (internal = false): Promise<string> => {
-  const configured = process.env.CLOUD_CORE_INTERNAL_ORIGIN?.trim();
+  const configured = env.CLOUD_CORE_INTERNAL_ORIGIN;
   if (internal && !configured) throw new Error("CLOUD_CORE_INTERNAL_ORIGIN is required for mandate-backed invocation");
   const origin = configured || publicCloudOrigin(await get<string>("app.url"));
   const url = new URL(origin);

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

@@ -1,13 +1,13 @@
-import { AiModelPricingSchema, type AiModelPricing } from "../../shared/ai-costs";
+import { type AiModelPricing, AiModelPricingSchema } from "../../shared/ai-costs";
 import {
+  type AiQuotaConfig,
   AiQuotaConfigSchema,
-  AiQuotaReportQuerySchema,
+  type AiQuotaIdentity,
   AiQuotaIdentitySchema,
+  AiQuotaReportQuerySchema,
   AiQuotaResetSchema,
-  type AiQuotaConfig,
-  type AiQuotaIdentity,
 } from "../../shared/ai-quotas";
-import { cliText, command, confirmFlag, flag, printRows, printStructured, type CloudCliContext } from "../index";
+import { type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured } from "../index";
 import { apiGet, apiJson, queryString, readJsonInput } from "./shared";
 
 const path = "/api/admin/core/ai-quotas";

package/src/cli/admin/app-credentials.ts

@@ -52,15 +52,13 @@ export const appCredentialCommands = [
     async run({ ctx, args, flags }) {
       if (!flags.yes)
         throw new Error(cliText(ctx, { en: "Creating an app credential requires --yes.", de: "App-Zugang erstellen erfordert --yes." }));
-      const result = z
-        .object({ credential: metadata, token: z.string() })
-        .parse(
-          await apiJson(ctx, "POST", path(args.app), {
-            name: flags.name,
-            scopes: ["identity:invoke"],
-            ...(flags.expiresAt ? { expiresAt: flags.expiresAt } : {}),
-          }),
-        );
+      const result = z.object({ credential: metadata, token: z.string() }).parse(
+        await apiJson(ctx, "POST", path(args.app), {
+          name: flags.name,
+          scopes: ["identity:invoke"],
+          ...(flags.expiresAt ? { expiresAt: flags.expiresAt } : {}),
+        }),
+      );
       if (!printStructured(ctx, result)) ctx.print(result.token);
     },
   }),

package/src/cli/admin/index.ts

@@ -1,4 +1,3 @@
-import { appCredentialCommands } from "./app-credentials";
 /**
  * `cld admin` — Cloud administration surfaces.
  *
@@ -9,10 +8,11 @@ import { appCredentialCommands } from "./app-credentials";
 import { defineCliCommands } from "../commands";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
-import { appSignInCommands } from "./app-sign-in";
-import { aiSkillCommands } from "./ai-skills";
 import { aiQuotaCommands } from "./ai-quotas";
+import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
+import { appCredentialCommands } from "./app-credentials";
+import { appSignInCommands } from "./app-sign-in";
 import { dataCommands } from "./data";
 import { documentationCommands } from "./documentation";
 import { gatewayCommands } from "./gateway";

package/src/cli/admin/instance.ts

@@ -7,10 +7,10 @@ import type { PostgresDiagnostics, RedisDiagnostics } from "./data";
 import type { GatewayHealth } from "./gateway";
 import type { BackgroundJobRow } from "./jobs";
 import { getLogs, type LogSummary, trimLogMessages } from "./logs";
-import type { NatsSnapshot } from "./nats";
-import type { SyncOverview } from "./sync";
 import type { MetricsCollector } from "./metrics";
+import type { NatsSnapshot } from "./nats";
 import { apiGet, formatBytes, parseLookbackHours, printJsonOrTable, queryString, safeCollect, skippedCollect, truncate } from "./shared";
+import type { SyncOverview } from "./sync";
 import type { TelemetryEvent, TelemetryRouteRow } from "./telemetry";
 import { diagnoseRange } from "./telemetry";
 

package/src/cli/admin/linux.ts

@@ -1,4 +1,4 @@
-import { LinuxIdentityConfigurationSchema, type LinuxIdentityConfiguration } from "../../contracts/posix";
+import { type LinuxIdentityConfiguration, LinuxIdentityConfigurationSchema } from "../../contracts/posix";
 import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
 import { apiGet, apiJson, queryString } from "./shared";
 
@@ -10,7 +10,9 @@ export const linuxCommands = [
     flags: {
       after: flag.string({ description: "Continue after the previous page's nextCursor" }),
       search: flag.string({ description: "Filter by username substring" }),
-      scope: flag.enum(["ready", "all"] as const, { description: "Show eligible accounts missing Linux attributes or all accounts (default)" }),
+      scope: flag.enum(["ready", "all"] as const, {
+        description: "Show eligible accounts missing Linux attributes or all accounts (default)",
+      }),
     },
     async run({ ctx, flags }) {
       const result = await apiGet<unknown>(ctx, `${path}${queryString({ after: flags.after, search: flags.search, scope: flags.scope })}`);

package/src/cli/admin/sync.ts

@@ -1,6 +1,6 @@
 /** Admin access to application-owned Sync diagnostics and recovery. */
 import type { SyncDeadLetterEntry, SyncDeadLetterKind, SyncDeadLetterStoreView, SyncScheduleView } from "../../services/sync-ops";
-import { arg, command, confirmFlag, flag, type CloudCliContext } from "../index";
+import { arg, type CloudCliContext, command, confirmFlag, flag } from "../index";
 import { apiGet, apiJson, printJsonOrTable, queryString } from "./shared";
 
 export type SyncOverview = {

package/src/cli/capabilities.ts

@@ -1,5 +1,3 @@
-import { saveCapabilityStream } from "./capability-streams";
-import { CapabilityStreamSchema } from "../contracts/capabilities";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import {
@@ -8,11 +6,13 @@ import {
   CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
+  CapabilityStreamSchema,
   CloudResourceRefSchema,
   capabilityResultSchema,
   cloudResourceRefAppId,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
+import { saveCapabilityStream } from "./capability-streams";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, defineCliCommands, flag, readCliInput } from "./index";
 
 const parseInput = async (input: CliInputFlagValue): Promise<unknown> => {
@@ -120,33 +120,46 @@ export default defineCliCommands({
   name: "capabilities",
   summary: "Discover and invoke versioned Cloud app capabilities.",
   commands: [
-    ...(["read", "write", "status", "abort"] as const).map(verb => command(`stream-${verb}`, {
-      summary: `${verb} an authenticated binary capability stream`,
-      flags: {
-        input: flag.input({ required: true, description: "Stream descriptor JSON; use --input-file or --stdin" }),
-        ...(verb === "read" ? { out: flag.string({ required: true, description: "New output file; never overwritten" }) } : {}),
-        ...(verb === "write" ? { file: flag.string({ required: true, description: "Local binary file to upload" }) } : {}),
-      },
-      run: async ({ctx, flags}) => {
-        const stream = CapabilityStreamSchema.parse(await parseInput(flags.input));
-        if ((verb === "read") !== (stream.direction === "read")) throw new Error("Wrong stream direction.");
-        const body = verb === "write" ? Bun.file(String(flags.file)) : undefined;
-        if (body && (!(await body.exists()) || body.size !== stream.size)) throw new Error("Input file must match the authorized byte size.");
-        const controller = new AbortController();
-        const abort = () => controller.abort();
-        process.once("SIGINT", abort); process.once("SIGTERM", abort);
-        try {
-          const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(300_000)]);
-          const response = await ctx.fetch(`/api/capabilities/v1/streams/${verb}`, {
-            method: "POST", headers: {"x-cloud-stream-id": stream.id, "content-type": "application/octet-stream"},
-            body, signal, redirect: "error",
-          });
-          printGenericResult(ctx, verb === "read"
-            ? await saveCapabilityStream(response, stream, String(flags.out), signal)
-            : await readCapabilityJson(response, CAPABILITY_MAX_RESULT_BYTES));
-        } finally { process.off("SIGINT", abort); process.off("SIGTERM", abort); }
-      },
-    })),
+    ...(["read", "write", "status", "abort"] as const).map((verb) =>
+      command(`stream-${verb}`, {
+        summary: `${verb} an authenticated binary capability stream`,
+        flags: {
+          input: flag.input({ required: true, description: "Stream descriptor JSON; use --input-file or --stdin" }),
+          ...(verb === "read" ? { out: flag.string({ required: true, description: "New output file; never overwritten" }) } : {}),
+          ...(verb === "write" ? { file: flag.string({ required: true, description: "Local binary file to upload" }) } : {}),
+        },
+        run: async ({ ctx, flags }) => {
+          const stream = CapabilityStreamSchema.parse(await parseInput(flags.input));
+          if ((verb === "read") !== (stream.direction === "read")) throw new Error("Wrong stream direction.");
+          const body = verb === "write" ? Bun.file(String(flags.file)) : undefined;
+          if (body && (!(await body.exists()) || body.size !== stream.size))
+            throw new Error("Input file must match the authorized byte size.");
+          const controller = new AbortController();
+          const abort = () => controller.abort();
+          process.once("SIGINT", abort);
+          process.once("SIGTERM", abort);
+          try {
+            const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(300_000)]);
+            const response = await ctx.fetch(`/api/capabilities/v1/streams/${verb}`, {
+              method: "POST",
+              headers: { "x-cloud-stream-id": stream.id, "content-type": "application/octet-stream" },
+              body,
+              signal,
+              redirect: "error",
+            });
+            printGenericResult(
+              ctx,
+              verb === "read"
+                ? await saveCapabilityStream(response, stream, String(flags.out), signal)
+                : await readCapabilityJson(response, CAPABILITY_MAX_RESULT_BYTES),
+            );
+          } finally {
+            process.off("SIGINT", abort);
+            process.off("SIGTERM", abort);
+          }
+        },
+      }),
+    ),
     command("catalog", {
       summary: "List live capability manifests",
       flags: {

package/src/config/define-env.ts

@@ -0,0 +1,97 @@
+/**
+ * Environment registry factory.
+ *
+ * Every runtime environment variable is declared once with a schema, a
+ * default, a scope and a one-sentence doc. Registries read `process.env`
+ * lazily: each key is parsed on access, so tests can change variables and
+ * consumers never depend on an import-time snapshot. `.env.example`,
+ * `.env.prod.example` and the configuration reference are generated from the
+ * `$specs` of every registry by `scripts/generate-config-docs.ts`.
+ */
+import { z } from "zod";
+
+/**
+ * `runtime` is read by deployed processes, `secret` is a runtime credential,
+ * `development` only matters for host-run development, builds or tooling.
+ */
+export type EnvScope = "runtime" | "secret" | "development";
+
+export type EnvSpec<T> = {
+  /** Parses the trimmed raw value. Empty and unset values never reach the schema. */
+  schema: z.ZodType<T, unknown>;
+  /** Used when the variable is unset or empty; a function is evaluated on every access. */
+  default?: T | (() => T);
+  /** One sentence for operators; rendered into the generated files. */
+  doc: string;
+  /** Default `runtime`. */
+  scope?: EnvScope;
+  /** Host-run development value written to `.env.example`. */
+  example?: string;
+  /** Throw on access when unset and no default exists. */
+  required?: boolean;
+  /** Alternative variable names, consulted after the canonical key. */
+  aliases?: string[];
+};
+
+export type EnvSpecs = Record<string, EnvSpec<unknown>>;
+
+type EnvValue<S extends EnvSpec<unknown>> = S extends { default: unknown } | { required: true }
+  ? z.output<S["schema"]>
+  : z.output<S["schema"]> | undefined;
+
+export type EnvRegistry<S extends EnvSpecs> = { readonly [K in keyof S]: EnvValue<S[K]> } & {
+  readonly $specs: S;
+  readonly $keys: readonly string[];
+};
+
+const rawValue = (key: string, aliases: string[] = []): string | undefined => {
+  for (const name of [key, ...aliases]) {
+    const value = process.env[name]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+};
+
+const isFactory = <T>(value: T | (() => T)): value is () => T => typeof value === "function";
+
+export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
+  const raw = rawValue(key, spec.aliases);
+  if (raw === undefined) {
+    if (spec.default !== undefined) return isFactory(spec.default) ? spec.default() : spec.default;
+    if (spec.required) throw new Error(`${key} is required`);
+    return undefined;
+  }
+  const parsed = spec.schema.safeParse(raw);
+  if (!parsed.success) {
+    const reason = parsed.error.issues.map((issue) => issue.message).join("; ") || "is invalid";
+    throw new Error(`${key} ${reason}`);
+  }
+  return parsed.data;
+};
+
+export const defineEnv = <S extends EnvSpecs>(specs: S): EnvRegistry<S> => {
+  const keys = Object.freeze(Object.keys(specs));
+  const registry: Record<string, unknown> = { $specs: specs, $keys: keys };
+  for (const key of keys) {
+    Object.defineProperty(registry, key, { enumerable: true, configurable: true, get: () => readEnv(key, specs[key]!) });
+  }
+  // The getters above are the only way to build a typed lazy object.
+  return registry as EnvRegistry<S>;
+};
+
+/** Any non-empty string; empty values are treated as unset before parsing. */
+export const envString = z.string();
+
+/** `true` or `1` (case-insensitive) is true; everything else is false. */
+export const envBoolean = z.string().transform((value) => {
+  const normalized = value.toLowerCase();
+  return normalized === "true" || normalized === "1";
+});
+
+/** Comma-separated entries; whitespace and empty entries are dropped. */
+export const envList = z.string().transform((value) =>
+  value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean),
+);