firstly 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # firstly
 
+## 0.10.2
+
+### Patch Changes
+
+- [#366](https://github.com/jycouet/firstly/pull/366) [`2c661f6`](https://github.com/jycouet/firstly/commit/2c661f6474b8614733e5494e7deda3cd069aed9c) Thanks [@jycouet](https://github.com/jycouet)! - `ff` handles: read failed writes through `errorMessage()`. Remult rejects with a plain object, not
+  an `Error`, so `handle.error` used to end up as the string `[object Object]` on a 403.
+
+## 0.10.1
+
+### Patch Changes
+
+- [#365](https://github.com/jycouet/firstly/pull/365) [`cf68997`](https://github.com/jycouet/firstly/commit/cf68997ca89672c2026ea502d197a670b942f4c0) Thanks [@jycouet](https://github.com/jycouet)! - Expose `firstly/cron` (`Roles_Cron`, `Cron`) so client code can import them, like `firstly/changeLog` already does.
+
+- [#364](https://github.com/jycouet/firstly/pull/364) [`fcd660e`](https://github.com/jycouet/firstly/commit/fcd660ef5a8677f2dad6d4c8bc1017ae2fe46574) Thanks [@jycouet](https://github.com/jycouet)! - Accept SvelteKit 3 as a peer, prereleases included (`3.0.0-next.x`).
+
+- [#362](https://github.com/jycouet/firstly/pull/362) [`993486d`](https://github.com/jycouet/firstly/commit/993486dd25b5c06def4874a3b3f95440bc79a845) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: failed queries now carry Postgres' HINT (or the closest catalog names) and the SQLSTATE, so `column a.analysisversion does not exist` comes back with `Did you mean "activities"."analysisVersion"?`. New `ff-sql` bin to run token SQL from a terminal (`--origin=`, `--api-path=`, `--json`, stdin, `FF_SQL_TOKEN`/`FF_SQL_ORIGIN`); the mint screen now copies the full command, so there is nothing to set up. Tokens can be named automatically (`swift-otter-3f9`); a dead token can be deleted - one by one, or every one of them via `purgeTokens()` - which takes its call log with it, while a revoke keeps it.
+
 ## 0.10.0
 
 ### Minor Changes

package/bin/args.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @param {string[]} argv
+ * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ */
+export function parseArgs(argv: string[]): {
+    help: boolean;
+    json: boolean;
+    origin?: string;
+    apiPath?: string;
+    sql: string;
+    error?: string;
+};

package/bin/args.js

@@ -0,0 +1,66 @@
+// Pure arg parsing for `ff-sql`, split out so it can be tested without running
+// the cli. Plain JS like its caller: bin/ ships unbuilt.
+
+/** Flags that take no value. */
+const BOOLEAN = ['json', 'help']
+/** Flags that need one, as `--x=y` or `--x y`. */
+const VALUED = ['origin', 'api-path']
+
+const camel = { 'api-path': 'apiPath' }
+
+/** `--name` / `--name=value`. `-- comment` is SQL, not a flag. */
+const FLAG = /^--[a-z][\w-]*(=|$)/
+
+/**
+ * @param {string[]} argv
+ * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ */
+export function parseArgs(argv) {
+	/** @type {any} */
+	const out = { help: false, json: false, sql: '' }
+	const positional = []
+	const seen = new Set()
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (arg === '-h') {
+			out.help = true
+			continue
+		}
+		if (arg === '--') {
+			positional.push(...argv.slice(i + 1))
+			break
+		}
+		// A `-- comment` line is SQL: only a flag-shaped token is read as a flag.
+		if (!FLAG.test(arg)) {
+			positional.push(arg)
+			continue
+		}
+		const eq = arg.indexOf('=')
+		const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+		const inline = eq === -1 ? undefined : arg.slice(eq + 1)
+
+		const key = camel[name] ?? name
+		if (seen.has(key)) return { ...out, error: `--${name} given twice` }
+
+		if (BOOLEAN.includes(name)) {
+			// `--json=false` reading as "json on" is the kind of thing nobody debugs twice.
+			if (inline !== undefined) return { ...out, error: `--${name} takes no value` }
+			seen.add(key)
+			out[key] = true
+			continue
+		}
+		if (VALUED.includes(name)) {
+			const value = inline ?? argv[++i]
+			// Without this, `--origin http://x "select 1"` sends "http://x select 1" as SQL.
+			if (!value || FLAG.test(value)) return { ...out, error: `--${name} needs a value` }
+			seen.add(key)
+			out[key] = value
+			continue
+		}
+		return { ...out, error: `unknown flag --${name}` }
+	}
+
+	out.sql = positional.join(' ').trim()
+	return out
+}

package/bin/ff-sql.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Run SQL against a running app with a firstly sql token (`sqlAdmin({ tokens })`).
+// Plain JS, shipped as-is: it must run from node_modules/.bin with no build step.
+import { Console } from 'node:console'
+import { text } from 'node:stream/consumers'
+
+import { parseArgs } from './args.js'
+
+const HELP = `ff-sql - run SQL through a firstly sql token
+
+  FF_SQL_TOKEN=ffsql_… ff-sql --origin=https://example.com "select 1"
+  ff-sql --json "select * from users limit 3"
+  ff-sql <<'SQL'
+    select handle from "users" where "createdAt" > now() - interval '7 days'
+  SQL
+
+  --json          raw JSON instead of a table
+  --              end of flags, everything after is SQL
+  --origin=URL    the app to query (or FF_SQL_ORIGIN)
+  --api-path=P    remult api root (default /api)
+  --help, -h      this
+
+The app's <SqlTokens /> page hands you the whole command, token included -
+nothing to configure here. Reads run inside a READ ONLY transaction, one
+statement per call. Identifiers usually come from entity classes, so they are
+camelCase and need double quotes: "createdAt", not created_at. A heredoc avoids
+fighting the shell over single quotes, and keeps the token out of the line.`
+
+const TRAILING_SLASH = /\/$/
+
+const cli = parseArgs(process.argv.slice(2))
+
+if (cli.help) {
+	console.info(HELP)
+	process.exit(0)
+}
+if (cli.error) {
+	console.error(`${cli.error}. ff-sql --help`)
+	process.exit(2)
+}
+
+const token = process.env.FF_SQL_TOKEN
+const origin = cli.origin ?? process.env.FF_SQL_ORIGIN
+const apiPath = cli.apiPath ?? '/api'
+
+if (!token) {
+	console.error('FF_SQL_TOKEN missing - mint one in the app (<SqlTokens />). ff-sql --help')
+	process.exit(2)
+}
+if (!origin) {
+	console.error('origin missing - --origin=https://example.com, or FF_SQL_ORIGIN')
+	process.exit(2)
+}
+
+// Only read stdin when there is nothing else to run: on a tty that would hang.
+let cmd = cli.sql
+if (!cmd && !process.stdin.isTTY) cmd = (await text(process.stdin)).trim()
+if (!cmd) {
+	console.error('no sql given. ff-sql --help')
+	process.exit(2)
+}
+
+let res
+try {
+	res = await fetch(`${origin.replace(TRAILING_SLASH, '')}${apiPath}/ff/sqlAdmin/exec`, {
+		method: 'POST',
+		headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+		body: JSON.stringify({ args: [cmd] }),
+	})
+} catch (err) {
+	console.error(`${origin} unreachable: ${err.message}`)
+	process.exit(1)
+}
+
+const body = await res.json().catch(() => null)
+if (!res.ok) {
+	// 403 here is almost always a dead token: expired, revoked, or minted elsewhere.
+	console.error(`${res.status} ${body?.message ?? res.statusText}`)
+	process.exit(1)
+}
+
+const { rows, rowCount, took } = body.data ?? body
+// Table and rows on stdout, the summary on stderr, so `| jq` and `> file` stay clean.
+const out = new Console(process.stdout)
+if (cli.json) out.log(JSON.stringify(rows, null, 2))
+else if (rowCount) out.table(rows)
+console.error(`${rowCount ?? 0} row(s) · ${Math.round(took ?? 0)} ms`)

package/esm/cron/index.d.ts

@@ -1,4 +1,5 @@
 import { Log } from '@kitql/helpers';
+export { Cron } from './Cron';
 export { Roles_Cron } from './Roles_Cron';
 export declare const key = "cron";
 export declare const log: Log;

package/esm/cron/index.js

@@ -1,4 +1,5 @@
 import { Log } from '@kitql/helpers';
+export { Cron } from './Cron';
 export { Roles_Cron } from './Roles_Cron';
 export const key = 'cron';
 export const log = new Log(key);

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -72,7 +72,16 @@ export declare class SqlAdminController {
     private static execAsToken;
     /**
      * Returns the raw token exactly once. Needs a live session: a token can never
-     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`.
+     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`, deleting
+     * is a plain delete.
+     *
+     * @param name free text, or empty for an `adjective-animal` one.
      */
     static mintToken(name: string, capabilities: SqlCapability[], ttl: SqlTokenTtl): Promise<string>;
+    /**
+     * Deletes every token that can no longer be used (expired or revoked), and
+     * their calls. Returns how many were actually deleted: no transaction spans
+     * the loop, so a failure halfway leaves the rest in place.
+     */
+    static purgeTokens(): Promise<number>;
 }

package/esm/sqlAdmin/SqlAdminController.js

@@ -10,6 +10,9 @@ import { Roles_SqlAdmin } from './Roles_SqlAdmin';
 import { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
 export const SQL_ADMINS = [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin];
 const CALL_LOG_CMD_MAX = 4000;
+/** Retention is a housekeeping sweep, not something to pay for on every query. */
+const CALL_LOG_SWEEP_EVERY_MS = 3_600_000;
+let lastCallLogSweep = 0;
 function getDb() {
     return SqlAdminController.dp ?? SqlDatabase.getDb();
 }
@@ -40,14 +43,20 @@ export class SqlAdminController {
     }
     static async run(cmd, capabilities) {
         const db = getDb();
-        // Anything that is not an explicit list (null, a stray boolean) is a read.
-        if (Array.isArray(capabilities) && capabilities.includes('write')) {
-            const start = performance.now();
-            const rows = (await db.execute(cmd)).rows;
-            return { rows, rowCount: rows.length, took: performance.now() - start };
+        try {
+            // Anything that is not an explicit list (null, a stray boolean) is a read.
+            if (Array.isArray(capabilities) && capabilities.includes('write')) {
+                const start = performance.now();
+                const rows = (await db.execute(cmd)).rows;
+                return { rows, rowCount: rows.length, took: performance.now() - start };
+            }
+            const { readOnlySql } = await import('./server/readOnlySql');
+            return await readOnlySql(db, SqlAdminController.options.tokens?.pool ?? poolFrom(db), cmd);
+        }
+        catch (err) {
+            const { enrichSqlError } = await import('./server/sqlError');
+            throw await enrichSqlError(db, err, cmd);
         }
-        const { readOnlySql } = await import('./server/readOnlySql');
-        return readOnlySql(db, SqlAdminController.options.tokens?.pool ?? poolFrom(db), cmd);
     }
     static async execAsToken(token, cmd) {
         const o = SqlAdminController.options.tokens;
@@ -71,15 +80,21 @@ export class SqlAdminController {
         }
         finally {
             await repo(SqlTokenCall).insert(call);
-            const days = o.callLogRetentionDays ?? 30;
-            await repo(SqlTokenCall).deleteMany({
-                where: { ts: { $lt: new Date(Date.now() - days * 86_400_000) } },
-            });
+            if (Date.now() - lastCallLogSweep > CALL_LOG_SWEEP_EVERY_MS) {
+                lastCallLogSweep = Date.now();
+                const days = o.callLogRetentionDays ?? 30;
+                await repo(SqlTokenCall).deleteMany({
+                    where: { ts: { $lt: new Date(Date.now() - days * 86_400_000) } },
+                });
+            }
         }
     }
     /**
      * Returns the raw token exactly once. Needs a live session: a token can never
-     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`.
+     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`, deleting
+     * is a plain delete.
+     *
+     * @param name free text, or empty for an `adjective-animal` one.
      */
     static async mintToken(name, capabilities, ttl) {
         const o = SqlAdminController.options.tokens;
@@ -88,9 +103,6 @@ export class SqlAdminController {
         const userId = remult.user?.id;
         if (!userId)
             throw new Error('Forbidden');
-        const clean = name.trim();
-        if (!clean)
-            throw new Error('Name is required');
         const ttlMs = SQL_TOKEN_TTLS[ttl];
         if (!ttlMs)
             throw new Error('Unknown ttl');
@@ -103,11 +115,11 @@ export class SqlAdminController {
             if (!o.capabilities.includes(c))
                 throw new Error(`${c} is not enabled`);
         }
-        const { newRawToken, hashToken, tokenHint } = await import('./server/token');
+        const { newRawToken, hashToken, tokenHint, randomTokenName } = await import('./server/token');
         const prefix = o.prefix ?? 'ffsql_';
         const raw = newRawToken(prefix);
         await repo(SqlToken).insert({
-            name: clean,
+            name: name.trim() || randomTokenName(),
             hint: tokenHint(raw, prefix),
             tokenHash: hashToken(raw),
             userId,
@@ -116,6 +128,23 @@ export class SqlAdminController {
         });
         return raw;
     }
+    /**
+     * Deletes every token that can no longer be used (expired or revoked), and
+     * their calls. Returns how many were actually deleted: no transaction spans
+     * the loop, so a failure halfway leaves the rest in place.
+     */
+    static async purgeTokens() {
+        const dead = await repo(SqlToken).find({
+            where: { $or: [{ revokedAt: { $ne: null } }, { expiresAt: { $lt: new Date() } }] },
+        });
+        // One by one: the cascade to the call log lives in the entity's hooks.
+        let deleted = 0;
+        for (const t of dead) {
+            await repo(SqlToken).delete(t);
+            deleted++;
+        }
+        return deleted;
+    }
 }
 __decorate([
     BackendMethod({
@@ -139,3 +168,9 @@ __decorate([
         apiPrefix: 'ff/sqlAdmin',
     })
 ], SqlAdminController, "mintToken", null);
+__decorate([
+    BackendMethod({
+        allowed: () => !!SqlAdminController.options.tokens && !remult.context.sqlToken && remult.isAllowed(SQL_ADMINS),
+        apiPrefix: 'ff/sqlAdmin',
+    })
+], SqlAdminController, "purgeTokens", null);

package/esm/sqlAdmin/server/sqlError.d.ts

@@ -0,0 +1,6 @@
+import type { SqlDatabase } from 'remult';
+/**
+ * Never throws and never hides the original message - the returned error is the
+ * one to rethrow, with the code and any hint appended.
+ */
+export declare function enrichSqlError(db: SqlDatabase, err: unknown, cmd?: string): Promise<unknown>;

package/esm/sqlAdmin/server/sqlError.js

@@ -0,0 +1,132 @@
+/**
+ * Turns "column X does not exist" into something a caller can act on without a
+ * second round trip: Postgres' own HINT when it has one, otherwise the closest
+ * names taken from the catalog.
+ *
+ * Why it matters here more than in an app: the callers of `exec` are scripts
+ * and AIs writing SQL against a schema they cannot see, and every case observed
+ * in the call log was a misremembered identifier - quoted camelCase read as
+ * snake_case, a table named in the singular. Postgres already knows the answer
+ * (`Perhaps you meant "athleteEraEstimates.estMaxBpm"`) and the raw message
+ * throws it away.
+ */
+const RELATION_MISSING = /relation "([^"]+)" does not exist/;
+const COLUMN_MISSING = /column "?([\w$.]+)"? does not exist/;
+const NON_ALPHANUM = /[^a-z0-9]/g;
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+const UNDEFINED_TABLE = '42P01';
+const UNDEFINED_COLUMN = '42703';
+/** SQLSTATE class 08: the connection is gone, so asking it about its catalog only adds a timeout. */
+const CONNECTION_CLASS = '08';
+const MAX_CANDIDATES = 3;
+const MIN_MATCH_LENGTH = 3;
+/** A caller looping on bad SQL must not turn each failure into a catalog scan. */
+const CATALOG_TTL_MS = 10_000;
+/** Comparison key: an unquoted identifier is folded to lowercase, and `_` is how the same name is spelled in snake_case. */
+const norm = (s) => s.toLowerCase().replace(NON_ALPHANUM, '');
+/** `a.analysisversion` and `public.users` are about their last part. */
+const lastPart = (s) => s.split('.').at(-1);
+/**
+ * Same name modulo case and underscores, then one name being the start of the
+ * other - which is what a singular/plural or a truncated guess looks like
+ * (`key_value` for `keyValues`). Deliberately not a typo distance: real misses
+ * are spellings of the right word, and Postgres already suggests actual typos
+ * through its own HINT.
+ */
+function closest(wanted, candidates) {
+    const target = norm(wanted);
+    if (target.length < MIN_MATCH_LENGTH)
+        return [];
+    const exact = candidates.filter((c) => norm(c.name) === target);
+    if (exact.length)
+        return exact.slice(0, MAX_CANDIDATES);
+    return candidates
+        .filter((c) => {
+        const n = norm(c.name);
+        return n.length >= MIN_MATCH_LENGTH && (n.startsWith(target) || target.startsWith(n));
+    })
+        .slice(0, MAX_CANDIDATES);
+}
+/** A column suggestion from a table the query never mentions is noise; keep those last. */
+function preferMentioned(candidates, cmd) {
+    const haystack = norm(cmd);
+    const mentioned = candidates.filter((c) => c.table && haystack.includes(norm(c.table)));
+    return mentioned.length ? mentioned : candidates;
+}
+const catalogCache = new WeakMap();
+async function catalog(db, sql) {
+    let perDb = catalogCache.get(db);
+    if (!perDb)
+        catalogCache.set(db, (perDb = new Map()));
+    const hit = perDb.get(sql);
+    if (hit && Date.now() - hit.at < CATALOG_TTL_MS)
+        return hit.rows;
+    let rows = [];
+    try {
+        rows = (await db.execute(sql)).rows ?? [];
+    }
+    catch {
+        // Not Postgres, no catalog access, connection gone: the plain error is still useful.
+    }
+    perDb.set(sql, { at: Date.now(), rows });
+    return rows;
+}
+async function suggest(db, err, cmd) {
+    const message = err.message ?? '';
+    if (err.code === UNDEFINED_TABLE) {
+        const wanted = RELATION_MISSING.exec(message)?.[1];
+        if (!wanted)
+            return [];
+        const rows = await catalog(db, `select table_name from information_schema.tables where table_schema not in ('pg_catalog', 'information_schema')`);
+        const found = closest(lastPart(wanted), rows.map((r) => ({ label: `"${r.table_name}"`, name: r.table_name })));
+        return found.map((c) => c.label);
+    }
+    if (err.code === UNDEFINED_COLUMN) {
+        const wanted = COLUMN_MISSING.exec(message)?.[1];
+        if (!wanted)
+            return [];
+        const rows = await catalog(db, `select table_name, column_name from information_schema.columns where table_schema not in ('pg_catalog', 'information_schema')`);
+        const found = closest(lastPart(wanted), rows.map((r) => ({
+            label: `"${r.table_name}"."${r.column_name}"`,
+            name: r.column_name,
+            table: r.table_name,
+        })));
+        return preferMentioned(found, cmd).map((c) => c.label);
+    }
+    return [];
+}
+/**
+ * Never throws and never hides the original message - the returned error is the
+ * one to rethrow, with the code and any hint appended.
+ */
+export async function enrichSqlError(db, err, cmd = '') {
+    if (!(err instanceof Error))
+        return err;
+    const pg = err;
+    // A SQLSTATE, not any error that happens to carry a `code`: ENOTFOUND is too
+    // long to match, but EPIPE and EBUSY have the exact same shape.
+    if (!pg.code || !SQLSTATE.test(pg.code) || pg.code.startsWith(CONNECTION_CLASS))
+        return err;
+    if (pg.errno !== undefined || pg.syscall !== undefined)
+        return err;
+    const parts = [pg.message];
+    if (pg.hint)
+        parts.push(pg.hint);
+    else {
+        const found = await suggest(db, pg, cmd);
+        if (found.length)
+            parts.push(`Did you mean ${found.join(' or ')}?`);
+    }
+    if (pg.detail)
+        parts.push(pg.detail);
+    parts.push(`[${pg.code}${pg.position ? ` at ${pg.position}` : ''}]`);
+    const out = new Error(parts.join(' · '));
+    Object.assign(out, {
+        code: pg.code,
+        hint: pg.hint,
+        detail: pg.detail,
+        position: pg.position,
+        cause: err,
+    });
+    return out;
+}

package/esm/sqlAdmin/server/token.d.ts

@@ -1,3 +1,5 @@
 export declare function newRawToken(prefix: string): string;
 export declare function hashToken(raw: string): string;
 export declare function tokenHint(raw: string, prefix: string): string;
+/** `swift-otter-3f9`: a name you can say out loud when asking "who is running this query?". */
+export declare function randomTokenName(): string;

package/esm/sqlAdmin/server/token.js

@@ -1,4 +1,4 @@
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomInt } from 'node:crypto';
 export function newRawToken(prefix) {
     return prefix + randomBytes(32).toString('base64url');
 }
@@ -8,3 +8,10 @@ export function hashToken(raw) {
 export function tokenHint(raw, prefix) {
     return raw.slice(0, prefix.length + 8);
 }
+const ADJECTIVES = 'amber bold brave calm clever cosmic crisp eager fuzzy gentle happy jolly keen lucky mellow neat nimble plucky quiet rapid rusty shiny silent sly snappy sunny swift tidy vivid witty zesty'.split(' ');
+const ANIMALS = 'otter badger falcon heron ibex lynx marmot narwhal ocelot panda quokka raven seal tapir urchin viper walrus yak zebu gecko koala llama mantis newt puffin stoat toucan vole wombat'.split(' ');
+/** `swift-otter-3f9`: a name you can say out loud when asking "who is running this query?". */
+export function randomTokenName() {
+    const pick = (xs) => xs[randomInt(xs.length)];
+    return `${pick(ADJECTIVES)}-${pick(ANIMALS)}-${randomBytes(2).toString('hex').slice(0, 3)}`;
+}

package/esm/sqlAdmin/sqlTokenEntities.d.ts

@@ -7,6 +7,7 @@ export declare const SQL_TOKEN_TTLS: {
     readonly '7d': 604800000;
 };
 export type SqlTokenTtl = keyof typeof SQL_TOKEN_TTLS;
+export declare const SQL_TOKEN_DELETE_LIVE = "Revoke a live token before deleting it";
 export declare class SqlToken {
     id: string;
     name: string;

package/esm/sqlAdmin/sqlTokenEntities.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { Entity, Fields } from 'remult';
+import { Entity, Fields, repo } from 'remult';
 import { FF_Role } from '../core/common';
 import { Roles_SqlAdmin } from './Roles_SqlAdmin';
 /** What a call may do: `read` runs inside a READ ONLY transaction (one statement), `write` runs SQL as is. */
@@ -14,6 +14,13 @@ const admins = [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin];
 // Minting is `SqlAdminController.mintToken` (the raw value is generated
 // server-side, shown once, never stored). Revoking is the one update the API
 // allows: set `revokedAt`; nothing else is writable and a revoke is final.
+//
+// Revoke and delete are not the same gesture: revoking is the kill switch and
+// keeps the row plus its call log, which is the audit trail; deleting is
+// cleanup and takes the calls with it - a call log pointing at a token nobody
+// can name is noise, not history. So only a dead token can be deleted: killing
+// a live one is always a revoke.
+export const SQL_TOKEN_DELETE_LIVE = 'Revoke a live token before deleting it';
 let SqlToken = class SqlToken {
     id = '';
     name = '';
@@ -61,14 +68,25 @@ __decorate([
 SqlToken = __decorate([
     Entity('_ff_sql_tokens', {
         caption: 'FF Sql Tokens',
+        // Admins means a session: a bearer is only ever resolved for the exec path
+        // (`server/index.ts`), so a token reaching this entity is an anonymous request.
         allowApiRead: admins,
         allowApiUpdate: admins,
+        allowApiDelete: admins,
         defaultOrderBy: { createdAt: 'desc' },
         saving: (t, e) => {
             if (!e.isNew && e.fields.revokedAt.valueChanged() && !t.revokedAt) {
                 throw new Error('A revoked token stays revoked');
             }
         },
+        deleting: (t) => {
+            if (isSqlTokenLive(t))
+                throw new Error(SQL_TOKEN_DELETE_LIVE);
+        },
+        // After, not before: a failed row delete must not have dropped the calls already.
+        deleted: async (t) => {
+            await repo(SqlTokenCall).deleteMany({ where: { tokenId: t.id } });
+        },
     })
 ], SqlToken);
 export { SqlToken };

package/esm/sqlAdmin/ui/SqlTokens.svelte

@@ -20,14 +20,27 @@
 	type Props = {
 		/** Capabilities offered in the form. Others render disabled. @default ['read'] */
 		capabilities?: SqlCapability[]
-		/** Command shown once a token is minted (what the user pastes). Defaults to a curl line. */
+		/** Command shown once a token is minted (what the user pastes). Defaults to a full `ff-sql` line. */
 		command?: (token: string) => string
+		/** Remult api root, when the app moved it. @default '/api' */
+		apiPath?: string
 	}
-	let { capabilities: enabled = ['read'], command }: Props = $props()
+	let { capabilities: enabled = ['read'], command, apiPath = '/api' }: Props = $props()
 
 	const TTLS = Object.keys(SQL_TOKEN_TTLS) as SqlTokenTtl[]
+	// Self-contained on purpose: every parameter is in the line, so the copy runs
+	// as is from any terminal - no env file, nothing to set up first.
 	const defaultCommand = (token: string) =>
-		`curl -X POST ${location.origin}/api/ff/sqlAdmin/exec -H "authorization: Bearer ${token}" -H "content-type: application/json" -d '{"args":["select 1"]}'`
+		[
+			`FF_SQL_TOKEN=${token}`,
+			// npx, not `pnpm exec`: the line must run wherever it is pasted.
+			'npx ff-sql',
+			`--origin=${location.origin}`,
+			apiPath === '/api' ? '' : `--api-path=${apiPath}`,
+			'"select 1"',
+		]
+			.filter(Boolean)
+			.join(' ')
 
 	let name = $state('')
 	let picked = $state<SqlCapability[]>(['read'])
@@ -68,11 +81,42 @@
 
 	async function revoke(t: SqlToken) {
 		error = ''
+		busy = true
 		try {
 			await repo(SqlToken).update(t.id, { revokedAt: new Date() })
 			await refresh()
 		} catch (err) {
 			error = err instanceof Error ? err.message : String(err)
+		} finally {
+			busy = false
+		}
+	}
+
+	async function remove(t: SqlToken) {
+		if (!confirm(`Delete "${t.name}" and its calls? The audit trail goes with it.`)) return
+		error = ''
+		busy = true
+		try {
+			await repo(SqlToken).delete(t)
+			await refresh()
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err)
+		} finally {
+			busy = false
+		}
+	}
+
+	async function purge() {
+		if (!confirm('Delete every expired or revoked token, with their calls?')) return
+		error = ''
+		busy = true
+		try {
+			await SqlAdminController.purgeTokens()
+			await refresh()
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err)
+		} finally {
+			busy = false
 		}
 	}
 
@@ -103,6 +147,8 @@
 	const status = (t: SqlToken) =>
 		t.revokedAt ? 'revoked' : t.expiresAt.getTime() < Date.now() ? 'expired' : 'live'
 
+	const deadCount = $derived(tokens.filter((t) => status(t) !== 'live').length)
+
 	const th = 'px-4 py-2 text-left text-xs font-medium tracking-wide text-muted-foreground uppercase'
 	const td = 'px-4 py-2 align-top'
 	const btn =
@@ -116,18 +162,18 @@
 			A token is a bag of capabilities that acts as you, for a short while. Minting needs a live
 			session - a token can never mint or revoke a token. <code>read</code> runs inside a
 			<code>READ ONLY</code> transaction, one statement at a time. Every call is logged below (SQL text,
-			rows, ms, error - never the rows themselves). Revoking is immediate.
+			rows, ms, error - never the rows themselves). Revoking is immediate and keeps the trail; a dead token
+			can then be deleted, which drops its calls too.
 		</p>
 	</header>
 
 	<div class="flex flex-col gap-6 p-5">
 		<form onsubmit={mint} class="flex flex-wrap items-end gap-4 text-sm">
 			<label class="flex flex-col gap-1">
-				<span class="text-xs text-muted-foreground">Name</span>
+				<span class="text-xs text-muted-foreground">Name (optional)</span>
 				<input
 					bind:value={name}
-					required
-					placeholder="laptop · claude"
+					placeholder="auto: swift-otter-3f9"
 					class="w-56 border border-input bg-background px-2 py-1.5 text-foreground focus:border-ring focus:outline-none"
 				/>
 			</label>
@@ -183,6 +229,10 @@
 			<div class="border border-primary bg-muted p-4 text-sm">
 				<p class="text-xs font-medium tracking-wide text-primary uppercase">Shown once - copy it now</p>
 				<code class="mt-2 block font-mono break-all select-all">{line}</code>
+				<p class="mt-2 text-xs text-muted-foreground">
+					The token is in the line: paste it with a leading space, or put it in an env file, to keep it
+					out of your shell history.
+				</p>
 				<div class="mt-3 flex gap-2">
 					<button type="button" class={btn} onclick={() => copy(line)}>
 						{copied ? 'Copied' : 'Copy'}
@@ -193,7 +243,14 @@
 		{/if}
 
 		<section>
-			<h3 class="mb-2 text-sm font-semibold text-foreground">Tokens</h3>
+			<div class="mb-2 flex items-center justify-between">
+				<h3 class="text-sm font-semibold text-foreground">Tokens</h3>
+				{#if deadCount}
+					<button type="button" class={btn} disabled={busy} onclick={purge}>
+						Delete {deadCount} dead
+					</button>
+				{/if}
+			</div>
 			<div class="overflow-x-auto border border-border">
 				<table class="w-full text-sm">
 					<thead class="border-b border-border bg-muted">
@@ -219,9 +276,16 @@
 								<td class={td}>{fmt(t.expiresAt)}</td>
 								<td class={td}>{fmt(t.lastUsedAt)}</td>
 								<td class={td} class:text-primary={s === 'live'}>{s}</td>
-								<td class="{td} text-right">
+								<td class="{td} space-x-2 text-right whitespace-nowrap">
+									<!-- Revoke is the kill switch, delete is cleanup: a live token can only be revoked. -->
 									{#if s === 'live'}
-										<button type="button" class={btn} onclick={() => revoke(t)}>Revoke</button>
+										<button type="button" class={btn} disabled={busy} onclick={() => revoke(t)}>
+											Revoke
+										</button>
+									{:else}
+										<button type="button" class={btn} disabled={busy} onclick={() => remove(t)}>
+											Delete
+										</button>
 									{/if}
 								</td>
 							</tr>

package/esm/sqlAdmin/ui/SqlTokens.svelte.d.ts

@@ -2,8 +2,10 @@ import { type SqlCapability } from '../sqlTokenEntities';
 type Props = {
     /** Capabilities offered in the form. Others render disabled. @default ['read'] */
     capabilities?: SqlCapability[];
-    /** Command shown once a token is minted (what the user pastes). Defaults to a curl line. */
+    /** Command shown once a token is minted (what the user pastes). Defaults to a full `ff-sql` line. */
     command?: (token: string) => string;
+    /** Remult api root, when the app moved it. @default '/api' */
+    apiPath?: string;
 };
 declare const SqlTokens: import("svelte").Component<Props, {}, "">;
 type SqlTokens = ReturnType<typeof SqlTokens>;

package/esm/svelte/ff.svelte.js

@@ -1,4 +1,5 @@
 import { repo as remultRepo, } from 'remult';
+import { errorMessage } from '../core/helper.js';
 import { dialog } from './dialog.svelte.js';
 /** Classify a thrown read error into an {@link FF_Issue} (best-effort status sniffing). */
 function toIssue(e) {
@@ -70,7 +71,7 @@ class FF_RepoHandle {
                         this.#fireItems();
                     },
                     error: (e) => {
-                        this.error = e instanceof Error ? e.message : String(e);
+                        this.error = errorMessage(e);
                         this.loading.init = false;
                         this.#fireIssue(toIssue(e));
                     },
@@ -144,7 +145,7 @@ class FF_RepoHandle {
         }
         catch (e) {
             if (seq === this.#seq) {
-                this.error = e instanceof Error ? e.message : String(e);
+                this.error = errorMessage(e);
                 this.#fireIssue(toIssue(e));
             }
         }
@@ -280,7 +281,7 @@ class FF_RepoHandle {
             return res;
         }
         catch (e) {
-            this.error = e instanceof Error ? e.message : String(e);
+            this.error = errorMessage(e);
             throw e;
         }
         finally {

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "firstly",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
+  "bin": {
+    "ff-sql": "./bin/ff-sql.js"
+  },
   "funding": "https://github.com/sponsors/jycouet",
   "homepage": "https://firstly.fun/",
   "repository": {
@@ -15,7 +18,7 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@sveltejs/kit": ">=1.0.0 <3.0.0",
+    "@sveltejs/kit": ">=1.0.0 <4.0.0 || ^3.0.0-next.0",
     "remult": ">=3.3.7",
     "svelte": ">=5"
   },
@@ -39,8 +42,8 @@
     "cron": "4.4.0",
     "esm-env": "1.2.2",
     "nodemailer": "8.0.5",
-    "svelte-sonner": "1.1.1",
-    "tailwind-merge": "3.6.0",
+    "svelte-sonner": "1.2.1",
+    "tailwind-merge": "3.7.0",
     "tailwindcss": "4.3.0",
     "vite-plugin-kit-routes": "1.0.6",
     "vite-plugin-stripper": "0.10.4"
@@ -77,6 +80,10 @@
       "types": "./esm/changeLog/server/index.d.ts",
       "default": "./esm/changeLog/server/index.js"
     },
+    "./cron": {
+      "types": "./esm/cron/index.d.ts",
+      "default": "./esm/cron/index.js"
+    },
     "./cron/server": {
       "types": "./esm/cron/server/index.d.ts",
       "default": "./esm/cron/server/index.js"