create-davepi-app 0.1.0 → 0.1.3

package/bin/index.js

@@ -184,6 +184,25 @@ async function scaffold({ name, template, install, davepiVersion, port }) {
   }
 
   // 2. package.json — pin dAvePi as a runtime dep.
+  //
+  // The `imports` block declares Node's built-in subpath-import
+  // aliases (https://nodejs.org/api/packages.html#subpath-imports).
+  // Use them from any file in this project to require local code
+  // without `../../../` ladders:
+  //
+  //   const postmark = require('#plugins/postmark');           // → ./plugins/postmark.js
+  //   const { genCode } = require('#lib/codes');               // → ./lib/codes.js
+  //   const helper = require('#plugins/postmark/helpers');     // → ./plugins/postmark/helpers.js
+  //
+  // The `.js` suffix on the right-hand side is intentional: Node's
+  // subpath-import resolver does NOT fall back to CJS resolution
+  // (`.js` / `/index.js`) for bare-glob targets — without the
+  // explicit extension, `require('#plugins/postmark')` would crash
+  // with MODULE_NOT_FOUND. The `*` matches the path segment(s)
+  // between the alias and the trailing `.js`, so nested files work
+  // too. `#` is the standard prefix (not `@`, which Node reserves
+  // for npm-scoped packages). This is the convention every dAvePi
+  // project uses; the docs site and the agent.md guide expect it.
   writeJson(path.join(target, 'package.json'), {
     name,
     version: '0.1.0',
@@ -205,6 +224,11 @@ async function scaffold({ name, template, install, davepiVersion, port }) {
       'gen-client': 'davepi gen-client --out client/davepi.ts',
       'mcp:stdio': 'davepi mcp',
     },
+    imports: {
+      '#plugins/*': './plugins/*.js',
+      '#lib/*':     './lib/*.js',
+      '#schema/*':  './schema/*.js',
+    },
     dependencies: {
       davepi: davepiVersion || 'latest',
     },
@@ -230,7 +254,11 @@ async function scaffold({ name, template, install, davepiVersion, port }) {
       `TOKEN_KEY=${randomSecret()}`,
       `API_PORT=${apiPort}`,
       `PAGE_SIZE=20`,
-      `CORS_ORIGINS=http://localhost:3000,http://localhost:5173`,
+      // localhost:3000 + localhost:5173 cover common frontend dev servers
+      // (CRA, Vite). localhost:${apiPort} covers same-origin asset loads
+      // from the bundled admin SPA in case the framework's same-origin
+      // bypass is ever bypassed.
+      `CORS_ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost:${apiPort}`,
       `# Set HOT_RELOAD_SCHEMAS=true in dev to pick up schema/versions/* changes live.`,
       `HOT_RELOAD_SCHEMAS=true`,
       `NODE_ENV=development`,
@@ -352,7 +380,7 @@ async function scaffold({ name, template, install, davepiVersion, port }) {
       `- REST: http://localhost:${apiPort}/api/v1/...`,
       `- GraphQL: http://localhost:${apiPort}/graphql/`,
       `- Swagger: http://localhost:${apiPort}/api-docs`,
-      `- Admin SPA: http://localhost:${apiPort}/admin (after \`npm run build:admin\` in node_modules/davepi)`,
+      `- Admin SPA: http://localhost:${apiPort}/admin`,
       `- Capability manifest: http://localhost:${apiPort}/_describe`,
       '',
       '## What\'s in this template',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-davepi-app",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Scaffolder for new dAvePi projects. Run: npx create-davepi-app <name> [--template <name>]",
   "license": "ISC",
   "author": "David Baxter",

package/templates/_shared/agent.md

@@ -206,6 +206,32 @@ module.exports = {
 - **State machines need `initial`.** Without it, the framework can't pick
   a default starting state on POST and creates fail with a validation
   error.
+- **Use `#` subpath imports for local requires — never `../` ladders.**
+  Every scaffolded project ships with this in `package.json`:
+
+  ```json
+  "imports": {
+    "#plugins/*": "./plugins/*.js",
+    "#lib/*":     "./lib/*.js",
+    "#schema/*":  "./schema/*.js"
+  }
+  ```
+
+  So from a schema file or plugin, write:
+
+  ```js
+  const postmark = require('#plugins/postmark');   // ✅ → ./plugins/postmark.js
+  const { genCode } = require('#lib/codes');       // ✅ → ./lib/codes.js
+  const postmark = require('../../../plugins/postmark');  // ❌ fragile
+  ```
+
+  This is [Node's built-in subpath imports](https://nodejs.org/api/packages.html#subpath-imports) —
+  no bundler, no extra dep, no `@` prefix (Node reserves `@` for npm-scoped
+  packages like `@scope/pkg`; `#` is the standard for local aliases). The
+  trailing `.js` on the mapping target is required — Node's resolver does
+  not fall back to `.js`/`/index.js` for bare-glob subpath targets. Add
+  more entries to `imports` as you grow the project. Framework code from
+  the `davepi` package itself stays as `require('davepi/utils/...')`.
 
 ## The MCP tool surface