create-astram-app

The Astram app scaffolder (ADR-0023 §3). Emits a new consumer app that depends on the published, immutable framework (@astram/core, @astram/guard, @astram/sdk) and enforces deny-by-default from the first boot.

Use it

npx create-astram-app my-app
cd my-app
npm install
npm run dev        # boots the app; GET /health → 200, unclassified route → 403

What it emits

A running, framework-enforced NestJS app (the minimal, clean version of examples/example-backend/):

my-app/
├── package.json         depends on @astram/core ^0.1.0, @astram/guard ^0.1.1,
│                        @astram/sdk ^0.1.0 (published ranges — NEVER workspace:*),
│                        plus the NestJS runtime. "private": true.
├── tsconfig.json + tsconfig.build.json
├── vitest.config.ts
├── src/
│   ├── main.ts          bootstraps Nest; loadAppConfig from @astram/guard
│   ├── app.module.ts    imports ShieldModule.forRoot() — the ONE seam
│   ├── health/          @Public health probes + a demo denied route (enforcement proof)
│   └── features/        EMPTY — the developer's editable space
├── test/                enforcement e2e (200 health + 403 unclassified)
├── .astram/guide/       DEVELOPER-OWNED guide layer (ADR-0025) — upgrade-safe, never touched
├── .env.example         config references only (safe defaults; boots with no .env)
├── .gitignore
└── README.md            how to run + how to add features the framework way

Guarantees

• Immutable-core consumption — the emitted package.json uses published semver ranges, never workspace:* and never a source symlink. The framework upgrades via npm update; the app's src/ is never touched.
• Never clobbers — scaffolding into an existing directory only writes files that do NOT already exist. A developer-authored docs/, .astram/guide/, README, or any other file is left exactly as-is (and reported as skipped). astram3's program docs survive scaffolding.
• Runs immediately — npm install && npm run dev boots a framework-enforced app with no further wiring. (A turnkey login/session boilerplate arrives in a later framework release; today the app gives correct-by-default enforcement.)
• Honest — the CLI never prints "not implemented"; it scaffolds a real app and tells you how to run it and add a feature.

Commands (for developing this package)

pnpm --filter create-astram-app build   # tsc → dist/index.js (the CLI)
pnpm --filter create-astram-app test    # vitest — CLI + never-clobber + emitted-shape
pnpm --filter create-astram-app lint