@thejoseki/clawform 0.0.1 → 2.2.0

package/LICENSE

@@ -1,9 +1,100 @@
+Clawform Commercial License
 Copyright (c) 2026 Joseki. All rights reserved.
 
-This release contains no product — it reserves the package name and prints a
-notice. You may install and run it. You may not redistribute it under this name.
+This is a commercial software license, not an open-source license. By
+installing, copying, or using Clawform ("the Software") you agree to these
+terms. If you do not agree, do not install or use the Software.
 
-Clawform itself is licensed commercially, per seat. Those terms ship with the
-product and are not granted by this package.
+1. GRANT (PER-SEAT)
+
+   Subject to payment and to these terms, Joseki grants you a
+   non-exclusive, non-transferable, revocable license to install and use the
+   Software on a per-seat basis. One seat authorizes use by one individual
+   developer. A team must hold one seat for each developer who uses the
+   Software. Seats are counted per person, not per machine; a single developer
+   may install the Software on more than one machine they personally use.
+
+2. RESTRICTIONS
+
+   You may not:
+     (a) resell, sublicense, rent, lease, or otherwise redistribute the
+         Software or any part of it, whether modified or unmodified;
+     (b) share your copy, license key, or access with anyone who does not hold
+         their own seat;
+     (c) remove or alter this license, copyright notices, or attribution;
+     (d) represent the Software, or anything derived from it, as your own
+         product for distribution.
+
+   Templates the Software generates for your own infrastructure are yours to
+   use; this restriction governs the Software itself, not the CloudFormation
+   output you produce with it.
+
+   WATERMARKING. Your installed copy is watermarked with your licence identity:
+   the plugin content carries your masked account address and licence key
+   suffix, and a `.licensed-to` file records the full details of your seat.
+   This lets a redistributed copy be traced back to the seat it came from. The
+   watermark identifies the licence, and is not used to track your use of the
+   Software.
+
+   DEVICE FINGERPRINT. Activating any licence computes a fingerprint of the
+   machine (a hash of its hostname, platform, architecture, and machine
+   identifier) and uses it as the activation's label, which is how activation
+   slots are counted. For trial licences only, the fingerprint is additionally
+   recorded in a device register operated by Joseki, so that one machine can
+   use one trial. The fingerprint identifies the machine, not you, and is not
+   used to track your use of the Software.
+
+3. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. Joseki does not
+   warrant that the Software's templates, guardrails, or recommendations are
+   correct, safe, secure, complete, or suitable for any particular purpose. You
+   are solely responsible for reviewing every change before it is deployed to
+   AWS.
+
+4. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, JOSEKI SHALL NOT BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR
+   ANY LOSS OF PROFITS, DATA, OR GOODWILL, ARISING OUT OF OR RELATED TO THE
+   SOFTWARE.
+
+   FOR CLARITY, THIS EXCLUSION INCLUDES ANY AWS OR OTHER CLOUD INFRASTRUCTURE
+   CHARGES, COSTS, OR BILLS incurred through use of the Software — including
+   charges resulting from a guardrail that failed to catch a mistake, a
+   template that provisioned more than intended, or any resource created,
+   modified, or left running as a result of the Software. You are responsible
+   for your own cloud spend.
+
+   JOSEKI'S TOTAL AGGREGATE LIABILITY UNDER THIS LICENSE SHALL NOT EXCEED
+   THE AMOUNT YOU ACTUALLY PAID FOR THE SEAT GIVING RISE TO THE CLAIM.
+
+5. NO AFFILIATION
+
+   Clawform is an independent product. It is not affiliated with, endorsed by,
+   sponsored by, or otherwise associated with Amazon Web Services, Inc. or its
+   affiliates. "AWS", "Amazon Web Services", and "CloudFormation" are trademarks
+   of Amazon.com, Inc. or its affiliates, used here only to describe
+   interoperability.
+
+6. THIRD-PARTY COMPONENTS
+
+   The Software depends on third-party open-source packages, each licensed under
+   its own terms. Nothing in this license alters your rights or obligations
+   under those third-party licenses.
+
+7. TERMINATION
+
+   This license terminates automatically if you breach any term. On termination
+   you must stop using and destroy all copies of the Software. Sections 3, 4,
+   and 5 survive termination.
+
+8. GENERAL
+
+   If any provision of this license is held unenforceable, the remaining
+   provisions stay in effect. This license is the entire agreement between you
+   and Joseki regarding the Software.
 
 Contact: support@thejoseki.com

package/README.md

@@ -1,18 +1,95 @@
-# clawform
+# Clawform
 
-**Not released yet.** This package reserves the name.
+**Safe CloudFormation workflows for Claude Code.**
 
-Clawform will be a commercial tool for running AWS CloudFormation safely from
-Claude Code — rules the agent reads before it writes, a CLI that does every AWS
-call through a changeset you confirm, and a hook that vetoes dangerous commands
-before they run.
+Claude writes CloudFormation fast — and just as confidently when it's wrong.
+Clawform is the layer between the agent and your AWS account.
 
-Installing this version gives you a stub that prints a notice. It does not talk
-to AWS, read credentials, or write anything to disk.
+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.
 
-Availability and pricing: **support@thejoseki.com**
+CloudFormation only — by design. Not Terraform, not CDK, not Pulumi.
 
----
+## Quickstart (10 minutes)
+
+```bash
+# 1. Install the CLI (adds `clawform` to your PATH)
+npm i -g @thejoseki/clawform
+
+# 2. Activate your license (the key is in your purchase email)
+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.
+
+## 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.

package/bin/clawform.js

@@ -1,16 +1,151 @@
-#!/usr/bin/env node
-
-// Placeholder release. This package reserves the name; the tool itself is not
-// published yet. Every command prints the same notice rather than failing
-// silently or pretending to work — someone who installed this expected a CLI.
-
-const NOTICE = `
-  Clawform is not released yet.
-
-  This package reserves the name. Installing it does not give you the tool.
-  Nothing here talks to AWS, reads your credentials, or writes to your disk.
-
-  Ask about availability: support@thejoseki.com
-`;
-
-process.stdout.write(NOTICE);
+#!/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);

package/package.json

@@ -1,27 +1,63 @@
 {
   "name": "@thejoseki/clawform",
-  "version": "0.0.1",
+  "version": "2.2.0",
+  "description": "Clawform — safe CloudFormation workflows for Claude Code",
+  "homepage": "https://clawform.thejoseki.com",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Joseki <support@thejoseki.com>",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Clawform — safe CloudFormation workflows for Claude Code. Name reserved; the tool is not released yet.",
-  "license": "SEE LICENSE IN LICENSE",
-  "author": "Joseki <support@thejoseki.com>",
-  "type": "module",
   "bin": {
     "clawform": "bin/clawform.js"
   },
-  "files": [
-    "bin/",
-    "LICENSE"
-  ],
   "engines": {
     "node": ">=20.10"
   },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:eval": "vitest run tests/eval",
+    "lint": "node scripts/lint-content.js",
+    "package": "node scripts/package-plugin.js && node scripts/pack-payload.js",
+    "kit:build": "node scripts/package-plugin.js && node scripts/build-kit-worker.js",
+    "kit:deploy": "npm run kit:build && npm --prefix services/kit-worker run deploy",
+    "prepublishOnly": "node scripts/check-release-mode.js && npm run package",
+    "clean-room": "node scripts/clean-room.js",
+    "e2e": "node scripts/e2e-licensed-install.js",
+    "e2e:trial": "node scripts/e2e-trial.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-cloudformation": "^3.700.0",
+    "@aws-sdk/client-cost-explorer": "^3.1066.0",
+    "@aws-sdk/client-sts": "^3.700.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "diff": "^7.0.0",
+    "execa": "^9.5.0",
+    "inquirer": "^12.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
   "keywords": [
+    "claude-code",
+    "claude",
     "cloudformation",
     "aws",
-    "claude-code",
-    "infrastructure-as-code"
+    "iac",
+    "infrastructure-as-code",
+    "aws-cdk-alternative",
+    "changeset",
+    "cfn-lint",
+    "devops",
+    "guardrails",
+    "ai-agent"
   ]
 }

package/src/aws/catalog.js

@@ -0,0 +1,116 @@
+import { paginateListExports } from '@aws-sdk/client-cloudformation';
+import { ENVS, VISIBILITY_PREFIXES, SERVICE_SHORTNAMES } from '../lib/constants.js';
+
+const ENV_PREFIX_RE = new RegExp(`^(${ENVS.join('|')})-`);
+const VISIBILITY = new Set(VISIBILITY_PREFIXES);
+const SERVICES = new Set(SERVICE_SHORTNAMES);
+
+export function parseExport(name) {
+  const m = ENV_PREFIX_RE.exec(name);
+  if (!m) return { env: null, project: null };
+  const tokens = name.split('-');
+  if (tokens.length < 3) return { env: null, project: null };
+
+  let projectIdx;
+  if (VISIBILITY.has(tokens[2])) projectIdx = 4;       // <env>-<cust>-<pri|pub>-<svc>-<project>
+  else if (SERVICES.has(tokens[2])) projectIdx = 3;     // <env>-<cust>-<svc>-<project>
+  else projectIdx = 2;                                  // <env>-<cust>-<project>-<feature>
+
+  const project = tokens[projectIdx];
+  if (!project) return { env: null, project: null };
+  return { env: m[1], project };
+}
+
+export async function fetchExports(client) {
+  const exports = [];
+  for await (const page of paginateListExports({ client }, {})) {
+    for (const ex of page.Exports ?? []) {
+      exports.push({
+        name: ex.Name,
+        value: ex.Value,
+        exportingStackId: ex.ExportingStackId,
+      });
+    }
+  }
+  return exports;
+}
+
+export function groupExports(exports) {
+  const byProject = new Map();
+  const uncategorized = [];
+  for (const ex of exports) {
+    const { env, project } = parseExport(ex.name);
+    if (!env || !project) {
+      uncategorized.push(ex);
+      continue;
+    }
+    if (!byProject.has(project)) byProject.set(project, new Map());
+    const byEnv = byProject.get(project);
+    if (!byEnv.has(env)) byEnv.set(env, []);
+    byEnv.get(env).push(ex);
+  }
+  return { byProject, uncategorized };
+}
+
+function stackNameOf(exportingStackId) {
+  if (!exportingStackId) return '(unknown)';
+  const parts = exportingStackId.split('/');
+  return parts[1] ?? '(unknown)';
+}
+
+function truncate(s, n) {
+  if (!s) return '';
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+function escapePipe(s) {
+  return String(s ?? '').replace(/\|/g, '\\|');
+}
+
+function renderTable(items) {
+  const lines = [];
+  lines.push('| Export | Value preview | Source stack |');
+  lines.push('|---|---|---|');
+  const sorted = [...items].sort((a, b) => a.name.localeCompare(b.name));
+  for (const it of sorted) {
+    lines.push(
+      `| \`${escapePipe(it.name)}\` | \`${escapePipe(truncate(it.value, 40))}\` | \`${escapePipe(stackNameOf(it.exportingStackId))}\` |`,
+    );
+  }
+  return lines;
+}
+
+export function renderCatalog({ byProject, uncategorized }, meta) {
+  const lines = [
+    '# CloudFormation Outputs Catalog',
+    '',
+    `> Generated by \`clawform sync\` at ${meta.generatedAt}`,
+    `> Account: ${meta.account} · Region: ${meta.region} · ${meta.total} exports`,
+    '',
+  ];
+
+  const projects = [...byProject.keys()].sort();
+  for (const project of projects) {
+    lines.push(`## Project: ${project}`, '');
+    const envs = [...byProject.get(project).keys()].sort();
+    for (const env of envs) {
+      lines.push(`### Env: ${env}`, '');
+      lines.push(...renderTable(byProject.get(project).get(env)));
+      lines.push('');
+    }
+  }
+
+  if (uncategorized.length > 0) {
+    lines.push(
+      `## Uncategorized (non-conforming naming, ${uncategorized.length})`,
+      '',
+      '> Exports that don\'t match `<env>-<customer>-[<pri|pub>-]<service>-<project>-...`.',
+      '> Usually legacy stacks (OLDNET-*, OLDAPP-*) or pre-convention exports (e.g. `d-vpc-acme-billing-id`).',
+      '',
+    );
+    lines.push(...renderTable(uncategorized));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}