@thejoseki/clawform 2.3.1 → 2.4.0

package/README.md

@@ -1,120 +1,141 @@
-# Clawform
-
-**Safe CloudFormation workflows for Claude Code.**
-
-![The Clawform hook vetoing an aws cloudformation delete-stack, then the safe changeset path](https://clawform.thejoseki.com/assets/clawform-demo.gif)
-
-Claude writes CloudFormation fast — and just as confidently when it's wrong.
-Clawform is the layer between the agent and your AWS account.
-
-It gives Claude the conventions to read before it writes, so templates come out
-named to your standard, tagged, and with retention set on every stateful
-resource. Every AWS change then goes through the `clawform` CLI: create a
-changeset, show you the diff, execute only after you confirm. Destructive
-operations and the stacks you've marked frozen are refused.
-
-CloudFormation only — by design. Not Terraform, not CDK, not Pulumi.
-
-**Try it free for 14 days** — the full kit, email-only checkout, no card:
-<https://clawform.thejoseki.com/?utm_source=npm>. When the trial lapses, `deploy` and
-`rollback` keep working; an expired licence never strands a stack.
-
-## Quickstart (10 minutes)
-
-```bash
-# 1. Install the CLI (adds `clawform` to your PATH)
-npm i -g @thejoseki/clawform
-
-# 2. Activate your key — free 14-day trial or purchase, both from the site
-clawform activate <your-license-key>
-
-# 3. Install the Claude Code plugin — the CLI unpacks it from your activated copy
-clawform init plugin              # --global (default) or --project
-```
-
-Activation claims one of your seat's device slots; free one with
-`clawform deactivate` when you retire a machine. **In CI, do not activate** —
-set `CLAWFORM_LICENSE_KEY` in the environment instead, which validates per-run
-without taking a slot.
-
-Then, **in your own project**:
-
-```bash
-# 4. Create your config — customer, region, accounts, legacy prefixes
-clawform init            # interactive wizard, writes clawform.config.json
-
-# 5. Point Clawform at your AWS profile (per-user, gitignored)
-#    .claude/settings.local.json → env block → AWS_PROFILE
-
-# 6. Cache your account's stacks and exports (run before your first deploy,
-#    and after every successful one)
-clawform sync
-
-# 7. Open Claude Code and scaffold your first stack
-claude
-> /clawform:scaffold-project      # propose architecture + deploy order
-> /clawform:new-stack networking d
-> /clawform:validate cfn/d-acme-networking.yaml
-> /clawform:deploy cfn/d-acme-networking.yaml d
-```
-
-That's a real stack, deployed through a changeset you confirmed.
-
-### Don't know which services you need?
-
-`/clawform:scaffold-project` detects that case and asks a different set of questions —
-about consequences rather than services. *"If this were down for two hours on a Sunday
-night, would anyone lose money?"* rather than *"Fargate or Lambda?"* Every question has an
-**"I'm not sure"** option that states the default it applies and what that default costs.
-
-Your monthly spending ceiling is the first question, and it eliminates candidate
-architectures **before** any design work — so you never spend half an hour agreeing to
-something you cannot pay for. Nothing is priced from memory: figures come from the AWS
-Pricing API, and if one cannot be fetched you are told so instead of being given a guess.
-
-The interview runs in at most three rounds and its answers are written to
-`docs/scaffold/*.json`, so an interrupted session resumes where it stopped rather than
-starting over. **Those files are committed** — that is what makes the design reviewable in
-a pull request — and `requirements.json` contains your spending ceiling and a
-plain-language description of what you are building. On a public repository, decide
-whether you want that before you push.
-
-## Configuration
-
-Clawform reads two files. Neither hardcodes anything about your organization.
-
-| File | Scope | Committed? | Holds |
-|---|---|---|---|
-| `clawform.config.json` | per-project | yes | customer, region, accounts, `legacy_prefixes` |
-| `.claude/settings.local.json` | per-user | no (gitignored) | `AWS_PROFILE`, owner/cost-center overrides |
-
-`clawform init` writes the first one. For CI or scripted bootstrap, set
-`CLAWFORM_INIT_CUSTOMER=… CLAWFORM_INIT_REGION=… clawform init`.
-
-A fresh project with an empty `legacy_prefixes` has no legacy-freeze gate — that
-is correct. Clawform never imposes another project's freeze list on you.
-
-## Requirements
-
-- Node.js ≥ 20 LTS
-- AWS CLI v2
-- Claude Code CLI
-- *(recommended)* `cfn-lint` — `pip install cfn-lint`
-- *(optional)* `cfn-guard` 3.x for Clawform's custom rules
-
-## Links
-
-- **[clawform.thejoseki.com](https://clawform.thejoseki.com)** — the product
-  page: what Clawform does, per-seat pricing, and how to get a license.
-- **[thejoseki.com](https://thejoseki.com)** — Joseki, the vendor behind
-  Clawform. Known-good moves for agentic work.
-
-## License
-
-Commercial, per-seat. One seat per developer; no resale or redistribution.
-Provided **as is**, with no warranty and no liability for AWS charges — you are
-responsible for reviewing every change before it deploys and for your own cloud
-spend. Full terms in the `LICENSE` file.
-
-Clawform is not affiliated with Amazon Web Services, Inc. "AWS" and
-"CloudFormation" are trademarks of Amazon.com, Inc. or its affiliates.
+# Clawform
+
+**Safe CloudFormation workflows for Claude Code.**
+
+![The Clawform hook vetoing an aws cloudformation delete-stack, then the safe changeset path](https://clawform.thejoseki.com/assets/clawform-demo.gif)
+
+Claude writes CloudFormation fast — and just as confidently when it's wrong.
+Clawform is the layer between the agent and your AWS account.
+
+It gives Claude the conventions to read before it writes, so templates come out
+named to your standard, tagged, and with retention set on every stateful
+resource. Every AWS change then goes through the `clawform` CLI: create a
+changeset, show you the diff, execute only after you confirm. Destructive
+operations and the stacks you've marked frozen are refused.
+
+CloudFormation only — by design. Not Terraform, not CDK, not Pulumi.
+
+**Try it free for 14 days** — the full kit, email-only checkout, no card:
+<https://clawform.thejoseki.com/?utm_source=npm>. When the trial lapses, `deploy` and
+`rollback` keep working; an expired licence never strands a stack.
+
+## Quickstart (10 minutes)
+
+```bash
+# 1. Install the CLI (adds `clawform` to your PATH)
+npm i -g @thejoseki/clawform
+
+# 2. Activate your key — free 14-day trial or purchase, both from the site
+clawform activate <your-license-key>
+
+# 3. Install the Claude Code plugin — the CLI unpacks it from your activated copy
+clawform init plugin              # --global (default) or --project
+```
+
+Activation claims one of your seat's device slots; free one with
+`clawform deactivate` when you retire a machine (re-activating the same machine
+re-adopts its existing slot — it does not take a second). **In CI, do not
+activate** — set `CLAWFORM_LICENSE_KEY` in the environment instead, which
+validates per-run without taking a slot.
+
+Upgrading later? After `npm i -g @thejoseki/clawform@latest`, run
+`clawform update` to pull the newest skills (it force-refreshes the plugin kit),
+then restart Claude Code.
+
+Then, **in your own project**:
+
+```bash
+# 4. Create your config — customer, region, accounts, legacy prefixes
+clawform init            # interactive wizard, writes clawform.config.json
+
+# 5. Point Clawform at your AWS profile (per-user, gitignored)
+#    .claude/settings.local.json → env block → AWS_PROFILE
+
+# 6. Cache your account's stacks and exports (run before your first deploy,
+#    and after every successful one)
+clawform sync
+
+# 7. Open Claude Code and scaffold your first stack
+claude
+> /clawform:scaffold-project      # propose architecture + deploy order
+> /clawform:new-stack networking d
+> /clawform:validate cfn/d-acme-networking.yaml
+> /clawform:deploy cfn/d-acme-networking.yaml d
+```
+
+That's a real stack, deployed through a changeset you confirmed.
+
+### Don't know which services you need?
+
+`/clawform:scaffold-project` detects that case and asks a different set of questions —
+about consequences rather than services. *"If this were down for two hours on a Sunday
+night, would anyone lose money?"* rather than *"Fargate or Lambda?"* Every question has an
+**"I'm not sure"** option that states the default it applies and what that default costs.
+
+Your monthly spending ceiling is the first question, and it eliminates candidate
+architectures **before** any design work — so you never spend half an hour agreeing to
+something you cannot pay for. Nothing is priced from memory: figures come from the AWS
+Pricing API, and if one cannot be fetched you are told so instead of being given a guess.
+
+The interview runs in at most three rounds and its answers are written to
+`docs/scaffold/*.json`, so an interrupted session resumes where it stopped rather than
+starting over. **Those files are committed** — that is what makes the design reviewable in
+a pull request — and `requirements.json` contains your spending ceiling and a
+plain-language description of what you are building. On a public repository, decide
+whether you want that before you push.
+
+## Configuration
+
+Clawform reads two files. Neither hardcodes anything about your organization.
+
+| File | Scope | Committed? | Holds |
+|---|---|---|---|
+| `clawform.config.json` | per-project | yes | customer, region, accounts, `legacy_prefixes` |
+| `.claude/settings.local.json` | per-user | no (gitignored) | `AWS_PROFILE`, owner/cost-center overrides |
+
+`clawform init` writes the first one. For CI or scripted bootstrap, set
+`CLAWFORM_INIT_CUSTOMER=… CLAWFORM_INIT_REGION=… clawform init`.
+
+A fresh project with an empty `legacy_prefixes` has no legacy-freeze gate — that
+is correct. Clawform never imposes another project's freeze list on you.
+
+## CI/CD
+
+`clawform ci init` generates a GitHub Actions workflow or a GitLab CI config that
+lints your templates and, on the protected branch, hands a source bundle to the
+`cicd-pipeline` archetype's CodePipeline (validate → manual approval → execute).
+
+- `--provider gitlab | github` — your Git host (SaaS or self-managed).
+- `--auth keys | oidc` — `keys` (default) stores IAM access keys as CI secrets;
+  `--auth oidc` is keyless — the job assumes an IAM role through the host's OIDC
+  issuer (GitHub or GitLab SaaS) and uses short-lived credentials, so there are
+  no AWS keys to store. OIDC needs a `--role-arn` and a one-time AWS-side trust
+  policy you own; a self-managed GitLab uses `--auth keys`.
+
+Full trust-policy setup and the keys→OIDC cutover are in the runbook
+(`docs/runbook.md`, bundled with the plugin).
+
+## Requirements
+
+- Node.js ≥ 20 LTS
+- AWS CLI v2
+- Claude Code CLI
+- *(recommended)* `cfn-lint` — `pip install cfn-lint`
+- *(optional)* `cfn-guard` 3.x for Clawform's custom rules
+
+## Links
+
+- **[clawform.thejoseki.com](https://clawform.thejoseki.com)** — the product
+  page: what Clawform does, per-seat pricing, and how to get a license.
+- **[thejoseki.com](https://thejoseki.com)** — Joseki, the vendor behind
+  Clawform. Known-good moves for agentic work.
+
+## License
+
+Commercial, per-seat. One seat per developer; no resale or redistribution.
+Provided **as is**, with no warranty and no liability for AWS charges — you are
+responsible for reviewing every change before it deploys and for your own cloud
+spend. Full terms in the `LICENSE` file.
+
+Clawform is not affiliated with Amazon Web Services, Inc. "AWS" and
+"CloudFormation" are trademarks of Amazon.com, Inc. or its affiliates.

package/bin/clawform.js

@@ -1,151 +1,161 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import { readLicense } from '../src/lib/license-store.js';
-import { versionWatermark } from '../src/lib/watermark.js';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { logger } from '../src/lib/logger.js';
-import pkg from '../package.json' with { type: 'json' };
-
-// Inject .claude/settings.local.json env block into process.env before any
-// command runs. Claude Code applies this env to its own tool invocations,
-// but when the CLI is spawned via Bash (or run directly) it must self-load.
-loadSettingsEnv(process.cwd());
-
-function loadSettingsEnv(cwd) {
-  const path = join(cwd, '.claude', 'settings.local.json');
-  if (!existsSync(path)) return;
-  try {
-    const settings = JSON.parse(readFileSync(path, 'utf8'));
-    for (const [k, v] of Object.entries(settings.env ?? {})) {
-      if (!process.env[k] && typeof v === 'string') process.env[k] = v;
-    }
-  } catch {
-    // Silent — loadConfig() will surface missing creds with an actionable message.
-  }
-}
-
-const program = new Command();
-
-program
-  .name('clawform')
-  .description('Clawform — safe CloudFormation workflows for Claude Code')
-  // Version carries the ownership watermark (holder + key suffix) so a shared
-  // install names its source. readLicense fails open, so this never throws.
-  .version(pkg.version + versionWatermark(readLicense()), '-v, --version');
-
-const lazy = (mod) => async (...args) => {
-  const { default: handler } = await import(`../src/commands/${mod}.js`);
-  return runSafe(() => handler(...args));
-};
-
-const init = program
-  .command('init')
-  .description('Scaffold a new AWS project (greenfield wizard). Non-interactive when CLAWFORM_INIT_* env vars are set.')
-  .option('--force', 'Overwrite an existing clawform.config.json')
-  .action(async (opts) => lazy('init')(opts));
-
-init
-  .command('plugin')
-  .description('Install the Clawform Claude Code plugin (decrypts the bundled content; requires an active license once enforcement is on)')
-  .option('--global', 'Install for all projects (~/.claude) — default')
-  .option('--project', 'Install for the current project only (./.claude)')
-  .action(async (opts) => lazy('init-plugin')({ scope: opts.project ? 'project' : 'global' }));
-
-program
-  .command('sync')
-  .description('Refresh outputs-catalog.md and stacks-inventory.md from live AWS')
-  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
-  .option('--region <name>', 'AWS region (overrides .claude/settings.local.json env block)')
-  .action(async (opts) => lazy('sync')(opts));
-
-program
-  .command('validate <file>')
-  .description('Run cfn-lint, cfn-guard (rules.guard + lint-overrides), cfn-nag, and CloudFormation ValidateTemplate on a YAML template')
-  .option('--skip-aws', 'Skip the live ValidateTemplate call (CI / fresh box without AWS creds)')
-  .action(async (file, opts) => lazy('validate')({ file, ...opts }));
-
-program
-  .command('deploy <file> <env>')
-  .description('Deploy a template to <env> via CloudFormation changeset (create → confirm → execute)')
-  .requiredOption('--stack-name <name>', 'CFN stack name (e.g., d-acme-clawtest-fanout)')
-  .requiredOption('--project <name>', 'Project shortname for Project tag (e.g., clawtest)')
-  .option('--params <path>', 'JSON file: [{ParameterKey, ParameterValue}, ...]')
-  .option('--capabilities <list>', 'Comma-separated: CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND')
-  .option('--auto-approve', 'Skip confirmation (refused on Replace or data-resource removal)')
-  .action(async (file, env, opts) => lazy('deploy')({ file, env, ...opts }));
-
-program
-  .command('diff <stack>')
-  .description('Diff local template vs live stack')
-  .option('--file <path>', 'Local template file (defaults to cfn/<stack>.yaml)')
-  .action(async (stack, opts) => lazy('diff')({ stack, ...opts }));
-
-program
-  .command('rollback <stack>')
-  .description('Recover a stack stuck in CREATE_FAILED / UPDATE_ROLLBACK_FAILED')
-  .action(async (stack, opts) => lazy('rollback')({ stack, ...opts }));
-
-program
-  .command('drift <stack>')
-  .description('Detect configuration drift on a deployed stack')
-  .action(async (stack, opts) => lazy('drift')({ stack, ...opts }));
-
-program
-  .command('status')
-  .description('Day-2 health board: per-project stack status, last deploy, last-known drift, monitoring gap')
-  .option('--project <name>', 'Project shortname to filter to (default: all)')
-  .option('--env <env>', 'Env to filter to (d | stg | p)')
-  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
-  .option('--region <name>', 'AWS region (overrides .claude/settings.local.json env block)')
-  .action(async (opts) => lazy('status')(opts));
-
-program
-  .command('activate <key>')
-  .description('Activate a license key on this machine (one activation slot; CI should use CLAWFORM_LICENSE_KEY instead)')
-  .action(async (key) => lazy('activate')({ key }));
-
-program
-  .command('license')
-  .description('Show license status on this machine. --check exits 1 when unlicensed (for scripts/skills)')
-  .option('--check', 'Silent success when active; exit 1 when not')
-  .action(async (opts) => lazy('license-status')(opts));
-
-program
-  .command('deactivate')
-  .description('Release this machine\'s activation slot and clear the local license')
-  .action(async () => lazy('deactivate')({}));
-
-program
-  .command('cost-report')
-  .description('Month-to-date AWS spend grouped by Project / Env / CostCenter tag (or service) via Cost Explorer')
-  .option('--month <YYYY-MM>', 'Month to report (defaults to the current month, month-to-date)')
-  .option('--group-by <key>', 'project | env | costcenter | service', 'project')
-  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
-  .action(async (opts) => lazy('cost-report')(opts));
-
-const ci = program
-  .command('ci')
-  .description('CI/CD scaffolding for the GitLab On-Prem → CodePipeline model');
-
-ci
-  .command('init')
-  .description('Generate CI config: cfn-lint on every MR/PR, upload source.zip to the pipeline bucket on the protected branch')
-  .option('--provider <name>', 'gitlab | github', 'gitlab')
-  .option('--source-bucket <name>', 'Pipeline SourceBucket name (the cicd-pipeline stack\'s SourceBucketName output)')
-  .option('--cfn-dir <dir>', 'Directory holding cfn templates', 'cfn')
-  .option('--branch <name>', 'Protected branch that triggers the deploy upload', 'main')
-  .option('--force', 'Overwrite an existing CI config')
-  .action(async (opts) => lazy('ci-init')({ provider: opts.provider, sourceBucket: opts.sourceBucket, cfnDir: opts.cfnDir, branch: opts.branch, force: opts.force }));
-
-async function runSafe(fn) {
-  try {
-    await fn();
-  } catch (err) {
-    logger.error(err.message || String(err));
-    if (process.env.CLAWFORM_DEBUG) console.error(err.stack);
-    process.exit(1);
-  }
-}
-
-program.parseAsync(process.argv);
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { readLicense } from '../src/lib/license-store.js';
+import { versionWatermark } from '../src/lib/watermark.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../src/lib/logger.js';
+import pkg from '../package.json' with { type: 'json' };
+
+// Inject .claude/settings.local.json env block into process.env before any
+// command runs. Claude Code applies this env to its own tool invocations,
+// but when the CLI is spawned via Bash (or run directly) it must self-load.
+loadSettingsEnv(process.cwd());
+
+function loadSettingsEnv(cwd) {
+  const path = join(cwd, '.claude', 'settings.local.json');
+  if (!existsSync(path)) return;
+  try {
+    const settings = JSON.parse(readFileSync(path, 'utf8'));
+    for (const [k, v] of Object.entries(settings.env ?? {})) {
+      if (!process.env[k] && typeof v === 'string') process.env[k] = v;
+    }
+  } catch {
+    // Silent — loadConfig() will surface missing creds with an actionable message.
+  }
+}
+
+const program = new Command();
+
+program
+  .name('clawform')
+  .description('Clawform — safe CloudFormation workflows for Claude Code')
+  // Version carries the ownership watermark (holder + key suffix) so a shared
+  // install names its source. readLicense fails open, so this never throws.
+  .version(pkg.version + versionWatermark(readLicense()), '-v, --version');
+
+const lazy = (mod) => async (...args) => {
+  const { default: handler } = await import(`../src/commands/${mod}.js`);
+  return runSafe(() => handler(...args));
+};
+
+const init = program
+  .command('init')
+  .description('Scaffold a new AWS project (greenfield wizard). Non-interactive when CLAWFORM_INIT_* env vars are set.')
+  .option('--force', 'Overwrite an existing clawform.config.json')
+  .action(async (opts) => lazy('init')(opts));
+
+init
+  .command('plugin')
+  .description('Install the Clawform Claude Code plugin (decrypts the bundled content; requires an active license once enforcement is on)')
+  .option('--global', 'Install for all projects (~/.claude) — default')
+  .option('--project', 'Install for the current project only (./.claude)')
+  .option('--refresh', 'Re-fetch the plugin kit from the service, ignoring the local cache (gets the newest skills)')
+  .action(async (opts) => lazy('init-plugin')({ scope: opts.project ? 'project' : 'global', refresh: Boolean(opts.refresh) }));
+
+program
+  .command('update')
+  .description('Refresh the installed plugin to the newest skills/commands (force re-fetches the kit) and remind you to update the CLI')
+  .option('--project', 'Refresh the project-scoped install (./.claude) instead of global')
+  .action(async (opts) => lazy('update')({ scope: opts.project ? 'project' : 'global' }));
+
+program
+  .command('sync')
+  .description('Refresh outputs-catalog.md and stacks-inventory.md from live AWS')
+  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
+  .option('--region <name>', 'AWS region (overrides .claude/settings.local.json env block)')
+  .action(async (opts) => lazy('sync')(opts));
+
+program
+  .command('validate <file>')
+  .description('Run cfn-lint, cfn-guard (rules.guard + lint-overrides), cfn-nag, and CloudFormation ValidateTemplate on a YAML template')
+  .option('--skip-aws', 'Skip the live ValidateTemplate call (CI / fresh box without AWS creds)')
+  .action(async (file, opts) => lazy('validate')({ file, ...opts }));
+
+program
+  .command('deploy <file> <env>')
+  .description('Deploy a template to <env> via CloudFormation changeset (create → confirm → execute)')
+  .requiredOption('--stack-name <name>', 'CFN stack name (e.g., d-acme-clawtest-fanout)')
+  .requiredOption('--project <name>', 'Project shortname for Project tag (e.g., clawtest)')
+  .option('--params <path>', 'JSON file: [{ParameterKey, ParameterValue}, ...]')
+  .option('--capabilities <list>', 'Comma-separated: CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND')
+  .option('--auto-approve', 'Skip confirmation (refused on Replace or data-resource removal)')
+  .action(async (file, env, opts) => lazy('deploy')({ file, env, ...opts }));
+
+program
+  .command('diff <stack>')
+  .description('Diff local template vs live stack')
+  .option('--file <path>', 'Local template file (defaults to cfn/<stack>.yaml)')
+  .action(async (stack, opts) => lazy('diff')({ stack, ...opts }));
+
+program
+  .command('rollback <stack>')
+  .description('Recover a stack stuck in CREATE_FAILED / UPDATE_ROLLBACK_FAILED')
+  .action(async (stack, opts) => lazy('rollback')({ stack, ...opts }));
+
+program
+  .command('drift <stack>')
+  .description('Detect configuration drift on a deployed stack')
+  .action(async (stack, opts) => lazy('drift')({ stack, ...opts }));
+
+program
+  .command('status')
+  .description('Day-2 health board: per-project stack status, last deploy, last-known drift, monitoring gap')
+  .option('--project <name>', 'Project shortname to filter to (default: all)')
+  .option('--env <env>', 'Env to filter to (d | stg | p)')
+  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
+  .option('--region <name>', 'AWS region (overrides .claude/settings.local.json env block)')
+  .action(async (opts) => lazy('status')(opts));
+
+program
+  .command('activate <key>')
+  .description('Activate a license key on this machine (one activation slot; CI should use CLAWFORM_LICENSE_KEY instead)')
+  .action(async (key) => lazy('activate')({ key }));
+
+program
+  .command('license')
+  .description('Show license status on this machine. --check exits 1 when unlicensed (for scripts/skills)')
+  .option('--check', 'Silent success when active; exit 1 when not')
+  .action(async (opts) => lazy('license-status')(opts));
+
+program
+  .command('deactivate')
+  .description('Release this machine\'s activation slot and clear the local license')
+  .action(async () => lazy('deactivate')({}));
+
+program
+  .command('cost-report')
+  .description('Month-to-date AWS spend grouped by Project / Env / CostCenter tag (or service) via Cost Explorer')
+  .option('--month <YYYY-MM>', 'Month to report (defaults to the current month, month-to-date)')
+  .option('--group-by <key>', 'project | env | costcenter | service', 'project')
+  .option('--profile <name>', 'AWS profile (overrides .claude/settings.local.json env block)')
+  .action(async (opts) => lazy('cost-report')(opts));
+
+const ci = program
+  .command('ci')
+  .description('CI/CD scaffolding: bundle the repo to the pipeline SourceBucket on the protected branch (GitHub or GitLab, SaaS or self-managed)');
+
+ci
+  .command('init')
+  .description('Generate CI config (GitHub Actions or GitLab CI): cfn-lint on every MR/PR, then upload source.zip to the pipeline bucket on the protected branch. Creds via stored IAM keys or keyless OIDC (--auth)')
+  .addOption(new Option('--provider <name>', 'Git host').choices(['gitlab', 'github']).default('gitlab'))
+  .addOption(new Option('--auth <mode>', 'keys (stored IAM keys, default) | oidc (keyless, github.com/gitlab.com)').choices(['keys', 'oidc']).default('keys'))
+  .option('--role-arn <arn>', 'IAM role to assume via OIDC (required with --auth oidc)')
+  .option('--region <name>', 'AWS region for the upload (--auth oidc; defaults to clawform.config.json region)')
+  .option('--source-bucket <name>', 'Pipeline SourceBucket name (the cicd-pipeline stack\'s SourceBucketName output)')
+  .option('--cfn-dir <dir>', 'Directory holding cfn templates', 'cfn')
+  .option('--branch <name>', 'Protected branch that triggers the deploy upload', 'main')
+  .option('--force', 'Overwrite an existing CI config')
+  .action(async (opts) => lazy('ci-init')({ provider: opts.provider, auth: opts.auth, roleArn: opts.roleArn, region: opts.region, sourceBucket: opts.sourceBucket, cfnDir: opts.cfnDir, branch: opts.branch, force: opts.force }));
+
+async function runSafe(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    logger.error(err.message || String(err));
+    if (process.env.CLAWFORM_DEBUG) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+program.parseAsync(process.argv);