@apso/cli 0.13.0 → 0.14.0

package/dist/commands/doctor.d.ts

@@ -0,0 +1,10 @@
+import BaseCommand from "../lib/base-command";
+export default class Doctor extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        report: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/doctor.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const core_1 = require("@oclif/core");
+const inquirer = tslib_1.__importStar(require("inquirer"));
+const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
+const apsorc_parser_1 = require("../lib/apsorc-parser");
+const runner_1 = require("../lib/doctor/runner");
+class Doctor extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(Doctor);
+        // Find and parse .apsorc
+        const configPath = (0, apsorc_parser_1.findConfigPath)();
+        if (!configPath) {
+            this.error("No .apsorc file found in the current directory or parent directories.");
+        }
+        let parsed;
+        try {
+            parsed = (0, apsorc_parser_1.parseApsorc)();
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.error(`Failed to parse .apsorc: ${msg}`);
+        }
+        const projectRoot = path.dirname(configPath);
+        const language = parsed.language || "typescript";
+        const ctx = {
+            entities: parsed.entities,
+            relationshipMap: parsed.relationshipMap,
+            rootFolder: parsed.rootFolder || "src",
+            language,
+            projectRoot,
+        };
+        if (!flags.json) {
+            this.log("Running diagnostics...");
+        }
+        const findings = await (0, runner_1.runDiagnostics)(ctx);
+        // Output
+        if (flags.json) {
+            this.log(JSON.stringify(findings, null, 2));
+        }
+        else {
+            this.log("");
+            this.log((0, runner_1.formatFindings)(findings));
+            const errors = findings.filter((f) => f.severity === "error").length;
+            const warnings = findings.filter((f) => f.severity === "warning").length;
+            this.log(`${findings.length} finding(s): ${errors} error(s), ${warnings} warning(s)`);
+        }
+        // Report flow
+        if (flags.report) {
+            const actionable = findings.filter((f) => f.severity === "error" || f.severity === "warning");
+            if (actionable.length === 0) {
+                this.log("No errors or warnings to report.");
+                return;
+            }
+            if (!(0, runner_1.isGhAvailable)()) {
+                this.error("GitHub CLI (gh) is not installed or not authenticated.\n" +
+                    "Install: https://cli.github.com\n" +
+                    "Authenticate: gh auth login");
+            }
+            // Dedupe check
+            const firstError = actionable.find((f) => f.severity === "error") || actionable[0];
+            const searchTitle = firstError.message.slice(0, 100);
+            const existing = (0, runner_1.searchExistingIssues)(searchTitle);
+            if (existing.length > 0) {
+                this.log("");
+                this.log("Potentially related open issues:");
+                for (const issue of existing) {
+                    this.log(`  #${issue.number}: ${issue.title}`);
+                    this.log(`    ${issue.url}`);
+                }
+                this.log("");
+                const { proceed } = await inquirer.prompt([
+                    {
+                        type: "confirm",
+                        name: "proceed",
+                        message: "File a new issue anyway?",
+                        default: false,
+                    },
+                ]);
+                if (!proceed) {
+                    this.log("Aborted.");
+                    return;
+                }
+            }
+            // Confirm before filing
+            const { confirm } = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "confirm",
+                    message: `File a GitHub issue with ${actionable.length} finding(s) against apsoai/cli?`,
+                    default: true,
+                },
+            ]);
+            if (!confirm) {
+                this.log("Aborted.");
+                return;
+            }
+            try {
+                const url = (0, runner_1.fileGitHubIssue)(findings, ctx);
+                this.log(`Issue filed: ${url}`);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                this.error(`Failed to file issue: ${msg}`);
+            }
+        }
+    }
+}
+Doctor.description = "Run diagnostic checks on generated code and optionally file a GitHub issue with findings";
+Doctor.examples = [
+    `$ apso doctor`,
+    `$ apso doctor --json`,
+    `$ apso doctor --report`,
+];
+Doctor.flags = {
+    report: core_1.Flags.boolean({
+        description: "File a GitHub issue with diagnostic findings (requires gh CLI)",
+        default: false,
+    }),
+    json: core_1.Flags.boolean({
+        description: "Output findings as JSON instead of human-readable text",
+        default: false,
+    }),
+};
+exports.default = Doctor;

package/dist/commands/mcp/serve.js

@@ -10,6 +10,7 @@ const zod_1 = require("zod");
 const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
 const apsorc_parser_1 = require("../../lib/apsorc-parser");
 const lib_1 = require("../../lib");
+const runner_1 = require("../../lib/doctor/runner");
 const file_system_1 = require("../../lib/utils/file-system");
 const schema_convert_1 = require("../../lib/utils/schema-convert");
 const perf_hooks_1 = require("perf_hooks");
@@ -626,6 +627,133 @@ class McpServe extends base_command_1.default {
                 ],
             };
         });
+        // ── diagnose ──────────────────────────────────────────────────
+        server.tool("diagnose", "Run diagnostic checks on the current project's generated code. Detects issues like missing PK generation strategies, unused imports, unrecognized field types, broken relationships, and migration failures.", {}, async () => {
+            try {
+                const configPath = (0, apsorc_parser_1.findConfigPath)();
+                if (!configPath) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No .apsorc file found in the current directory or parent directories.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const parsed = (0, apsorc_parser_1.parseApsorc)();
+                const projectRoot = path.dirname(configPath);
+                const language = parsed.language || "typescript";
+                const ctx = {
+                    entities: parsed.entities,
+                    relationshipMap: parsed.relationshipMap,
+                    rootFolder: parsed.rootFolder || "src",
+                    language,
+                    projectRoot,
+                };
+                const findings = await (0, runner_1.runDiagnostics)(ctx);
+                if (findings.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "All diagnostic checks passed. No issues found.",
+                            },
+                        ],
+                    };
+                }
+                const text = (0, runner_1.formatFindings)(findings);
+                const errors = findings.filter((f) => f.severity === "error").length;
+                const warnings = findings.filter((f) => f.severity === "warning").length;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${text}\n${findings.length} finding(s): ${errors} error(s), ${warnings} warning(s)\n\nUse the report_issue tool to file a GitHub issue with these findings.`,
+                        },
+                    ],
+                    isError: errors > 0,
+                };
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Diagnostic error: ${msg}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        // ── report_issue ──────────────────────────────────────────────
+        server.tool("report_issue", "File a GitHub issue against apsoai/cli with diagnostic findings or a custom description. Deduplicates against open issues. Requires the gh CLI to be installed and authenticated.", {
+            title: zod_1.z.string().describe("Issue title"),
+            body: zod_1.z.string().describe("Issue body (markdown)"),
+            confirm: zod_1.z
+                .boolean()
+                .default(false)
+                .describe("Set to true to actually create the issue. When false, returns a preview and any duplicate issues found."),
+        }, async ({ title, body, confirm }) => {
+            try {
+                if (!(0, runner_1.isGhAvailable)()) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "GitHub CLI (gh) is not installed or not authenticated.\nInstall: https://cli.github.com\nAuthenticate: gh auth login",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Check for duplicates
+                const existing = (0, runner_1.searchExistingIssues)(title);
+                const dupeInfo = existing.length > 0
+                    ? `\n\nPotentially related open issues:\n${existing.map((i) => `  #${i.number}: ${i.title} (${i.url})`).join("\n")}`
+                    : "";
+                if (!confirm) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Issue preview:\n\nTitle: ${title}\n\n${body}${dupeInfo}\n\nCall report_issue again with confirm: true to file this issue.`,
+                            },
+                        ],
+                    };
+                }
+                // File the issue
+                const { execSync } = await Promise.resolve().then(() => tslib_1.__importStar(require("child_process")));
+                const url = execSync(`gh issue create --repo apsoai/cli --title "${title.replace(/"/g, '\\"')}" --body-file -`, {
+                    input: body,
+                    encoding: "utf-8",
+                    timeout: 30000,
+                }).trim();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Issue filed: ${url}${dupeInfo}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to file issue: ${msg}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
     }
     registerResources(server) {
         // ── Schema guide resource ──────────────────────────────────────
@@ -717,8 +845,9 @@ function validateSchemaObject(schema) {
         return errors;
     }
     const validFieldTypes = [
-        "text", "integer", "float", "decimal", "numeric",
-        "boolean", "date", "enum", "json", "json-plain", "array",
+        "text", "string", "varchar", "integer", "float", "decimal", "numeric",
+        "boolean", "date", "timestamp", "datetime", "uuid", "enum", "json",
+        "json-plain", "array",
     ];
     const validRelTypes = ["OneToMany", "ManyToOne", "ManyToMany", "OneToOne"];
     const entityNames = new Set();

package/dist/lib/doctor/checks.d.ts

@@ -0,0 +1,35 @@
+import { DiagnosticFinding, DiagnosticContext } from "./types";
+/**
+ * Check that UUID primary keys use @PrimaryGeneratedColumn('uuid')
+ * instead of @PrimaryColumn() in generated entity files.
+ *
+ * Issue #59: uuid PK generated with no generation strategy causes
+ * runtime errors because the database never generates a value.
+ */
+export declare function checkPkStrategy(ctx: DiagnosticContext): DiagnosticFinding[];
+/**
+ * Check for unused imports in generated entity files.
+ *
+ * The code generator sometimes imports symbols (like Generated, Index)
+ * that aren't used in the entity body.
+ */
+export declare function checkUnusedImports(ctx: DiagnosticContext): DiagnosticFinding[];
+/**
+ * Check that each field type in the schema is recognized by the generator.
+ *
+ * Uses the canonical fieldTypeToColumnType map as the source of truth.
+ */
+export declare function checkFieldTypeMismatch(ctx: DiagnosticContext): DiagnosticFinding[];
+/**
+ * Check that relationship targets reference existing entities.
+ *
+ * This overlaps with validate_schema but is included for completeness
+ * in the diagnostic suite.
+ */
+export declare function checkRelationshipTarget(ctx: DiagnosticContext): DiagnosticFinding[];
+/**
+ * Check that generated schema can sync in PGlite without errors.
+ *
+ * This is an async check that imports and runs the migration sandbox.
+ */
+export declare function checkMigrationSandbox(ctx: DiagnosticContext): Promise<DiagnosticFinding[]>;

package/dist/lib/doctor/checks.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkMigrationSandbox = exports.checkRelationshipTarget = exports.checkFieldTypeMismatch = exports.checkUnusedImports = exports.checkPkStrategy = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const field_1 = require("../utils/field");
+const casing_1 = require("../utils/casing");
+/**
+ * Check that UUID primary keys use @PrimaryGeneratedColumn('uuid')
+ * instead of @PrimaryColumn() in generated entity files.
+ *
+ * Issue #59: uuid PK generated with no generation strategy causes
+ * runtime errors because the database never generates a value.
+ */
+function checkPkStrategy(ctx) {
+    var _a, _b;
+    const findings = [];
+    for (const entity of ctx.entities) {
+        if (entity.primaryKeyType !== "uuid")
+            continue;
+        // Check if any field is explicitly marked as primary (custom PK)
+        const hasCustomPk = (_b = (_a = entity.fields) === null || _a === void 0 ? void 0 : _a.some((f) => f.primary)) !== null && _b !== void 0 ? _b : false;
+        if (hasCustomPk)
+            continue;
+        // Look for the generated entity file
+        const entityFileName = `${entity.name}.entity.ts`;
+        const entityDir = (0, casing_1.snakeCase)(entity.name);
+        const entityPath = path.join(ctx.projectRoot, ctx.rootFolder, "autogen", entityDir, entityFileName);
+        if (!fs.existsSync(entityPath)) {
+            findings.push({
+                check: "pk-strategy",
+                severity: "warning",
+                message: `Entity "${entity.name}" has primaryKeyType "uuid" but generated file not found`,
+                entity: entity.name,
+                file: path.relative(ctx.projectRoot, entityPath),
+                suggestion: "Run `apso generate` to create entity files",
+            });
+            continue;
+        }
+        const content = fs.readFileSync(entityPath, "utf-8");
+        // The correct pattern is @PrimaryGeneratedColumn('uuid')
+        const hasPrimaryGenerated = /PrimaryGeneratedColumn\s*\(\s*['"]uuid['"]\s*\)/.test(content);
+        // Wrong patterns: @PrimaryColumn() or @PrimaryColumn({ type: 'uuid' }) without generation
+        const hasPrimaryColumnOnly = /PrimaryColumn\s*\(/.test(content) && !hasPrimaryGenerated;
+        if (hasPrimaryColumnOnly) {
+            findings.push({
+                check: "pk-strategy",
+                severity: "error",
+                message: `Entity "${entity.name}" uses @PrimaryColumn() for UUID PK instead of @PrimaryGeneratedColumn('uuid'). The database will not auto-generate IDs.`,
+                entity: entity.name,
+                file: path.relative(ctx.projectRoot, entityPath),
+                suggestion: `Replace @PrimaryColumn() with @PrimaryGeneratedColumn('uuid') in the entity file, or regenerate with \`apso generate\``,
+            });
+        }
+        else if (!hasPrimaryGenerated) {
+            findings.push({
+                check: "pk-strategy",
+                severity: "warning",
+                message: `Entity "${entity.name}" has primaryKeyType "uuid" but no @PrimaryGeneratedColumn('uuid') found in generated code`,
+                entity: entity.name,
+                file: path.relative(ctx.projectRoot, entityPath),
+                suggestion: "Regenerate with `apso generate`",
+            });
+        }
+    }
+    return findings;
+}
+exports.checkPkStrategy = checkPkStrategy;
+/**
+ * Check for unused imports in generated entity files.
+ *
+ * The code generator sometimes imports symbols (like Generated, Index)
+ * that aren't used in the entity body.
+ */
+function checkUnusedImports(ctx) {
+    const findings = [];
+    if (ctx.language !== "typescript")
+        return findings;
+    for (const entity of ctx.entities) {
+        const entityFileName = `${entity.name}.entity.ts`;
+        const entityDir = (0, casing_1.snakeCase)(entity.name);
+        const entityPath = path.join(ctx.projectRoot, ctx.rootFolder, "autogen", entityDir, entityFileName);
+        if (!fs.existsSync(entityPath))
+            continue;
+        const content = fs.readFileSync(entityPath, "utf-8");
+        const lines = content.split("\n");
+        // Find import lines from typeorm
+        for (const line of lines) {
+            const importMatch = line.match(/import\s*\{([^}]+)\}\s*from\s*['"]typeorm['"]/);
+            if (!importMatch)
+                continue;
+            const imports = importMatch[1]
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            // Check each imported symbol against the rest of the file
+            // (excluding the import line itself)
+            const restOfFile = content.replace(line, "");
+            for (const sym of imports) {
+                // Count usages: decorators appear as @Symbol or Symbol( or Symbol<
+                const usagePattern = new RegExp(`(?:@${sym}\\b|${sym}\\s*[(<])`, "g");
+                const usages = restOfFile.match(usagePattern);
+                if (!usages || usages.length === 0) {
+                    findings.push({
+                        check: "unused-imports",
+                        severity: "warning",
+                        message: `Entity "${entity.name}" imports "${sym}" from typeorm but never uses it`,
+                        entity: entity.name,
+                        file: path.relative(ctx.projectRoot, entityPath),
+                        suggestion: `Remove "${sym}" from the import statement`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+exports.checkUnusedImports = checkUnusedImports;
+/**
+ * Check that each field type in the schema is recognized by the generator.
+ *
+ * Uses the canonical fieldTypeToColumnType map as the source of truth.
+ */
+function checkFieldTypeMismatch(ctx) {
+    const findings = [];
+    const validTypes = new Set(Object.keys(field_1.fieldTypeToColumnType));
+    for (const entity of ctx.entities) {
+        for (const field of entity.fields || []) {
+            if (!validTypes.has(field.type)) {
+                findings.push({
+                    check: "field-type-mismatch",
+                    severity: "error",
+                    message: `Entity "${entity.name}", field "${field.name}": type "${field.type}" is not recognized by the generator`,
+                    entity: entity.name,
+                    suggestion: `Valid types: text, integer, float, decimal, numeric, boolean, date, enum, json, json-plain, array, uuid`,
+                });
+            }
+            // Enum fields must have values
+            if (field.type === "enum" && (!field.values || field.values.length === 0)) {
+                findings.push({
+                    check: "field-type-mismatch",
+                    severity: "error",
+                    message: `Entity "${entity.name}", field "${field.name}": enum type requires a "values" array`,
+                    entity: entity.name,
+                    suggestion: `Add "values": ["option1", "option2"] to the field definition`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+exports.checkFieldTypeMismatch = checkFieldTypeMismatch;
+/**
+ * Check that relationship targets reference existing entities.
+ *
+ * This overlaps with validate_schema but is included for completeness
+ * in the diagnostic suite.
+ */
+function checkRelationshipTarget(ctx) {
+    const findings = [];
+    const entityNames = new Set(ctx.entities.map((e) => e.name));
+    for (const [entityName, relationships] of Object.entries(ctx.relationshipMap)) {
+        if (!entityNames.has(entityName)) {
+            findings.push({
+                check: "relationship-target",
+                severity: "error",
+                message: `Relationship source "${entityName}" does not match any entity`,
+                entity: entityName,
+                suggestion: `Check spelling or add an entity named "${entityName}"`,
+            });
+            continue;
+        }
+        for (const rel of relationships) {
+            if (!entityNames.has(rel.name)) {
+                findings.push({
+                    check: "relationship-target",
+                    severity: "error",
+                    message: `Entity "${entityName}": relationship target "${rel.name}" does not exist`,
+                    entity: entityName,
+                    suggestion: `Check spelling or add an entity named "${rel.name}"`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+exports.checkRelationshipTarget = checkRelationshipTarget;
+/**
+ * Check that generated schema can sync in PGlite without errors.
+ *
+ * This is an async check that imports and runs the migration sandbox.
+ */
+async function checkMigrationSandbox(ctx) {
+    const findings = [];
+    try {
+        const { runMigrationSandbox } = await Promise.resolve().then(() => tslib_1.__importStar(require("../migrate/sandbox")));
+        const result = await runMigrationSandbox({
+            entities: ctx.entities,
+            relationshipMap: ctx.relationshipMap,
+        });
+        if (!result.success) {
+            findings.push({
+                check: "migration-sandbox",
+                severity: "error",
+                message: `Migration sandbox failed: ${result.error || "unknown error"}`,
+                suggestion: "Fix schema issues and run `apso migrate` to debug",
+            });
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        findings.push({
+            check: "migration-sandbox",
+            severity: "warning",
+            message: `Could not run migration sandbox: ${msg}`,
+            suggestion: "Ensure @electric-sql/pglite and typeorm-pglite are installed",
+        });
+    }
+    return findings;
+}
+exports.checkMigrationSandbox = checkMigrationSandbox;

package/dist/lib/doctor/index.d.ts

@@ -0,0 +1,4 @@
+export { DiagnosticFinding, DiagnosticContext } from "./types";
+export { runDiagnostics } from "./runner";
+export { checkPkStrategy, checkUnusedImports, checkFieldTypeMismatch, checkRelationshipTarget, } from "./checks";
+export { isGhAvailable, searchExistingIssues, fileGitHubIssue, } from "./runner";

package/dist/lib/doctor/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileGitHubIssue = exports.searchExistingIssues = exports.isGhAvailable = exports.checkRelationshipTarget = exports.checkFieldTypeMismatch = exports.checkUnusedImports = exports.checkPkStrategy = exports.runDiagnostics = void 0;
+var runner_1 = require("./runner");
+Object.defineProperty(exports, "runDiagnostics", { enumerable: true, get: function () { return runner_1.runDiagnostics; } });
+var checks_1 = require("./checks");
+Object.defineProperty(exports, "checkPkStrategy", { enumerable: true, get: function () { return checks_1.checkPkStrategy; } });
+Object.defineProperty(exports, "checkUnusedImports", { enumerable: true, get: function () { return checks_1.checkUnusedImports; } });
+Object.defineProperty(exports, "checkFieldTypeMismatch", { enumerable: true, get: function () { return checks_1.checkFieldTypeMismatch; } });
+Object.defineProperty(exports, "checkRelationshipTarget", { enumerable: true, get: function () { return checks_1.checkRelationshipTarget; } });
+var runner_2 = require("./runner");
+Object.defineProperty(exports, "isGhAvailable", { enumerable: true, get: function () { return runner_2.isGhAvailable; } });
+Object.defineProperty(exports, "searchExistingIssues", { enumerable: true, get: function () { return runner_2.searchExistingIssues; } });
+Object.defineProperty(exports, "fileGitHubIssue", { enumerable: true, get: function () { return runner_2.fileGitHubIssue; } });

package/dist/lib/doctor/runner.d.ts

@@ -0,0 +1,29 @@
+import { DiagnosticFinding, DiagnosticContext } from "./types";
+/**
+ * Run all diagnostic checks and return aggregated findings.
+ *
+ * Sync checks run first (schema validation, code scanning).
+ * The migration sandbox check is async and runs last.
+ */
+export declare function runDiagnostics(ctx: DiagnosticContext): Promise<DiagnosticFinding[]>;
+/**
+ * Format findings as a human-readable string.
+ */
+export declare function formatFindings(findings: DiagnosticFinding[]): string;
+/**
+ * Check if the GitHub CLI is installed and authenticated.
+ */
+export declare function isGhAvailable(): boolean;
+/**
+ * Search for existing issues that might duplicate what we're about to file.
+ */
+export declare function searchExistingIssues(title: string): {
+    number: number;
+    title: string;
+    url: string;
+}[];
+/**
+ * Build and file a GitHub issue from diagnostic findings.
+ * Returns the URL of the created issue.
+ */
+export declare function fileGitHubIssue(findings: DiagnosticFinding[], ctx: DiagnosticContext): string;

package/dist/lib/doctor/runner.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileGitHubIssue = exports.searchExistingIssues = exports.isGhAvailable = exports.formatFindings = exports.runDiagnostics = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const os = tslib_1.__importStar(require("os"));
+const checks_1 = require("./checks");
+/**
+ * Run all diagnostic checks and return aggregated findings.
+ *
+ * Sync checks run first (schema validation, code scanning).
+ * The migration sandbox check is async and runs last.
+ */
+async function runDiagnostics(ctx) {
+    const findings = [];
+    // Sync checks
+    findings.push(...(0, checks_1.checkFieldTypeMismatch)(ctx));
+    findings.push(...(0, checks_1.checkRelationshipTarget)(ctx));
+    findings.push(...(0, checks_1.checkPkStrategy)(ctx));
+    findings.push(...(0, checks_1.checkUnusedImports)(ctx));
+    // Async checks
+    const sandboxFindings = await (0, checks_1.checkMigrationSandbox)(ctx);
+    findings.push(...sandboxFindings);
+    return findings;
+}
+exports.runDiagnostics = runDiagnostics;
+/**
+ * Format findings as a human-readable string.
+ */
+function formatFindings(findings) {
+    if (findings.length === 0) {
+        return "No issues found.";
+    }
+    const lines = [];
+    const errors = findings.filter((f) => f.severity === "error");
+    const warnings = findings.filter((f) => f.severity === "warning");
+    const infos = findings.filter((f) => f.severity === "info");
+    if (errors.length > 0) {
+        lines.push(`${errors.length} error(s):`);
+        for (const f of errors) {
+            lines.push(formatFinding(f));
+        }
+        lines.push("");
+    }
+    if (warnings.length > 0) {
+        lines.push(`${warnings.length} warning(s):`);
+        for (const f of warnings) {
+            lines.push(formatFinding(f));
+        }
+        lines.push("");
+    }
+    if (infos.length > 0) {
+        lines.push(`${infos.length} info(s):`);
+        for (const f of infos) {
+            lines.push(formatFinding(f));
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+exports.formatFindings = formatFindings;
+function formatFinding(f) {
+    const parts = [`  [${f.severity.toUpperCase()}] ${f.message}`];
+    if (f.file) {
+        parts.push(`    File: ${f.file}`);
+    }
+    if (f.suggestion) {
+        parts.push(`    Fix: ${f.suggestion}`);
+    }
+    return parts.join("\n");
+}
+/**
+ * Check if the GitHub CLI is installed and authenticated.
+ */
+function isGhAvailable() {
+    try {
+        (0, child_process_1.execSync)("gh auth status", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+exports.isGhAvailable = isGhAvailable;
+/**
+ * Search for existing issues that might duplicate what we're about to file.
+ */
+function searchExistingIssues(title) {
+    try {
+        // Extract key terms from the title for search
+        const searchQuery = title.slice(0, 100);
+        const result = (0, child_process_1.execSync)(`gh issue list --repo apsoai/cli --search "${searchQuery.replace(/"/g, '\\"')}" --state open --json number,title,url --limit 5`, { encoding: "utf-8", timeout: 15000 });
+        return JSON.parse(result);
+    }
+    catch {
+        return [];
+    }
+}
+exports.searchExistingIssues = searchExistingIssues;
+/**
+ * Build and file a GitHub issue from diagnostic findings.
+ * Returns the URL of the created issue.
+ */
+function fileGitHubIssue(findings, ctx) {
+    const pkg = loadCliVersion();
+    const title = buildIssueTitle(findings);
+    const body = buildIssueBody(findings, ctx, pkg);
+    const result = (0, child_process_1.execSync)(`gh issue create --repo apsoai/cli --title "${title.replace(/"/g, '\\"')}" --body-file -`, {
+        input: body,
+        encoding: "utf-8",
+        timeout: 30000,
+    });
+    return result.trim();
+}
+exports.fileGitHubIssue = fileGitHubIssue;
+function loadCliVersion() {
+    try {
+        const pkg = require("../../../package.json");
+        return pkg.version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function buildIssueTitle(findings) {
+    const firstError = findings.find((f) => f.severity === "error");
+    if (firstError) {
+        const prefix = firstError.entity ? `[${firstError.entity}] ` : "";
+        return `[doctor] ${prefix}${firstError.message}`.slice(0, 120);
+    }
+    return `[doctor] ${findings.length} diagnostic finding(s)`;
+}
+function buildIssueBody(findings, ctx, cliVersion) {
+    const sections = [];
+    // Environment
+    sections.push("## Environment");
+    sections.push(`- \`@apso/cli\` ${cliVersion} (${os.platform()}, node ${process.version})`);
+    sections.push(`- Language: ${ctx.language}`);
+    sections.push("");
+    // Findings table
+    sections.push("## Diagnostic findings");
+    sections.push("");
+    sections.push("| Severity | Check | Entity | Message |");
+    sections.push("|----------|-------|--------|---------|");
+    for (const f of findings) {
+        sections.push(`| ${f.severity} | ${f.check} | ${f.entity || "-"} | ${f.message} |`);
+    }
+    sections.push("");
+    // Schema excerpt (entity names, field types, PK types -- no field values or data)
+    sections.push("## Schema excerpt");
+    sections.push("```json");
+    const excerpt = ctx.entities.map((e) => ({
+        name: e.name,
+        primaryKeyType: e.primaryKeyType || "serial",
+        fields: (e.fields || []).map((f) => ({
+            name: f.name,
+            type: f.type,
+        })),
+    }));
+    sections.push(JSON.stringify(excerpt, null, 2));
+    sections.push("```");
+    sections.push("");
+    // Suggestions
+    const suggestions = findings
+        .filter((f) => f.suggestion)
+        .map((f) => `- **${f.check}**: ${f.suggestion}`);
+    if (suggestions.length > 0) {
+        sections.push("## Suggested fixes");
+        sections.push(suggestions.join("\n"));
+        sections.push("");
+    }
+    sections.push("---");
+    sections.push("Filed automatically by `apso doctor --report`");
+    return sections.join("\n");
+}

package/dist/lib/doctor/types.d.ts

@@ -0,0 +1,35 @@
+import { Entity } from "../types/entity";
+import { RelationshipMap } from "../types/relationship";
+import { TargetLanguage } from "../types/generator";
+/**
+ * A single finding from a diagnostic check.
+ */
+export interface DiagnosticFinding {
+    /** Check identifier (e.g. "pk-strategy") */
+    check: string;
+    /** Severity level */
+    severity: "error" | "warning" | "info";
+    /** Human-readable description */
+    message: string;
+    /** Affected entity name */
+    entity?: string;
+    /** Affected file path (relative to project root) */
+    file?: string;
+    /** Suggested fix */
+    suggestion?: string;
+}
+/**
+ * Context passed to each diagnostic check function.
+ */
+export interface DiagnosticContext {
+    /** Parsed entities from .apsorc */
+    entities: Entity[];
+    /** Relationship map from .apsorc */
+    relationshipMap: RelationshipMap;
+    /** Root folder from .apsorc (e.g. "src") */
+    rootFolder: string;
+    /** Target language */
+    language: TargetLanguage;
+    /** Absolute path to the project root (where .apsorc lives) */
+    projectRoot: string;
+}

package/dist/lib/doctor/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.13.0",
+      "version": "0.14.0",
       "license": "MIT",
       "dependencies": {
         "@electric-sql/pglite": "^0.2.17",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.13.0",
+  "version": "0.14.0",
   "commands": {
     "config": {
       "id": "config",
@@ -102,6 +102,35 @@
       },
       "args": {}
     },
+    "doctor": {
+      "id": "doctor",
+      "description": "Run diagnostic checks on generated code and optionally file a GitHub issue with findings",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "examples": [
+        "$ apso doctor",
+        "$ apso doctor --json",
+        "$ apso doctor --report"
+      ],
+      "flags": {
+        "report": {
+          "name": "report",
+          "type": "boolean",
+          "description": "File a GitHub issue with diagnostic findings (requires gh CLI)",
+          "allowNo": false
+        },
+        "json": {
+          "name": "json",
+          "type": "boolean",
+          "description": "Output findings as JSON instead of human-readable text",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
     "generate": {
       "id": "generate",
       "description": "Generate code from .apsorc schema",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",