@generacy-ai/generacy 0.0.0-preview-20260304013206

package/dist/cli/commands/doctor/runner.js

@@ -0,0 +1,257 @@
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default timeout for checks that involve network calls (ms). */
+const CHECK_TIMEOUT_MS = 5_000;
+/** Categories that involve network calls and should be subject to timeout. */
+const NETWORK_CATEGORIES = new Set(['credentials', 'services']);
+// ---------------------------------------------------------------------------
+// runChecks — main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Execute an ordered list of checks, running independent checks concurrently
+ * within each dependency tier.
+ *
+ * The `checks` array **must** be in topological (dependency) order — as
+ * returned by `CheckRegistry.resolve()`. The runner groups them into tiers
+ * where all items in a tier have their dependencies satisfied by earlier tiers,
+ * then runs each tier concurrently via `Promise.all`.
+ *
+ * @returns A `DoctorReport` containing per-check results and a summary.
+ */
+export async function runChecks(checks, options) {
+    // Shared mutable context populated progressively by checks
+    const context = {
+        configPath: null,
+        config: null,
+        envVars: null,
+        inDevContainer: !!process.env.REMOTE_CONTAINERS,
+        verbose: options.verbose ?? false,
+        projectRoot: null,
+    };
+    // Outcomes keyed by check ID
+    const outcomes = new Map();
+    // Build execution tiers
+    const tiers = buildTiers(checks);
+    for (const tier of tiers) {
+        await Promise.all(tier.map(async (check) => {
+            const outcome = await executeCheck(check, context, outcomes);
+            outcomes.set(check.id, outcome);
+        }));
+    }
+    // Assemble report
+    const entries = checks.map((check) => {
+        const outcome = outcomes.get(check.id);
+        const entry = {
+            id: check.id,
+            label: check.label,
+            category: check.category,
+            status: outcome.result.status,
+            message: outcome.result.message,
+            duration_ms: outcome.duration_ms,
+        };
+        if (outcome.result.suggestion)
+            entry.suggestion = outcome.result.suggestion;
+        if (outcome.result.detail)
+            entry.detail = outcome.result.detail;
+        return entry;
+    });
+    const summary = computeSummary(entries);
+    const exitCode = computeExitCode(entries);
+    return {
+        version: 1,
+        timestamp: new Date().toISOString(),
+        summary,
+        checks: entries,
+        exitCode,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tier building
+// ---------------------------------------------------------------------------
+/**
+ * Group checks into execution tiers. Each tier contains checks whose
+ * dependencies all appear in earlier tiers (or have no dependencies).
+ *
+ * Assumes `checks` is already in topological order.
+ */
+function buildTiers(checks) {
+    const tiers = [];
+    // Track which tier each check is assigned to
+    const tierIndex = new Map();
+    for (const check of checks) {
+        // The earliest tier this check can run in is one past the highest tier
+        // of any of its dependencies.
+        let maxDepTier = -1;
+        for (const dep of check.dependencies) {
+            const depTier = tierIndex.get(dep);
+            if (depTier !== undefined && depTier > maxDepTier) {
+                maxDepTier = depTier;
+            }
+        }
+        const myTier = maxDepTier + 1;
+        tierIndex.set(check.id, myTier);
+        while (tiers.length <= myTier) {
+            tiers.push([]);
+        }
+        tiers[myTier].push(check);
+    }
+    return tiers;
+}
+// ---------------------------------------------------------------------------
+// Single check execution
+// ---------------------------------------------------------------------------
+/**
+ * Execute a single check, handling:
+ * - Dependency skip propagation
+ * - Timeout wrapping for network checks
+ * - Context merging from result data
+ * - Duration tracking
+ */
+async function executeCheck(check, context, outcomes) {
+    // Check if any dependency failed or was skipped due to a failure
+    const failedDep = findFailedDependency(check, outcomes);
+    if (failedDep) {
+        return {
+            result: {
+                status: 'skip',
+                message: `Skipped — dependency '${failedDep}' failed`,
+            },
+            duration_ms: 0,
+        };
+    }
+    const start = performance.now();
+    try {
+        let result;
+        if (NETWORK_CATEGORIES.has(check.category)) {
+            result = await withTimeout(check.run(context), CHECK_TIMEOUT_MS, check.id);
+        }
+        else {
+            result = await check.run(context);
+        }
+        // Merge any data the check wants to share into the context
+        if (result.data) {
+            mergeContextData(context, result.data);
+        }
+        const duration_ms = Math.round(performance.now() - start);
+        return { result, duration_ms };
+    }
+    catch (error) {
+        const duration_ms = Math.round(performance.now() - start);
+        return {
+            result: {
+                status: 'fail',
+                message: `Internal error: ${error instanceof Error ? error.message : String(error)}`,
+                detail: error instanceof Error ? error.stack : undefined,
+            },
+            duration_ms,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Dependency failure detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns the ID of the first dependency that failed (status `'fail'`) or
+ * was itself skipped due to a dependency failure. Returns `undefined` if
+ * all dependencies passed or warned.
+ */
+function findFailedDependency(check, outcomes) {
+    for (const depId of check.dependencies) {
+        const depOutcome = outcomes.get(depId);
+        if (!depOutcome)
+            continue; // not yet run — shouldn't happen in tier model
+        if (depOutcome.result.status === 'fail' || depOutcome.result.status === 'skip') {
+            return depId;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Timeout wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a check promise with a timeout. If the check doesn't resolve within
+ * `ms` milliseconds, return a `fail` result.
+ */
+async function withTimeout(promise, ms, checkId) {
+    let timeoutId;
+    const timeoutPromise = new Promise((resolve) => {
+        timeoutId = setTimeout(() => {
+            resolve({
+                status: 'fail',
+                message: `Check timed out after ${ms / 1000}s`,
+                suggestion: `The '${checkId}' check did not respond within ${ms / 1000} seconds. Check your network connection.`,
+            });
+        }, ms);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Context merging
+// ---------------------------------------------------------------------------
+/**
+ * Merge data from a check result into the shared context. Only known
+ * context keys are merged.
+ */
+function mergeContextData(context, data) {
+    if ('configPath' in data && typeof data.configPath === 'string') {
+        context.configPath = data.configPath;
+    }
+    if ('config' in data && data.config !== undefined) {
+        context.config = data.config;
+    }
+    if ('envVars' in data && data.envVars !== undefined) {
+        context.envVars = data.envVars;
+    }
+    if ('projectRoot' in data && typeof data.projectRoot === 'string') {
+        context.projectRoot = data.projectRoot;
+    }
+}
+// ---------------------------------------------------------------------------
+// Summary & exit code
+// ---------------------------------------------------------------------------
+function computeSummary(entries) {
+    let passed = 0;
+    let failed = 0;
+    let warnings = 0;
+    let skipped = 0;
+    for (const entry of entries) {
+        switch (entry.status) {
+            case 'pass':
+                passed++;
+                break;
+            case 'fail':
+                failed++;
+                break;
+            case 'warn':
+                warnings++;
+                break;
+            case 'skip':
+                skipped++;
+                break;
+        }
+    }
+    return { passed, failed, warnings, skipped, total: entries.length };
+}
+function computeExitCode(entries) {
+    for (const entry of entries) {
+        if (entry.message.startsWith('Internal error:')) {
+            return 2;
+        }
+    }
+    for (const entry of entries) {
+        if (entry.status === 'fail') {
+            return 1;
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=runner.js.map

package/dist/cli/commands/doctor/runner.js.map

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

package/dist/cli/commands/doctor/types.d.ts

@@ -0,0 +1,87 @@
+import type { GeneracyConfig } from '../../../config/index.js';
+export type CheckCategory = 'system' | 'config' | 'credentials' | 'packages' | 'services';
+export interface CheckDefinition {
+    /** Unique identifier, e.g. 'docker', 'config', 'github-token'. */
+    id: string;
+    /** Human-readable label shown in output. */
+    label: string;
+    /** Category for grouping: system, config, credentials, packages, services. */
+    category: CheckCategory;
+    /** IDs of checks that must pass before this one runs. */
+    dependencies: string[];
+    /** Priority: P1 checks always run; P2 can be skipped. */
+    priority: 'P1' | 'P2';
+    /** The check function. */
+    run: (context: CheckContext) => Promise<CheckResult>;
+    /** Optional auto-fix function (reserved for future use). */
+    fix?: (context: CheckContext) => Promise<FixResult>;
+}
+export interface CheckContext {
+    /** Resolved config file path (null if not yet found). */
+    configPath: string | null;
+    /** Parsed config (null if config check failed or hasn't run). */
+    config: GeneracyConfig | null;
+    /** Parsed env vars from .generacy/generacy.env. */
+    envVars: Record<string, string> | null;
+    /** Whether running inside a dev container. */
+    inDevContainer: boolean;
+    /** Whether --verbose was passed. */
+    verbose: boolean;
+    /** Project root directory (null if not yet resolved). */
+    projectRoot: string | null;
+}
+export interface CheckResult {
+    /** Outcome of the check. */
+    status: 'pass' | 'fail' | 'warn' | 'skip';
+    /** Short description of the result. */
+    message: string;
+    /** Actionable fix suggestion (shown on fail/warn). */
+    suggestion?: string;
+    /** Additional detail shown in --verbose mode. */
+    detail?: string;
+    /** Data to merge into CheckContext for dependent checks. */
+    data?: Record<string, unknown>;
+}
+export interface DoctorOptions {
+    /** Run only these checks (and their transitive dependencies). */
+    check?: string[];
+    /** Skip these checks. */
+    skip?: string[];
+    /** Output results as JSON. */
+    json?: boolean;
+    /** Show detailed diagnostic information. */
+    verbose?: boolean;
+    /** Attempt to auto-fix detected issues (reserved for future use). */
+    fix?: boolean;
+}
+export interface DoctorReportCheckEntry {
+    id: string;
+    label: string;
+    category: CheckCategory;
+    status: 'pass' | 'fail' | 'warn' | 'skip';
+    message: string;
+    suggestion?: string;
+    detail?: string;
+    duration_ms?: number;
+}
+export interface DoctorReportSummary {
+    passed: number;
+    failed: number;
+    warnings: number;
+    skipped: number;
+    total: number;
+}
+export interface DoctorReport {
+    version: number;
+    timestamp: string;
+    summary: DoctorReportSummary;
+    checks: DoctorReportCheckEntry[];
+    exitCode: 0 | 1 | 2;
+}
+export interface FixResult {
+    /** Whether the fix was applied successfully. */
+    success: boolean;
+    /** Description of what was done (or why it failed). */
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/commands/doctor/types.d.ts.map

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

package/dist/cli/commands/doctor/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/commands/doctor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/cli/commands/doctor/types.ts"],"names":[],"mappings":""}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Doctor command definition.
+ * Validates the full development environment setup by running a series of
+ * categorized health checks with color-coded pass/fail/warning output and
+ * actionable fix suggestions.
+ */
+import { Command } from 'commander';
+/**
+ * Create the doctor command.
+ */
+export declare function doctorCommand(): Command;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyCpC;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAoEvC"}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,97 @@
+/**
+ * Doctor command definition.
+ * Validates the full development environment setup by running a series of
+ * categorized health checks with color-coded pass/fail/warning output and
+ * actionable fix suggestions.
+ */
+import { Command } from 'commander';
+import { CheckRegistry, runChecks, formatText, formatJson } from './doctor/index.js';
+// Individual checks
+import { dockerCheck } from './doctor/checks/docker.js';
+import { configCheck } from './doctor/checks/config.js';
+import { envFileCheck } from './doctor/checks/env-file.js';
+import { devcontainerCheck } from './doctor/checks/devcontainer.js';
+import { githubTokenCheck } from './doctor/checks/github-token.js';
+import { anthropicKeyCheck } from './doctor/checks/anthropic-key.js';
+import { npmPackagesCheck } from './doctor/checks/npm-packages.js';
+import { agencyMcpCheck } from './doctor/checks/agency-mcp.js';
+/**
+ * Create and configure a registry with all built-in checks.
+ */
+function createDefaultRegistry() {
+    const registry = new CheckRegistry();
+    // System checks
+    registry.register(dockerCheck);
+    registry.register(devcontainerCheck);
+    // Config checks
+    registry.register(configCheck);
+    registry.register(envFileCheck);
+    // Credential checks
+    registry.register(githubTokenCheck);
+    registry.register(anthropicKeyCheck);
+    // Package checks
+    registry.register(npmPackagesCheck);
+    // Service checks
+    registry.register(agencyMcpCheck);
+    return registry;
+}
+/**
+ * Create the doctor command.
+ */
+export function doctorCommand() {
+    const command = new Command('doctor');
+    command
+        .description('Validate the full development environment setup')
+        .option('--check <name...>', 'Run only specific checks (and their dependencies)')
+        .option('--skip <name...>', 'Skip specific checks')
+        .option('-j, --json', 'Output results as JSON')
+        .option('-v, --verbose', 'Show detailed diagnostic information')
+        .option('-f, --fix', 'Attempt to fix detected issues (where possible)')
+        .action(async (options) => {
+        const doctorOptions = {
+            check: options.check,
+            skip: options.skip,
+            json: options.json,
+            verbose: options.verbose,
+            fix: options.fix,
+        };
+        try {
+            // Build registry and resolve checks
+            const registry = createDefaultRegistry();
+            const checks = registry.resolve({
+                check: doctorOptions.check,
+                skip: doctorOptions.skip,
+            });
+            if (doctorOptions.fix) {
+                console.error('Note: Auto-fix is not yet implemented. Running checks only.');
+            }
+            // Execute checks
+            const report = await runChecks(checks, doctorOptions);
+            // Format and output
+            if (doctorOptions.json) {
+                console.log(formatJson(report));
+            }
+            else {
+                console.log(formatText(report, checks, doctorOptions.verbose ?? false));
+            }
+            process.exit(report.exitCode);
+        }
+        catch (error) {
+            // Internal errors (e.g., invalid --check/--skip names, circular deps)
+            if (doctorOptions.json) {
+                console.log(JSON.stringify({
+                    version: 1,
+                    timestamp: new Date().toISOString(),
+                    error: error instanceof Error ? error.message : String(error),
+                    exitCode: 2,
+                }, null, 2));
+            }
+            else {
+                console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            process.exit(2);
+        }
+    });
+    return command;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

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

package/dist/cli/commands/init/conflicts.d.ts

@@ -0,0 +1,36 @@
+import type { FileAction, InitOptions } from './types.js';
+/**
+ * Check which rendered files already exist on disk.
+ *
+ * @param files - Map of relative path → generated content (from `renderProject`).
+ * @param gitRoot - Absolute path to the git repository root.
+ * @returns Map of conflicting relative paths → existing file content.
+ */
+export declare function checkConflicts(files: Map<string, string>, gitRoot: string): Map<string, string>;
+/**
+ * Print a unified diff between the existing and generated file content.
+ *
+ * Uses the `diff` package's `createTwoFilesPatch()` to produce a standard
+ * unified diff with `--- existing` / `+++ generated` headers.
+ *
+ * @param path - Relative file path (used in the diff header).
+ * @param existing - Current file content on disk.
+ * @param generated - New content that would be written.
+ */
+export declare function showDiff(path: string, existing: string, generated: string): void;
+/**
+ * Resolve per-file actions for all rendered files, handling conflicts.
+ *
+ * - Non-conflicting files → `'overwrite'` (create new).
+ * - `--force` flag → all conflicts → `'overwrite'`.
+ * - Files in `MERGE_FILES` → `'merge'` (smart merge handled by `renderProject`'s
+ *   `existingFiles` parameter upstream).
+ * - Otherwise → interactive per-file prompt: Overwrite / Skip / Show diff.
+ *
+ * @param files - Map of relative path → generated content.
+ * @param conflicts - Map of conflicting relative paths → existing content.
+ * @param options - Resolved init options (uses `force` and `yes` flags).
+ * @returns Map of relative path → resolved `FileAction`.
+ */
+export declare function resolveConflicts(files: Map<string, string>, conflicts: Map<string, string>, options: InitOptions): Promise<Map<string, FileAction>>;
+//# sourceMappingURL=conflicts.d.ts.map

package/dist/cli/commands/init/conflicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflicts.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init/conflicts.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,MAAM,GACd,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBrB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAYN;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAqDlC"}