@dbx-tools/cli-appkit-env 0.3.21

package/README.md

@@ -0,0 +1,71 @@
+# @dbx-tools/cli-appkit-env
+
+CLI and formatting helpers for exporting AppKit auto-configuration results.
+
+Use the `dbx-tools-appkit-env` bin when a shell or process manager needs the Lakebase /
+AppKit environment that [`@dbx-tools/appkit`](../../node/appkit) would
+resolve before `createApp()`.
+
+Key features:
+
+- Runs the same AppKit auto-configuration path used by
+  [`@dbx-tools/appkit`](../../node/appkit).
+- Emits only variables that changed during auto-configuration.
+- Supports shell `export`, JSON, and Windows `set` output formats.
+- Provides importable env snapshot/diff/format helpers for tests and wrapper
+  CLIs.
+- Keeps local shell setup aligned with deployed AppKit startup behavior.
+
+## Load Env Into A Shell
+
+```sh
+eval "$(dbx-tools-appkit-env --quiet)"
+```
+
+The command snapshots `process.env`, runs AppKit auto-config, diffs the result,
+and prints only new or changed variables. On POSIX shells the default output is
+`export KEY=value`.
+
+The package installs two equivalent commands: `dbx-tools-appkit-env` and the
+shorter `dbxt-appkit-env`. Neither matches the package name, so a one-off run
+has to name the command explicitly:
+
+```sh
+npx --package @dbx-tools/cli-appkit-env dbx-tools-appkit-env --quiet
+```
+
+This is useful when another process must start after Lakebase discovery has
+filled `PGHOST`, `PGDATABASE`, `PGUSER`, or related AppKit variables.
+
+## Inspect JSON Or Windows Output
+
+```sh
+dbx-tools-appkit-env --format json
+dbx-tools-appkit-env --format windows
+```
+
+Use JSON for process managers and tests. Use Windows format for `cmd.exe`
+`set KEY=value` lines.
+
+## Format Env Diffs Programmatically
+
+```ts
+import { envExport } from "@dbx-tools/cli-appkit-env";
+
+const before = envExport.snapshotEnv();
+process.env.PGHOST = "ep-foo.database.azuredatabricks.net";
+const diff = envExport.diffEnv(before);
+
+console.log(envExport.formatEnvExport(diff, "export"));
+```
+
+These helpers are useful in tests for auto-config behavior or in custom CLIs
+that want the same output formats without invoking the bin.
+
+## Modules
+
+- `envExport` - env snapshots, env diffs, default format detection,
+  `formatEnvExport()`, and `parseEnvExportFormat()`.
+
+Auto-config itself lives in
+[`@dbx-tools/appkit`](../../node/appkit).

package/bin/dbx-tools-appkit-env.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by projen synth (cli tag) - DO NOT EDIT.
+// Regenerated from ./dbx-tools-appkit-env.ts.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+// Resolved as a bare specifier so Node looks in THIS file's package rather than the
+// caller's cwd - the only way a globally installed CLI finds its own tsx.
+import { register } from "tsx/esm/api";
+
+register();
+await import(new URL("./dbx-tools-appkit-env.ts", import.meta.url).href);

package/bin/dbx-tools-appkit-env.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * `dbx-tools-appkit-env`: run AppKit auto-config and print the env vars it added or
+ * changed. Snapshots `process.env`, runs auto-config, diffs, and writes
+ * eval-able `export` / `set` lines (or JSON) to stdout - e.g.
+ * `eval "$(dbx-tools-appkit-env)"` to load a resolved Lakebase connection into your shell.
+ */
+
+import { Command, CommanderError } from "commander";
+import { log } from "@dbx-tools/shared-core";
+import { createApp } from "@dbx-tools/appkit";
+import {
+  defaultEnvExportFormat,
+  diffEnv,
+  formatEnvExport,
+  parseEnvExportFormat,
+  snapshotEnv,
+} from "../src/env-export";
+
+const logger = log.logger("appkit-env");
+
+const program = new Command()
+  .name("dbx-tools-appkit-env")
+  .description("Run AppKit auto-config and print new/changed env vars.")
+  .option(
+    "-f, --format <format>",
+    "Output: export (POSIX shell), windows (cmd set), or json. Defaults by platform.",
+  )
+  .option("-q, --quiet", "Suppress auto-config log output (LOG_LEVEL=error)")
+  .action(async (opts: { format?: string; quiet?: boolean }) => {
+    if (opts.quiet) {
+      process.env.LOG_LEVEL = "error";
+    }
+
+    const format = opts.format ? parseEnvExportFormat(opts.format) : defaultEnvExportFormat();
+    logger.debug("Snapshotting env vars");
+    const before = snapshotEnv();
+    await createApp.autoConfigure({ autoConfigure: true });
+    const changes = diffEnv(before, snapshotEnv());
+
+    process.stdout.write(formatEnvExport(changes, format));
+  });
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  if (err instanceof CommanderError) {
+    process.exit(err.exitCode);
+  }
+  process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+  process.exit(1);
+});

package/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as envExport from "./src/env-export";
+export type { EnvExportFormat } from "./src/env-export";

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@dbx-tools/cli-appkit-env",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/cli/appkit-env"
+  },
+  "bin": {
+    "dbx-tools-appkit-env": "./bin/dbx-tools-appkit-env.mjs",
+    "dbxt-appkit-env": "./bin/dbx-tools-appkit-env.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@databricks/appkit": "^0.43.0",
+    "commander": "^15.0.0",
+    "tsx": "^4.23.0",
+    "@dbx-tools/appkit": "0.3.21",
+    "@dbx-tools/shared-core": "0.3.21"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.21",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./env-export": "./src/env-export.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "cli"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/env-export.ts

@@ -0,0 +1,111 @@
+/**
+ * Snapshot `process.env`, diff after auto-config, and format deltas as
+ * eval-able shell `export` / Windows `set` lines or JSON.
+ *
+ * @module
+ */
+
+export type EnvExportFormat = "export" | "windows" | "json";
+
+/** Shallow copy of the current process environment. */
+export function snapshotEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Keys whose values were added, changed, or cleared between snapshots. A key
+ * that went from a non-blank value to blank/removed is emitted with an empty
+ * value so it can be unset. Keys that were already blank/absent and stayed that
+ * way are omitted.
+ */
+export function diffEnv(
+  before: Record<string, string>,
+  after: Record<string, string>,
+): Record<string, string> {
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  const out: Record<string, string> = {};
+  for (const key of [...keys].sort()) {
+    // Treat a removed key as blank so a non-blank -> blank/removed transition is a delta.
+    const prev = before[key] ?? "";
+    const next = after[key] ?? "";
+    if (next !== prev) {
+      out[key] = next;
+    }
+  }
+  return out;
+}
+
+export function defaultEnvExportFormat(
+  platform: NodeJS.Platform = process.platform,
+): EnvExportFormat {
+  return platform === "win32" ? "windows" : "export";
+}
+
+function escapeExportValue(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, "\\$")
+    .replace(/`/g, "\\`");
+}
+
+function escapeWindowsSetValue(value: string): string {
+  if (/[\s"&|<>^]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/**
+ * Format env entries for the requested output style. An empty map prints
+ * nothing (no trailing newline).
+ */
+export function formatEnvExport(env: Record<string, string>, format: EnvExportFormat): string {
+  const entries = Object.entries(env).sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) {
+    return "";
+  }
+
+  switch (format) {
+    case "json":
+      return `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`;
+    case "windows":
+      return (
+        entries.map(([key, value]) => `set ${key}=${escapeWindowsSetValue(value)}`).join("\n") +
+        "\n"
+      );
+    case "export":
+      return (
+        entries.map(([key, value]) => `export ${key}="${escapeExportValue(value)}"`).join("\n") +
+        "\n"
+      );
+    default:
+      throw new Error(`Unknown env export format: ${format satisfies never}`);
+  }
+}
+
+/** Normalize CLI format aliases to a supported export format. */
+export function parseEnvExportFormat(value: string): EnvExportFormat {
+  const normalized = value.trim().toLowerCase();
+  if (
+    normalized === "export" ||
+    normalized === "shell" ||
+    normalized === "nix" ||
+    normalized === "bash"
+  ) {
+    return "export";
+  }
+  if (normalized === "windows" || normalized === "win" || normalized === "cmd") {
+    return "windows";
+  }
+  if (normalized === "json") {
+    return "json";
+  }
+  throw new Error(`Unknown format '${value}'. Use export, windows, or json.`);
+}

package/tsconfig.json

@@ -0,0 +1,43 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "index.ts",
+    "bin/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}