create-astram-app 0.1.2 → 0.2.0

package/template/server/scripts/dev.mjs

@@ -0,0 +1,51 @@
+/**
+ * Dev runner — TypeScript watch + auto-restart, with CORRECT NestJS decorator
+ * metadata.
+ *
+ * WHY not `tsx watch`: tsx uses esbuild, which does NOT emit `emitDecoratorMetadata`.
+ * NestJS constructor injection (`constructor(private x: Service)`) depends on that
+ * metadata, so under tsx a controller's injected service is `undefined` at runtime
+ * (a silent 500 on the first call). `tsc` DOES emit the metadata — so this runner
+ * compiles with `tsc --watch` (→ dist/) and runs `node --watch dist/main.js`, giving
+ * hot-reload AND correct DI. Same compiler as the production build, no extra deps.
+ *
+ * `.env` is loaded by the node child via --env-file-if-exists.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+
+mkdirSync('dist', { recursive: true });
+
+// 1) tsc in watch mode → dist/ (emits decorator metadata; the whole point).
+const tsc = spawn(
+  process.execPath,
+  [new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname, '-w', '-p', 'tsconfig.build.json', '--preserveWatchOutput'],
+  { stdio: 'inherit' },
+);
+
+// 2) Wait for the first emit, then run node --watch on the built entry.
+let started = false;
+const startNode = () => {
+  if (started) return;
+  if (!existsSync('dist/main.js')) {
+    setTimeout(startNode, 300);
+    return;
+  }
+  started = true;
+  const node = spawn(
+    process.execPath,
+    ['--env-file-if-exists=.env', '--watch', 'dist/main.js'],
+    { stdio: 'inherit' },
+  );
+  node.on('exit', (code) => {
+    tsc.kill();
+    process.exit(code ?? 0);
+  });
+};
+setTimeout(startNode, 800);
+
+process.on('SIGINT', () => {
+  tsc.kill();
+  process.exit(0);
+});

package/template/server/scripts/sync-astram-guide.mjs

@@ -0,0 +1,63 @@
+/**
+ * sync-astram-guide — copy the framework's guide docs into `.claude/rules/` so
+ * Claude Code reads the CURRENT framework rules.
+ *
+ * WHY (ADR-0025, the two-layer AI guide): the framework ships its hard rules +
+ * capabilities in the installed `@astram/guide` package (in node_modules). Claude
+ * Code reliably reads rules from `.claude/rules/` (a documented, symlink-aware
+ * location) — but NOT from an @import that points into node_modules. So this script
+ * bridges the two: it copies the framework docs from the installed package into the
+ * app-root `.claude/rules/`, where the app's CLAUDE.md references them.
+ *
+ * It runs on `npm install` AND `npm update` (wired as a postinstall in
+ * server/package.json), so a FRAMEWORK UPGRADE automatically refreshes the rules —
+ * the whole point of the upgrade-safe design. The copied files are GITIGNORED (they
+ * are a generated mirror of the framework's version); the developer-owned
+ * `.astram/guide/` layer is separate, git-tracked, and NEVER touched by this script.
+ *
+ * The app root is the monorepo root (one level up from server/), because CLAUDE.md +
+ * .claude/ live at the app root and Claude walks UP the tree from wherever you work.
+ */
+
+import { cpSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url)); // server/scripts
+const appRoot = resolve(here, '..', '..'); // monorepo root
+const rulesDir = join(appRoot, '.claude', 'rules');
+
+function main() {
+  let guide;
+  try {
+    guide = require('@astram/guide');
+  } catch {
+    // The framework guide package isn't installed (e.g. a partial install). Skip
+    // silently — this is a best-effort refresh, never a hard failure of the install.
+    process.stdout.write('[sync-astram-guide] @astram/guide not found — skipped.\n');
+    return 0;
+  }
+
+  mkdirSync(rulesDir, { recursive: true });
+  // Copy the framework docs into .claude/rules/ (overwrite — they are the framework's
+  // to own; on upgrade the newer versions replace the older ones cleanly).
+  cpSync(guide.FRAMEWORK_RULES_PATH, join(rulesDir, 'astram-framework-rules.md'));
+  cpSync(guide.CAPABILITIES_PATH, join(rulesDir, 'astram-framework-capabilities.md'));
+
+  // Stamp the synced version so a human/AI can see which framework version's rules
+  // are present (and notice when an upgrade changed them).
+  writeFileSync(
+    join(rulesDir, '.astram-guide-version'),
+    `${guide.version}\n`,
+    'utf8',
+  );
+
+  process.stdout.write(
+    `[sync-astram-guide] framework rules synced (v${guide.version}) → .claude/rules/\n`,
+  );
+  return 0;
+}
+
+process.exitCode = main();

package/template/_env.example

@@ -1,33 +0,0 @@
-# __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/package.json

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