@cogenta/cli 0.1.0

package/dist/commands/migrate.js

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { CogentaError, createDatabaseRegistry, createLogger, createMigrator, isCogentaError, loadConfig, } from '@cogenta/core';
+/** The directory a project keeps its migrations in, relative to the config file. */
+export const MIGRATIONS_DIRECTORY = 'migrations';
+/**
+ * Only ESM sources. `.cjs` is deliberately absent: Cogenta is ESM-only, and a
+ * migration that needs a CommonJS loader would be the one place it leaked back
+ * in. `.ts` works from Node 22.18, which strips types on import.
+ */
+const MIGRATION_EXTENSIONS = ['.js', '.mjs', '.ts', '.mts'];
+const USAGE = `Usage
+  cogenta migrate status                    List every migration and its state
+  cogenta migrate up [--to <id>]            Apply the pending migrations
+  cogenta migrate down [--steps <n>|--to <id>]  Revert applied migrations
+
+Options
+  --confirm-destructive   The impact of every destructive migration has been read
+  --backup-verified       A backup was taken and verified to restore
+`;
+function isBody(value) {
+    return typeof value === 'function';
+}
+function invalidMigration(file, reason) {
+    return new CogentaError({
+        code: 'MIGRATION_FAILED',
+        message: `${file} is not a migration: ${reason}.`,
+        hint: 'A migration file default-exports an object with an `up(tx)` and a `down(tx)`, both returning a promise. `down` is required — every migration is reversible.',
+        details: { file },
+    });
+}
+/**
+ * Turns one loaded module into a `Migration`, refusing anything that only looks
+ * like one.
+ *
+ * The id defaults to the file name without its extension, which is why files are
+ * sorted by name: the on-disk order and the applied order are then the same
+ * thing, and there is no second ordering to keep in sync.
+ */
+function toMigration(exported, file, checksum) {
+    if (typeof exported !== 'object' || exported === null) {
+        throw invalidMigration(file, 'its default export is not an object');
+    }
+    const record = exported;
+    const { up, down } = record;
+    if (!isBody(up))
+        throw invalidMigration(file, 'it has no `up` function');
+    if (!isBody(down))
+        throw invalidMigration(file, 'it has no `down` function');
+    const id = typeof record.id === 'string' ? record.id : file.replace(/\.[^.]+$/, '');
+    const name = record.name;
+    const impact = record.impact;
+    const duration = record.estimatedDurationMs;
+    return {
+        id,
+        ...(typeof name === 'string' ? { name } : {}),
+        // The file's own checksum wins over a declared one: the point is to detect a
+        // file that changed after it was applied, and a hand-written checksum would
+        // be edited along with the file it is supposed to guard.
+        checksum,
+        ...(record.destructive === true ? { destructive: true } : {}),
+        ...(typeof impact === 'string' ? { impact } : {}),
+        ...(typeof duration === 'number' ? { estimatedDurationMs: duration } : {}),
+        up,
+        down,
+    };
+}
+/**
+ * Loads every migration from a directory, in file-name order.
+ *
+ * A missing directory is not an error. L0 ships no business schema at all, so a
+ * fresh project legitimately has nothing to migrate, and failing there would
+ * make `migrate status` unusable exactly when an operator wants to check.
+ */
+export async function loadMigrations(directory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return [];
+    }
+    const files = names
+        .filter((name) => !name.endsWith('.d.ts') && MIGRATION_EXTENSIONS.some((suffix) => name.endsWith(suffix)))
+        .sort((a, b) => a.localeCompare(b));
+    const migrations = [];
+    for (const file of files) {
+        const path = join(directory, file);
+        // Hashing the source, not the exported object: it is the source that an
+        // operator edits, and the engine refuses a migration whose hash moved after
+        // it was applied.
+        const checksum = createHash('sha256')
+            .update(await readFile(path))
+            .digest('hex');
+        let module;
+        try {
+            module = (await import(pathToFileURL(path).href));
+        }
+        catch (error) {
+            throw new CogentaError({
+                code: 'MIGRATION_FAILED',
+                message: `Could not load ${path}: ${error instanceof Error ? error.message : String(error)}`,
+                hint: path.endsWith('.ts')
+                    ? 'A TypeScript migration needs a Node runtime that strips types, which means Node 22.18 or later. Rename it to .mjs on an older one.'
+                    : 'Check the file for a syntax error, and that every import it uses is installed.',
+                cause: error,
+                details: { path },
+            });
+        }
+        migrations.push(toMigration(module.default, file, checksum));
+    }
+    return migrations;
+}
+/**
+ * Reads back the destructive migrations the engine named when it refused.
+ *
+ * The refusal is only useful if the operator can see *what* would be lost, so
+ * the details the engine attached are unpacked rather than summarised away.
+ */
+function destructiveDetails(error) {
+    const listed = error.details?.migrations;
+    if (!Array.isArray(listed))
+        return [];
+    const entries = listed;
+    return entries.flatMap((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return [];
+        const record = entry;
+        const id = record.id;
+        const impact = record.impact;
+        if (typeof id !== 'string')
+            return [];
+        return [{ id, impact: typeof impact === 'string' ? impact : 'not documented' }];
+    });
+}
+function formatStatus(rows, out) {
+    out.heading('Migrations');
+    if (rows.length === 0) {
+        out.warn('No migration found. Add files to the migrations/ directory of the project.');
+        return;
+    }
+    for (const row of rows) {
+        const label = row.name === row.id ? row.id : `${row.id} — ${row.name}`;
+        if (!row.applied) {
+            out.warn(`${label} — pending`);
+        }
+        else if (row.checksumMismatch) {
+            out.bad(`${label} — applied ${row.appliedAt ?? 'at an unknown time'}, but changed since`);
+        }
+        else {
+            out.ok(`${label} — applied ${row.appliedAt ?? 'at an unknown time'} (${row.durationMs ?? 0}ms)`);
+        }
+        if (row.destructive)
+            out.detail(`destructive: ${row.impact ?? 'impact not documented'}`);
+        if (row.checksumMismatch) {
+            out.detail('The file no longer matches what ran here. Write a new migration instead.');
+        }
+    }
+}
+function formatOutcomes(outcomes, out) {
+    for (const outcome of outcomes) {
+        const verb = outcome.direction === 'up' ? 'applied' : 'reverted';
+        out.ok(`${verb} ${outcome.id} (${outcome.durationMs}ms)`);
+    }
+}
+/** Opens the database named by the configuration, exactly the way doctor does. */
+async function withDatabase(options, logger, use) {
+    const env = options.env ?? process.env;
+    const loaded = await loadConfig({
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env,
+    });
+    // Migrations belong to the project, so they sit next to its configuration
+    // file — not next to whatever directory the command happened to be run from.
+    const projectRoot = loaded.path === null ? resolvePath(options.cwd ?? process.cwd()) : dirname(loaded.path);
+    const selection = await createDatabaseRegistry({ logger }).select(loaded.config.database);
+    try {
+        return await use(selection.instance, projectRoot);
+    }
+    finally {
+        await selection.dispose();
+    }
+}
+/**
+ * Runs one `migrate` subcommand and returns its exit code.
+ *
+ * 0 succeeded, 1 the database or a migration said no, 2 the command line was
+ * wrong. Nothing calls `process.exit` and nothing writes to a stream directly,
+ * so a test drives this exactly as a shell does.
+ */
+export async function runMigrate(options) {
+    const { out, stderr } = options;
+    if (options.subcommand === undefined) {
+        stderr(`cogenta migrate needs a subcommand.\n\n${USAGE}`);
+        return 2;
+    }
+    if (options.subcommand !== 'status' &&
+        options.subcommand !== 'up' &&
+        options.subcommand !== 'down') {
+        stderr(`Unknown subcommand "${options.subcommand}".\n\n${USAGE}`);
+        return 2;
+    }
+    const subcommand = options.subcommand;
+    // Silent unless asked: a human report on stdout must not be interleaved with
+    // NDJSON. `--verbose` sends the structured lines to stderr instead.
+    const logger = options.logger ?? createLogger({ level: 'silent' });
+    try {
+        return await withDatabase(options, logger, async (db, projectRoot) => {
+            const directory = options.directory ?? join(projectRoot, MIGRATIONS_DIRECTORY);
+            const migrations = await loadMigrations(directory);
+            const migrator = createMigrator({ db, migrations, logger });
+            const run = {
+                ...(options.to === undefined ? {} : { to: options.to }),
+                ...(options.confirmDestructive === true ? { confirmDestructive: true } : {}),
+                ...(options.backupVerified === true ? { backupVerified: true } : {}),
+            };
+            if (subcommand === 'status') {
+                const rows = await migrator.status();
+                formatStatus(rows, out);
+                const pending = rows.filter((row) => !row.applied).length;
+                const drifted = rows.filter((row) => row.checksumMismatch).length;
+                out.line();
+                out.line(`${rows.length - pending} applied, ${pending} pending.`);
+                // A drifted checksum is a real fault, not a note: two environments ran
+                // different SQL under the same id, and a deployment script must notice.
+                return drifted === 0 ? 0 : 1;
+            }
+            const outcomes = subcommand === 'up'
+                ? await migrator.up(run)
+                : await migrator.down({
+                    ...run,
+                    ...(options.steps === undefined ? {} : { steps: options.steps }),
+                });
+            out.heading(subcommand === 'up' ? 'Applied' : 'Reverted');
+            formatOutcomes(outcomes, out);
+            out.line();
+            out.line(outcomes.length === 0
+                ? subcommand === 'up'
+                    ? 'Nothing to apply.'
+                    : 'Nothing to revert.'
+                : `${outcomes.length} migration(s) ${subcommand === 'up' ? 'applied' : 'reverted'}.`);
+            return 0;
+        });
+    }
+    catch (error) {
+        if (isCogentaError(error) && error.code === 'MIGRATION_DESTRUCTIVE') {
+            // The engine already refused. The CLI's job is to make the refusal
+            // actionable: name what would be lost, then say the two flags out loud.
+            stderr(`${error.message}\n`);
+            for (const entry of destructiveDetails(error)) {
+                stderr(`  ${entry.id}: ${entry.impact}\n`);
+            }
+            if (error.hint !== undefined)
+                stderr(`\n${error.hint}\n`);
+            stderr('\nRe-run with --confirm-destructive --backup-verified once both are true.\n');
+            return 1;
+        }
+        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=migrate.js.map

package/dist/commands/migrate.js.map

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

package/dist/commands/serve.d.ts

@@ -0,0 +1,81 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type AgentsRouter, type AuditRouter, type AuthRouter, createContentGateway, type MediaRouter, type RestRouter } from '@cogenta/api';
+import { type AuthStore } from '@cogenta/auth';
+import { type DatabaseHandle, type HealthReport, type Logger, type MediaStore, type StorageDriver } from '@cogenta/core';
+import { type CollectionDefinition, type SchemaDocument } from '@cogenta/schema';
+import type { GraphQLSchema } from 'graphql';
+import type { Output, Writer } from '../output.js';
+/**
+ * Loads a project's content model.
+ *
+ * `cogenta.schema.ts` next to the config file, default-exporting the
+ * collections — the same "one file, dynamic-imported, next to the config"
+ * convention `migrate.ts` already established for migrations. A project with
+ * none is invalid here, unlike a project with no migrations: a site with zero
+ * collections has nothing to serve.
+ */
+export declare function loadCollections(projectRoot: string): Promise<readonly CollectionDefinition[]>;
+interface Site {
+    readonly db: DatabaseHandle;
+    readonly auth: AuthStore;
+    readonly restRouter: RestRouter;
+    readonly authRouter: AuthRouter;
+    readonly mediaRouter: MediaRouter;
+    readonly auditRouter: AuditRouter;
+    /** Only set when a caller passes `agents` into `assembleSite` — no site constructs one today (R2: agents are optional, not a hard dependency of the CMS). */
+    readonly agentsRouter?: AgentsRouter;
+    /** Not routed through `mediaRouter`: serving a binary body is outside the JSON-only `RestResponse` shape, so the file route is handled directly (same treatment `/api/schema` already gets). */
+    readonly mediaStore: MediaStore;
+    readonly storage: StorageDriver;
+    readonly graphqlSchema: GraphQLSchema;
+    readonly gateway: ReturnType<typeof createContentGateway>;
+    /** `.cogenta/schema.json`'s in-memory twin — the admin's only view of the collections (never the schema modules themselves, which are Node code). */
+    readonly schemaDocument: SchemaDocument;
+    /** Live, not cached: a driver that just went down must show as down the next time this is called, not until the process restarts. */
+    readonly health: () => Promise<{
+        readonly database: HealthReport;
+        readonly storage: HealthReport;
+    }>;
+    dispose(): Promise<void>;
+}
+/**
+ * Builds the Node request handler from an already-assembled site.
+ *
+ * All the actual logic — routing, permissions, actor resolution — was already
+ * tested as plain values in `@cogenta/api` and `@cogenta/auth`; this function
+ * is deliberately just the translation from `IncomingMessage`/`ServerResponse`
+ * to that shape and back, so a serverless adapter later is the same kind of
+ * thin layer rather than a second implementation of any of it.
+ */
+export declare function createRequestListener(site: Site, logger: Logger): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface ServeOptions {
+    readonly cwd?: string;
+    readonly env?: Record<string, string | undefined>;
+    readonly logger?: Logger;
+    readonly out: Output;
+    readonly stderr: Writer;
+    readonly port?: number;
+    readonly host?: string;
+    /** Resolves once the server is actually listening — tests need the OS-assigned port. */
+    onListening?: (address: {
+        port: number;
+        host: string;
+    }) => void;
+    /** Stops the server and disposes the database when aborted. */
+    readonly signal?: AbortSignal;
+    /**
+     * "Commencer par une démo en lecture seule" (L9 tâche 12, playground). Every
+     * write attempt refuses with `CONTENT_READ_ONLY`; reads are unaffected.
+     * Scheduling a periodic reset back to demo content is an operational
+     * decision for whoever deploys a read-only instance, not made here.
+     */
+    readonly readOnly?: boolean;
+}
+/**
+ * Runs until `options.signal` aborts. Returns 0 on a clean shutdown, 1 if
+ * startup failed — nothing here calls `process.exit` (same convention as
+ * every other command), so an embedder controls the process lifecycle.
+ */
+export declare function runServe(options: ServeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=serve.d.ts.map

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

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