@boopkit/cli 0.1.0

package/dist/lib/capability.d.ts

@@ -0,0 +1,17 @@
+import { CapabilityMetadata } from './config';
+/**
+ * Resolve the directory of an installed @boopkit/cap-{name} package.
+ * Returns null if not found.
+ */
+export declare function getPackageDir(name: string): string | null;
+/**
+ * List all capabilities by scanning package directory and capabilities/ source tree (test fixtures only).
+ * Package resolution takes priority. Returns metadata for each valid capability.
+ */
+export declare function listCapabilities(): CapabilityMetadata[];
+/**
+ * Get a single capability's metadata by name.
+ * Tries package resolution first, falls back to source tree.
+ * Returns null if not found in either location.
+ */
+export declare function getCapability(name: string): CapabilityMetadata | null;

package/dist/lib/capability.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageDir = getPackageDir;
+exports.listCapabilities = listCapabilities;
+exports.getCapability = getCapability;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+/**
+ * Resolve the directory of an installed @boopkit/cap-{name} package.
+ * Returns null if not found.
+ */
+function getPackageDir(name) {
+    const pkgName = `@boopkit/cap-${name}`;
+    try {
+        const pkgJsonPath = require.resolve(`${pkgName}/package.json`, {
+            paths: [(0, config_1.getBoopRoot)()],
+        });
+        return path.dirname(pkgJsonPath);
+    }
+    catch {
+        // Fall back to scanning for a package whose capability.json has this name
+        return findPackageDirByCapabilityName(name);
+    }
+}
+/**
+ * Read capability metadata from a package's capability.json.
+ * Returns null if the package is not found or has no capability.json.
+ */
+function getCapabilityFromPackage(name) {
+    // getPackageDir already falls back to findPackageDirByCapabilityName on
+    // require.resolve failure, so no secondary scan needed here.
+    const pkgDir = getPackageDir(name);
+    if (!pkgDir)
+        return null;
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    if (!fs.existsSync(capJsonPath))
+        return null;
+    // Check the package.json for boopkit.capability === true
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return null;
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    if (!pkgJson.boopkit?.capability)
+        return null;
+    const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+    return capJson;
+}
+/**
+ * Scan node_modules/@boopkit/cap-* to find a package whose capability.json
+ * has the given capability name. Handles mismatches between capability name
+ * and package name (e.g. "users-and-accounts" → @boopkit/cap-users).
+ */
+function findPackageDirByCapabilityName(name) {
+    const nodeModulesBoopkit = path.join((0, config_1.getBoopRoot)(), 'node_modules', '@boopkit');
+    if (!fs.existsSync(nodeModulesBoopkit))
+        return null;
+    const entries = fs.readdirSync(nodeModulesBoopkit, { withFileTypes: true });
+    for (const entry of entries) {
+        if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !entry.name.startsWith('cap-'))
+            continue;
+        const dir = path.join(nodeModulesBoopkit, entry.name);
+        const capJsonPath = path.join(dir, 'capability.json');
+        if (!fs.existsSync(capJsonPath))
+            continue;
+        try {
+            const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+            if (capJson.name === name)
+                return dir;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * List all capabilities by scanning package directory and capabilities/ source tree (test fixtures only).
+ * Package resolution takes priority. Returns metadata for each valid capability.
+ */
+function listCapabilities() {
+    const seen = new Set();
+    const capabilities = [];
+    // Scan node_modules/@boopkit/cap-* for packages with boopkit.capability === true
+    const nodeModulesBoopkit = path.join((0, config_1.getBoopRoot)(), 'node_modules', '@boopkit');
+    if (fs.existsSync(nodeModulesBoopkit)) {
+        const entries = fs.readdirSync(nodeModulesBoopkit, { withFileTypes: true });
+        for (const entry of entries) {
+            if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !entry.name.startsWith('cap-'))
+                continue;
+            const capName = entry.name.replace(/^cap-/, '');
+            const cap = getCapabilityFromPackage(capName);
+            if (cap) {
+                seen.add(capName);
+                capabilities.push(cap);
+            }
+        }
+    }
+    // Fallback: scan capabilities/ source tree for test fixtures
+    const capabilitiesDir = path.join((0, config_1.getBoopRoot)(), 'capabilities');
+    if (fs.existsSync(capabilitiesDir)) {
+        const entries = fs.readdirSync(capabilitiesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (seen.has(entry.name))
+                continue; // Package takes priority
+            const cap = getCapabilityFromSourceTree(entry.name);
+            if (cap) {
+                capabilities.push(cap);
+            }
+        }
+    }
+    return capabilities.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Get a single capability's metadata by name.
+ * Tries package resolution first, falls back to source tree.
+ * Returns null if not found in either location.
+ */
+function getCapability(name) {
+    // Try package first
+    const fromPackage = getCapabilityFromPackage(name);
+    if (fromPackage)
+        return fromPackage;
+    // Fall back to source tree
+    return getCapabilityFromSourceTree(name);
+}
+/**
+ * Get capability metadata from the capabilities/ source tree (test fixtures only).
+ */
+function getCapabilityFromSourceTree(name) {
+    const capMd = path.join((0, config_1.getBoopRoot)(), 'capabilities', name, 'capability.md');
+    const parsed = (0, config_1.parseFrontmatter)(capMd);
+    if (!parsed) {
+        return null;
+    }
+    return parsed.data;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,70 @@
+/** Root of the boop package (where profiles/ and packages/ live). */
+export declare function getBoopRoot(): string;
+export interface KernelConfig {
+    runtime: string;
+    languages: string[];
+    deploy: string;
+    port: number;
+    scripts: Record<string, string>;
+    dependencies?: string[];
+    devDependencies?: string[];
+    nodeVersion?: string;
+}
+export interface ProfileMetadata {
+    name: string;
+    description: string;
+    defaultCapabilities: string[];
+    kernel: KernelConfig;
+}
+export interface CapabilityScript {
+    cmd: string;
+    description: string;
+}
+export interface CapabilityHook {
+    phase: 'imports' | 'init' | 'preRoutes' | 'postRoutes';
+    order?: number;
+    /** Raw code injected into generated server file. TRUST BOUNDARY: not escaped or sandboxed. */
+    code: string;
+    description?: string;
+}
+export interface CapabilityEnvVar {
+    name: string;
+    description: string;
+    default?: string;
+    required?: 'boot' | 'runtime';
+}
+export interface CapabilitySetupCheck {
+    type: 'env-set' | 'service' | 'database' | 'prisma-migrate' | 'prisma-generate';
+    label: string;
+    hint?: string;
+}
+export interface CapabilityPostInstall {
+    prerequisites?: string[];
+    steps?: string[];
+    verify?: string;
+    setupChecks?: CapabilitySetupCheck[];
+}
+export interface CapabilityMetadata {
+    name: string;
+    description: string;
+    type?: 'application' | 'development' | 'operations' | 'demo';
+    requires?: string[];
+    dependencies?: string[];
+    devDependencies?: string[];
+    files?: string[];
+    skills?: string[];
+    scripts?: Record<string, CapabilityScript>;
+    package?: string;
+    hooks?: CapabilityHook[];
+    env?: CapabilityEnvVar[];
+    postInstall?: CapabilityPostInstall;
+}
+export interface ParsedFrontmatter {
+    data: Record<string, unknown>;
+    content: string;
+}
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Returns null if the file does not exist.
+ */
+export declare function parseFrontmatter(filePath: string): ParsedFrontmatter | null;

package/dist/lib/config.js

@@ -0,0 +1,59 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBoopRoot = getBoopRoot;
+exports.parseFrontmatter = parseFrontmatter;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+/** Root of the boop package (where profiles/ and packages/ live). */
+function getBoopRoot() {
+    return path.resolve(__dirname, '..', '..');
+}
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Returns null if the file does not exist.
+ */
+function parseFrontmatter(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const { data, content } = (0, gray_matter_1.default)(raw);
+    return { data, content };
+}

package/dist/lib/db-status.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Parse host and port from a PostgreSQL connection URL.
+ * Returns null if the URL is missing or unparseable.
+ */
+export declare function parseDbHostPort(url: string | undefined): {
+    host: string;
+    port: number;
+} | null;
+/**
+ * Check if a TCP port is reachable (e.g. Postgres is listening).
+ * Resolves true/false; never rejects.
+ */
+export declare function checkTcpReachable(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Check if a specific database is connectable via psql.
+ * Returns true (connectable), false (not connectable), or null (psql not available).
+ */
+export declare function checkDatabaseConnectable(dbUrl: string): Promise<boolean | null>;
+/**
+ * Check if the _prisma_migrations table exists in the database.
+ * Returns true if migrations have been run, false if not, null if psql unavailable.
+ */
+export declare function checkMigrationsTable(dbUrl: string): Promise<boolean | null>;
+/**
+ * Check if any Prisma migrations exist in the project.
+ * Returns true if prisma/migrations/ contains at least one migration subdirectory.
+ */
+export declare function hasPrismaMigrations(projectDir: string): boolean;
+/**
+ * Check if any .prisma files in the project define models.
+ * Returns true if at least one file contains a `model` declaration.
+ */
+export declare function hasPrismaModels(projectDir: string): boolean;
+/**
+ * Check if the Prisma client has been generated.
+ */
+export declare function isPrismaClientGenerated(projectDir: string): boolean;
+/**
+ * Check if Prisma schema is in sync with the database.
+ * Uses `prisma migrate status` which reports pending migrations.
+ * Returns true if in sync, false if not, null if prisma not available.
+ */
+export declare function checkPrismaMigrateStatus(projectDir: string): Promise<boolean | null>;
+export interface SetupStep {
+    label: string;
+    done: boolean;
+    hint?: string;
+}
+export interface CheckContext {
+    envValues: Map<string, string>;
+    projectDir: string;
+    projectName: string;
+    /** Accumulated results from earlier checks — keyed by check type. */
+    results: Map<string, boolean>;
+}
+/**
+ * Run all setup checks declared in a capability's setupChecks list.
+ * Returns an ordered list of steps with live done/pending status.
+ */
+export declare function runSetupChecks(checks: {
+    type: string;
+    label: string;
+    hint?: string;
+}[], envValues: Map<string, string>, projectDir: string, projectName: string): Promise<SetupStep[]>;

package/dist/lib/db-status.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDbHostPort = parseDbHostPort;
+exports.checkTcpReachable = checkTcpReachable;
+exports.checkDatabaseConnectable = checkDatabaseConnectable;
+exports.checkMigrationsTable = checkMigrationsTable;
+exports.hasPrismaMigrations = hasPrismaMigrations;
+exports.hasPrismaModels = hasPrismaModels;
+exports.isPrismaClientGenerated = isPrismaClientGenerated;
+exports.checkPrismaMigrateStatus = checkPrismaMigrateStatus;
+exports.runSetupChecks = runSetupChecks;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+/**
+ * Parse host and port from a PostgreSQL connection URL.
+ * Returns null if the URL is missing or unparseable.
+ */
+function parseDbHostPort(url) {
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(url);
+        return {
+            host: parsed.hostname || 'localhost',
+            port: parseInt(parsed.port, 10) || 5432,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a TCP port is reachable (e.g. Postgres is listening).
+ * Resolves true/false; never rejects.
+ */
+function checkTcpReachable(host, port, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, host);
+    });
+}
+/**
+ * Check if a specific database is connectable via psql.
+ * Returns true (connectable), false (not connectable), or null (psql not available).
+ */
+function checkDatabaseConnectable(dbUrl) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('psql', [dbUrl, '-c', 'SELECT 1'], { timeout: 3000 }, (error) => {
+            if (error) {
+                if ('code' in error && error.code === 'ENOENT') {
+                    resolve(null); // psql not installed
+                }
+                else {
+                    resolve(false); // connection failed (db doesn't exist, auth error, etc.)
+                }
+            }
+            else {
+                resolve(true);
+            }
+        });
+    });
+}
+/**
+ * Check if the _prisma_migrations table exists in the database.
+ * Returns true if migrations have been run, false if not, null if psql unavailable.
+ */
+function checkMigrationsTable(dbUrl) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('psql', [dbUrl, '-tAc', "SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = '_prisma_migrations')"], { timeout: 3000 }, (error, stdout) => {
+            if (error) {
+                if ('code' in error && error.code === 'ENOENT') {
+                    resolve(null);
+                }
+                else {
+                    resolve(false);
+                }
+            }
+            else {
+                resolve(stdout.trim() === 't');
+            }
+        });
+    });
+}
+/**
+ * Check if any Prisma migrations exist in the project.
+ * Returns true if prisma/migrations/ contains at least one migration subdirectory.
+ */
+function hasPrismaMigrations(projectDir) {
+    const migrationsDir = path.join(projectDir, 'prisma', 'schema', 'migrations');
+    if (!fs.existsSync(migrationsDir))
+        return false;
+    const entries = fs.readdirSync(migrationsDir, { withFileTypes: true });
+    return entries.some(e => e.isDirectory());
+}
+/**
+ * Check if any .prisma files in the project define models.
+ * Returns true if at least one file contains a `model` declaration.
+ */
+function hasPrismaModels(projectDir) {
+    const prismaDir = path.join(projectDir, 'prisma', 'schema');
+    if (!fs.existsSync(prismaDir))
+        return false;
+    const files = fs.readdirSync(prismaDir).filter(f => f.endsWith('.prisma'));
+    return files.some(f => {
+        const content = fs.readFileSync(path.join(prismaDir, f), 'utf-8');
+        return /^\s*model\s+\w+/m.test(content);
+    });
+}
+/**
+ * Check if the Prisma client has been generated.
+ */
+function isPrismaClientGenerated(projectDir) {
+    return fs.existsSync(path.join(projectDir, 'node_modules', '.prisma', 'client', 'index.js'));
+}
+/**
+ * Check if Prisma schema is in sync with the database.
+ * Uses `prisma migrate status` which reports pending migrations.
+ * Returns true if in sync, false if not, null if prisma not available.
+ */
+function checkPrismaMigrateStatus(projectDir) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('npx', ['prisma', 'migrate', 'status', '--schema=prisma/schema/'], { timeout: 10000, cwd: projectDir }, (error, stdout) => {
+            if (error) {
+                if ('code' in error && error.code === 'ENOENT') {
+                    resolve(null);
+                }
+                else {
+                    // prisma migrate status exits non-zero when migrations are pending
+                    resolve(false);
+                }
+            }
+            else {
+                // Trust Prisma's assessment of migration status
+                resolve(stdout.includes('Database schema is up to date'));
+            }
+        });
+    });
+}
+/**
+ * Run a single setup check by type. Returns true/false for pass/fail.
+ * Checks can depend on earlier results via ctx.results.
+ */
+async function runCheck(type, ctx) {
+    switch (type) {
+        case 'env-set': {
+            const dbUrl = ctx.envValues.get('DATABASE_URL');
+            return !!dbUrl;
+        }
+        case 'service': {
+            const dbUrl = ctx.envValues.get('DATABASE_URL');
+            if (!dbUrl)
+                return false;
+            const hostPort = parseDbHostPort(dbUrl);
+            if (!hostPort)
+                return false;
+            return checkTcpReachable(hostPort.host, hostPort.port);
+        }
+        case 'database': {
+            if (!ctx.results.get('service'))
+                return false;
+            const dbUrl = ctx.envValues.get('DATABASE_URL');
+            if (!dbUrl)
+                return false;
+            const result = await checkDatabaseConnectable(dbUrl);
+            return result === true;
+        }
+        case 'prisma-migrate': {
+            // Skip only if a database check was explicitly run and failed
+            if (ctx.results.has('database') && !ctx.results.get('database'))
+                return false;
+            // If schema has models but no migrations exist, migration hasn't been run
+            if (hasPrismaModels(ctx.projectDir) && !hasPrismaMigrations(ctx.projectDir))
+                return false;
+            const result = await checkPrismaMigrateStatus(ctx.projectDir);
+            return result === true;
+        }
+        case 'prisma-generate': {
+            return isPrismaClientGenerated(ctx.projectDir);
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Run all setup checks declared in a capability's setupChecks list.
+ * Returns an ordered list of steps with live done/pending status.
+ */
+async function runSetupChecks(checks, envValues, projectDir, projectName) {
+    const ctx = { envValues, projectDir, projectName, results: new Map() };
+    const steps = [];
+    for (const check of checks) {
+        const done = await runCheck(check.type, ctx);
+        ctx.results.set(check.type, done);
+        let hint = check.hint;
+        // When prisma-migrate fails and no migrations exist yet, the first
+        // `prisma migrate dev` will prompt interactively for a name.
+        // Adjust the hint so users (and agents) pass --name to avoid the prompt.
+        // Only apply fallback if the capability hint doesn't already specify --name.
+        if (check.type === 'prisma-migrate' && !done && !hasPrismaMigrations(ctx.projectDir) && (!hint || !hint.includes('--name'))) {
+            hint = 'npm run db:migrate -- --name init';
+        }
+        steps.push({
+            label: check.label,
+            done,
+            hint,
+        });
+    }
+    return steps;
+}

package/dist/lib/env.d.ts

@@ -0,0 +1,25 @@
+export interface EnvEntry {
+    name: string;
+    description: string;
+    default?: string;
+    capability: string;
+}
+/**
+ * Generate or append to .env and .env.example files from capability env declarations.
+ * - Creates files if they don't exist
+ * - Appends new entries without duplicating existing ones
+ * - .env gets empty values (so the var is unset and capabilities degrade gracefully)
+ * - .env.example gets interpolated defaults (as documentation for the developer)
+ */
+export declare function generateEnvFiles(dir: string, entries: EnvEntry[], projectName: string): void;
+/**
+ * Read a .env file and return the set of variable names that have non-empty values.
+ * Returns an empty set if the file does not exist.
+ */
+export declare function readEnvKeys(filePath: string): Set<string>;
+/**
+ * Read a .env file and return a map of variable names to their values.
+ * Only includes variables with non-empty values.
+ * Returns an empty map if the file does not exist.
+ */
+export declare function readEnvValues(filePath: string): Map<string, string>;