@thejoseki/clawform 2.3.0 → 2.3.2

package/src/commands/ci-init.js

@@ -1,212 +1,393 @@
-// clawform ci init — generate a .gitlab-ci.yml for the Clawform CI model:
-// GitLab On-Prem is the source of truth; AWS just runs the pipeline.
-//
-//   validate (every MR, offline)  →  deploy:upload (protected branch)
-//   - validate: cfn-lint the cfn/ templates on a GitLab Runner. No AWS creds,
-//     so it's safe on any runner and fast on every merge request. cfn-lint is
-//     the CI floor — local `clawform validate` adds cfn-guard + cfn-nag +
-//     lint-overrides on top; the generated file says so.
-//   - deploy:upload: zip the repo and put it to the pipeline's SourceBucket as
-//     source.zip, which triggers the CodePipeline stood up by
-//     templates/cicd-pipeline.yaml (validate → manual approval → execute).
-//
-// The CLI writes the file and prints the next steps; it does NOT touch AWS.
-// renderGitlabCi() is a pure string builder so it's unit-tested without I/O.
-
-import { writeFile, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { logger } from '../lib/logger.js';
-import { assertLicensed } from '../lib/license.js';
-import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
-
-const BUCKET_PLACEHOLDER = '<PIPELINE_SOURCE_BUCKET>';
-
-export function renderGitlabCi({ cfnDir = 'cfn', branch = 'main', sourceBucket } = {}) {
-  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
-  return `# Generated by \`clawform ci init\`. Clawform CI for GitLab On-Prem.
-# Model: GitLab is the source of truth; AWS runs the pipeline. The protected
-# branch uploads a source bundle to S3, which triggers the CodePipeline from
-# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
-#
-# Required CI/CD variables (Settings -> CI/CD -> Variables), protected + masked:
-#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
-#     s3:PutObject on the pipeline SourceBucket (or use a runner instance role)
-#   AWS_DEFAULT_REGION                          -> the pipeline's region
-
-stages:
-  - validate
-  - deploy
-
-# Every merge request: lint the templates. Offline — no AWS credentials needed.
-# NOTE: cfn-lint is the CI *floor*. Local \`clawform validate\` additionally runs
-# cfn-guard (the shipped rules.guard, incl. the Rule #4 retention checks) and
-# cfn-nag — run it before merging; green CI is not the same as a green /validate.
-validate:cfn:
-  stage: validate
-  image: python:3.12-slim
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-  variables:
-    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
-  cache:
-    key: clawform-pip
-    paths:
-      - .cache/pip
-  script:
-    - pip install --quiet cfn-lint
-    - cfn-lint ${cfnDir}/*.yaml
-
-# Protected branch only: bundle the repo and hand it to the pipeline. CodePipeline
-# re-validates, builds a change-set, and waits for a human to approve in the
-# CodePipeline console before executing (Rule #5 approval gate, off-TTY).
-# The entrypoint override is REQUIRED: amazon/aws-cli's Docker ENTRYPOINT is the
-# aws binary itself, so without it the runner cannot start a shell in the container.
-deploy:upload:
-  stage: deploy
-  image:
-    name: amazon/aws-cli:latest
-    entrypoint: [""]
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "${branch}"'
-  before_script:
-    - yum install -y -q zip
-  script:
-    # Bundle the template dir plus the optional config/params paths that exist.
-    # Built explicitly (no stderr suppression, no || fallback) so a real zip
-    # failure fails the job instead of uploading a partial bundle.
-    - BUNDLE_PATHS="${cfnDir}"
-    - for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
-    - echo "Bundling: $BUNDLE_PATHS"
-    - zip -r source.zip $BUNDLE_PATHS
-    - aws s3 cp source.zip "s3://${bucket}/source.zip"
-  # The pipeline takes over from here — approve the change-set in CodePipeline.
-`;
-}
-
-// Same Git → S3 → CodePipeline model as the GitLab variant, expressed as a
-// GitHub Actions workflow. Pure string builder, unit-tested without I/O.
-export function renderGithubActions({ cfnDir = 'cfn', branch = 'main', sourceBucket } = {}) {
-  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
-  return `# Generated by \`clawform ci init --provider github\`. Clawform CI for GitHub.
-# Model: GitHub is the source of truth; AWS runs the pipeline. The protected
-# branch uploads a source bundle to S3, which triggers the CodePipeline from
-# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
-#
-# Required repository secrets (Settings -> Secrets and variables -> Actions):
-#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
-#     s3:PutObject on the pipeline SourceBucket
-#   AWS_DEFAULT_REGION                          -> the pipeline's region
-
-name: clawform-cfn
-
-on:
-  pull_request:
-  push:
-    branches: [ ${branch} ]
-
-jobs:
-  # Every pull request: lint the templates. Offline — no AWS credentials.
-  # NOTE: cfn-lint is the CI floor. Local \`clawform validate\` additionally runs
-  # cfn-guard (rules.guard, incl. Rule #4 retention) and cfn-nag — green CI is
-  # not the same as a green /validate.
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-          cache: pip
-      - run: pip install --quiet cfn-lint
-      - run: cfn-lint ${cfnDir}/*.yaml
-
-  # Protected branch only: bundle the repo and hand it to the pipeline, which
-  # re-validates, builds a change-set, and waits for a human to approve in the
-  # CodePipeline console before executing (Rule #5 approval gate, off-TTY).
-  upload:
-    if: github.ref == 'refs/heads/${branch}'
-    needs: validate
-    runs-on: ubuntu-latest
-    env:
-      AWS_ACCESS_KEY_ID: \${{ secrets.AWS_ACCESS_KEY_ID }}
-      AWS_SECRET_ACCESS_KEY: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
-      AWS_DEFAULT_REGION: \${{ secrets.AWS_DEFAULT_REGION }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Bundle and upload source
-        run: |
-          # Bundle the template dir plus the optional config/params paths that
-          # exist. Built explicitly (no stderr suppression, no || fallback) so a
-          # real zip failure fails the job instead of uploading a partial bundle.
-          BUNDLE_PATHS="${cfnDir}"
-          for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
-          echo "Bundling: $BUNDLE_PATHS"
-          zip -r source.zip $BUNDLE_PATHS
-          aws s3 cp source.zip "s3://${bucket}/source.zip"
-      # The pipeline takes over from here — approve the change-set in CodePipeline.
-`;
-}
-
-export default async function ciInit({ sourceBucket, cfnDir = 'cfn', branch = 'main', force, projectDir, provider = 'gitlab' } = {}) {
-  await assertLicensed({ command: 'ci-init', client: resolveLicenseClient() });
-  const dir = projectDir || process.cwd();
-
-  // Provider decides both the rendered content and where it lands. Default is
-  // gitlab so the pre-existing call shape keeps working.
-  const isGithub = provider === 'github';
-  const content = isGithub
-    ? renderGithubActions({ cfnDir, branch, sourceBucket })
-    : renderGitlabCi({ cfnDir, branch, sourceBucket });
-
-  const primary = isGithub
-    ? join(dir, '.github', 'workflows', 'clawform-cfn.yml')
-    : join(dir, '.gitlab-ci.yml');
-  const sample = isGithub
-    ? join(dir, '.github', 'workflows', 'clawform-cfn.clawform.yml')
-    : join(dir, '.gitlab-ci.clawform.yml');
-
-  await mkdir(dirname(primary), { recursive: true });
-  const exists = existsSync(primary);
-  // Never clobber an existing pipeline config silently — write a sample alongside
-  // it and let the user merge, unless they explicitly asked to overwrite.
-  const target = exists && !force ? sample : primary;
-  await writeFile(target, content, 'utf8');
-
-  logger.step(`clawform ci init`);
-  if (target === primary) {
-    logger.ok(`Wrote ${target}`);
-  } else {
-    logger.warn(`${primary} already exists — wrote a sample to ${target} instead. Merge it in (or re-run with --force to overwrite).`);
-  }
-
-  logger.info('');
-  logger.info('Next steps:');
-  logger.info('  1. Stand up the pipeline stack FIRST (it creates the SourceBucket this CI uploads to):');
-  logger.info('       clawform deploy templates/cicd-pipeline.yaml <env> \\');
-  logger.info('         --stack-name <env>-<customer>-<project>-pipeline --project <project> \\');
-  logger.info('         --params params/<env>-pipeline.json --capabilities CAPABILITY_NAMED_IAM');
-  logger.info('     The params file must set ALL template parameters: EnvName, CustomerName, ProjectName,');
-  logger.info('     TargetStackName, TemplatePathInBundle, ApprovalEmail, CfnDeployRoleArn');
-  if (cfnDir !== 'cfn') {
-    logger.info(`     — and CfnDirInBundle="${cfnDir}" (you used --cfn-dir, so the pipeline's lint stage must match).`);
-  } else {
-    logger.info('     (CfnDirInBundle defaults to "cfn" and matches this CI file).');
-  }
-  if (!sourceBucket) {
-    logger.warn(`  2. Replace ${BUCKET_PLACEHOLDER} in the generated file with the stack's SourceBucketName output`);
-    logger.info('     (or re-run: clawform ci init --source-bucket <name> --force).');
-  } else {
-    logger.info(`  2. SourceBucket is set to "${sourceBucket}".`);
-  }
-  logger.info('  3. In GitLab → Settings → CI/CD → Variables, add (protected + masked):');
-  logger.info('       AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (IAM user scoped to s3:PutObject on the bucket),');
-  logger.info('       AWS_DEFAULT_REGION.');
-  logger.info('  4. Know the pipeline\'s limits: it enforces the Rule #5 SHAPE (changeset → approval → execute)');
-  logger.info('     but NOT the CLI\'s other gates (account guard, legacy-freeze, export-lock, data-resource');
-  logger.info('     retype). The approver MUST open the change-set link and check for Replace on data');
-  logger.info('     resources before approving. Details: templates/cicd-pipeline.yaml header.');
-  logger.info('  5. Older account that still has CodeCommit and prefers a Git mirror? Point GitLab repository');
-  logger.info('     mirroring at a CodeCommit repo and swap the pipeline Source action to CodeCommit — see');
-  logger.info('     the prose header in templates/cicd-pipeline.yaml.');
-}
+// clawform ci init — generate CI config for the Clawform model: your Git host
+// (GitHub or GitLab, SaaS or self-managed) is the source of truth; AWS just runs
+// the pipeline.
+//
+//   validate (every MR/PR, offline)  →  upload (protected branch)
+//   - validate: cfn-lint the cfn/ templates on a runner. No AWS creds, so it's
+//     safe on any runner and fast on every change. cfn-lint is the CI floor —
+//     local `clawform validate` adds cfn-guard + cfn-nag + lint-overrides on top;
+//     the generated file says so.
+//   - upload: zip the repo and put it to the pipeline's SourceBucket as
+//     source.zip, which triggers the CodePipeline stood up by
+//     templates/cicd-pipeline.yaml (validate → manual approval → execute).
+//
+// Credentials come one of two ways (--auth): `keys` uses long-lived IAM access
+// keys stored as CI secrets (default); `oidc` is keyless — the protected branch
+// assumes an IAM role via the host's OIDC issuer (github.com / gitlab.com only).
+//
+// The CLI writes the file and prints the next steps; it does NOT touch AWS.
+// The render* functions are pure string builders, unit-tested without I/O.
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { logger } from '../lib/logger.js';
+import { loadProjectConfig } from '../lib/project-config.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const PROVIDERS = new Set(['gitlab', 'github']);
+const AUTH_MODES = new Set(['keys', 'oidc']);
+
+const BUCKET_PLACEHOLDER = '<PIPELINE_SOURCE_BUCKET>';
+
+// The bundle-and-upload tail shared by both GitLab auth branches. Built explicitly
+// (no stderr suppression, no || fallback) so a real zip failure fails the job
+// instead of uploading a partial bundle. Emitted identically for keys and oidc so
+// the two modes stay functionally equivalent past the credential step (D1, D4).
+function gitlabBundleSteps({ cfnDir, bucket }) {
+  return `    - BUNDLE_PATHS="${cfnDir}"
+    - for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
+    - echo "Bundling: $BUNDLE_PATHS"
+    - zip -r source.zip $BUNDLE_PATHS
+    - aws s3 cp source.zip "s3://${bucket}/source.zip"`;
+}
+
+export function renderGitlabCi({ cfnDir = 'cfn', branch = 'main', sourceBucket, auth = 'keys', roleArn, region } = {}) {
+  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
+  const isOidc = auth === 'oidc';
+
+  // Host-neutral header framing (D1): "GitLab is the source of truth" holds for
+  // SaaS and self-managed alike — the old "On-Prem" label hid gitlab.com. The
+  // oidc header must NOT carry the stored-key "Required CI/CD variables" block.
+  const header = isOidc
+    ? `# Generated by \`clawform ci init --auth oidc\`. Clawform CI (keyless / OIDC).
+# Model: GitLab (SaaS or self-managed) is the source of truth; AWS runs the
+# pipeline. The protected branch assumes an IAM role via GitLab OIDC — NO stored
+# AWS keys — then uploads a source bundle to S3, which triggers the CodePipeline
+# from templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
+#
+# No AWS access keys are stored. The AWS-side IAM OIDC provider + role are a
+# one-time prerequisite — see the \`clawform ci init\` "Next steps" output for the
+# exact trust policy (issuer gitlab.com, sub-scoped to this project + branch,
+# audience sts.amazonaws.com). OIDC targets gitlab.com; on a self-managed
+# instance re-run with --auth keys.
+# NOTE: do NOT enable CI_DEBUG_TRACE on this job — a trace would print the OIDC
+# JWT ($AWS_ID_TOKEN) as it is written to the token file.`
+    : `# Generated by \`clawform ci init\`. Clawform CI: your Git host is the source of
+# truth; AWS just runs the pipeline. The protected branch uploads a source bundle
+# to S3, which triggers the CodePipeline from templates/cicd-pipeline.yaml
+# (validate -> manual approval -> execute).
+#
+# Required CI/CD variables (Settings -> CI/CD -> Variables), protected + masked:
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
+#     s3:PutObject on the pipeline SourceBucket (or use a runner instance role)
+#   AWS_DEFAULT_REGION                          -> the pipeline's region`;
+
+  // The upload job: keys reads creds from protected CI variables; oidc mints
+  // short-lived creds from ONE assume-role-with-web-identity call (three fields
+  // from one session — two calls would not pair) with the token passed via a file
+  // so it never lands on the process argv (Finding 10). Both keep the full bundle
+  // body and the entrypoint override (amazon/aws-cli's ENTRYPOINT is the aws
+  // binary, so without it the runner cannot start a shell).
+  const uploadJob = isOidc
+    ? `deploy:upload:
+  stage: deploy
+  image:
+    name: amazon/aws-cli:latest
+    entrypoint: [""]
+  id_tokens:
+    AWS_ID_TOKEN:
+      aud: sts.amazonaws.com
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "${branch}"'
+  before_script:
+    - yum install -y -q zip
+  script:
+    # Keyless auth via the AWS web-identity-token-file credential provider: write
+    # the OIDC JWT to a file and point the SDK at it with AWS_ROLE_ARN +
+    # AWS_WEB_IDENTITY_TOKEN_FILE. The CLI assumes the role itself on each call —
+    # no manual STS call to parse, no credentials in the job shell (so nothing to
+    # leak into logs), and the token never appears on a process argv.
+    - export AWS_DEFAULT_REGION=${region}
+    - export AWS_ROLE_ARN="${roleArn}"
+    - export AWS_ROLE_SESSION_NAME="gitlab-clawform-$CI_PIPELINE_ID"
+    - printf '%s' "$AWS_ID_TOKEN" > /tmp/awsclaw-oidc-token
+    - export AWS_WEB_IDENTITY_TOKEN_FILE=/tmp/awsclaw-oidc-token
+${gitlabBundleSteps({ cfnDir, bucket })}`
+    : `deploy:upload:
+  stage: deploy
+  image:
+    name: amazon/aws-cli:latest
+    entrypoint: [""]
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "${branch}"'
+  before_script:
+    - yum install -y -q zip
+  script:
+    # Creds come from the protected CI/CD variables above, injected as env vars.
+${gitlabBundleSteps({ cfnDir, bucket })}`;
+
+  return `${header}
+
+stages:
+  - validate
+  - deploy
+
+# Every merge request: lint the templates. Offline — no AWS credentials needed.
+# NOTE: cfn-lint is the CI *floor*. Local \`clawform validate\` additionally runs
+# cfn-guard (the shipped rules.guard, incl. the Rule #4 retention checks) and
+# cfn-nag — run it before merging; green CI is not the same as a green /validate.
+validate:cfn:
+  stage: validate
+  image: python:3.12-slim
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  cache:
+    key: clawform-pip
+    paths:
+      - .cache/pip
+  script:
+    - pip install --quiet cfn-lint
+    - cfn-lint ${cfnDir}/*.yaml
+
+# Protected branch only: bundle the repo and hand it to the pipeline. CodePipeline
+# re-validates, builds a change-set, and waits for a human to approve in the
+# CodePipeline console before executing (Rule #5 approval gate, off-TTY).
+${uploadJob}
+  # The pipeline takes over from here — approve the change-set in CodePipeline.
+`;
+}
+
+// The bundle-and-upload step body shared by both GitHub auth branches (indented
+// for a `run: |` block). Identical across keys and oidc so the modes stay
+// functionally equivalent past the credential step (D1).
+function githubBundleStep({ cfnDir, bucket }) {
+  return `      - name: Bundle and upload source
+        run: |
+          # Bundle the template dir plus the optional config/params paths that
+          # exist. Built explicitly (no stderr suppression, no || fallback) so a
+          # real zip failure fails the job instead of uploading a partial bundle.
+          BUNDLE_PATHS="${cfnDir}"
+          for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
+          echo "Bundling: $BUNDLE_PATHS"
+          zip -r source.zip $BUNDLE_PATHS
+          aws s3 cp source.zip "s3://${bucket}/source.zip"`;
+}
+
+// Same Git → S3 → CodePipeline model as the GitLab variant, expressed as a
+// GitHub Actions workflow. Pure string builder, unit-tested without I/O.
+export function renderGithubActions({ cfnDir = 'cfn', branch = 'main', sourceBucket, auth = 'keys', roleArn, region } = {}) {
+  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
+  const isOidc = auth === 'oidc';
+
+  // Host-neutral header framing (D1). The oidc header must NOT carry the stored-key
+  // "Required repository secrets" block.
+  const header = isOidc
+    ? `# Generated by \`clawform ci init --provider github --auth oidc\`. Clawform CI
+# (keyless / OIDC). Model: GitHub is the source of truth; AWS runs the pipeline.
+# The protected branch assumes an IAM role via GitHub OIDC — NO stored AWS keys —
+# then uploads a source bundle to S3, which triggers the CodePipeline from
+# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
+#
+# No AWS access keys are stored. The AWS-side IAM OIDC provider + role are a
+# one-time prerequisite — see the \`clawform ci init\` "Next steps" output for the
+# exact trust policy (issuer token.actions.githubusercontent.com, sub-scoped to
+# this repo + branch, audience sts.amazonaws.com).`
+    : `# Generated by \`clawform ci init --provider github\`. Clawform CI: your Git host is
+# the source of truth; AWS just runs the pipeline. The protected branch uploads a
+# source bundle to S3, which triggers the CodePipeline from
+# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
+#
+# Required repository secrets (Settings -> Secrets and variables -> Actions):
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
+#     s3:PutObject on the pipeline SourceBucket
+#   AWS_DEFAULT_REGION                          -> the pipeline's region`;
+
+  // OIDC needs a top-level grant so both jobs' checkout can read the repo; the
+  // token-minting permission is scoped to the upload job only (Finding 6).
+  const topPermissions = isOidc ? `\npermissions:\n  contents: read\n` : '';
+
+  // The upload job: keys pulls creds from repository secrets; oidc grants
+  // id-token:write on THIS job only and lets configure-aws-credentials assume the
+  // role (audience defaults to sts.amazonaws.com — no static keys anywhere).
+  const uploadJob = isOidc
+    ? `  upload:
+    if: github.ref == 'refs/heads/${branch}'
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${roleArn}
+          aws-region: ${region}
+${githubBundleStep({ cfnDir, bucket })}`
+    : `  upload:
+    if: github.ref == 'refs/heads/${branch}'
+    needs: validate
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: \${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_DEFAULT_REGION: \${{ secrets.AWS_DEFAULT_REGION }}
+    steps:
+      - uses: actions/checkout@v4
+${githubBundleStep({ cfnDir, bucket })}`;
+
+  return `${header}
+
+name: clawform-cfn
+
+on:
+  pull_request:
+  push:
+    branches: [ ${branch} ]
+${topPermissions}
+jobs:
+  # Every pull request: lint the templates. Offline — no AWS credentials.
+  # NOTE: cfn-lint is the CI floor. Local \`clawform validate\` additionally runs
+  # cfn-guard (rules.guard, incl. Rule #4 retention) and cfn-nag — green CI is
+  # not the same as a green /validate.
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install --quiet cfn-lint
+      - run: cfn-lint ${cfnDir}/*.yaml
+
+  # Protected branch only: bundle the repo and hand it to the pipeline, which
+  # re-validates, builds a change-set, and waits for a human to approve in the
+  # CodePipeline console before executing (Rule #5 approval gate, off-TTY).
+${uploadJob}
+      # The pipeline takes over from here — approve the change-set in CodePipeline.
+`;
+}
+
+export default async function ciInit({ sourceBucket, cfnDir = 'cfn', branch = 'main', force, projectDir, provider = 'gitlab', auth = 'keys', roleArn, region } = {}) {
+  await assertLicensed({ command: 'ci-init', client: resolveLicenseClient() });
+  const dir = projectDir || process.cwd();
+
+  // Validate the enums in ciInit() itself, not only in commander — a direct
+  // caller must not be able to silently degrade to gitlab/keys on a typo (the old
+  // `provider === 'github'` test did exactly that). Throw BEFORE any mkdir/write
+  // so a bad invocation never lands a file; assertLicensed stays the first call.
+  if (!PROVIDERS.has(provider)) {
+    throw new Error(`Unknown --provider "${provider}". Use one of: gitlab, github.`);
+  }
+  if (!AUTH_MODES.has(auth)) {
+    throw new Error(`Unknown --auth "${auth}". Use one of: keys, oidc.`);
+  }
+
+  // OIDC needs an AWS role to assume and a region for the upload. role-arn is
+  // hard-required (the CLI never creates the role); region falls back to the
+  // project config so a configured repo need not repeat --region. Neither
+  // resolvable → refuse here, before writing, so we never ship a file whose
+  // protected-branch job is green on PRs but fails the moment it merges.
+  if (auth === 'oidc') {
+    if (!roleArn) {
+      throw new Error(
+        '--auth oidc requires --role-arn <arn> (the IAM role the pipeline assumes via OIDC). ' +
+        'The CLI does not create it — see the "Next steps" trust-policy block.',
+      );
+    }
+    region = region || loadProjectConfig({ projectDir: dir }).region;
+    if (!region) {
+      throw new Error(
+        '--auth oidc needs a region: pass --region <name> or set "region" in clawform.config.json.',
+      );
+    }
+  }
+
+  // Provider decides both the rendered content and where it lands. Default is
+  // gitlab so the pre-existing call shape keeps working.
+  const isGithub = provider === 'github';
+  const isOidc = auth === 'oidc';
+  const content = isGithub
+    ? renderGithubActions({ cfnDir, branch, sourceBucket, auth, roleArn, region })
+    : renderGitlabCi({ cfnDir, branch, sourceBucket, auth, roleArn, region });
+
+  const primary = isGithub
+    ? join(dir, '.github', 'workflows', 'clawform-cfn.yml')
+    : join(dir, '.gitlab-ci.yml');
+  const sample = isGithub
+    ? join(dir, '.github', 'workflows', 'clawform-cfn.clawform.yml')
+    : join(dir, '.gitlab-ci.clawform.yml');
+
+  await mkdir(dirname(primary), { recursive: true });
+  const exists = existsSync(primary);
+  // Never clobber an existing pipeline config silently — write a sample alongside
+  // it and let the user merge, unless they explicitly asked to overwrite.
+  const target = exists && !force ? sample : primary;
+  await writeFile(target, content, 'utf8');
+
+  logger.step(`clawform ci init`);
+  if (target === primary) {
+    logger.ok(`Wrote ${target}`);
+  } else {
+    logger.warn(`${primary} already exists — wrote a sample to ${target} instead. Merge it in (or re-run with --force to overwrite).`);
+  }
+
+  logger.info('');
+  logger.info('Next steps:');
+  logger.info('  1. Stand up the pipeline stack FIRST (it creates the SourceBucket this CI uploads to):');
+  logger.info('       clawform deploy templates/cicd-pipeline.yaml <env> \\');
+  logger.info('         --stack-name <env>-<customer>-<project>-pipeline --project <project> \\');
+  logger.info('         --params params/<env>-pipeline.json --capabilities CAPABILITY_NAMED_IAM');
+  logger.info('     The params file must set ALL template parameters: EnvName, CustomerName, ProjectName,');
+  logger.info('     TargetStackName, TemplatePathInBundle, ApprovalEmail, CfnDeployRoleArn');
+  if (cfnDir !== 'cfn') {
+    logger.info(`     — and CfnDirInBundle="${cfnDir}" (you used --cfn-dir, so the pipeline's lint stage must match).`);
+  } else {
+    logger.info('     (CfnDirInBundle defaults to "cfn" and matches this CI file).');
+  }
+  if (!sourceBucket) {
+    logger.warn(`  2. Replace ${BUCKET_PLACEHOLDER} in the generated file with the stack's SourceBucketName output`);
+    logger.info('     (or re-run: clawform ci init --source-bucket <name> --force).');
+  } else {
+    logger.info(`  2. SourceBucket is set to "${sourceBucket}".`);
+  }
+  if (isOidc) {
+    // Keyless: the AWS-side IAM OIDC provider + sub-scoped role are a one-time
+    // prerequisite the CLI cannot create. Emit an exact, copy-paste trust policy.
+    const issuer = isGithub ? 'token.actions.githubusercontent.com' : 'gitlab.com';
+    const sub = isGithub
+      ? `repo:<OWNER>/<REPO>:ref:refs/heads/${branch}`
+      : `project_path:<GROUP>/<PROJECT>:ref_type:branch:ref:${branch}`;
+    logger.info('  3. Create the AWS-side OIDC trust ONCE — the CLI does NOT create it:');
+    logger.info(`       a. IAM → Identity providers → Add provider → OpenID Connect.`);
+    logger.info(`          Provider URL: https://${issuer}   Audience: sts.amazonaws.com`);
+    logger.info(`       b. Give the role ${roleArn} this trust policy (the sub line is what scopes it):`);
+    logger.info('            {');
+    logger.info('              "Effect": "Allow",');
+    logger.info(`              "Principal": { "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/${issuer}" },`);
+    logger.info('              "Action": "sts:AssumeRoleWithWebIdentity",');
+    logger.info('              "Condition": { "StringEquals": {');
+    logger.info(`                "${issuer}:aud": "sts.amazonaws.com",`);
+    logger.info(`                "${issuer}:sub": "${sub}"`);
+    logger.info('              } }');
+    logger.info('            }');
+    logger.warn('          WARNING: an aud-only policy (no sub) trusts EVERY repo/project on the issuer — keep the sub line.');
+    logger.info(`       c. Attach a permissions policy to ${roleArn} allowing s3:PutObject on the SourceBucket.`);
+    if (!isGithub) {
+      logger.info('       Note: OIDC targets gitlab.com only. On a self-managed GitLab, re-run with --auth keys.');
+    }
+    logger.info('     → CUTOVER once the keyless run works: delete the old IAM user access keys and remove the');
+    logger.info('       AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION CI variables/secrets.');
+    logger.info('       Re-running ci init writes a *.clawform sample unless you pass --force to regenerate in place.');
+  } else if (isGithub) {
+    logger.info('  3. In GitHub → Settings → Secrets and variables → Actions, add:');
+    logger.info('       AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (IAM user scoped to s3:PutObject on the bucket),');
+    logger.info('       AWS_DEFAULT_REGION.');
+  } else {
+    logger.info('  3. In GitLab → Settings → CI/CD → Variables, add (protected + masked):');
+    logger.info('       AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (IAM user scoped to s3:PutObject on the bucket),');
+    logger.info('       AWS_DEFAULT_REGION.');
+  }
+  logger.info('  4. Know the pipeline\'s limits: it enforces the Rule #5 SHAPE (changeset → approval → execute)');
+  logger.info('     but NOT the CLI\'s other gates (account guard, legacy-freeze, export-lock, data-resource');
+  logger.info('     retype). The approver MUST open the change-set link and check for Replace on data');
+  logger.info('     resources before approving. Details: templates/cicd-pipeline.yaml header.');
+  logger.info('  5. Older account that still has CodeCommit and prefers a Git mirror? Point GitLab repository');
+  logger.info('     mirroring at a CodeCommit repo and swap the pipeline Source action to CodeCommit — see');
+  logger.info('     the prose header in templates/cicd-pipeline.yaml.');
+}