ekwo-os 0.4.1

package/dist/migrations.js

@@ -0,0 +1,226 @@
+/**
+ * The migration runner.
+ *
+ * It applies `supabase/migrations/*.sql` in filename order and records what
+ * it did in `supabase_migrations.schema_migrations`, **in the format the
+ * Supabase CLI uses** — same schema, same table, same three columns, version
+ * being the timestamp prefix of the filename. That is the whole point: an
+ * installation set up with `ekwo init` can later be pushed to with
+ * `supabase db push`, and one set up with `supabase db push` can be brought
+ * forward with `ekwo migrate`. The two are interchangeable because they read
+ * and write the same history.
+ *
+ * Each file is applied inside one transaction together with its history row,
+ * so a migration that fails halfway leaves neither half-applied schema nor a
+ * history row that lies. Re-running resumes at the file that failed.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const FILE_PATTERN = /^(\d{14})_(.+)\.sql$/;
+/** Parses a migration filename, or returns `undefined` if it is not one. */
+export function parseMigrationFile(file) {
+    const match = FILE_PATTERN.exec(file);
+    if (match === null)
+        return undefined;
+    const [, version, name] = match;
+    if (version === undefined || name === undefined)
+        return undefined;
+    return { version, name, file };
+}
+/** Every migration in `dir`, in the order they must be applied. */
+export async function listMigrations(dir) {
+    const files = (await readdir(dir)).filter((f) => f.endsWith('.sql')).sort();
+    const migrations = [];
+    for (const file of files) {
+        const parsed = parseMigrationFile(file);
+        if (parsed === undefined) {
+            throw new Error(`migration_name_invalid: ${file} — expected YYYYMMDDHHMMSS_subject.sql`);
+        }
+        migrations.push({ ...parsed, path: join(dir, file) });
+    }
+    return migrations;
+}
+/**
+ * The history table, created exactly as the Supabase CLI creates it.
+ *
+ * The columns are added one by one with `if not exists`, so this is safe on a
+ * project the Supabase CLI has already touched, whichever version of it.
+ */
+export async function ensureHistory(db) {
+    await db.exec(`
+    create schema if not exists supabase_migrations;
+    create table if not exists supabase_migrations.schema_migrations (
+      version text not null primary key
+    );
+    alter table supabase_migrations.schema_migrations
+      add column if not exists statements text[];
+    alter table supabase_migrations.schema_migrations
+      add column if not exists name text;
+  `);
+}
+/** Versions already recorded, oldest first. */
+export async function appliedVersions(db) {
+    const rows = await db.query('select version from supabase_migrations.schema_migrations order by version');
+    return rows.map((r) => r.version);
+}
+/** What separates the database from the migrations this CLI carries. */
+export async function migrationGap(db, all) {
+    await ensureHistory(db);
+    const applied = await appliedVersions(db);
+    const appliedSet = new Set(applied);
+    const shipped = new Set(all.map((m) => m.version));
+    return {
+        applied,
+        pending: all.filter((m) => !appliedSet.has(m.version)),
+        unknown: applied.filter((v) => !shipped.has(v)),
+    };
+}
+/**
+ * Applies one migration and records it, atomically.
+ *
+ * The file is sent as a single command string, so Postgres runs it as one
+ * unit inside the transaction we opened. No file in this repository opens a
+ * transaction of its own, and none may: the runner owns that.
+ */
+export async function applyMigration(db, migration) {
+    const sql = await readFile(migration.path, 'utf8');
+    const statements = splitStatements(sql);
+    await db.transaction(async (tx) => {
+        await tx.exec(sql);
+        await tx.query(`insert into supabase_migrations.schema_migrations (version, name, statements)
+       values ($1, $2, $3)
+       on conflict (version) do nothing`, [migration.version, migration.name, statements]);
+    });
+}
+/** Applies every pending migration, in order, reporting each one as it lands. */
+export async function applyMigrations(db, all, onApplied) {
+    const gap = await migrationGap(db, all);
+    for (const migration of gap.pending) {
+        await applyMigration(db, migration);
+        onApplied?.(migration);
+    }
+    return { applied: gap.pending, alreadyApplied: gap.applied.length };
+}
+/**
+ * Splits a SQL file into statements, for the `statements` column only.
+ *
+ * Execution never goes through this: the file is handed to Postgres whole.
+ * The column is what `supabase migration repair` and `supabase db diff` read
+ * back, so it should hold statements rather than one blob — but a mistake
+ * here can only make that column less pretty, never break an installation.
+ *
+ * Handles line and block comments, single- and double-quoted literals,
+ * `E''` backslash escapes and dollar quoting with tags, which is what the
+ * function bodies in this schema are made of.
+ */
+export function splitStatements(sql) {
+    const statements = [];
+    let current = '';
+    let index = 0;
+    const push = () => {
+        const trimmed = current.trim();
+        if (trimmed.length > 0)
+            statements.push(trimmed);
+        current = '';
+    };
+    while (index < sql.length) {
+        const char = sql[index];
+        const next = sql[index + 1];
+        // Line comment.
+        if (char === '-' && next === '-') {
+            const end = sql.indexOf('\n', index);
+            const stop = end === -1 ? sql.length : end;
+            current += sql.slice(index, stop);
+            index = stop;
+            continue;
+        }
+        // Block comment, which nests in Postgres.
+        if (char === '/' && next === '*') {
+            let depth = 0;
+            const start = index;
+            while (index < sql.length) {
+                if (sql[index] === '/' && sql[index + 1] === '*') {
+                    depth += 1;
+                    index += 2;
+                }
+                else if (sql[index] === '*' && sql[index + 1] === '/') {
+                    depth -= 1;
+                    index += 2;
+                    if (depth === 0)
+                        break;
+                }
+                else {
+                    index += 1;
+                }
+            }
+            current += sql.slice(start, index);
+            continue;
+        }
+        // Dollar-quoted string: $$ … $$ or $tag$ … $tag$.
+        if (char === '$') {
+            const tag = DOLLAR_TAG.exec(sql.slice(index));
+            if (tag !== null) {
+                const marker = tag[0];
+                const end = sql.indexOf(marker, index + marker.length);
+                const stop = end === -1 ? sql.length : end + marker.length;
+                current += sql.slice(index, stop);
+                index = stop;
+                continue;
+            }
+        }
+        // Single-quoted literal. Backslash escapes only after E''.
+        if (char === "'") {
+            const escaped = /[eE]$/.test(current);
+            const start = index;
+            index += 1;
+            while (index < sql.length) {
+                if (escaped && sql[index] === BACKSLASH) {
+                    index += 2;
+                    continue;
+                }
+                if (sql[index] === "'") {
+                    if (sql[index + 1] === "'") {
+                        index += 2;
+                        continue;
+                    }
+                    index += 1;
+                    break;
+                }
+                index += 1;
+            }
+            current += sql.slice(start, index);
+            continue;
+        }
+        // Quoted identifier.
+        if (char === '"') {
+            const start = index;
+            index += 1;
+            while (index < sql.length) {
+                if (sql[index] === '"') {
+                    if (sql[index + 1] === '"') {
+                        index += 2;
+                        continue;
+                    }
+                    index += 1;
+                    break;
+                }
+                index += 1;
+            }
+            current += sql.slice(start, index);
+            continue;
+        }
+        if (char === ';') {
+            current += char;
+            push();
+            index += 1;
+            continue;
+        }
+        current += char;
+        index += 1;
+    }
+    push();
+    return statements;
+}
+const DOLLAR_TAG = /^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/;
+const BACKSLASH = String.fromCharCode(92);
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}

package/dist/module/read.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The modules this checkout — or this published package — carries.
+ *
+ * A module is a folder: a manifest, a `supabase/migrations/` of its own, a
+ * README and its tests. There is no registry in code here either: the folders
+ * are the list, `module.json` is what each one says about itself, and
+ * `public.modules` is what the database holds once its migrations have run.
+ *
+ * Nothing in this file talks to a database. Reading and validating a manifest
+ * is the same work whether the next step is `ekwo module list` in a checkout
+ * or `ekwo migrate` against a Supabase project, so it is done once, here.
+ */
+import { type Migration } from '../migrations.js';
+export declare class ModuleError extends Error {
+}
+export interface ModuleMcp {
+    prefix: string;
+}
+export interface ModulePack {
+    /** `assets` → a country pack may carry `packs/<cc>/assets.json`. */
+    section: string;
+}
+export interface ModuleManifest {
+    code: string;
+    name: string;
+    description?: string;
+    schema: string;
+    version: string;
+    status: 'draft' | 'available' | 'deprecated';
+    requires_socle_min?: string;
+    posts?: boolean;
+    mcp?: ModuleMcp;
+    pack?: ModulePack;
+}
+export interface EkwoModule {
+    manifest: ModuleManifest;
+    /** Absolute path of `modules/<code>/`. */
+    dir: string;
+    /** Its own migrations, in the order they must be applied. */
+    migrations: Migration[];
+}
+/**
+ * Where the modules live.
+ *
+ * Published package: `dist/assets/modules/`, put there at build time by
+ * `scripts/copy-assets.mjs`, because `npx ekwo-os migrate` has no clone. Checkout:
+ * `<repo>/modules/`. The two candidates mirror `resolveBundleDir()`.
+ */
+export declare function resolveModulesDir(): string | undefined;
+/** `modules/schema/module.1.json`, the published shape of a manifest. */
+export declare function readModuleSchema(dir: string): Promise<Record<string, unknown>>;
+/** The module folders of `dir`, by code, in the order they are applied. */
+export declare function listModules(dir?: string | undefined): Promise<EkwoModule[]>;
+/** One module, with its manifest validated and its migrations listed. */
+export declare function readModule(code: string, dir?: string | undefined, schema?: Record<string, unknown>): Promise<EkwoModule>;
+/**
+ * A module's migrations, recorded under the same history the socle uses.
+ *
+ * `version` stays the plain timestamp, because that is the column Supabase
+ * keys its history on and the whole point of that choice is that `ekwo
+ * migrate` and `supabase db push` read and write the same table. What carries
+ * the module is `name`: `assets/initial` rather than `initial`, so a human
+ * reading `supabase migration list` sees which module a version belongs to.
+ *
+ * The consequence, which is a rule and a test: a module's timestamps sort
+ * after every socle migration it depends on, and no two migrations anywhere in
+ * this repository share a version.
+ */
+export declare function moduleMigrations(manifest: ModuleManifest, folder: string): Promise<Migration[]>;
+/**
+ * Every module migration, in one list, ordered by version.
+ *
+ * Concatenated with the socle's and sorted, this is what `ekwo migrate`
+ * applies. A duplicate version is a bug in whoever wrote the second one and is
+ * refused here rather than silently dropping a file, which is exactly what the
+ * Supabase history does when two files share a timestamp prefix.
+ */
+export declare function allModuleMigrations(modules: readonly EkwoModule[]): Migration[];
+/**
+ * The seeds compiled from the `<section>.json` of a country pack, for one
+ * module: `supabase/seed/modules/<code>/*.sql`.
+ *
+ * They are not reference data of the socle and are deliberately not in
+ * `supabase/seed/` itself, where `ekwo migrate` and the test harness read a
+ * flat directory: a module's country data has no business landing on an
+ * installation that does not carry the module.
+ */
+export declare function moduleSeeds(code: string, seedDir: string): Promise<string[]>;
+/** The line an operator has to add by hand, because no migration can. */
+export declare function exposeSchemaNote(schemaName: string): string[];
+//# sourceMappingURL=read.d.ts.map

package/dist/module/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/module/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGtE,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAUtD;AAED,yEAAyE;AACzE,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMpF;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,GAAG,qBAAsB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAalF;AAED,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,qBAAsB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,UAAU,CAAC,CA6BrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,EAAE,CAAC,CAkBtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,EAAE,CAgB/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOlF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAO7D"}

package/dist/module/read.js

@@ -0,0 +1,172 @@
+/**
+ * The modules this checkout — or this published package — carries.
+ *
+ * A module is a folder: a manifest, a `supabase/migrations/` of its own, a
+ * README and its tests. There is no registry in code here either: the folders
+ * are the list, `module.json` is what each one says about itself, and
+ * `public.modules` is what the database holds once its migrations have run.
+ *
+ * Nothing in this file talks to a database. Reading and validating a manifest
+ * is the same work whether the next step is `ekwo module list` in a checkout
+ * or `ekwo migrate` against a Supabase project, so it is done once, here.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseMigrationFile } from '../migrations.js';
+import { validate } from '../pack/schema.js';
+export class ModuleError extends Error {
+}
+/**
+ * Where the modules live.
+ *
+ * Published package: `dist/assets/modules/`, put there at build time by
+ * `scripts/copy-assets.mjs`, because `npx ekwo-os migrate` has no clone. Checkout:
+ * `<repo>/modules/`. The two candidates mirror `resolveBundleDir()`.
+ */
+export function resolveModulesDir() {
+    const candidates = [
+        new URL('../assets/modules/', import.meta.url),
+        new URL('../../../../modules/', import.meta.url),
+    ];
+    for (const candidate of candidates) {
+        const dir = fileURLToPath(candidate).replace(/\/$/, '');
+        if (existsSync(dir))
+            return dir;
+    }
+    return undefined;
+}
+/** `modules/schema/module.1.json`, the published shape of a manifest. */
+export async function readModuleSchema(dir) {
+    const path = join(dir, 'schema', 'module.1.json');
+    const raw = await readFile(path, 'utf8').catch(() => {
+        throw new ModuleError(`module_schema_missing: ${path}`);
+    });
+    return JSON.parse(raw);
+}
+/** The module folders of `dir`, by code, in the order they are applied. */
+export async function listModules(dir = resolveModulesDir()) {
+    if (dir === undefined)
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const schema = await readModuleSchema(dir);
+    const modules = [];
+    for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory() || entry.name === 'schema')
+            continue;
+        const folder = join(dir, entry.name);
+        if (!existsSync(join(folder, 'module.json')))
+            continue;
+        modules.push(await readModule(entry.name, dir, schema));
+    }
+    return modules;
+}
+/** One module, with its manifest validated and its migrations listed. */
+export async function readModule(code, dir = resolveModulesDir(), schema) {
+    if (dir === undefined)
+        throw new ModuleError('modules_missing: this installation carries no modules folder');
+    const folder = join(dir, code);
+    const manifestPath = join(folder, 'module.json');
+    const raw = await readFile(manifestPath, 'utf8').catch(() => {
+        throw new ModuleError(`unknown_module: ${manifestPath} does not exist`);
+    });
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ModuleError(`module_manifest_invalid: ${code}/module.json — ${error.message}`);
+    }
+    const issues = validate(manifest, schema ?? (await readModuleSchema(dir)));
+    if (issues.length > 0) {
+        throw new ModuleError(`module_manifest_invalid: ${code}/module.json\n` +
+            issues.map((issue) => `  ${issue.path}: ${issue.message}`).join('\n'));
+    }
+    if (manifest.code !== code) {
+        throw new ModuleError(`module_code_mismatch: modules/${code}/module.json calls itself "${manifest.code}"`);
+    }
+    return { manifest, dir: folder, migrations: await moduleMigrations(manifest, folder) };
+}
+/**
+ * A module's migrations, recorded under the same history the socle uses.
+ *
+ * `version` stays the plain timestamp, because that is the column Supabase
+ * keys its history on and the whole point of that choice is that `ekwo
+ * migrate` and `supabase db push` read and write the same table. What carries
+ * the module is `name`: `assets/initial` rather than `initial`, so a human
+ * reading `supabase migration list` sees which module a version belongs to.
+ *
+ * The consequence, which is a rule and a test: a module's timestamps sort
+ * after every socle migration it depends on, and no two migrations anywhere in
+ * this repository share a version.
+ */
+export async function moduleMigrations(manifest, folder) {
+    const dir = join(folder, 'supabase', 'migrations');
+    if (!existsSync(dir))
+        return [];
+    const files = (await readdir(dir)).filter((f) => f.endsWith('.sql')).sort();
+    return files.map((file) => {
+        const parsed = parseMigrationFile(file);
+        if (parsed === undefined) {
+            throw new ModuleError(`migration_name_invalid: modules/${manifest.code}/supabase/migrations/${file} — expected YYYYMMDDHHMMSS_subject.sql`);
+        }
+        return {
+            version: parsed.version,
+            name: `${manifest.code}/${parsed.name}`,
+            file: parsed.file,
+            path: join(dir, file),
+        };
+    });
+}
+/**
+ * Every module migration, in one list, ordered by version.
+ *
+ * Concatenated with the socle's and sorted, this is what `ekwo migrate`
+ * applies. A duplicate version is a bug in whoever wrote the second one and is
+ * refused here rather than silently dropping a file, which is exactly what the
+ * Supabase history does when two files share a timestamp prefix.
+ */
+export function allModuleMigrations(modules) {
+    const seen = new Map();
+    const all = [];
+    for (const module of modules) {
+        for (const migration of module.migrations) {
+            const previous = seen.get(migration.version);
+            if (previous !== undefined) {
+                throw new ModuleError(`migration_version_duplicate: ${migration.version} is used by ${previous} and by ${migration.name}`);
+            }
+            seen.set(migration.version, migration.name);
+            all.push(migration);
+        }
+    }
+    return all.sort((a, b) => a.version.localeCompare(b.version));
+}
+/**
+ * The seeds compiled from the `<section>.json` of a country pack, for one
+ * module: `supabase/seed/modules/<code>/*.sql`.
+ *
+ * They are not reference data of the socle and are deliberately not in
+ * `supabase/seed/` itself, where `ekwo migrate` and the test harness read a
+ * flat directory: a module's country data has no business landing on an
+ * installation that does not carry the module.
+ */
+export async function moduleSeeds(code, seedDir) {
+    const dir = join(seedDir, 'modules', code);
+    if (!existsSync(dir))
+        return [];
+    return (await readdir(dir))
+        .filter((f) => f.endsWith('.sql'))
+        .sort()
+        .map((file) => join(dir, file));
+}
+/** The line an operator has to add by hand, because no migration can. */
+export function exposeSchemaNote(schemaName) {
+    return [
+        `PostgREST does not serve \`${schemaName}\` until the project exposes it.`,
+        `  Supabase dashboard → Project Settings → API → Exposed schemas: add \`${schemaName}\`.`,
+        `  Self-hosted: add it to \`[api] schemas\` in supabase/config.toml and restart.`,
+        'No migration can do this: it is a setting of the API, not of the database.',
+    ];
+}
+//# sourceMappingURL=read.js.map

package/dist/module/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/module/read.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The output contract: what a command answers, and with which exit code.
+ *
+ * Every command of this CLI is run through `execute()`, so the contract is
+ * written once and a command cannot opt out of it by forgetting.
+ *
+ *   0  done.
+ *   1  it did not end well and the books were not asked: the network, a
+ *      database that does not answer, a bug — and a check that found
+ *      something (`doctor`, `pack check`, a pending migration), which is how
+ *      a CI job goes red.
+ *   2  the command was called wrong: an unknown option, a missing argument,
+ *      a question that needed an answer and no terminal to ask it on.
+ *   3  the database refused. A locked period, a capability the caller does
+ *      not hold, a tax that does not apply here. The command was well formed
+ *      and everything worked; the accounting said no.
+ *
+ * A caller — an agent with a shell, a Makefile — has to tell 2 from 3 without
+ * reading a sentence, and that is the reason 3 exists.
+ *
+ * The refusal itself is printed as the database wrote it. Its name
+ * (`period_locked`) is the part a program matches on and its sentence is the
+ * part a person reads; neither is rephrased here, and nothing in this file
+ * knows what any of the names mean. Which SQLSTATEs count as a refusal and
+ * how a name is read out of a message are in `@ekwo-ai/core`, where the MCP
+ * server reads them too.
+ */
+import { type ParsedArgs } from './args.js';
+export declare const EXIT_OK = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_REFUSED = 3;
+export type ErrorKind = 'refusal' | 'usage' | 'technical';
+export interface OutputError {
+    kind: ErrorKind;
+    /** `period_locked`, when the message carries a name. Never invented. */
+    name?: string;
+    /** What was said, word for word. */
+    message: string;
+    /** What Postgres called it, when the error came from the database. */
+    sqlstate?: string;
+    /** The DETAIL and HINT of the raise, when the database gave them. */
+    detail?: string;
+    hint?: string;
+}
+/** The one JSON document a command writes under `--json`. */
+export interface OutputDocument {
+    ok: boolean;
+    command: string;
+    exitCode: number;
+    /** What the command has to say. Absent when it failed before having any. */
+    data?: unknown;
+    /**
+     * On whose behalf, where, and for which company the answer was rendered.
+     * Present on every command that acts as a person; absent on the commands
+     * that install and operate, which act as nobody.
+     */
+    context?: OutputContext;
+    /** Every warning the command printed, without the colours. */
+    warnings: string[];
+    error?: OutputError;
+}
+/**
+ * What a caller checks before it believes the rest.
+ *
+ * An agent that keeps the books of two companies and answers for the wrong
+ * one has made the one mistake no total will reveal. So the company is in the
+ * document itself — `null` when none is in use — on success and on a refusal
+ * alike, as soon as it is known.
+ */
+export interface OutputContext {
+    /** `null` when the environment said who, and no profile was read. */
+    profile: string | null;
+    instance: string;
+    company: {
+        id: string;
+        name: string;
+    } | null;
+}
+/** Called by a command that acts as a person, as soon as it knows for which company. */
+export declare function setContext(value: OutputContext): void;
+/**
+ * What the command answers under `--json`.
+ *
+ * Called by the command with the same values it prints, never with values of
+ * its own: a figure that exists in one of the two forms only is a bug.
+ */
+export declare function setResult(data: unknown): void;
+/** `module list`, `pack upgrade`, `status`: the words that named the command. */
+export declare function commandLabel(args: ParsedArgs): string;
+/** Which of the three an error is, and with it the exit code. */
+export declare function classify(error: unknown): {
+    exitCode: number;
+    error: OutputError;
+};
+/** `--json` as it was typed, for the errors that happen before flags are read. */
+export declare function askedForJson(argv: readonly string[]): boolean;
+/** An error met before any command ran: a bad option, an unknown command. */
+export declare function reportFailure(command: string, json: boolean, error: unknown): number;
+/**
+ * Runs one command under the contract.
+ *
+ * The handler prints for a person as it goes and hands `setResult()` what a
+ * program should read. Here the two are kept apart: under `--json` the prose
+ * has already gone to the standard error, and the standard output receives
+ * exactly one document — on success, on a finding, and on a refusal alike, so
+ * a caller parses the same shape whatever happened.
+ */
+export declare function execute(args: ParsedArgs, json: boolean, handler: () => Promise<number>): Promise<number>;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAIxD,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAKD,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAID,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAWrD;AAQD,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CA8BjF;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM7D;AAQD,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,CA6BjB"}