ecs-truly-auto-mode - GitLite

KO | EN

gitlite — search

#gemini #electron #awesome-list #monitoring #privacy #http #windows #machine-learning #animation #codex

ecs-truly-auto-mode

(★ 9)

No description available.

File Explorer

ZIP Download

- - build.yml
  - pull-request-lint.yml
  - release.yml
  - upgrade-main.yml
- pull_request_template.md
- deps.json
- files.json
- tasks.json
- adopting-resources.md
- editing-generated-code.md
- getting-started.md
- known-limits.md
- two-stack-model.md
- - Dockerfile
  - expected-manifest.yaml
  - package.json
  - README.md
- - Dockerfile
  - package.json
  - README.md
- - Dockerfile
  - expected-manifest.yaml
  - go.mod
  - go.sum
  - main.go
  - README.md
- - adopted-vpc.manifest.yaml
  - created-certificate.manifest.yaml
  - created-datastores.manifest.yaml
  - created-vpc.manifest.yaml
  - dsql-adopted.manifest.yaml
  - dsql-created.manifest.yaml
  - projen-style.manifest.yaml
- - Dockerfile
  - expected-manifest.yaml
  - package-lock.json
  - package.json
  - README.md
  - tsconfig.json
- - .env.example
  - alembic.ini
  - Dockerfile
  - expected-manifest.yaml
  - poetry.lock
  - pyproject.toml
  - README.md
- config.yaml
- tsconfig.json
- manifest.schema.json
- check-generated.mjs
- derive-path-filter.mjs
- generate-config.mjs
- materialize-skills.mjs
- resume-phase.mjs
- validate-examples.mjs
- validate-manifest.mjs
- verify-fixtures.mjs
- verify-packaging.mjs
- verify-pipeline-equivalence.mjs
- verify-resume.mjs
- verify-styles.mjs
- - skill.json
  - SKILL.md
- cli.ts
- errors.ts
- index.ts
- operations.ts
- paths.ts
- prompt.ts
- selfupdate.ts
- skills.ts
- version.ts
- - cdk.json
  - package-lock.json
  - package.json
  - tsconfig.json
- - .projenrc.ts
- - ssm-preflight.sh
- cli.test.ts
- harness.ts
- tsconfig.json
- units.test.ts
.eslintrc.json
.gitattributes
.gitignore
.mergify.yml
.npmignore
.projenrc.ts
LICENSE
package-lock.json
package.json
README.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A Claude Code skill that takes a repository with a Dockerfile and gets it running
on ECS — by reading the code first, showing you what it inferred, and handing you
CDK you own.

ECS Express Mode automates a narrow happy path and hides the resources it creates.
This does the opposite: it analyzes the actual repository, presents every inference
with the file and line that supports it, asks about anything it isn't sure of, and
generates infrastructure code that keeps working after the skill is gone.

## What it produces

- **A CDK TypeScript app split into two stacks.** A *platform* stack (VPC, cluster,
  ECR, load balancer, roles, logging, DNS) that changes rarely, and a *service*
  stack (task definition and service, nothing else) that changes on every deploy.
  As a plain CDK app or a projen `AwsCdkTypeScriptApp` — your choice, same stacks and
  same synthesized template either way.
- **A CI/CD pipeline** — GitHub Actions or CodePipeline, your choice — triggered on
  push with a path filter derived from what the image build actually reads. It
  builds, pushes to ECR tagged with the commit SHA, and rolls the service stack
  forward.
- **A manifest** (`.ecs-auto-mode/manifest.yaml`) recording every finding and every
  decision, so re-runs are incremental instead of starting over.

## The four phases

**1. Analyze.** Parse the Dockerfile for ports, architecture, and build context.
Scan the source for the HTTP listener and health-check endpoint, for outbound calls
that leave the VPC, for hostnames and candidate domains, for datastores, and for the
environment variables the container reads. Build the image to prove it builds — if
it doesn't, the run stops here.

**2. Plan.** Present every AWS resource the app needs. Each one is either *created*
or *adopted*; adopting means you supply the ID of something you already own. Nothing
is generated until the plan is complete and you've approved it.

**3. Generate infrastructure.** Emit the two CDK stacks from the manifest. They
synthesize without AWS credentials, because adopted resources are imported from
recorded attributes rather than looked up.

**4. Generate the pipeline.** Emit the target you picked, implementing the same
deployment contract either way.

## Two design decisions worth knowing about

**The stacks are coupled through SSM Parameter Store, not CloudFormation exports.**
`Fn::ImportValue` locks the exporting stack — the platform stack could not change a
value while the service stack imported it. That is exactly the wrong coupling to put
between a stack that changes rarely and one that changes constantly. The platform
stack writes its outputs to SSM parameters; the service stack reads them, and can
deploy in a pipeline that has never synthesized the platform stack.

**Whether you get a NAT gateway is a derived decision, with its reasoning shown.**
If the outbound scan finds nothing that leaves the VPC, the service goes in isolated
subnets with interface endpoints for exactly the AWS services it calls, and no NAT.
If something does need the public internet, you get private subnets with NAT — and
the plan names the file and line that forced it. A NAT gateway is the most common
piece of accidental spend in a small ECS setup, so this is stated up front rather
than buried.

## Installing

```bash
npx @matthewbonig/ecs-truly-auto-mode-skill install
```

It asks where to put the skill — `~/.claude/skills` (the default, available in every
project) or `./.claude/skills` (this project only) — and copies it there along with
everything it needs at runtime. Then, from a repository with a Dockerfile, ask Claude
Code to deploy it to ECS.

| | |
| --- | --- |
| `install [skill...]` | Install the named skills, or all of them if none are named |
| `list` | Show what this package ships and what is installed |
| `uninstall <skill...>` | Remove installed skills |
| `update [skill...]` | Update the CLI, then refresh the skills it installed |

| | |
| --- | --- |
| `--user` | `~/.claude/skills` — the default |
| `--project` | `./.claude/skills` |
| `--dir <path>` | An explicit directory |
| `--force` | Replace a skill that is already installed |
| `--dry-run` | Report what would happen and write nothing |

When stdin is not a terminal — piped through a script, or running in CI — nothing is
prompted and the user-global default applies. The resolved destination is printed on
every run either way.

An install never overwrites silently: if the skill is already there, the CLI reports
both versions and stops until you pass `--force`. It writes only inside the skills
directory it resolved, and never touches Claude Code settings or other skills.

## Updating

Every push to `main` publishes a new version, so an installed skill goes stale on its
own. One command brings both the CLI and the skills it installed up to date:

```bash
ecs-truly-auto-mode update
```

If your installed CLI is old enough not to have `update` yet, bootstrap once with:

```bash
npx @matthewbonig/ecs-truly-auto-mode-skill@latest install --force
```

`update` upgrades itself *first*, then refreshes skills using the version it upgraded
to — a skill's version is the package's version, so refreshing from a stale CLI would
copy stale skills and report success. What "upgrade itself" means depends on how the
CLI got onto your machine:

| How it is installed | What `update` does |
| --- | --- |
| Globally (`npm install -g`) | Upgrades the global install, so the next bare `ecs-truly-auto-mode` is current too |
| Through `npx` | Fetches the latest package for this run and changes nothing on your `PATH` |
| As a project dependency | Leaves your `package.json` and lockfile alone — upgrade that copy with your own package manager — and fetches the latest package for the refresh |
| From a checkout of this repository | Nothing: it makes no network call and refreshes from the working tree |

| | |
| --- | --- |
| `--check` | Report what is out of date — the CLI and each skill — and write nothing |
| `--no-self-update` | Refresh from this package only, with no network call |
| `--dry-run` | Print the upgrade it would perform and the directories it would replace |

It also takes `--user`, `--project`, and `--dir <path>`, which mean exactly what they
mean for `install`.

`update` is the only command that makes a network request, and the only one that can
write outside the skills directory — it upgrades its own globally installed package.
`--no-self-update` turns both off. A registry it cannot reach is a warning, not a
failure: it says the check did not happen and refreshes from the package in hand.

Two things it deliberately will not do:

- **It never replaces a skill directory it did not install.** A directory with no
  install record from this package is reported and left alone, and `--force` does not
  change that. `install --force` is where an explicit overwrite belongs.
- **It never adds a skill that is not installed.** `update` refreshes; `install` adds.
  A target with nothing installed reports that and exits zero.

Updating replaces the whole skill directory, so anything you edited by hand inside an
installed skill does not survive it. Keep local changes outside the skill directory.

### Installing by hand

If you would rather not use the CLI, copy the skill and the assets it references:

```bash
cp -r skills/ecs-truly-auto-mode ~/.claude/skills/
mkdir -p ~/.claude/skills/ecs-truly-auto-mode/assets
cp -r templates ~/.claude/skills/ecs-truly-auto-mode/assets/templates
cp -r schemas   ~/.claude/skills/ecs-truly-auto-mode/assets/schemas
```

The two `assets` copies are not optional. `SKILL.md` refers to the CDK sources and the
manifest schema as `./assets/...`, so a skill copied without them analyzes and plans
correctly and then has nothing to generate from.

> **Breaking change.** Those paths used to be repo-relative (`templates/cdk/`), which
> never resolved once the skill was copied out of this repository. If you installed the
> skill by hand before this change and worked around the missing templates, re-install.

## Requirements

- Docker, for the build-validation step
- Node.js and AWS CDK v2, for the generated app
- AWS credentials with permission to deploy the platform stack

## What it does not do

- Fix an app that doesn't containerize. If `docker build` fails it reports the error
  and stops; it does not rewrite your Dockerfile or your app.
- Manage adopted resources. Point it at an existing database and it wires
  connectivity and permissions, and never touches the database itself.
- Multi-region, multi-account, EKS, or non-container compute.

## Repository layout

| Path | Contents |
| --- | --- |
| `skills/ecs-truly-auto-mode/` | The skill package — `SKILL.md`, its references, and `skill.json` |
| `templates/` | CDK stacks and pipeline definitions the skill emits |
| `schemas/` | JSON Schema for the manifest |
| `src/` | The installer CLI |
| `test/` | CLI tests |
| `scripts/` | Validation tooling |
| `examples/` | Fixture applications exercising each analysis path |
| `openspec/` | Change proposals, specs, and design docs |
| `.projenrc.ts` | Project definition — the source of truth for all generated config |

`templates/` and `schemas/` live at the repository root but ship *inside* an installed
skill, as `assets/templates` and `assets/schemas`. Each skill declares what it needs in
its `skill.json`, and the CLI does the copy at install time. They are not committed
under the skill because `templates/` is live source that the fixture suite synthesizes
from — a second committed copy would drift from it.

## Documentation

| | |
| --- | --- |
| [Getting started](docs/getting-started.md) | One app from invocation to a running service |
| [The two-stack model](docs/two-stack-model.md) | Why the split, and why SSM instead of CloudFormation exports |
| [Adopting resources](docs/adopting-resources.md) | What identifiers each resource needs, and what is adopt-only |
| [Editing generated code](docs/editing-generated-code.md) | The overwrite check, and when to change the manifest instead |
| [Known limits](docs/known-limits.md) | How the analysis can be wrong, and what is out of scope |

## Development

```bash
npm install
npx projen build   # compile, lint, and the full suite
npm test           # the suite on its own
```

The suite runs the CLI tests, 22 manifest-corruption checks, 13 pipeline-equivalence
properties, 5 infrastructure-style equivalence properties, 20 resume/incremental
checks, 34 fixture assertions that synthesize real CloudFormation and assert on what
came out, and a packaging check.

The packaging check is the one worth knowing about: it packs the real tarball, installs
from it into a temporary directory using the packed CLI, and then resolves every
relative path the installed `SKILL.md` and reference documents point at. A missing
ignore rule, a wrong `skill.json`, or a stale path in a document all fail there rather
than reaching someone's machine.

Two things about `verify:fixtures`: it needs `templates/cdk` dependencies installed
(`cd templates/cdk && npm ci`), and it needs Docker for the fixtures that build.

While working on a skill in this repository, its own `./assets/...` paths do not
resolve, because assets are copied in at install time. To make them resolve locally:

```bash
npx projen skills:materialize   # writes skills/*/assets, which is gitignored
```

### This repository is managed by projen

`package.json`, `tsconfig.json`, `.gitignore`, `.npmignore`, and everything under
`.github/workflows/` are **generated**. Edit `.projenrc.ts` and run `npx projen`; edits
made directly to a generated file are overwritten on the next synth, and CI fails on
the difference rather than letting it through.

### Releases

Merging to `main` publishes. The workflow computes the next version from git history,
runs the full suite, publishes to npm with a provenance attestation, and pushes a tag
and a GitHub release. It does not commit anything back to `main` — the version in
`package.json` stays `0.0.0` and the real version lives in the tag, so there is no
version to bump in a pull request.

Because the bump size comes from commit messages, PR titles are linted as conventional
commits: a `feat:` title produces a minor release, anything else a patch.

Two prerequisites, neither of which the workflow can solve for itself:

- **A trusted publisher configured on npm** — publishing uses OIDC trusted publishing,
  so there is no `NPM_TOKEN`.
- **A public repository.** npm provenance requires one; on a private repository the
  publish fails until `npmProvenance: false` is set in `.projenrc.ts`.

To verify without publishing, run the **release** workflow from the Actions tab with
**Dry run** ticked.

#### Why the first release needed a tag

projen bumps `none` when there is no prior git tag — see `isFirstRelease` in its
`bump-version` logic — and would have published the `0.0.0` placeholder rather than a
version derived from commit messages. A `v0.0.0` tag was created on the commit
preceding the CLI work to give the workflow a baseline, so the first real release
counts those commits and lands on `0.1.0`. Conventional-commit bumping behaves
normally from there on.

## License

MIT