@dokebi/cli 0.4.1 → 0.4.26

package/dist/recipe-login.js

@@ -0,0 +1,464 @@
+// The admin login of `dokebi recipe blog --admin login` (D-0076 §6): the user code the recipe
+// writes after `add @dokebi/auth`. The user table and its column names are the app's own
+// (app_members: member_no, login_name, pass_phc, logout_key, is_active, role), so the generated
+// extension class shows how @dokebi/auth maps any table; nothing here knows the plugin's
+// internals. Every file is user code from the moment it is written. D-0115: a project an older
+// recipe made keeps blog_authors and its names (recipeLoginNames), byte for byte.
+//
+// Files: the auth extension (replaces the untouched template of `add`), a migration and a seed
+// of connection main for the database dialect, the login routes and two pages of the main app
+// for the view (EJS or Inertia), and one line in src/apps/main/routes.ts. dokebi.yaml gets
+// `options.first-admin` with the login name and a generated initial password the seed hashes
+// (D-0115: a project an older recipe gave `options.blog-admin` keeps that name).
+import { CliError } from './errors.js';
+import { LEGACY_LOGIN_NAMES, LOGIN_NAMES, MEMBER_MODEL, memberExtension, memberFiles, USERS_TABLE, } from './recipe-members.js';
+import { resetFiles } from './recipe-reset.js';
+/**
+ * The dokebi.yaml section the first admin comes from (no plugin owns it). D-0115: named for what
+ * it holds (the first admin, like the seed first-admin.ts), not for one kind of app.
+ */
+export const ADMIN_SECTION = 'first-admin';
+/** The name older recipes wrote (until D-0115); such projects keep it and keep working. */
+export const LEGACY_ADMIN_SECTION = 'blog-admin';
+/** Both names the CLI reads (config show, check, verify). */
+export const ADMIN_SECTIONS = [ADMIN_SECTION, LEGACY_ADMIN_SECTION];
+/** The key of the generated initial password in that section (never printed). */
+export const ADMIN_PASSWORD_KEY = 'initialPassword';
+/** The login name of the first admin. */
+export const ADMIN_LOGIN = 'admin';
+/** The table (collection) of the app's users, and the names of its code (D-0115). */
+export { LEGACY_LOGIN_NAMES, LOGIN_NAMES, USERS_TABLE };
+/** The one sentence of every failed login (never tell an unknown name from a wrong password). */
+export const LOGIN_FAILED = 'Invalid login or password.';
+/** Where a login goes, and the auth `homePath` (a signed-in user on the login page goes there). */
+export const ADMIN_PATH = '/admin';
+export const EXTENSION_FILE = 'src/infra/auth/extension.ts';
+export const SEED_FILE = 'src/infra/db/seeds/main/first-admin.ts';
+/**
+ * The section the recipe writes the first admin into (D-0115): the older name when the project
+ * already uses it (its section in dokebi.yaml, or the seed an older recipe wrote reads it), so a
+ * recipe applied again never splits one admin over two sections; otherwise ADMIN_SECTION.
+ */
+export function recipeAdminSection(options, seedText = '') {
+    if (Object.hasOwn(options, ADMIN_SECTION))
+        return ADMIN_SECTION;
+    if (Object.hasOwn(options, LEGACY_ADMIN_SECTION) ||
+        seedText.includes(`options['${LEGACY_ADMIN_SECTION}']`))
+        return LEGACY_ADMIN_SECTION;
+    return ADMIN_SECTION;
+}
+const MIGRATIONS = 'src/infra/db/migrations/main';
+/**
+ * The names of the login code for this project (D-0115): an older recipe's blog_authors when the
+ * project has its migration, or a model, extension or seed that names that table; otherwise
+ * LOGIN_NAMES. So migrationPath and a recipe applied again never make a second table or a
+ * migration that conflicts with the one the project has.
+ */
+export function recipeLoginNames(migrations, sources = []) {
+    const legacy = LEGACY_LOGIN_NAMES;
+    if (migrations.some((name) => new RegExp(`^\\d{14}_${legacy.migration}\\.ts$`).test(name)) ||
+        sources.some((text) => text.includes(legacy.table)))
+        return legacy;
+    return LOGIN_NAMES;
+}
+/** The project files that tell an older recipe's login code (recipeLoginNames). */
+export const LOGIN_NAME_SOURCES = [MEMBER_MODEL, EXTENSION_FILE, SEED_FILE];
+const APP = 'src/apps/main';
+/** `20261017093000`: the UTC time a new migration file is named after (dokebi-migrate make). */
+export function migrationStamp(date) {
+    return date.toISOString().replace(/\D/g, '').slice(0, 14);
+}
+/** The migration file this project already has, else a new name for `now`. */
+export function migrationPath(existing, now, names = recipeLoginNames(existing)) {
+    const found = existing.find((name) => new RegExp(`^\\d{14}_${names.migration}\\.ts$`).test(name));
+    return `${MIGRATIONS}/${found ?? `${migrationStamp(now)}_${names.migration}.ts`}`;
+}
+export const MIGRATIONS_DIRECTORY = MIGRATIONS;
+const HEADER = (what) => `// ${what}, written by \`dokebi recipe blog --admin login\` (D-0076 §6); user code from now on.`;
+// --- migration ------------------------------------------------------------------------------
+const MIGRATION_INTRO = (dialect) => `${HEADER(`Migration of connection main (${dialect})`)}
+// The app's own user table for @dokebi/auth: the column names are this app's, mapped in
+// src/infra/auth/extension.ts. Run it with npx dokebi-migrate up (never at app start).
+`;
+function migration(dialect, n) {
+    if (dialect === 'postgres')
+        return `${MIGRATION_INTRO(dialect)}import type { PoolClient as Db } from 'pg';
+
+export async function up(db: Db): Promise<void> {
+  await db.query(\`CREATE TABLE ${n.table} (
+    ${n.id.padEnd(10)} serial PRIMARY KEY,
+    login_name text NOT NULL UNIQUE,
+    pass_phc   text,
+    logout_key text NOT NULL,
+    is_active  boolean NOT NULL DEFAULT true,
+    role       text NOT NULL DEFAULT '${n.role}',
+    created_at timestamptz NOT NULL DEFAULT now()
+  )\`);
+}
+
+export async function down(db: Db): Promise<void> {
+  await db.query('DROP TABLE ${n.table}');
+}
+`;
+    if (dialect === 'mongodb')
+        return `${MIGRATION_INTRO(dialect)}// MongoDB has no transactions here: each step can run again.
+import type { Db } from 'mongodb';
+
+async function exists(db: Db): Promise<boolean> {
+  const found = await db.listCollections({ name: '${n.table}' }, { nameOnly: true }).toArray();
+  return found.length > 0;
+}
+
+export async function up(db: Db): Promise<void> {
+  if (!(await exists(db))) await db.createCollection('${n.table}');
+  await db
+    .collection('${n.table}')
+    .createIndex({ login_name: 1 }, { unique: true, name: 'login_name_unique' });
+}
+
+export async function down(db: Db): Promise<void> {
+  if (await exists(db)) await db.dropCollection('${n.table}');
+}
+`;
+    const type = dialect === 'mysql'
+        ? "import type { PoolConnection as Db } from 'mysql2/promise';"
+        : "import type { PoolConnection as Db } from 'mariadb';";
+    return `${MIGRATION_INTRO(dialect)}// DDL commits at once: one statement, safe to run again (IF NOT EXISTS).
+${type}
+
+export async function up(db: Db): Promise<void> {
+  await db.query(\`CREATE TABLE IF NOT EXISTS ${n.table} (
+    ${n.id.padEnd(10)} int AUTO_INCREMENT PRIMARY KEY,
+    login_name varchar(190) NOT NULL UNIQUE,
+    pass_phc   varchar(255) NULL,
+    logout_key varchar(64) NOT NULL,
+    is_active  boolean NOT NULL DEFAULT true,
+    role       varchar(32) NOT NULL DEFAULT '${n.role}',
+    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP
+  ) CHARACTER SET utf8mb4\`);
+}
+
+export async function down(db: Db): Promise<void> {
+  await db.query('DROP TABLE IF EXISTS ${n.table}');
+}
+`;
+}
+// --- seed -----------------------------------------------------------------------------------
+const SEED_INTRO = (section) => `${HEADER('Seed of connection main: the first admin')}
+// The login name and the initial password come from dokebi.yaml (options.${section}); the
+// password is hashed with passwords.hash and never stored, logged or printed in clear. It runs
+// again safely: an existing admin is left as it is, so a changed password is never reset, and
+// once the admin exists the initial password may be removed from dokebi.yaml.
+// Run it with npx dokebi-migrate seed (after npx dokebi-migrate up).
+`;
+const SEED_CONFIG = (section) => `/** options.${section} of dokebi.yaml (this file is src/infra/db/seeds/main/). */
+async function firstAdmin(): Promise<{ login: string; password(): string }> {
+  const config = await loadConfig(new URL('../../../../../dokebi.yaml', import.meta.url));
+  const section: unknown = config.options['${section}'];
+  const values = (section && typeof section === 'object' ? section : {}) as Record<string, unknown>;
+  const login =
+    typeof values.login === 'string' && values.login.trim()
+      ? values.login.trim().toLowerCase()
+      : '${ADMIN_LOGIN}';
+  return {
+    login,
+    // Read only when the admin does not exist yet.
+    password() {
+      const value = values.${ADMIN_PASSWORD_KEY};
+      if (typeof value !== 'string' || value.length < 12)
+        throw new Error(
+          'Set options.${section}.${ADMIN_PASSWORD_KEY} (12 characters or more) in dokebi.yaml: the first admin does not exist yet',
+        );
+      return value;
+    },
+  };
+}
+`;
+function seed(dialect, section, n) {
+    const imports = `import { randomBytes } from 'node:crypto';
+import { passwords } from '@dokebi/auth';
+import { loadConfig } from '@dokebi/core';
+`;
+    const body = dialect === 'postgres'
+        ? `import type { PoolClient as Db } from 'pg';
+
+${SEED_CONFIG(section)}
+export async function run(db: Db): Promise<void> {
+  const admin = await firstAdmin();
+  const found = await db.query('SELECT 1 FROM ${n.table} WHERE login_name = $1', [admin.login]);
+  if (found.rowCount) return;
+  await db.query(
+    "INSERT INTO ${n.table} (login_name, pass_phc, logout_key, role) VALUES ($1, $2, $3, 'admin') ON CONFLICT (login_name) DO NOTHING",
+    [admin.login, await passwords.hash(admin.password()), randomBytes(16).toString('base64url')],
+  );
+}
+`
+        : dialect === 'mongodb'
+            ? `import type { Db } from 'mongodb';
+
+${SEED_CONFIG(section)}
+export async function run(db: Db): Promise<void> {
+  const admin = await firstAdmin();
+  const ${n.rows} = db.collection('${n.table}');
+  if (await ${n.rows}.findOne({ login_name: admin.login }, { projection: { _id: 1 } })) return;
+  await ${n.rows}.updateOne(
+    { login_name: admin.login },
+    {
+      $setOnInsert: {
+        login_name: admin.login,
+        pass_phc: await passwords.hash(admin.password()),
+        logout_key: randomBytes(16).toString('base64url'),
+        is_active: true,
+        role: 'admin',
+        created_at: new Date(),
+      },
+    },
+    { upsert: true },
+  );
+}
+`
+            : `import type { PoolConnection as Db${dialect === 'mysql' ? ', RowDataPacket' : ''} } from '${dialect === 'mysql' ? 'mysql2/promise' : 'mariadb'}';
+
+${SEED_CONFIG(section)}
+export async function run(db: Db): Promise<void> {
+  const admin = await firstAdmin();
+  ${dialect === 'mysql'
+                ? `const [found] = await db.query<RowDataPacket[]>(
+    'SELECT 1 FROM ${n.table} WHERE login_name = ?',
+    [admin.login],
+  );`
+                : `const found = await db.query<unknown[]>('SELECT 1 FROM ${n.table} WHERE login_name = ?', [
+    admin.login,
+  ]);`}
+  if (found.length) return;
+  await db.query(
+    "INSERT IGNORE INTO ${n.table} (login_name, pass_phc, logout_key, role) VALUES (?, ?, ?, 'admin')",
+    [admin.login, await passwords.hash(admin.password()), randomBytes(16).toString('base64url')],
+  );
+}
+`;
+    return `${SEED_INTRO(section)}${imports}${body}`;
+}
+// --- routes and pages -----------------------------------------------------------------------
+function authController(view, n) {
+    return view === 'ejs'
+        ? `// Login controller of the main app, written by \`dokebi recipe blog --admin login\` (D-0076 §6); user code from now on.
+// @dokebi/auth checks the password, throttles and starts a new session (request.auth.attempt);
+// this file only shows the pages. One sentence for every failed login: never tell an unknown login
+// name from a wrong password. @dokebi/csrf checks every POST (the pages send the token).
+import type { AppPage } from '@dokebi/app';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { validationError } from '@dokebi/web';
+
+/** The only failure sentence of the login form. */
+export const LOGIN_FAILED = '${LOGIN_FAILED}';
+
+export class AuthController {
+  loginPage(_request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    return page.view.reply(reply, 'login', {});
+  }
+  async login(request: FastifyRequest, reply: FastifyReply) {
+    const { login, password } = (request.body ?? {}) as Record<string, unknown>;
+    const result = await request.auth.attempt({
+      identity: typeof login === 'string' ? login : '',
+      password: typeof password === 'string' ? password : '',
+    });
+    // invalid, inactive or throttled: the form comes back (303) with the same sentence.
+    if (!result.ok) throw validationError({ login: LOGIN_FAILED });
+    return reply.redirect(await request.auth.takeReturnPath('${ADMIN_PATH}'), 303);
+  }
+  async logout(request: FastifyRequest, reply: FastifyReply) {
+    await request.auth.logout();
+    return reply.redirect('/', 303);
+  }
+  async dashboard(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    return page.view.reply(reply, 'admin', { canWrite: await request.auth.can('${n.ability}') });
+  }
+}
+`
+        : `// Login controller of the main app, written by \`dokebi recipe blog --admin login\` (D-0076 §6); user code from now on.
+// @dokebi/auth checks the password, throttles and starts a new session (request.auth.attempt);
+// this file only shows the pages. One sentence for every failed login: never tell an unknown login
+// name from a wrong password. @dokebi/csrf checks every POST (the pages send the token).
+import type { AppPage, AppInertia } from '@dokebi/app';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { validationError } from '@dokebi/web';
+
+/** The only failure sentence of the login form. */
+export const LOGIN_FAILED = '${LOGIN_FAILED}';
+
+function inertia(page: AppPage): AppInertia {
+  if (!page.inertia) throw new Error('Add @dokebi/template-inertia for this app');
+  return page.inertia;
+}
+
+export class AuthController {
+  loginPage(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    return inertia(page).render(request, reply, 'Login');
+  }
+  async login(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    const { login, password } = (request.body ?? {}) as Record<string, unknown>;
+    const result = await request.auth.attempt({
+      identity: typeof login === 'string' ? login : '',
+      password: typeof password === 'string' ? password : '',
+    });
+    // invalid, inactive or throttled: form.errors.login gets the same sentence.
+    if (!result.ok) throw validationError({ login: LOGIN_FAILED });
+    return inertia(page).redirect(request, reply, await request.auth.takeReturnPath('${ADMIN_PATH}'));
+  }
+  async logout(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    await request.auth.logout();
+    return inertia(page).redirect(request, reply, '/');
+  }
+  async dashboard(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    return inertia(page).render(request, reply, 'Admin', {
+      canWrite: await request.auth.can('${n.ability}'),
+    });
+  }
+}
+`;
+}
+function routes(view) {
+    const args = view === 'ejs' ? 'request, reply' : 'request, reply, page';
+    return `import type { AppRouter } from '@dokebi/app';
+import { AuthController } from '../controllers/auth.ts';
+
+export function loginRoutes(route: AppRouter): void {
+  const controller = new AuthController();
+  route.get('/login', (_request, reply, page) => controller.loginPage(_request, reply, page), {
+    config: { auth: 'guest' },
+  });
+  route.post('/login', (${args}) => controller.login(${args}), { config: { auth: 'guest' } });
+  route.post('/logout', (${args}) => controller.logout(${args}), { config: { auth: false } });
+  route.get('/admin', (request, reply, page) => controller.dashboard(request, reply, page), { config: { auth: 'required' } });
+}
+`;
+}
+const LOGIN_EJS = `<main>
+  <h1>Sign in</h1>
+  <form method="post" action="/login">
+    <%- data.csrf.field %>
+    <% if (data.errors.login) { %><p role="alert"><%= data.errors.login %></p><% } %>
+    <label>Login <input name="login" value="<%= data.old.login ?? '' %>" autocomplete="username" required></label>
+    <label>Password <input name="password" type="password" autocomplete="current-password" required></label>
+    <button>Sign in</button>
+  </form>
+</main>
+`;
+const ADMIN_EJS = (n) => `<main>
+  <h1>Admin</h1>
+  <p>Signed in as <%= data.auth.user?.login %> (<%= data.auth.user?.role %>).</p>
+  <% if (data.canWrite) { %><p>${n.mayWrite}</p><% } %>
+  <form method="post" action="/logout">
+    <%- data.csrf.field %>
+    <button>Sign out</button>
+  </form>
+</main>
+`;
+const LOGIN_VUE = `<script setup lang="ts">
+import { useForm } from '@inertiajs/vue3';
+
+// @dokebi/csrf: Inertia sends the XSRF-TOKEN cookie as the X-XSRF-TOKEN header by itself.
+const form = useForm({ login: '', password: '' });
+function submit() {
+  // A failed login changes only the errors; a successful one opens another page.
+  form.post('/login', { only: ['errors'], onFinish: () => form.reset('password') });
+}
+</script>
+<template>
+  <h1>Sign in</h1>
+  <form @submit.prevent="submit">
+    <p v-if="form.errors.login" role="alert">{{ form.errors.login }}</p>
+    <label>Login <input v-model="form.login" autocomplete="username" required /></label>
+    <label>Password <input v-model="form.password" type="password" autocomplete="current-password" required /></label>
+    <button :disabled="form.processing">Sign in</button>
+  </form>
+</template>
+`;
+const ADMIN_VUE = (n) => `<script setup lang="ts">
+import { router, usePage } from '@inertiajs/vue3';
+
+defineProps<{ canWrite: boolean }>();
+// @dokebi/auth shares the signed-in user as \`auth\`; typed here, so the template is checked.
+const page = usePage<{ auth?: { user?: { login: string; role: string } } }>();
+function signOut() {
+  // dokebi-check: allow inertia-form-only signing out opens another page with all its props
+  router.post('/logout');
+}
+</script>
+<template>
+  <h1>Admin</h1>
+  <p>Signed in as {{ page.props.auth?.user?.login }} ({{ page.props.auth?.user?.role }}).</p>
+  <p v-if="canWrite">${n.mayWrite}</p>
+  <button type="button" @click="signOut">Sign out</button>
+</template>
+`;
+/** Every file of the admin login for a dialect and view (the migration path decided by the caller). */
+export function loginFiles(dialect, view, migrationFile, mail = false, 
+/** The section of dokebi.yaml the seed reads (recipeAdminSection). */
+section = ADMIN_SECTION, 
+/** The table and code names (recipeLoginNames, D-0115). */
+names = LOGIN_NAMES) {
+    const pages = view === 'ejs'
+        ? [
+            {
+                path: `${APP}/views/default/login.ejs`,
+                content: mail
+                    ? LOGIN_EJS.replace('</form>', '</form><p><a href="/password/forgot">Forgot your password?</a></p>')
+                    : LOGIN_EJS,
+            },
+            { path: `${APP}/views/default/admin.ejs`, content: ADMIN_EJS(names) },
+        ]
+        : [
+            {
+                path: `${APP}/views/default/Pages/Login.vue`,
+                content: mail
+                    ? LOGIN_VUE.replace('</form>', '</form><p><a href="/password/forgot">Forgot your password?</a></p>')
+                    : LOGIN_VUE,
+            },
+            { path: `${APP}/views/default/Pages/Admin.vue`, content: ADMIN_VUE(names) },
+        ];
+    return [
+        {
+            path: EXTENSION_FILE,
+            content: memberExtension(dialect, names),
+            replaceTemplate: true,
+        },
+        ...memberFiles(dialect, names),
+        { path: migrationFile, content: migration(dialect, names) },
+        { path: SEED_FILE, content: seed(dialect, section, names) },
+        {
+            path: `${APP}/routes/auth.ts`,
+            content: mail
+                ? `import { passwordResetRoutes } from './password-reset.ts';\n${routes(view)}`.replace('export function loginRoutes(route: AppRouter): void {', 'export function loginRoutes(route: AppRouter): void {\n  passwordResetRoutes(route);')
+                : routes(view),
+        },
+        { path: `${APP}/controllers/auth.ts`, content: authController(view, names) },
+        ...pages,
+        ...(mail ? resetFiles() : []),
+    ];
+}
+/**
+ * src/apps/main/routes.ts with the login routes added: an import after the last import and a call
+ * at the top of `routes(route, …)`. Unchanged when already there; RECIPE_FILE_CONFLICT when the
+ * file has no `export function routes(<router>…)` to add it to.
+ */
+export function withLoginRoutes(text) {
+    if (/\bloginRoutes\(/.test(text))
+        return text;
+    const start = /export function routes\(\s*(\w+)[^)]*\)[^{]*\{\n/.exec(text);
+    const imports = [...text.matchAll(/^import [^;]*;\n/gm)].at(-1);
+    if (!start || !imports)
+        throw new CliError('RECIPE_FILE_CONFLICT', `${APP}/routes.ts has no export function routes(route, …) to add the login routes to`, {
+            details: {
+                path: `${APP}/routes.ts`,
+                fix: `call loginRoutes(route) from ${APP}/routes/auth.ts in your routes yourself`,
+            },
+        });
+    const call = `  // Login, sign-out and the admin page (dokebi recipe blog --admin login).\n  loginRoutes(${start[1]});\n`;
+    const at = (start.index ?? 0) + start[0].length;
+    const withCall = `${text.slice(0, at)}${call}${text.slice(at)}`;
+    const after = (imports.index ?? 0) + imports[0].length;
+    return `${withCall.slice(0, after)}import { loginRoutes } from './routes/auth.ts';\n${withCall.slice(after)}`;
+}
+export const ROUTES_FILE = `${APP}/routes.ts`;

package/dist/recipe-mail.d.ts

@@ -0,0 +1,21 @@
+import type { Project } from './project.js';
+import type { ProjectView, Step } from './recipe-step.js';
+export declare const MAIL_COMPOSE = "compose.mail.yaml";
+export interface MailPorts {
+    smtp: number;
+    inbox: number;
+    nats: number;
+}
+/** Omitting ports reproduces the legacy template for safe migration only. */
+export declare function mailCompose(root: string, ports?: MailPorts): string;
+/** Accept only an untouched generated template; never infer ownership from a filename. */
+export declare function mailComposePorts(root: string, source: string): MailPorts | undefined;
+export declare function checkMailCompose(root: string): Promise<void>;
+/** Reserve three distinct loopback ports together, then persist them before Docker starts. */
+export declare function allocateMailPorts(): Promise<MailPorts>;
+export declare function mailSteps(input: {
+    root: string;
+    project: Project;
+    choice: string | undefined;
+    now(): Promise<ProjectView | undefined>;
+}): Step[];