@azx-pbc/helix-cli 0.0.0 → 0.1.0

package/dist/helix.js

@@ -0,0 +1,1185 @@
+#!/usr/bin/env node
+
+// src/args.ts
+import { parseArgs } from "node:util";
+var options = {
+  slug: { type: "string" },
+  "portal-url": { type: "string" },
+  dir: { type: "string" },
+  bundle: { type: "string" },
+  token: { type: "string" },
+  promote: { type: "boolean" },
+  "display-name": { type: "string" },
+  visibility: { type: "string" },
+  help: { type: "boolean" }
+};
+function parseCliArgs(argv) {
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  return parseArgs({ args, allowPositionals: true, options });
+}
+
+// src/client.ts
+import { z as z18 } 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("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 VisibilityModeSchema = z.enum(VISIBILITY_MODES);
+
+// ../shared/src/app.ts
+import { z as z2 } from "zod";
+var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+var AppSchema = z2.object({
+  id: z2.uuid(),
+  slug: z2.string().min(1).max(63).regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  displayName: z2.string().min(1).max(200),
+  visibility: VisibilitySchema,
+  /** The version currently served; null before the first deploy. */
+  currentVersionId: z2.uuid().nullable(),
+  /** When set, the app is archived: the edge serves 410 + Clear-Site-Data (§7). */
+  archivedAt: z2.iso.datetime().nullable(),
+  createdAt: z2.iso.datetime(),
+  updatedAt: z2.iso.datetime(),
+  /**
+   * Where this app is served, computed control-plane-side from the deployment's
+   * apps base (`APP_PUBLIC_BASE`) — so clients render a URL instead of
+   * templating `<slug>.<domain>` themselves and drifting per deployment. Optional
+   * on the wire: the CLI parses this schema, so requiring it would break a newer
+   * CLI against an older portal. Clients that lack it fall back to composing the
+   * slug onto `appPublicBase` from `GET /api/v1/config`.
+   */
+  url: z2.url().optional()
+});
+
+// ../shared/src/version.ts
+import { z as z3 } from "zod";
+var VERSION_STATUSES = ["preview", "live", "archived"];
+var VersionStatusSchema = z3.enum(VERSION_STATUSES);
+var VersionSchema = z3.object({
+  id: z3.uuid(),
+  appId: z3.uuid(),
+  /** Monotonic per app, 1-based. */
+  number: z3.int().positive(),
+  /** Blob key prefix for this version's assets, e.g. `apps/<appId>/7/`. */
+  blobPrefix: z3.string().min(1),
+  status: VersionStatusSchema,
+  createdAt: z3.iso.datetime()
+});
+
+// ../shared/src/manifest.ts
+import { z as z4 } from "zod";
+var LlmCapabilitySchema = z4.object({
+  models: z4.array(z4.string()).default([]),
+  /**
+   * Per-app daily LLM spend cap in USD; unset ⇒ unbounded. Denominated in
+   * dollars (not tokens) so the cap means the same thing across models — the
+   * edge prices each call via `@azx-pbc/shared` pricing and enforces a daily +
+   * rolling-hour burst window off the frozen `costMicroUsd` ledger column.
+   */
+  dollarsPerDay: z4.number().positive().optional()
+});
+var DataCapabilitySchema = z4.object({
+  user: z4.boolean().default(false),
+  collections: z4.array(z4.string().min(1)).default([]),
+  sharedRead: z4.array(z4.string().min(1)).default([]),
+  sharedWrite: z4.array(z4.string().min(1)).default([]),
+  writesPerDay: z4.int().positive().optional(),
+  bytesPerDay: z4.int().positive().optional()
+});
+var FetchConnectionSchema = z4.object({
+  origin: z4.url(),
+  connection: z4.string().min(1).optional()
+});
+var FetchCapabilitySchema = z4.object({
+  /** Opt-in transparent `fetch` shim injected at serve time (fetch-proxy §3.2). */
+  shim: z4.boolean().default(false),
+  /** Origins reached through the proxy (mode `proxy`); direct stays in `externalOrigins`. */
+  origins: z4.array(FetchConnectionSchema).default([]),
+  /** Per-app daily proxied-request budget; unset ⇒ unbounded (fetch-proxy §7). */
+  requestsPerDay: z4.int().positive().optional()
+});
+var CapabilitiesSchema = z4.object({
+  llm: LlmCapabilitySchema.optional(),
+  data: DataCapabilitySchema.optional(),
+  /** Platform-registered MCP servers this app may reach (§6.1, exposed as REST). */
+  mcp: z4.array(z4.string()).default([]),
+  /** 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()
+});
+var AppManifestSchema = z4.object({
+  /** App slug; matches `App.slug`. */
+  app: z4.string().min(1),
+  visibility: VisibilitySchema,
+  capabilities: CapabilitiesSchema.default({ mcp: [], externalOrigins: [] })
+});
+
+// ../shared/src/approval.ts
+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 }
+};
+
+// ../shared/src/approval.ts
+var RISK_LEVELS = ["low", "med", "high"];
+var RiskSchema = z5.enum(RISK_LEVELS);
+var APPROVAL_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "withdrawn",
+  "needs_changes"
+];
+var ApprovalStatusSchema = z5.enum(APPROVAL_STATUSES);
+var DeltaSchema = z5.object({
+  path: z5.string(),
+  from: z5.union([z5.string(), z5.number(), z5.boolean()]).optional(),
+  to: z5.union([z5.string(), z5.number(), z5.boolean()]).optional()
+});
+var ApprovalRequestSchema = z5.object({
+  id: z5.string(),
+  appId: z5.string(),
+  /** Joined for the admin queue / banner; not a column. */
+  appSlug: z5.string().optional(),
+  appDisplayName: z5.string().optional(),
+  status: ApprovalStatusSchema,
+  risk: RiskSchema,
+  deltas: z5.array(DeltaSchema),
+  baseSnapshot: z5.unknown(),
+  requestedBy: z5.string(),
+  reason: z5.string().nullable().optional(),
+  decidedBy: z5.string().nullable().optional(),
+  decisionNote: z5.string().nullable().optional(),
+  createdAt: z5.string(),
+  decidedAt: z5.string().nullable().optional()
+});
+var ManifestUpdateResultSchema = z5.object({
+  manifest: AppManifestSchema,
+  applied: z5.array(DeltaSchema),
+  pending: z5.string().nullable()
+});
+var VisibilityUpdateResultSchema = z5.object({
+  app: AppSchema,
+  applied: z5.array(DeltaSchema),
+  pending: z5.string().nullable()
+});
+var ApprovalDecisionRequestSchema = z5.object({
+  note: z5.string().max(2e3).optional()
+});
+var CURATED_LLM_MODELS = Object.keys(MODEL_PRICING);
+
+// ../shared/src/health.ts
+import { z as z6 } from "zod";
+var HealthStateSchema = z6.enum(["ok", "degraded", "error"]);
+var HealthCheckSchema = z6.object({
+  /** Stable identifier an alert rule can key on, e.g. `registry-projection`. */
+  name: z6.string(),
+  status: HealthStateSchema,
+  /** Operator-facing one-liner: what is wrong, and for how long. */
+  detail: z6.string().optional(),
+  /** Wall-clock instant this check last succeeded. Report-only — never the
+   *  basis of a staleness decision (see the monotonic note in the edge's
+   *  registry projection). */
+  lastSuccessAt: z6.iso.datetime().optional(),
+  /** Numeric facts a dashboard or a log-based metric can key on. */
+  metrics: z6.record(z6.string(), z6.number()).optional()
+});
+var HealthStatusSchema = z6.object({
+  /** The roll-up: the worst state across `checks` (see `worstHealthState`). */
+  status: HealthStateSchema,
+  service: z6.string(),
+  /** Process uptime in seconds. */
+  uptime: z6.number().nonnegative(),
+  /** Absent means the service reports liveness only (portal and egress today). */
+  checks: z6.array(HealthCheckSchema).optional()
+});
+
+// ../shared/src/api.ts
+import { z as z7 } from "zod";
+var CreateAppRequestSchema = z7.object({
+  slug: AppSchema.shape.slug,
+  displayName: AppSchema.shape.displayName,
+  visibility: VisibilitySchema.default({ mode: "private" }),
+  /** Optional per-app capability grant set at create time (architecture §6.3). */
+  capabilities: CapabilitiesSchema.optional()
+});
+var SetManifestRequestSchema = z7.object({
+  capabilities: CapabilitiesSchema,
+  /** Justification carried onto an approval request for any elevated deltas. */
+  reason: z7.string().max(2e3).optional()
+});
+var SetVisibilityRequestSchema = z7.object({
+  visibility: VisibilitySchema,
+  /** Justification carried onto the approval request when going public. */
+  reason: z7.string().max(2e3).optional()
+});
+var MIN_PASSWORD_LENGTH = 12;
+var SetPasswordRequestSchema = z7.object({
+  password: z7.string().min(MIN_PASSWORD_LENGTH).optional()
+});
+var PasswordCredentialResponseSchema = z7.object({
+  /** The shared passphrase, in cleartext, for the owner to copy/share. */
+  password: z7.string().min(1),
+  /** The app's public URL, prebuilt so the UI can offer a one-click copy. */
+  url: z7.url(),
+  /** When the current password was set (ISO 8601). */
+  setAt: z7.string()
+});
+var CspWarningSchema = z7.object({
+  file: z7.string(),
+  origin: z7.string(),
+  hint: z7.string()
+});
+var OriginGrantRequestSchema = z7.object({
+  origin: z7.url(),
+  reason: z7.string().max(2e3).optional()
+});
+var CspViolationSchema = z7.object({
+  appId: z7.string(),
+  appSlug: z7.string().nullable(),
+  directive: z7.string(),
+  blockedUri: z7.string(),
+  count: z7.number().int(),
+  lastSeen: z7.string(),
+  /**
+   * The blocked origin is already permitted by the app's *current* manifest, so
+   * this historical report is no longer actionable. Derived at read time
+   * (directive-aware — only `connect-src`/`img-src` are widened by an
+   * `externalOrigins` grant); the row itself is never deleted.
+   */
+  resolved: z7.boolean()
+});
+var CspViolationsPageSchema = z7.object({
+  violations: z7.array(CspViolationSchema)
+});
+var UploadVersionResponseSchema = z7.object({
+  version: VersionSchema,
+  warnings: z7.array(CspWarningSchema)
+});
+var RollbackRequestSchema = z7.object({
+  toNumber: z7.int().positive().optional()
+});
+var API_ERROR_CODES = [
+  "validation_failed",
+  "not_found",
+  "slug_taken",
+  "bundle_invalid",
+  "unauthorized",
+  /** Authenticated but not allowed — reserved for v1 RBAC. */
+  "forbidden",
+  "conflict",
+  /** Gateway: requested model is not in the app's manifest allowlist (§6.3). */
+  "model_not_allowed",
+  /** Gateway: the app's daily token budget is exhausted (§6.1). */
+  "quota_exceeded",
+  /**
+   * Gateway: the anonymous tier's per-IP request budget is exhausted on a
+   * `public` app (app-data design §7). Distinct from `quota_exceeded` (per-app
+   * daily budget) so the app can tell per-IP throttling apart from running out
+   * of its own budget. HTTP 429.
+   */
+  "rate_limited",
+  /** Gateway: a configured capability is not available on this edge. */
+  "capability_unavailable",
+  "internal"
+];
+var ApiErrorCodeSchema = z7.enum(API_ERROR_CODES);
+var ApiErrorSchema = z7.object({
+  error: z7.object({
+    code: ApiErrorCodeSchema,
+    message: z7.string(),
+    details: z7.unknown().optional()
+  })
+});
+
+// ../shared/src/auth.ts
+import { z as z8 } from "zod";
+var MeResponseSchema = z8.object({
+  user: z8.object({
+    /** IdP subject (Entra object id) — stable, safe to key app data on. */
+    id: z8.string(),
+    displayName: z8.string()
+  })
+});
+var PortalMeResponseSchema = z8.object({
+  sub: z8.string(),
+  /** How the actor was established: `oidc` or `dev-token`. */
+  via: z8.string(),
+  name: z8.string().optional(),
+  email: z8.string().optional(),
+  /**
+   * Whether the actor holds the `platform-admin` role. Computed server-side from
+   * the actor's group/role claim — the raw ids never cross to the browser. Drives
+   * admin nav + route gating in the SPA (and `helix whoami`).
+   */
+  isAdmin: z8.boolean()
+});
+var AuthConfigResponseSchema = z8.object({
+  issuer: z8.url(),
+  cliClientId: z8.string().min(1),
+  /** Public client the portal SPA uses for code+PKCE in the browser. */
+  webClientId: z8.string().min(1).optional(),
+  /** Expected token audience — part of what the CLI binds cached tokens to. */
+  audience: z8.string().min(1).optional(),
+  /**
+   * Whether this deployment permits `public` (anonymous) apps. Drives the SPA's
+   * visibility UI — it hides the public option when false. Absent = forbidden
+   * (older portal / dev-token-only where this endpoint 404s — open surfaces are
+   * opt-in). Server-side enforcement is independent of this hint (portal routes
+   * + edge serving).
+   */
+  allowPublicApps: z8.boolean().optional(),
+  /** Whether this deployment permits `password` (shared-passphrase) apps. Same shape as {@link allowPublicApps}. */
+  allowPasswordApps: z8.boolean().optional()
+});
+function portalApiScope(audience) {
+  if (!audience || audience.startsWith("urn:")) return null;
+  const appIdUri = audience.startsWith("api://") ? audience : `api://${audience}`;
+  return `${appIdUri.replace(/\/+$/, "")}/access`;
+}
+
+// ../shared/src/deployment.ts
+import { z as z9 } from "zod";
+var DeploymentConfigResponseSchema = z9.object({
+  /**
+   * Scheme + host + (non-default) port where apps are served, as reachable by
+   * this browser (architecture §4.1). The app slug is prepended as a subdomain:
+   * `https://<slug>.<host>`.
+   */
+  appPublicBase: z9.url(),
+  /**
+   * Base of the opt-in dev gateway (dev-mode design §3), absent when it is not
+   * deployed. Unlike {@link appPublicBase} the slug goes in the *path*, not the
+   * host. Absent ⇒ dev mode is unavailable here, so the UI says so instead of
+   * printing an unreachable host.
+   */
+  devApiBase: z9.url().optional(),
+  /**
+   * Month-to-date platform spend ceiling (USD) for the admin budget watch line.
+   * 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()
+});
+
+// ../shared/src/scrypt.ts
+var SCRYPT_PARAMS = {
+  /** CPU/memory cost. OWASP floor for scrypt. */
+  N: 2 ** 17,
+  /** Block size. */
+  r: 8,
+  /** Parallelization. */
+  p: 1,
+  /** 192 MiB — headroom above the ~128 MiB working set at these params. */
+  maxmem: 192 * 1024 * 1024
+};
+
+// ../shared/src/llm.ts
+import { z as z10 } from "zod";
+var LlmMessageSchema = z10.object({
+  role: z10.enum(["user", "assistant"]),
+  content: z10.string().min(1)
+});
+var LlmUsageSchema = z10.object({
+  inputTokens: z10.int().nonnegative(),
+  outputTokens: z10.int().nonnegative(),
+  cacheReadInputTokens: z10.int().nonnegative().default(0),
+  cacheCreationInputTokens: z10.int().nonnegative().default(0)
+});
+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),
+  /** SSE streaming (default) vs a single JSON body. */
+  stream: z10.boolean().default(true)
+});
+var LlmChatResponseSchema = z10.object({
+  model: z10.string(),
+  content: z10.string(),
+  stopReason: z10.string(),
+  usage: LlmUsageSchema
+});
+var LlmStreamDeltaSchema = z10.object({ text: z10.string() });
+var LlmStreamDoneSchema = z10.object({
+  stopReason: z10.string(),
+  usage: LlmUsageSchema
+});
+var LlmStreamErrorSchema = z10.object({
+  code: z10.string(),
+  message: z10.string()
+});
+
+// ../shared/src/usage.ts
+import { z as z11 } from "zod";
+var GATEWAY_OUTCOMES = ["ok", "error", "refusal", "quota_blocked"];
+var GatewayOutcomeSchema = z11.enum(GATEWAY_OUTCOMES);
+var USAGE_RANGES = ["24h", "7d", "30d"];
+var UsageRangeSchema = z11.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(),
+  /** The rolling range these figures cover. */
+  range: UsageRangeSchema,
+  requests: z11.int().nonnegative(),
+  inputTokens: z11.int().nonnegative(),
+  outputTokens: z11.int().nonnegative(),
+  /** Cache-aware input token totals (0 until prompt caching is enabled). */
+  cacheReadInputTokens: z11.int().nonnegative(),
+  cacheCreationInputTokens: z11.int().nonnegative(),
+  /** Estimated spend in USD over the window at current rates (./pricing.ts). */
+  costUsd: z11.number().nonnegative(),
+  /** 95th-percentile upstream latency (ms) over the window; null when no timed calls. */
+  latencyP95Ms: z11.number().nonnegative().nullable(),
+  /** Fraction of calls in the window whose outcome was not `ok` (0..1). */
+  errorRate: z11.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(),
+      /** Estimated spend in USD for this model over the window. */
+      costUsd: z11.number().nonnegative()
+    })
+  ),
+  /** Dense, zero-filled buckets across the range, oldest-first, for the trend chart. */
+  series: z11.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()
+  })
+});
+var GatewayCallSchema = z11.object({
+  id: z11.uuid(),
+  appId: z11.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(),
+  /** Estimated spend in USD for this single call at current rates. */
+  costUsd: z11.number().nonnegative(),
+  /** Upstream round-trip latency in ms (0 when not measured). */
+  durationMs: z11.int().nonnegative(),
+  /** Upstream/egress HTTP status — set for `fetch`; null for streamed `llm`. */
+  statusCode: z11.int().nullable(),
+  /** LLM stop reason; null for non-LLM calls. */
+  stopReason: z11.string().nullable(),
+  /** Short upstream error string; null on success. */
+  errorDetail: z11.string().nullable(),
+  outcome: GatewayOutcomeSchema,
+  createdAt: z11.iso.datetime()
+});
+var GatewayAuditPageSchema = z11.object({
+  rows: z11.array(GatewayCallSchema),
+  /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
+  nextBefore: z11.iso.datetime().optional()
+});
+var PlatformUsageSchema = z11.object({
+  /** The rolling range the series + breakdowns cover. */
+  range: PlatformRangeSchema,
+  /** Dense, zero-filled daily buckets across the range, oldest-first. */
+  series: z11.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(),
+      /** Estimated spend in USD for this app over the range. */
+      costUsd: z11.number().nonnegative()
+    })
+  ),
+  /** Month-to-date headline KPIs (independent of `range`). */
+  totals: z11.object({
+    tokensMTD: z11.int().nonnegative(),
+    requestsMTD: z11.int().nonnegative(),
+    /** Estimated month-to-date spend in USD across all apps. */
+    costMTD: z11.number().nonnegative(),
+    /** Distinct `userOid`s seen month-to-date. */
+    activeUsers: z11.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(),
+      /** Estimated spend in USD for this capability over the range. */
+      costUsd: z11.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
+import { z as z13 } from "zod";
+var ENVS = ["prod", "dev"];
+var EnvSchema = z13.enum(ENVS);
+
+// ../shared/src/secrets.ts
+var InjectionRecipeSchema = z14.discriminatedUnion("kind", [
+  /** `Authorization: Bearer <secret>` — the common case. */
+  z14.object({ kind: z14.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("{}")
+  }),
+  /** Query parameter `?<param>=<secret>`. */
+  z14.object({ kind: z14.literal("query"), param: z14.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),
+  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),
+  /** 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) });
+
+// ../shared/src/devTokens.ts
+import { z as z15 } from "zod";
+function isValidDevOrigin(input) {
+  if (input.includes("*")) return false;
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (url.pathname !== "/" || url.search !== "" || url.hash !== "") return false;
+  if (url.username !== "" || url.password !== "") return false;
+  return input === url.origin || input === `${url.origin}/`;
+}
+var DevOriginSchema = z15.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),
+  ttlDays: TtlDaysSchema
+});
+var DevTokenRotateRequestSchema = z15.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(),
+  metadata: DevTokenMetadataSchema
+});
+
+// ../shared/src/instruction.ts
+import { z as z16 } from "zod";
+var INSTRUCTION_CAPABILITIES = ["fetch", "llm"];
+var InstructionCapabilitySchema = z16.enum(INSTRUCTION_CAPABILITIES);
+var AttestedInstructionSchema = z16.object({
+  /** App the call is attributed to (registry app id). */
+  appId: z16.string().min(1),
+  /** Authenticated user, or the anonymous sentinel on `public` apps. */
+  userOid: z16.string().min(1),
+  capability: InstructionCapabilitySchema,
+  /** The allowlisted origin the edge authorized (scheme + host + port). */
+  origin: z16.url(),
+  /** Connection (secret) name to inject, if this is a secret-backed call. */
+  connection: z16.string().min(1).optional(),
+  /** Correlates the edge audit row with the egress call. */
+  requestId: z16.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
+   * redirected to a different request on the same origin (origin is already bound
+   * above; the `jti` burn already blocks replay — this closes the residual
+   * same-origin-different-request gap). Bound to `pathname` only (not query): the
+   * app controls the query, and origin + jti already constrain the call.
+   *
+   * Optional for rollout safety (like `env`): within one instance edge+egress
+   * deploy together and instructions live 30 s, but a rolling restart may briefly
+   * verify an old-edge token that lacks these. Only the edge can sign, so absence
+   * 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(),
+  /**
+   * 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
+   * `prod` connection secret and vice-versa. Carried by the attested (signed)
+   * claim, never an app/request parameter; defaults `prod` so any instruction
+   * minted before this field existed verifies as production.
+   */
+  env: EnvSchema.default("prod")
+});
+var INSTRUCTION_TTL_SECONDS = 30;
+var INSTRUCTION_BURN_RETENTION_SECONDS = INSTRUCTION_TTL_SECONDS + 15;
+
+// ../shared/src/fetch.ts
+import { z as z17 } from "zod";
+var FETCH_ERROR_CODES = [
+  "forbidden",
+  "rate_limited",
+  "bad_target",
+  "blocked",
+  "too_large",
+  "replay",
+  "upstream_error"
+];
+var FetchErrorCodeSchema = z17.enum(FETCH_ERROR_CODES);
+var FetchProxyErrorSchema = z17.object({
+  code: FetchErrorCodeSchema,
+  message: z17.string()
+});
+
+// src/client.ts
+var CliError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+  }
+};
+var VersionListSchema = z18.array(VersionSchema);
+var PortalClient = class {
+  #baseUrl;
+  #tokenProvider;
+  /** `token` may be a static string (dev token) or an async provider (OIDC). */
+  constructor(baseUrl, token) {
+    this.#baseUrl = baseUrl.replace(/\/+$/, "");
+    this.#tokenProvider = typeof token === "string" ? async () => token : token;
+  }
+  createApp(input) {
+    return this.#json(AppSchema, "POST", "/api/v1/apps", { auth: true, body: input });
+  }
+  /** Public IdP discovery info — how `helix login` finds the issuer. */
+  getAuthConfig() {
+    return this.#json(AuthConfigResponseSchema, "GET", "/api/v1/auth/config", {});
+  }
+  /** The authenticated actor, per the portal — powers `helix whoami`. */
+  me() {
+    return this.#json(PortalMeResponseSchema, "GET", "/api/v1/me", { auth: true });
+  }
+  listVersions(slug) {
+    return this.#json(VersionListSchema, "GET", `/api/v1/apps/${enc(slug)}/versions`, {
+      auth: true
+    });
+  }
+  promote(slug, number) {
+    return this.#json(AppSchema, "POST", `/api/v1/apps/${enc(slug)}/versions/${number}/promote`, {
+      auth: true
+    });
+  }
+  rollback(slug, toNumber) {
+    return this.#json(AppSchema, "POST", `/api/v1/apps/${enc(slug)}/rollback`, {
+      auth: true,
+      body: toNumber !== void 0 ? { toNumber } : {}
+    });
+  }
+  async uploadVersion(slug, zip, filename = "bundle.zip") {
+    const form = new FormData();
+    form.append("bundle", new Blob([new Uint8Array(zip)]), filename);
+    const res = await fetch(this.#url(`/api/v1/apps/${enc(slug)}/versions`), {
+      method: "POST",
+      headers: await this.#authHeaders(true),
+      body: form
+    });
+    return this.#parse(UploadVersionResponseSchema, res);
+  }
+  #url(path3) {
+    return `${this.#baseUrl}${path3}`;
+  }
+  async #authHeaders(auth) {
+    if (!auth) return {};
+    const token = await this.#tokenProvider?.();
+    if (!token) {
+      throw new CliError("not signed in; run `helix login` (or set HELIX_TOKEN / pass --token)");
+    }
+    return { authorization: `Bearer ${token}` };
+  }
+  async #json(schema, method, path3, opts) {
+    const headers = await this.#authHeaders(opts.auth ?? false);
+    if (opts.body !== void 0) headers["content-type"] = "application/json";
+    const res = await fetch(this.#url(path3), {
+      method,
+      headers,
+      body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    return this.#parse(schema, res);
+  }
+  async #parse(schema, res) {
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      const parsed = ApiErrorSchema.safeParse(data);
+      if (parsed.success) throw new CliError(parsed.data.error.message, parsed.data.error.code);
+      throw new CliError(`request failed (HTTP ${res.status})`);
+    }
+    return schema.parse(data);
+  }
+};
+function enc(segment) {
+  return encodeURIComponent(segment);
+}
+
+// src/commands.ts
+import { readFile as readFile2 } from "node:fs/promises";
+
+// src/zip.ts
+import { ZipArchive } from "archiver";
+function zipDirectory(dir) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const archive = new ZipArchive({ zlib: { level: 9 } });
+    archive.on("data", (c) => chunks.push(c));
+    archive.on("error", reject);
+    archive.on("end", () => resolve(Buffer.concat(chunks)));
+    archive.directory(dir, false);
+    void archive.finalize();
+  });
+}
+
+// src/auth/deviceFlow.ts
+import * as oidc from "openid-client";
+var DEVICE_SCOPES = "openid profile email offline_access";
+function deviceScopes(audience) {
+  const apiScope = portalApiScope(audience);
+  return apiScope ? `${DEVICE_SCOPES} ${apiScope}` : DEVICE_SCOPES;
+}
+async function discover(issuer, clientId) {
+  const url = new URL(issuer);
+  return oidc.discovery(
+    url,
+    clientId,
+    void 0,
+    void 0,
+    // The local dev IdP is plain http on localhost; real issuers are https.
+    url.protocol === "http:" ? { execute: [oidc.allowInsecureRequests] } : void 0
+  );
+}
+function toStoredTokens(tokens, clientId) {
+  if (!tokens.access_token) throw new Error("token response carried no access token");
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt: Date.now() + (tokens.expires_in ?? 300) * 1e3,
+    clientId
+  };
+}
+async function runDeviceLogin(opts) {
+  const config = await discover(opts.issuer, opts.clientId);
+  const handle = await oidc.initiateDeviceAuthorization(config, {
+    scope: deviceScopes(opts.audience)
+  });
+  opts.log("To sign in, open this URL in a browser:");
+  opts.log(`  ${handle.verification_uri_complete ?? handle.verification_uri}`);
+  opts.log(`and confirm the code: ${handle.user_code}`);
+  opts.log("Waiting for approval\u2026");
+  const tokens = await oidc.pollDeviceAuthorizationGrant(config, handle);
+  return toStoredTokens(tokens, opts.clientId);
+}
+async function refreshGrant(issuer, clientId, refreshToken) {
+  const config = await discover(issuer, clientId);
+  const tokens = await oidc.refreshTokenGrant(config, refreshToken);
+  const stored = toStoredTokens(tokens, clientId);
+  return { ...stored, refreshToken: stored.refreshToken ?? refreshToken };
+}
+
+// src/auth/tokenStore.ts
+import { mkdir, readFile, rename, writeFile, chmod, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+function portalOrigin(portalUrl) {
+  return new URL(portalUrl).origin;
+}
+function defaultTokenPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "helix", "tokens.json");
+}
+async function readFileTolerant(file) {
+  const empty = { version: 2, byPortal: {} };
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    if (parsed.version !== 2 || typeof parsed.byPortal !== "object" || !parsed.byPortal) {
+      return empty;
+    }
+    return parsed;
+  } catch {
+    return empty;
+  }
+}
+async function readTokens(key, file = defaultTokenPath()) {
+  const data = await readFileTolerant(file);
+  const entry = data.byPortal[portalOrigin(key.portalUrl)];
+  if (!entry || entry.issuer !== key.issuer) return void 0;
+  const tokens = entry.tokens;
+  if (!tokens || typeof tokens.accessToken !== "string" || typeof tokens.expiresAt !== "number") {
+    return void 0;
+  }
+  return tokens;
+}
+async function writeFile0600(file, content) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 448 });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, content, { mode: 384 });
+  await rename(tmp, file);
+  await chmod(file, 384);
+}
+async function writeTokens(key, tokens, file = defaultTokenPath(), opts = {}) {
+  const data = await readFileTolerant(file);
+  data.byPortal[portalOrigin(key.portalUrl)] = {
+    issuer: key.issuer,
+    ...opts.audience ? { audience: opts.audience } : {},
+    tokens
+  };
+  await writeFile0600(file, JSON.stringify(data, null, 2));
+}
+async function deleteTokens(portalUrl, file = defaultTokenPath()) {
+  const data = await readFileTolerant(file);
+  const origin = portalOrigin(portalUrl);
+  if (!(origin in data.byPortal)) return false;
+  delete data.byPortal[origin];
+  if (Object.keys(data.byPortal).length === 0) {
+    await rm(file, { force: true });
+  } else {
+    await writeFile0600(file, JSON.stringify(data, null, 2));
+  }
+  return true;
+}
+
+// src/commands.ts
+function requireSlug(config) {
+  if (!config.slug) {
+    throw new CliError("no app slug; set it in helix.json or pass --slug");
+  }
+  return config.slug;
+}
+function parseVisibility(input) {
+  if (!input) return void 0;
+  if (input.startsWith("group:")) {
+    const groupId = input.slice("group:".length);
+    if (!groupId) throw new CliError("group visibility needs an id: group:<id>");
+    return { mode: "group", groupId };
+  }
+  if (input === "private" || input === "password" || input === "public") {
+    return { mode: input };
+  }
+  throw new CliError(`invalid visibility "${input}" (private | group:<id> | password | public)`);
+}
+function printVersion(v) {
+  console.log(`  version ${v.number} (${v.status}) \u2014 ${v.id}`);
+  console.log(`  assets: ${v.blobPrefix}`);
+}
+function printApp(app) {
+  console.log(`  app ${app.slug} \u2014 live version: ${app.currentVersionId ?? "(none)"}`);
+}
+async function createCommand(client, config, opts) {
+  const slug = requireSlug(config);
+  const app = await client.createApp({
+    slug,
+    displayName: opts.displayName ?? slug,
+    visibility: parseVisibility(opts.visibility)
+  });
+  console.log(`Created app "${app.slug}".`);
+  printApp(app);
+}
+async function deployCommand(client, config, opts) {
+  const slug = requireSlug(config);
+  const zip = config.bundle ? await readFile2(config.bundle) : await zipDirectory(config.dir);
+  console.log(`Uploading bundle to "${slug}"\u2026`);
+  const { version, warnings } = await client.uploadVersion(slug, zip);
+  console.log(`Uploaded as preview:`);
+  printVersion(version);
+  if (warnings.length > 0) {
+    console.log(`
+${warnings.length} CSP warning(s):`);
+    for (const w of warnings) console.log(`  - ${w.file}: ${w.hint}`);
+  }
+  if (opts.promote) {
+    const app = await client.promote(slug, version.number);
+    console.log(`
+Promoted version ${version.number} to live.`);
+    printApp(app);
+  } else {
+    console.log(`
+Not live yet \u2014 promote with: helix promote ${version.number}`);
+  }
+}
+async function versionsCommand(client, config) {
+  const slug = requireSlug(config);
+  const versions = await client.listVersions(slug);
+  if (versions.length === 0) {
+    console.log(`No versions for "${slug}".`);
+    return;
+  }
+  console.log(`Versions for "${slug}" (newest first):`);
+  for (const v of versions) console.log(`  ${v.number}	${v.status}	${v.id}`);
+}
+async function promoteCommand(client, config, number) {
+  const slug = requireSlug(config);
+  const app = await client.promote(slug, number);
+  console.log(`Promoted version ${number} to live.`);
+  printApp(app);
+}
+async function rollbackCommand(client, config, toNumber) {
+  const slug = requireSlug(config);
+  const app = await client.rollback(slug, toNumber);
+  console.log(
+    toNumber ? `Rolled back to version ${toNumber}.` : `Rolled back to previous version.`
+  );
+  printApp(app);
+}
+async function loginCommand(client, config) {
+  const { issuer, cliClientId, audience } = await client.getAuthConfig();
+  const tokens = await runDeviceLogin({
+    issuer,
+    clientId: cliClientId,
+    audience,
+    log: console.log
+  });
+  await writeTokens({ portalUrl: config.portalUrl, issuer }, tokens, void 0, { audience });
+  const authed = new PortalClient(config.portalUrl, tokens.accessToken);
+  const me = await authed.me();
+  console.log(`Logged in as ${me.name ?? me.sub} (${me.sub}).`);
+}
+async function logoutCommand(config) {
+  const forgot = await deleteTokens(config.portalUrl);
+  console.log(forgot ? "Logged out (local tokens forgotten)." : "Already logged out.");
+}
+async function whoamiCommand(client) {
+  const me = await client.me();
+  console.log(`${me.sub} (via ${me.via}${me.name ? `, ${me.name}` : ""})`);
+}
+
+// src/auth/session.ts
+var REFRESH_MARGIN_MS = 6e4;
+async function fetchAuthConfig(portalUrl) {
+  const res = await fetch(`${portalUrl.replace(/\/+$/, "")}/api/v1/auth/config`);
+  if (!res.ok) {
+    throw new Error(
+      `portal has no OIDC configured (GET /api/v1/auth/config \u2192 ${res.status}); use HELIX_TOKEN / --token instead`
+    );
+  }
+  return AuthConfigResponseSchema.parse(await res.json());
+}
+var defaultDeps = {
+  getAuthConfig: fetchAuthConfig,
+  refresh: refreshGrant,
+  storePath: defaultTokenPath()
+};
+function makeTokenProvider(opts, deps = defaultDeps) {
+  return async function getAccessToken() {
+    if (opts.staticToken) return opts.staticToken;
+    const { issuer, cliClientId } = await deps.getAuthConfig(opts.portalUrl);
+    const key = { portalUrl: opts.portalUrl, issuer };
+    const stored = await readTokens(key, deps.storePath);
+    if (!stored) return void 0;
+    if (stored.expiresAt - REFRESH_MARGIN_MS > Date.now()) {
+      return stored.accessToken;
+    }
+    if (!stored.refreshToken) return void 0;
+    try {
+      const renewed = await deps.refresh(
+        issuer,
+        stored.clientId || cliClientId,
+        stored.refreshToken
+      );
+      await writeTokens(key, renewed, deps.storePath);
+      return renewed.accessToken;
+    } catch {
+      return void 0;
+    }
+  };
+}
+
+// src/config.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import path2 from "node:path";
+var DEFAULT_PORTAL_URL = "http://localhost:3001";
+var DEFAULT_DIR = "dist";
+var CONFIG_FILENAMES = ["helix.json", "azx.json"];
+async function readConfigFile(cwd) {
+  for (const name of CONFIG_FILENAMES) {
+    try {
+      return JSON.parse(await readFile3(path2.join(cwd, name), "utf8"));
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+  }
+  return {};
+}
+async function resolveConfig(flags, env = process.env, cwd = process.cwd()) {
+  const file = await readConfigFile(cwd);
+  return {
+    portalUrl: flags.portalUrl ?? env.HELIX_PORTAL_URL ?? env.AZX_PORTAL_URL ?? file.portalUrl ?? DEFAULT_PORTAL_URL,
+    token: flags.token ?? env.HELIX_TOKEN ?? env.AZX_TOKEN,
+    slug: flags.slug ?? file.slug,
+    dir: flags.dir ?? file.dir ?? DEFAULT_DIR,
+    bundle: flags.bundle
+  };
+}
+
+// src/bin.ts
+var USAGE = `helix \u2014 Helix deploy CLI
+
+Usage:
+  helix login                # sign in via the browser (OIDC device flow)
+  helix logout
+  helix whoami
+  helix deploy   [--dir <dir>] [--bundle <zip>] [--promote]
+  helix create   [--display-name <name>] [--visibility <v>]
+  helix versions
+  helix promote  <number>
+  helix rollback [number]
+
+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
+`;
+async function main() {
+  const { values, positionals } = parseCliArgs(process.argv.slice(2));
+  const command = positionals[0];
+  if (!command || values.help) {
+    console.log(USAGE);
+    return;
+  }
+  const config = await resolveConfig({
+    slug: values.slug,
+    portalUrl: values["portal-url"],
+    dir: values.dir,
+    bundle: values.bundle,
+    token: values.token
+  });
+  const client = new PortalClient(
+    config.portalUrl,
+    makeTokenProvider({ portalUrl: config.portalUrl, staticToken: config.token })
+  );
+  switch (command) {
+    case "login":
+      await loginCommand(client, config);
+      break;
+    case "logout":
+      await logoutCommand(config);
+      break;
+    case "whoami":
+      await whoamiCommand(client);
+      break;
+    case "deploy":
+      await deployCommand(client, config, { promote: values.promote });
+      break;
+    case "create":
+      await createCommand(client, config, {
+        displayName: values["display-name"],
+        visibility: values.visibility
+      });
+      break;
+    case "versions":
+      await versionsCommand(client, config);
+      break;
+    case "promote": {
+      const number = Number(positionals[1]);
+      if (!Number.isInteger(number)) throw new CliError("usage: helix promote <number>");
+      await promoteCommand(client, config, number);
+      break;
+    }
+    case "rollback": {
+      const number = positionals[1] !== void 0 ? Number(positionals[1]) : void 0;
+      if (number !== void 0 && !Number.isInteger(number)) {
+        throw new CliError("usage: helix rollback [number]");
+      }
+      await rollbackCommand(client, config, number);
+      break;
+    }
+    default:
+      throw new CliError(`unknown command "${command}"
+
+${USAGE}`);
+  }
+}
+main().catch((err) => {
+  if (err instanceof CliError) {
+    console.error(`error: ${err.message}${err.code ? ` (${err.code})` : ""}`);
+  } else {
+    console.error(err);
+  }
+  process.exitCode = 1;
+});