@nage-api/cli 1.0.0-beta.2

package/dist/cli.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * The `nage` command layer (PLAN.md §10).
+ *
+ * Argument parsing uses Node's own `util.parseArgs` rather than a framework:
+ * the command surface is small and regular, and a CLI that scaffolds
+ * dependency-light projects should be dependency-light itself.
+ *
+ * `run()` returns an exit code and writes through an injected output object, so
+ * every command is testable without spawning a process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_VERSION = void 0;
+exports.run = run;
+exports.usage = usage;
+const node_util_1 = require("node:util");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const core_1 = require("@nage-api/core");
+const file_tree_js_1 = require("./fs/file-tree.js");
+const manifest_js_1 = require("./workspace/manifest.js");
+const create_js_1 = require("./commands/create.js");
+const generate_js_1 = require("./commands/generate.js");
+const doctor_js_1 = require("./commands/doctor.js");
+const features_js_1 = require("./commands/features.js");
+exports.CLI_VERSION = '0.0.0';
+const GLOBAL_FLAGS = {
+    app: { type: 'string' },
+    all: { type: 'boolean' },
+    force: { type: 'boolean' },
+    'dry-run': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    // create / new app
+    db: { type: 'string' },
+    'first-app': { type: 'string' },
+    preset: { type: 'string' },
+    port: { type: 'string' },
+    standalone: { type: 'boolean' },
+    // generate
+    fields: { type: 'string' },
+    route: { type: 'string' },
+    package: { type: 'string' },
+    'no-migration': { type: 'boolean' },
+    'no-spec': { type: 'boolean' },
+    // doctor
+    legacy: { type: 'boolean' },
+};
+/** Run one command. Returns the process exit code. */
+async function run(options) {
+    const { io } = options;
+    let parsed;
+    try {
+        parsed = (0, node_util_1.parseArgs)({
+            args: [...options.argv],
+            options: GLOBAL_FLAGS,
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (error) {
+        io.err(`✖ ${error instanceof Error ? error.message : String(error)}\n`);
+        io.err('  Run `nage --help` to see the available commands.\n');
+        return 1;
+    }
+    const flags = parsed.values;
+    const [command, ...rest] = parsed.positionals;
+    if (flags.version === true) {
+        io.out(`${options.version ?? exports.CLI_VERSION}\n`);
+        return 0;
+    }
+    if (command === undefined || flags.help === true) {
+        io.out(usage());
+        return command === undefined && flags.help !== true ? 1 : 0;
+    }
+    try {
+        return await dispatch(command, rest, flags, options);
+    }
+    catch (error) {
+        // Framework errors carry an operator-facing message; anything else is a bug
+        // and its stack belongs on stderr.
+        if ((0, core_1.isNageError)(error)) {
+            io.err(`✖ ${error.message}\n`);
+            const hint = error.meta?.['hint'];
+            if (typeof hint === 'string')
+                io.err(`  ${hint}\n`);
+            return 1;
+        }
+        io.err(`✖ ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+        return 1;
+    }
+}
+async function dispatch(command, positionals, flags, options) {
+    const { io, cwd } = options;
+    const dryRun = flags['dry-run'] === true;
+    switch (command) {
+        case 'create': {
+            const name = requirePositional(positionals, 0, 'nage create <name>');
+            const plan = (0, create_js_1.planCreate)({
+                name,
+                ...(typeof flags['db'] === 'string' ? { engine: flags['db'] } : {}),
+                ...(typeof flags['first-app'] === 'string' ? { firstApp: flags['first-app'] } : {}),
+                ...(typeof flags['preset'] === 'string' ? { preset: flags['preset'] } : {}),
+                ...(flags['standalone'] === true ? { standalone: true } : {}),
+            });
+            const root = (0, node_path_1.join)((0, node_path_1.resolve)(cwd), plan.manifest.name);
+            if (!dryRun)
+                await (0, promises_1.mkdir)(root, { recursive: true });
+            const result = await (0, file_tree_js_1.commitFileTree)(plan.tree, { root, dryRun });
+            report(io, result, dryRun);
+            io.out(`\n${plan.notes.join('\n')}\n`);
+            return 0;
+        }
+        case 'new': {
+            const kind = requirePositional(positionals, 0, 'nage new app|package <name>');
+            const name = requirePositional(positionals, 1, `nage new ${kind} <name>`);
+            const { root, manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            const plan = kind === 'app'
+                ? await (0, create_js_1.planNewApp)({
+                    root,
+                    manifest,
+                    name,
+                    ...(typeof flags['preset'] === 'string' ? { preset: flags['preset'] } : {}),
+                    ...(typeof flags['port'] === 'string' ? { port: Number(flags['port']) } : {}),
+                })
+                : kind === 'package'
+                    ? await (0, create_js_1.planNewPackage)({ root, manifest, name })
+                    : fail(`"${kind}" is not something \`nage new\` can create (app, package)`);
+            const result = await (0, file_tree_js_1.commitFileTree)(plan.tree, { root, dryRun });
+            report(io, result, dryRun);
+            io.out(`\n${plan.notes.join('\n')}\n`);
+            return 0;
+        }
+        case 'generate':
+        case 'g': {
+            const schematic = requirePositional(positionals, 0, 'nage g <schematic> <name>');
+            if (!generate_js_1.SCHEMATICS.includes(schematic)) {
+                return fail(`"${schematic}" is not a schematic (${generate_js_1.SCHEMATICS.join(', ')})`);
+            }
+            const name = requirePositional(positionals, 1, `nage g ${schematic} <name>`);
+            const { root, manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            const app = (0, manifest_js_1.resolveTargetApp)(manifest, {
+                root,
+                cwd,
+                ...(typeof flags['app'] === 'string' ? { app: flags['app'] } : {}),
+            });
+            const plan = await (0, generate_js_1.planGenerate)({
+                root,
+                manifest,
+                schematic: schematic,
+                name,
+                appName: app.name,
+                ...(typeof flags['fields'] === 'string' ? { fields: flags['fields'] } : {}),
+                ...(typeof flags['route'] === 'string' ? { route: flags['route'] } : {}),
+                ...(typeof flags['package'] === 'string' ? { entityPackage: flags['package'] } : {}),
+                ...(flags['no-migration'] === true ? { withMigration: false } : {}),
+                ...(flags['no-spec'] === true ? { withSpec: false } : {}),
+            });
+            const result = await (0, file_tree_js_1.commitFileTree)(plan.tree, { root, dryRun });
+            report(io, result, dryRun);
+            if (plan.notes.length > 0)
+                io.out(`\n${plan.notes.join('\n')}\n`);
+            return 0;
+        }
+        case 'add':
+        case 'remove': {
+            const target = requirePositional(positionals, 0, `nage ${command} <feature|app|package>`);
+            const { root, manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            if (command === 'remove' && (target === 'app' || target === 'package')) {
+                const name = requirePositional(positionals, 1, `nage remove ${target} <name>`);
+                const plan = target === 'app'
+                    ? await (0, features_js_1.planRemoveApp)({ root, manifest, name })
+                    : await (0, features_js_1.planRemovePackage)({ root, manifest, name });
+                const result = await (0, file_tree_js_1.commitFileTree)(plan.tree, { root, dryRun });
+                if (!dryRun && target === 'app')
+                    await (0, file_tree_js_1.archiveDirectory)(root, `apps/${name}`);
+                report(io, result, dryRun);
+                io.out(`\n${plan.notes.join('\n')}\n`);
+                return 0;
+            }
+            const apps = (0, features_js_1.selectApps)(manifest, {
+                ...(typeof flags['app'] === 'string' ? { app: flags['app'] } : {}),
+                ...(flags['all'] === true ? { all: true } : {}),
+            }).map((app) => app.name);
+            const plan = command === 'add'
+                ? await (0, features_js_1.planAddFeature)({ root, manifest, feature: target, apps })
+                : await (0, features_js_1.planRemoveFeature)({ root, manifest, feature: target, apps });
+            const result = await (0, file_tree_js_1.commitFileTree)(plan.tree, { root, dryRun });
+            report(io, result, dryRun);
+            io.out(`\n${plan.notes.join('\n')}\n`);
+            return 0;
+        }
+        case 'list': {
+            const { manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            io.out((0, features_js_1.formatList)(manifest));
+            return 0;
+        }
+        case 'info': {
+            const { manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            io.out((0, features_js_1.formatInfo)(manifest, options.version ?? exports.CLI_VERSION));
+            return 0;
+        }
+        case 'doctor': {
+            const { root, manifest } = await (0, manifest_js_1.loadWorkspace)(cwd);
+            // No `env` is passed: `doctor` weighs the workspace's own `.env`, not the
+            // shell's, so the report is about the project rather than the machine.
+            const report_ = await (0, doctor_js_1.runDoctor)({
+                root,
+                manifest,
+                ...(flags['legacy'] === true ? { legacy: true } : {}),
+                ...(typeof flags['app'] === 'string' ? { app: flags['app'] } : {}),
+            });
+            io.out(`${(0, core_1.formatFindings)(report_.findings)}\n`);
+            // A non-zero exit is what makes `doctor` usable as a CI gate.
+            return report_.healthy ? 0 : 1;
+        }
+        default:
+            return fail(`"${command}" is not a nage command. Run \`nage --help\`.`);
+    }
+}
+function report(io, result, dryRun) {
+    const verb = dryRun ? 'Would write' : 'Wrote';
+    io.out(`${verb} ${String(result.written.length)} file(s):\n`);
+    for (const path of result.written)
+        io.out(`  + ${path}\n`);
+    for (const path of result.skipped)
+        io.out(`  · ${path} (exists, left alone)\n`);
+}
+function requirePositional(positionals, index, usageLine) {
+    const value = positionals[index];
+    if (value === undefined || value === '')
+        fail(`Missing argument. Usage: ${usageLine}`);
+    return value;
+}
+function fail(message) {
+    const error = new Error(message);
+    error.name = 'UsageError';
+    throw error;
+}
+function usage() {
+    return [
+        'nage — scaffold and manage a @nage-api workspace',
+        '',
+        'Usage: nage <command> [options]',
+        '',
+        'Commands:',
+        '  create <name>              Scaffold a workspace seeded with one app',
+        '  new app <name>             Add an app to the current workspace',
+        '  new package <name>         Add a shared local package',
+        '  g|generate <what> <name>   resource, module, service, controller, entity, dto, migration, seed',
+        '  add <feature>              Enable auth|cache|queue|storage|realtime|notify|observability',
+        '  remove <feature>           Disable a feature',
+        '  remove app|package <name>  Unregister an app or package',
+        '  list                       Show apps and packages',
+        '  info                       Show versions and workspace summary',
+        '  doctor                     Check workspace integrity and configuration',
+        '',
+        'Options:',
+        '  --app <name>     Target one app (defaults to the app the cwd is in)',
+        '  --all            Target every app',
+        '  --db <engine>    postgres|mysql|mariadb|sqlite|mongodb (create)',
+        '  --preset <p>     minimal|api|api-realtime|worker',
+        '  --port <n>       Port for a new app',
+        '  --fields <spec>  "name:string,slug:string:unique" (generate)',
+        '  --route <path>   Base route for a resource',
+        '  --package <name> Put a generated entity in a shared package',
+        '  --no-migration   Skip the migration (generate resource)',
+        '  --no-spec        Skip the tests (not recommended)',
+        '  --legacy         Also scan for legacy insecure patterns (doctor)',
+        '  --dry-run        Show what would change without writing',
+        '  -h, --help       Show this help',
+        '  -v, --version    Show the CLI version',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=cli.js.map

package/dist/commands/create.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `nage create <name>` and `nage new app|package` (PLAN.md §10.1).
+ *
+ * Every command here returns the files it would write plus the manifest it
+ * would leave behind, so the caller can commit them in one transaction, print
+ * them for `--dry-run`, or assert on them in a test. Nothing writes directly.
+ */
+import type { DatabaseDriver } from '@nage-api/contracts';
+import { FileTree } from '../fs/file-tree.js';
+import { type FeatureName, type Preset, type WorkspaceManifest } from '../workspace/manifest.js';
+/** What a command intends to do, before anything touches the disk. */
+export interface CommandPlan {
+    readonly tree: FileTree;
+    readonly manifest: WorkspaceManifest;
+    /** Lines printed after a successful run. */
+    readonly notes: readonly string[];
+}
+export interface CreateOptions {
+    readonly name: string;
+    readonly engine?: DatabaseDriver;
+    readonly firstApp?: string;
+    readonly preset?: Preset;
+    readonly features?: readonly FeatureName[];
+    readonly frameworkVersion?: string;
+    readonly packageManager?: 'pnpm' | 'npm' | 'yarn';
+    /** Emit a single app at the root instead of a workspace (§10.2). */
+    readonly standalone?: boolean;
+}
+export declare const DEFAULT_FRAMEWORK_VERSION = "^0.1.0";
+/**
+ * Plan a new workspace.
+ *
+ * Workspace-first by §27.10: a lone app inside a workspace costs almost
+ * nothing, and growing to several apps later is then friction-free.
+ */
+export declare function planCreate(options: CreateOptions): CommandPlan;
+export interface NewAppOptions {
+    readonly root: string;
+    readonly manifest: WorkspaceManifest;
+    readonly name: string;
+    readonly preset?: Preset;
+    readonly port?: number;
+    readonly features?: readonly FeatureName[];
+}
+/** Plan an additional app inside an existing workspace. */
+export declare function planNewApp(options: NewAppOptions): Promise<CommandPlan>;
+export interface NewPackageOptions {
+    readonly root: string;
+    readonly manifest: WorkspaceManifest;
+    readonly name: string;
+    /** Import alias; defaults to `@app/<name>`. */
+    readonly alias?: string;
+}
+/** Plan a shared local package (§9.1: the team's own code, not the framework's). */
+export declare function planNewPackage(options: NewPackageOptions): Promise<CommandPlan>;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/create.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * `nage create <name>` and `nage new app|package` (PLAN.md §10.1).
+ *
+ * Every command here returns the files it would write plus the manifest it
+ * would leave behind, so the caller can commit them in one transaction, print
+ * them for `--dry-run`, or assert on them in a test. Nothing writes directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FRAMEWORK_VERSION = void 0;
+exports.planCreate = planCreate;
+exports.planNewApp = planNewApp;
+exports.planNewPackage = planNewPackage;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const core_1 = require("@nage-api/core");
+const file_tree_js_1 = require("../fs/file-tree.js");
+const naming_js_1 = require("../naming.js");
+const manifest_js_1 = require("../workspace/manifest.js");
+const wiring_js_1 = require("../workspace/wiring.js");
+const app_template_js_1 = require("../templates/app.template.js");
+const workspace_template_js_1 = require("../templates/workspace.template.js");
+exports.DEFAULT_FRAMEWORK_VERSION = '^0.1.0';
+/**
+ * Plan a new workspace.
+ *
+ * Workspace-first by §27.10: a lone app inside a workspace costs almost
+ * nothing, and growing to several apps later is then friction-free.
+ */
+function planCreate(options) {
+    const workspaceName = (0, naming_js_1.deriveNames)(options.name).kebab;
+    const appName = (0, naming_js_1.deriveNames)(options.firstApp ?? 'api').kebab;
+    const app = {
+        name: appName,
+        preset: options.preset ?? 'api',
+        port: manifest_js_1.DEFAULT_PORT,
+        features: [...(options.features ?? [])],
+    };
+    const manifest = {
+        ...(0, manifest_js_1.createManifest)({
+            name: workspaceName,
+            engine: options.engine ?? 'postgres',
+            frameworkVersion: options.frameworkVersion ?? exports.DEFAULT_FRAMEWORK_VERSION,
+        }),
+        apps: [app],
+    };
+    // The app's build project joins the root solution config, so `tsc -b` at the
+    // root covers everything. The reference is added to the template's own
+    // tsconfig rather than to a second copy of it, so there is exactly one
+    // planned version of the file.
+    const workspace = (0, workspace_template_js_1.workspaceFiles)({
+        manifest,
+        packageManager: options.packageManager ?? 'pnpm',
+    }).map((file) => file.path === 'tsconfig.json'
+        ? { ...file, contents: (0, wiring_js_1.addProjectReference)(file.contents, `apps/${appName}`) }
+        : file);
+    const tree = new file_tree_js_1.FileTree().addAll(workspace).addAll((0, app_template_js_1.appFiles)({ app, manifest }));
+    return {
+        tree,
+        manifest,
+        notes: [
+            `Created workspace "${workspaceName}" with app "${appName}".`,
+            '',
+            'Next:',
+            `  cd ${workspaceName}`,
+            '  pnpm install',
+            '  cp .env.example .env',
+            '  pnpm dev',
+        ],
+    };
+}
+/** Plan an additional app inside an existing workspace. */
+async function planNewApp(options) {
+    const name = (0, naming_js_1.deriveNames)(options.name).kebab;
+    if (options.manifest.apps.some((app) => app.name === name)) {
+        throw new core_1.ConfigurationError({
+            detail: `This workspace already has an app named "${name}"`,
+            meta: { app: name },
+        });
+    }
+    const port = options.port ?? (0, manifest_js_1.nextAvailablePort)(options.manifest);
+    const clash = options.manifest.apps.find((app) => app.port === port);
+    if (clash !== undefined) {
+        // Two apps on one port is a failure that only shows up when both are
+        // started, which is the worst time to find it.
+        throw new core_1.ConfigurationError({
+            detail: `Port ${String(port)} is already used by "${clash.name}"`,
+            meta: { port, app: clash.name },
+        });
+    }
+    const app = {
+        name,
+        preset: options.preset ?? 'api',
+        port,
+        features: [...(options.features ?? [])],
+    };
+    const manifest = {
+        ...options.manifest,
+        apps: [...options.manifest.apps, app],
+    };
+    const tree = new file_tree_js_1.FileTree().addAll((0, app_template_js_1.appFiles)({ app, manifest }));
+    tree.add({
+        path: 'nage.workspace.json',
+        contents: (0, manifest_js_1.serialiseManifest)(manifest),
+        onConflict: 'overwrite',
+    });
+    const rootTsconfig = await (0, promises_1.readFile)((0, node_path_1.join)(options.root, 'tsconfig.json'), 'utf8');
+    tree.add({
+        path: 'tsconfig.json',
+        contents: (0, wiring_js_1.addProjectReference)(rootTsconfig, `apps/${name}`),
+        onConflict: 'overwrite',
+    });
+    return {
+        tree,
+        manifest,
+        notes: [
+            `Added app "${name}" (${app.preset}) on port ${String(port)}.`,
+            '',
+            'Next:',
+            '  pnpm install',
+            `  pnpm --filter ./apps/${name} dev`,
+        ],
+    };
+}
+/** Plan a shared local package (§9.1: the team's own code, not the framework's). */
+async function planNewPackage(options) {
+    const name = (0, naming_js_1.deriveNames)(options.name).kebab;
+    const alias = options.alias ?? `@app/${name}`;
+    if (options.manifest.packages.some((entry) => entry.name === name)) {
+        throw new core_1.ConfigurationError({
+            detail: `This workspace already has a package named "${name}"`,
+            meta: { package: name },
+        });
+    }
+    const manifest = {
+        ...options.manifest,
+        packages: [...options.manifest.packages, { name, alias }],
+    };
+    const files = [
+        {
+            path: `packages/${name}/package.json`,
+            contents: (0, workspace_template_js_1.json)({
+                name: alias,
+                version: '0.0.0',
+                private: true,
+                type: 'commonjs',
+                main: 'dist/index.js',
+                types: 'dist/index.d.ts',
+                scripts: {
+                    build: 'tsc -b tsconfig.build.json',
+                    typecheck: 'tsc -p tsconfig.json --noEmit',
+                    test: 'vitest run',
+                },
+            }),
+        },
+        {
+            path: `packages/${name}/tsconfig.json`,
+            contents: (0, workspace_template_js_1.json)({
+                extends: '../../tsconfig.base.json',
+                compilerOptions: { noEmit: true, types: ['node'] },
+                include: ['src/**/*.ts', 'test/**/*.ts'],
+            }),
+        },
+        {
+            path: `packages/${name}/tsconfig.build.json`,
+            contents: (0, workspace_template_js_1.json)({
+                extends: '../../tsconfig.base.json',
+                compilerOptions: { composite: true, rootDir: 'src', outDir: 'dist', types: ['node'] },
+                include: ['src/**/*.ts'],
+            }),
+        },
+        {
+            path: `packages/${name}/src/index.ts`,
+            contents: [
+                `/** Shared code for this workspace, imported as \`${alias}\`. */`,
+                '',
+                'export {};',
+                '',
+            ].join('\n'),
+        },
+    ];
+    const tree = new file_tree_js_1.FileTree().addAll(files);
+    tree.add({
+        path: 'nage.workspace.json',
+        contents: (0, manifest_js_1.serialiseManifest)(manifest),
+        onConflict: 'overwrite',
+    });
+    // A shared package is only usable once the alias resolves and pnpm knows
+    // about the directory, so both are updated in the same transaction.
+    const tsconfigBase = await (0, promises_1.readFile)((0, node_path_1.join)(options.root, 'tsconfig.base.json'), 'utf8');
+    tree.add({
+        path: 'tsconfig.base.json',
+        contents: (0, wiring_js_1.addPathAlias)(tsconfigBase, alias, `./packages/${name}/src/index.ts`),
+        onConflict: 'overwrite',
+    });
+    const pnpmWorkspace = await (0, promises_1.readFile)((0, node_path_1.join)(options.root, 'pnpm-workspace.yaml'), 'utf8');
+    tree.add({
+        path: 'pnpm-workspace.yaml',
+        contents: (0, wiring_js_1.addWorkspaceGlob)(pnpmWorkspace, 'packages/*'),
+        onConflict: 'overwrite',
+    });
+    const rootTsconfig = await (0, promises_1.readFile)((0, node_path_1.join)(options.root, 'tsconfig.json'), 'utf8');
+    tree.add({
+        path: 'tsconfig.json',
+        contents: (0, wiring_js_1.addProjectReference)(rootTsconfig, `packages/${name}`),
+        onConflict: 'overwrite',
+    });
+    return {
+        tree,
+        manifest,
+        notes: [
+            `Added package "${name}" (${alias}).`,
+            '',
+            'Import it as:',
+            `  import { … } from '${alias}';`,
+        ],
+    };
+}
+//# sourceMappingURL=create.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `nage doctor` (PLAN.md §10.1, §12).
+ *
+ * Two kinds of check, one report:
+ *   - **workspace integrity** — duplicate app names or ports, orphan packages,
+ *     apps missing from disk, version skew across apps;
+ *   - **security** — delegated to `auditSecurity` in `@nage-api/core`, so the
+ *     checks `doctor` reports and the ones that block a production boot are the
+ *     same code rather than two lists that drift.
+ */
+import type { SecurityFinding } from '@nage-api/contracts';
+import type { WorkspaceManifest } from '../workspace/manifest.js';
+export interface DoctorOptions {
+    readonly root: string;
+    readonly manifest: WorkspaceManifest;
+    /** Limit to one app. */
+    readonly app?: string;
+    /**
+     * Values used only to judge secret strength; never echoed.
+     *
+     * Defaults to the workspace's own `.env` — deliberately **not**
+     * `process.env`. The shell a developer runs `doctor` in carries CI tokens and
+     * unrelated variables whose names match any secret heuristic, and a report
+     * full of findings about the machine rather than the project is a report
+     * nobody reads.
+     */
+    readonly env?: Record<string, string | undefined>;
+    /** Also scan for the legacy insecure patterns (§23.3). */
+    readonly legacy?: boolean;
+}
+export interface DoctorReport {
+    readonly findings: readonly SecurityFinding[];
+    /** True when nothing critical or high was found. */
+    readonly healthy: boolean;
+}
+export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+/**
+ * Read the workspace's `.env`, if it has one.
+ *
+ * Just enough of the format to judge secret strength: `KEY=value`, `export`
+ * prefixes, `#` comments and one level of quoting. Nothing is interpolated and
+ * nothing is exported — the values are read, weighed and dropped.
+ */
+export declare function readDotEnv(root: string): Promise<Record<string, string>>;
+/** Duplicate names and ports — the two failures that only appear at run time. */
+export declare function checkWorkspaceIntegrity(manifest: WorkspaceManifest): SecurityFinding[];
+//# sourceMappingURL=doctor.d.ts.map