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

package/dist/cli.js

@@ -1,312 +1,25 @@
 #!/usr/bin/env node
-import { getAskDbRuntimeConfig, isAskDbDebugEnabled } from "@askdb/config";
-import { createAiRegistry, } from "@askdb/ai";
-import { createAskDb } from "@askdb/client";
-import { AskDbError, AskDbLogEvent, SchemaParseError, formatAskDbModesV1, parseAskDbModeV1, SqlValidationError, formatSensitiveReference, loadSchema, } from "@askdb/core";
-import { Command } from "commander";
-import { runInitCli, VALID_AI_PROVIDERS } from "./init.js";
-import { runIntrospectCli } from "./introspect.js";
-import { createCliLogger, resolveCliLogLevel } from "./logger.js";
-import { MissingAskDbConfigError, requireAskDbConfig } from "./project-config.js";
-import { runRagCli } from "./rag.js";
-import { readCliVersion } from "./version.js";
-// Batteries-included surface: every built-in provider is registered, and each
-// loads its @ai-sdk/* package only when first used, so env config alone
-// selects the provider.
-const ai = createAiRegistry();
-function printCliError(error) {
-    if (error instanceof MissingAskDbConfigError) {
-        console.error(error.message);
-        return;
-    }
-    if (error instanceof SqlValidationError) {
-        console.error(`${error.name} [${error.rule}]: ${error.message}`);
-        if (error.hint) {
-            console.error(`Hint: ${error.hint}`);
-        }
-        return;
-    }
-    if (error instanceof AskDbError) {
-        console.error(`${error.name}: ${error.message}`);
-        return;
-    }
-    if (error instanceof Error) {
-        console.error(error.message);
-        return;
-    }
-    console.error(String(error));
-}
-async function runBundleCommand(args) {
-    const schemaDir = args[0];
-    const outFlag = args[1];
-    const outPath = args[2];
-    if (!schemaDir || outFlag !== "--out" || !outPath) {
-        process.stderr.write("Usage: askdb bundle <schema-dir> --out <bundle.json>\n");
-        return 1;
-    }
-    const { bundleSchemaDirectory } = await import("@askdb/enrich");
-    const { writeFileSync } = await import("node:fs");
-    const { resolve } = await import("node:path");
-    try {
-        const bundle = bundleSchemaDirectory(resolve(schemaDir));
-        writeFileSync(resolve(outPath), `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
-        process.stdout.write(`Wrote ${resolve(outPath)}\n`);
-        return 0;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`askdb bundle: ${message}\n`);
-        return 1;
-    }
-}
-async function runStudioCommand(args) {
-    // Studio owns config loading for its own startup: a missing config opens the setup wizard.
-    const { runStudioBin } = await import("@askdb/studio");
-    return runStudioBin(args);
-}
-function formatSchemaPathHint(schemaPath) {
-    return `Schema path: ${schemaPath}\nHint: Try \`fixtures/schemas/orders-users.schema/\` (v2 directory) as a known-good example.`;
-}
-function loadSchemaFromPath(schemaPath) {
-    try {
-        return loadSchema(schemaPath);
-    }
-    catch (e) {
-        const err = e;
-        const code = typeof err.code === "string" ? err.code : undefined;
-        if (code === "ENOENT") {
-            throw new AskDbError(`Schema path not found.\n${formatSchemaPathHint(schemaPath)}`, e);
-        }
-        if (code === "EACCES") {
-            throw new AskDbError(`Schema path is not readable (permission denied).\n${formatSchemaPathHint(schemaPath)}`, e);
-        }
-        if (e instanceof SchemaParseError) {
-            throw new AskDbError(`Failed to parse schema.\n${formatSchemaPathHint(schemaPath)}\nDetails: ${e.message}`, e);
-        }
-        const msg = e instanceof Error ? e.message : String(e);
-        throw new AskDbError(`Failed to load schema.\n${formatSchemaPathHint(schemaPath)}\nDetails: ${msg}`, e);
-    }
-}
-function resolveSchemaPathForAsk(optionSchema, runtime) {
-    return optionSchema ?? runtime.introspection.outputDir;
-}
-const program = new Command();
-program
-    .name("askdb")
-    .description("AskDB — natural language → validated SQL for your database")
-    .version(readCliVersion(), "-V, --version", "Print the askdb version");
-program
-    .command("init")
-    .description("Create tailored askdb.config.ts via a wizard (TTY) or flags (CI). Installs selected packages unless --skip-install.")
-    .option("-f, --force", "Overwrite an existing file", false)
-    .option("--path <path>", "Output path for askdb.config.ts", "askdb.config.ts")
-    .option("--skip-install", "Only write the file; do not install packages", false)
-    .option("-y, --yes", "Accept defaults without prompts", false)
-    .option("--interactive", "Force wizard mode; errors if stdin/stdout are not TTYs", false)
-    .option("--no-interactive", "Do not prompt; use defaults or flags")
-    .option("--database <db>", "postgres|mysql|sqlite|sqlserver|prisma")
-    .option("--connection-env <name>", "Env var name for connection URL")
-    .option("--sqlite-file <path>", "SQLite file path or env var name")
-    .option("--prisma-schema <path>", "Path to schema.prisma")
-    .option("--schema-out <dir>", "Schema output directory (default: ./askdb)")
-    .option("--ai-provider <name>", VALID_AI_PROVIDERS.join("|"))
-    .option("--ai-key-env <name>", "Env var name for AI API key")
-    .option("--ai-model-env <name>", "Env var name for model override")
-    .option("--rag-store <name>", "file|memory|pgvector (default: file)")
-    .option("--pgvector-env <name>", "Env var name for pgvector URL")
-    .option("--studio-execute", "Enable Studio execute")
-    .option("--no-studio-execute", "Disable Studio execute")
-    .action(async (opts) => {
-    const args = [];
-    if (opts.force)
-        args.push("--force");
-    if (opts.skipInstall)
-        args.push("--skip-install");
-    if (opts.yes)
-        args.push("--yes");
-    if (opts.interactive)
-        args.push("--interactive");
-    if (opts.noInteractive)
-        args.push("--no-interactive");
-    if (opts.path && opts.path !== "askdb.config.ts")
-        args.push("--path", opts.path);
-    if (opts.database)
-        args.push("--database", opts.database);
-    if (opts.connectionEnv)
-        args.push("--connection-env", opts.connectionEnv);
-    if (opts.sqliteFile)
-        args.push("--sqlite-file", opts.sqliteFile);
-    if (opts.prismaSchema)
-        args.push("--prisma-schema", opts.prismaSchema);
-    if (opts.schemaOut)
-        args.push("--schema-out", opts.schemaOut);
-    if (opts.aiProvider)
-        args.push("--ai-provider", opts.aiProvider);
-    if (opts.aiKeyEnv)
-        args.push("--ai-key-env", opts.aiKeyEnv);
-    if (opts.aiModelEnv)
-        args.push("--ai-model-env", opts.aiModelEnv);
-    if (opts.ragStore)
-        args.push("--rag-store", opts.ragStore);
-    if (opts.pgvectorEnv)
-        args.push("--pgvector-env", opts.pgvectorEnv);
-    if (opts.studioExecute === true)
-        args.push("--studio-execute");
-    if (opts.studioExecute === false)
-        args.push("--no-studio-execute");
-    process.exit(await runInitCli(args));
-});
-program
-    .command("enrich")
-    .description("Open Studio for Schema v2 enrichment (alias of `askdb studio`)")
-    .allowUnknownOption(true);
-program
-    .command("studio")
-    .description("Start the local browser UI for Schema v2 enrichment")
-    .allowUnknownOption(true);
-program
-    .command("bundle")
-    .description("Bundle a Schema v2 directory into a single JSON file")
-    .allowUnknownOption(true);
-program
-    .command("introspect")
-    .description("Introspect a database into Schema v2 files (see `askdb introspect --help`)")
-    .allowUnknownOption(true);
-program
-    .command("rag")
-    .description("Chunk, embed, and query a schema artifact for retrieval (see `askdb rag --help`)")
-    .allowUnknownOption(true);
-program
-    .command("ask")
-    .description("Generate SQL from schema + question")
-    .hook("preAction", () => {
-    requireAskDbConfig();
-})
-    .option("-s, --schema <path>", "Path to AskDB Schema v2 directory, bundled JSON, or schema.json (default: configured introspection.outputDir, or ./askdb/)")
-    .requiredOption("-q, --question <text>", "Natural language question")
-    .option("--explain", "After SQL, print a JSON block describing heuristic guardrails satisfied (Phase 2 explainability)", false)
-    .option("-v, --verbose", "Emit structured JSON logs (info) to stderr", false)
-    .option("--log-level <level>", "Structured log level (trace|debug|info|warn|error|fatal|silent)")
-    .option("--log-file <path>", "Append structured JSON logs to this file")
-    .option("--log-stdout", "Mirror structured JSON logs to stdout", false)
-    .option("--correlation-id <id>", "Correlation ID for logs (overrides logging.correlationId in askdb.config)")
-    .option("--mock-sql <sql>", "Deterministic NL→SQL for tests (bypasses live model call). Also via dev.mockSql in askdb.config.")
-    .option("--mode <id>", `Operating mode (${formatAskDbModesV1()}). Can tighten config modes.askdbMode (default schema_only), never loosen it`)
-    .option("--omit-sensitive-from-prompt", "Omit sensitive column/table names from NL→SQL DDL (default: include names, tagged as sensitive)", false)
-    .action(async (opts) => {
-    let logLevel;
-    // Only the flag is parsed here: the facade applies config `modes.askdbMode` (ADR 0025).
-    let mode;
-    const runtime = getAskDbRuntimeConfig();
-    try {
-        logLevel = resolveCliLogLevel(opts, runtime);
-        mode = opts.mode === undefined ? undefined : parseAskDbModeV1(opts.mode);
-    }
-    catch (e) {
-        printCliError(e);
-        process.exitCode = 1;
-        return;
-    }
-    const logger = createCliLogger(opts, runtime, logLevel);
-    const mockSql = opts.mockSql ?? runtime.dev.mockSql;
-    const aiConfig = mockSql ? undefined : ai.resolveAiConfig(runtime.ai.aiEnv);
-    if (!mockSql && !aiConfig) {
-        console.error(ai.keyMissingMessage("NL→SQL generation"));
-        console.error("Tip: in tests, pass --mock-sql or set dev.mockSql in askdb.config to bypass live model calls.");
-        process.exitCode = 1;
-        return;
-    }
-    logger.info({ event: AskDbLogEvent.RunStart }, "askdb run start");
-    try {
-        const schemaPath = resolveSchemaPathForAsk(opts.schema, runtime);
-        const schema = loadSchemaFromPath(schemaPath);
-        const askdb = createAskDb({
-            config: runtime,
-            registry: ai,
-            onResolve: (info) => {
-                if (info.dialect.note) {
-                    logger.info({
-                        event: "askdb.pipeline.dialect_override",
-                        note: info.dialect.note,
-                    }, info.dialect.note);
-                    console.error(`Note: ${info.dialect.note}`);
-                }
-            },
-        });
-        const out = await askdb.ask(opts.question, {
-            schema: { schema },
-            logger,
-            ...(mode ? { mode } : {}),
-            explain: Boolean(opts.explain),
-            // The facade adds config `modes.omitSensitiveFromPrompt` as a floor.
-            omitSensitiveIdentifiersFromNlToSqlPrompt: Boolean(opts.omitSensitiveFromPrompt),
-            // When --mock-sql flag is set explicitly (not just from runtime config),
-            // pass it as a per-call deps override so the flag wins over config.
-            ...(opts.mockSql !== undefined
-                ? {
-                    deps: {
-                        generateText: (async () => ({ text: opts.mockSql })),
-                    },
-                }
-                : {}),
-        });
-        // `ask()` runs the sensitive-identifier guardrail in warn mode and emits
-        // askdb.pipeline.sensitive_sql_warning through the logger above; the CLI
-        // only renders it for the operator.
-        const sensitive = out.sensitiveGuardrail;
-        if (sensitive && sensitive.references.length > 0) {
-            const cols = sensitive.references.map(formatSensitiveReference);
-            console.error(`Warning: generated SQL references sensitive columns: ${cols.join(", ")}\n` +
-                "Review carefully before sharing or running this SQL outside AskDB.");
-        }
-        if (sensitive?.unresolvedScope) {
-            console.error(`Note: ${sensitive.unresolvedScope.message}`);
-        }
-        console.log("-- sql --");
-        console.log(out.sql);
-        if (opts.explain) {
-            console.log("-- explain --");
-            console.log(JSON.stringify(out.explain ?? null, null, 2));
-        }
-        logger.info({ event: AskDbLogEvent.RunEnd, ok: true }, "askdb run end");
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        logger.error({ event: AskDbLogEvent.RunError, errMessage: msg }, "askdb run error");
-        printCliError(error);
-        process.exitCode = 1;
-    }
-});
-const RAG_NO_CONFIG_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
-// Each command loads askdb.config itself, only on the path that reads it.
-async function main(argv) {
-    const [command, ...rest] = argv.slice(2);
-    switch (command) {
-        case "init":
-            return runInitCli(rest);
-        case "introspect":
-            return runIntrospectCli(rest);
-        case "rag":
-            // Help, version and no args work without a config; every other rag command reads it.
-            if (rest.length > 0 && !rest.some((arg) => RAG_NO_CONFIG_FLAGS.has(arg)))
-                requireAskDbConfig();
-            return runRagCli(rest);
-        case "enrich":
-        case "studio":
-            return runStudioCommand(rest);
-        case "bundle":
-            return runBundleCommand(rest);
-        default:
-            // Commander handles `--help`, `--version`, `help`, and no-args without loading config;
-            // commands that need config load it lazily in a preAction hook.
-            await program.parseAsync(argv);
-            return undefined;
-    }
-}
+import { isAskDbDebugEnabled } from "@askdb/config";
+import { AskDbError } from "@askdb/core";
+import { printCliError } from "./cli-error.js";
+import { runCli } from "./dispatch.js";
+/**
+ * Resolves once everything written so far has reached stdout and stderr, so exiting can't cut it
+ * off. A reader that closed early (`askdb --help | grep -q …`) leaves nothing to drain: its EPIPE
+ * resolves instead of crashing the exit.
+ */
+function drain() {
+    return Promise.all([process.stdout, process.stderr].map((stream) => new Promise((done) => {
+        stream.on("error", done);
+        stream.write("", done);
+    })));
+}
+const EXIT_GRACE_MS = 250;
+// Each command loads askdb.config itself, only on the path that reads it. An error that escapes a
+// command, such as a missing or broken config, lands here.
+let exitCode;
 try {
-    const exitCode = await main(process.argv);
-    if (exitCode !== undefined)
-        process.exit(exitCode);
+    exitCode = await runCli(process.argv.slice(2));
 }
 catch (error) {
     printCliError(error);
@@ -316,6 +29,12 @@ catch (error) {
     else if (!(error instanceof AskDbError)) {
         console.error("Set ASKDB_DEBUG=1 to print the stack trace.");
     }
-    process.exit(1);
+    exitCode = 1;
 }
+await drain();
+// Exit once the event loop is empty, so a logger's own pending writes (`--log-stdout` into a reader
+// that closed early) settle instead of making the exit hook retry them forever. A command that
+// leaves a handle open, such as Studio's sockets after it stops, is cut off after a grace period.
+process.exitCode = exitCode;
+setTimeout(() => process.exit(), EXIT_GRACE_MS).unref();
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC;;;;GAIG;AACH,SAAS,KAAK;IACZ,OAAO,OAAO,CAAC,GAAG,CAChB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAClC,CAAC,MAAM,EAAE,EAAE,CACT,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACnB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CACL,CACF,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B,kGAAkG;AAClG,2DAA2D;AAC3D,IAAI,QAAgB,CAAC;AACrB,IAAI,CAAC;IACH,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,aAAa,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,mBAAmB,EAAE,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QACnE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;SAAM,IAAI,CAAC,CAAC,KAAK,YAAY,UAAU,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC/D,CAAC;IACD,QAAQ,GAAG,CAAC,CAAC;AACf,CAAC;AACD,MAAM,KAAK,EAAE,CAAC;AACd,oGAAoG;AACpG,+FAA+F;AAC/F,kGAAkG;AAClG,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC5B,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC,KAAK,EAAE,CAAC"}

package/dist/command.d.ts

@@ -0,0 +1,56 @@
+/** One flag of a command: how it's spelt, how it shows in the help, and what it sets. */
+export type Flag<O> = {
+    /** Spellings, short form first: `["-f", "--force"]`. */
+    names: readonly string[];
+    /** Placeholder for the flag's value, e.g. `<dir>`; absent for a switch. */
+    value?: string;
+    /** The help line; a function when it depends on something the command is built with. */
+    help: string | (() => string);
+    /** The help section, e.g. `Database options`. Absent: `Options`. */
+    group?: string;
+    /** Sets the flag on `opts`. A bad value throws; the error repeats it only when `showable()`. */
+    apply(opts: O, value: string): void;
+};
+/** Everything `runCommand` needs to parse, document, gate and run one `askdb` command. */
+export type CommandSpec<O> = {
+    name: string;
+    /** One line, for the top of the command's help and for `askdb --help`. */
+    summary: string;
+    /** Usage lines, each starting `askdb <name>`. */
+    usage: readonly string[];
+    /** Lines printed between the usage and the options. */
+    notes?: readonly string[];
+    flags: readonly Flag<O>[];
+    /**
+     * Takes the `index`th argument that isn't a flag. Absent: the command takes none. Throws for
+     * one it doesn't take, without repeating it.
+     */
+    positional?(opts: O, value: string, index: number): void;
+    /** Options before any flag is applied. */
+    initial(): O;
+    /** Conflicts between flags, after every flag is applied. Throws a usage error. */
+    check?(opts: O): void;
+    /** Whether this run reads askdb.config. */
+    needsConfig(opts: O): boolean;
+    run(opts: O): Promise<number>;
+};
+/** The spellings every command, and `askdb` itself, takes for its help and its version. */
+export declare const HELP_FLAGS: readonly string[];
+export declare const VERSION_FLAGS: readonly string[];
+/** The help and version lines every command takes. `askdb --help` lists them too. */
+export declare const GENERAL_OPTION_LINES: readonly OptionLine[];
+type OptionLine = {
+    usage: string;
+    help: string;
+};
+/**
+ * Runs one command: `--help`/`-h` and `--version`/`-V` first, anywhere in `argv`; then the flags,
+ * positionals and `check`; then the config gate; then `run`. A usage error or an error `run`
+ * throws goes to stderr and returns 1. The config gate's error propagates, so the top-level
+ * handler prints it with its debug hint.
+ */
+export declare function runCommand<O>(spec: CommandSpec<O>, argv: readonly string[]): Promise<number>;
+/** `Heading:` then one aligned line per option, for each section with any. */
+export declare function formatOptionSections(sections: ReadonlyMap<string, readonly OptionLine[]>): string[];
+export {};
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAKA,yFAAyF;AACzF,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;IACpB,wDAAwD;IACxD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC9B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,0CAA0C;IAC1C,OAAO,IAAI,CAAC,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;IAC9B,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAqB,CAAC;AAC9D,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAwB,CAAC;AAEpE,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,SAAS,UAAU,EAGrD,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBlG;AAqFD,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC,GAAG,MAAM,EAAE,CAMnG"}

package/dist/command.js

@@ -0,0 +1,139 @@
+import { errorMessage } from "./cli-error.js";
+import { labelled } from "./error-values.js";
+import { requireAskDbConfig } from "./project-config.js";
+import { readCliVersion } from "./version.js";
+/** The spellings every command, and `askdb` itself, takes for its help and its version. */
+export const HELP_FLAGS = ["--help", "-h"];
+export const VERSION_FLAGS = ["--version", "-V"];
+/** The help and version lines every command takes. `askdb --help` lists them too. */
+export const GENERAL_OPTION_LINES = [
+    { usage: "-V, --version", help: "Print the askdb version." },
+    { usage: "-h, --help", help: "Print this help." },
+];
+/**
+ * Runs one command: `--help`/`-h` and `--version`/`-V` first, anywhere in `argv`; then the flags,
+ * positionals and `check`; then the config gate; then `run`. A usage error or an error `run`
+ * throws goes to stderr and returns 1. The config gate's error propagates, so the top-level
+ * handler prints it with its debug hint.
+ */
+export async function runCommand(spec, argv) {
+    if (argv.some((arg) => HELP_FLAGS.includes(arg))) {
+        process.stdout.write(formatHelp(spec));
+        return 0;
+    }
+    if (argv.some((arg) => VERSION_FLAGS.includes(arg))) {
+        process.stdout.write(`${readCliVersion()}\n`);
+        return 0;
+    }
+    let opts;
+    try {
+        opts = parseArgs(spec, argv);
+        spec.check?.(opts);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    if (spec.needsConfig(opts))
+        requireAskDbConfig();
+    try {
+        return await spec.run(opts);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function parseArgs(spec, argv) {
+    const byName = new Map(spec.flags.flatMap((flag) => flag.names.map((name) => [name, flag])));
+    const opts = spec.initial();
+    let positionals = 0;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        // Errors never repeat an argument whole: it can be a connection string, password included.
+        if (!arg.startsWith("-")) {
+            if (!spec.positional) {
+                throw new Error(`Unexpected argument: askdb ${spec.name} takes no positional arguments. Pass values with their flag.`);
+            }
+            spec.positional(opts, arg, positionals);
+            positionals += 1;
+            continue;
+        }
+        // `--flag=value` works like `--flag value`.
+        const eq = arg.indexOf("=");
+        const name = eq === -1 ? arg : arg.slice(0, eq);
+        const inline = eq === -1 ? undefined : arg.slice(eq + 1);
+        const flag = byName.get(name);
+        if (flag) {
+            if (!flag.value) {
+                if (inline !== undefined)
+                    throw new Error(`${name} takes no value.`);
+                flag.apply(opts, "");
+            }
+            else if (inline !== undefined) {
+                if (!inline)
+                    throw new Error(`${name} requires a value.`);
+                flag.apply(opts, inline);
+            }
+            else {
+                flag.apply(opts, readValue(argv, ++i, name));
+            }
+            continue;
+        }
+        if (arg.startsWith("--") || arg.length < 3)
+            throw new Error(labelled("Unknown option", name));
+        // Short flags cluster: `-fy` is `-f -y`, `-qtext` is `-q text`, and `-vq text` ends with the
+        // flag that takes a value.
+        for (let j = 1; j < arg.length; j += 1) {
+            const short = `-${arg[j]}`;
+            const cluster = byName.get(short);
+            if (!cluster)
+                throw new Error(labelled("Unknown option", short));
+            if (!cluster.value) {
+                cluster.apply(opts, "");
+                continue;
+            }
+            const rest = arg.slice(j + 1);
+            cluster.apply(opts, rest || readValue(argv, ++i, short));
+            break;
+        }
+    }
+    return opts;
+}
+/** The argument after a flag that takes a value; another flag there means the value is missing. */
+function readValue(argv, index, name) {
+    const value = argv[index];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value.`);
+    return value;
+}
+/** What `askdb <name> --help` and `askdb help <name>` print. */
+function formatHelp(spec) {
+    const sections = new Map([["Options", []]]);
+    for (const flag of spec.flags) {
+        const group = flag.group ?? "Options";
+        if (!sections.has(group))
+            sections.set(group, []);
+        sections.get(group).push({
+            usage: flag.names.join(", ") + (flag.value ? ` ${flag.value}` : ""),
+            help: typeof flag.help === "function" ? flag.help() : flag.help,
+        });
+    }
+    sections.get("Options").push(...GENERAL_OPTION_LINES);
+    return [
+        `askdb ${spec.name} - ${spec.summary}`,
+        "",
+        "Usage:",
+        ...spec.usage.map((line) => `  ${line}`),
+        "",
+        ...(spec.notes && spec.notes.length > 0 ? [...spec.notes, ""] : []),
+        ...formatOptionSections(sections),
+    ].join("\n");
+}
+/** `Heading:` then one aligned line per option, for each section with any. */
+export function formatOptionSections(sections) {
+    const all = [...sections.values()].flat();
+    const width = Math.max(...all.map((line) => line.usage.length)) + 2;
+    return [...sections].flatMap(([heading, lines]) => lines.length === 0 ? [] : [`${heading}:`, ...lines.map((line) => `  ${line.usage.padEnd(width)}${line.help}`), ""]);
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

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

package/dist/dispatch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `askdb <command> …`, `askdb help <command>`, `--help` and `--version`. Returns the exit code.
+ * With no command, prints the help to stderr and returns 1.
+ */
+export declare function runCli(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AA6CA;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBrE"}