@xeplr/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+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,95 @@
+# @xeplr/cli
+
+Creates a working xeplr application — an API, sign-in, and a UI — from four
+questions.
+
+```bash
+npx @xeplr/cli new myapp
+```
+
+## What you get
+
+```
+myapp/
+├─ api/     backend, sign-in, your data
+└─ ui/      React frontend
+```
+
+Already working, with nothing to wire up:
+
+- **Sign-in** — login, register, forgot and reset password, activation,
+  profile, change password, and the admin screens for users, roles and
+  permissions. You write none of them.
+- **A guarded API** — every address needs a valid token. An address you want
+  open is named explicitly; there is no way to leave the whole thing public by
+  forgetting.
+- **A sample form** — a table, a model, one line of routing, and a page, with
+  instructions beside it showing how to add your own.
+- **A welcome screen** that checks it can reach everything and tells you which
+  files to change first.
+
+## Before you start
+
+- **Node.js** 18 or later
+- **PostgreSQL**, running, with a user allowed to create databases
+
+## Then
+
+```bash
+cd myapp/api
+npm install
+npm run setup        # creates both databases and their tables
+npm run start-auth   # sign-in
+npm run start-api    # your API
+
+cd ../ui
+npm install
+npm run dev
+```
+
+Open the UI and sign in with the account you named.
+
+## Changing the database connection later
+
+A password rotates, the database moves, or the first answer was wrong. From
+the project's `api` folder:
+
+```bash
+npm run db:encrypt
+```
+
+It reads the encryption key out of your settings, asks for the database
+details, and rewrites every connection setting for you.
+
+The same thing without a project to run it in — before `npm install`, or from
+any other folder — is `npx @xeplr/cli encrypt`. It asks for the key too, and
+prints the result rather than writing it.
+
+## If you skip the connection question
+
+The setting is left **blank**, with `npx @xeplr/cli encrypt` written directly
+above it in `api/development.env`.
+
+That is deliberate. Host, port, user and password are encrypted together into a
+single string, and a guessed value would start cleanly, migrate, serve traffic,
+and read as *empty data* rather than as an error — the most expensive way for
+this to go wrong. Until you fill it in, the app refuses to start and names the
+setting.
+
+The same rule applies to every database name and storage path in a xeplr app:
+no defaults, ever.
+
+## Questions it asks
+
+| | |
+|---|---|
+| Project name | the folder, and the database prefix |
+| Port decade | three consecutive ports — ui, sign-in, api |
+| Super admin email | the account you sign in with |
+| Super admin password | its password |
+
+Encryption keys and signing secrets are **generated, never asked**.
+
+## Licence
+
+MIT

package/bin/xeplr.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+var path = require('path');
+var prompt = require('../lib/prompt');
+var questions = require('../lib/questions');
+var plan = require('../lib/plan');
+var generate = require('../lib/generate');
+var nextSteps = require('../lib/nextSteps');
+var encryptCmd = require('../lib/commands/encrypt');
+
+var HELP = [
+  '',
+  '  xeplr — create a working xeplr application',
+  '',
+  '  Usage:',
+  '    xeplr new [name]     create a project',
+  '    xeplr encrypt        redo the database connection',
+  '',
+  '  new      Creates a project with an API, sign-in and a UI, all talking',
+  '           to each other. Asks a few questions; generates the rest.',
+  '',
+  '  encrypt  Turns database details into the single string the settings',
+  '           file holds. Run it inside a project and it finds the key and',
+  '           writes the result in for you. For when a password changes, the',
+  '           database moves, or the first answer was wrong.',
+  ''
+].join('\n');
+
+async function main() {
+  var argv = process.argv.slice(2);
+  var command = argv[0];
+
+  if (!command || command === '-h' || command === '--help' || command === 'help') {
+    console.log(HELP);
+    return 0;
+  }
+  if (command === 'encrypt') {
+    var s2 = prompt.createSession();
+    try {
+      return await encryptCmd.run(s2, argv.slice(1));
+    } finally {
+      s2.close();
+    }
+  }
+
+  if (command !== 'new') {
+    console.error('\n  Unknown command: ' + command + '\n  Try: xeplr new <name>  or  xeplr encrypt\n');
+    return 1;
+  }
+
+  console.log('\n  Creating a xeplr application.\n');
+
+  var session = prompt.createSession();
+  try {
+    var answers = await questions.collect(session, argv[1]);
+    console.log(plan.describe(answers));
+
+    var go = await session.confirm('  Create it?', true);
+    if (!go) {
+      console.log('\n  Nothing was written.\n');
+      return 0;
+    }
+  } finally {
+    session.close();
+  }
+
+  var target = path.resolve(process.cwd(), answers.name);
+  var result = generate.generate(answers, target);
+  console.log('\n  Wrote ' + result.written.length + ' files.');
+  console.log(nextSteps.describe(answers, target));
+  return 0;
+}
+
+main().then(function (code) { process.exit(code); }, function (err) {
+  console.error('\n  ' + (err && err.message ? err.message : err) + '\n');
+  process.exit(1);
+});

package/lib/commands/encrypt.js

@@ -0,0 +1,144 @@
+var fs = require('fs');
+var path = require('path');
+var { encrypt } = require('@xeplr/utils/isomorphic/crypto');
+
+// Where a settings file usually is, relative to wherever this was run.
+// Running it from the project root and from inside api/ are both normal.
+var CANDIDATES = ['development.env', path.join('api', 'development.env')];
+
+function findEnvFile(cwd) {
+  for (var i = 0; i < CANDIDATES.length; i++) {
+    var full = path.join(cwd, CANDIDATES[i]);
+    if (fs.existsSync(full)) return full;
+  }
+  return null;
+}
+
+function readSetting(file, name) {
+  var line = fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .find(function (l) { return l.indexOf(name + '=') === 0; });
+  return line ? line.slice(name.length + 1).trim() : null;
+}
+
+/**
+ * Rewrite every setting that holds a connection string.
+ *
+ * BOTH of them, always. The two settings name the same server, and a project
+ * where only one was updated fails halfway through setup — the sign-in
+ * database is created and the app's own is not, or the reverse — which reads
+ * as a broken install rather than as a half-finished edit.
+ */
+function writeConnection(file, value) {
+  var body = fs.readFileSync(file, 'utf8');
+  var updated = [];
+  body = body.split('\n').map(function (line) {
+    var m = line.match(/^([A-Z0-9_]*CONNECTION[A-Z0-9_]*)=/);
+    if (!m) return line;
+    updated.push(m[1]);
+    return m[1] + '=' + value;
+  }).join('\n');
+  fs.writeFileSync(file, body);
+  return updated;
+}
+
+/**
+ * `xeplr encrypt` — turn database details into the single string the settings
+ * file holds, and optionally write it straight in.
+ *
+ * Exists because the details change: a password rotates, the database moves,
+ * or the first answer was simply wrong. Without this the only way back is a
+ * long npx command with two --package flags whose output has to be pasted into
+ * two places — which is exactly the kind of step people get wrong at the point
+ * they are already frustrated.
+ */
+function parseFlags(argv) {
+  var flags = {};
+  (argv || []).forEach(function (arg, i) {
+    var m = arg.match(/^--([a-z-]+)(?:=(.*))?$/);
+    if (!m) return;
+    var value = m[2] !== undefined ? m[2] : (argv[i + 1] || '');
+    // A flag whose "value" is the next flag was given with nothing after it.
+    flags[m[1]] = /^--/.test(value) ? '' : value;
+  });
+  return flags;
+}
+
+/**
+ * Ask, unless it was already given on the command line.
+ *
+ * Every value here can arrive either way, so the same command serves somebody
+ * typing at a terminal and a script that has no terminal to type at. A
+ * password on a command line is visible in shell history and in the process
+ * list, so the prompt stays the default and the flag is the opt-in.
+ */
+function given(flags, name, fallback) {
+  return Object.prototype.hasOwnProperty.call(flags, name) ? flags[name] : fallback;
+}
+
+async function run(session, argv, cwd) {
+  cwd = cwd || process.cwd();
+  var flags = parseFlags(argv);
+  var envFile = findEnvFile(cwd);
+
+  // The key must match the one the project already uses, or nothing it wrote
+  // before can be read back. So it is taken FROM the project rather than
+  // asked for, whenever there is a project to take it from.
+  var key = given(flags, 'key', null);
+  if (!key && envFile) {
+    key = readSetting(envFile, 'ENCRYPTION_KEY');
+    if (key) console.log('\n  Using ENCRYPTION_KEY from ' + path.relative(cwd, envFile));
+  }
+  if (!key) {
+    console.log('\n  No settings file found here, so the key has to be given.');
+    key = await session.ask('  ENCRYPTION_KEY?', {
+      validate: function (v) { return v.length >= 16 ? true : 'That looks too short.'; }
+    });
+  }
+
+  var host = given(flags, 'host', null) ||
+    await session.ask('  Database host?', { default: 'localhost' });
+
+  var port = given(flags, 'port', null) ||
+    await session.ask('  Database port?', {
+      default: '5432',
+      validate: function (v) { return /^\d+$/.test(v) ? true : 'A number.'; }
+    });
+
+  var user = given(flags, 'user', null) ||
+    await session.ask('  Database user?', { default: 'postgres' });
+
+  // hasOwnProperty rather than a truthiness check: --password= with nothing
+  // after it means an EMPTY password, which some local installs really do
+  // have, and must not silently turn into a prompt.
+  var password = Object.prototype.hasOwnProperty.call(flags, 'password')
+    ? flags.password
+    : await session.askSecret('  Database password?');
+
+  var value = await encrypt(JSON.stringify({
+    host: host, port: Number(port), user: user, password: password
+  }), key);
+
+  console.log('\n  Encrypted connection:\n');
+  console.log('  ' + value + '\n');
+
+  if (!envFile) {
+    console.log('  Paste it into every *_CONNECTION setting in your');
+    console.log('  development.env, and into AUTH_DB_CONNECTION_INFO_ENCRYPTED.\n');
+    return 0;
+  }
+
+  var write = Object.prototype.hasOwnProperty.call(flags, 'no-write') ? false
+    : Object.prototype.hasOwnProperty.call(flags, 'write') ? true
+    : await session.confirm('  Write it into ' + path.relative(cwd, envFile) + ' now?', true);
+  if (!write) {
+    console.log('\n  Left alone. Paste it in yourself when ready.\n');
+    return 0;
+  }
+
+  var updated = writeConnection(envFile, value);
+  console.log('\n  Updated ' + updated.length + ' settings: ' + updated.join(', ') + '\n');
+  return 0;
+}
+
+module.exports = { run: run, parseFlags: parseFlags, findEnvFile: findEnvFile, writeConnection: writeConnection };

package/lib/generate/index.js

@@ -0,0 +1,147 @@
+var fs = require('fs');
+var path = require('path');
+
+var TEMPLATES = path.join(__dirname, '..', '..', 'templates');
+
+// Files whose names cannot ship as-is. `.env` and `.gitignore` are both
+// swallowed on the way here — npm refuses to pack a .gitignore, and an .env in
+// a published package is a mistake waiting to happen — so they travel under a
+// safe name and are restored on the way out.
+var RENAME = {
+  'development.env.tpl': 'development.env',
+  'dotenv.tpl': '.env',
+  'gitignore.tpl': '.gitignore'
+};
+
+// Everything the templates can refer to. One table, so a placeholder that is
+// never filled shows up as a missing key rather than as the literal
+// __SOMETHING__ in a generated file.
+function substitutions(answers) {
+  return {
+    __NAME__: answers.name,
+    __PREFIX__: answers.prefix,
+    __UI_PORT__: String(answers.ports.ui),
+    __AUTH_PORT__: String(answers.ports.auth),
+    __API_PORT__: String(answers.ports.api),
+    __ENCRYPTION_KEY__: answers.secrets.encryptionKey,
+    __JWT_SECRET__: answers.secrets.jwtSecret,
+    __ADMIN_EMAIL__: answers.admin.email,
+    __ADMIN_PASSWORD__: answers.admin.password,
+    __DB_CONNECTION__: answers.connection || '',
+    __CONNECTION_NOTE__: connectionNote(answers)
+  };
+}
+
+/**
+ * The comment above the connection setting.
+ *
+ * Two different situations, and a reader in the second one needs a command
+ * rather than an explanation of why the line is empty.
+ */
+function connectionNote(answers) {
+  if (answers.connection) {
+    return [
+      '# ── Where the databases are ──',
+      '# Host, port, user and password, encrypted together from what you told',
+      '# the installer. One value is enough because everything needed is inside',
+      '# it. Both settings use the same server.',
+      '#',
+      '# CHANGED? From the api folder, this replaces both lines for you:',
+      '#',
+      '#   npm run db:encrypt'
+    ].join('\n');
+  }
+  return [
+    '# ═══════════════════════════════════════════════════════════════════════',
+    '#  FILL THESE IN BEFORE STARTING ANYTHING',
+    '#',
+    '#  From the api folder, after `npm install`, this fills both lines in:',
+    '#',
+    '#    npm run db:encrypt',
+    '#',
+    '#  Before installing, or from anywhere else:',
+    '#',
+    '#    npx @xeplr/cli encrypt',
+    '#',
+    '#  Blank on purpose. A guessed database location starts cleanly, migrates,',
+    '#  serves traffic, and reads as EMPTY DATA rather than as an error — so',
+    '#  nothing is guessed. Until these are filled in the app refuses to start',
+    '#  and names them.',
+    '# ═══════════════════════════════════════════════════════════════════════'
+  ].join('\n');
+}
+
+function fill(body, subs) {
+  // The inner name must START and END with a letter or digit.
+  //
+  // Without that, a greedy match on `__PREFIX___PORT` takes `__PREFIX___` —
+  // swallowing the underscore that belongs to `_PORT` — and then complains
+  // about a token nobody wrote. Anchoring both ends makes `__PREFIX__` the
+  // only possible match, leaving `_PORT` alone.
+  return body.replace(/__([A-Z][A-Z0-9_]*[A-Z0-9])__/g, function (token) {
+    // An unknown placeholder is a bug in the templates, and leaving it in the
+    // generated file would be found much later by somebody who did not write
+    // it. Fail here, naming the token.
+    if (!(token in subs)) throw new Error('Template refers to ' + token + ', which nothing fills in');
+    return subs[token];
+  });
+}
+
+function isBinary(file) {
+  return /\.(png|jpe?g|gif|ico|woff2?|ttf)$/i.test(file);
+}
+
+function walk(dir) {
+  var out = [];
+  fs.readdirSync(dir).forEach(function (entry) {
+    var full = path.join(dir, entry);
+    if (fs.statSync(full).isDirectory()) return out.push.apply(out, walk(full));
+    out.push(full);
+  });
+  return out;
+}
+
+/**
+ * Write the project.
+ *
+ * REFUSES TO OVERWRITE. Generating into a folder that already has something in
+ * it is how somebody loses work they had not committed, and the check is one
+ * line.
+ *
+ * @param {object} answers  from lib/questions.js
+ * @param {string} target   absolute path of the folder to create
+ * @returns {{ written: string[] }}
+ */
+function generate(answers, target) {
+  if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+    throw new Error(target + ' already exists and is not empty.');
+  }
+
+  var subs = substitutions(answers);
+  var written = [];
+
+  walk(TEMPLATES).forEach(function (src) {
+    var rel = path.relative(TEMPLATES, src);
+    var dir = path.dirname(rel);
+    var base = path.basename(rel);
+    var outName = RENAME[base] || base;
+    var dest = path.join(target, dir, outName);
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+    if (isBinary(src)) {
+      fs.copyFileSync(src, dest);
+    } else {
+      fs.writeFileSync(dest, fill(fs.readFileSync(src, 'utf8'), subs));
+    }
+
+    // bin/www is executed directly, so it has to keep the bit that says so.
+    if (outName === 'www') fs.chmodSync(dest, 0o755);
+
+    written.push(path.join(dir, outName));
+  });
+
+  return { written: written.sort() };
+}
+
+module.exports = { generate: generate, substitutions: substitutions, fill: fill };

package/lib/nextSteps.js

@@ -0,0 +1,39 @@
+/**
+ * What to do now that the files exist.
+ *
+ * Printed at the end because the one thing a generator cannot do for you is
+ * the database connection — and a project that looks finished but will not
+ * start is worse than one that says what is left.
+ */
+function describe(answers, dir) {
+  var p = answers.prefix;
+  var head = ['', '  Created ' + dir, ''];
+
+  if (!answers.connection) {
+    head = head.concat([
+      '  ONE THING LEFT — your database connection:',
+      '',
+      '    cd ' + answers.name + '/api  &&  npm install  &&  npm run db:encrypt',
+      '',
+      '  It asks for your database details and fills them in for you.',
+      ''
+    ]);
+  }
+
+  return head.concat([
+    '  Then:',
+    '',
+    '    cd ' + answers.name + '/api   &&  npm install  &&  npm run setup',
+    '    npm run start-auth            # sign-in, port ' + answers.ports.auth,
+    '    npm run start-api             # your API, port ' + answers.ports.api,
+    '',
+    '    cd ../ui                      &&  npm install',
+    '    npm run dev                   # the app, port ' + answers.ports.ui,
+    '',
+    '  Then open http://localhost:' + answers.ports.ui + ' and sign in as',
+    '  ' + answers.admin.email + '.',
+    ''
+  ]).join('\n');
+}
+
+module.exports = { describe: describe };

package/lib/plan.js

@@ -0,0 +1,44 @@
+/**
+ * What the generator is about to do, printed before it does any of it.
+ *
+ * A generator that writes 30 files and then tells you is one you have to undo
+ * by hand when an answer was wrong. This is the last point where "no" is free.
+ */
+function describe(answers) {
+  var L = [];
+  var p = answers.prefix;
+
+  L.push('');
+  L.push('  ' + answers.name + '/');
+  L.push('  ├─ api/     backend, on port ' + answers.ports.api);
+  L.push('  └─ ui/      frontend, on port ' + answers.ports.ui);
+  L.push('');
+  L.push('  Sign-in runs alongside the API on port ' + answers.ports.auth + '.');
+  L.push('');
+  L.push('  Databases (created for you on first run):');
+  L.push('    ' + answers.databases.auth + '    accounts, roles, permissions');
+  L.push('    ' + answers.databases.api + '     your own data');
+  L.push('');
+  L.push('  You will sign in as ' + answers.admin.email + '.');
+  L.push('');
+  L.push('  Settings written for you:');
+  L.push('    ' + p + '_PORT, AUTH_PORT, AUTH_URL, DB_API, AUTH_DB_NAME');
+  L.push('    ENCRYPTION_KEY and AUTH_JWT_SECRET      generated, not asked');
+  L.push('    AUTH_SUPER_ADMIN_EMAIL / _PASSWORD      from your answers');
+  L.push('');
+  if (answers.connection) {
+    L.push('    ' + p + '_CONNECTION                        encrypted from your answers');
+    L.push('');
+  } else {
+    L.push('');
+    L.push('  Left BLANK, for you to fill in:');
+    L.push('    ' + p + '_CONNECTION and AUTH_DB_CONNECTION_INFO_ENCRYPTED');
+    L.push('');
+    L.push('  Run `npx @xeplr/cli encrypt` in the project to fill them in.');
+    L.push('  Until then the app refuses to start and names them.');
+    L.push('');
+  }
+  return L.join('\n');
+}
+
+module.exports = { describe: describe };