@cogenta/cli 0.1.0

package/dist/commands/skin.js

@@ -0,0 +1,199 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import process from 'node:process';
+import { createAnthropicClient, createGoogleClient, createOpenAiClient, generateSkin, } from '@cogenta/agents';
+import { CogentaError, isCogentaError, loadConfig } from '@cogenta/core';
+import { TOKEN_GROUPS, validateSkin } from '@cogenta/render';
+const TOKENS_FILE = 'theme.tokens.json';
+const USAGE = `Usage
+  cogenta skin list                       Show the site's active skin
+  cogenta skin validate <tokens.json>     Check a token file against contract D
+  cogenta skin apply <tokens.json>        Validate, then make it the active skin
+  cogenta skin generate --description "…" Generate a skin from a description
+
+"generate" needs an LLM provider configured (cogenta.config's llm block, or
+COGENTA_LLM_* environment variables) — the CMS works without one (R2), so
+"skin generate" is the one skin subcommand that refuses without it.
+`;
+async function resolveProjectRoot(options) {
+    const env = options.env ?? process.env;
+    const loaded = await loadConfig({
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env,
+    });
+    return loaded.path === null ? resolvePath(options.cwd ?? process.cwd()) : dirname(loaded.path);
+}
+function reportCogentaError(error, stderr) {
+    if (isCogentaError(error)) {
+        stderr(`${error.code}: ${error.message}\n`);
+        if (error.hint !== undefined)
+            stderr(`${error.hint}\n`);
+    }
+    else {
+        stderr(`${error instanceof Error ? error.stack : String(error)}\n`);
+    }
+}
+async function readTokensFile(path) {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+}
+/** Validates, then writes — a skin is never applied without passing contract D first. */
+async function applyTokens(tokens, projectRoot) {
+    const path = join(projectRoot, TOKENS_FILE);
+    await writeFile(path, `${JSON.stringify(tokens, null, 2)}\n`, 'utf8');
+    return path;
+}
+async function runList(options) {
+    const { out, stderr } = options;
+    const projectRoot = await resolveProjectRoot(options);
+    const path = join(projectRoot, TOKENS_FILE);
+    let candidate;
+    try {
+        candidate = await readTokensFile(path);
+    }
+    catch (error) {
+        stderr(`Could not read ${path}: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    try {
+        const tokens = validateSkin(candidate);
+        out.heading('Active skin');
+        out.line(path);
+        for (const group of TOKEN_GROUPS) {
+            out.line(`${group}: ${JSON.stringify(tokens[group])}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        reportCogentaError(error, stderr);
+        return 1;
+    }
+}
+async function runValidate(options) {
+    const { out, stderr } = options;
+    if (options.file === undefined || options.file.trim().length === 0) {
+        stderr(`A file path is required.\n\n${USAGE}`);
+        return 2;
+    }
+    let candidate;
+    try {
+        candidate = await readTokensFile(options.file);
+    }
+    catch (error) {
+        stderr(`Could not read "${options.file}": ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    try {
+        validateSkin(candidate);
+        out.ok(`${options.file} is a valid skin.`);
+        return 0;
+    }
+    catch (error) {
+        reportCogentaError(error, stderr);
+        return 1;
+    }
+}
+async function runApply(options) {
+    const { out, stderr } = options;
+    if (options.file === undefined || options.file.trim().length === 0) {
+        stderr(`A file path is required.\n\n${USAGE}`);
+        return 2;
+    }
+    let candidate;
+    try {
+        candidate = await readTokensFile(options.file);
+    }
+    catch (error) {
+        stderr(`Could not read "${options.file}": ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    try {
+        const tokens = validateSkin(candidate);
+        const projectRoot = await resolveProjectRoot(options);
+        const written = await applyTokens(tokens, projectRoot);
+        out.ok(`Applied. ${written}`);
+        return 0;
+    }
+    catch (error) {
+        reportCogentaError(error, stderr);
+        return 1;
+    }
+}
+/** The same adapter construction `create-cogenta`'s `llm-setup.ts` uses for its own provider client — kept as a small, local switch rather than a shared dependency, since the CLI's only need is "one client for the configured provider," with its own test seam. */
+function clientFor(provider, apiKey, model, fetchImpl) {
+    const config = { apiKey, model, ...(fetchImpl === undefined ? {} : { fetchImpl }) };
+    if (provider === 'anthropic')
+        return createAnthropicClient(config);
+    if (provider === 'openai')
+        return createOpenAiClient(config);
+    if (provider === 'google')
+        return createGoogleClient(config);
+    throw new CogentaError({
+        code: 'PROVIDER_UNKNOWN',
+        message: `No provider named "${provider}" is configured for this site.`,
+        hint: 'Set llm.provider in cogenta.config to "anthropic", "openai" or "google".',
+    });
+}
+async function runGenerateSkin(options) {
+    const { out, stderr } = options;
+    if (options.description === undefined || options.description.trim().length === 0) {
+        stderr(`--description is required.\n\n${USAGE}`);
+        return 2;
+    }
+    const env = options.env ?? process.env;
+    const loaded = await loadConfig({
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env,
+    });
+    if (loaded.config.llm === undefined || loaded.config.llm.apiKey === undefined) {
+        stderr('No LLM provider is configured for this site — the CMS works without one (R2).\n');
+        stderr('Set llm.provider/llm.model in cogenta.config and COGENTA_LLM_API_KEY to use this.\n');
+        return 1;
+    }
+    const projectRoot = loaded.path === null ? resolvePath(options.cwd ?? process.cwd()) : dirname(loaded.path);
+    try {
+        const client = clientFor(loaded.config.llm.provider, loaded.config.llm.apiKey, loaded.config.llm.model, options.fetchImpl);
+        out.detail(`Generating a skin from your description…`);
+        const result = await generateSkin({
+            client,
+            model: loaded.config.llm.model,
+            description: options.description,
+            blueprintLabel: loaded.config.site.name,
+        });
+        if (!result.ok) {
+            stderr(`${result.attempts} attempt${result.attempts === 1 ? '' : 's'} all failed validation: ${result.reason}\n`);
+            stderr('The site keeps its current skin — nothing was written.\n');
+            return 1;
+        }
+        const written = await applyTokens(result.tokens, projectRoot);
+        out.ok(`Skin generated and validated in ${result.attempts} attempt${result.attempts === 1 ? '' : 's'}. Applied. ${written}`);
+        return 0;
+    }
+    catch (error) {
+        reportCogentaError(error, stderr);
+        return 1;
+    }
+}
+/**
+ * `cogenta skin` — 0 the operation succeeded (including a valid `validate`).
+ * 1 an invalid skin, a missing file, or a real failure. 2 the command line
+ * was wrong.
+ */
+export async function runSkin(options) {
+    const { stderr } = options;
+    if (options.subcommand === undefined) {
+        stderr(`cogenta skin needs a subcommand.\n\n${USAGE}`);
+        return 2;
+    }
+    if (options.subcommand === 'list')
+        return runList(options);
+    if (options.subcommand === 'validate')
+        return runValidate(options);
+    if (options.subcommand === 'apply')
+        return runApply(options);
+    if (options.subcommand === 'generate')
+        return runGenerateSkin(options);
+    stderr(`Unknown subcommand "${options.subcommand}".\n\n${USAGE}`);
+    return 2;
+}
+//# sourceMappingURL=skin.js.map

package/dist/commands/skin.js.map

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

package/dist/commands/users.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from '@cogenta/core';
+import type { Output, Writer } from '../output.js';
+export type UsersSubcommand = 'create';
+export interface UsersOptions {
+    readonly subcommand: string | undefined;
+    readonly cwd?: string;
+    readonly env?: Record<string, string | undefined>;
+    readonly logger?: Logger;
+    readonly out: Output;
+    readonly stderr: Writer;
+    readonly email?: string;
+    readonly roles?: string;
+    readonly admin?: boolean;
+}
+/**
+ * Runs one `users` subcommand and returns its exit code.
+ *
+ * 0 succeeded, 1 the database or the store said no, 2 the command line was
+ * wrong — same convention as `migrate` and `doctor`.
+ */
+export declare function runUsers(options: UsersOptions): Promise<number>;
+//# sourceMappingURL=users.d.ts.map

package/dist/commands/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/commands/users.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,MAAM,EAEZ,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAElD,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAA;AAEtC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB;AAuDD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAsDrE"}

package/dist/commands/users.js

@@ -0,0 +1,107 @@
+import { randomBytes } from 'node:crypto';
+import process from 'node:process';
+import { createCredentialStore, createUserStore, ensureAuthTables } from '@cogenta/auth';
+import { createDatabaseRegistry, createLogger, isCogentaError, loadConfig, } from '@cogenta/core';
+const USAGE = `Usage
+  cogenta users create --email <email> [--roles <role,role>] [--admin]
+
+The very first admin account is created this way — there is no other way in,
+since the admin UI needs one to sign in to. A random password is generated and
+printed once; it is never stored anywhere but the credential table's hash.
+
+Options
+  --admin   Shorthand for --roles admin
+`;
+/** Base64url, so it is safe to read off a terminal and paste back with no escaping. */
+function generatePassword() {
+    return randomBytes(24).toString('base64url');
+}
+function parseRoles(options) {
+    if (options.admin === true && options.roles !== undefined) {
+        return { error: '--admin and --roles are mutually exclusive — --admin already means admin.' };
+    }
+    if (options.admin === true)
+        return ['admin'];
+    if (options.roles === undefined) {
+        return { error: 'Name at least one role with --roles, or pass --admin for the first account.' };
+    }
+    const roles = options.roles
+        .split(',')
+        .map((role) => role.trim())
+        .filter((role) => role.length > 0);
+    if (roles.length === 0) {
+        return { error: '--roles was given but named no role.' };
+    }
+    return roles;
+}
+async function withDatabase(options, logger, use) {
+    const env = options.env ?? process.env;
+    const loaded = await loadConfig({
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env,
+    });
+    const selection = await createDatabaseRegistry({ logger }).select(loaded.config.database);
+    try {
+        return await use(selection.instance);
+    }
+    finally {
+        await selection.dispose();
+    }
+}
+/**
+ * Runs one `users` subcommand and returns its exit code.
+ *
+ * 0 succeeded, 1 the database or the store said no, 2 the command line was
+ * wrong — same convention as `migrate` and `doctor`.
+ */
+export async function runUsers(options) {
+    const { out, stderr } = options;
+    if (options.subcommand === undefined) {
+        stderr(`cogenta users needs a subcommand.\n\n${USAGE}`);
+        return 2;
+    }
+    if (options.subcommand !== 'create') {
+        stderr(`Unknown subcommand "${options.subcommand}".\n\n${USAGE}`);
+        return 2;
+    }
+    if (options.email === undefined || options.email.trim().length === 0) {
+        stderr(`--email is required.\n\n${USAGE}`);
+        return 2;
+    }
+    const roles = parseRoles(options);
+    if ('error' in roles) {
+        stderr(`${roles.error}\n\n${USAGE}`);
+        return 2;
+    }
+    const logger = options.logger ?? createLogger({ level: 'silent' });
+    const password = generatePassword();
+    try {
+        return await withDatabase(options, logger, async (db) => {
+            await ensureAuthTables(db);
+            const users = createUserStore(db);
+            const credentials = createCredentialStore(db);
+            const user = await users.create({ email: options.email, roles });
+            await credentials.setPassword(user.id, password);
+            out.heading('User created');
+            out.ok(`${user.email} — ${user.roles.join(', ')}`);
+            out.line();
+            out.line(`Password: ${password}`);
+            out.line();
+            out.warn('This password is shown once. It is stored only as a salted hash.');
+            out.detail('A role that can publish, or admin, will be asked to set up a second factor at first sign-in.');
+            return 0;
+        });
+    }
+    catch (error) {
+        if (isCogentaError(error)) {
+            stderr(`${error.code}: ${error.message}\n`);
+            if (error.hint !== undefined)
+                stderr(`${error.hint}\n`);
+        }
+        else {
+            stderr(`${error instanceof Error ? error.stack : String(error)}\n`);
+        }
+        return 1;
+    }
+}
+//# sourceMappingURL=users.js.map

package/dist/commands/users.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { type Writer } from './output.js';
+export type { DoctorCheck, DoctorOptions, DoctorReport } from './commands/doctor.js';
+export { formatDoctorReport, runDoctor } from './commands/doctor.js';
+export type { GenerateOptions, GenerateSubcommand } from './commands/generate.js';
+export { runGenerate } from './commands/generate.js';
+export type { ImportOptions, ImportSubcommand } from './commands/import.js';
+export { runImport } from './commands/import.js';
+export type { MigrateOptions, MigrateSubcommand } from './commands/migrate.js';
+export { loadMigrations, MIGRATIONS_DIRECTORY, runMigrate } from './commands/migrate.js';
+export type { ServeOptions } from './commands/serve.js';
+export { loadCollections, runServe } from './commands/serve.js';
+export type { SkinOptions, SkinSubcommand } from './commands/skin.js';
+export { runSkin } from './commands/skin.js';
+export type { UsersOptions, UsersSubcommand } from './commands/users.js';
+export { runUsers } from './commands/users.js';
+export type { Output, Writer } from './output.js';
+export { createOutput, shouldUseColour } from './output.js';
+export interface RunOptions {
+    readonly argv: readonly string[];
+    readonly stdout?: Writer;
+    readonly stderr?: Writer;
+    readonly env?: Record<string, string | undefined>;
+    readonly isTty?: boolean;
+    readonly version?: string;
+    /** Stops `serve` when aborted. Ignored by every other command. */
+    readonly signal?: AbortSignal;
+    /** `serve` only: reports the bound address once listening (tests need the OS-assigned port). */
+    readonly onListening?: (address: {
+        port: number;
+        host: string;
+    }) => void;
+}
+/**
+ * Runs one command and returns its exit code.
+ *
+ * Nothing here calls `process.exit` or writes to a stream directly: the streams
+ * are injected, so the whole CLI is testable without spawning a process or
+ * capturing stdout.
+ */
+export declare function run(options: RunOptions): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAiC,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAExE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACpE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACxF,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAC5C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAkD3D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACzE;AAED;;;;;;GAMG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuL9D"}

package/dist/index.js

@@ -0,0 +1,244 @@
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { createLogger, isCogentaError } from '@cogenta/core';
+import { formatDoctorReport, runDoctor } from './commands/doctor.js';
+import { runGenerate } from './commands/generate.js';
+import { runImport } from './commands/import.js';
+import { runMigrate } from './commands/migrate.js';
+import { runServe } from './commands/serve.js';
+import { runSkin } from './commands/skin.js';
+import { runUsers } from './commands/users.js';
+import { createOutput, shouldUseColour } from './output.js';
+export { formatDoctorReport, runDoctor } from './commands/doctor.js';
+export { runGenerate } from './commands/generate.js';
+export { runImport } from './commands/import.js';
+export { loadMigrations, MIGRATIONS_DIRECTORY, runMigrate } from './commands/migrate.js';
+export { loadCollections, runServe } from './commands/serve.js';
+export { runSkin } from './commands/skin.js';
+export { runUsers } from './commands/users.js';
+export { createOutput, shouldUseColour } from './output.js';
+const USAGE = `cogenta — the command line for a Cogenta site
+
+Usage
+  cogenta <command> [options]
+
+Commands
+  doctor           Report which driver is running for each need, and why
+  migrate status   List every migration and whether it ran here
+  migrate up       Apply the pending migrations
+  migrate down     Revert applied migrations
+  users create     Create a user — the first admin account is made this way
+  import wordpress <file.xml>   Import a WordPress WXR export, with a report
+  generate types   Write TypeScript declarations for the content schema
+  skin list        Show the site's active skin
+  skin validate <tokens.json>   Check a token file against contract D
+  skin apply <tokens.json>      Validate, then make it the active skin
+  skin generate --description "…"   Generate a skin from a description
+  serve, dev       Run the content and auth API over HTTP
+  help             Show this message
+  version          Print the version
+
+Not built yet: build, backup, upgrade, deploy, theme, agent, and
+generate schema/generate migrations — see CLAUDE.md for why each is
+deferred rather than stubbed.
+
+Options
+  --cwd <path>            Run as if from this directory
+  --no-color              Never colour the output (NO_COLOR is honoured too)
+  --verbose               Send structured driver logs to stderr
+  --out <path>            generate types: where to write the declarations
+  --description <text>    skin generate: free text describing the site
+
+Migration options
+  --to <id>               Stop at this migration, inclusive
+  --steps <n>             How many migrations "migrate down" reverts (default 1)
+  --confirm-destructive   The impact of every destructive migration has been read
+  --backup-verified       A backup was taken and verified to restore
+
+User options
+  --email <email>         The new user's email
+  --roles <role,role>     Comma-separated role names
+  --admin                 Shorthand for --roles admin
+
+Serve options
+  --port <n>              Port to listen on (default 4000)
+  --host <host>           Host to bind to (default 127.0.0.1)
+`;
+/**
+ * Runs one command and returns its exit code.
+ *
+ * Nothing here calls `process.exit` or writes to a stream directly: the streams
+ * are injected, so the whole CLI is testable without spawning a process or
+ * capturing stdout.
+ */
+export async function run(options) {
+    const env = options.env ?? process.env;
+    const stdout = options.stdout ?? ((text) => void process.stdout.write(text));
+    const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...options.argv],
+            allowPositionals: true,
+            strict: true,
+            options: {
+                cwd: { type: 'string' },
+                'no-color': { type: 'boolean' },
+                verbose: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+                to: { type: 'string' },
+                steps: { type: 'string' },
+                'confirm-destructive': { type: 'boolean' },
+                'backup-verified': { type: 'boolean' },
+                email: { type: 'string' },
+                roles: { type: 'string' },
+                admin: { type: 'boolean' },
+                port: { type: 'string' },
+                host: { type: 'string' },
+                out: { type: 'string' },
+                description: { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        stderr(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+        return 2;
+    }
+    const colour = parsed.values['no-color'] === true ? false : shouldUseColour(env, options.isTty ?? false);
+    const out = createOutput(stdout, colour);
+    const command = parsed.positionals[0] ?? (parsed.values.version === true ? 'version' : 'help');
+    if (parsed.values.help === true || command === 'help') {
+        stdout(USAGE);
+        return 0;
+    }
+    if (command === 'version') {
+        stdout(`${options.version ?? '0.0.0'}\n`);
+        return 0;
+    }
+    const verboseLogger = parsed.values.verbose === true
+        ? createLogger({ level: 'debug', destination: stderr })
+        : undefined;
+    if (command === 'migrate') {
+        // `--steps` is a string here because parseArgs has no number type. A
+        // non-number is a usage error, not a silent 0 that would revert nothing.
+        let steps;
+        if (typeof parsed.values.steps === 'string') {
+            steps = Number(parsed.values.steps);
+            if (!Number.isInteger(steps) || steps < 1) {
+                stderr(`--steps must be a whole number of migrations, not "${parsed.values.steps}".\n`);
+                return 2;
+            }
+        }
+        return runMigrate({
+            subcommand: parsed.positionals[1],
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(typeof parsed.values.to === 'string' ? { to: parsed.values.to } : {}),
+            ...(steps === undefined ? {} : { steps }),
+            ...(parsed.values['confirm-destructive'] === true ? { confirmDestructive: true } : {}),
+            ...(parsed.values['backup-verified'] === true ? { backupVerified: true } : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+    }
+    if (command === 'users') {
+        return runUsers({
+            subcommand: parsed.positionals[1],
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(typeof parsed.values.email === 'string' ? { email: parsed.values.email } : {}),
+            ...(typeof parsed.values.roles === 'string' ? { roles: parsed.values.roles } : {}),
+            ...(parsed.values.admin === true ? { admin: true } : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+    }
+    if (command === 'import') {
+        return runImport({
+            subcommand: parsed.positionals[1],
+            file: parsed.positionals[2],
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+    }
+    if (command === 'generate') {
+        return runGenerate({
+            subcommand: parsed.positionals[1],
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(typeof parsed.values.out === 'string' ? { outFile: parsed.values.out } : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+    }
+    if (command === 'skin') {
+        return runSkin({
+            subcommand: parsed.positionals[1],
+            file: parsed.positionals[2],
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(typeof parsed.values.description === 'string'
+                ? { description: parsed.values.description }
+                : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+    }
+    if (command === 'serve' || command === 'dev') {
+        let port;
+        if (typeof parsed.values.port === 'string') {
+            port = Number(parsed.values.port);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                stderr(`--port must be a whole number between 0 and 65535, not "${parsed.values.port}".\n`);
+                return 2;
+            }
+        }
+        return runServe({
+            out,
+            stderr,
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            ...(port === undefined ? {} : { port }),
+            ...(typeof parsed.values.host === 'string' ? { host: parsed.values.host } : {}),
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.onListening === undefined ? {} : { onListening: options.onListening }),
+        });
+    }
+    if (command !== 'doctor') {
+        stderr(`Unknown command "${command}".\n\n${USAGE}`);
+        return 2;
+    }
+    try {
+        const report = await runDoctor({
+            env,
+            ...(typeof parsed.values.cwd === 'string' ? { cwd: parsed.values.cwd } : {}),
+            // Structured logs go to stderr so the report on stdout stays readable
+            // when it is piped.
+            ...(verboseLogger === undefined ? {} : { logger: verboseLogger }),
+        });
+        formatDoctorReport(report, out);
+        return report.problems.length === 0 ? 0 : 1;
+    }
+    catch (error) {
+        // Anything that reaches here is a bug in doctor itself, not a diagnosis.
+        if (isCogentaError(error)) {
+            stderr(`${error.code}: ${error.message}\n`);
+            if (error.hint !== undefined)
+                stderr(`${error.hint}\n`);
+        }
+        else {
+            stderr(`${error instanceof Error ? error.stack : String(error)}\n`);
+        }
+        return 1;
+    }
+}
+//# sourceMappingURL=index.js.map