@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/scaffoldMachine.js

@@ -0,0 +1,184 @@
+/**
+ * A record's life read off its status vocabulary: the one inference the
+ * scaffold writes as a `machine()` and `tablewalk seed` walks when no App
+ * says otherwise.
+ *
+ * A CHECK or enum list of plain words on a column named like a state is the
+ * work's states in their order. Most of them are a path — received, in
+ * progress, ready, collected — walked one verb at a time to the last, which
+ * is final. A word that calls the work off (cancelled, rejected, lost) is an
+ * exit: final, reached from every open state by a verb that asks first. A
+ * word that parks the work (on hold, waiting for parts) is a side state: one
+ * verb into it from the step before it, one back. That is a draft of how the
+ * work moves, not a rule about the business: the author adds the skips and
+ * the commands.
+ *
+ * Stamps follow: a date column named for a state (`ready_at`) is the
+ * platform's to write as the record enters it, so it is left alone; one
+ * named for what entering a state means (`completed_on` beside `collected`,
+ * `cancelled_at` beside a `cancel` verb) is set by the verbs that lead there.
+ */
+import { columnKind, momentColumn, stateStampColumn } from '../shared/schema.js';
+const said = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_');
+/* Words that call the work off: the exits. */
+const EXIT = /^(cancell?ed|rejected|declined|denied|lost|closed_lost|void|voided|withdrawn|abandoned|failed|expired|refunded|no_show|dismissed|discarded|dropped|disqualified|unqualified|churned|terminated|aborted|wont_fix|duplicate|spam)$/;
+/* Words that park the work: a side state, left the way it was entered. */
+const HOLD = /^(on_hold|hold|paused|blocked|stalled|deferred|snoozed|backordered|waiting|waiting_\w+)$/;
+/* The verb that leads into a state, by the state's word: what a person does to put the record there. */
+const INTO = {
+    in_progress: 'start',
+    working: 'start',
+    started: 'start',
+    active: 'activate',
+    open: 'open',
+    ready: 'markReady',
+    done: 'complete',
+    complete: 'complete',
+    completed: 'complete',
+    finished: 'finish',
+    collected: 'collect',
+    picked_up: 'markPickedUp',
+    closed: 'close',
+    resolved: 'resolve',
+    approved: 'approve',
+    accepted: 'accept',
+    confirmed: 'confirm',
+    qualified: 'qualify',
+    won: 'markWon',
+    closed_won: 'markWon',
+    shipped: 'ship',
+    delivered: 'deliver',
+    fulfilled: 'fulfill',
+    invoiced: 'invoice',
+    paid: 'markPaid',
+    sent: 'send',
+    submitted: 'submit',
+    published: 'publish',
+    scheduled: 'schedule',
+    assigned: 'assign',
+    in_review: 'sendForReview',
+    review: 'sendForReview',
+    archived: 'archive',
+    returned: 'markReturned',
+    on_hold: 'hold',
+    hold: 'hold',
+    paused: 'pause',
+    blocked: 'block',
+    cancelled: 'cancel',
+    canceled: 'cancel',
+    rejected: 'reject',
+    declined: 'decline',
+    denied: 'deny',
+    lost: 'markLost',
+    closed_lost: 'markLost',
+    void: 'void',
+    voided: 'void',
+    withdrawn: 'withdraw',
+    abandoned: 'abandon',
+    failed: 'markFailed',
+    expired: 'expire',
+    refunded: 'refund',
+    dismissed: 'dismiss',
+    discarded: 'discard',
+    disqualified: 'disqualify',
+    terminated: 'terminate',
+};
+/* What a stamp's word says entering a state means, when it is not the state's own name. */
+const DONE_STAMP = /^(completed|finished|closed|done|resolved|fulfilled|delivered|collected|picked_up|handed_over|shipped)$/;
+const START_STAMP = /^(started|begun|commenced|work_started)$/;
+const EXIT_STAMP = /^(cancell?ed|rejected|declined|lost|voided|withdrawn|abandoned|failed|terminated|closed_lost)$/;
+const SINCE = /^(status|state|stage|phase)_(changed|updated|since|entered)(_at|_on)?$|^(status|state|stage|phase)_since$/i;
+const REASON = /(^|_)reason$/i;
+const camel = (words) => words.replace(/_+([a-z0-9])/g, (_, c) => c.toUpperCase());
+/** Whether a vocabulary reads as a lifecycle: three or more plain words, at least two of them steps forward. */
+export function draftMachine(table, column) {
+    const states = column.allowed ?? [];
+    if (states.length < 3 || states.length > 10 || column.flag || !states.every((state) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(state)))
+        return undefined;
+    const exits = states.filter((state, i) => i > 0 && EXIT.test(said(state)));
+    const holdStates = states.filter((state, i) => i > 0 && !exits.includes(state) && HOLD.test(said(state)));
+    const path = states.filter((state) => !exits.includes(state) && !holdStates.includes(state));
+    if (path.length < 2)
+        return undefined;
+    const holds = new Map();
+    for (const hold of holdStates) {
+        /* Entered from the path state the vocabulary lists before it; one listed after the last step returns to the step before. */
+        const before = states.slice(0, states.indexOf(hold)).filter((state) => path.includes(state) && state !== path.at(-1));
+        holds.set(hold, before.at(-1) ?? path[0]);
+    }
+    /* A state named for a plan (due, scheduled) would read the plan's date as the moment it was entered: `due_on` stamped
+       as the record is made. Such a vocabulary is a schedule's, not a lifecycle's. */
+    if (states.some((state) => /^(due|scheduled|planned|expected|overdue|late)$/.test(said(state)) &&
+        stateStampColumn(state, table.columns, { column: column.name })))
+        return undefined;
+    const final = path.at(-1);
+    const open = states.filter((state) => state !== final && !exits.includes(state));
+    const taken = new Set();
+    const verbFor = (state) => {
+        const word = INTO[said(state)] ?? camel(`mark_${said(state)}`);
+        let verb = word;
+        for (let n = 2; taken.has(verb); n++)
+            verb = `${word}${n}`;
+        taken.add(verb);
+        return verb;
+    };
+    const dated = table.columns.filter((c) => !c.primaryKey &&
+        c.name !== column.name &&
+        /_(at|on)$/.test(c.name) &&
+        (momentColumn(c) !== undefined || columnKind(c.type ?? '') === 'date'));
+    const since = table.columns.find((c) => SINCE.test(c.name) && momentColumn(c) !== undefined)?.name;
+    const machine = { column: column.name, ...(since ? { since } : {}) };
+    /* A stamp the state's own name says is the platform's; one the verb's meaning says is the verb's. */
+    const stampsFor = (to) => dated
+        .filter((c) => c.name !== since && stateStampColumn(to, table.columns, machine)?.name !== c.name)
+        .filter((c) => {
+        const word = said(c.name.replace(/_(at|on)$/, ''));
+        if (states.some((state) => said(state) === word))
+            return false;
+        const state = said(to);
+        if (word === `${state}d` || word === `${state}ed` || state === `${word}d`)
+            return true;
+        if (to === final)
+            return DONE_STAMP.test(word);
+        if (exits.includes(to))
+            return EXIT_STAMP.test(word) && (exits.length === 1 || word.startsWith(state.slice(0, 4)));
+        return path.length > 2 && to === path[1] && START_STAMP.test(word);
+    })
+        .map((c) => c.name);
+    const reasonFor = (exit) => {
+        const reasons = table.columns.filter((c) => REASON.test(c.name) && columnKind(c.type ?? '') === 'text' && !c.allowed?.length);
+        return (reasons.find((c) => c.name.startsWith(said(exit).slice(0, 4))) ?? (reasons.length === 1 ? reasons[0] : undefined))?.name;
+    };
+    const verbs = [];
+    const add = (from, to, extra = {}) => {
+        const stamps = stampsFor(to);
+        verbs.push({ verb: verbFor(to), from, to, stamps, ...extra });
+    };
+    for (let i = 0; i + 1 < path.length; i++)
+        add([path[i]], path[i + 1]);
+    for (const [hold, base] of holds) {
+        add([base], hold);
+        verbs.push({ verb: taken.has('resume') ? verbFor(base) : (taken.add('resume'), 'resume'), from: [hold], to: base, stamps: [] });
+    }
+    for (const exit of exits) {
+        const reason = reasonFor(exit);
+        add(open, exit, { confirm: true, ...(reason ? { reason } : {}) });
+    }
+    return { column: column.name, states, path, holds, exits, verbs, ...(since ? { since } : {}) };
+}
+/** Every column the machine writes: its column, its `since`, each state's own stamp and each verb's. */
+export function machineWrites(table, machine) {
+    const written = new Set([machine.column, ...(machine.since ? [machine.since] : [])]);
+    for (const state of machine.states) {
+        const own = stateStampColumn(state, table.columns, machine);
+        if (own)
+            written.add(own.name);
+    }
+    for (const verb of machine.verbs)
+        for (const stamp of verb.stamps)
+            written.add(stamp);
+    return written;
+}

package/dist/server/seed/cli.d.ts

@@ -0,0 +1,20 @@
+import { type Options } from '../cli/args.js';
+import { type StartupConfig } from '../cli/config.js';
+import type { ConfigSections } from '../configSections.js';
+import { type TargetBinding } from '../migrate/target.js';
+import { type SeedResource } from './seed.js';
+/** The App framework's part of `tablewalk seed`: the App in `dir`, as seed reads it. Throws with the sentence to print. */
+export interface SeedHost {
+    app(dir: string, given: {
+        opts: Options;
+        config: StartupConfig;
+    }): Promise<{
+        binding: TargetBinding;
+        resources?: Record<string, SeedResource>;
+        people?: {
+            table: string;
+            column: string;
+        };
+    }>;
+}
+export declare function runSeed(argv: string[], write?: (line: string) => void, sections?: ConfigSections, host?: SeedHost): Promise<number>;

package/dist/server/seed/cli.js

@@ -0,0 +1,164 @@
+/**
+ * `tablewalk seed`: fill an App's database with rows to look at (seed.ts says
+ * what makes them believable). The database is found the way `migrate` finds
+ * it — the App's connection, a named one, or the only one — and written only
+ * when its config says `"writable": true`: the flag is the reviewable
+ * statement that this database may be changed, and seed is a change.
+ *
+ * `--app` is the App framework's: a main that has one hands a `SeedHost`
+ * (cli/appTargets.ts) that names the App's connection, how its statuses move
+ * and who signs in. With no host, `--app` is refused.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Registry, redact } from '../connections.js';
+import { parseArgs } from '../cli/args.js';
+import { readStartupConfig } from '../cli/config.js';
+import { CACHE_SECTIONS } from '../cacheService.js';
+import { targetConnection } from '../migrate/target.js';
+import { seedDatabase, SeedRefusal } from './seed.js';
+import { configFileName } from '../product.js';
+import { product } from '../product.js';
+const seedUsage = () => product() + ' seed [--app <dir>] [<db> | --db <target> | --config <path>] [--connection <name>] [--rows <n>] [--seed <n>] [--append]';
+/** The exit codes: 1 could not run, 2 refused (read-only, or rows already there). */
+const EXIT = { ok: 0, couldNot: 1, refused: 2 };
+/* The start's own flags this command takes, and whether each has a value. */
+const PASSED = {
+    '--db': true,
+    '-d': true,
+    '--config': true,
+    '--no-config': false,
+    '--schema': true,
+    '--app-entry': true,
+};
+export async function runSeed(argv, write = (line) => process.stdout.write(`${line}\n`), sections = CACHE_SECTIONS, host) {
+    const fail = (why, code = EXIT.couldNot) => {
+        console.error(`${product()} seed: ${why}`);
+        return code;
+    };
+    if (argv[0] === '--help' || argv[0] === '-h') {
+        write(`${seedUsage()}\n\n` +
+            'Rows to look at, in a writable database: about --rows per main table (default 40), fewer for staff\n' +
+            "and lookups, more for lines. Each status the way the App's machine moves it, with its stamps; dates\n" +
+            'across the last 90 days, some work due today or overdue. --seed <n> makes the same rows again on the\n' +
+            'same day. A table that already holds rows is refused unless --append.');
+        return EXIT.ok;
+    }
+    let app;
+    let connection;
+    let rows = 40;
+    let seed;
+    let append = false;
+    const rest = [];
+    const value = (i, flag) => {
+        const given = argv[i + 1];
+        if (given === undefined || given.startsWith('-'))
+            throw new Error(`${flag} needs a value. ${seedUsage()}`);
+        return given;
+    };
+    const whole = (text, flag, lo, hi) => {
+        const n = Number(text);
+        if (!Number.isInteger(n) || n < lo || n > hi)
+            throw new Error(`${flag} takes a whole number from ${lo} to ${hi}; "${text}" is not one.`);
+        return n;
+    };
+    try {
+        for (let i = 0; i < argv.length; i++) {
+            const arg = argv[i];
+            if (arg === '--app') {
+                app = value(i++, arg);
+                continue;
+            }
+            if (arg === '--connection') {
+                connection = value(i++, arg);
+                continue;
+            }
+            if (arg === '--rows') {
+                rows = whole(value(i++, arg), arg, 1, 10_000);
+                continue;
+            }
+            if (arg === '--seed') {
+                seed = whole(value(i++, arg), arg, 0, 2 ** 32 - 1);
+                continue;
+            }
+            if (arg === '--append') {
+                append = true;
+                continue;
+            }
+            const flag = arg.split('=')[0];
+            if (flag in PASSED) {
+                rest.push(arg);
+                if (PASSED[flag] && !arg.includes('='))
+                    rest.push(value(i++, arg));
+                continue;
+            }
+            if (arg.startsWith('-'))
+                throw new Error(`"${arg}" is not an option of seed. ${seedUsage()}`);
+            rest.push(arg);
+        }
+    }
+    catch (error) {
+        return fail(error.message);
+    }
+    const opts = parseArgs(rest);
+    if (opts.unknown)
+        return fail(`unknown option "${opts.unknown}". ${seedUsage()}`);
+    const appDir = app !== undefined ? resolve(app) : undefined;
+    if (appDir !== undefined && !host)
+        return fail("--app reads an App, which is the App framework's part: " +
+            product() +
+            ' seeds a database alone. Run npx @mistriwork/mistri seed --app, or drop --app.');
+    if (appDir !== undefined && !existsSync(appDir))
+        return fail(`${app} is not a directory.`);
+    /* A seed nobody chose is still said, so the same rows can be made again. */
+    const chosen = seed ?? Math.floor(Math.random() * 1_000_000);
+    const registry = new Registry();
+    const log = console.log;
+    console.log = () => { };
+    try {
+        const config = await readStartupConfig(opts, registry, sections);
+        const argument = opts.target
+            ? registry.add({ name: redact(opts.target), url: opts.target, schemas: opts.schemas, source: 'argument' }).id
+            : undefined;
+        let loaded;
+        if (appDir !== undefined) {
+            try {
+                loaded = await host.app(appDir, { opts, config });
+            }
+            catch (error) {
+                return fail(error.message);
+            }
+        }
+        const target = targetConnection(registry, { connection, argument }, loaded?.binding, 'seed');
+        if (target.http)
+            return fail(`"${target.name}" is an HTTP API; seed writes rows to a database.`, EXIT.refused);
+        if (target.writable !== true)
+            return fail(`"${target.name}" is read-only, and seed writes rows. Give the connection "writable": true in ${configFileName()} — ` +
+                'a database named on the command line is always read-only.', EXIT.refused);
+        const { adapter, schema } = await registry.open(target.id);
+        const me = loaded?.people;
+        const report = await seedDatabase(adapter, schema, {
+            rows,
+            seed: chosen,
+            append,
+            ...(loaded?.resources ? { resources: loaded.resources } : {}),
+            ...(me ? { people: me } : {}),
+        });
+        const total = report.tables.reduce((sum, table) => sum + table.rows, 0);
+        write(`Seeded ${target.name} with ${total} rows (--seed ${chosen}):`);
+        for (const table of report.tables)
+            write(`  ${table.table.padEnd(24)} ${table.rows}`);
+        if (report.signIn.length)
+            write(`Sign in as ${report.signIn.join(', ')} — or any other of ${me.table}.`);
+        return EXIT.ok;
+    }
+    catch (error) {
+        if (error instanceof SeedRefusal)
+            return fail(error.message, EXIT.refused);
+        return fail(error.message);
+    }
+    finally {
+        console.log = log;
+        await registry.closeAll();
+    }
+}

package/dist/server/seed/lexicon.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The words `tablewalk seed` picks by meaning. A schema says what it is about
+ * in its table and column names (appointments, patients, lab_results; orders,
+ * carts, SKUs), so the words are chosen from that: a domain for the whole
+ * database, then, inside it, the list a table or a column calls for — a
+ * department is Cardiology in a clinic and Grocery in a shop, a staff title is
+ * a Registered nurse or a Cashier, a lab test is not a "Lab order 39". A schema
+ * that says nothing gets neutral, plausible text rather than another domain's
+ * parts and faults.
+ */
+export type DomainId = 'clinical' | 'retail' | 'logistics' | 'finance' | 'hr' | 'education' | 'property' | 'repair' | 'general';
+/** The domain a schema is about: the one whose signals its table names (heavier) and column names hit most. */
+export declare function detectDomain(tables: readonly string[], columns: readonly string[]): DomainId;
+/**
+ * The named rows of a lookup table — its first n, a handful, each its own — or undefined when no list fits and the
+ * table is better named by its word and a number ("Ward 3").
+ */
+export declare function lookupList(domain: DomainId, tableName: string): string[] | undefined;
+/** The pool a name column draws from in a table that is not a lookup: a drug, a test, a product; undefined for no pool. */
+export declare function entityNames(domain: DomainId, tableName: string): string[] | undefined;
+type Meaning = 'job' | 'subject' | 'reason' | 'notes' | 'category' | 'department' | 'specialty' | 'diagnosis' | 'test' | 'procedure' | 'drug';
+/** The meaning a text column's name has in this table, when a domain list answers it. */
+export declare function meaningOf(column: string, tableName: string, staffLike: boolean): Meaning | undefined;
+/** The list a meaning draws from, in this domain. */
+export declare function wordsFor(domain: DomainId, meaning: Meaning): string[];
+export {};