@xeplr/cli 0.1.1

package/lib/prompt.js

@@ -0,0 +1,130 @@
+// Asking questions on a terminal, with nothing installed.
+//
+// NO DEPENDENCIES, deliberately. This is the first thing anybody runs, usually
+// through `npx`, and every package it pulls is time spent before the first
+// question and one more thing that can fail on a machine we have never seen.
+// readline has been in Node since forever and does everything needed here.
+var readline = require('readline');
+
+/**
+ * WHY THIS QUEUES LINES INSTEAD OF CALLING rl.question() PER ANSWER.
+ *
+ * rl.question() registers a ONE-SHOT listener. On a terminal that is fine,
+ * because a human cannot type faster than we can re-register it. Piped input
+ * is not: readline reads the whole chunk and emits every 'line' synchronously,
+ * so each answer after the first arrives while no question is pending and is
+ * DROPPED ON THE FLOOR. The next question then waits for input that has
+ * already been and gone, and the process exits mid-wizard having silently
+ * discarded most of what it was given.
+ *
+ * So we listen for 'line' permanently and keep what arrives. A question takes
+ * the next queued line if one is waiting, or waits for the next one. Identical
+ * behaviour typed or piped — which matters, because piping answers is how this
+ * gets tested and how anybody scripts it.
+ */
+function createSession(options) {
+  options = options || {};
+  var input = options.input || process.stdin;
+  var output = options.output || process.stdout;
+
+  var rl = readline.createInterface({ input: input, output: output });
+
+  var queued = [];      // lines that arrived before anything asked for them
+  var waiting = [];     // resolvers waiting for a line that has not arrived
+  var closed = false;
+
+  rl.on('line', function (line) {
+    if (waiting.length) return waiting.shift()(line);
+    queued.push(line);
+  });
+
+  rl.on('close', function () {
+    closed = true;
+    // Anything still waiting gets an empty string, so its default applies and
+    // the caller ends cleanly rather than hanging on a stream that is finished.
+    while (waiting.length) waiting.shift()('');
+  });
+
+  function nextLine() {
+    if (queued.length) return Promise.resolve(queued.shift());
+    if (closed) return Promise.resolve('');
+    return new Promise(function (resolve) { waiting.push(resolve); });
+  }
+
+  /**
+   * @param {string} question
+   * @param {object} [opts]
+   * @param {string} [opts.default]  shown in brackets; returned on empty input
+   * @param {Function} [opts.validate] (value) => true | 'why it is wrong'
+   */
+  async function ask(question, opts) {
+    opts = opts || {};
+    var suffix = opts.default ? ' (' + opts.default + ')' : '';
+
+    for (;;) {
+      output.write(question + suffix + ' ');
+      var answer = await nextLine();
+      var value = (answer || '').trim() || opts.default || '';
+
+      if (!opts.validate) return value;
+
+      var verdict = opts.validate(value);
+      if (verdict === true) return value;
+
+      // Re-ask rather than exit. Being thrown out of a wizard on the fourth
+      // question because of a typo means starting over.
+      output.write('  ' + verdict + '\n');
+
+      // ...unless there is no more input to re-ask with. Piped or redirected
+      // input would otherwise loop forever printing the same complaint.
+      if (closed && !queued.length) {
+        throw new Error(question + ' — ' + verdict);
+      }
+    }
+  }
+
+  /**
+   * Like ask(), but the typing does not appear on screen.
+   *
+   * Only when the input is a real terminal. Piped input has no echo to
+   * suppress, and trying to mute it there breaks reading altogether — which
+   * would make the one thing nobody can retype impossible to script.
+   */
+  async function askSecret(question) {
+    if (!input.isTTY) return ask(question);
+
+    output.write(question + ' ');
+    var muted = true;
+    var onData = function (char) {
+      // Stop hiding once the line ends, so the next prompt is visible.
+      if (char.toString() === '\n' || char.toString() === '\r') muted = false;
+    };
+    input.on('data', onData);
+
+    var originalWrite = output.write.bind(output);
+    output.write = function (chunk) {
+      if (muted) return true;          // swallow the echo
+      return originalWrite(chunk);
+    };
+
+    try {
+      var value = await nextLine();
+      return (value || '').trim();
+    } finally {
+      output.write = originalWrite;
+      input.removeListener('data', onData);
+      originalWrite('\n');
+    }
+  }
+
+  async function confirm(question, defaultYes) {
+    var v = await ask(question + (defaultYes ? ' [Y/n]' : ' [y/N]'), {
+      default: defaultYes ? 'y' : 'n'
+    });
+    return /^y/i.test(v);
+  }
+
+  return { ask: ask, askSecret: askSecret, confirm: confirm, close: function () { rl.close(); } };
+}
+
+module.exports = { createSession: createSession };

package/lib/questions.js

@@ -0,0 +1,125 @@
+var crypto = require('crypto');
+var { encrypt } = require('@xeplr/utils/isomorphic/crypto');
+
+// A name that works as a folder, an npm package name, AND a database name.
+//
+// Must start with a letter and END with a letter or digit. A trailing dash
+// passes as a folder name and then fails twice over: `@thing-/api` is not a
+// legal package name, and `thing-_api` is a database name that has to be
+// quoted everywhere it appears.
+var NAME_RE = /^[a-z][a-z0-9-]{0,39}[a-z0-9]$/;
+
+// Ports are taken a DECADE at a time — ui, auth, api — so two products can run
+// side by side without either being renumbered. xeplr-bi holds 19100, workflow
+// 19120.
+var TAKEN_DECADES = [19100, 19120];
+
+function envPrefix(name) {
+  // yyan → YYAN, my-app → MY_APP. This becomes MY_APP_PORT and
+  // MY_APP_CONNECTION, so it has to be a legal env var name.
+  return name.toUpperCase().replace(/-/g, '_');
+}
+
+function secret() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Everything the generator needs, collected from the person running this.
+ *
+ * ASKS AS LITTLE AS POSSIBLE. Anything that can be computed is computed,
+ * anything that can be generated is generated, and the one value that can be
+ * neither — the database connection — is deliberately left blank rather than
+ * guessed at. See lib/plan.js.
+ */
+async function collect(session, argvName) {
+  // Generated up front: the connection below is encrypted with it.
+  var encryptionKey = secret();
+
+  var name = argvName;
+  if (!name || NAME_RE.test(name) !== true) {
+    name = await session.ask('Project name?', {
+      default: argvName || undefined,
+      validate: function (v) {
+        return NAME_RE.test(v) ? true
+          : 'Lowercase letters, numbers and dashes, starting with a letter.';
+      }
+    });
+  }
+
+  var decade = await session.ask('Port decade?', {
+    default: '19140',
+    validate: function (v) {
+      if (!/^\d{4,5}0$/.test(v)) return 'A number ending in 0, e.g. 19140.';
+      if (TAKEN_DECADES.indexOf(Number(v)) !== -1) {
+        return Number(v) + ' is already used by another xeplr product.';
+      }
+      return true;
+    }
+  });
+
+  var adminEmail = await session.ask('Super admin email?', {
+    default: 'admin@' + name + '.local',
+    validate: function (v) {
+      return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v) ? true : 'That is not an email address.';
+    }
+  });
+
+  var adminPassword = await session.ask('Super admin password?', {
+    default: 'ChangeMe123',
+    validate: function (v) {
+      // These are substituted into SQL text by the migrator, so the characters
+      // that would break that are refused here rather than at migrate time.
+      if (v.length < 8) return 'At least 8 characters.';
+      if (/["'\s$#]/.test(v)) return 'No quotes, spaces, $ or # — it is substituted into SQL.';
+      return true;
+    }
+  });
+
+  // ── the database ──────────────────────────────────────────────────────
+  //
+  // ASKED, not defaulted, and not left for the reader to do by hand either.
+  // The rule is that a database location is never GUESSED — asking is the
+  // opposite of guessing. Doing it here also spares everyone a long command
+  // with two --package flags whose result has to be pasted into two places.
+  //
+  // Declining is fine: the settings are written blank with the command above
+  // them, and the app refuses to start until they are filled in.
+  var connection = '';
+  var haveDb = await session.confirm('Set up the database connection now?', true);
+  if (haveDb) {
+    var dbHost = await session.ask('  Database host?', { default: 'localhost' });
+    var dbPort = await session.ask('  Database port?', {
+      default: '5432',
+      validate: function (v) { return /^\d+$/.test(v) ? true : 'A number.'; }
+    });
+    var dbUser = await session.ask('  Database user?', { default: 'postgres' });
+    var dbPass = await session.askSecret('  Database password?');
+
+    // Host, port, user and password are encrypted TOGETHER into one string —
+    // which is why a single setting is enough for the app to connect.
+    connection = await encrypt(JSON.stringify({
+      host: dbHost,
+      port: Number(dbPort),
+      user: dbUser,
+      password: dbPass
+    }), encryptionKey);
+  }
+
+  var base = Number(decade);
+
+  return {
+    connection: connection,
+    name: name,
+    prefix: envPrefix(name),
+    ports: { ui: base, auth: base + 1, api: base + 2 },
+    databases: { auth: name + '_auth', api: name + '_api' },
+    admin: { email: adminEmail, password: adminPassword },
+
+    // GENERATED, never asked. Nobody should be inventing these by hand, and a
+    // prompt invites a weak answer or a reused one.
+    secrets: { encryptionKey: encryptionKey, jwtSecret: secret() }
+  };
+}
+
+module.exports = { collect: collect, envPrefix: envPrefix, NAME_RE: NAME_RE };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xeplr/cli",
+  "version": "0.1.1",
+  "description": "Creates a working xeplr application — API, sign-in and UI — from a few answers.",
+  "license": "MIT",
+  "author": "xeppie <admin@xeplr.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xeplr/xeplr-cli.git"
+  },
+  "homepage": "https://github.com/Xeplr/xeplr-cli#readme",
+  "keywords": [
+    "xeplr",
+    "scaffold",
+    "generator",
+    "cli"
+  ],
+  "bin": {
+    "xeplr": "./bin/xeplr.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xeplr/utils": "^1.0.7"
+  }
+}

package/templates/api/app.js

@@ -0,0 +1,21 @@
+var createApp = require('@xeplr/base-apis/express');
+var routes = require('./routes');
+
+// No `|| __API_PORT__` fallback — the port is required in env.required.js, so a
+// default could only ever fire in a process that skipped that check.
+var port = process.env.__PREFIX___PORT;
+
+module.exports = function buildApp(extraRoutes) {
+  return createApp(port, '__NAME___api', {
+    // Every route needs a valid token, checked against the auth service at
+    // AUTH_URL. This app names no `middleware` of its own — it takes the
+    // framework's gate rather than writing one.
+    auth: {
+      // The only exception, and it earns it: a health check has no token to
+      // send. Prefixes, so '/health' also covers '/health/anything'.
+      publicPaths: ['/health']
+    },
+    log: { logDir: process.env.LOG_DIR || './logs' },
+    routes: Object.assign({}, extraRoutes || {}, { '/': routes })
+  });
+};

package/templates/api/bin/www

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+require('dotenv').config({ path: require('path').join(__dirname, '..', (process.env.NODE_ENV || 'development') + '.env') });
+
+// ── the database connection, checked first and by name ──────────────────
+//
+// BEFORE the general check, because this one has a fix that nobody can guess
+// from a variable name. The generic check can only say "this is missing";
+// these two settings hold an ENCRYPTED value that has to be produced by a
+// command, so a bare name sends somebody looking for a password to type into
+// a field that will not accept one.
+var CONNECTION_SETTINGS = ['__PREFIX___CONNECTION', 'AUTH_DB_CONNECTION_INFO_ENCRYPTED'];
+var blank = CONNECTION_SETTINGS.filter(function (name) { return !process.env[name]; });
+
+if (blank.length) {
+  console.error('\n[api] No database connection.\n');
+  console.error('  ' + blank.join(' and '));
+  console.error('  ' + (blank.length > 1 ? 'are' : 'is') + ' blank in development.env.\n');
+  console.error('  These hold your database host, port, user and password,');
+  console.error('  encrypted together into one value. To fill them in:\n');
+  console.error('    npm run db:encrypt\n');
+  console.error('  It asks for the details and writes both settings for you.');
+  console.error('  Non-interactively:\n');
+  console.error('    npm run db:encrypt -- --host localhost --port 5432 \\');
+  console.error('      --user postgres --password \'<yours>\' --write\n');
+  process.exit(1);
+}
+
+// Fail fast on the rest — shared check from @xeplr/base-apis.
+require('@xeplr/base-apis').checkEnv(require('../env.required.js'), { appName: 'api' });
+
+var path = require('path');
+var { resolveConfig } = require('@xeplr/db');
+var { up } = require('@xeplr/db').sqlMigrator;
+
+async function start() {
+  // Name the connection before anything uses it — the migrator resolves by
+  // name from a registry that getConnection does not populate.
+  await resolveConfig('api', process.env.__PREFIX___CONNECTION);
+
+  // Migrations run ON BOOT, so starting the API is the only thing anyone has
+  // to remember. Already-applied ones are skipped.
+  var result = await up({
+    db: process.env.DB_API,
+    dir: path.join(__dirname, '..', 'migrations'),
+    connectionName: 'api'
+  });
+  console.log(result.migrations.length
+    ? '[api] ran ' + result.migrations.length + ' migrations'
+    : '[api] migrations up to date');
+
+  // AWAITED before the app is built: routes/index.js hands MODEL CLASSES to
+  // genericRoute at build time, and an unbound class has no connection at all.
+  await require('../db/setup');
+
+  require('../app')();
+}
+
+start().catch(function(err) {
+  console.error('[api] startup failed:', err.stack || err.message);
+  process.exit(1);
+});

package/templates/api/db/setup.js

@@ -0,0 +1,10 @@
+// One call: decrypt the connection, connect to this app's own database, and
+// wire the models to it. Exports the connection promise, awaited by callers
+// that need it ready.
+var { getConnection } = require('@xeplr/db');
+
+// No `|| '__NAME___api'` fallback. DB_API is required at startup
+// (env.required.js), so a default could only ever fire in a process that
+// skipped that check — and silently connecting to a database nobody named is
+// exactly what the check exists to prevent.
+module.exports = getConnection(process.env.DB_API, process.env.__PREFIX___CONNECTION);

package/templates/api/development.env.tpl

@@ -0,0 +1,47 @@
+# __NAME__ — development settings.
+#
+# Ports: __UI_PORT__ ui · __AUTH_PORT__ auth · __API_PORT__ api
+
+NODE_ENV=development
+LOG_DIR=./logs
+
+# ── API service ──
+__PREFIX___PORT=__API_PORT__
+
+# ── Shared ──
+# Locks and unlocks the database connections below. Generated for you; keep it.
+# Lose it and the connection strings below have to be made again.
+ENCRYPTION_KEY=__ENCRYPTION_KEY__
+
+__CONNECTION_NOTE__
+__PREFIX___CONNECTION=__DB_CONNECTION__
+AUTH_DB_CONNECTION_INFO_ENCRYPTED=__DB_CONNECTION__
+
+# ── Databases ──
+# Two of them: accounts in one, your own data in the other. Both are created
+# for you the first time you run the setup.
+DB_API=__NAME___api
+AUTH_DB_NAME=__NAME___auth
+
+# ── Sign-in service ──
+AUTH_PORT=__AUTH_PORT__
+AUTH_JWT_SECRET=__JWT_SECRET__
+
+# Where the sign-in service is. Your API asks it to check every token.
+AUTH_URL=http://localhost:__AUTH_PORT__
+
+# Your own sign-in setup files — menu entries and anything else this app adds.
+XEPLR_AUTH_MIGRATIONS=./migrations-auth
+
+# ── The first account you sign in with ──
+# Created for you when you set up the database. Change the password here and
+# delete the account to reset it.
+AUTH_SUPER_ADMIN_EMAIL=__ADMIN_EMAIL__
+AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
+
+# ── Links that go out in emails ──
+# FULLY QUALIFIED, and they point at UI pages rather than at the API. The
+# sign-in service builds these links and appends the token as ?token=... — an
+# email template can carry a token as a value but cannot build an address.
+AUTH_ACTIVATION_URL=http://localhost:__UI_PORT__/auth/activate
+AUTH_INVITE_URL=http://localhost:__UI_PORT__/auth/accept-invite

package/templates/api/env.required.js

@@ -0,0 +1,29 @@
+/**
+ * Mandatory env vars for the __NAME__ API process. Checked at startup
+ * (bin/www) and at build (`npm run check-env`).
+ *
+ * SPREAD EACH LIBRARY'S OWN LIST rather than re-typing its variable names.
+ * The names belong to the library, so a new requirement it adds lands here on
+ * the next upgrade with nothing to remember — and nothing drifts out of step.
+ * Only APP-SPECIFIC names are written out literally below.
+ */
+module.exports = [
+  // ENCRYPTION_KEY, AUTH_JWT_SECRET, AUTH_PORT, AUTH_DB_NAME,
+  // XEPLR_AUTH_MIGRATIONS
+  ...require('@xeplr/auth').requiredEnv,
+
+  // ── this app's own ──
+  '__PREFIX___PORT',
+
+  // Where the sign-in service is. createApp gates every route by default and
+  // validates against this, so a missing one already stops the boot with a
+  // named variable — listing it here just moves the same complaint to
+  // `npm run check-env`, before anything starts at all.
+  'AUTH_URL',
+
+  // This app's own database. NEVER defaulted: a wrong-but-present name boots
+  // clean, migrates, serves traffic and reads as EMPTY DATA rather than as an
+  // error — the most expensive way for this to go wrong.
+  'DB_API',
+  '__PREFIX___CONNECTION'
+];

package/templates/api/gitignore.tpl

@@ -0,0 +1,2 @@
+node_modules/
+logs/

package/templates/api/migrations/0001_tasks.sql

@@ -0,0 +1,23 @@
+-- The sample table.
+--
+-- `id` is varchar(25) because ids are minted by the framework
+-- (@xeplr/utils' generateId) rather than by the database.
+--
+-- `isActive` is what makes a delete SOFT: the generic delete route sets it
+-- false and every query filters on it, so a deleted row stops appearing
+-- without ever leaving the table.
+
+CREATE TABLE IF NOT EXISTS "tasks" (
+  "id"                  varchar(25) PRIMARY KEY,
+  "title"               varchar(200) NOT NULL,
+  "description"         varchar(1000),
+  "status"              varchar(20) NOT NULL DEFAULT 'todo',
+  "dueDate"             date,
+  "isActive"            boolean DEFAULT true,
+  "recordCreatedDate"   timestamptz,
+  "recordModifiedDate"  timestamptz,
+  "recordCreatedBy"     varchar(25),
+  "recordModifiedBy"    varchar(25)
+);
+
+CREATE INDEX IF NOT EXISTS "tasks_status_idx" ON "tasks" ("status");

package/templates/api/migrations-auth/0001_home_menu.sql

@@ -0,0 +1,14 @@
+-- "Home" — this app's own drawer item, matching the name used in the UI's
+-- drawerItems list (ui/src/App.jsx).
+--
+-- Without this row the item is dropped from the drawer SILENTLY: the name has
+-- to exist here for @xeplr/ui-account to show it, and an unrecognised one
+-- produces no error anywhere.
+--
+-- isPublic: every signed-in user should see Home, whatever their role.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Home', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Home');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = 'Home';

package/templates/api/migrations-auth/0002_tasks_menu.sql

@@ -0,0 +1,11 @@
+-- "Tasks" — the drawer item for the sample page.
+--
+-- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
+-- @xeplr/ui-account drops unrecognised names silently, so a typo removes the
+-- item with no error anywhere.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Tasks', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Tasks');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = 'Tasks';

package/templates/api/models/Task.js

@@ -0,0 +1,48 @@
+var { BaseModel } = require('@xeplr/db');
+
+/**
+ * A task. The sample model — deliberately small, and deliberately showing the
+ * three things almost every real model needs: required fields, a value
+ * restricted to a known set, and a date.
+ *
+ * `jsonSchema` is not decoration. It is checked on every insert and update, so
+ * a bad value is refused by the API with a message naming the field, rather
+ * than reaching the database and failing as a constraint error nobody can read.
+ */
+class Task extends BaseModel {
+  static get tableName() { return 'tasks'; }
+  static get idColumn() { return 'id'; }
+
+  // Rows are NOT scoped to a company/workspace here, because this app has not
+  // declared any tenancy levels. Leave it as the default (true) and add
+  // registerMTs() later, and every row written before that has no owner.
+  static get multiTenant() { return false; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['title'],
+      properties: {
+        // 25 characters, because that is what the framework's own id generator
+        // produces (see genericController — ids are minted there, not here).
+        id: { type: 'string', maxLength: 25 },
+        title: { type: 'string', minLength: 1, maxLength: 200 },
+        description: { type: ['string', 'null'], maxLength: 1000 },
+        status: { type: 'string', enum: ['todo', 'in_progress', 'done'] },
+        dueDate: { type: ['string', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  $beforeInsert() {
+    super.$beforeInsert();   // keeps recordCreatedDate / isActive handling
+    if (!this.status) this.status = 'todo';
+  }
+}
+
+module.exports = Task;

package/templates/api/models/index.js

@@ -0,0 +1,7 @@
+// Every model this app owns. Add yours here — routes/index.js reads them from
+// this one place rather than reaching into individual files.
+var Task = require('./Task');
+
+module.exports = {
+  Task: Task
+};

package/templates/api/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@__NAME__/api",
+  "version": "1.0.0",
+  "private": true,
+  "license": "UNLICENSED",
+  "description": "__NAME__ backend — @xeplr/base-apis app.",
+  "main": "app.js",
+  "scripts": {
+    "check-env": "dotenv -e development.env -- xeplr-check-env",
+    "setup": "npm run db:create && npm run db:create:api && npm run migrate:auth",
+    "db:encrypt": "xeplr encrypt",
+    "db:create": "dotenv -e development.env -- xeplr-migrate create-db --connectionName auth --connection-env AUTH_DB_CONNECTION_INFO_ENCRYPTED --db-env AUTH_DB_NAME",
+    "db:create:api": "dotenv -e development.env -- xeplr-migrate create-db --connectionName api --connection-env __PREFIX___CONNECTION --db-env DB_API",
+    "migrate:auth": "dotenv -e development.env -- xeplr-auth-migrate up --connection-env AUTH_DB_CONNECTION_INFO_ENCRYPTED",
+    "migrate:up": "dotenv -e development.env -- xeplr-migrate up --dir ./migrations --connectionName api --connection-env __PREFIX___CONNECTION",
+    "start-auth": "dotenv -e ./development.env -- xeplr-auth-server",
+    "start-api": "NODE_ENV=development node ./bin/www"
+  },
+  "dependencies": {
+    "@xeplr/auth": "^1.1.0",
+    "@xeplr/base-apis": "^2.0.0",
+    "@xeplr/db": "^1.0.5",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.0"
+  },
+  "devDependencies": {
+    "dotenv-cli": "^8.0.0",
+    "@xeplr/cli": "^0.1.0"
+  }
+}

package/templates/api/routes/index.js

@@ -0,0 +1,46 @@
+var express = require('express');
+var { genericRoute } = require('@xeplr/base-apis');
+var { Task } = require('../models');
+
+var router = express.Router();
+
+// PUBLIC — listed in app.js's auth.publicPaths. Whatever polls this has never
+// signed in, so it has no token to send. It reports liveness and nothing else.
+router.get('/health', function(req, res) {
+  res.json({ status: 'ok' });
+});
+
+// GATED, like everything not named public.
+router.get('/', function(req, res) {
+  res.json({ service: 'api', status: 'running', name: '__NAME__-api' });
+});
+
+// Who is calling, and what they are allowed to reach. Both were put on the
+// request by the auth gate, so this makes no call of its own.
+router.get('/whoami', function(req, res) {
+  res.json({ user: req.user, roles: (req.access || {}).roles || [] });
+});
+
+// ── tasks ────────────────────────────────────────────────────────────────
+//
+// MOUNTED UNDER /api, and that prefix matters. The browser asks the UI's dev
+// server for BOTH its own pages and its data, and the dev server decides by
+// path which to forward. Serve data at /tasks and the UI's own /tasks page is
+// shadowed by it — opening that page shows raw JSON instead of the app.
+//
+// Keeping every data address under /api means a page path and a data path can
+// never collide, whatever either is called later.
+//
+// FOUR ADDRESSES FROM ONE LINE. Hand genericRoute a model and it builds:
+//
+//   GET  /api/tasks         list, paginated  (?page=1&limit=50)
+//   GET  /api/tasks/:id     one task
+//   POST /api/tasks/save    create and update, in one transaction
+//   POST /api/tasks/delete  soft delete by ids
+//
+// No handler is written for any of them. The model's own jsonSchema is what
+// validates the incoming values, so the rules live in one place rather than
+// being restated here.
+router.use('/api/tasks', genericRoute({ key: 'task', model: Task }));
+
+module.exports = router;