create-davepi-app 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# create-davepi-app
+
+Scaffold a new [dAvePi](https://github.com/projik/davepi) project in one command.
+
+```bash
+npx create-davepi-app my-app
+npx create-davepi-app my-crm --template crm
+npx create-davepi-app my-tickets --template ticketing
+npx create-davepi-app my-blog --template content
+```
+
+## Templates
+
+| Template | What you get |
+|----------|--------------|
+| `blank` | Minimal — one resource (`note`) with full-text search. |
+| `crm` | Accounts / contacts / deals (state machine) / activities. Showcases relations, computed fields, file uploads, aggregations. |
+| `ticketing` | Tickets with two state machines (status + priority) plus comments. Showcases ACL on a comment field. |
+| `content` | Blog / CMS skeleton: articles (editorial workflow), categories, hero image uploads, computed slugs. |
+| `b2b-saas` | Multi-tenant SaaS skeleton: orgs / workspaces / invites (state machine) / billing-event ledger with monthly aggregations. |
+
+## What's scaffolded
+
+```
+my-app/
+├── .env                # random TOKEN_KEY, local Mongo URI
+├── .gitignore
+├── .mcp.json           # Claude Code wiring, ready to go
+├── .cursorrules        # mirrors agent.md for Cursor
+├── README.md
+├── TEMPLATE.md         # walkthrough of the chosen template's schemas
+├── agent.md            # drop-in agent guide
+├── docker-compose.yml  # local Mongo
+├── index.js            # `require('davepi')`
+├── package.json
+└── schema/
+    └── versions/
+        └── v1/
+            └── *.js    # the template's resource definitions
+```
+
+## Flags
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--template <name>` | `blank` | Pick the starter from the table above. |
+| `--no-install` | (run install) | Skip `npm install`. |
+| `--davepi-version <range>` | `latest` | Pin a specific dAvePi version in the generated `package.json`. |
+
+## Next steps after scaffolding
+
+```bash
+cd my-app
+docker compose up -d   # start Mongo
+npm start              # http://localhost:5050
+```
+
+Then open the project in Claude Code or Cursor — the MCP server is already wired and the agent guide lives at `agent.md`. Ask the agent to add a resource and watch it land via hot-reload.

package/bin/index.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+/**
+ * `npx create-davepi-app <name> [--template blank|crm|ticketing|content]`
+ *
+ * Scaffolds a new dAvePi project: copies the chosen template's
+ * schema files into the target directory, generates a package.json
+ * pinned to the latest dAvePi, writes a `.env` with secure defaults,
+ * pre-configures `.mcp.json` for Claude Code, and prints the next
+ * three commands the user should run.
+ *
+ * Stays small on purpose: no `inquirer`, no fancy progress bars —
+ * the goal is "from cold install to running with auth + sample
+ * data" in under a minute, and the fewer failure modes the better.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const net = require('net');
+
+const TEMPLATES = ['blank', 'crm', 'ticketing', 'content', 'b2b-saas'];
+
+function out(line) {
+  process.stdout.write(line + '\n');
+}
+function err(line) {
+  process.stderr.write(line + '\n');
+}
+
+/**
+ * Read a `--name <value>` flag from argv. Returns:
+ *   - null   when the flag isn't present
+ *   - true   when the flag is present with no following token
+ *            (treated as a boolean flag — e.g., --no-install)
+ *   - string when the flag has a non-flag value following it
+ *
+ * Throws when the next token starts with `--` (e.g.,
+ * `--davepi-version --no-install` would otherwise pin davepi to
+ * "--no-install" and silently produce an un-installable project).
+ */
+function flag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return null;
+  const next = args[i + 1];
+  if (next === undefined) return true;
+  if (typeof next === 'string' && next.startsWith('--')) {
+    const errFn = require('util').inspect;
+    const e = new Error(
+      `Flag ${name} requires a value (got ${errFn(next)}, which looks like another flag).`
+    );
+    e.usage = true;
+    throw e;
+  }
+  return next;
+}
+
+/**
+ * Find an unused TCP port near the requested starting port. Tries
+ * ports sequentially up to `maxAttempts` apart so the scaffolded
+ * .env carries a value the user can probably bind to. The check is
+ * advisory — by the time `npm start` runs, another process could
+ * have grabbed the port — but it dramatically reduces "tutorial
+ * fails because port 5050 is in use" failures.
+ */
+async function pickPort(start = 5050, maxAttempts = 20) {
+  for (let p = start; p < start + maxAttempts; p++) {
+    if (await isPortFree(p)) return p;
+  }
+  // Fall back to OS-assigned (port 0) to guarantee something works.
+  return await new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', () => resolve(false));
+    srv.listen(port, '127.0.0.1', () => {
+      srv.close(() => resolve(true));
+    });
+  });
+}
+
+function usage() {
+  out(`Usage: npx create-davepi-app <name> [--template <name>] [--no-install]
+
+Templates:
+  blank      Minimal — one resource, full-text search.
+  crm        Accounts / contacts / deals (state machine) / activities.
+  ticketing  Tickets (status + priority state machines) / comments.
+  content    Articles (editorial workflow) / categories / file uploads.
+  b2b-saas   Orgs / workspaces / invites (state machine) / billingEvent (aggregations).
+
+Examples:
+  npx create-davepi-app my-app
+  npx create-davepi-app my-crm --template crm
+  npx create-davepi-app my-app --template blank --no-install`);
+}
+
+/**
+ * Resolve the templates directory. When the package is installed
+ * from npm, templates live alongside `bin/` in the package itself.
+ * In the dAvePi monorepo (during dev / tests), templates live at
+ * the repo root one level up. Try both.
+ */
+function templatesDir() {
+  const local = path.resolve(__dirname, '..', 'templates');
+  if (fs.existsSync(local)) return local;
+  const monorepo = path.resolve(__dirname, '..', '..', 'templates');
+  if (fs.existsSync(monorepo)) return monorepo;
+  throw new Error(
+    'Cannot find templates directory. Reinstall create-davepi-app.'
+  );
+}
+
+function copyTree(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(src, dest);
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+function writeJson(filePath, obj) {
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + '\n');
+}
+
+function randomSecret() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+async function scaffold({ name, template, install, davepiVersion, port }) {
+  const target = path.resolve(name);
+  if (fs.existsSync(target)) {
+    const empty = fs.readdirSync(target).length === 0;
+    if (!empty) {
+      throw new Error(
+        `Target directory ${target} already exists and is not empty.`
+      );
+    }
+  } else {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  if (!TEMPLATES.includes(template)) {
+    throw new Error(
+      `Unknown template '${template}'. Allowed: ${TEMPLATES.join(', ')}`
+    );
+  }
+
+  // 1. Schemas + template README
+  copyTree(path.join(templatesDir(), template), target);
+
+  // 1a. Shared files dropped on top of every scaffolded project:
+  //   .github/workflows/*  — starter CI (test, client-gen drift,
+  //                          migrate-with-approval-gate, deploy).
+  //   tests/smoke.test.js  — schema-shape smoke test, sufficient
+  //                          for `npm test` to be a useful default
+  //                          before the user adds their own.
+  // Anything under _shared/ that isn't a directory the templates
+  // depend on goes in here. agent.md is loaded separately because
+  // it has placeholder substitution.
+  const sharedRoot = path.join(templatesDir(), '_shared');
+  for (const dir of ['.github', 'tests']) {
+    const src = path.join(sharedRoot, dir);
+    if (fs.existsSync(src)) {
+      copyTree(src, path.join(target, dir));
+    }
+  }
+
+  // 2. package.json — pin dAvePi as a runtime dep.
+  writeJson(path.join(target, 'package.json'), {
+    name,
+    version: '0.1.0',
+    private: true,
+    description: `${name} — built on dAvePi (${template} template).`,
+    scripts: {
+      // The consumer's index.js is just `require('davepi')` — that
+      // boots the server with the consumer's schemas/versions/.
+      start: 'node index.js',
+      dev: 'node index.js',
+      // Each template ships a `seed.js` that registers a demo user
+      // and POSTs sample records. Run AFTER `npm start` is up in
+      // another terminal.
+      seed: 'node seed.js',
+      // Schema-shape smoke test. node --test is built into Node 18+
+      // so this needs no extra dependencies. The shipped CI workflow
+      // runs this script.
+      test: 'node --test tests/*.test.js',
+      'gen-client': 'davepi gen-client --out client/davepi.ts',
+      'mcp:stdio': 'davepi mcp',
+    },
+    dependencies: {
+      davepi: davepiVersion || 'latest',
+    },
+  });
+
+  // 3. index.js — the consumer's entry point.
+  fs.writeFileSync(
+    path.join(target, 'index.js'),
+    "// Boots the dAvePi server using this project's schema/versions/* files.\n" +
+    "// Add custom routes here AFTER the require, using `app.locals.schemaLoader`.\n" +
+    "require('davepi');\n"
+  );
+
+  // 4. .env — random TOKEN_KEY (NEVER use the default in prod), local Mongo defaults.
+  // Port was probed for availability before scaffolding so the
+  // user lands on something they can actually bind to.
+  const apiPort = port || (await pickPort());
+  fs.writeFileSync(
+    path.join(target, '.env'),
+    [
+      `# Generated by create-davepi-app. Don't commit this file.`,
+      `MONGO_URI=mongodb://127.0.0.1:27017/${name.replace(/[^A-Za-z0-9_-]/g, '_')}`,
+      `TOKEN_KEY=${randomSecret()}`,
+      `API_PORT=${apiPort}`,
+      `PAGE_SIZE=20`,
+      `CORS_ORIGINS=http://localhost:3000,http://localhost:5173`,
+      `# Set HOT_RELOAD_SCHEMAS=true in dev to pick up schema/versions/* changes live.`,
+      `HOT_RELOAD_SCHEMAS=true`,
+      `NODE_ENV=development`,
+      ``,
+    ].join('\n')
+  );
+
+  // 5. .gitignore — note `client/davepi.ts` is NOT listed here. The
+  // generated TS client is a committed artifact so the
+  // `client-gen.yml` drift workflow has something to diff against,
+  // and downstream consumers can vendor it as part of the project.
+  // The file doesn't exist until the user runs `npm run gen-client`,
+  // which is fine — `git diff --exit-code` against a non-existent
+  // file fails cleanly.
+  fs.writeFileSync(
+    path.join(target, '.gitignore'),
+    ['node_modules', '.env', 'uploads', ''].join('\n')
+  );
+
+  // 6. .mcp.json — Claude Code wiring out of the box.
+  // Uses @davepi/mcp in HTTP-proxy mode pointed at the local server,
+  // so the agent talks to the SAME server the developer is already
+  // running (`npm start`). No duplicate process, and the wrapper
+  // installs on demand via `npx -y` — the user doesn't need to
+  // manage the binary path manually.
+  writeJson(path.join(target, '.mcp.json'), {
+    mcpServers: {
+      davepi: {
+        command: 'npx',
+        args: ['-y', '@davepi/mcp'],
+        env: {
+          DAVEPI_URL: `http://127.0.0.1:${apiPort}`,
+          DAVEPI_TOKEN:
+            '<run `npm start`, register a user, then paste the accessToken here>',
+        },
+      },
+    },
+  });
+
+  // 7. Agent guide. Canonical content lives in `templates/_shared/agent.md`
+  // and is mirrored to four locations so each agent runtime picks it up
+  // from its conventional path:
+  //   agent.md                              ← canonical, human-readable
+  //   .cursorrules                          ← Cursor
+  //   AGENTS.md                             ← OpenAI / Codex / agentic IDEs
+  //   .claude/skills/davepi/SKILL.md        ← Claude Code skill (with frontmatter)
+  // The shared file carries `{{PORT}}` placeholders that we substitute
+  // with the actually-bound API port so commands in the guide work
+  // out of the box.
+  const guideTemplate = fs.readFileSync(
+    path.join(templatesDir(), '_shared', 'agent.md'),
+    'utf8'
+  );
+  const agentGuide = guideTemplate.replace(/\{\{PORT\}\}/g, String(apiPort));
+  fs.writeFileSync(path.join(target, 'agent.md'), agentGuide);
+  fs.writeFileSync(path.join(target, '.cursorrules'), agentGuide);
+  fs.writeFileSync(path.join(target, 'AGENTS.md'), agentGuide);
+
+  // Claude Code skills require YAML frontmatter naming the skill and
+  // describing when to invoke it. Strip the leading "# Title" line
+  // from the canonical content (frontmatter replaces the H1) and
+  // prepend the metadata block.
+  const skillBody = agentGuide.replace(/^#\s+.+\n+/, '');
+  const skillContent =
+    [
+      '---',
+      'name: davepi',
+      'description: Conventions for adding resources / fields / relations / state machines / aggregations to this dAvePi project. Read before adding code.',
+      '---',
+      '',
+    ].join('\n') + skillBody;
+  const skillDir = path.join(target, '.claude', 'skills', 'davepi');
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillContent);
+
+  // 8. docker-compose.yml — local Mongo for dev.
+  fs.writeFileSync(
+    path.join(target, 'docker-compose.yml'),
+    [
+      '# Local Mongo for development. Run: docker compose up -d',
+      'services:',
+      '  mongo:',
+      '    image: mongo:7',
+      '    restart: unless-stopped',
+      '    ports:',
+      '      - "27017:27017"',
+      '    volumes:',
+      '      - mongo_data:/data/db',
+      'volumes:',
+      '  mongo_data: {}',
+      '',
+    ].join('\n')
+  );
+
+  // 9. README — project-level, not template-level. Renames the
+  // template README to TEMPLATE.md so both survive.
+  if (fs.existsSync(path.join(target, 'README.md'))) {
+    fs.renameSync(
+      path.join(target, 'README.md'),
+      path.join(target, 'TEMPLATE.md')
+    );
+  }
+  fs.writeFileSync(
+    path.join(target, 'README.md'),
+    [
+      `# ${name}`,
+      '',
+      `Built on dAvePi (\`${template}\` template).`,
+      '',
+      '## Get running',
+      '',
+      '```bash',
+      'docker compose up -d            # local Mongo',
+      'npm install                     # install dAvePi',
+      'npm start                       # boot the server',
+      '```',
+      '',
+      'Then:',
+      `- 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)`,
+      `- Capability manifest: http://localhost:${apiPort}/_describe`,
+      '',
+      '## What\'s in this template',
+      '',
+      `See [TEMPLATE.md](./TEMPLATE.md) for the schema walkthrough.`,
+      '',
+      '## With Claude Code / Cursor',
+      '',
+      'The MCP server is pre-configured in `.mcp.json`. The agent guide is at',
+      '`agent.md` and mirrored to `.cursorrules`, `AGENTS.md`, and',
+      '`.claude/skills/davepi/SKILL.md` so each runtime picks it up from its',
+      'conventional path. Open the project in your editor and ask the agent',
+      "to add a resource — schema files in `schema/versions/v1/` hot-reload",
+      'as you save.',
+      '',
+      '## Regenerate the typed client',
+      '',
+      '```bash',
+      'npm run gen-client',
+      '```',
+      '',
+      'Output lands at `client/davepi.ts`. Pair with `client/davepi-runtime.ts`',
+      "from dAvePi's source tree (or copy from `node_modules/davepi/client/`).",
+      '',
+    ].join('\n')
+  );
+
+  // 10. Done. Run npm install if requested.
+  out(`\nScaffolded ${name} (template: ${template})`);
+  if (install) {
+    out('\nInstalling dependencies...');
+    const { spawnSync } = require('child_process');
+    // npm ships as a .cmd shim on Windows, so the bare `npm`
+    // binary spawn fails with ENOENT there. Use the platform-
+    // specific shim name to keep the auto-install step working
+    // everywhere.
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const r = spawnSync(npmCmd, ['install'], { cwd: target, stdio: 'inherit' });
+    if (r.status !== 0) {
+      err(
+        `\nnpm install failed. Re-run manually: cd ${name} && npm install`
+      );
+      return target;
+    }
+  }
+
+  out('');
+  out(`Next steps:`);
+  out(`  cd ${name}`);
+  if (!install) out(`  npm install`);
+  out(`  docker compose up -d   # start Mongo`);
+  out(`  npm start              # http://localhost:${apiPort}`);
+  out('');
+  out(`Try Claude Code: open the project, the MCP server is wired in .mcp.json.`);
+  out(`Agent guide: agent.md (also mirrored to .cursorrules, AGENTS.md, .claude/skills/davepi/SKILL.md)`);
+  return target;
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (!args.length || args.includes('--help') || args.includes('-h')) {
+    usage();
+    process.exit(0);
+  }
+  const name = args.find((a) => !a.startsWith('--'));
+  if (!name) {
+    err('Project name required.');
+    usage();
+    process.exit(1);
+  }
+  let template = 'blank';
+  let davepiVersion = null;
+  let port = null;
+  try {
+    const tplArg = flag(args, '--template');
+    if (typeof tplArg === 'string') template = tplArg;
+    const v = flag(args, '--davepi-version');
+    if (typeof v === 'string') davepiVersion = v;
+    const p = flag(args, '--port');
+    if (typeof p === 'string' && /^\d+$/.test(p)) port = parseInt(p, 10);
+  } catch (parseErr) {
+    err(`\n${parseErr.message}`);
+    usage();
+    process.exit(1);
+  }
+  const noInstall = args.includes('--no-install');
+
+  try {
+    await scaffold({ name, template, install: !noInstall, davepiVersion, port });
+  } catch (e) {
+    err(`\nError: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv).catch((e) => {
+    err(`\nError: ${e && e.message ? e.message : String(e)}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { scaffold, TEMPLATES, flag, pickPort, isPortFree };

package/bin/sync-templates.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish hook: copy `templates/` from the dAvePi monorepo
+ * root into this package's directory so the published tarball
+ * carries the templates and consumers don't need a working
+ * monorepo layout to scaffold.
+ *
+ * The runtime CLI (`bin/index.js`) prefers a sibling `templates/`
+ * inside the package; this script populates that sibling. In dev
+ * (running tests, working in the monorepo) the CLI falls back to
+ * `../../templates` instead.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const src = path.resolve(__dirname, '..', '..', 'templates');
+const dest = path.resolve(__dirname, '..', 'templates');
+
+if (!fs.existsSync(src)) {
+  process.stderr.write(
+    `sync-templates: ${src} not found. Run from inside the dAvePi monorepo.\n`
+  );
+  process.exit(1);
+}
+
+fs.rmSync(dest, { recursive: true, force: true });
+
+function copyTree(s, d) {
+  fs.mkdirSync(d, { recursive: true });
+  for (const entry of fs.readdirSync(s, { withFileTypes: true })) {
+    const a = path.join(s, entry.name);
+    const b = path.join(d, entry.name);
+    if (entry.isDirectory()) copyTree(a, b);
+    else fs.copyFileSync(a, b);
+  }
+}
+
+copyTree(src, dest);
+process.stdout.write(`sync-templates: copied ${src} → ${dest}\n`);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-davepi-app",
+  "version": "0.1.0",
+  "description": "Scaffolder for new dAvePi projects. Run: npx create-davepi-app <name> [--template <name>]",
+  "license": "ISC",
+  "author": "David Baxter",
+  "bin": {
+    "create-davepi-app": "bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "node bin/sync-templates.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "davepi",
+    "scaffolder",
+    "create-app",
+    "template",
+    "rest",
+    "graphql",
+    "mcp"
+  ],
+  "homepage": "https://github.com/projik/davepi#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/projik/davepi.git",
+    "directory": "create-davepi-app"
+  }
+}

package/templates/_shared/.github/workflows/client-gen.yml

@@ -0,0 +1,65 @@
+name: Typed client drift
+
+# Regenerates client/davepi.ts from the live schema registry and
+# fails the PR if the committed copy doesn't match. This catches
+# the common bug where a schema field changes but the typed client
+# wasn't regenerated — without this guard, frontend code keeps
+# compiling against a stale type until someone hits a runtime
+# 500.
+#
+# The job uses a Mongo service because `davepi gen-client` boots
+# the schema loader (which connects to Mongo). It doesn't read or
+# write any data — Mongo just needs to accept the connection.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      # Only run when something that could affect the generated
+      # client has changed. Saves CI minutes on docs-only PRs.
+      - 'schema/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/client-gen.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    services:
+      mongo:
+        image: mongo:7
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --quiet --eval 'db.adminCommand({ ping: 1 }).ok'"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      MONGO_URI: mongodb://127.0.0.1:27017/client-gen
+      TOKEN_KEY: ci-only-not-a-real-secret
+      NODE_ENV: development
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: npm
+      - run: npm ci
+      - name: Regenerate the typed client
+        run: npx davepi gen-client --out client/davepi.ts
+      - name: Fail if the committed client is stale or missing
+        run: |
+          # Mark untracked files as intent-to-add so they show up in
+          # `git diff`. Without this, a never-committed (or
+          # accidentally gitignored) client/davepi.ts would silently
+          # pass the drift check — defeating the whole point of the
+          # workflow.
+          git add --intent-to-add client/davepi.ts 2>/dev/null || true
+          if ! git diff --exit-code -- client/davepi.ts; then
+            echo "::error::client/davepi.ts is out of date or not committed. Run \`npm run gen-client\` locally and commit the result."
+            exit 1
+          fi