@azx-pbc/helix-cli 0.4.0 → 0.5.0

package/dist/helix.js

@@ -13,6 +13,10 @@ var options = {
   description: { type: "string" },
   visibility: { type: "string" },
   path: { type: "string" },
+  repo: { type: "string" },
+  branch: { type: "string" },
+  reusable: { type: "boolean" },
+  force: { type: "boolean" },
   help: { type: "boolean" }
 };
 function parseCliArgs(argv) {
@@ -21,7 +25,7 @@ function parseCliArgs(argv) {
 }
 
 // src/client.ts
-import { z as z27 } from "zod";
+import { z as z29 } from "zod";
 
 // ../shared/src/visibility.ts
 import { z } from "zod";
@@ -176,6 +180,16 @@ var DeployReportSchema = z4.object({
   /** Candidate roots the planner considered. */
   candidates: z4.array(z4.string().max(1024)).max(20).default([])
 });
+var VersionSourceSchema = z4.object({
+  provider: z4.literal("github"),
+  repoFullName: z4.string(),
+  repositoryId: z4.string(),
+  ref: z4.string(),
+  commitSha: z4.string(),
+  workflowRef: z4.string(),
+  runId: z4.string(),
+  runAttempt: z4.int().positive()
+});
 var VersionSchema = z4.object({
   id: z4.uuid(),
   appId: z4.uuid(),
@@ -186,7 +200,9 @@ var VersionSchema = z4.object({
   status: VersionStatusSchema,
   createdAt: z4.iso.datetime(),
   /** Client-asserted salvage provenance (ADR-0038); absent on CLI uploads. */
-  deployReport: DeployReportSchema.optional()
+  deployReport: DeployReportSchema.optional(),
+  /** Verified CI provenance (ADR-0051); absent on non-CI uploads. */
+  source: VersionSourceSchema.optional()
 });
 
 // ../shared/src/manifest.ts
@@ -1256,7 +1272,20 @@ var DeploymentConfigResponseSchema = z13.object({
    * chasing a rejection it can't see the cause of.
    */
   deployMaxFileMb: z13.number().positive().optional(),
-  deployMaxBundleMb: z13.number().positive().optional()
+  deployMaxBundleMb: z13.number().positive().optional(),
+  /**
+   * Repo-backed deploys (ADR-0051). `audience` is the exact `aud` the CI route
+   * accepts, so `helix deploy` in GitHub Actions requests its token for this
+   * value rather than for whatever URL it was pointed at. `serverUrl` is the
+   * GitHub web origin for commit and run links. Optional only to tolerate a
+   * portal that predates the feature; when `enabled` is false the CI route and
+   * the binding routes answer 404 and clients hide the surface.
+   */
+  repoDeploy: z13.object({
+    enabled: z13.boolean(),
+    audience: z13.url(),
+    serverUrl: z13.url()
+  }).optional()
 });
 
 // ../shared/src/catalogue.ts
@@ -1718,7 +1747,12 @@ var GatewayCallSchema = z18.object({
   method: z18.string().nullable(),
   /** LLM stop reason; null for non-LLM calls. */
   stopReason: z18.string().nullable(),
-  /** Short upstream error string; null on success. */
+  /**
+   * Short upstream error string; null on success. Admin-only in practice — it
+   * can quote request content and, on an auth failure, the key, so it serves
+   * the admin audit log's audience while the app-scoped feed
+   * (`/api/v1/apps/:slug/audit`) nulls it for non-admin callers.
+   */
   errorDetail: z18.string().nullable(),
   outcome: GatewayOutcomeSchema,
   createdAt: z18.iso.datetime()
@@ -1763,11 +1797,59 @@ var PlatformUsageSchema = z18.object({
   )
 });
 
-// ../shared/src/data.ts
+// ../shared/src/visitors.ts
 import { z as z19 } from "zod";
-var CollectionItemSchema = z19.object({
-  id: z19.uuid(),
-  collection: z19.string(),
+var VISITOR_RANGES = ["7d", "30d", "90d"];
+var VisitorRangeSchema = z19.enum(VISITOR_RANGES);
+var count = z19.int().nonnegative();
+var VisitorTotalsSchema = z19.object({
+  visits: count,
+  uniqueVisitors: count
+});
+var GeoStatusSchema = z19.object({
+  available: z19.boolean(),
+  reason: z19.string().nullable(),
+  attribution: z19.object({ text: z19.string(), url: z19.url() }).nullable()
+});
+var VisitorLocationSchema = z19.object({
+  /** ISO 3166-1 alpha-2. */
+  country: z19.string(),
+  countryName: z19.string().nullable(),
+  /** First-level subdivision (state, province); null when the database has none. */
+  region: z19.string().nullable(),
+  visitors: count,
+  visits: count
+});
+var VisitorSeriesPointSchema = z19.object({
+  /** Bucket-start ISO timestamp (one calendar day). */
+  bucket: z19.iso.datetime(),
+  visits: count,
+  /** Distinct visitors that day — a visitor active on two days counts on each. */
+  uniqueVisitors: count
+});
+var VisitorSummarySchema = z19.object({
+  appId: z19.uuid(),
+  range: VisitorRangeSchema,
+  /** The selected window. */
+  current: VisitorTotalsSchema,
+  /** The window of the same length immediately before it, for the deltas. */
+  prior: VisitorTotalsSchema,
+  /** Dense, zero-filled daily buckets, oldest first. */
+  series: z19.array(VisitorSeriesPointSchema),
+  /** The top {@link VISITOR_LOCATION_LIMIT} locations by visitors. */
+  locations: z19.array(VisitorLocationSchema),
+  /** Every resolved location past the top ones. */
+  otherLocations: VisitorTotalsSchema,
+  /** Private, proxied or unknown networks, and every row when geo is unavailable. */
+  unresolved: VisitorTotalsSchema,
+  geo: GeoStatusSchema
+});
+
+// ../shared/src/data.ts
+import { z as z20 } from "zod";
+var CollectionItemSchema = z20.object({
+  id: z20.uuid(),
+  collection: z20.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
@@ -1776,141 +1858,141 @@ var CollectionItemSchema = z19.object({
    */
   env: EnvSchema,
   /** The submitting user, if authenticated; null for anonymous/public visitors. */
-  userOid: z19.string().nullable(),
+  userOid: z20.string().nullable(),
   /**
    * The submitter's captured claims — display half, rendered but never compared
    * (see `GatewayCallSchema.userName`). Null whenever `userOid` is, and for
    * password/dev-token principals.
    */
-  userName: z19.string().nullable(),
-  userEmail: z19.string().nullable(),
+  userName: z20.string().nullable(),
+  userEmail: z20.string().nullable(),
   /** The submitter's kind; null whenever `userOid` is, and on pre-column rows. */
   userKind: PrincipalKindSchema.nullable(),
-  item: z19.unknown(),
+  item: z20.unknown(),
   /** Hashed IP / truncated UA for abuse triage; null if not captured. */
-  meta: z19.unknown().nullable(),
-  createdAt: z19.iso.datetime()
+  meta: z20.unknown().nullable(),
+  createdAt: z20.iso.datetime()
 });
-var CollectionItemsPageSchema = z19.object({
-  rows: z19.array(CollectionItemSchema),
+var CollectionItemsPageSchema = z20.object({
+  rows: z20.array(CollectionItemSchema),
   /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
-  nextBefore: z19.iso.datetime().optional()
+  nextBefore: z20.iso.datetime().optional()
 });
-var CollectionSummarySchema = z19.object({
-  name: z19.string(),
+var CollectionSummarySchema = z20.object({
+  name: z20.string(),
   env: EnvSchema,
-  count: z19.int().nonnegative(),
+  count: z20.int().nonnegative(),
   /** Newest row's timestamp; null only if the group is somehow empty. */
-  lastAt: z19.iso.datetime().nullable()
+  lastAt: z20.iso.datetime().nullable()
 });
 
 // ../shared/src/collectionTable.ts
 var BOM = String.fromCharCode(65279);
 
 // ../shared/src/connections.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 var CONNECTION_STATUSES = ["live", "reconnect-needed", "invalidated"];
-var ConnectionStatusSchema = z20.enum(CONNECTION_STATUSES);
-var ConnectionMaterialSchema = z20.strictObject({
-  access: z20.string().min(1),
-  refresh: z20.string().min(1)
+var ConnectionStatusSchema = z21.enum(CONNECTION_STATUSES);
+var ConnectionMaterialSchema = z21.strictObject({
+  access: z21.string().min(1),
+  refresh: z21.string().min(1)
 });
 var MAX_GRANTED_SCOPES = 64;
-var GrantedScopesSchema = z20.array(ScopeTokenSchema).max(MAX_GRANTED_SCOPES);
-var UserConnectionSchema = z20.strictObject({
-  id: z20.uuid(),
-  userOid: z20.string().min(1),
-  providerId: z20.uuid(),
-  providerRevision: z20.int().positive(),
+var GrantedScopesSchema = z21.array(ScopeTokenSchema).max(MAX_GRANTED_SCOPES);
+var UserConnectionSchema = z21.strictObject({
+  id: z21.uuid(),
+  userOid: z21.string().min(1),
+  providerId: z21.uuid(),
+  providerRevision: z21.int().positive(),
   env: EnvSchema,
   status: ConnectionStatusSchema,
-  material: z20.string().min(1),
+  material: z21.string().min(1),
   grantedScopes: GrantedScopesSchema,
-  grantedAt: z20.iso.datetime(),
-  expiresAt: z20.iso.datetime(),
-  renewBeforeNext: z20.boolean(),
-  pendingRetire: z20.string().min(1).nullable(),
-  lastRenewedAt: z20.iso.datetime().nullable(),
-  createdAt: z20.iso.datetime(),
-  updatedAt: z20.iso.datetime()
-});
-var MyConnectionSchema = z20.strictObject({
-  id: z20.uuid(),
+  grantedAt: z21.iso.datetime(),
+  expiresAt: z21.iso.datetime(),
+  renewBeforeNext: z21.boolean(),
+  pendingRetire: z21.string().min(1).nullable(),
+  lastRenewedAt: z21.iso.datetime().nullable(),
+  createdAt: z21.iso.datetime(),
+  updatedAt: z21.iso.datetime()
+});
+var MyConnectionSchema = z21.strictObject({
+  id: z21.uuid(),
   providerRef: ProviderRefSchema,
-  providerDisplayName: z20.string().min(1).max(200),
+  providerDisplayName: z21.string().min(1).max(200),
   env: EnvSchema,
   status: ConnectionStatusSchema.exclude(["invalidated"]),
   grantedScopes: GrantedScopesSchema,
-  grantedAt: z20.iso.datetime(),
-  sharedApps: z20.array(BoundAppSchema)
+  grantedAt: z21.iso.datetime(),
+  sharedApps: z21.array(BoundAppSchema)
 });
-var MyConnectionsResponseSchema = z20.strictObject({
-  connections: z20.array(MyConnectionSchema)
+var MyConnectionsResponseSchema = z21.strictObject({
+  connections: z21.array(MyConnectionSchema)
 });
-var DisconnectResponseSchema = z20.strictObject({
-  outcome: z20.enum(["disconnected", "already_removed"])
+var DisconnectResponseSchema = z21.strictObject({
+  outcome: z21.enum(["disconnected", "already_removed"])
 });
 
 // ../shared/src/consent.ts
-import { z as z21 } from "zod";
-var ConsentStateSchema = z21.string().min(43).max(128);
-var ConsentNonceSchema = z21.string().min(16).max(128);
-var ConsentAttemptTagSchema = z21.string().min(1).max(128).regex(/^[A-Za-z0-9._~-]+$/, "must be URL-safe punctuation, letters, or digits");
-var ConsentIdentitySchema = z21.discriminatedUnion("kind", [
-  z21.strictObject({ kind: z21.literal("user"), userOid: z21.string().min(1).max(128) }),
-  z21.strictObject({
-    kind: z21.literal("dev"),
-    developerOid: z21.string().min(1).max(128),
+import { z as z22 } from "zod";
+var ConsentStateSchema = z22.string().min(43).max(128);
+var ConsentNonceSchema = z22.string().min(16).max(128);
+var ConsentAttemptTagSchema = z22.string().min(1).max(128).regex(/^[A-Za-z0-9._~-]+$/, "must be URL-safe punctuation, letters, or digits");
+var ConsentIdentitySchema = z22.discriminatedUnion("kind", [
+  z22.strictObject({ kind: z22.literal("user"), userOid: z22.string().min(1).max(128) }),
+  z22.strictObject({
+    kind: z22.literal("dev"),
+    developerOid: z22.string().min(1).max(128),
     nonce: ConsentNonceSchema
   })
 ]);
 var HttpUrlNoUserinfoSchema = (() => {
   const userinfo = /^https?:\/\/[/\\]*[^/?#\\]*@/i;
-  return z21.url({ protocol: /^https?$/ }).refine(
+  return z22.url({ protocol: /^https?$/ }).refine(
     (value) => !userinfo.test(value.replace(/[\t\n\r]/g, "")),
     "URL must not carry userinfo"
   );
 })();
-var ConsultRequestSchema = z21.strictObject({
+var ConsultRequestSchema = z22.strictObject({
   identity: ConsentIdentitySchema,
-  appSlug: z21.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  appSlug: z22.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
   providerRef: ProviderRefSchema,
   openerOrigin: HttpUrlNoUserinfoSchema.transform((value) => new URL(value).origin),
   callbackUrl: HttpUrlNoUserinfoSchema
 });
-var ConsultResponseSchema = z21.discriminatedUnion("outcome", [
-  z21.strictObject({ outcome: z21.literal("already_connected") }),
-  z21.strictObject({ outcome: z21.literal("not_available") }),
-  z21.strictObject({ outcome: z21.literal("started"), authorizeUrl: z21.url() })
+var ConsultResponseSchema = z22.discriminatedUnion("outcome", [
+  z22.strictObject({ outcome: z22.literal("already_connected") }),
+  z22.strictObject({ outcome: z22.literal("not_available") }),
+  z22.strictObject({ outcome: z22.literal("started"), authorizeUrl: z22.url() })
 ]);
-var CancelRequestSchema = z21.strictObject({
+var CancelRequestSchema = z22.strictObject({
   identity: ConsentIdentitySchema,
   state: ConsentStateSchema
 });
 var CONSENT_CANCEL_OUTCOMES = ["cancelled", "not_cancellable"];
-var CancelResponseSchema = z21.strictObject({
-  outcome: z21.enum(CONSENT_CANCEL_OUTCOMES)
+var CancelResponseSchema = z22.strictObject({
+  outcome: z22.enum(CONSENT_CANCEL_OUTCOMES)
 });
-var ConnectionStatusIdentitySchema = z21.discriminatedUnion("kind", [
-  z21.strictObject({ kind: z21.literal("user"), userOid: z21.string().min(1).max(128) }),
-  z21.strictObject({ kind: z21.literal("dev"), developerOid: z21.string().min(1).max(128) })
+var ConnectionStatusIdentitySchema = z22.discriminatedUnion("kind", [
+  z22.strictObject({ kind: z22.literal("user"), userOid: z22.string().min(1).max(128) }),
+  z22.strictObject({ kind: z22.literal("dev"), developerOid: z22.string().min(1).max(128) })
 ]);
-var ConnectionStatusRequestSchema = z21.strictObject({
+var ConnectionStatusRequestSchema = z22.strictObject({
   identity: ConnectionStatusIdentitySchema,
-  appSlug: z21.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  appSlug: z22.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
   providerRef: ProviderRefSchema
 });
-var ConnectionStatusResponseSchema = z21.strictObject({
-  status: z21.enum(["connected", "not_connected", "not_available"])
+var ConnectionStatusResponseSchema = z22.strictObject({
+  status: z22.enum(["connected", "not_connected", "not_available"])
 });
-var AttemptCancelRequestSchema = z21.strictObject({
+var AttemptCancelRequestSchema = z22.strictObject({
   provider: ProviderRefSchema,
   attempt: ConsentAttemptTagSchema
 });
-var DevConsentStartResponseSchema = z21.discriminatedUnion("outcome", [
-  z21.strictObject({ outcome: z21.literal("started"), popupUrl: z21.url() }),
-  z21.strictObject({ outcome: z21.literal("already_connected") }),
-  z21.strictObject({ outcome: z21.literal("not_available") })
+var DevConsentStartResponseSchema = z22.discriminatedUnion("outcome", [
+  z22.strictObject({ outcome: z22.literal("started"), popupUrl: z22.url() }),
+  z22.strictObject({ outcome: z22.literal("already_connected") }),
+  z22.strictObject({ outcome: z22.literal("not_available") })
 ]);
 var HELIX_CONNECT_MESSAGE_SOURCE = "helix-connect";
 var CONNECT_MESSAGE_VERSION = 1;
@@ -1931,32 +2013,32 @@ var CONSENT_MESSAGE_REASONS = [
   "provider_incompatible",
   "service_unavailable"
 ];
-var ConnectOutcomeMessageSchema = z21.strictObject({
-  source: z21.literal(HELIX_CONNECT_MESSAGE_SOURCE),
-  version: z21.literal(CONNECT_MESSAGE_VERSION),
+var ConnectOutcomeMessageSchema = z22.strictObject({
+  source: z22.literal(HELIX_CONNECT_MESSAGE_SOURCE),
+  version: z22.literal(CONNECT_MESSAGE_VERSION),
   attempt: ConsentAttemptTagSchema.optional(),
   provider: ProviderRefSchema,
-  outcome: z21.enum(CONSENT_MESSAGE_OUTCOMES),
-  reason: z21.enum(CONSENT_MESSAGE_REASONS).nullable()
+  outcome: z22.enum(CONSENT_MESSAGE_OUTCOMES),
+  reason: z22.enum(CONSENT_MESSAGE_REASONS).nullable()
 }).refine((message) => message.outcome === "error" || message.reason === null, {
   error: "reason is only carried with the error outcome"
 });
-var ConnectResultSchema = z21.object({
-  outcome: z21.enum(CONSENT_MESSAGE_OUTCOMES),
-  provider: z21.string(),
+var ConnectResultSchema = z22.object({
+  outcome: z22.enum(CONSENT_MESSAGE_OUTCOMES),
+  provider: z22.string(),
   attempt: ConsentAttemptTagSchema.optional(),
-  reason: z21.enum(CONSENT_MESSAGE_REASONS).optional()
+  reason: z22.enum(CONSENT_MESSAGE_REASONS).optional()
 }).refine((result) => result.outcome === "error" || result.reason === void 0, {
   error: "reason is only carried with the error outcome"
 });
 
 // ../shared/src/exchange.ts
-import { z as z22 } from "zod";
-var ExchangeCodeSchema = z22.string().min(1).max(1024);
-var CodeVerifierSchema = z22.string().min(43).max(128).regex(/^[A-Za-z0-9\-._~]+$/, "must be an RFC 7636 code_verifier (43-128 unreserved characters)");
-var ExchangeRequestSchema = z22.strictObject({
-  providerId: z22.uuid(),
-  providerRevision: z22.int().positive(),
+import { z as z23 } from "zod";
+var ExchangeCodeSchema = z23.string().min(1).max(1024);
+var CodeVerifierSchema = z23.string().min(43).max(128).regex(/^[A-Za-z0-9\-._~]+$/, "must be an RFC 7636 code_verifier (43-128 unreserved characters)");
+var ExchangeRequestSchema = z23.strictObject({
+  providerId: z23.uuid(),
+  providerRevision: z23.int().positive(),
   env: EnvSchema,
   code: ExchangeCodeSchema,
   codeVerifier: CodeVerifierSchema,
@@ -1967,24 +2049,24 @@ var EXCHANGE_REJECTION_REASONS = [
   "missing_refresh_token",
   "missing_permissions"
 ];
-var ExchangeRejectionReasonSchema = z22.enum(EXCHANGE_REJECTION_REASONS);
+var ExchangeRejectionReasonSchema = z23.enum(EXCHANGE_REJECTION_REASONS);
 var MAX_EXCHANGED_SCOPES = 64;
-var ExchangedScopesSchema = z22.array(ScopeTokenSchema).max(MAX_EXCHANGED_SCOPES);
-var ExchangeResponseSchema = z22.discriminatedUnion("outcome", [
-  z22.strictObject({
-    outcome: z22.literal("exchanged"),
-    access: z22.string().min(1),
-    refresh: z22.string().min(1),
+var ExchangedScopesSchema = z23.array(ScopeTokenSchema).max(MAX_EXCHANGED_SCOPES);
+var ExchangeResponseSchema = z23.discriminatedUnion("outcome", [
+  z23.strictObject({
+    outcome: z23.literal("exchanged"),
+    access: z23.string().min(1),
+    refresh: z23.string().min(1),
     grantedScopes: ExchangedScopesSchema,
-    accessExpiresAt: z22.iso.datetime()
+    accessExpiresAt: z23.iso.datetime()
   }),
-  z22.strictObject({ outcome: z22.literal("rejected"), reason: ExchangeRejectionReasonSchema }),
-  z22.strictObject({ outcome: z22.literal("provider_unavailable") }),
-  z22.strictObject({ outcome: z22.literal("exchange_failed") })
+  z23.strictObject({ outcome: z23.literal("rejected"), reason: ExchangeRejectionReasonSchema }),
+  z23.strictObject({ outcome: z23.literal("provider_unavailable") }),
+  z23.strictObject({ outcome: z23.literal("exchange_failed") })
 ]);
 
 // ../shared/src/devTokens.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 function isValidDevOrigin(input) {
   if (input.includes("*")) return false;
   let url;
@@ -1998,40 +2080,83 @@ function isValidDevOrigin(input) {
   if (url.username !== "" || url.password !== "") return false;
   return input === url.origin || input === `${url.origin}/`;
 }
-var DevOriginSchema = z23.string().refine(
+var DevOriginSchema = z24.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 = z23.number().int().min(1).max(365).optional();
-var DevTokenMintRequestSchema = z23.object({
-  origins: z23.array(DevOriginSchema).min(1).max(20),
+var TtlDaysSchema = z24.number().int().min(1).max(365).optional();
+var DevTokenMintRequestSchema = z24.object({
+  origins: z24.array(DevOriginSchema).min(1).max(20),
   ttlDays: TtlDaysSchema
 });
-var DevTokenRotateRequestSchema = z23.object({
+var DevTokenRotateRequestSchema = z24.object({
   ttlDays: TtlDaysSchema
 });
-var DevTokenMetadataSchema = z23.object({
-  id: z23.string(),
-  developerOid: z23.string(),
-  origins: z23.array(z23.string()),
-  expiresAt: z23.string(),
-  revokedAt: z23.string().nullable().optional(),
-  createdAt: z23.string()
+var DevTokenMetadataSchema = z24.object({
+  id: z24.string(),
+  developerOid: z24.string(),
+  origins: z24.array(z24.string()),
+  expiresAt: z24.string(),
+  revokedAt: z24.string().nullable().optional(),
+  createdAt: z24.string()
 });
-var DevTokenMintResponseSchema = z23.object({
-  token: z23.string(),
+var DevTokenMintResponseSchema = z24.object({
+  token: z24.string(),
   metadata: DevTokenMetadataSchema
 });
 
+// ../shared/src/repoBinding.ts
+import { z as z25 } from "zod";
+function hasControlChar(v) {
+  for (let i = 0; i < v.length; i++) {
+    const c = v.charCodeAt(i);
+    if (c < 32 || c === 127) return true;
+  }
+  return false;
+}
+var RepoFullNameSchema = z25.string().max(140).regex(
+  /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/,
+  "must be owner/name, as in the repository's GitHub URL"
+).refine((v) => !/\/\.{1,2}$/.test(v), "must be owner/name, as in the repository's GitHub URL");
+var BranchNameSchema = z25.string().min(1).max(255).refine(
+  (v) => !v.startsWith("refs/") && !hasControlChar(v) && !/[\s~^:?*[\\]/.test(v) && !v.includes("..") && !v.includes("@{") && !v.includes("//") && !/^[-/]/.test(v) && !/(\/|\.lock|\.)$/.test(v),
+  "must be a branch name such as main, without refs/heads/"
+);
+var WorkflowRefSchema = z25.string().max(512).regex(
+  /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}\/\.github\/workflows\/[^@\s]+\.ya?ml@\S+$/,
+  "must look like owner/repo/.github/workflows/deploy.yml@refs/heads/main"
+);
+var EnvironmentNameSchema = z25.string().min(1).max(255).refine((v) => !hasControlChar(v) && v.trim() === v, "must be an environment name");
+var SetRepoBindingRequestSchema = z25.object({
+  repoFullName: RepoFullNameSchema,
+  branch: BranchNameSchema,
+  workflowRef: WorkflowRefSchema.optional(),
+  environment: EnvironmentNameSchema.optional()
+});
+var REPO_PROVIDERS = ["github"];
+var RepoBindingSchema = z25.object({
+  provider: z25.enum(REPO_PROVIDERS),
+  repoFullName: z25.string(),
+  branch: z25.string(),
+  workflowRef: z25.string().optional(),
+  environment: z25.string().optional(),
+  /** Pinned from the first accepted token; absent until then. */
+  repositoryId: z25.string().optional(),
+  repositoryOwnerId: z25.string().optional(),
+  pinnedAt: z25.iso.datetime().optional(),
+  createdAt: z25.iso.datetime(),
+  updatedAt: z25.iso.datetime()
+});
+
 // ../shared/src/instruction.ts
-import { z as z24 } from "zod";
+import { z as z26 } from "zod";
 var INSTRUCTION_CAPABILITIES = ["fetch", "llm"];
-var InstructionCapabilitySchema = z24.enum(INSTRUCTION_CAPABILITIES);
-var AttestedInstructionSchema = z24.strictObject({
+var InstructionCapabilitySchema = z26.enum(INSTRUCTION_CAPABILITIES);
+var AttestedInstructionSchema = z26.strictObject({
   /** App the call is attributed to (registry app id). */
-  appId: z24.string().min(1),
+  appId: z26.string().min(1),
   /** Authenticated user, or the anonymous sentinel on `public` apps. */
-  userOid: z24.string().min(1),
+  userOid: z26.string().min(1),
   /**
    * Which kind of principal `userOid` is (the `PrincipalKind` vocabulary the
    * edge records at capture time — recorded, never inferred). The delegated
@@ -2048,9 +2173,9 @@ var AttestedInstructionSchema = z24.strictObject({
   userKind: PrincipalKindSchema.optional(),
   capability: InstructionCapabilitySchema,
   /** The allowlisted origin the edge authorized (scheme + host + port). */
-  origin: z24.url(),
+  origin: z26.url(),
   /** Connection (secret) name to inject, if this is a secret-backed call. */
-  connection: z24.string().min(1).optional(),
+  connection: z26.string().min(1).optional(),
   /**
    * Provider reference for a delegated call — the user's connection to this
    * provider is what egress injects. Exactly
@@ -2060,7 +2185,7 @@ var AttestedInstructionSchema = z24.strictObject({
    */
   provider: ProviderRefSchema.optional(),
   /** Correlates the edge audit row with the egress call. */
-  requestId: z24.string().min(1),
+  requestId: z26.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
@@ -2075,8 +2200,8 @@ var AttestedInstructionSchema = z24.strictObject({
    * means "old edge", not tampering — egress asserts ONLY when the claim is
    * present. Make required once a fleet is reliably past deploy.
    */
-  method: z24.string().min(1).optional(),
-  path: z24.string().optional(),
+  method: z26.string().min(1).optional(),
+  path: z26.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
@@ -2105,7 +2230,7 @@ var INSTRUCTION_TTL_SECONDS = 30;
 var INSTRUCTION_BURN_RETENTION_SECONDS = INSTRUCTION_TTL_SECONDS + 15;
 
 // ../shared/src/fetch.ts
-import { z as z25 } from "zod";
+import { z as z27 } from "zod";
 var FETCH_ERROR_CODES = [
   "forbidden",
   "rate_limited",
@@ -2118,26 +2243,26 @@ var FETCH_ERROR_CODES = [
   "provider_unavailable",
   "provider_misconfigured"
 ];
-var FetchErrorCodeSchema = z25.enum(FETCH_ERROR_CODES);
-var FetchErrorProviderSchema = z25.strictObject({
+var FetchErrorCodeSchema = z27.enum(FETCH_ERROR_CODES);
+var FetchErrorProviderSchema = z27.strictObject({
   ref: ProviderRefSchema,
-  displayName: z25.string().min(1).max(200).optional()
+  displayName: z27.string().min(1).max(200).optional()
 });
-var FetchProxyErrorSchema = z25.object({
+var FetchProxyErrorSchema = z27.object({
   code: FetchErrorCodeSchema,
-  message: z25.string(),
+  message: z27.string(),
   /** Present only on the delegated-call codes that carry it (`connection_required`, `provider_unavailable`). */
   provider: FetchErrorProviderSchema.optional()
 });
 
 // ../shared/src/sessions.ts
-import { z as z26 } from "zod";
-var SessionPrincipalKindSchema = z26.enum(["user", "password"]);
-var SessionSummarySchema = z26.object({
-  id: z26.uuid(),
-  appId: z26.uuid(),
+import { z as z28 } from "zod";
+var SessionPrincipalKindSchema = z28.enum(["user", "password"]);
+var SessionSummarySchema = z28.object({
+  id: z28.uuid(),
+  appId: z28.uuid(),
   /** App slug at read time; the FK guarantees the app row exists. */
-  slug: z26.string(),
+  slug: z28.string(),
   /**
    * The identity half — Entra's `oid` claim since ADR-0048 (a pairwise `sub`
    * on rows that predate the re-base; a `pw_*` pseudonym for shared-password
@@ -2145,55 +2270,63 @@ var SessionSummarySchema = z26.object({
    * resort: the platform deliberately holds no Graph `/users` grant, so no
    * principal id it stores resolves to a name.
    */
-  userOid: z26.string(),
+  userOid: z28.string(),
   /**
    * The display half, captured at login. Render, never compare. Null for
    * shared-password visitors (each login is a fresh pseudonym) and for rows
    * predating the columns.
    */
-  userName: z26.string().nullable(),
-  userEmail: z26.string().nullable(),
+  userName: z28.string().nullable(),
+  userEmail: z28.string().nullable(),
   userKind: SessionPrincipalKindSchema.nullable(),
   /** Group-id snapshot as of this session's login/refresh. */
-  groups: z26.array(z26.string()),
-  createdAt: z26.iso.datetime(),
+  groups: z28.array(z28.string()),
+  createdAt: z28.iso.datetime(),
   /** Null while the handoff is un-redeemed — impossible here (live rows only). */
-  activatedAt: z26.iso.datetime().nullable(),
+  activatedAt: z28.iso.datetime().nullable(),
   /** When silent re-auth (`prompt=none`) becomes due; past = overdue. */
-  refreshDueAt: z26.iso.datetime(),
+  refreshDueAt: z28.iso.datetime(),
   /** Hard cap — the session is dead at this instant regardless of activity. */
-  expiresAt: z26.iso.datetime()
+  expiresAt: z28.iso.datetime()
 });
-var SessionListResponseSchema = z26.object({
-  rows: z26.array(SessionSummarySchema),
-  groupNames: z26.record(z26.string(), z26.string().nullable()),
-  groupsResolved: z26.boolean()
+var SessionListResponseSchema = z28.object({
+  rows: z28.array(SessionSummarySchema),
+  groupNames: z28.record(z28.string(), z28.string().nullable()),
+  groupsResolved: z28.boolean()
 });
-var SessionRevokeRequestSchema = z26.object({
+var SessionRevokeRequestSchema = z28.object({
   /**
    * A session's principal id as seen in the list — the `oid` claim, a `pw_*`
    * pseudonym, or a pre-re-base pairwise `sub`. Opaque to the admin; copied
    * from the row they clicked, so its shape is whatever the session rows
    * hold — bounded only against abuse, not parsed.
    */
-  userOid: z26.string().min(1).max(200)
+  userOid: z28.string().min(1).max(200)
 });
-var SessionRevokeResultSchema = z26.object({
-  removed: z26.int().nonnegative(),
+var SessionRevokeResultSchema = z28.object({
+  removed: z28.int().nonnegative(),
   /** Slugs of the apps the removed sessions lived on; empty when none. */
-  apps: z26.array(z26.string())
+  apps: z28.array(z28.string())
 });
 
 // src/client.ts
 var CliError = class extends Error {
   code;
-  constructor(message, code) {
+  /** The portal envelope's `details`, when it sent one. */
+  details;
+  constructor(message, code, details) {
     super(message);
     this.name = "CliError";
     this.code = code;
+    this.details = details;
   }
 };
-var VersionListSchema = z27.array(VersionSchema);
+function errorReason(err) {
+  if (!(err instanceof CliError)) return void 0;
+  const reason = err.details?.reason;
+  return typeof reason === "string" ? reason : void 0;
+}
+var VersionListSchema = z29.array(VersionSchema);
 var PortalClient = class {
   #baseUrl;
   #tokenProvider;
@@ -2219,6 +2352,34 @@ var PortalClient = class {
   getAuthConfig() {
     return this.#json(AuthConfigResponseSchema, "GET", "/api/v1/auth/config", {});
   }
+  /** Public deployment topology (`GET /api/v1/config`), incl. the CI token audience. */
+  getDeploymentConfig() {
+    return this.#json(DeploymentConfigResponseSchema, "GET", "/api/v1/config", {});
+  }
+  /** The app's GitHub binding (ADR-0051), or null when it has none. */
+  async getRepoBinding(slug) {
+    try {
+      return await this.#json(RepoBindingSchema, "GET", `/api/v1/apps/${enc(slug)}/repo-binding`, {
+        auth: true
+      });
+    } catch (err) {
+      if (errorReason(err) === "no_binding") return null;
+      throw err;
+    }
+  }
+  putRepoBinding(slug, body) {
+    return this.#json(RepoBindingSchema, "PUT", `/api/v1/apps/${enc(slug)}/repo-binding`, {
+      auth: true,
+      body
+    });
+  }
+  async deleteRepoBinding(slug) {
+    const res = await fetch(this.#url(`/api/v1/apps/${enc(slug)}/repo-binding`), {
+      method: "DELETE",
+      headers: await this.#authHeaders(true)
+    });
+    if (!res.ok) await this.#parse(z29.unknown(), res);
+  }
   /** The authenticated actor, per the portal — powers `helix whoami`. */
   me() {
     return this.#json(PortalMeResponseSchema, "GET", "/api/v1/me", { auth: true });
@@ -2258,8 +2419,22 @@ var PortalClient = class {
     });
     return this.#parse(UploadVersionResponseSchema, res);
   }
-  #url(path3) {
-    return `${this.#baseUrl}${path3}`;
+  /**
+   * Upload from GitHub Actions to the CI route (ADR-0051), authenticated by the
+   * job's GitHub OIDC token rather than a Helix sign-in.
+   */
+  async uploadCiVersion(slug, zip, githubToken) {
+    const form = new FormData();
+    form.append("bundle", new Blob([new Uint8Array(zip)]), "bundle.zip");
+    const res = await fetch(this.#url(`/api/v1/apps/${enc(slug)}/ci/versions`), {
+      method: "POST",
+      headers: { authorization: `Bearer ${githubToken}` },
+      body: form
+    });
+    return this.#parse(UploadVersionResponseSchema, res);
+  }
+  #url(path5) {
+    return `${this.#baseUrl}${path5}`;
   }
   async #authHeaders(auth) {
     if (!auth) return {};
@@ -2269,10 +2444,10 @@ var PortalClient = class {
     }
     return { authorization: `Bearer ${token}` };
   }
-  async #json(schema, method, path3, opts) {
+  async #json(schema, method, path5, 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), {
+    const res = await fetch(this.#url(path5), {
       method,
       headers,
       body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
@@ -2284,20 +2459,26 @@ var PortalClient = class {
     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);
+      if (parsed.success) {
+        const { message, code, details } = parsed.data.error;
+        throw new CliError(message, code, details);
+      }
       throw new CliError(`request failed (HTTP ${res.status})`);
     }
     return schema.parse(data);
   }
   /** A non-JSON GET (the markdown skill) — errors still typed via the envelope. */
-  async #text(path3, opts) {
+  async #text(path5, opts) {
     const headers = await this.#authHeaders(opts.auth ?? false);
-    const res = await fetch(this.#url(path3), { method: "GET", headers });
+    const res = await fetch(this.#url(path5), { method: "GET", headers });
     const body = await res.text();
     if (!res.ok) {
       const data = body ? safeJsonParse(body) : void 0;
       const parsed = ApiErrorSchema.safeParse(data);
-      if (parsed.success) throw new CliError(parsed.data.error.message, parsed.data.error.code);
+      if (parsed.success) {
+        const { message, code, details } = parsed.data.error;
+        throw new CliError(message, code, details);
+      }
       throw new CliError(`request failed (HTTP ${res.status})`);
     }
     return body;
@@ -2444,6 +2625,28 @@ async function deleteTokens(portalUrl, file = defaultTokenPath()) {
   return true;
 }
 
+// src/auth/githubActions.ts
+import { z as z30 } from "zod";
+function githubTokenSource(env) {
+  const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  return requestUrl && requestToken ? { requestUrl, requestToken } : null;
+}
+var IdTokenResponseSchema = z30.object({ value: z30.string().min(1) });
+async function requestGithubIdToken(source, audience, fetchImpl = fetch) {
+  const url = new URL(source.requestUrl);
+  url.searchParams.set("audience", audience);
+  const res = await fetchImpl(url, {
+    headers: { authorization: `Bearer ${source.requestToken}`, accept: "application/json" }
+  });
+  if (!res.ok) {
+    throw new CliError(`GitHub refused the ID token request (HTTP ${res.status})`);
+  }
+  const parsed = IdTokenResponseSchema.safeParse(await res.json());
+  if (!parsed.success) throw new CliError("GitHub's ID token response had no token");
+  return parsed.data.value;
+}
+
 // src/commands.ts
 function requireSlug(config) {
   if (!config.slug) {
@@ -2498,13 +2701,53 @@ async function createCommand(client, config, opts) {
   console.log(`Created app "${app.slug}".`);
   printApp(app);
 }
-async function deployCommand(client, config, opts) {
+async function deployCommand(client, config, opts, env = process.env) {
   const slug = requireSlug(config);
+  const github = config.token ? null : githubTokenSource(env);
+  if (!config.token && !github && env.GITHUB_ACTIONS === "true") {
+    throw new CliError(
+      "running in GitHub Actions without an ID token; add `permissions: id-token: write` to the workflow (see `helix ci init`)"
+    );
+  }
+  if (github && !isSafePortalUrl(config.portalUrl)) {
+    throw new CliError(
+      `won't send a GitHub token over plain http (${config.portalUrl}); use the portal's https URL`
+    );
+  }
+  if (github && opts.promote) {
+    throw new CliError(
+      "CI deploys land as a preview; promote it in the portal or with `helix promote <n>`"
+    );
+  }
   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);
+  let result;
+  if (github) {
+    const deployment = await client.getDeploymentConfig();
+    if (!deployment.repoDeploy?.enabled) {
+      throw new CliError("this portal does not accept repo-backed deploys (ask its operator)");
+    }
+    const idToken = await requestGithubIdToken(github, deployment.repoDeploy.audience);
+    try {
+      result = await client.uploadCiVersion(slug, zip, idToken);
+    } catch (err) {
+      if (err instanceof CliError && err.code === "forbidden" && !errorReason(err)) {
+        throw new CliError(
+          `${err.message}; check that "${slug}" is connected to this repo (helix ci show)`,
+          err.code
+        );
+      }
+      throw err;
+    }
+  } else {
+    result = await client.uploadVersion(slug, zip);
+  }
+  const { version, warnings } = result;
   console.log(`Uploaded as preview:`);
   printVersion(version);
+  if (version.source) {
+    console.log(`  from: ${version.source.repoFullName}@${version.source.commitSha.slice(0, 7)}`);
+  }
   if (warnings.length > 0) {
     console.log(`
 ${warnings.length} CSP warning(s):`);
@@ -2520,6 +2763,10 @@ Promoted version ${version.number} to live.`);
 Not live yet \u2014 promote with: helix promote ${version.number}`);
   }
 }
+function isSafePortalUrl(url) {
+  const { protocol, hostname } = new URL(url);
+  return protocol === "https:" || protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(hostname);
+}
 async function versionsCommand(client, config) {
   const slug = requireSlug(config);
   const versions = await client.listVersions(slug);
@@ -2615,6 +2862,12 @@ function makeTokenProvider(opts, deps = defaultDeps) {
   };
 }
 
+// src/ci/commands.ts
+import { execFile } from "node:child_process";
+import { mkdir as mkdir2, readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
+import path4 from "node:path";
+import { promisify } from "node:util";
+
 // src/config.ts
 import { readFile as readFile3 } from "node:fs/promises";
 import path2 from "node:path";
@@ -2644,6 +2897,341 @@ async function resolveConfig(flags, env = process.env, cwd = process.cwd()) {
   };
 }
 
+// src/version.ts
+var CLI_VERSION = true ? "0.5.0" : "latest";
+
+// src/ci/remote.ts
+function parseGithubRemote(remote, githubHost = "github.com") {
+  const url = remote.trim();
+  const scp = /^[\w.-]+@([^:/]+):(.+)$/.exec(url);
+  let host;
+  let path5;
+  if (scp && !url.includes("://")) {
+    host = scp[1];
+    path5 = scp[2];
+  } else {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return null;
+    }
+    if (!["https:", "http:", "ssh:", "git:"].includes(parsed.protocol)) return null;
+    host = parsed.hostname;
+    path5 = parsed.pathname.replace(/^\/+/, "");
+  }
+  if (host.toLowerCase() !== githubHost.toLowerCase()) return null;
+  const match = /^([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9._-]+?)(\.git)?\/?$/.exec(path5);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+// src/ci/workflow.ts
+import { access, readFile as readFile4 } from "node:fs/promises";
+import path3 from "node:path";
+var REUSABLE_WORKFLOW_PATH = "AZX-PBC-OSS/helix-actions/.github/workflows/deploy.yml";
+var REUSABLE_WORKFLOW_TAG = "v1";
+var REUSABLE_WORKFLOW_REF = `${REUSABLE_WORKFLOW_PATH}@refs/tags/${REUSABLE_WORKFLOW_TAG}`;
+var WORKFLOW_FILE = ".github/workflows/helix-deploy.yml";
+var DEFAULT_PNPM_VERSION = "10";
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"]
+];
+var posix = (p) => p.split(path3.sep).join("/");
+async function readPackageJson(file) {
+  try {
+    return JSON.parse(await readFile4(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function detectBuildPlan(appDir, repoRoot) {
+  let packageManager = "npm";
+  let lockfilePath = null;
+  search: for (const dir of [appDir, repoRoot]) {
+    for (const [name, pm] of LOCKFILES) {
+      if (await exists(path3.join(dir, name))) {
+        packageManager = pm;
+        lockfilePath = posix(path3.relative(repoRoot, path3.join(dir, name)));
+        break search;
+      }
+    }
+  }
+  const appPkg = await readPackageJson(path3.join(appDir, "package.json"));
+  let pnpmPackageJson = null;
+  if (packageManager === "pnpm") {
+    for (const dir of [appDir, repoRoot]) {
+      const pkg = dir === appDir ? appPkg : await readPackageJson(path3.join(dir, "package.json"));
+      if (typeof pkg?.packageManager === "string" && pkg.packageManager.startsWith("pnpm@")) {
+        pnpmPackageJson = posix(path3.relative(repoRoot, path3.join(dir, "package.json")));
+        break;
+      }
+    }
+  }
+  const buildScript = typeof appPkg?.scripts?.build === "string" ? "build" : null;
+  return {
+    packageManager,
+    hasLockfile: lockfilePath !== null,
+    lockfilePath,
+    pnpmPackageJson,
+    buildScript
+  };
+}
+var INSTALL = {
+  npm: "npm ci",
+  pnpm: "pnpm install --frozen-lockfile",
+  yarn: "yarn install --frozen-lockfile"
+};
+var HEADER = (branch) => `# Deploys this app to Helix as a preview on every push to ${branch}.
+# Written by \`helix ci init\`. The repo needs no secret: the deploy job
+# authenticates with its own GitHub OIDC token. The build job runs the repo's
+# code without that permission. A preview goes live only when someone promotes
+# it, in the portal or with \`helix promote <n>\`.
+name: Deploy to Helix
+on:
+  push:
+    branches: [${JSON.stringify(branch)}]
+  workflow_dispatch:
+# Each job asks for only what it needs.
+permissions: {}
+`;
+var inDir = (workingDirectory, rel) => workingDirectory === "." ? rel : `${workingDirectory}/${rel}`;
+var FIND_OUTPUT = `if [ -f helix.json ]; then cfg=helix.json; elif [ -f azx.json ]; then cfg=azx.json; else echo "::error::no helix.json in this directory"; exit 1; fi
+          echo "config=$cfg" >> "$GITHUB_OUTPUT"
+          echo "dir=$(node -p "require('./' + process.argv[1]).dir || 'dist'" "$cfg")" >> "$GITHUB_OUTPUT"`;
+function renderStarterWorkflow(opts) {
+  const { plan, workingDirectory: wd } = opts;
+  const sub = wd !== ".";
+  const install = plan.hasLockfile ? INSTALL[plan.packageManager] : "npm install";
+  const pnpmSetup = plan.packageManager !== "pnpm" ? [] : [
+    "      - uses: pnpm/action-setup@v4",
+    "        with:",
+    plan.pnpmPackageJson ? `          package_json_file: ${plan.pnpmPackageJson}` : `          version: ${DEFAULT_PNPM_VERSION}`
+  ];
+  const cache = plan.lockfilePath ? [
+    `          cache: ${plan.packageManager}`,
+    `          cache-dependency-path: ${plan.lockfilePath}`
+  ] : [];
+  const lines = [
+    HEADER(opts.branch),
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "    permissions:",
+    "      contents: read",
+    ...sub ? ["    defaults:", "      run:", `        working-directory: ${JSON.stringify(wd)}`] : [],
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    ...pnpmSetup,
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 24",
+    ...cache,
+    `      - run: ${install}`,
+    ...plan.buildScript ? [`      - run: ${plan.packageManager} run ${plan.buildScript}`] : [],
+    "      - id: output",
+    "        run: |",
+    `          ${FIND_OUTPUT}`,
+    "      - uses: actions/upload-artifact@v4",
+    "        with:",
+    "          name: helix-bundle",
+    "          path: |",
+    `            ${inDir(wd, "${{ steps.output.outputs.config }}")}`,
+    `            ${inDir(wd, "${{ steps.output.outputs.dir }}")}`,
+    "          include-hidden-files: true",
+    "          if-no-files-found: error",
+    "  deploy:",
+    "    needs: build",
+    "    runs-on: ubuntu-latest",
+    "    permissions:",
+    "      id-token: write",
+    "    steps:",
+    "      - uses: actions/download-artifact@v4",
+    "        with:",
+    "          name: helix-bundle",
+    `          path: ${JSON.stringify(wd)}`,
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 24",
+    `      - run: npx --yes @azx-pbc/helix-cli@${opts.cliVersion} deploy`,
+    ...sub ? [`        working-directory: ${JSON.stringify(wd)}`] : [],
+    ""
+  ];
+  return lines.join("\n");
+}
+function renderReusableWorkflow(opts) {
+  const { plan } = opts;
+  const lines = [
+    HEADER(opts.branch),
+    "jobs:",
+    "  deploy:",
+    `    uses: ${REUSABLE_WORKFLOW_PATH}@${REUSABLE_WORKFLOW_TAG}`,
+    // A caller grants the reusable workflow at most these; its own jobs narrow
+    // them per job.
+    "    permissions:",
+    "      contents: read",
+    "      id-token: write",
+    "    with:",
+    `      package-manager: ${plan.packageManager}`,
+    `      working-directory: ${JSON.stringify(opts.workingDirectory)}`,
+    `      build-script: ${JSON.stringify(plan.buildScript ?? "")}`,
+    ...plan.packageManager === "pnpm" && !plan.pnpmPackageJson ? [`      pnpm-version: ${JSON.stringify(DEFAULT_PNPM_VERSION)}`] : [],
+    `      cli-version: ${JSON.stringify(opts.cliVersion)}`,
+    ""
+  ];
+  return lines.join("\n");
+}
+
+// src/ci/commands.ts
+var run = promisify(execFile);
+var defaultGit = async (args, cwd) => (await run("git", args, { cwd })).stdout.trim();
+function requireSlug2(config) {
+  if (!config.slug) throw new CliError("no app slug; set it in helix.json or pass --slug");
+  return config.slug;
+}
+async function ciInitCommand(client, config, opts, deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const git = deps.git ?? defaultGit;
+  const log = deps.log ?? console.log;
+  const slug = requireSlug2(config);
+  const deployment = await client.getDeploymentConfig();
+  if (!deployment.repoDeploy?.enabled) {
+    throw new CliError("this portal does not accept repo-backed deploys (ask its operator)");
+  }
+  const githubHost = new URL(deployment.repoDeploy.serverUrl).hostname;
+  let repoRoot;
+  try {
+    repoRoot = await git(["rev-parse", "--show-toplevel"], cwd);
+  } catch {
+    throw new CliError("not inside a git checkout; run this from the app's directory in its repo");
+  }
+  const repo = opts.repo ?? parseGithubRemote(await originUrl(git, cwd), githubHost);
+  if (!repo) {
+    throw new CliError(
+      `couldn't read a ${githubHost} repo from the origin remote; pass --repo owner/name`
+    );
+  }
+  const branch = opts.branch ?? await defaultBranch(git, cwd);
+  if (!branch || branch === "HEAD") {
+    throw new CliError("couldn't tell which branch to deploy from; pass --branch <name>");
+  }
+  const workflowPath = path4.join(repoRoot, WORKFLOW_FILE);
+  if (!opts.force && await fileExists(workflowPath)) {
+    throw new CliError(`${WORKFLOW_FILE} already exists; pass --force to replace it`);
+  }
+  const workingDirectory = path4.relative(repoRoot, cwd).split(path4.sep).join("/") || ".";
+  const plan = await detectBuildPlan(cwd, repoRoot);
+  const render = opts.reusable ? renderReusableWorkflow : renderStarterWorkflow;
+  const workflow = render({ branch, workingDirectory, plan, cliVersion: CLI_VERSION });
+  const existing = await client.getRepoBinding(slug);
+  const workflowRef = opts.reusable ? REUSABLE_WORKFLOW_REF : existing?.workflowRef;
+  const environment = existing?.environment;
+  if (existing?.workflowRef && workflowRef !== existing.workflowRef && !opts.force) {
+    throw new CliError(
+      `the binding pins deploys to workflow ${existing.workflowRef}; --reusable would replace that pin. Pass --force to replace it.`
+    );
+  }
+  const binding = await client.putRepoBinding(slug, {
+    repoFullName: repo,
+    branch,
+    ...workflowRef ? { workflowRef } : {},
+    ...environment ? { environment } : {}
+  });
+  const configFile = await writeHelixJson(cwd, {
+    slug,
+    portalUrl: config.portalUrl,
+    dir: config.dir
+  });
+  await mkdir2(path4.dirname(workflowPath), { recursive: true });
+  await writeFile3(workflowPath, workflow, "utf8");
+  log(`Connected "${slug}" to ${repo}.`);
+  log(`Branch: ${branch}${opts.branch ? "" : " (use --branch to change)"}`);
+  printBinding(binding, log);
+  log(`Wrote ${path4.relative(cwd, workflowPath) || WORKFLOW_FILE} and ${configFile}.`);
+  if (isLocalPortal(config.portalUrl)) {
+    log(`warning: helix.json points CI at ${config.portalUrl}, which a GitHub runner can't reach.`);
+  }
+  log("Commit both files and push; each push lands a preview to promote.");
+}
+async function ciShowCommand(client, config, log = console.log) {
+  const slug = requireSlug2(config);
+  const binding = await client.getRepoBinding(slug);
+  if (!binding) {
+    log(`"${slug}" is not connected to a repo. Run: helix ci init`);
+    return;
+  }
+  printBinding(binding, log);
+}
+async function ciRemoveCommand(client, config, log = console.log) {
+  const slug = requireSlug2(config);
+  await client.deleteRepoBinding(slug);
+  log(`Disconnected "${slug}" from its repo. CI deploys to it are now refused.`);
+}
+function printBinding(b, log) {
+  log(`  repo:        ${b.repoFullName}`);
+  log(`  branch:      ${b.branch}`);
+  if (b.workflowRef) log(`  workflow:    ${b.workflowRef}`);
+  if (b.environment) log(`  environment: ${b.environment}`);
+  log(
+    b.repositoryId ? `  pinned:      repo id ${b.repositoryId}, owner id ${b.repositoryOwnerId ?? "?"}` : "  pinned:      not yet (the first deploy pins the repo's ids)"
+  );
+}
+async function originUrl(git, cwd) {
+  try {
+    return await git(["remote", "get-url", "origin"], cwd);
+  } catch {
+    return "";
+  }
+}
+async function defaultBranch(git, cwd) {
+  try {
+    const remoteHead = await git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd);
+    if (remoteHead.startsWith("origin/")) return remoteHead.slice("origin/".length);
+  } catch {
+  }
+  return git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+}
+async function fileExists(file) {
+  try {
+    await readFile5(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeHelixJson(cwd, values) {
+  for (const name2 of CONFIG_FILENAMES) {
+    const file = path4.join(cwd, name2);
+    let existing;
+    try {
+      existing = JSON.parse(await readFile5(file, "utf8"));
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+    await writeFile3(file, `${JSON.stringify({ ...existing, ...values }, null, 2)}
+`, "utf8");
+    return name2;
+  }
+  const name = CONFIG_FILENAMES[0];
+  await writeFile3(path4.join(cwd, name), `${JSON.stringify(values, null, 2)}
+`, "utf8");
+  return name;
+}
+function isLocalPortal(url) {
+  const host = new URL(url).hostname;
+  return host === "localhost" || host === "127.0.0.1" || host.endsWith(".local") || host === "::1";
+}
+
 // src/bin.ts
 var USAGE = `helix \u2014 Helix deploy CLI
 
@@ -2657,9 +3245,13 @@ Usage:
   helix promote  <number>
   helix rollback [number]
   helix skill    [--path <file>]   # write this deployment's agent skill to disk
+  helix ci init  [--repo <owner/name>] [--branch <b>] [--reusable] [--force]
+                                   # connect the app to its GitHub repo and write the workflow
+  helix ci show | helix ci remove
 
 Common flags: --slug <slug>  --portal-url <url>  --token <token>
-Env:  HELIX_PORTAL_URL, HELIX_TOKEN (static token \u2014 skips login; CI/scripts).
+Env:  HELIX_PORTAL_URL, HELIX_TOKEN (static token \u2014 skips login; local scripts).
+      In GitHub Actions, deploy uses the job's OIDC token (permissions: id-token: write).
 Config file: helix.json { slug, portalUrl, dir, description }
 Visibility: internal | group:<id>[,<id>...] | password | public
 `;
@@ -2704,6 +3296,24 @@ async function main() {
         visibility: values.visibility
       });
       break;
+    case "ci": {
+      const sub = positionals[1];
+      if (sub === "init") {
+        await ciInitCommand(client, config, {
+          repo: values.repo,
+          branch: values.branch,
+          reusable: values.reusable,
+          force: values.force
+        });
+      } else if (sub === "show") {
+        await ciShowCommand(client, config);
+      } else if (sub === "remove") {
+        await ciRemoveCommand(client, config);
+      } else {
+        throw new CliError("usage: helix ci init | show | remove");
+      }
+      break;
+    }
     case "versions":
       await versionsCommand(client, config);
       break;