create-astram-app 0.1.0 → 0.1.2

package/README.md

@@ -1,28 +1,61 @@
 # create-astram-app
 
-**STUB (ADR-0023 §3)** — the Astram app scaffolder. `private`, not implemented in
-this layer (Rule of Three, ADR-0023 §7 — don't over-build the scaffolder before
-it's needed).
+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.
 
-## Intent
+## Use it
 
 ```bash
 npx create-astram-app my-app
+cd my-app
+npm install
+npm run dev        # boots the app; GET /health → 200, unclassified route → 403
 ```
 
-will emit a consumer app **skeleton** (a scaffolded app skeleton that depends on
-the published framework package) — generated from this package's
-`template/` — whose `package.json` depends on the published `@astram/core` +
-`@astram/guard`. The consumer builds features in the scaffolded `src/`, declaring
-Astram through the ONE seam `ShieldModule.forRoot(...)`. Framework upgrades flow
-through the dependency (`npm update`), never by re-cloning the skeleton.
+## What it emits
 
-The CLI currently prints a stub notice and exits non-zero (nothing is scaffolded).
-The canonical shape of the emitted skeleton is [`examples/example-backend/`](../examples/example-backend/).
+A running, framework-**enforced** NestJS app (the minimal, clean version of
+[`examples/example-backend/`](../examples/example-backend/)):
 
-## Commands
+```
+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)
 
 ```bash
-pnpm --filter create-astram-app build   # tsc → dist/index.js (the CLI stub)
+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
 ```

package/dist/index.js

@@ -1,46 +1,196 @@
 #!/usr/bin/env node
 /**
- * `create-astram-app` — the Shield scaffolder (ADR-0023 §3).
+ * `create-astram-app` — the Astram app scaffolder (ADR-0023 §3).
  *
- * ┌─────────────────────────────────────────────────────────────────────────┐
- * │ STUB — NOT IMPLEMENTED IN THIS LAYER.                                     │
- * │ This is a deliberate placeholder (Rule of Three, ADR-0023 §7): the       │
- * │ scaffolder is not built before it is needed. A later layer replaces the  │
- * │ body below with the real copy-from-template + install flow.              │
- * └─────────────────────────────────────────────────────────────────────────┘
+ *   npx create-astram-app <name>
  *
- * INTENT (what the finished tool will do):
+ * Emits a NEW consumer app directory that depends on the published, immutable
+ * framework packages (`@astram/core`, `@astram/guard`, `@astram/sdk`) via real
+ * semver ranges — never `workspace:*`, never a source symlink. The developer
+ * builds features in the emitted `src/features/`; the framework lives read-only
+ * in `node_modules` and upgrades through `npm update`.
  *
- *   npx create-astram-app my-app
+ * What the emitted app IS today (honest scope — Phase 0a):
+ *   A running, framework-ENFORCED NestJS app. `ShieldModule.forRoot()` is the ONE
+ *   registration seam: it wires the global deny-by-default guard (ADR-0002), so
+ *   every route is denied unless explicitly classified (`@Public()`/`@Classified()`).
+ *   Health probes + a demo route prove enforcement from the consumer's side.
+ *   A turnkey login/session boilerplate arrives in a later framework release — this
+ *   scaffold does NOT emit a fake login route.
  *
- * emits the consumer's editable app SKELETON (a scaffolded app skeleton that
- * depends on the published framework package) — scaffolded from this package's
- * `template/` reference — whose `package.json` depends
- * on the published `@astram/core` + `@astram/guard`. The scaffolded `src/` is
- * where the consumer builds features; its `AppModule` declares Shield through the
- * ONE registration seam, `ShieldModule.forRoot(...)`. Framework upgrades flow
- * through the dependency (`npm update`), never by re-cloning the skeleton.
- *
- * The canonical shape of the emitted skeleton is `packages/nestjs-app/` in this
- * monorepo (the consumer-skeleton reference). See `template/README.md`.
+ * Reference skeleton: `examples/example-backend/` in the astram-framework repo.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/** Token substituted with the app name at copy time (in package.json name, README title, …). */
+const APP_NAME_TOKEN = '__APP_NAME__';
+/** Directory (inside the published package) that holds the emitted app template. */
+function templateDir() {
+    // dist/index.js → ../template (bundled via the package's `files` field).
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '..', 'template');
+}
+/**
+ * Validate a requested app name: non-empty, safe as a single directory segment,
+ * no path traversal / separators / leading dot. Returns an error string or null.
  */
-const STUB_MESSAGE = [
-    'create-astram-app is a STUB (ADR-0023 §3) — not implemented in this layer.',
+export function validateAppName(name) {
+    if (!name || name.trim().length === 0) {
+        return 'an app name is required';
+    }
+    const trimmed = name.trim();
+    if (trimmed !== name) {
+        return `app name must not have leading/trailing whitespace: "${name}"`;
+    }
+    if (trimmed === '.' || trimmed === '..') {
+        return `app name must not be "." or ".."`;
+    }
+    if (/[/\\]/.test(trimmed)) {
+        return `app name must be a single directory name (no "/" or "\\"): "${name}"`;
+    }
+    if (trimmed.startsWith('.')) {
+        return `app name must not start with a dot: "${name}"`;
+    }
+    // Conservative, npm-friendly directory segment.
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        return `app name may only contain letters, numbers, ".", "_", and "-": "${name}"`;
+    }
+    return null;
+}
+const USAGE = [
+    'Usage: create-astram-app <name>',
     '',
-    'When built, it will scaffold a consumer app skeleton (a scaffolded app',
-    'skeleton that depends on the published framework package) depending on',
-    '@astram/core + @astram/guard, whose AppModule declares',
-    'Shield via ShieldModule.forRoot(...).',
+    'Scaffolds a new Astram consumer app that depends on the published framework',
+    '(@astram/core, @astram/guard, @astram/sdk) and enforces deny-by-default from',
+    'the first boot.',
     '',
-    'Reference skeleton: packages/nestjs-app/ · template: this package’s template/.',
+    'Example:',
+    '  npx create-astram-app my-app',
 ].join('\n');
-/** Entry point. Prints the stub notice and exits non-zero (nothing scaffolded). */
-export function main() {
-    console.error(STUB_MESSAGE);
-    return 1;
+/**
+ * Recursively copy `srcDir` → `destDir`, substituting {@link APP_NAME_TOKEN} in
+ * text file CONTENTS, and NEVER overwriting a file that already exists at the
+ * destination (spec §3.1 — never clobber developer-authored files). Directories
+ * are created as needed; only missing files are written.
+ *
+ * `relBase` accumulates the path relative to the template root for reporting.
+ */
+function copyTemplate(srcDir, destDir, appName, report, relBase = '') {
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = join(srcDir, entry.name);
+        // Template files that must land under a leading-dot name are stored WITHOUT
+        // the dot so npm/pnpm ship them (npm strips a top-level `.gitignore`, and a
+        // dotfile inside `files` can be filtered). `_gitignore` → `.gitignore`, etc.
+        const destName = entry.name.startsWith('_') ? `.${entry.name.slice(1)}` : entry.name;
+        const destPath = join(destDir, destName);
+        const rel = relBase ? `${relBase}/${destName}` : destName;
+        if (entry.isDirectory()) {
+            copyTemplate(srcPath, destPath, appName, report, rel);
+            continue;
+        }
+        if (existsSync(destPath)) {
+            // Never-clobber: leave the developer's file exactly as-is.
+            report.skipped.push(rel);
+            continue;
+        }
+        const raw = readFileSync(srcPath);
+        if (isTextFile(entry.name)) {
+            const substituted = raw.toString('utf8').split(APP_NAME_TOKEN).join(appName);
+            writeFileSync(destPath, substituted, 'utf8');
+        }
+        else {
+            cpSync(srcPath, destPath);
+        }
+        report.written.push(rel);
+    }
+}
+/** Text extensions that get token substitution + utf8 handling. */
+function isTextFile(fileName) {
+    return /\.(json|ts|js|mjs|cjs|md|txt|example|yml|yaml|gitignore)$/i.test(fileName) || fileName.startsWith('_');
+}
+/**
+ * Scaffold `appName` into `<cwd>/<appName>`. Returns the copy report + resolved
+ * target dir. Exported for tests (which pass an explicit `cwd`).
+ */
+export function scaffold(appName, cwd = process.cwd()) {
+    const targetDir = resolve(cwd, appName);
+    const report = { written: [], skipped: [] };
+    if (existsSync(targetDir)) {
+        const stat = statSync(targetDir);
+        if (!stat.isDirectory()) {
+            throw new Error(`target "${appName}" exists and is not a directory`);
+        }
+        // Existing dir is allowed — copyTemplate skips any file that already exists,
+        // so developer-authored docs/, .astram/guide/, README, etc. survive untouched.
+    }
+    copyTemplate(templateDir(), targetDir, appName, report);
+    return { targetDir, report };
+}
+/** Entry point. Returns a process exit code (0 ok, non-zero on error). */
+export function main(argv = process.argv.slice(2)) {
+    const name = argv[0];
+    const validationError = validateAppName(name);
+    if (validationError) {
+        console.error(`create-astram-app: ${validationError}\n`);
+        console.error(USAGE);
+        return 1;
+    }
+    const appName = name.trim();
+    let report;
+    try {
+        ({ report } = scaffold(appName));
+    }
+    catch (err) {
+        console.error(`create-astram-app: ${err.message}`);
+        return 1;
+    }
+    // Honest, helpful output — no "not implemented" text.
+    console.log(`\nScaffolded a new Astram app in ./${appName}`);
+    console.log(`  ${report.written.length} file(s) written.`);
+    if (report.skipped.length > 0) {
+        console.log(`  ${report.skipped.length} existing file(s) left untouched (never-clobber): ${report.skipped.join(', ')}`);
+    }
+    console.log('\nWhat you got:');
+    console.log('  • A running, framework-ENFORCED NestJS app — every route is denied by');
+    console.log('    default (ADR-0002) unless you classify it with @Public()/@Classified().');
+    console.log('  • The framework installed as immutable dependencies (@astram/core,');
+    console.log('    @astram/guard, @astram/sdk) — you never edit it; upgrade via `npm update`.');
+    console.log('  • An empty src/features/ — your editable space. Add a feature by writing a');
+    console.log('    Nest module/controller there and registering it in src/app.module.ts.');
+    console.log('  • .astram/guide/ — your own, upgrade-safe project-rules space (ADR-0025).');
+    console.log('\n  (A turnkey login/session boilerplate ships in a later framework release;');
+    console.log('   today the app gives you correct-by-default ENFORCEMENT out of the box.)');
+    console.log('\nNext steps:');
+    console.log(`  cd ${appName}`);
+    console.log('  npm install');
+    console.log('  npm run dev        # boots the app; GET /health → 200, unclassified → 403');
+    console.log('');
+    return 0;
+}
+// Run ONLY when this module is the process entry point (i.e. executed as the
+// CLI), NOT when imported by a test. Keyed on the actual entry script rather
+// than NODE_ENV (so a consumer whose shell exports NODE_ENV=test still gets a
+// working CLI). CRITICAL: `npx`/npm run the package through a `bin` SYMLINK, so
+// `process.argv[1]` is the symlink path, not this real dist file — we must
+// resolve it (realpath) before comparing, or `import.meta.url` (the real file)
+// never matches and the CLI silently no-ops. When imported by a test, argv[1]
+// is the test runner, which resolves to a different real file → correctly skips.
+function isInvokedAsCli() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    const thisFile = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(entry) === realpathSync(thisFile);
+    }
+    catch {
+        // If either path can't be realpath'd, fall back to a direct compare.
+        return pathToFileURL(entry).href === import.meta.url;
+    }
 }
-// Only run when invoked as a CLI (not when imported by a test).
-if (process.env.NODE_ENV !== 'test') {
+if (isInvokedAsCli()) {
     process.exitCode = main();
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,YAAY,GAAG;IACnB,4EAA4E;IAC5E,EAAE;IACF,wEAAwE;IACxE,wEAAwE;IACxE,wDAAwD;IACxD,uCAAuC;IACvC,EAAE;IACF,gFAAgF;CACjF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,mFAAmF;AACnF,MAAM,UAAU,IAAI;IAClB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC;AACX,CAAC;AAED,gEAAgE;AAChE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "create-astram-app",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
-  "description": "Scaffolder for a new Astram app — emits a consumer project skeleton (Auth boilerplate + empty src/features/) that installs the sealed @astram/core + @astram/guard framework.",
+  "description": "Scaffolder for a new Astram app — emits a running, framework-enforced consumer project (empty src/features/ + deny-by-default enforcement) that installs the immutable @astram/core, @astram/guard, and @astram/sdk framework.",
   "type": "module",
   "bin": {
     "create-astram-app": "dist/index.js"
@@ -14,14 +14,14 @@
     "dist",
     "template"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "lint": "eslint \"src/**/*.ts\"",
-    "test": "vitest run --passWithNoTests"
-  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run --passWithNoTests"
   }
-}
+}

package/template/README.md

@@ -1,18 +1,89 @@
-# create-astram-app template (reference)
-
-This directory will hold the **app-skeleton template** the scaffolder copies to
-emit a new consumer app (ADR-0023 §3). It is a placeholder in this layer.
-
-Until the scaffolder is built, the **canonical reference for the emitted skeleton
-is [`examples/example-backend/`](../../examples/example-backend/)** in this monorepo — the
-consumer app skeleton (a scaffolded app skeleton that depends on the published
-framework package). A generated app follows it:
-
-- `package.json` depends on `@astram/core` + `@astram/guard` (published), plus the
-  host NestJS runtime (`@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express`,
-  `reflect-metadata`, `rxjs`).
-- `src/app.module.ts` declares Astram via `ShieldModule.forRoot(...)` — the one
-  registration seam — and adds the consumer's feature controllers.
-- `src/main.ts` bootstraps Nest and listens (thin).
-- Feature code lives in the consumer's editable `src/`; the framework is never
-  edited (upgrades flow through `npm update`).
+# __APP_NAME__
+
+An **Astram consumer app**, scaffolded with `create-astram-app`. It depends on the
+published, immutable framework packages ([`@astram/core`](https://www.npmjs.com/package/@astram/core),
+[`@astram/guard`](https://www.npmjs.com/package/@astram/guard),
+[`@astram/sdk`](https://www.npmjs.com/package/@astram/sdk)) and enforces
+**deny-by-default** from the very first boot. You build features; the framework
+lives read-only in `node_modules` and upgrades via `npm update` — you never edit it.
+
+## Run it
+
+```bash
+npm install
+npm run dev        # boots the app (tsx watch) on http://localhost:3000
+```
+
+Then:
+
+```bash
+curl -i localhost:3000/health          # 200 — @Public health probe
+curl -i localhost:3000/demo/public     # 200 — explicit @Public() opt-out
+curl -i localhost:3000/demo/unclassified   # 403 — DENIED (no classification)
+```
+
+That last 403 is the whole point: **every route is denied unless you explicitly
+classify it.** Forgetting to declare a route locks the door instead of silently
+exposing it.
+
+Other scripts: `npm run build` (→ `dist/`), `npm start` (run the build),
+`npm test` (the enforcement e2e), `npm run lint`.
+
+## How it wires the framework
+
+`src/app.module.ts` imports the ONE registration seam — no local security wiring:
+
+```ts
+import { ShieldModule } from '@astram/guard';
+
+@Module({
+  imports: [ShieldModule.forRoot()],          // framework owns enforcement
+  controllers: [HealthController, DemoController],
+})
+export class AppModule {}
+```
+
+`ShieldModule.forRoot()` binds the global deny-by-default guard (ADR-0002), the
+boot-pool assertion (ADR-0018), and the Core decision-authority token. You never
+re-implement enforcement — you register it once and add your controllers.
+
+## Add a feature (the framework way)
+
+1. Create `src/features/<your-feature>/` with a Nest module + controller(s).
+2. Register it in `src/app.module.ts` (add the module to `imports`, or its
+   controller to `controllers`).
+3. **Classify every route:** `@Public()` for open routes, `@Classified(...)` for
+   guarded ones. Anything unclassified is denied (403) by design.
+4. Add a test (see `test/enforcement.e2e.spec.ts` for the pattern).
+
+`src/features/` starts empty — it's your space.
+
+## What's here today (and what's next)
+
+Today you get correct-by-default **enforcement** out of the box: the framework's
+guard protects every route from the first boot. A turnkey **login / session**
+boilerplate (wired through the same `ShieldModule.forRoot()` seam) arrives in a
+later framework release — when it lands, you'll pick it up via `npm update` without
+touching your `src/`.
+
+## Layout
+
+```
+src/
+  main.ts                   HTTP bootstrap (thin) — loadAppConfig from @astram/guard
+  app.module.ts             declares enforcement via ShieldModule.forRoot()
+  health/
+    health.controller.ts    /health /ready /live  (all @Public)
+    demo.controller.ts      /demo/public (@Public) + /demo/unclassified (denied)
+  features/                 EMPTY — your editable space
+test/
+  enforcement.e2e.spec.ts   boots the app; proves 200 health + 403 unclassified
+.astram/guide/              YOUR project guide (upgrade-safe; never touched)
+docs/                       your own docs (the scaffolder never clobbers this)
+```
+
+## The `.astram/guide/` directory
+
+This is your **project-owned** AI/dev guide layer (ADR-0025) — framework upgrades
+never touch it. Put your project's own rules and context there. See
+`.astram/guide/README.md`.

package/template/_astram/guide/README.md

@@ -0,0 +1,32 @@
+# `.astram/guide/` — your project's AI/dev guide (yours to own)
+
+This directory is **yours**. The framework scaffolder created it once and will
+**never touch it again** — `npm update` / framework upgrades leave everything here
+exactly as you wrote it. It is the *developer-owned* half of Astram's two-layer
+guide model (ADR-0025):
+
+| Layer                  | Where it lives                          | Who owns it | On upgrade        |
+| ---------------------- | --------------------------------------- | ----------- | ----------------- |
+| **Framework guide**    | the installed `@astram/guide` package\* | framework   | replaced on update |
+| **Project guide (you)**| **this `.astram/guide/` directory**     | **you**     | **never touched**  |
+
+\* The framework-owned guide is delivered as an installed package (resolved in
+`node_modules`), not copied into your repo — so upgrades can refresh it without
+overwriting your work. It is a later framework release; today your app is simply
+structured to consume it when it lands.
+
+## What to put here
+
+Your **project-specific** rules and context for AI assistants and teammates:
+
+- Conventions and patterns specific to *this* app.
+- Domain glossary, module map, "how we do X here" notes.
+- Decisions and constraints an assistant should honor when generating code.
+
+## What NOT to put here
+
+- **Framework rules.** Those come from the framework guide package — don't copy
+  them in, or upgrades and your local edits will diverge. Keep this directory to
+  *your* project's additions only.
+
+Add markdown files alongside this README as your project grows.

package/template/_env.example

@@ -0,0 +1,33 @@
+# __APP_NAME__ — environment configuration (references only, no secrets).
+#
+# Every value below has a safe default, so the app boots with NO .env file at all.
+# Copy this file to `.env` and override only what you need. `.env` is gitignored.
+#
+# These are read by `loadAppConfig()` from the installed @astram/guard framework.
+
+# HTTP port the app listens on (default: 3000).
+PORT=3000
+
+# Runtime environment: development | production | test (default: development).
+NODE_ENV=development
+
+# --- ADR-0018 connection-pool budget (all optional; framework defaults apply) ---
+# Uncomment + tune only if your deployment needs to.
+# SHIELD_POOL_WORKERS=1
+# SHIELD_DB_MAX_CONNECTIONS=50
+# SHIELD_POOL_HEADROOM=5
+# SHIELD_POOL_MAX_CORE=10
+# SHIELD_POOL_MAX_APP_CRUD=10
+# SHIELD_POOL_MAX_SCHEMA_SVC=5
+
+# --- OPTIONAL: real authentication (only if you set ShieldModule.forRoot({ auth: true })) ---
+# Auth needs a live MariaDB + Redis and a refresh-token HMAC key. These are
+# REQUIRED once auth is enabled (the app fails closed without the HMAC key) — but
+# irrelevant (unread) while auth is off. Point them at your MariaDB/Redis.
+# SHIELD_DB_HOST=127.0.0.1
+# SHIELD_DB_PORT=3306
+# SHIELD_DB_USER=shield_core
+# SHIELD_DB_PASSWORD=change-me
+# SHIELD_DB_DATABASE=shield_identity
+# SHIELD_REDIS_URL=redis://127.0.0.1:6379
+# SHIELD_REFRESH_HMAC_KEY=change-me-to-a-long-random-secret   # REQUIRED when auth is on

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store

package/template/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "description": "An Astram consumer app. Depends on the published, immutable framework (@astram/core, @astram/guard, @astram/sdk) and declares enforcement via ShieldModule.forRoot(). Features go in src/features/.",
+  "type": "commonjs",
+  "main": "dist/main.js",
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/main.js",
+    "dev": "tsx watch src/main.ts",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\""
+  },
+  "dependencies": {
+    "@astram/core": "^0.1.0",
+    "@astram/guard": "^0.1.1",
+    "@astram/sdk": "^0.1.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11.0.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/supertest": "^6.0.2",
+    "supertest": "^7.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0",
+    "unplugin-swc": "^1.5.1",
+    "vitest": "^2.1.8"
+  }
+}

package/template/src/app.module.ts

@@ -0,0 +1,45 @@
+import { Module } from '@nestjs/common';
+import { ShieldModule } from '@astram/guard';
+import { HealthController } from './health/health.controller';
+import { DemoController } from './health/demo.controller';
+
+/**
+ * Root module — YOUR editable space.
+ *
+ * `ShieldModule.forRoot()` is the ONE registration seam into the framework. That
+ * single import wires the global deny-by-default enforcement guard (ADR-0002) via
+ * `APP_GUARD`, the boot-pool assertion (ADR-0018), and the Core decision-authority
+ * token — all owned by the framework, all read-only in `node_modules`. You never
+ * re-wire enforcement yourself; you register it once and add your controllers.
+ *
+ * TO ADD A FEATURE:
+ *   1. Create a module + controller under `src/features/<your-feature>/`.
+ *   2. Import that module here (add it to `imports`) or list its controller in
+ *      `controllers`.
+ *   3. Classify every route: `@Public()` for open routes, `@Classified(...)` for
+ *      guarded ones. Anything left unclassified is DENIED (403) by design.
+ *
+ * `HealthController` + `DemoController` below are starter routes that prove the
+ * framework enforces from your side (health/@Public → 200, unclassified → 403).
+ * Keep the health probes; the demo controller is illustrative — delete it once
+ * you've seen enforcement work.
+ *
+ * ── OPTIONAL: real authentication (login/MFA/refresh/logout) ──────────────────
+ * The framework ships a complete Auth surface you can turn on WITHOUT writing any
+ * auth code. It is OFF by default so this app boots with NO `.env` at all (pure
+ * enforcement). To enable it:
+ *   1. Change `ShieldModule.forRoot()` below to `ShieldModule.forRoot({ auth: true })`.
+ *   2. Provide the DB/Redis/HMAC config in `.env` (see the AUTH block in
+ *      `.env.example`) — auth needs a real MariaDB + Redis and a refresh HMAC key.
+ *   3. Create a user in the `shield_identity.identity_credential` table.
+ * You then get framework-owned `POST /auth/{login,mfa,refresh,logout}` for free —
+ * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
+ * boot; turning it on requires the config above, by design — fail-closed.)
+ */
+@Module({
+  // Enforcement-only by default (boots with no config). For real login, use:
+  //   imports: [ShieldModule.forRoot({ auth: true })],
+  imports: [ShieldModule.forRoot()],
+  controllers: [HealthController, DemoController],
+})
+export class AppModule {}

package/template/src/features/_gitkeep

@@ -0,0 +1,9 @@
+# Your editable feature space.
+#
+# Add each feature under its own folder here, e.g. src/features/orders/, with a
+# Nest module + controller(s). Register the feature in src/app.module.ts and
+# classify every route (@Public / @Classified) — unclassified routes are denied
+# by the framework's global guard (deny-by-default, ADR-0002).
+#
+# This file only keeps the empty directory in version control; delete it once you
+# add your first feature.

package/template/src/health/demo.controller.ts

@@ -0,0 +1,28 @@
+import { Controller, Get } from '@nestjs/common';
+import { Public } from '@astram/guard';
+
+/**
+ * Demonstration routes proving the deny-by-default enforcement seam (ADR-0002).
+ *
+ * - `GET /demo/public`       → `@Public()`  → REACHABLE (200).
+ * - `GET /demo/unclassified` → no metadata  → DENIED by the global guard (403).
+ *
+ * The second handler carries NO classification decorator on purpose: it shows
+ * that forgetting to declare a route locks the door (deny-by-default) rather than
+ * silently exposing it. This controller is illustrative — delete it once you've
+ * seen enforcement work; a real feature would classify every route.
+ */
+@Controller('demo')
+export class DemoController {
+  @Public()
+  @Get('public')
+  publicRoute(): { message: string } {
+    return { message: 'public route reachable — explicit @Public() opt-out' };
+  }
+
+  // NOTE: intentionally NO @Public() / @Classified() — must be DENIED (403).
+  @Get('unclassified')
+  unclassifiedRoute(): { message: string } {
+    return { message: 'this body must never be reached — the guard denies first' };
+  }
+}

package/template/src/health/health.controller.ts

@@ -0,0 +1,43 @@
+import { Controller, Get } from '@nestjs/common';
+import { Public } from '@astram/guard';
+
+/** Simple ok payload shape for the probe endpoints. */
+export interface ProbePayload {
+  readonly status: 'ok';
+  readonly check: 'health' | 'ready' | 'live';
+  /** UTC epoch milliseconds (set explicitly in UTC). */
+  readonly timestampMs: number;
+}
+
+function ok(check: ProbePayload['check']): ProbePayload {
+  return { status: 'ok', check, timestampMs: Date.now() };
+}
+
+/**
+ * Liveness / readiness / health probes.
+ *
+ * All three are explicitly `@Public()` — they must be reachable without a
+ * classification. This app returns a static ok payload; wire real readiness
+ * (DB / cache / pool) into `/ready` as your app grows.
+ */
+@Controller()
+export class HealthController {
+  @Public()
+  @Get('health')
+  health(): ProbePayload {
+    return ok('health');
+  }
+
+  @Public()
+  @Get('ready')
+  ready(): ProbePayload {
+    // LATER: reflect real readiness (pool / deps) here.
+    return ok('ready');
+  }
+
+  @Public()
+  @Get('live')
+  live(): ProbePayload {
+    return ok('live');
+  }
+}

package/template/src/main.ts

@@ -0,0 +1,25 @@
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { loadAppConfig } from '@astram/guard';
+import { AppModule } from './app.module';
+
+/**
+ * HTTP bootstrap for this Astram consumer app.
+ *
+ * Thin on purpose: it builds the Nest app (whose `AppModule` declares enforcement
+ * via `ShieldModule.forRoot()`, wiring the framework's global deny-by-default
+ * guard) and starts the HTTP listener. No security logic lives here —
+ * `loadAppConfig` comes from the installed `@astram/guard` framework package and
+ * reads PORT / ENVIRONMENT from the environment (see `.env.example`).
+ */
+export async function bootstrap(): Promise<void> {
+  const config = loadAppConfig();
+  const app = await NestFactory.create(AppModule, { bufferLogs: false });
+  await app.listen(config.port);
+  console.log(`[__APP_NAME__] listening on :${config.port} (${config.environment})`);
+}
+
+// Only auto-start when run directly (not when imported by tests).
+if (process.env.NODE_ENV !== 'test') {
+  void bootstrap();
+}

package/template/test/enforcement.e2e.spec.ts

@@ -0,0 +1,56 @@
+import type { INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { AppModule } from '../src/app.module';
+
+/**
+ * End-to-end proof of the framework's global, deny-by-default enforcement seam
+ * (ADR-0002) and the public health probes. Boots the real Nest app (with the
+ * global APP_GUARD wired by ShieldModule.forRoot()) and drives it over HTTP.
+ *
+ * This is your starter test — extend it as you add features. Every new route you
+ * write should have a test asserting it's reachable only when you meant it to be.
+ */
+describe('__APP_NAME__ — framework enforcement + health (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('boots the application', () => {
+    expect(app).toBeDefined();
+    expect(app.getHttpServer()).toBeDefined();
+  });
+
+  it('GET /health returns 200 with an ok payload (@Public)', async () => {
+    const res = await request(app.getHttpServer()).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ status: 'ok', check: 'health' });
+    expect(typeof res.body.timestampMs).toBe('number');
+  });
+
+  it('GET /demo/public is REACHABLE — explicit @Public() opt-out', async () => {
+    const res = await request(app.getHttpServer()).get('/demo/public');
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({
+      message: expect.stringContaining('public route reachable'),
+    });
+  });
+
+  it('GET /demo/unclassified is DENIED (403) — deny-by-default (ADR-0002)', async () => {
+    const res = await request(app.getHttpServer()).get('/demo/unclassified');
+    expect(res.status).toBe(403);
+    // The guard denies BEFORE the handler body runs.
+    expect(res.body.message).toContain('no access classification');
+  });
+});

package/template/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "sourceMap": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["test/**/*", "vitest.config.ts", "**/*.spec.ts", "**/*.test.ts"]
+}

package/template/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+
+    // NestJS is a Node/CommonJS runtime that relies on emitted decorator metadata
+    // (reflect-metadata DI). This is the standard NestJS TS setup.
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": true,
+
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+
+    // NestJS DI injects constructor params that trivial wiring may not reference,
+    // and uses framework decorators — relax these two so DI wiring type-checks.
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,32 @@
+import swc from 'unplugin-swc';
+import { defineConfig } from 'vitest/config';
+
+/**
+ * Vitest config for the NestJS app.
+ *
+ * NestJS DI depends on emitted decorator metadata (`emitDecoratorMetadata`).
+ * Vitest's default esbuild transform strips decorators WITHOUT emitting that
+ * metadata, which breaks constructor injection. unplugin-swc runs SWC with
+ * `legacyDecorator` + `decoratorMetadata` enabled so the reflect-metadata model
+ * works exactly as it does at build time (tsc).
+ */
+export default defineConfig({
+  plugins: [
+    swc.vite({
+      module: { type: 'es6' },
+      jsc: {
+        target: 'es2022',
+        transform: {
+          legacyDecorator: true,
+          decoratorMetadata: true,
+        },
+      },
+    }),
+  ],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.{test,spec}.ts', 'src/**/*.{test,spec}.ts'],
+    passWithNoTests: false,
+  },
+});