askdb 1.0.0-beta.48 → 1.0.0-beta.49

package/dist/init.js

@@ -4,21 +4,20 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getBuiltinAiProviderSetup, listBuiltinAiProviderSetups } from "@askdb/ai";
-import { ASKDB_AI_PROVIDERS } from "@askdb/config";
-import { renderAskDbAiConfigScaffold } from "@askdb/config/scaffold";
-import { PRISMA_BUILD_APPROVALS } from "./prisma-install.js";
+import { ASKDB_AI_PROVIDERS, ASKDB_RAG_STORES } from "@askdb/config";
+import { AskDbScaffoldInputError, detectPackageManager, findNearestPackageJsonDir, formatInstallCommand, isAskDbScaffoldEnvName, isLikelyWorkspaceRoot, packageManagerAddArgs, packageManagerSpawnSpec, planAskDbScaffold, supportedBuildApprovals, } from "@askdb/config/scaffold";
+import { errorMessage } from "./cli-error.js";
+import { runCommand } from "./command.js";
+import { showable } from "./error-values.js";
 const DEFAULT_CONFIG_PATH = "askdb.config.ts";
-// ---------------------------------------------------------------------------
-// Config rendering
-// ---------------------------------------------------------------------------
 /**
  * Selectable AI providers, in `@askdb/ai`'s built-in table order: every id that has an
  * `askdb.config.*` branch (`ASKDB_AI_PROVIDERS`), with the key/model env var names to
  * scaffold. Derived from `@askdb/ai`'s `BUILTIN_AI_PROVIDERS` so it cannot drift.
  */
 const AI_PROVIDER_SETUPS = listBuiltinAiProviderSetups(ASKDB_AI_PROVIDERS);
-/** Every id `--ai-provider` accepts; `cli.ts` builds its help text from this list too. */
-export const VALID_AI_PROVIDERS = AI_PROVIDER_SETUPS.map((setup) => setup.id);
+/** Every id `--ai-provider` accepts; its help line lists them. */
+const VALID_AI_PROVIDERS = AI_PROVIDER_SETUPS.map((setup) => setup.id);
 function aiDefaults(provider) {
     const setup = getBuiltinAiProviderSetup(provider);
     if (!setup)
@@ -26,166 +25,69 @@ function aiDefaults(provider) {
     return setup;
 }
 /**
- * Render a value as a TypeScript string literal for the generated config.
- * Every interpolated value goes through this — the file is later executed
- * (via jiti), so a raw `"${value}"` would let a quote in a path inject code.
- * Mirrors `tsString` in `apps/studio/src/setup.ts`.
+ * `--sqlite-file`'s value as the config reads it: a value the planner accepts as an env var
+ * name (`SQLITE_FILE`, `UPPER_SNAKE_CASE`) is a variable, anything else (`data.db`,
+ * `../db/app.db`, `/srv/app.db`) a path. No value means the `SQLITE_FILE` variable.
  */
-function tsString(value) {
-    return JSON.stringify(value);
-}
-/** An env var name as `--sqlite-file` accepts one, e.g. `SQLITE_FILE`. Anything else is a path. */
-const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
-/**
- * The env var a SQLite `file` setting reads, or `undefined` when it's a literal
- * path (`data.db`, `../db/app.db`, `/srv/app.db`, …). Only an env-name-shaped value
- * is a variable. No value means the `SQLITE_FILE` default. Rendering, the
- * `.env.example`, and the printed variable list all go through this.
- */
-function sqliteFileEnv(file) {
+function sqliteFileValue(file) {
     if (!file)
-        return "SQLITE_FILE";
-    return ENV_NAME_PATTERN.test(file) ? file : undefined;
+        return { env: "SQLITE_FILE" };
+    return isAskDbScaffoldEnvName(file) ? { env: file } : { path: file };
+}
+/** `InitAnswers` as the planner in `@askdb/config/scaffold` takes them. It ignores what the engine doesn't read. */
+function scaffoldAnswers(answers) {
+    const { studioExecute } = answers;
+    return {
+        database: answers.database,
+        connectionEnv: answers.connectionEnv ?? "DATABASE_URL",
+        sqliteFile: sqliteFileValue(answers.sqliteFile),
+        ...(answers.prismaSchema ? { prismaSchemaPath: answers.prismaSchema } : {}),
+        schemaOut: answers.schemaOut,
+        ai: {
+            provider: answers.aiProvider,
+            keyEnv: answers.aiKeyEnv,
+            ...(answers.aiModelEnv ? { modelEnv: answers.aiModelEnv } : {}),
+        },
+        rag: { store: answers.ragStore, pgvectorEnv: answers.pgvectorEnv ?? "ASKDB_PGVECTOR_URL" },
+        ...(studioExecute.enabled
+            ? {
+                studioExecute: {
+                    provider: studioExecute.provider,
+                    connectionEnv: studioExecute.connectionEnv ?? "DATABASE_URL",
+                    sqliteFile: sqliteFileValue(studioExecute.sqliteFile),
+                },
+            }
+            : {}),
+    };
 }
+/** The flag that sets each planner answer, for errors. */
+const ANSWER_FLAGS = {
+    database: "--database",
+    connectionEnv: "--connection-env",
+    sqliteFile: "--sqlite-file",
+    prismaSchemaPath: "--prisma-schema",
+    schemaOut: "--schema-out",
+    "ai.provider": "--ai-provider",
+    "ai.keyEnv": "--ai-key-env",
+    "ai.modelEnv": "--ai-model-env",
+    "rag.store": "--rag-store",
+    "rag.pgvectorEnv": "--pgvector-env",
+    "studioExecute.sqliteFile": "--sqlite-file",
+};
 /**
- * The `ai` block and the env vars it reads, from `@askdb/config/scaffold` (shared with
- * Studio's setup wizard, so provider-specific fields such as Azure's
- * `resourceName` live in one place).
+ * The config, `.env.example` and installs for `answers`, from `@askdb/config/scaffold`'s
+ * planner (shared with Studio's setup wizard). A bad answer fails with an error that names
+ * its flag, before anything is written.
  */
-function aiScaffold(answers) {
-    return renderAskDbAiConfigScaffold({
-        provider: answers.aiProvider,
-        keyEnv: answers.aiKeyEnv,
-        ...(answers.aiModelEnv ? { modelEnv: answers.aiModelEnv } : {}),
-    });
-}
-function renderIntrospectionSection(answers) {
-    const { database, connectionEnv, sqliteFile, prismaSchema, schemaOut } = answers;
-    const outputDirLine = `\n    outputDir: ${tsString(schemaOut)},`;
-    const connectionEnvExpr = `env(${tsString(connectionEnv ?? "DATABASE_URL")})`;
-    switch (database) {
-        case "postgres":
-            return `  introspection: {
-    provider: "postgres",
-    providerConfig: {
-      postgres: {
-        databaseUrl: ${connectionEnvExpr},
-      },
-    },${outputDirLine}
-  },`;
-        case "mysql":
-            return `  introspection: {
-    provider: "mysql",
-    providerConfig: {
-      mysql: {
-        databaseUrl: ${connectionEnvExpr},
-      },
-    },${outputDirLine}
-  },`;
-        case "sqlite": {
-            const fileEnv = sqliteFileEnv(sqliteFile);
-            const resolvedFile = fileEnv ? `env(${tsString(fileEnv)})` : tsString(sqliteFile);
-            return `  introspection: {
-    provider: "sqlite",
-    providerConfig: {
-      sqlite: {
-        file: ${resolvedFile},
-      },
-    },${outputDirLine}
-  },`;
-        }
-        case "sqlserver":
-            return `  introspection: {
-    provider: "sqlserver",
-    providerConfig: {
-      sqlserver: {
-        databaseUrl: ${connectionEnvExpr},
-      },
-    },${outputDirLine}
-  },`;
-        case "prisma": {
-            const schemaLine = prismaSchema ? `\n        schemaPath: ${tsString(prismaSchema)},` : "";
-            return `  introspection: {
-    provider: "prisma",
-    providerConfig: {
-      prisma: {${schemaLine}
-      },
-    },${outputDirLine}
-  },`;
-        }
-    }
-}
-function renderRagSection(answers) {
-    const { ragStore, pgvectorEnv } = answers;
-    switch (ragStore) {
-        case "file":
-            return `  rag: {
-    embedder: "mock",
-    store: "file",
-    storeConfig: {
-      file: {},
-    },
-  },`;
-        case "memory":
-            return `  rag: {
-    embedder: "mock",
-    store: "memory",
-    storeConfig: {
-      memory: {},
-    },
-  },`;
-        case "pgvector":
-            return `  rag: {
-    embedder: "mock",
-    store: "pgvector",
-    storeConfig: {
-      pgvector: {
-        databaseUrl: env(${tsString(pgvectorEnv ?? "ASKDB_PGVECTOR_URL")}),
-      },
-    },
-  },`;
+export function planInitScaffold(answers, specs) {
+    try {
+        return planAskDbScaffold(scaffoldAnswers(answers), { config: specs.configSpec, prisma: specs.prismaSpec });
     }
-}
-function renderStudioSection(answers) {
-    const { studioExecute } = answers;
-    if (!studioExecute.enabled)
-        return null;
-    const { provider } = studioExecute;
-    if (provider === "sqlite") {
-        const fileEnv = sqliteFileEnv(studioExecute.sqliteFile);
-        const fileExpr = fileEnv ? `env(${tsString(fileEnv)})` : tsString(studioExecute.sqliteFile);
-        return `  studio: {
-    execute: {
-      enabled: true,
-      provider: "sqlite",
-      file: ${fileExpr},
-    },
-  },`;
+    catch (error) {
+        if (!(error instanceof AskDbScaffoldInputError))
+            throw error;
+        throw new Error(`${ANSWER_FLAGS[error.field] ?? error.field} ${error.reason}`);
     }
-    const urlEnv = studioExecute.connectionEnv ?? "DATABASE_URL";
-    return `  studio: {
-    execute: {
-      enabled: true,
-      provider: ${tsString(provider)},
-      databaseUrl: env(${tsString(urlEnv)}),
-    },
-  },`;
-}
-export function renderInitConfig(answers) {
-    const sections = [
-        aiScaffold(answers).source,
-        renderIntrospectionSection(answers),
-        renderRagSection(answers),
-    ];
-    const studio = renderStudioSection(answers);
-    if (studio)
-        sections.push(studio);
-    return `import { defineConfig, env, type AskDbConfig } from "@askdb/config";
-
-export default defineConfig({
-${sections.join("\n")}
-} satisfies AskDbConfig);
-`;
 }
 export function resolveDefaultInitAnswers(overrides = {}) {
     const database = overrides.database ?? "postgres";
@@ -203,7 +105,9 @@ export function resolveDefaultInitAnswers(overrides = {}) {
         studioExecute = {
             enabled: true,
             provider: execProvider,
-            connectionEnv: overrides.studioExecuteConnectionEnv ?? (execProvider === "sqlite" ? undefined : "DATABASE_URL"),
+            // On the introspection engine, execute reads the same connection env var, as the wizard does (#777).
+            connectionEnv: overrides.studioExecuteConnectionEnv ??
+                (execProvider === "sqlite" ? undefined : execProvider === database ? connectionEnv : "DATABASE_URL"),
             sqliteFile: overrides.studioExecuteSqliteFile ?? (execProvider === "sqlite" ? overrides.sqliteFile : undefined),
         };
     }
@@ -224,94 +128,7 @@ export function resolveDefaultInitAnswers(overrides = {}) {
         studioExecute,
     };
 }
-/** Package maps — names come from an allowlist, not from user input */
-const DB_DRIVER_PACKAGES = {
-    postgres: "pg",
-    mysql: "mysql2",
-    sqlite: "better-sqlite3",
-    sqlserver: "mssql",
-};
-export function buildInitInstallPlan(answers, specs) {
-    const packages = [
-        `@askdb/config@${specs.configSpec}`,
-    ];
-    const labels = ["@askdb/config"];
-    const allowBuilds = [];
-    // `@askdb/prisma` is an optional peer of askdb (#259). It depends on Prisma, whose
-    // `@prisma/engines` postinstall pnpm 11 refuses to run until it's approved, and then
-    // exits 1. A Prisma project approves it anyway, so the install does it here.
-    // Studio's guided setup does the same (`apps/studio/src/setup.ts`).
-    if (answers.database === "prisma") {
-        packages.push(`@askdb/prisma@${specs.prismaSpec}`);
-        labels.push("@askdb/prisma");
-        allowBuilds.push(...PRISMA_BUILD_APPROVALS);
-    }
-    const driversNeeded = new Set();
-    // Live DB driver for introspection
-    if (answers.database !== "prisma") {
-        driversNeeded.add(answers.database);
-    }
-    // Live DB driver for Studio execute
-    if (answers.studioExecute.enabled) {
-        driversNeeded.add(answers.studioExecute.provider);
-    }
-    for (const db of driversNeeded) {
-        const pkg = DB_DRIVER_PACKAGES[db];
-        if (pkg) {
-            packages.push(pkg);
-            labels.push(pkg);
-        }
-    }
-    return { packages, labels, allowBuilds };
-}
-// ---------------------------------------------------------------------------
-// Package manager detection
-// ---------------------------------------------------------------------------
 const require = createRequire(import.meta.url);
-/** Walk upward from `startDir` to find a directory containing `package.json`. */
-export function findNearestPackageJsonDir(startDir) {
-    let dir = resolve(startDir);
-    for (let i = 0; i < 40; i += 1) {
-        if (existsSync(join(dir, "package.json")))
-            return dir;
-        const parent = dirname(dir);
-        if (parent === dir)
-            return undefined;
-        dir = parent;
-    }
-    return undefined;
-}
-/** Monorepo / workspace root — avoid mutating root `package.json` from `askdb init`. */
-export function isLikelyWorkspaceRoot(packageDir) {
-    if (existsSync(join(packageDir, "pnpm-workspace.yaml")) || existsSync(join(packageDir, "pnpm-workspace.yml"))) {
-        return true;
-    }
-    try {
-        const pkg = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
-        return pkg.workspaces !== undefined && pkg.workspaces !== null;
-    }
-    catch {
-        return false;
-    }
-}
-export function detectPackageManager(packageDir) {
-    let dir = packageDir;
-    for (let i = 0; i < 40; i += 1) {
-        if (existsSync(join(dir, "pnpm-lock.yaml")))
-            return "pnpm";
-        if (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))
-            return "bun";
-        if (existsSync(join(dir, "yarn.lock")))
-            return "yarn";
-        if (existsSync(join(dir, "package-lock.json")))
-            return "npm";
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return "npm";
-}
 /**
  * The versions `askdb init` installs: `@askdb/config` and `@askdb/prisma` at the versions
  * this CLI was built with. Published, those are its `@askdb/config` dependency and the floor
@@ -342,196 +159,156 @@ function builtWithVersion(packageName, declared) {
 }
 function defaultInstaller(pm, packageDir, packages, allowBuilds) {
     const env = { ...process.env, CI: process.env.CI ?? "true" };
-    const win = process.platform === "win32";
-    const cmd = win ? { pnpm: "pnpm.CMD", yarn: "yarn.cmd", bun: "bun.exe", npm: "npm.cmd" }[pm] : pm;
-    const r = spawnSync(cmd, installArgs(pm, packages, allowBuilds), { cwd: packageDir, stdio: "inherit", env, shell: false });
+    const { command, args, shell } = packageManagerSpawnSpec(pm, packageManagerAddArgs(pm, packages, allowBuilds));
+    const r = spawnSync(command, args, { cwd: packageDir, stdio: "inherit", env, shell });
     return r.status === 0;
 }
-function formatManualInstallCommand(pm, packages, allowBuilds) {
-    return [pm, ...installArgs(pm, packages, allowBuilds)].join(" ");
-}
-/**
- * The build approvals to pass `pm` in `packageDir`: `allowBuilds`, or none for a pnpm older
- * than 10.4.0, whose `add` rejects `--allow-build` (pnpm 9 runs install scripts, and 10.0 to
- * 10.3 skip unapproved ones without failing). A pnpm whose version can't be read keeps them.
- * Studio's setup applies the same rule (`apps/studio/src/package-manager.ts`).
- */
-function supportedBuildApprovals(pm, packageDir, allowBuilds) {
-    if (pm !== "pnpm" || allowBuilds.length === 0)
-        return allowBuilds;
-    const version = spawnSync("pnpm", ["--version"], {
-        cwd: packageDir,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-        // Windows runs pnpm through its `.cmd` shim, which needs a shell; the arguments are fixed.
-        shell: process.platform === "win32",
-        timeout: 15_000,
-    });
-    const match = version.status === 0 ? /^(\d+)\.(\d+)\./.exec(version.stdout.trim()) : null;
-    if (!match)
-        return allowBuilds;
-    const [major, minor] = [Number(match[1]), Number(match[2])];
-    return major > 10 || (major === 10 && minor >= 4) ? allowBuilds : [];
-}
-/**
- * The add command's arguments. Build approvals apply to pnpm only: npm and Yarn run install
- * scripts, and Bun skips untrusted ones without failing. Mirrors Studio's
- * `packageManagerAddArgs` (`apps/studio/src/package-manager.ts`); change both together.
- */
-function installArgs(pm, packages, allowBuilds) {
-    switch (pm) {
-        case "pnpm":
-            return ["add", ...allowBuilds.map((name) => `--allow-build=${name}`), ...packages];
-        case "yarn":
-        case "bun":
-            return ["add", ...packages];
-        default:
-            return ["install", "--save", ...packages];
-    }
-}
 const VALID_DATABASES = ["postgres", "mysql", "sqlite", "sqlserver", "prisma"];
-const VALID_RAG_STORES = ["file", "memory", "pgvector"];
-function parseOptions(argv) {
-    const opts = {
-        force: false,
-        path: DEFAULT_CONFIG_PATH,
-        skipInstall: false,
-        yes: false,
-        interactive: undefined,
-        noInteractive: false,
-    };
-    for (let i = 0; i < argv.length; i += 1) {
-        const arg = argv[i];
-        switch (arg) {
-            case "--force":
-            case "-f":
-                opts.force = true;
-                break;
-            case "--skip-install":
-                opts.skipInstall = true;
-                break;
-            case "--yes":
-            case "-y":
-                opts.yes = true;
-                break;
-            case "--interactive":
-                opts.interactive = true;
-                break;
-            case "--no-interactive":
-                opts.noInteractive = true;
-                break;
-            case "--studio-execute":
-                opts.studioExecute = true;
-                break;
-            case "--no-studio-execute":
-                opts.studioExecute = false;
-                break;
-            case "--path": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.path = value;
-                break;
-            }
-            case "--database": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                if (!VALID_DATABASES.includes(value)) {
-                    throw new Error(`${arg}: invalid value "${value}". Allowed: ${VALID_DATABASES.join(", ")}.`);
-                }
-                opts.database = value;
-                break;
-            }
-            case "--connection-env": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.connectionEnv = value;
-                break;
-            }
-            case "--sqlite-file": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.sqliteFile = value;
-                break;
-            }
-            case "--prisma-schema": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.prismaSchema = value;
-                break;
-            }
-            case "--schema-out": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.schemaOut = value;
-                break;
-            }
-            case "--ai-provider": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                if (!VALID_AI_PROVIDERS.includes(value)) {
-                    throw new Error(`${arg}: invalid value "${value}". Allowed: ${VALID_AI_PROVIDERS.join(", ")}.`);
-                }
-                opts.aiProvider = value;
-                break;
-            }
-            case "--ai-key-env": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.aiKeyEnv = value;
-                break;
-            }
-            case "--ai-model-env": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.aiModelEnv = value;
-                break;
-            }
-            case "--rag-store": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                if (!VALID_RAG_STORES.includes(value)) {
-                    throw new Error(`${arg}: invalid value "${value}". Allowed: ${VALID_RAG_STORES.join(", ")}.`);
-                }
-                opts.ragStore = value;
-                break;
+/** A flag that takes one of `allowed`; the error repeats a bad value only when it's `showable`. */
+function oneOf(flag, allowed, value) {
+    if (allowed.includes(value))
+        return value;
+    const got = showable(value) ? ` "${value}"` : "";
+    throw new Error(`${flag}: invalid value${got}. Allowed: ${allowed.join(", ")}.`);
+}
+/** Every flag `askdb init` accepts, for the parser and the help. */
+const INIT_FLAGS = [
+    { names: ["-y", "--yes"], help: "Accept defaults without prompts.", apply: (opts) => (opts.yes = true) },
+    {
+        names: ["--interactive"],
+        help: "Force wizard mode; errors if stdin/stdout are not TTYs.",
+        apply: (opts) => (opts.interactive = true),
+    },
+    { names: ["--no-interactive"], help: "Never prompt; use defaults or flags.", apply: (opts) => (opts.noInteractive = true) },
+    {
+        names: ["--path"],
+        value: "<file>",
+        help: `Write the config to this path. Default: ${DEFAULT_CONFIG_PATH}.`,
+        apply: (opts, value) => (opts.path = value),
+    },
+    { names: ["-f", "--force"], help: "Overwrite an existing file.", apply: (opts) => (opts.force = true) },
+    {
+        names: ["--skip-install"],
+        help: "Only write the file; do not install packages.",
+        apply: (opts) => (opts.skipInstall = true),
+    },
+    {
+        names: ["--database"],
+        value: "<db>",
+        group: "Database options",
+        help: `${VALID_DATABASES.join("|")} (default: postgres)`,
+        apply: (opts, value) => (opts.database = oneOf("--database", VALID_DATABASES, value)),
+    },
+    {
+        names: ["--connection-env"],
+        value: "<name>",
+        group: "Database options",
+        help: "Env var name for connection URL",
+        apply: (opts, value) => (opts.connectionEnv = value),
+    },
+    {
+        names: ["--sqlite-file"],
+        value: "<path-or-env>",
+        group: "Database options",
+        help: "SQLite file path, or an UPPER_SNAKE_CASE env var name",
+        apply: (opts, value) => (opts.sqliteFile = value),
+    },
+    {
+        names: ["--prisma-schema"],
+        value: "<path>",
+        group: "Database options",
+        help: "Path to schema.prisma",
+        apply: (opts, value) => (opts.prismaSchema = value),
+    },
+    {
+        names: ["--schema-out"],
+        value: "<dir>",
+        group: "Database options",
+        help: "Schema output directory (default: ./askdb)",
+        apply: (opts, value) => (opts.schemaOut = value),
+    },
+    {
+        names: ["--ai-provider"],
+        value: "<name>",
+        group: "AI options",
+        help: `${VALID_AI_PROVIDERS.join("|")} (default: openai)`,
+        apply: (opts, value) => (opts.aiProvider = oneOf("--ai-provider", VALID_AI_PROVIDERS, value)),
+    },
+    {
+        names: ["--ai-key-env"],
+        value: "<name>",
+        group: "AI options",
+        help: "Env var name for API key",
+        apply: (opts, value) => (opts.aiKeyEnv = value),
+    },
+    {
+        names: ["--ai-model-env"],
+        value: "<name>",
+        group: "AI options",
+        help: "Env var name for model override",
+        apply: (opts, value) => (opts.aiModelEnv = value),
+    },
+    {
+        names: ["--rag-store"],
+        value: "<name>",
+        group: "RAG options",
+        help: `${ASKDB_RAG_STORES.join("|")} (default: file)`,
+        apply: (opts, value) => (opts.ragStore = oneOf("--rag-store", ASKDB_RAG_STORES, value)),
+    },
+    {
+        names: ["--pgvector-env"],
+        value: "<name>",
+        group: "RAG options",
+        help: "Env var name for pgvector URL",
+        apply: (opts, value) => (opts.pgvectorEnv = value),
+    },
+    {
+        names: ["--studio-execute"],
+        group: "Studio options",
+        help: "Enable Studio execute (default: off)",
+        apply: (opts) => (opts.studioExecute = true),
+    },
+    {
+        names: ["--no-studio-execute"],
+        group: "Studio options",
+        help: "Disable Studio execute",
+        apply: (opts) => (opts.studioExecute = false),
+    },
+];
+/** `askdb init`, installing packages with `installer`. It never reads askdb.config. */
+export function initCommand(installer = defaultInstaller) {
+    return {
+        name: "init",
+        summary: "Create askdb.config.ts tailored to your database and AI provider",
+        usage: [
+            "askdb init                    Start wizard in a TTY, or use defaults in CI",
+            "askdb init --yes              Accept defaults without prompts",
+            "askdb init --no-interactive   Same as --yes",
+            "askdb init --force            Overwrite an existing askdb.config.ts",
+            "askdb init --path <file>      Write config to a custom file path",
+            "askdb init --skip-install     Only write the file; do not install packages",
+        ],
+        flags: INIT_FLAGS,
+        initial: () => ({
+            force: false,
+            path: DEFAULT_CONFIG_PATH,
+            skipInstall: false,
+            yes: false,
+            interactive: undefined,
+            noInteractive: false,
+        }),
+        check(opts) {
+            if (opts.yes && opts.interactive) {
+                throw new Error("--yes and --interactive cannot be used together.");
             }
-            case "--pgvector-env": {
-                const value = argv[++i];
-                if (!value || value.startsWith("--"))
-                    throw new Error(`${arg} requires a value.`);
-                opts.pgvectorEnv = value;
-                break;
+            if (opts.interactive && opts.noInteractive) {
+                throw new Error("--interactive and --no-interactive cannot be used together.");
             }
-            case "--help":
-            case "-h":
-                opts.path = "--help";
-                return opts;
-            default:
-                throw new Error(`Unknown option: ${arg}`);
-        }
-    }
-    // Conflict checks
-    if (opts.yes && opts.interactive) {
-        throw new Error("--yes and --interactive cannot be used together.");
-    }
-    if (opts.interactive && opts.noInteractive) {
-        throw new Error("--interactive and --no-interactive cannot be used together.");
-    }
-    return opts;
+        },
+        needsConfig: () => false,
+        run: (opts) => runInit(opts, installer),
+    };
 }
-// ---------------------------------------------------------------------------
-// TTY wizard
-// ---------------------------------------------------------------------------
 function validatePath(value) {
     if (!value.trim())
         return "Cannot be empty.";
@@ -671,9 +448,6 @@ export async function runWizard(prompter) {
         studioExecute,
     };
 }
-// ---------------------------------------------------------------------------
-// Real Inquirer prompter
-// ---------------------------------------------------------------------------
 async function buildInquirerPrompter() {
     const { select, input, confirm } = await import("@inquirer/prompts");
     return {
@@ -682,79 +456,6 @@ async function buildInquirerPrompter() {
         confirm: (opts) => confirm({ message: opts.message, default: opts.default }),
     };
 }
-// ---------------------------------------------------------------------------
-// Next steps printer
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// .env.example generation
-// ---------------------------------------------------------------------------
-const DB_URL_PLACEHOLDER = {
-    postgres: "postgresql://<USERNAME>:<PASSWORD>@<DATABASE_HOST>:<DATABASE_PORT>/<DATABASE_NAME>",
-    mysql: "mysql://<USERNAME>:<PASSWORD>@<DATABASE_HOST>:<DATABASE_PORT>/<DATABASE_NAME>",
-    sqlserver: "Data Source=<DATABASE_HOST>,<DATABASE_PORT>;Initial Catalog=<DATABASE_NAME>;User ID=<USERNAME>;Password=<PASSWORD>;Trust Server Certificate=True;Authentication=SqlPassword;",
-};
-/**
- * The database-side env vars the generated config reads (the introspection URL,
- * SQLite file paths, the pgvector URL, and Studio execute's URL), each once.
- * Names fall back to the same defaults the renderers above use, so
- * `.env.example` and the printed variable list match the config.
- */
-function databaseEnvVars(answers) {
-    const { database, studioExecute } = answers;
-    const vars = new Map();
-    const add = (envVar) => {
-        if (!vars.has(envVar.name))
-            vars.set(envVar.name, envVar);
-    };
-    if (database !== "sqlite" && database !== "prisma") {
-        add({ name: answers.connectionEnv ?? "DATABASE_URL", placeholder: DB_URL_PLACEHOLDER[database] ?? "" });
-    }
-    const sqliteFileEnvs = [
-        database === "sqlite" ? sqliteFileEnv(answers.sqliteFile) : undefined,
-        studioExecute.enabled && studioExecute.provider === "sqlite" ? sqliteFileEnv(studioExecute.sqliteFile) : undefined,
-    ];
-    for (const name of sqliteFileEnvs) {
-        if (name)
-            add({ name, placeholder: "", purpose: "SQLite database file path" });
-    }
-    if (answers.ragStore === "pgvector") {
-        add({ name: answers.pgvectorEnv ?? "ASKDB_PGVECTOR_URL", placeholder: DB_URL_PLACEHOLDER.postgres ?? "" });
-    }
-    if (studioExecute.enabled && studioExecute.provider !== "sqlite") {
-        add({
-            name: studioExecute.connectionEnv ?? "DATABASE_URL",
-            placeholder: DB_URL_PLACEHOLDER[studioExecute.provider] ?? "",
-        });
-    }
-    return [...vars.values()];
-}
-function buildEnvExample(answers) {
-    const lines = [
-        "# AskDB environment — copy to .env and fill in real values.",
-        "# .env is read by the CLI, Studio, and the HTTP API; never commit it.",
-        "",
-    ];
-    for (const envVar of databaseEnvVars(answers)) {
-        if (envVar.purpose)
-            lines.push(`# ${envVar.purpose}`);
-        lines.push(`${envVar.name}=${envVar.placeholder}`);
-    }
-    for (const envVar of aiScaffold(answers).envVars) {
-        lines.push(`# ${envVar.purpose}`);
-        lines.push(`${envVar.name}=`);
-    }
-    lines.push("");
-    return lines.join("\n");
-}
-/** Env var NAMES the generated config references — conventional defaults, not values. */
-function collectEnvVarNames(answers) {
-    const names = new Set();
-    for (const envVar of aiScaffold(answers).envVars)
-        names.add(envVar.name);
-    for (const envVar of databaseEnvVars(answers))
-        names.add(envVar.name);
-    return Array.from(names);
-}
 function printNextSteps(answers) {
     const lines = ["\nNext steps:"];
     lines.push("  1. Copy .env.example → .env and fill in your credentials.");
@@ -771,24 +472,10 @@ function printNextSteps(answers) {
     lines.push(`  ${answers.studioExecute.enabled ? "4" : "3"}. Ask a question:  askdb ask --question "Which customers signed up last week?"`);
     process.stdout.write(lines.join("\n") + "\n");
 }
-// ---------------------------------------------------------------------------
-// Main entry point
-// ---------------------------------------------------------------------------
-export async function runInitCli(argv, _installer) {
-    const installer = _installer ?? defaultInstaller;
-    let opts;
-    try {
-        opts = parseOptions(argv);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        process.stderr.write(`${msg}\n`);
-        return 1;
-    }
-    if (opts.path === "--help") {
-        printHelp();
-        return 0;
-    }
+export async function runInitCli(argv, installer) {
+    return runCommand(initCommand(installer), argv);
+}
+async function runInit(opts, installer) {
     const configTarget = resolve(process.cwd(), opts.path);
     if (existsSync(configTarget) && !opts.force) {
         process.stderr.write(`Refusing to overwrite existing file:\n` +
@@ -796,7 +483,6 @@ export async function runInitCli(argv, _installer) {
             `Use \`askdb init --force\` to overwrite.\n`);
         return 1;
     }
-    // Determine interactive mode
     const isTTY = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
     const wantInteractive = opts.interactive === true || (!opts.yes && !opts.noInteractive && isTTY);
     if (opts.interactive && !isTTY) {
@@ -804,6 +490,7 @@ export async function runInitCli(argv, _installer) {
         return 1;
     }
     let answers;
+    let plan;
     if (wantInteractive) {
         let prompter;
         try {
@@ -812,24 +499,16 @@ export async function runInitCli(argv, _installer) {
         catch {
             process.stderr.write("Failed to load @inquirer/prompts. Falling back to non-interactive mode.\n");
             answers = resolveDefaultInitAnswers(optsToOverrides(opts));
-            return await finishInit(configTarget, answers, opts, installer);
+            return await finishInit(configTarget, answers, planInitScaffold(answers, resolveInitDepSpecs()), opts, installer);
         }
-        let wizardResult;
         try {
-            wizardResult = await runWizard(prompter);
+            answers = await runWizard(prompter);
         }
         catch {
             process.stderr.write("\nSetup cancelled.\n");
             return 1;
         }
-        if (!wizardResult) {
-            process.stderr.write("\nSetup cancelled.\n");
-            return 1;
-        }
-        answers = wizardResult;
-        // Summary and confirmation
-        const specs = resolveInitDepSpecs();
-        const plan = buildInitInstallPlan(answers, specs);
+        plan = planInitScaffold(answers, resolveInitDepSpecs());
         process.stdout.write("\n--- Summary ---\n");
         process.stdout.write(`  Config path:   ${configTarget}\n`);
         process.stdout.write(`  Database:      ${answers.database}\n`);
@@ -837,9 +516,10 @@ export async function runInitCli(argv, _installer) {
         process.stdout.write(`  RAG store:     ${answers.ragStore}\n`);
         process.stdout.write(`  Studio execute: ${answers.studioExecute.enabled ? `enabled (${answers.studioExecute.provider})` : "disabled"}\n`);
         if (!opts.skipInstall) {
-            process.stdout.write(`  Packages:      ${plan.labels.join(", ")}\n`);
+            const packages = packagesToInstall(plan, findNearestPackageJsonDir(process.cwd()));
+            process.stdout.write(`  Packages:      ${packages.map(packageNameOf).join(", ")}\n`);
         }
-        process.stdout.write(`  Env vars:      ${collectEnvVarNames(answers).join(", ")}\n`);
+        process.stdout.write(`  Env vars:      ${plan.envVars.map((v) => v.name).join(", ")}\n`);
         process.stdout.write('                 (defaults — rename via `env("...")` in askdb.config.ts if you\'d like)\n');
         process.stdout.write("---------------\n\n");
         let confirmed;
@@ -857,8 +537,42 @@ export async function runInitCli(argv, _installer) {
     }
     else {
         answers = resolveDefaultInitAnswers(optsToOverrides(opts));
+        plan = planInitScaffold(answers, resolveInitDepSpecs());
+    }
+    return await finishInit(configTarget, answers, plan, opts, installer);
+}
+/** `@askdb/prisma` from `@askdb/prisma@1.0.0`, `pg` from `pg`. */
+function packageNameOf(spec) {
+    const at = spec.indexOf("@", 1);
+    return at === -1 ? spec : spec.slice(0, at);
+}
+/**
+ * The plan's packages to install in `pkgRoot`. AskDB's own packages always install, at the
+ * versions this CLI pins. Any other package (a driver, or `ai` and `zod` for Prisma) installs
+ * only when the project's `package.json` doesn't list it yet, so `init` never moves a range
+ * the project already chose, such as `ai@^6`. With no project, or at a workspace root, where
+ * `init` only prints the command for another package, every package is listed.
+ */
+function packagesToInstall(plan, pkgRoot) {
+    const listed = pkgRoot && !isLikelyWorkspaceRoot(pkgRoot) ? listedDependencies(pkgRoot) : new Set();
+    return plan.install.packages.filter((spec) => {
+        const name = packageNameOf(spec);
+        return name.startsWith("@askdb/") || !listed.has(name);
+    });
+}
+/** Every package `dir/package.json` lists as a dependency of any kind. */
+function listedDependencies(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        const fields = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+        return new Set(fields.flatMap((field) => {
+            const deps = pkg[field];
+            return deps !== null && typeof deps === "object" ? Object.keys(deps) : [];
+        }));
+    }
+    catch {
+        return new Set();
     }
-    return await finishInit(configTarget, answers, opts, installer);
 }
 function optsToOverrides(opts) {
     return {
@@ -875,21 +589,19 @@ function optsToOverrides(opts) {
         studioExecute: opts.studioExecute,
     };
 }
-async function finishInit(configTarget, answers, opts, installer) {
-    const configContent = renderInitConfig(answers);
+async function finishInit(configTarget, answers, plan, opts, installer) {
     try {
-        writeFileSync(configTarget, configContent, { encoding: "utf8" });
+        writeFileSync(configTarget, plan.configSource, { encoding: "utf8" });
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        process.stderr.write(`Failed to write config: ${msg}\n`);
+        process.stderr.write(`Failed to write config: ${errorMessage(e)}\n`);
         return 1;
     }
     process.stdout.write(`Wrote:\n  - ${configTarget}\n`);
     const envExamplePath = join(dirname(configTarget), ".env.example");
     if (!existsSync(envExamplePath)) {
         try {
-            writeFileSync(envExamplePath, buildEnvExample(answers), { encoding: "utf8" });
+            writeFileSync(envExamplePath, plan.envExample, { encoding: "utf8" });
             process.stdout.write(`  - ${envExamplePath}\n`);
         }
         catch {
@@ -898,67 +610,37 @@ async function finishInit(configTarget, answers, opts, installer) {
     }
     if (!opts.skipInstall) {
         const pkgRoot = findNearestPackageJsonDir(process.cwd());
-        const specs = resolveInitDepSpecs();
-        const plan = buildInitInstallPlan(answers, specs);
+        const packages = packagesToInstall(plan, pkgRoot);
+        const { allowBuilds } = plan.install;
+        // The manager comes from the project's lockfile or package.json, else from whoever
+        // ran init (`pnpm dlx`, `npx`, …); with no package.json, from the current directory.
+        const pmDir = pkgRoot ?? process.cwd();
+        const pm = detectPackageManager(pmDir);
+        const approvedBuilds = supportedBuildApprovals(pm, pmDir, allowBuilds);
+        const installCommand = formatInstallCommand(pm, packages, approvedBuilds);
         if (!pkgRoot) {
             process.stdout.write("\nNo package.json found in this directory or any parent directory.\n" +
                 "Install the template imports yourself (from a project with a package.json):\n" +
-                `  npm install --save ${plan.packages.join(" ")}\n\n`);
+                `  ${installCommand}\n\n`);
         }
         else if (isLikelyWorkspaceRoot(pkgRoot)) {
             process.stdout.write("\nSkipped automatic dependency install (workspace / monorepo root).\n" +
                 "Add these to the package that will load this config (or run `askdb init` from that package directory):\n" +
-                `  npm install --save ${plan.packages.join(" ")}\n\n`);
+                `  ${installCommand}\n\n`);
         }
         else {
-            const pm = detectPackageManager(pkgRoot);
-            const approvedBuilds = supportedBuildApprovals(pm, pkgRoot, plan.allowBuilds);
             process.stdout.write(`\nInstalling dependencies with ${pm} in ${pkgRoot} …\n`);
-            const ok = installer(pm, pkgRoot, plan.packages, approvedBuilds);
+            const ok = installer(pm, pkgRoot, packages, approvedBuilds);
             if (!ok) {
                 process.stderr.write("Dependency install failed. The config file was written, but packages are not installed yet.\n" +
                     `  cd ${pkgRoot}\n` +
-                    `  ${formatManualInstallCommand(pm, plan.packages, approvedBuilds)}\n`);
+                    `  ${installCommand}\n`);
                 return 1;
             }
-            process.stdout.write(`Installed: ${plan.labels.join(", ")}.\n`);
+            process.stdout.write(`Installed: ${packages.map(packageNameOf).join(", ")}.\n`);
         }
     }
     printNextSteps(answers);
     return 0;
 }
-function printHelp() {
-    process.stdout.write([
-        "askdb init - Create askdb.config.ts tailored to your database and AI provider",
-        "",
-        "Usage:",
-        "  askdb init                    Start wizard in a TTY, or use defaults in CI",
-        "  askdb init --yes              Accept defaults without prompts",
-        "  askdb init --no-interactive   Same as --yes",
-        "  askdb init --force            Overwrite an existing askdb.config.ts",
-        "  askdb init --path <file>      Write config to a custom file path",
-        "  askdb init --skip-install     Only write the file; do not install packages",
-        "",
-        "Database options:",
-        "  --database <db>               postgres|mysql|sqlite|sqlserver|prisma (default: postgres)",
-        "  --connection-env <name>       Env var name for connection URL",
-        "  --sqlite-file <path-or-env>   SQLite file path, or an UPPER_SNAKE_CASE env var name",
-        "  --prisma-schema <path>        Path to schema.prisma",
-        "  --schema-out <dir>            Schema output directory (default: ./askdb)",
-        "",
-        "AI options:",
-        `  --ai-provider <name>          ${VALID_AI_PROVIDERS.join("|")} (default: openai)`,
-        "  --ai-key-env <name>           Env var name for API key",
-        "  --ai-model-env <name>         Env var name for model override",
-        "",
-        "RAG options:",
-        "  --rag-store <name>            file|memory|pgvector (default: file)",
-        "  --pgvector-env <name>         Env var name for pgvector URL",
-        "",
-        "Studio options:",
-        "  --studio-execute              Enable Studio execute (default: off)",
-        "  --no-studio-execute           Disable Studio execute",
-        "",
-    ].join("\n"));
-}
 //# sourceMappingURL=init.js.map