@askdb/config 1.0.0-beta.17 → 1.0.0-beta.18

package/dist/runtime-types.d.ts

@@ -127,7 +127,7 @@ export type AskDbRuntimeStudioConfig = {
         /**
          * Resolved execute provider. Falls back to the active introspection provider when it
          * is a live engine (`postgres`, `mysql`, `sqlite`, `sqlserver`), then defaults to
-         * `"postgres"` for backward compatibility.
+         * `"postgres"`.
          */
         provider: AskDbStudioExecuteProvider;
         /** Connection URL used by the Studio playground query runner for network databases. */

package/dist/scaffold/ai.d.ts

@@ -25,6 +25,9 @@ export type AskDbAiConfigScaffold = {
  *
  * Every value is emitted as a JSON string literal: the generated file is
  * executed when the config loads, so a raw quote in a name must not inject code.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change it (ADR 0030).
  */
 export declare function renderAskDbAiConfigScaffold(input: AskDbAiConfigScaffoldInput): AskDbAiConfigScaffold;
 //# sourceMappingURL=ai.d.ts.map

package/dist/scaffold/ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/scaffold/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oHAAoH;IACpH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC,CAAC;AAYF;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,CAmCpG"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/scaffold/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oHAAoH;IACpH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC,CAAC;AAYF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,CAmCpG"}

package/dist/scaffold/ai.js

@@ -14,6 +14,9 @@ const AZURE_RESOURCE_NAME_ENV = "AZURE_RESOURCE_NAME";
  *
  * Every value is emitted as a JSON string literal: the generated file is
  * executed when the config loads, so a raw quote in a name must not inject code.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change it (ADR 0030).
  */
 export function renderAskDbAiConfigScaffold(input) {
     const { provider, keyEnv, modelEnv } = input;

package/dist/scaffold/ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../src/scaffold/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA0B,MAAM,iBAAiB,CAAC;AAwB7E,SAAS,YAAY,CAAC,QAAgB;IACpC,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAiC;IAC3E,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC7C,8EAA8E;IAC9E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,OAAO,GAA0B,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,UAAU,EAAE,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3D,oGAAoG;IACpG,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,iBAAiB,EAAE,CAAC,CAAC;QACxE,QAAQ,GAAG;;mBAEI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;OACpC,CAAC;IACN,CAAC;IACD,gFAAgF;IAChF,yEAAyE;IACzE,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,kFAAkF;SAC5F,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG;gBACD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;;QAEhC,QAAQ;EACd,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;QAE9C,QAAQ;KACX,CAAC;IACJ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../src/scaffold/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA0B,MAAM,iBAAiB,CAAC;AAwB7E,SAAS,YAAY,CAAC,QAAgB;IACpC,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAiC;IAC3E,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC7C,8EAA8E;IAC9E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,OAAO,GAA0B,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,UAAU,EAAE,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3D,oGAAoG;IACpG,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,iBAAiB,EAAE,CAAC,CAAC;QACxE,QAAQ,GAAG;;mBAEI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;OACpC,CAAC;IACN,CAAC;IACD,gFAAgF;IAChF,yEAAyE;IACzE,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,kFAAkF;SAC5F,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG;gBACD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;;QAEhC,QAAQ;EACd,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;QAE9C,QAAQ;KACX,CAAC;IACJ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/scaffold/index.d.ts

@@ -1,8 +1,17 @@
 /**
- * `@askdb/config/scaffold`: helpers for tools that write a new `askdb.config.ts`
- * (`askdb init`, Studio's setup wizard). Kept off the main entry, which user
- * configs import, so tooling can change without touching the config API.
+ * `@askdb/config/scaffold`: helpers for tools that set up a project and write a new
+ * `askdb.config.ts` (`askdb init`, Studio's setup wizard): the planner, which turns a
+ * project's answers into its config, `.env.example` and installs, and the package-manager
+ * helpers that run the installs. Kept off the main entry, which user configs import, so
+ * tooling can change without touching the config API.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change these exports (ADR 0030).
  */
 export { renderAskDbAiConfigScaffold } from "./ai.js";
 export type { AskDbAiConfigScaffold, AskDbAiConfigScaffoldInput, AskDbScaffoldEnvVar } from "./ai.js";
+export { AskDbScaffoldInputError, isAskDbScaffoldEnvName, planAskDbScaffold } from "./plan.js";
+export type { AskDbScaffoldAnswers, AskDbScaffoldPlan, ScaffoldValue } from "./plan.js";
+export { detectPackageManager, findNearestPackageJsonDir, formatInstallCommand, isLikelyWorkspaceRoot, lockfilePackageManager, packageManagerAddArgs, packageManagerSpawnSpec, supportedBuildApprovals, } from "./package-manager.js";
+export type { PackageManager, PackageManagerSpawnSpec } from "./package-manager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scaffold/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACtG,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/F,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/scaffold/index.js

@@ -1,7 +1,14 @@
 /**
- * `@askdb/config/scaffold`: helpers for tools that write a new `askdb.config.ts`
- * (`askdb init`, Studio's setup wizard). Kept off the main entry, which user
- * configs import, so tooling can change without touching the config API.
+ * `@askdb/config/scaffold`: helpers for tools that set up a project and write a new
+ * `askdb.config.ts` (`askdb init`, Studio's setup wizard): the planner, which turns a
+ * project's answers into its config, `.env.example` and installs, and the package-manager
+ * helpers that run the installs. Kept off the main entry, which user configs import, so
+ * tooling can change without touching the config API.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change these exports (ADR 0030).
  */
 export { renderAskDbAiConfigScaffold } from "./ai.js";
+export { AskDbScaffoldInputError, isAskDbScaffoldEnvName, planAskDbScaffold } from "./plan.js";
+export { detectPackageManager, findNearestPackageJsonDir, formatInstallCommand, isLikelyWorkspaceRoot, lockfilePackageManager, packageManagerAddArgs, packageManagerSpawnSpec, supportedBuildApprovals, } from "./package-manager.js";
 //# sourceMappingURL=index.js.map

package/dist/scaffold/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAEtD,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE/F,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC"}

package/dist/scaffold/package-manager.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Package-manager helpers for the tools that set up a project: `askdb init` and
+ * Studio's setup wizard and execute-driver install. One copy, so the two front
+ * ends detect, format and spawn the same way.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change these exports (ADR 0030).
+ *
+ * Only allowlisted package names ever reach these helpers, never user- or
+ * browser-supplied strings, but {@link packageManagerSpawnSpec} re-checks every
+ * argument anyway because Windows needs `shell: true` (see below).
+ */
+/** @experimental See the module note. */
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+/**
+ * The nearest directory at or above `startDir` that holds a `package.json`.
+ *
+ * @experimental See the module note.
+ */
+export declare function findNearestPackageJsonDir(startDir: string): string | undefined;
+/**
+ * Whether `packageDir` looks like a monorepo or workspace root (a `pnpm-workspace.yaml`,
+ * or a `workspaces` field), whose `package.json` setup tools leave alone.
+ *
+ * @experimental See the module note.
+ */
+export declare function isLikelyWorkspaceRoot(packageDir: string): boolean;
+/**
+ * The package manager implied by a lockfile directly inside `dir`, if any.
+ *
+ * @experimental See the module note.
+ */
+export declare function lockfilePackageManager(dir: string): PackageManager | null;
+/**
+ * The package manager to install with in `packageDir`, from the first of these that
+ * names one:
+ *
+ * 1. a lockfile in `packageDir` or a parent (pnpm, then Bun, Yarn, npm in one directory);
+ * 2. the nearest `package.json`, walking up, that declares a manager: its `packageManager`
+ *    field (Corepack's `pnpm@11.28.10`), then `devEngines.packageManager` (`{ name }` or a
+ *    list of them; `pnpm init` writes it);
+ * 3. `npm_config_user_agent` in `env`, which `pnpm dlx`, `yarn dlx`, `npx` and `bunx` set;
+ * 4. npm.
+ *
+ * An existing lockfile wins, so a project's install never switches managers.
+ *
+ * @experimental See the module note.
+ */
+export declare function detectPackageManager(packageDir: string, env?: Readonly<Record<string, string | undefined>>): PackageManager;
+/**
+ * Arguments that add `packages` as dependencies with the given package manager.
+ * `allowBuilds` are dependencies whose install scripts pnpm must be told to run
+ * (`--allow-build=<name>`; pnpm 11 exits 1 on an unapproved one). npm and Yarn
+ * run install scripts, and Bun skips untrusted ones without failing, so only
+ * pnpm gets them.
+ *
+ * @experimental See the module note.
+ */
+export declare function packageManagerAddArgs(pm: PackageManager, packages: readonly string[], allowBuilds?: readonly string[]): string[];
+/**
+ * The build approvals to pass `pm` in `dir`: `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.
+ *
+ * @experimental See the module note.
+ */
+export declare function supportedBuildApprovals(pm: PackageManager, dir: string, allowBuilds: readonly string[]): string[];
+/**
+ * Human-readable install command, e.g. `pnpm add pg`.
+ *
+ * @experimental See the module note.
+ */
+export declare function formatInstallCommand(pm: PackageManager, packages: readonly string[], allowBuilds?: readonly string[]): string;
+/** @experimental See the module note. */
+export type PackageManagerSpawnSpec = {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
+/**
+ * How to spawn a package manager on this platform.
+ *
+ * On Windows, package managers are `.cmd` shims, and Node refuses to spawn
+ * `.cmd`/`.bat` files without a shell (EINVAL since Node 18.20.2 / 20.12.2,
+ * CVE-2024-27980). So Windows gets `shell: true` with the bare command name.
+ * Arguments are validated against a strict allowlist pattern first, so the
+ * shell never sees anything it could interpret.
+ *
+ * @experimental See the module note.
+ */
+export declare function packageManagerSpawnSpec(pm: PackageManager, args: readonly string[], platform?: NodeJS.Platform): PackageManagerSpawnSpec;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/scaffold/package-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../../src/scaffold/package-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAK7D;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAUjE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAMzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,cAAc,CAWhB;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,MAAM,EAAE,CAIV;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAMjH;AAQD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,MAAM,CAER;AAED,yCAAyC;AACzC,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAQF;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,uBAAuB,CAUzB"}

package/dist/scaffold/package-manager.js

@@ -0,0 +1,200 @@
+/**
+ * Package-manager helpers for the tools that set up a project: `askdb init` and
+ * Studio's setup wizard and execute-driver install. One copy, so the two front
+ * ends detect, format and spawn the same way.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change these exports (ADR 0030).
+ *
+ * Only allowlisted package names ever reach these helpers, never user- or
+ * browser-supplied strings, but {@link packageManagerSpawnSpec} re-checks every
+ * argument anyway because Windows needs `shell: true` (see below).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** How far up the helpers walk looking for a `package.json` or lockfile. */
+const MAX_WALK_UP = 40;
+/**
+ * The nearest directory at or above `startDir` that holds a `package.json`.
+ *
+ * @experimental See the module note.
+ */
+export function findNearestPackageJsonDir(startDir) {
+    return ancestors(startDir).find((dir) => existsSync(join(dir, "package.json")));
+}
+/**
+ * Whether `packageDir` looks like a monorepo or workspace root (a `pnpm-workspace.yaml`,
+ * or a `workspaces` field), whose `package.json` setup tools leave alone.
+ *
+ * @experimental See the module note.
+ */
+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;
+    }
+}
+/**
+ * The package manager implied by a lockfile directly inside `dir`, if any.
+ *
+ * @experimental See the module note.
+ */
+export function lockfilePackageManager(dir) {
+    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";
+    return null;
+}
+/**
+ * The package manager to install with in `packageDir`, from the first of these that
+ * names one:
+ *
+ * 1. a lockfile in `packageDir` or a parent (pnpm, then Bun, Yarn, npm in one directory);
+ * 2. the nearest `package.json`, walking up, that declares a manager: its `packageManager`
+ *    field (Corepack's `pnpm@11.28.10`), then `devEngines.packageManager` (`{ name }` or a
+ *    list of them; `pnpm init` writes it);
+ * 3. `npm_config_user_agent` in `env`, which `pnpm dlx`, `yarn dlx`, `npx` and `bunx` set;
+ * 4. npm.
+ *
+ * An existing lockfile wins, so a project's install never switches managers.
+ *
+ * @experimental See the module note.
+ */
+export function detectPackageManager(packageDir, env = process.env) {
+    const dirs = ancestors(packageDir);
+    for (const dir of dirs) {
+        const pm = lockfilePackageManager(dir);
+        if (pm)
+            return pm;
+    }
+    for (const dir of dirs) {
+        const pm = declaredPackageManager(dir);
+        if (pm)
+            return pm;
+    }
+    return knownPackageManager(env.npm_config_user_agent?.split("/")[0]) ?? "npm";
+}
+/** `dir` and its parents, nearest first, at most {@link MAX_WALK_UP} of them. */
+function ancestors(dir) {
+    const dirs = [resolve(dir)];
+    while (dirs.length < MAX_WALK_UP) {
+        const parent = dirname(dirs[dirs.length - 1]);
+        if (parent === dirs[dirs.length - 1])
+            break;
+        dirs.push(parent);
+    }
+    return dirs;
+}
+/** The manager `dir/package.json` declares in `packageManager` or `devEngines.packageManager`. */
+function declaredPackageManager(dir) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (pkg === null || typeof pkg !== "object")
+        return null;
+    if (typeof pkg.packageManager === "string") {
+        const pm = knownPackageManager(pkg.packageManager.split("@")[0]);
+        if (pm)
+            return pm;
+    }
+    const devEngine = pkg.devEngines?.packageManager;
+    for (const entry of Array.isArray(devEngine) ? devEngine : [devEngine]) {
+        const name = entry !== null && typeof entry === "object" ? entry.name : undefined;
+        const pm = knownPackageManager(name);
+        if (pm)
+            return pm;
+    }
+    return null;
+}
+function knownPackageManager(name) {
+    return name === "pnpm" || name === "npm" || name === "yarn" || name === "bun" ? name : null;
+}
+/**
+ * Arguments that add `packages` as dependencies with the given package manager.
+ * `allowBuilds` are dependencies whose install scripts pnpm must be told to run
+ * (`--allow-build=<name>`; pnpm 11 exits 1 on an unapproved one). npm and Yarn
+ * run install scripts, and Bun skips untrusted ones without failing, so only
+ * pnpm gets them.
+ *
+ * @experimental See the module note.
+ */
+export function packageManagerAddArgs(pm, packages, allowBuilds = []) {
+    if (pm === "npm")
+        return ["install", "--save", ...packages];
+    if (pm === "pnpm")
+        return ["add", ...allowBuilds.map((name) => `--allow-build=${name}`), ...packages];
+    return ["add", ...packages];
+}
+/**
+ * The build approvals to pass `pm` in `dir`: `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.
+ *
+ * @experimental See the module note.
+ */
+export function supportedBuildApprovals(pm, dir, allowBuilds) {
+    if (pm !== "pnpm" || allowBuilds.length === 0)
+        return [...allowBuilds];
+    const match = /^(\d+)\.(\d+)\./.exec(pnpmVersion(dir) ?? "");
+    if (!match)
+        return [...allowBuilds];
+    const [major, minor] = [Number(match[1]), Number(match[2])];
+    return major > 10 || (major === 10 && minor >= 4) ? [...allowBuilds] : [];
+}
+function pnpmVersion(dir) {
+    const { command, args, shell } = packageManagerSpawnSpec("pnpm", ["--version"]);
+    const result = spawnSync(command, args, { cwd: dir, encoding: "utf8", shell, stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/**
+ * Human-readable install command, e.g. `pnpm add pg`.
+ *
+ * @experimental See the module note.
+ */
+export function formatInstallCommand(pm, packages, allowBuilds = []) {
+    return [pm, ...packageManagerAddArgs(pm, packages, allowBuilds)].join(" ");
+}
+// npm package names (optionally scoped, optionally with a version/range suffix),
+// simple `--flag` arguments, and pnpm's `--allow-build=<package name>`. Nothing a
+// shell would interpret.
+const SAFE_ARG = /^(?:--[a-z][a-z-]*|--allow-build=(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*|(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-z0-9.^~<>=*_-]+)?|add|install)$/i;
+/**
+ * How to spawn a package manager on this platform.
+ *
+ * On Windows, package managers are `.cmd` shims, and Node refuses to spawn
+ * `.cmd`/`.bat` files without a shell (EINVAL since Node 18.20.2 / 20.12.2,
+ * CVE-2024-27980). So Windows gets `shell: true` with the bare command name.
+ * Arguments are validated against a strict allowlist pattern first, so the
+ * shell never sees anything it could interpret.
+ *
+ * @experimental See the module note.
+ */
+export function packageManagerSpawnSpec(pm, args, platform = process.platform) {
+    for (const arg of args) {
+        if (!SAFE_ARG.test(arg)) {
+            throw new Error(`Refusing to pass unsafe argument to ${pm}: ${JSON.stringify(arg)}`);
+        }
+    }
+    if (platform === "win32") {
+        return { command: pm, args: [...args], shell: true };
+    }
+    return { command: pm, args: [...args], shell: false };
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/scaffold/package-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.js","sourceRoot":"","sources":["../../src/scaffold/package-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKnD,4EAA4E;AAC5E,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB;IACxD,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACtD,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC;QAC9G,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAA6B,CAAC;QAC3G,OAAO,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC;IAC3D,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1F,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC;IACtD,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,MAAoD,OAAO,CAAC,GAAG;IAE/D,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,mBAAmB,CAAC,GAAG,CAAC,qBAAqB,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;AAChF,CAAC;AAED,iFAAiF;AACjF,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAAE,MAAM;QAC5C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kGAAkG;AAClG,SAAS,sBAAsB,CAAC,GAAW;IACzC,IAAI,GAAmF,CAAC;IACxF,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAe,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,EAAE,GAAG,mBAAmB,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,EAAE,cAAc,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAA4B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1G,MAAM,EAAE,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAa;IACxC,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,EAAkB,EAClB,QAA2B,EAC3B,cAAiC,EAAE;IAEnC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC5D,IAAI,EAAE,KAAK,MAAM;QAAE,OAAO,CAAC,KAAK,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;IACtG,OAAO,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAkB,EAAE,GAAW,EAAE,WAA8B;IACrG,IAAI,EAAE,KAAK,MAAM,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,OAAO,KAAK,GAAG,EAAE,IAAI,CAAC,KAAK,KAAK,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACrI,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAAkB,EAClB,QAA2B,EAC3B,cAAiC,EAAE;IAEnC,OAAO,CAAC,EAAE,EAAE,GAAG,qBAAqB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7E,CAAC;AASD,iFAAiF;AACjF,kFAAkF;AAClF,yBAAyB;AACzB,MAAM,QAAQ,GACZ,2KAA2K,CAAC;AAE9K;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,EAAkB,EAClB,IAAuB,EACvB,WAA4B,OAAO,CAAC,QAAQ;IAE5C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,uCAAuC,EAAE,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACxD,CAAC"}

package/dist/scaffold/plan.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The scaffold planner: answers about a new project in, the files and installs it needs out.
+ * `askdb init` and Studio's setup wizard both call {@link planAskDbScaffold}, so the per-engine
+ * facts (config keys, URL formats, driver packages) and the config and `.env.example` layouts
+ * live here once. Each front end keeps its own defaults, how it asks, and how files land.
+ *
+ * @experimental Tooling for `askdb init` and AskDB Studio: a minor release of
+ * `@askdb/config` may change these exports (ADR 0030).
+ */
+import { type AskDbIntrospectionProvider, type AskDbRagStore, type AskDbStudioExecuteProvider } from "../constants.js";
+import { type AskDbAiConfigScaffoldInput } from "./ai.js";
+/**
+ * A setting a config reads either as a literal path or from an env var: `{ path }` is written
+ * as a string, `{ env }` as `env("NAME")`.
+ *
+ * @experimental See the module note.
+ */
+export type ScaffoldValue = {
+    path: string;
+} | {
+    env: string;
+};
+/**
+ * What a new project uses. Env var fields take NAMES, never values. Defaults are the
+ * caller's: every field the chosen engine, store or execute provider reads must be given.
+ *
+ * @experimental See the module note.
+ */
+export type AskDbScaffoldAnswers = {
+    database: AskDbIntrospectionProvider;
+    /** Env var NAME for the connection URL. Postgres, MySQL and SQL Server. */
+    connectionEnv?: string;
+    /** The SQLite database file. SQLite only. */
+    sqliteFile?: ScaffoldValue;
+    /** Path to `schema.prisma`. Prisma only; omit to let `@askdb/prisma` find it. */
+    prismaSchemaPath?: string;
+    /** Schema artifact directory (`introspection.outputDir`). */
+    schemaOut: string;
+    ai: AskDbAiConfigScaffoldInput;
+    /** `pgvectorEnv` names the connection URL's env var, for the pgvector store. */
+    rag: {
+        store: AskDbRagStore;
+        pgvectorEnv?: string;
+    };
+    /** Turns on Studio execute against this live database. `connectionEnv` for a URL engine, `sqliteFile` for SQLite. */
+    studioExecute?: {
+        provider: AskDbStudioExecuteProvider;
+        connectionEnv?: string;
+        sqliteFile?: ScaffoldValue;
+    };
+};
+/**
+ * Everything a new project needs, ready for a front end to write and install.
+ *
+ * @experimental See the module note.
+ */
+export type AskDbScaffoldPlan = {
+    /** The `askdb.config.ts` source. */
+    configSource: string;
+    /** The `.env.example` source: a `# purpose` line above each `NAME=`, every value empty. */
+    envExample: string;
+    /** Every env var the config reads, once each, database variables first. */
+    envVars: {
+        name: string;
+        purpose: string;
+        requiredForIntrospection: boolean;
+    }[];
+    /** `packages` are `name@spec`, or a bare name for a driver at its latest version. `allowBuilds` are the builds pnpm must approve. */
+    install: {
+        packages: string[];
+        allowBuilds: string[];
+    };
+};
+/**
+ * An answer {@link planAskDbScaffold} can't use. `field` is the answer's path, such as
+ * `connectionEnv` or `studioExecute.sqliteFile`; `reason` says what's wrong without naming
+ * it, so a front end can name the field its own way (a flag, a form field).
+ *
+ * @experimental See the module note.
+ */
+export declare class AskDbScaffoldInputError extends Error {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
+/**
+ * Plans a new project's `askdb.config.ts`, `.env.example` and installs from `answers`.
+ * `versions` are the `@askdb/config` and `@askdb/prisma` specs to install, which each front
+ * end reads from its own manifest. Pure: it reads and writes nothing.
+ *
+ * Every value lands in the config as a JSON string literal, and ids that become object
+ * keys are checked against their lists: the config runs when it loads.
+ *
+ * @throws {AskDbScaffoldInputError} for an env var name that isn't `^[A-Z_][A-Z0-9_]*$`,
+ * a control character in a path, an unknown id, or a missing answer.
+ * @experimental See the module note.
+ */
+export declare function planAskDbScaffold(answers: AskDbScaffoldAnswers, versions: {
+    config: string;
+    prisma: string;
+}): AskDbScaffoldPlan;
+/**
+ * Whether `name` is an env var name the planner accepts: POSIX, uppercase
+ * (`^[A-Z_][A-Z0-9_]*$`). A leading `_` is allowed. `askdb init` uses it to tell an env
+ * var name from a path in `--sqlite-file`.
+ *
+ * @experimental See the module note.
+ */
+export declare function isAskDbScaffoldEnvName(name: string): boolean;
+//# sourceMappingURL=plan.d.ts.map

package/dist/scaffold/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/scaffold/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAKL,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAA+B,KAAK,0BAA0B,EAA4B,MAAM,SAAS,CAAC;AAEjH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,0BAA0B,CAAC;IAC/B,gFAAgF;IAChF,GAAG,EAAE;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,qHAAqH;IACrH,aAAa,CAAC,EAAE;QAAE,QAAQ,EAAE,0BAA0B,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC;CAC9G,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,wBAAwB,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAChF,qIAAqI;IACrI,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACxD,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM;CAK1B;AA0CD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3C,iBAAiB,CAUnB;AA2ID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D"}