@azx-pbc/helix-cli 0.1.0 → 0.2.0

package/README.md

@@ -51,9 +51,15 @@ helix rollback [number]                                      # revert the live p
 ```
 
 `deploy` uploads the bundle as a **preview**; `--promote` flips it live in the
-same step (architecture §5.1). `visibility` is `private | group:<id> | password
+same step (architecture §5.1). `visibility` is `internal | group:<id> | password
 | public`.
 
+> **Breaking in 0.2.0:** the `private` visibility mode was renamed to `internal`.
+> It never checked _which_ user signed in, only that someone had. Passing the old
+> value now **errors** rather than mapping to the new one, deliberately: the name
+> is reserved for a future owner-only mode, so a silent alias would come to mean
+> the opposite of what it says. Update scripts to use `internal`.
+
 ## Authentication (M3)
 
 Two paths, in precedence order:

package/dist/helix.js

@@ -19,17 +19,17 @@ function parseCliArgs(argv) {
 }
 
 // src/client.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 
 // ../shared/src/visibility.ts
 import { z } from "zod";
 var VisibilitySchema = z.discriminatedUnion("mode", [
-  z.object({ mode: z.literal("private") }),
+  z.object({ mode: z.literal("internal") }),
   z.object({ mode: z.literal("group"), groupId: z.string().min(1) }),
   z.object({ mode: z.literal("password") }),
   z.object({ mode: z.literal("public") })
 ]);
-var VISIBILITY_MODES = ["private", "group", "password", "public"];
+var VISIBILITY_MODES = ["internal", "group", "password", "public"];
 var VisibilityModeSchema = z.enum(VISIBILITY_MODES);
 
 // ../shared/src/app.ts
@@ -104,6 +104,26 @@ var FetchCapabilitySchema = z4.object({
   /** Per-app daily proxied-request budget; unset ⇒ unbounded (fetch-proxy §7). */
   requestsPerDay: z4.int().positive().optional()
 });
+var SCOPE_SEGMENT = /^[A-Za-z0-9\-._~]+$/;
+function isValidServiceWorkerScope(scope) {
+  if (!scope.startsWith("/") || !scope.endsWith("/")) return false;
+  const segments = scope.slice(1, -1).split("/");
+  const first = segments[0];
+  if (first === void 0) return false;
+  if (segments.some((s) => s === "" || s === "." || s === ".." || !SCOPE_SEGMENT.test(s))) {
+    return false;
+  }
+  return !first.startsWith("_");
+}
+var OfflineCapabilitySchema = z4.object({
+  /**
+   * URL path prefix the worker controls, e.g. `/app/`. Leading and trailing
+   * slash required; never root, never a `_`-prefixed platform namespace.
+   */
+  scope: z4.string().refine(isValidServiceWorkerScope, {
+    message: "scope must be a non-root path prefix with a leading and trailing slash, and must not start with a reserved `_` segment (e.g. `/app/`)"
+  })
+});
 var CapabilitiesSchema = z4.object({
   llm: LlmCapabilitySchema.optional(),
   data: DataCapabilitySchema.optional(),
@@ -112,7 +132,9 @@ var CapabilitiesSchema = z4.object({
   /** Extra CSP `connect-src` origins for **direct** browser calls (§4.4). */
   externalOrigins: z4.array(z4.url()).default([]),
   /** Governed outbound HTTP via the fetch-proxy / egress plane (in build, M4.5). */
-  fetch: FetchCapabilitySchema.optional()
+  fetch: FetchCapabilitySchema.optional(),
+  /** Platform-owned, scope-confined service worker for offline cold boot (ADR-0035). */
+  offline: OfflineCapabilitySchema.optional()
 });
 var AppManifestSchema = z4.object({
   /** App slug; matches `App.slug`. */
@@ -126,12 +148,84 @@ import { z as z5 } from "zod";
 
 // ../shared/src/pricing.ts
 var MODEL_PRICING = {
-  "claude-fable-5": { inputPerMTok: 10, outputPerMTok: 50 },
-  "claude-opus-4-8": { inputPerMTok: 5, outputPerMTok: 25 },
-  "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25 },
-  "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25 },
-  "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15 },
-  "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 }
+  // Anthropic. NB `structuredOutputs` is deliberately absent on 4-7/4-6/sonnet-4-6:
+  // structured outputs are supported on Fable 5, Opus 4.8 and Haiku 4.5 but not on
+  // those three, so the flag is opt-in per model rather than per provider.
+  "claude-fable-5": {
+    inputPerMTok: 10,
+    outputPerMTok: 50,
+    provider: "anthropic",
+    structuredOutputs: true
+  },
+  "claude-opus-5": {
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    provider: "anthropic",
+    structuredOutputs: true
+  },
+  // NB list rates. Sonnet 5 has promotional $2/$10 pricing through 2026-08-31; this
+  // table drives the **cost gate**, so the list price is the safe number — it
+  // over-estimates spend during the promo rather than under-billing once it lapses.
+  "claude-sonnet-5": {
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+    provider: "anthropic",
+    structuredOutputs: true
+  },
+  "claude-opus-4-8": {
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    provider: "anthropic",
+    structuredOutputs: true
+  },
+  "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25, provider: "anthropic" },
+  "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25, provider: "anthropic" },
+  "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15, provider: "anthropic" },
+  "claude-haiku-4-5": {
+    inputPerMTok: 1,
+    outputPerMTok: 5,
+    provider: "anthropic",
+    structuredOutputs: true
+  },
+  // OpenAI — VERIFY against current published rates before production billing.
+  // Every model here resolves to a snapshot new enough for `response_format`
+  // json_schema, so `structuredOutputs` is set across the board.
+  "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10, provider: "openai", structuredOutputs: true },
+  "gpt-4o-mini": {
+    inputPerMTok: 0.15,
+    outputPerMTok: 0.6,
+    provider: "openai",
+    structuredOutputs: true
+  },
+  "gpt-4.1": { inputPerMTok: 2, outputPerMTok: 8, provider: "openai", structuredOutputs: true },
+  "gpt-4.1-mini": {
+    inputPerMTok: 0.4,
+    outputPerMTok: 1.6,
+    provider: "openai",
+    structuredOutputs: true
+  },
+  "gpt-4.1-nano": {
+    inputPerMTok: 0.1,
+    outputPerMTok: 0.4,
+    provider: "openai",
+    structuredOutputs: true
+  },
+  o3: {
+    inputPerMTok: 2,
+    outputPerMTok: 8,
+    provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
+    structuredOutputs: true
+  },
+  "o4-mini": {
+    inputPerMTok: 1.1,
+    outputPerMTok: 4.4,
+    provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
+    structuredOutputs: true
+  }
 };
 
 // ../shared/src/approval.ts
@@ -213,7 +307,7 @@ import { z as z7 } from "zod";
 var CreateAppRequestSchema = z7.object({
   slug: AppSchema.shape.slug,
   displayName: AppSchema.shape.displayName,
-  visibility: VisibilitySchema.default({ mode: "private" }),
+  visibility: VisibilitySchema.default({ mode: "internal" }),
   /** Optional per-app capability grant set at create time (architecture §6.3). */
   capabilities: CapabilitiesSchema.optional()
 });
@@ -373,7 +467,18 @@ var DeploymentConfigResponseSchema = z9.object({
    * Display-only — the gateway is the choke point, so the rollup is exact, but
    * nothing enforces this. Absent ⇒ no ceiling shown.
    */
-  platformMonthlyUsdCap: z9.number().positive().optional()
+  platformMonthlyUsdCap: z9.number().positive().optional(),
+  /**
+   * Deploy bundle size caps in megabytes (`DEPLOY_MAX_FILE_MB` /
+   * `DEPLOY_MAX_BUNDLE_MB` on the portal) — `deployMaxFileMb` is per file,
+   * `deployMaxBundleMb` the whole-archive total. A current portal always sends
+   * both; optional only to tolerate one that predates the fields, same as `url`
+   * on {@link AppSchema}. Absent means "don't state a number" — a client must not
+   * substitute a default, because printing the wrong cap to an agent sends it
+   * chasing a rejection it can't see the cause of.
+   */
+  deployMaxFileMb: z9.number().positive().optional(),
+  deployMaxBundleMb: z9.number().positive().optional()
 });
 
 // ../shared/src/scrypt.ts
@@ -400,12 +505,60 @@ var LlmUsageSchema = z10.object({
   cacheReadInputTokens: z10.int().nonnegative().default(0),
   cacheCreationInputTokens: z10.int().nonnegative().default(0)
 });
+var MAX_SCHEMA_CHARS = 32768;
+var MAX_SCHEMA_DEPTH = 12;
+function schemaDepth(value, depth = 1) {
+  if (value === null || typeof value !== "object") return depth;
+  let deepest = depth;
+  for (const child of Object.values(value)) {
+    const d = schemaDepth(child, depth + 1);
+    if (d > deepest) deepest = d;
+    if (deepest > MAX_SCHEMA_DEPTH) return deepest;
+  }
+  return deepest;
+}
+function withinSchemaBudget(schema) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(schema);
+  } catch {
+    return false;
+  }
+  return serialized.length <= MAX_SCHEMA_CHARS && schemaDepth(schema) <= MAX_SCHEMA_DEPTH;
+}
+var LlmResponseFormatSchema = z10.object({
+  type: z10.literal("json_schema"),
+  /** Schema name. OpenAI requires one; defaulted at translation when omitted. */
+  name: z10.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "must be 1-64 chars of [A-Za-z0-9_-]").optional(),
+  schema: z10.record(z10.string(), z10.unknown()).refine((s) => s.type === "object", 'schema root must be `{"type":"object"}`').refine(
+    withinSchemaBudget,
+    `schema must serialize to <= ${MAX_SCHEMA_CHARS} characters and nest <= ${MAX_SCHEMA_DEPTH} levels`
+  )
+  // NB there is deliberately no `strict` knob. Anthropic's `output_config.format`
+  // always enforces and has no best-effort mode, so a `strict:false` could only be
+  // honored on one vendor — the same request would then yield schema-violating JSON
+  // on `gpt-*` but not `claude-*`, which is exactly the provider leak this seam
+  // exists to prevent. The platform always enforces; see ADR-0034.
+});
 var LlmChatRequestSchema = z10.object({
   model: z10.string().min(1),
   messages: z10.array(LlmMessageSchema).min(1),
   /** Optional system prompt; maps to the vendor's system channel. */
   system: z10.string().optional(),
-  maxTokens: z10.int().positive().max(128e3).default(1024),
+  maxTokens: z10.int().positive().max(128e3).optional(),
+  /** Sampling temperature; forwarded as-is (the vendor validates its own range). */
+  temperature: z10.number().optional(),
+  /** Nucleus sampling; forwarded as-is. */
+  topP: z10.number().optional(),
+  /** Stop sequences; normalized to a list at the boundary. */
+  stop: z10.array(z10.string()).optional(),
+  /**
+   * Constrain the completion to a JSON schema (ADR-0034). Refused up front when
+   * the requested model can't enforce it (`ModelPrice.structuredOutputs`). The
+   * JSON still arrives as ordinary text, so `content` and the SSE `delta` frames
+   * are unchanged — callers `JSON.parse` the result.
+   */
+  responseFormat: LlmResponseFormatSchema.optional(),
   /** SSE streaming (default) vs a single JSON body. */
   stream: z10.boolean().default(true)
 });
@@ -425,142 +578,238 @@ var LlmStreamErrorSchema = z10.object({
   message: z10.string()
 });
 
-// ../shared/src/usage.ts
+// ../shared/src/llmOpenai.ts
 import { z as z11 } from "zod";
+var OpenAiRoleSchema = z11.enum(["system", "developer", "user", "assistant", "tool"]);
+var OpenAiMessageSchema = z11.object({
+  role: OpenAiRoleSchema,
+  content: z11.union([z11.string(), z11.array(z11.unknown())]).nullish(),
+  /** Present only on assistant tool-call turns — parsed to reject, never honored. */
+  tool_calls: z11.array(z11.unknown()).optional(),
+  tool_call_id: z11.string().optional(),
+  name: z11.string().optional()
+});
+var OpenAiStreamOptionsSchema = z11.object({
+  include_usage: z11.boolean().optional()
+});
+var OpenAiResponseFormatSchema = z11.discriminatedUnion("type", [
+  z11.object({
+    type: z11.literal("json_schema"),
+    json_schema: z11.object({
+      name: z11.string().optional(),
+      schema: z11.record(z11.string(), z11.unknown()),
+      strict: z11.boolean().nullish(),
+      /**
+       * Declared so the codec can reject it rather than zod silently stripping it.
+       * It is honorable on the OpenAI path but has no Anthropic equivalent, so
+       * forwarding it would make behaviour depend on the backing vendor — the same
+       * provider leak that got `json_object` rejected (ADR-0034).
+       */
+      description: z11.string().optional()
+    })
+  }),
+  z11.object({ type: z11.literal("json_object") }),
+  z11.object({ type: z11.literal("text") })
+]);
+var OpenAiChatCompletionRequestSchema = z11.object({
+  model: z11.string().min(1),
+  messages: z11.array(OpenAiMessageSchema).min(1),
+  max_tokens: z11.int().positive().max(128e3).optional(),
+  max_completion_tokens: z11.int().positive().max(128e3).optional(),
+  temperature: z11.number().optional(),
+  top_p: z11.number().optional(),
+  stop: z11.union([z11.string(), z11.array(z11.string())]).optional(),
+  stream: z11.boolean().optional(),
+  stream_options: OpenAiStreamOptionsSchema.optional(),
+  /** Declared so the codec can reject tool use in v1 (not supported). */
+  tools: z11.array(z11.unknown()).optional(),
+  tool_choice: z11.unknown().optional(),
+  /**
+   * Structured output (ADR-0034). Parsed, not rejected — see the union above.
+   * `.nullish()` because clients and proxies that serialize every field send
+   * `"response_format": null` to mean "no structured output", which is a request
+   * this surface can serve; refusing it at the envelope would be gratuitous.
+   */
+  response_format: OpenAiResponseFormatSchema.nullish(),
+  // Behaviour-changing params the platform does not honor in v1. Declared (not
+  // stripped) so the codec can reject them with a 400 rather than silently drop
+  // them — the same "reject, never silently drop" contract as `tools`.
+  n: z11.unknown().optional(),
+  seed: z11.unknown().optional(),
+  logit_bias: z11.unknown().optional(),
+  presence_penalty: z11.unknown().optional(),
+  frequency_penalty: z11.unknown().optional(),
+  logprobs: z11.unknown().optional(),
+  top_logprobs: z11.unknown().optional()
+});
+var OpenAiUsageSchema = z11.object({
+  prompt_tokens: z11.int().nonnegative(),
+  completion_tokens: z11.int().nonnegative(),
+  total_tokens: z11.int().nonnegative()
+});
+var OpenAiChatCompletionResponseSchema = z11.object({
+  id: z11.string(),
+  object: z11.literal("chat.completion"),
+  created: z11.int(),
+  model: z11.string(),
+  choices: z11.array(
+    z11.object({
+      index: z11.int(),
+      message: z11.object({
+        role: z11.literal("assistant"),
+        content: z11.string()
+      }),
+      finish_reason: z11.string()
+    })
+  ),
+  usage: OpenAiUsageSchema
+});
+var OpenAiChatCompletionChunkSchema = z11.object({
+  id: z11.string(),
+  object: z11.literal("chat.completion.chunk"),
+  created: z11.int(),
+  model: z11.string(),
+  choices: z11.array(
+    z11.object({
+      index: z11.int(),
+      delta: z11.object({
+        role: z11.literal("assistant").optional(),
+        content: z11.string().optional()
+      }),
+      finish_reason: z11.string().nullable()
+    })
+  ),
+  usage: OpenAiUsageSchema.nullish()
+});
+var OpenAiModelSchema = z11.object({
+  id: z11.string(),
+  object: z11.literal("model"),
+  created: z11.int(),
+  owned_by: z11.string()
+});
+var OpenAiModelListSchema = z11.object({
+  object: z11.literal("list"),
+  data: z11.array(OpenAiModelSchema)
+});
+
+// ../shared/src/usage.ts
+import { z as z12 } from "zod";
 var GATEWAY_OUTCOMES = ["ok", "error", "refusal", "quota_blocked"];
-var GatewayOutcomeSchema = z11.enum(GATEWAY_OUTCOMES);
+var GatewayOutcomeSchema = z12.enum(GATEWAY_OUTCOMES);
 var USAGE_RANGES = ["24h", "7d", "30d"];
-var UsageRangeSchema = z11.enum(USAGE_RANGES);
+var UsageRangeSchema = z12.enum(USAGE_RANGES);
 var PLATFORM_RANGES = ["7d", "30d", "90d"];
-var PlatformRangeSchema = z11.enum(PLATFORM_RANGES);
-var UsageSeriesPointSchema = z11.object({
-  bucket: z11.iso.datetime(),
-  costUsd: z11.number().nonnegative(),
-  tokens: z11.int().nonnegative(),
-  requests: z11.int().nonnegative()
-});
-var UsageSummarySchema = z11.object({
-  appId: z11.uuid(),
+var PlatformRangeSchema = z12.enum(PLATFORM_RANGES);
+var UsageSeriesPointSchema = z12.object({
+  bucket: z12.iso.datetime(),
+  costUsd: z12.number().nonnegative(),
+  tokens: z12.int().nonnegative(),
+  requests: z12.int().nonnegative()
+});
+var UsageSummarySchema = z12.object({
+  appId: z12.uuid(),
   /** The rolling range these figures cover. */
   range: UsageRangeSchema,
-  requests: z11.int().nonnegative(),
-  inputTokens: z11.int().nonnegative(),
-  outputTokens: z11.int().nonnegative(),
+  requests: z12.int().nonnegative(),
+  inputTokens: z12.int().nonnegative(),
+  outputTokens: z12.int().nonnegative(),
   /** Cache-aware input token totals (0 until prompt caching is enabled). */
-  cacheReadInputTokens: z11.int().nonnegative(),
-  cacheCreationInputTokens: z11.int().nonnegative(),
+  cacheReadInputTokens: z12.int().nonnegative(),
+  cacheCreationInputTokens: z12.int().nonnegative(),
   /** Estimated spend in USD over the window at current rates (./pricing.ts). */
-  costUsd: z11.number().nonnegative(),
+  costUsd: z12.number().nonnegative(),
   /** 95th-percentile upstream latency (ms) over the window; null when no timed calls. */
-  latencyP95Ms: z11.number().nonnegative().nullable(),
+  latencyP95Ms: z12.number().nonnegative().nullable(),
   /** Fraction of calls in the window whose outcome was not `ok` (0..1). */
-  errorRate: z11.number().min(0).max(1),
+  errorRate: z12.number().min(0).max(1),
   /** Count of calls keyed by outcome (`ok` / `error` / `refusal` / `quota_blocked`). */
-  byOutcome: z11.record(z11.string(), z11.int().nonnegative()),
-  byModel: z11.array(
-    z11.object({
-      model: z11.string(),
-      tokens: z11.int().nonnegative(),
-      requests: z11.int().nonnegative(),
+  byOutcome: z12.record(z12.string(), z12.int().nonnegative()),
+  byModel: z12.array(
+    z12.object({
+      model: z12.string(),
+      tokens: z12.int().nonnegative(),
+      requests: z12.int().nonnegative(),
       /** Estimated spend in USD for this model over the window. */
-      costUsd: z11.number().nonnegative()
+      costUsd: z12.number().nonnegative()
     })
   ),
   /** Dense, zero-filled buckets across the range, oldest-first, for the trend chart. */
-  series: z11.array(UsageSeriesPointSchema),
+  series: z12.array(UsageSeriesPointSchema),
   /**
    * Today-since-midnight totals, independent of `range` — backs the daily-cap
    * gauge (the budget the edge enforces is per calendar day).
    */
-  today: z11.object({
-    tokens: z11.int().nonnegative(),
-    costUsd: z11.number().nonnegative()
+  today: z12.object({
+    tokens: z12.int().nonnegative(),
+    costUsd: z12.number().nonnegative()
   })
 });
-var GatewayCallSchema = z11.object({
-  id: z11.uuid(),
-  appId: z11.uuid(),
+var GatewayCallSchema = z12.object({
+  id: z12.uuid(),
+  appId: z12.uuid(),
   /** App slug at read time; null when the app row no longer exists. */
-  slug: z11.string().nullable(),
-  userOid: z11.string(),
-  capability: z11.string(),
-  model: z11.string(),
-  inputTokens: z11.int().nonnegative(),
-  outputTokens: z11.int().nonnegative(),
-  cacheReadInputTokens: z11.int().nonnegative(),
-  cacheCreationInputTokens: z11.int().nonnegative(),
+  slug: z12.string().nullable(),
+  userOid: z12.string(),
+  capability: z12.string(),
+  model: z12.string(),
+  inputTokens: z12.int().nonnegative(),
+  outputTokens: z12.int().nonnegative(),
+  cacheReadInputTokens: z12.int().nonnegative(),
+  cacheCreationInputTokens: z12.int().nonnegative(),
   /** Estimated spend in USD for this single call at current rates. */
-  costUsd: z11.number().nonnegative(),
+  costUsd: z12.number().nonnegative(),
   /** Upstream round-trip latency in ms (0 when not measured). */
-  durationMs: z11.int().nonnegative(),
+  durationMs: z12.int().nonnegative(),
   /** Upstream/egress HTTP status — set for `fetch`; null for streamed `llm`. */
-  statusCode: z11.int().nullable(),
+  statusCode: z12.int().nullable(),
   /** LLM stop reason; null for non-LLM calls. */
-  stopReason: z11.string().nullable(),
+  stopReason: z12.string().nullable(),
   /** Short upstream error string; null on success. */
-  errorDetail: z11.string().nullable(),
+  errorDetail: z12.string().nullable(),
   outcome: GatewayOutcomeSchema,
-  createdAt: z11.iso.datetime()
+  createdAt: z12.iso.datetime()
 });
-var GatewayAuditPageSchema = z11.object({
-  rows: z11.array(GatewayCallSchema),
+var GatewayAuditPageSchema = z12.object({
+  rows: z12.array(GatewayCallSchema),
   /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
-  nextBefore: z11.iso.datetime().optional()
+  nextBefore: z12.iso.datetime().optional()
 });
-var PlatformUsageSchema = z11.object({
+var PlatformUsageSchema = z12.object({
   /** The rolling range the series + breakdowns cover. */
   range: PlatformRangeSchema,
   /** Dense, zero-filled daily buckets across the range, oldest-first. */
-  series: z11.array(UsageSeriesPointSchema),
+  series: z12.array(UsageSeriesPointSchema),
   /** Per-app rollup over the range, busiest-first. */
-  byApp: z11.array(
-    z11.object({
-      slug: z11.string().nullable(),
-      tokens: z11.int().nonnegative(),
-      requests: z11.int().nonnegative(),
+  byApp: z12.array(
+    z12.object({
+      slug: z12.string().nullable(),
+      tokens: z12.int().nonnegative(),
+      requests: z12.int().nonnegative(),
       /** Estimated spend in USD for this app over the range. */
-      costUsd: z11.number().nonnegative()
+      costUsd: z12.number().nonnegative()
     })
   ),
   /** Month-to-date headline KPIs (independent of `range`). */
-  totals: z11.object({
-    tokensMTD: z11.int().nonnegative(),
-    requestsMTD: z11.int().nonnegative(),
+  totals: z12.object({
+    tokensMTD: z12.int().nonnegative(),
+    requestsMTD: z12.int().nonnegative(),
     /** Estimated month-to-date spend in USD across all apps. */
-    costMTD: z11.number().nonnegative(),
+    costMTD: z12.number().nonnegative(),
     /** Distinct `userOid`s seen month-to-date. */
-    activeUsers: z11.int().nonnegative()
+    activeUsers: z12.int().nonnegative()
   }),
   /** Token + cost share by capability over the range (essentially all `llm` in M4). */
-  capabilityMix: z11.array(
-    z11.object({
-      capability: z11.string(),
-      tokens: z11.int().nonnegative(),
+  capabilityMix: z12.array(
+    z12.object({
+      capability: z12.string(),
+      tokens: z12.int().nonnegative(),
       /** Estimated spend in USD for this capability over the range. */
-      costUsd: z11.number().nonnegative()
+      costUsd: z12.number().nonnegative()
     })
   )
 });
 
 // ../shared/src/data.ts
-import { z as z12 } from "zod";
-var CollectionItemSchema = z12.object({
-  id: z12.uuid(),
-  collection: z12.string(),
-  /** The submitting user, if authenticated; null for anonymous/public visitors. */
-  userOid: z12.string().nullable(),
-  item: z12.unknown(),
-  /** Hashed IP / truncated UA for abuse triage; null if not captured. */
-  meta: z12.unknown().nullable(),
-  createdAt: z12.iso.datetime()
-});
-var CollectionItemsPageSchema = z12.object({
-  rows: z12.array(CollectionItemSchema),
-  /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
-  nextBefore: z12.iso.datetime().optional()
-});
-
-// ../shared/src/secrets.ts
 import { z as z14 } from "zod";
 
 // ../shared/src/env.ts
@@ -568,46 +817,160 @@ import { z as z13 } from "zod";
 var ENVS = ["prod", "dev"];
 var EnvSchema = z13.enum(ENVS);
 
+// ../shared/src/data.ts
+var CollectionItemSchema = z14.object({
+  id: z14.uuid(),
+  collection: z14.string(),
+  /**
+   * Which tier collected the row (dev-mode §5). The runtime roles are RLS-pinned
+   * to one tier each, but the portal reads across both, so the discriminator has
+   * to travel — otherwise a developer's dev-mode test submissions are
+   * indistinguishable from real prod leads in the drain.
+   */
+  env: EnvSchema,
+  /** The submitting user, if authenticated; null for anonymous/public visitors. */
+  userOid: z14.string().nullable(),
+  item: z14.unknown(),
+  /** Hashed IP / truncated UA for abuse triage; null if not captured. */
+  meta: z14.unknown().nullable(),
+  createdAt: z14.iso.datetime()
+});
+var CollectionItemsPageSchema = z14.object({
+  rows: z14.array(CollectionItemSchema),
+  /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
+  nextBefore: z14.iso.datetime().optional()
+});
+var CollectionSummarySchema = z14.object({
+  name: z14.string(),
+  env: EnvSchema,
+  count: z14.int().nonnegative(),
+  /** Newest row's timestamp; null only if the group is somehow empty. */
+  lastAt: z14.iso.datetime().nullable()
+});
+
+// ../shared/src/collectionTable.ts
+var BOM = String.fromCharCode(65279);
+
 // ../shared/src/secrets.ts
-var InjectionRecipeSchema = z14.discriminatedUnion("kind", [
+import { z as z15 } from "zod";
+var FORBIDDEN_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "host",
+  "content-length",
+  "transfer-encoding",
+  "connection",
+  "te",
+  "upgrade",
+  "expect",
+  "trailer"
+]);
+var HEADER_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+var HEADER_VALUE_SAFE = /^[\t\x20-\x7e]*$/;
+var HEADER_VALUE_WIRE = /^[\t\x20-\x7e\x80-\xff]*$/;
+var headerName = (from) => {
+  const base = z15.string().min(1);
+  return (from === "request" ? base.max(64).regex(HEADER_TOKEN, "must be an RFC 7230 token") : base).transform((n) => n.trim().toLowerCase()).refine((n) => !FORBIDDEN_HEADER_NAMES.has(n), "reserved header name").refine((n) => !n.startsWith("x-helix-"), "reserved header prefix");
+};
+var headerTemplate = (from) => from === "request" ? z15.string().max(512).regex(HEADER_VALUE_SAFE) : z15.string().regex(HEADER_VALUE_WIRE);
+var injectionRecipe = (from) => z15.discriminatedUnion("kind", [
   /** `Authorization: Bearer <secret>` — the common case. */
-  z14.object({ kind: z14.literal("header-bearer") }),
+  z15.object({ kind: z15.literal("header-bearer") }),
   /** Arbitrary header; `{}` in `template` is replaced with the secret. */
-  z14.object({
-    kind: z14.literal("header"),
-    name: z14.string().min(1),
-    template: z14.string().default("{}")
+  z15.object({
+    kind: z15.literal("header"),
+    name: headerName(from),
+    template: headerTemplate(from).default("{}")
   }),
   /** Query parameter `?<param>=<secret>`. */
-  z14.object({ kind: z14.literal("query"), param: z14.string().min(1) })
+  z15.object({ kind: z15.literal("query"), param: z15.string().min(1) }),
+  /**
+   * HMAC over a timestamp. The signed input is the timestamp string **alone** —
+   * not the method, path, query, or body — so injection is a pure function of
+   * (private key, now) and needs no request context.
+   *
+   * The canonical form lives in the KIND NAME, deliberately. A scheme that signs
+   * method+path+body is a *sibling kind* (`hmac-request`) — a code change with
+   * tests, reviewed — never an admin-editable canonical-string template.
+   * Canonicalization is where implementations of this family go wrong, and it
+   * does not belong in a text box.
+   *
+   * SHA-256, lowercase-hex, and ISO-8601-with-milliseconds are fixed rather than
+   * configurable. Each would carry a default, and `app_secrets.injection` is a
+   * schemaless JSON column, so adding a knob later is purely additive with no
+   * migration — while fixing them now removes the weak-algorithm and
+   * unencodable-digest failure classes outright.
+   *
+   * The stored value is a JSON blob carrying both halves of the key pair
+   * ({@link HmacCredentialSchema}): regenerating the pair changes both, and a
+   * blob rotates atomically through the existing rotate route.
+   */
+  z15.object({
+    kind: z15.literal("hmac-timestamp"),
+    /** Header carrying the timestamp that is also the entire signed input. */
+    timestampHeader: headerName(from),
+    /** Header carrying the rendered credential + signature. */
+    authHeader: headerName(from).default("authorization"),
+    /**
+     * Value written to `authHeader`. `{credential}` and `{signature}` are
+     * substituted. Named rather than the `header` kind's bare `{}` because there
+     * are two substitutions: the convention is one value ⇒ `{}`, more than one ⇒
+     * named placeholders. Positional `{}` here would let a swapped template
+     * produce a well-formed header that silently fails to authenticate.
+     *
+     * Both placeholders are required. This recipe writes exactly two headers,
+     * one of them the timestamp, so there is no configuration where the public
+     * credential id travels elsewhere — omitting `{credential}` means the
+     * upstream can never identify the key and every call 401s.
+     */
+    template: headerTemplate(from).refine((t) => t.includes("{signature}"), "template must contain {signature}").refine((t) => t.includes("{credential}"), "template must contain {credential}")
+  }).refine(
+    (r) => r.timestampHeader !== r.authHeader,
+    "timestampHeader and authHeader must differ \u2014 the second write overwrites the first"
+  )
 ]);
+var InjectionRecipeSchema = injectionRecipe("request");
+var StoredInjectionRecipeSchema = injectionRecipe("stored");
+var HmacCredentialSchema = z15.object({
+  credential: z15.string().min(1),
+  key: z15.string().min(1)
+});
 var SECRET_SCOPES = ["app", "global", "platform"];
-var SecretScopeSchema = z14.enum(SECRET_SCOPES);
-var SecretMetadataSchema = z14.object({
-  id: z14.string(),
-  name: z14.string().min(1),
+var SecretScopeSchema = z15.enum(SECRET_SCOPES);
+var SecretMetadataSchema = z15.object({
+  id: z15.string(),
+  name: z15.string().min(1),
   scope: SecretScopeSchema,
   /** Partition tier (dev-mode §6): a dev fetch injects only `dev` connection secrets. */
   env: EnvSchema,
-  injection: InjectionRecipeSchema,
-  createdBy: z14.string(),
-  createdAt: z14.string(),
-  rotatedAt: z14.string().nullable().optional(),
-  lastUsedAt: z14.string().nullable().optional(),
-  boundApps: z14.array(z14.string()).default([])
-});
-var SecretCreateRequestSchema = z14.object({
-  name: z14.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits, and hyphens"),
-  value: z14.string().min(1),
+  /**
+   * The **stored** parser, not the strict one — this field describes a row, and
+   * the SPA re-parses this schema on every response. Using the strict parser here
+   * would let the portal return a name the browser then refuses, moving the read
+   * failure from the server to the client, where it presents as a dead page.
+   *
+   * `null` = the stored recipe is unreadable (it names a reserved header, or is
+   * not a recipe at all). The credential still exists and is still deletable; it
+   * cannot be rotated, and egress fails its hop closed. Recipes are immutable by
+   * design, so recovery is delete-and-recreate.
+   */
+  injection: StoredInjectionRecipeSchema.nullable(),
+  createdBy: z15.string(),
+  createdAt: z15.string(),
+  rotatedAt: z15.string().nullable().optional(),
+  lastUsedAt: z15.string().nullable().optional(),
+  boundApps: z15.array(z15.string()).default([])
+});
+var SecretCreateRequestSchema = z15.object({
+  name: z15.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits, and hyphens"),
+  value: z15.string().min(1),
   /** Target tier (dev-mode §6). Defaults `prod`; `dev` configures a dev-tier credential. */
   env: EnvSchema.default("prod"),
   injection: InjectionRecipeSchema.default({ kind: "header-bearer" })
 });
-var SecretRotateRequestSchema = z14.object({ value: z14.string().min(1) });
-var SecretGrantRequestSchema = z14.object({ appSlug: z14.string().min(1) });
+var SecretRotateRequestSchema = z15.object({ value: z15.string().min(1) });
+var SecretGrantRequestSchema = z15.object({ appSlug: z15.string().min(1) });
 
 // ../shared/src/devTokens.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 function isValidDevOrigin(input) {
   if (input.includes("*")) return false;
   let url;
@@ -621,47 +984,47 @@ function isValidDevOrigin(input) {
   if (url.username !== "" || url.password !== "") return false;
   return input === url.origin || input === `${url.origin}/`;
 }
-var DevOriginSchema = z15.string().refine(
+var DevOriginSchema = z16.string().refine(
   isValidDevOrigin,
   "must be an exact origin (scheme://host[:port]) \u2014 no path, query, or wildcard"
 ).transform((o) => new URL(o).origin);
-var TtlDaysSchema = z15.number().int().min(1).max(365).optional();
-var DevTokenMintRequestSchema = z15.object({
-  origins: z15.array(DevOriginSchema).min(1).max(20),
+var TtlDaysSchema = z16.number().int().min(1).max(365).optional();
+var DevTokenMintRequestSchema = z16.object({
+  origins: z16.array(DevOriginSchema).min(1).max(20),
   ttlDays: TtlDaysSchema
 });
-var DevTokenRotateRequestSchema = z15.object({
+var DevTokenRotateRequestSchema = z16.object({
   ttlDays: TtlDaysSchema
 });
-var DevTokenMetadataSchema = z15.object({
-  id: z15.string(),
-  developerOid: z15.string(),
-  origins: z15.array(z15.string()),
-  expiresAt: z15.string(),
-  revokedAt: z15.string().nullable().optional(),
-  createdAt: z15.string()
-});
-var DevTokenMintResponseSchema = z15.object({
-  token: z15.string(),
+var DevTokenMetadataSchema = z16.object({
+  id: z16.string(),
+  developerOid: z16.string(),
+  origins: z16.array(z16.string()),
+  expiresAt: z16.string(),
+  revokedAt: z16.string().nullable().optional(),
+  createdAt: z16.string()
+});
+var DevTokenMintResponseSchema = z16.object({
+  token: z16.string(),
   metadata: DevTokenMetadataSchema
 });
 
 // ../shared/src/instruction.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var INSTRUCTION_CAPABILITIES = ["fetch", "llm"];
-var InstructionCapabilitySchema = z16.enum(INSTRUCTION_CAPABILITIES);
-var AttestedInstructionSchema = z16.object({
+var InstructionCapabilitySchema = z17.enum(INSTRUCTION_CAPABILITIES);
+var AttestedInstructionSchema = z17.object({
   /** App the call is attributed to (registry app id). */
-  appId: z16.string().min(1),
+  appId: z17.string().min(1),
   /** Authenticated user, or the anonymous sentinel on `public` apps. */
-  userOid: z16.string().min(1),
+  userOid: z17.string().min(1),
   capability: InstructionCapabilitySchema,
   /** The allowlisted origin the edge authorized (scheme + host + port). */
-  origin: z16.url(),
+  origin: z17.url(),
   /** Connection (secret) name to inject, if this is a secret-backed call. */
-  connection: z16.string().min(1).optional(),
+  connection: z17.string().min(1).optional(),
   /** Correlates the edge audit row with the egress call. */
-  requestId: z16.string().min(1),
+  requestId: z17.string().min(1),
   /**
    * The HTTP method + URL pathname the edge authorized (ADR-0013 step 2, issue #6).
    * Egress refuses a mismatched verb/resource, so a captured instruction can't be
@@ -676,8 +1039,8 @@ var AttestedInstructionSchema = z16.object({
    * means "old edge", not tampering — egress asserts ONLY when the claim is
    * present. Make required once a fleet is reliably past deploy.
    */
-  method: z16.string().min(1).optional(),
-  path: z16.string().optional(),
+  method: z17.string().min(1).optional(),
+  path: z17.string().optional(),
   /**
    * Environment tier this call is scoped to (dev-mode design §6). Egress resolves
    * the connection secret within this tier — a `dev` instruction can never reach a
@@ -691,7 +1054,7 @@ var INSTRUCTION_TTL_SECONDS = 30;
 var INSTRUCTION_BURN_RETENTION_SECONDS = INSTRUCTION_TTL_SECONDS + 15;
 
 // ../shared/src/fetch.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 var FETCH_ERROR_CODES = [
   "forbidden",
   "rate_limited",
@@ -701,10 +1064,10 @@ var FETCH_ERROR_CODES = [
   "replay",
   "upstream_error"
 ];
-var FetchErrorCodeSchema = z17.enum(FETCH_ERROR_CODES);
-var FetchProxyErrorSchema = z17.object({
+var FetchErrorCodeSchema = z18.enum(FETCH_ERROR_CODES);
+var FetchProxyErrorSchema = z18.object({
   code: FetchErrorCodeSchema,
-  message: z17.string()
+  message: z18.string()
 });
 
 // src/client.ts
@@ -716,7 +1079,7 @@ var CliError = class extends Error {
     this.code = code;
   }
 };
-var VersionListSchema = z18.array(VersionSchema);
+var VersionListSchema = z19.array(VersionSchema);
 var PortalClient = class {
   #baseUrl;
   #tokenProvider;
@@ -938,10 +1301,15 @@ function parseVisibility(input) {
     if (!groupId) throw new CliError("group visibility needs an id: group:<id>");
     return { mode: "group", groupId };
   }
-  if (input === "private" || input === "password" || input === "public") {
+  if (input === "internal" || input === "password" || input === "public") {
     return { mode: input };
   }
-  throw new CliError(`invalid visibility "${input}" (private | group:<id> | password | public)`);
+  if (input === "private") {
+    throw new CliError(
+      'visibility "private" was renamed to "internal" (the mode never checked which user signed in, only that someone had). Use --visibility internal; the name "private" is reserved for a future owner-only mode, so it is not accepted as an alias.'
+    );
+  }
+  throw new CliError(`invalid visibility "${input}" (internal | group:<id> | password | public)`);
 }
 function printVersion(v) {
   console.log(`  version ${v.number} (${v.status}) \u2014 ${v.id}`);
@@ -1113,7 +1481,7 @@ Usage:
 Common flags: --slug <slug>  --portal-url <url>  --token <token>
 Env:  HELIX_PORTAL_URL, HELIX_TOKEN (static token \u2014 skips login; CI/scripts).
 Config file: helix.json { slug, portalUrl, dir }
-Visibility: private | group:<id> | password | public
+Visibility: internal | group:<id> | password | public
 `;
 async function main() {
   const { values, positionals } = parseCliArgs(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azx-pbc/helix-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deploy CLI for Helix, the AZX App Platform",
   "license": "MIT",
   "repository": {