create-astram-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# 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).
+
+## Intent
+
+```bash
+npx create-astram-app my-app
+```
+
+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.
+
+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/).
+
+## Commands
+
+```bash
+pnpm --filter create-astram-app build   # tsc → dist/index.js (the CLI stub)
+pnpm --filter create-astram-app lint
+```

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * `create-astram-app` — the Shield 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.              │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * INTENT (what the finished tool will do):
+ *
+ *   npx create-astram-app my-app
+ *
+ * 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`.
+ */
+const STUB_MESSAGE = [
+    'create-astram-app is a STUB (ADR-0023 §3) — not implemented in this layer.',
+    '',
+    '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(...).',
+    '',
+    'Reference skeleton: packages/nestjs-app/ · template: this package’s template/.',
+].join('\n');
+/** Entry point. Prints the stub notice and exits non-zero (nothing scaffolded). */
+export function main() {
+    console.error(STUB_MESSAGE);
+    return 1;
+}
+// Only run when invoked as a CLI (not when imported by a test).
+if (process.env.NODE_ENV !== 'test') {
+    process.exitCode = main();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "create-astram-app",
+  "version": "0.1.0",
+  "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.",
+  "type": "module",
+  "bin": {
+    "create-astram-app": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "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"
+  }
+}

package/template/README.md

@@ -0,0 +1,18 @@
+# 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`).