@openworkflow/cli 0.4.4 → 0.5.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 /* v8 ignore file -- @preserve */
 import { dashboard, doctor, getVersion, init, workerStart, } from "./commands.js";
 import { withErrorHandling } from "./errors.js";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 // openworkflow
 const program = new Command();
 program
@@ -14,13 +14,22 @@ program
 program
     .command("init")
     .description("initialize OpenWorkflow")
+    .addOption(new Option("--backend <backend>", "backend to configure").choices([
+    "sqlite",
+    "postgres",
+    "both",
+]))
+    .option("-y, --yes", "skip prompts (requires --backend; does not allow overwrites)")
+    .option("--skip-install", "create project files without installing dependencies")
     .option("--config <path>", "path to OpenWorkflow config file")
+    .option("--env-file <path>", "load environment variables from file")
     .action(withErrorHandling(init));
 // doctor
 program
     .command("doctor")
-    .description("check configuration and list available workflows")
+    .description("check worker prerequisites")
     .option("--config <path>", "path to OpenWorkflow config file")
+    .option("--env-file <path>", "load environment variables from file")
     .action(withErrorHandling(doctor));
 // worker
 const workerCmd = program.command("worker").description("manage workers");
@@ -30,6 +39,7 @@ workerCmd
     .description("start a worker to process workflows")
     .option("-c, --concurrency <number>", "number of concurrent workflows to process", Number.parseInt)
     .option("--config <path>", "path to OpenWorkflow config file")
+    .option("--env-file <path>", "load environment variables from file")
     .action(withErrorHandling(workerStart));
 // dashboard
 program
@@ -37,5 +47,6 @@ program
     .description("start the dashboard to view workflow runs")
     .option("-p, --port <number>", "custom port for the dashboard server", Number.parseInt)
     .option("--config <path>", "path to OpenWorkflow config file")
+    .option("--env-file <path>", "load environment variables from file")
     .action(withErrorHandling(dashboard));
 await program.parseAsync(process.argv);

package/dist/commands.d.ts

@@ -1,6 +1,13 @@
 import { WorkerConfig } from "./config.js";
+type BackendChoice = "sqlite" | "postgres" | "both";
 interface CommandOptions {
     config?: string;
+    envFile?: string;
+}
+interface InitOptions extends CommandOptions {
+    backend?: BackendChoice;
+    yes?: boolean;
+    skipInstall?: boolean;
 }
 interface DashboardOptions extends CommandOptions {
     port?: number;
@@ -14,7 +21,7 @@ export declare function getVersion(): string;
  * openworkflow init
  * @param options - Command options
  */
-export declare function init(options?: CommandOptions): Promise<void>;
+export declare function init(options?: InitOptions): Promise<void>;
 /**
  * openworkflow doctor
  * @param options - Command options
@@ -63,6 +70,7 @@ export declare function dashboard(options?: DashboardOptions): Promise<void>;
  */
 export declare function discoverWorkflowFiles(dirs: string[], baseDir: string, ignorePatterns?: string[]): string[];
 interface PackageJsonForDoctor {
+    scripts?: Record<string, string>;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
 }

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkC,MAAM,aAAa,CAAC;AAiC3E,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAoBnC;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoItE;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDxE;AAED,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,cAAc,CAAC;AAE/D;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAuEf;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE;QACZ,KAAK,EAAE,SAAS,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACzB,CAAC;CACH,CAYA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAavE;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8D7E;AAwOD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAAO,GAC5B,MAAM,EAAE,CA4CV;AAiWD,UAAU,oBAAoB;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAsBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAKR"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAIb,MAAM,aAAa,CAAC;AAwCrB,KAAK,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAEpD,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,WAAY,SAAQ,cAAc;IAC1C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,gBAAiB,SAAQ,cAAc;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAoBnC;AAED;;;GAGG;AAEH,wBAAsB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqJnE;AA8BD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2DxE;AAED,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,cAAc,CAAC;AAE/D;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE;QACZ,KAAK,EAAE,SAAS,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACzB,CAAC;CACH,CAYA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAavE;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D7E;AA4PD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAAO,GAC5B,MAAM,EAAE,CA8CV;AA2WD,UAAU,oBAAoB;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAoCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,GACjD,MAAM,CAER"}

package/dist/commands.js

@@ -1,18 +1,19 @@
-import { loadConfig, loadConfigFromPath } from "./config.js";
-import { CLIError } from "./errors.js";
+import { findConfigFile, loadConfigFromPath, } from "./config.js";
+import { CLIError, exit } from "./errors.js";
+import { createModuleLoader } from "./module-loader.js";
 import { CONFIG, HELLO_WORLD_RUNNER, HELLO_WORLD_WORKFLOW, POSTGRES_CLIENT, POSTGRES_PROD_SQLITE_DEV_CLIENT, SQLITE_CLIENT, } from "./templates.js";
 import * as p from "@clack/prompts";
 import { consola } from "consola";
 import { config as loadDotenv } from "dotenv";
-import { createJiti } from "jiti";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { addDependency, detectPackageManager } from "nypm";
+import { addDependency, addDependencyCommand, detectPackageManager, } from "nypm";
 import { OpenWorkflow } from "openworkflow";
 import { isWorkflow } from "openworkflow/internal";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const workflowSources = new WeakMap();
 /**
  * openworkflow -V | --version
  * @returns the version string, or "-" if it cannot be determined
@@ -40,94 +41,107 @@ export function getVersion() {
  * openworkflow init
  * @param options - Command options
  */
+// oxlint-disable-next-line complexity
 export async function init(options = {}) {
-    const configPath = options.config;
+    if (options.yes && !options.backend) {
+        throw new CLIError("--backend is required with --yes.");
+    }
+    if (!options.yes && !process.stdin.isTTY) {
+        throw new CLIError("Interactive setup requires a terminal. Pass --backend sqlite|postgres|both --yes.");
+    }
     p.intro("Initializing OpenWorkflow...");
-    const { configFile } = await loadConfigWithEnv(configPath);
+    const configFile = findConfigWithEnv(options);
     let configFileToDelete = null;
-    if (configFile) {
+    if (configFile && existsSync(configFile)) {
+        if (options.yes) {
+            throw new CLIError(`Config file already exists at ${configFile}. --yes does not allow overwrites.`);
+        }
         const shouldOverride = await p.confirm({
             message: `Config file already exists at ${configFile}. Override it?`,
             initialValue: false,
         });
-        if (!shouldOverride || p.isCancel(shouldOverride)) {
-            p.cancel("Setup canceled.");
-            // eslint-disable-next-line unicorn/no-process-exit
-            process.exit(0);
-        }
+        if (!shouldOverride || p.isCancel(shouldOverride))
+            cancelSetup();
         configFileToDelete = configFile;
     }
-    const backendChoice = await p.select({
-        message: "Select a backend for OpenWorkflow:",
-        options: [
-            {
-                value: "sqlite",
-                label: "SQLite",
-                hint: "Recommended for testing and development",
-            },
-            {
-                value: "postgres",
-                label: "PostgreSQL",
-                hint: "Recommended for production",
-            },
-            {
-                value: "both",
-                label: "Both",
-                hint: "SQLite for dev, PostgreSQL for production",
-            },
-        ],
-        initialValue: "sqlite",
-    });
-    if (p.isCancel(backendChoice)) {
-        p.cancel("Setup canceled.");
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(0);
-    }
+    const backendChoice = options.backend ??
+        (await p.select({
+            message: "Select a backend for OpenWorkflow:",
+            options: [
+                {
+                    value: "sqlite",
+                    label: "SQLite",
+                    hint: "Recommended for testing and development",
+                },
+                {
+                    value: "postgres",
+                    label: "PostgreSQL",
+                    hint: "Recommended for production",
+                },
+                {
+                    value: "both",
+                    label: "Both",
+                    hint: "SQLite for dev, PostgreSQL for production",
+                },
+            ],
+            initialValue: "sqlite",
+        }));
+    if (typeof backendChoice === "symbol")
+        cancelSetup();
     const spinner = p.spinner();
     // detect package manager & install packages
     spinner.start("Detecting package manager...");
     const pm = await detectPackageManager(process.cwd());
-    const packageManager = pm?.name ?? "your package manager";
+    const packageManager = pm?.name ?? "npm";
     spinner.stop(`Using ${packageManager}`);
     const packageJson = readPackageJsonForDoctor();
     if (!packageJson) {
         throw new CLIError("No package.json found.", "Please create a package.json file first by running `npm init` or `npm init -y`.");
     }
-    const configFileName = configPath ?? getConfigFileName(packageJson);
+    validateInitManifest(packageJson);
+    const configFileName = options.config ?? getConfigFileName(packageJson);
     const clientFileName = getClientFileName(packageJson);
     const exampleWorkflowFileName = getExampleWorkflowFileName(packageJson);
     const runFileName = getRunFileName(packageJson);
     const runCommand = runFileName.endsWith(".ts")
         ? `npx tsx openworkflow/${runFileName}`
         : `node openworkflow/${runFileName}`;
-    const shouldSetup = await p.confirm({
-        message: "Install packages and set up project files?",
-        initialValue: true,
-    });
-    if (p.isCancel(shouldSetup)) {
-        p.cancel("Setup canceled.");
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(0);
-    }
+    const shouldSetup = options.yes ??
+        (await p.confirm({
+            message: options.skipInstall
+                ? "Set up project files?"
+                : "Install packages and set up project files?",
+            initialValue: true,
+        }));
+    if (p.isCancel(shouldSetup))
+        cancelSetup();
     if (!shouldSetup) {
         p.outro("Setup skipped.");
         return;
     }
-    if (configFileToDelete) {
-        unlinkSync(configFileToDelete);
+    const dependencies = getDependenciesToInstall(backendChoice);
+    const devDependencies = getDevDependenciesToInstall();
+    if (options.skipInstall) {
+        p.note([
+            addDependencyCommand(packageManager, dependencies),
+            addDependencyCommand(packageManager, devDependencies, { dev: true }),
+        ].join("\n"), "Install dependencies before running OpenWorkflow");
     }
-    {
-        const dependencies = getDependenciesToInstall(backendChoice);
+    else {
         spinner.start(`Installing ${dependencies.join(", ")}...`);
-        await addDependency(dependencies, { silent: true });
+        await addDependency(dependencies, { silent: true, packageManager });
         spinner.stop(`Installed ${dependencies.join(", ")}`);
-    }
-    {
-        const devDependencies = getDevDependenciesToInstall();
         spinner.start(`Installing ${devDependencies.join(", ")}...`);
-        await addDependency(devDependencies, { silent: true, dev: true });
+        await addDependency(devDependencies, {
+            silent: true,
+            dev: true,
+            packageManager,
+        });
         spinner.stop(`Installed ${devDependencies.join(", ")}`);
     }
+    if (configFileToDelete) {
+        unlinkSync(configFileToDelete);
+    }
     createClientFile(backendChoice, clientFileName);
     createExampleWorkflow(exampleWorkflowFileName);
     createRunFile(runFileName);
@@ -145,56 +159,89 @@ export async function init(options = {}) {
     p.note(`➡️ Start a worker:\n$ npx @openworkflow/cli worker start\n\n➡️ Run the example workflow:\n$ ${runCommand}\n\n➡️ View the dashboard:\n$ npx @openworkflow/cli dashboard`, "Next steps");
     p.outro("✅ Setup complete!");
 }
+// Validate the manifest fields that init reads or updates.
+function validateInitManifest(manifest) {
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+        throw new CLIError("Invalid package.json: expected an object.");
+    }
+    for (const key of ["scripts", "dependencies", "devDependencies"]) {
+        const field = manifest[key];
+        if (field === undefined)
+            continue;
+        if (field === null ||
+            typeof field !== "object" ||
+            Array.isArray(field) ||
+            Object.values(field).some((value) => typeof value !== "string")) {
+            throw new CLIError(`Invalid package.json: ${key} must be an object containing string values.`);
+        }
+    }
+    const { scripts } = manifest;
+    const worker = scripts?.["worker"];
+    if (worker !== undefined && worker !== "npx @openworkflow/cli worker start") {
+        throw new CLIError("Setup would overwrite package.json scripts.worker.");
+    }
+}
 /**
  * openworkflow doctor
  * @param options - Command options
  */
 export async function doctor(options = {}) {
-    const configPath = options.config;
     consola.start("Running OpenWorkflow doctor...");
-    const { config, configFile } = await loadConfigWithEnv(configPath);
+    const timer = setTimeout(() => {
+        consola.error("Doctor timed out after 30 seconds.");
+        void exit(1);
+    }, 30_000);
+    const { config, configFile } = await loadConfigWithEnv(options);
     if (!configFile) {
         throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file.");
     }
     const backend = config.backend;
+    let cleanupFailed = false;
     try {
+        await checkBackendConnection(backend);
+        if (config.worker?.concurrency !== undefined) {
+            assertPositiveInteger("concurrency", config.worker.concurrency);
+        }
         consola.log("");
-        consola.info(`Config file: ${configFile}`);
+        consola.info(`Config file: ${path.relative(process.cwd(), configFile)}`);
         const backendName = backend.constructor.name.replace("Backend", "");
         consola.log(`  • Backend: ${backendName}`);
-        const packageJson = readPackageJsonForDoctor();
-        if (packageJson) {
-            warnIfMissingBackendPackage(backendName, packageJson);
-            warnIfMissingTsconfig(packageJson);
-        }
         // discover directories
-        const dirs = getWorkflowDirectories(config);
+        const dirs = [...new Set(getWorkflowDirectories(config))];
         consola.log(`  • Workflow directories: ${dirs.join(", ")}`);
         // discover files
         const configFileDir = path.dirname(configFile);
-        const { files, workflows } = await discoverWorkflowsInDirs(dirs, configFileDir, config.ignorePatterns ?? []);
-        consola.log("");
-        consola.info(`Found ${String(files.length)} workflow file(s):`);
-        for (const file of files) {
-            consola.log(`  • ${file}`);
-        }
+        const { workflows } = await discoverWorkflowsInDirs(dirs, configFileDir, config.ignorePatterns ?? []);
+        assertNoDuplicateWorkflows(workflows);
         printDiscoveredWorkflows(workflows);
-        warnAboutDuplicateWorkflows(workflows);
-        consola.log("");
-        consola.success("Configuration looks good!");
     }
     finally {
-        await backend.stop();
+        // Imported configs can omit the backend despite the declared config type.
+        // oxlint-disable-next-line typescript/no-unnecessary-condition
+        if (typeof backend?.stop === "function") {
+            try {
+                await backend.stop();
+            }
+            catch (error) {
+                cleanupFailed = true;
+                consola.error(`Backend cleanup failed: ${String(error)}`);
+            }
+        }
     }
+    clearTimeout(timer);
+    if (cleanupFailed)
+        await exit(1);
+    consola.log("");
+    consola.success("Configuration looks good!");
+    await exit(0);
 }
 /**
  * openworkflow worker start
  * @param options - Worker config and command options
  */
 export async function workerStart(options = {}) {
-    const { config: configPath, ...workerConfig } = options;
     consola.start("Starting worker...");
-    const { config, configFile } = await loadConfigWithEnv(configPath);
+    const { config, configFile } = await loadConfigWithEnv(options);
     if (!configFile) {
         throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file.");
     }
@@ -217,6 +264,7 @@ export async function workerStart(options = {}) {
         consola.success("Worker stopped");
     }
     try {
+        await checkBackendConnection(backend);
         // discover and import workflows
         const dirs = getWorkflowDirectories(config);
         consola.info(`Discovering workflows from: ${dirs.join(", ")}`);
@@ -225,7 +273,9 @@ export async function workerStart(options = {}) {
         consola.info(`Found ${String(files.length)} workflow file(s)`);
         consola.success(`Loaded ${String(workflows.length)} workflow(s): ${workflows.map((w) => w.spec.name).join(", ")}`);
         assertNoDuplicateWorkflows(workflows);
-        const workerOptions = mergeDefinedOptions(config.worker, workerConfig);
+        const workerOptions = mergeDefinedOptions(config.worker, {
+            concurrency: options.concurrency,
+        });
         if (workerOptions.concurrency !== undefined) {
             assertPositiveInteger("concurrency", workerOptions.concurrency);
         }
@@ -240,7 +290,12 @@ export async function workerStart(options = {}) {
         consola.success("Worker started.");
     }
     catch (error) {
-        await gracefulShutdown();
+        try {
+            await gracefulShutdown();
+        }
+        catch (cleanupError) {
+            consola.warn(`Backend cleanup failed: ${String(cleanupError)}`);
+        }
         throw error;
     }
 }
@@ -283,10 +338,9 @@ export function validateDashboardPort(port) {
  * @returns Resolves when the dashboard process exits.
  */
 export async function dashboard(options = {}) {
-    const configPath = options.config;
     const port = validateDashboardPort(options.port);
     consola.start("Starting dashboard...");
-    const { configFile } = await loadConfigWithEnv(configPath);
+    const { configFile } = await loadConfigWithEnv(options);
     if (!configFile) {
         throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file before starting the dashboard.");
     }
@@ -324,6 +378,30 @@ export async function dashboard(options = {}) {
     });
 }
 // -----------------------------------------------------------------------------
+/**
+ * Show a canceled-setup message and exit the process with status 0.
+ */
+function cancelSetup() {
+    p.cancel("Setup canceled.");
+    // oxlint-disable-next-line unicorn/no-process-exit
+    process.exit(0);
+}
+/**
+ * Exercise backend initialization, connectivity, and workflow table access.
+ * @param backend - Configured backend
+ */
+async function checkBackendConnection(backend) {
+    if (typeof backend?.listWorkflowRuns !== "function" ||
+        typeof backend.stop !== "function") {
+        throw new CLIError("Missing or invalid backend.", "Set config.backend to a connected OpenWorkflow backend.");
+    }
+    try {
+        await backend.listWorkflowRuns({ limit: 1 });
+    }
+    catch (error) {
+        throw new CLIError("Failed to access backend.", error instanceof Error ? error.message : String(error));
+    }
+}
 /**
  * Get workflow directories from config.
  * @param config - The loaded config
@@ -355,7 +433,7 @@ function findDuplicateWorkflows(workflows) {
     for (const workflow of workflows) {
         const name = workflow.spec.name;
         const version = workflow.spec.version ?? null;
-        const key = version ? `${name}@${version}` : name;
+        const key = JSON.stringify([name, version]);
         const existing = workflowKeys.get(key);
         if (existing) {
             existing.count += 1;
@@ -383,32 +461,18 @@ function assertNoDuplicateWorkflows(workflows) {
     const suffix = remaining > 0 ? ` (+${String(remaining)} more)` : "";
     throw new CLIError(`Duplicate workflow name${duplicates.length === 1 ? "" : "s"} detected: ${preview}${suffix}`, "Multiple workflow files export workflows with the same name and version. Each workflow must have a unique name and version combination.");
 }
-/**
- * Warn about duplicate workflows without failing.
- * @param workflows - Discovered workflows
- */
-function warnAboutDuplicateWorkflows(workflows) {
-    const duplicates = findDuplicateWorkflows(workflows);
-    for (const duplicate of duplicates) {
-        const versionStr = duplicate.version
-            ? ` (version: ${duplicate.version})`
-            : "";
-        consola.warn(`Duplicate workflow detected: "${duplicate.name}"${versionStr}`);
-        consola.warn("Multiple files export a workflow with the same name and version.");
-    }
-}
 /**
  * Print discovered workflows to the console.
  * @param workflows - Array of discovered workflows
  */
 function printDiscoveredWorkflows(workflows) {
     consola.log("");
-    consola.info(`Discovered ${String(workflows.length)} workflow(s):`);
+    consola.info(`Found ${String(workflows.length)} workflow${workflows.length === 1 ? "" : "s"}:`);
     for (const workflow of workflows) {
         const name = workflow.spec.name;
-        const version = workflow.spec.version ?? "unversioned";
-        const versionStr = version === "unversioned" ? "" : ` (version: ${version})`;
-        consola.log(`  • ${name}${versionStr}`);
+        const version = workflow.spec.version;
+        const versionStr = version ? ` (${version})` : "";
+        consola.log(`  • ${name}${versionStr} — ${workflowSources.get(workflow)}`);
     }
 }
 const WORKFLOW_EXTENSIONS = ["ts", "mts", "cts", "js", "mjs", "cjs"];
@@ -480,8 +544,8 @@ function globToRegExp(pattern) {
     return new RegExp(regex);
 }
 /**
- * Check whether a file path matches ignore patterns.
- * @param filePath - Absolute file path
+ * Check whether a file or directory path matches ignore patterns.
+ * @param filePath - Absolute path, with a trailing separator for directories
  * @param baseDir - Base directory for relative matching
  * @param matchers - Compiled regex matchers
  * @returns Whether the file should be ignored
@@ -491,7 +555,11 @@ function isIgnoredFile(filePath, baseDir, matchers) {
         return false;
     const relativePath = normalizeForGlobMatch(path.relative(baseDir, filePath));
     const fileName = path.basename(filePath);
-    return matchers.some((matcher) => matcher.test(relativePath) || matcher.test(fileName));
+    const isDirectory = filePath.endsWith(path.sep);
+    return matchers.some((matcher) => matcher.test(relativePath) ||
+        matcher.test(fileName) ||
+        (isDirectory &&
+            (matcher.test(`${relativePath}/`) || matcher.test(`${fileName}/`))));
 }
 /**
  * Discover workflow files from directories. Recursively scans directories for
@@ -516,19 +584,18 @@ export function discoverWorkflowFiles(dirs, baseDir, ignorePatterns = []) {
             entries = readdirSync(absoluteDir, { withFileTypes: true });
         }
         catch (error) {
-            // doesn't exist or can't be read, skip
-            const errMessage = error instanceof Error ? error.message : String(error);
-            consola.debug(`Failed to read directory: ${absoluteDir} - ${errMessage}`);
-            return;
+            throw new CLIError(`Cannot read workflow directory: ${absoluteDir}`, `${String(error)}\nCorrect config.dirs or make the directory readable.`);
         }
         for (const entry of entries) {
             const fullPath = path.join(absoluteDir, entry.name);
             if (entry.isDirectory()) {
-                scanDirectory(fullPath);
+                if (!isIgnoredFile(`${fullPath}${path.sep}`, baseDir, matchers)) {
+                    scanDirectory(fullPath);
+                }
             }
             else if (entry.isFile() &&
                 WORKFLOW_EXTENSIONS.some((ext) => entry.name.endsWith(`.${ext}`)) &&
-                !entry.name.endsWith(".d.ts") &&
+                !/\.d\.(?:ts|mts|cts)$/.test(entry.name) &&
                 !isIgnoredFile(fullPath, baseDir, matchers)) {
                 discoveredFiles.push(fullPath);
             }
@@ -537,7 +604,7 @@ export function discoverWorkflowFiles(dirs, baseDir, ignorePatterns = []) {
     for (const dir of dirs) {
         scanDirectory(dir);
     }
-    return discoveredFiles;
+    return [...new Set(discoveredFiles)];
 }
 /**
  * Import workflow files and extract workflow exports.
@@ -547,11 +614,11 @@ export function discoverWorkflowFiles(dirs, baseDir, ignorePatterns = []) {
  */
 async function importWorkflows(files) {
     const workflows = [];
-    const jiti = createJiti(import.meta.url);
     for (const file of files) {
         // import the module
         let module;
         try {
+            const jiti = createModuleLoader(file);
             module = await jiti.import(pathToFileURL(file).href);
         }
         catch (error) {
@@ -561,13 +628,13 @@ async function importWorkflows(files) {
         // extract workflow exports (named and default)
         for (const [key, value] of Object.entries(module)) {
             if (isWorkflow(value)) {
-                const workflow = value;
-                workflows.push(workflow);
-                consola.debug(`Found workflow "${workflow.spec.name}" in ${file} (${key})`);
+                workflows.push(value);
+                workflowSources.set(value, path.relative(process.cwd(), file));
+                consola.debug(`Found workflow "${value.spec.name}" in ${file} (${key})`);
             }
         }
     }
-    return workflows;
+    return [...new Set(workflows)];
 }
 /**
  * Discover workflow files and import workflows with common error handling.
@@ -646,24 +713,36 @@ function createConfigFile(configFileName) {
     spinner.stop(`Config written to ${configDestPath}`);
 }
 /**
- * Create hello-world runner file.
- * @param runFileName - The runner filename to write
+ * Write a file under the `openworkflow/` project directory, skipping when a
+ * file with the same name already exists. Progress is surfaced via the clack
+ * spinner using the provided label (e.g. "client file").
+ * @param label - Lowercase label describing the file (used in spinner text)
+ * @param fileName - Filename to write inside `openworkflow/`
+ * @param content - File contents to write when the file does not exist
  */
-function createRunFile(runFileName) {
+function writeWorkflowFileIfMissing(label, fileName, content) {
     const spinner = p.spinner();
     const workflowsDir = path.join(process.cwd(), "openworkflow");
     if (!existsSync(workflowsDir)) {
         mkdirSync(workflowsDir, { recursive: true });
     }
-    const runDestPath = path.join(workflowsDir, runFileName);
-    if (existsSync(runDestPath)) {
-        spinner.start("Checking hello-world runner...");
-        spinner.stop(`Hello-world runner already exists at ${runDestPath}`);
+    const destPath = path.join(workflowsDir, fileName);
+    if (existsSync(destPath)) {
+        spinner.start(`Checking ${label}...`);
+        const capitalized = label.charAt(0).toUpperCase() + label.slice(1);
+        spinner.stop(`${capitalized} already exists at ${destPath}`);
         return;
     }
-    spinner.start("Creating hello-world runner...");
-    writeFileSync(runDestPath, HELLO_WORLD_RUNNER, "utf8");
-    spinner.stop(`Created hello-world runner at ${runDestPath}`);
+    spinner.start(`Creating ${label}...`);
+    writeFileSync(destPath, content, "utf8");
+    spinner.stop(`Created ${label} at ${destPath}`);
+}
+/**
+ * Create hello-world runner file.
+ * @param runFileName - The runner filename to write
+ */
+function createRunFile(runFileName) {
+    writeWorkflowFileIfMissing("hello-world runner", runFileName, HELLO_WORLD_RUNNER);
 }
 /**
  * Create client file.
@@ -671,41 +750,14 @@ function createRunFile(runFileName) {
  * @param clientFileName - The client filename to write
  */
 function createClientFile(backendChoice, clientFileName) {
-    const spinner = p.spinner();
-    const workflowsDir = path.join(process.cwd(), "openworkflow");
-    if (!existsSync(workflowsDir)) {
-        mkdirSync(workflowsDir, { recursive: true });
-    }
-    const clientDestPath = path.join(workflowsDir, clientFileName);
-    if (existsSync(clientDestPath)) {
-        spinner.start("Checking client file...");
-        spinner.stop(`Client file already exists at ${clientDestPath}`);
-        return;
-    }
-    spinner.start("Creating client file...");
-    const clientTemplate = getClientTemplate(backendChoice);
-    writeFileSync(clientDestPath, clientTemplate, "utf8");
-    spinner.stop(`Created client file at ${clientDestPath}`);
+    writeWorkflowFileIfMissing("client file", clientFileName, getClientTemplate(backendChoice));
 }
 /**
  * Create example workflow.
  * @param exampleWorkflowFileName - The example workflow filename to write
  */
 function createExampleWorkflow(exampleWorkflowFileName) {
-    const spinner = p.spinner();
-    const workflowsDir = path.join(process.cwd(), "openworkflow");
-    if (!existsSync(workflowsDir)) {
-        mkdirSync(workflowsDir, { recursive: true });
-    }
-    const helloWorldDestPath = path.join(workflowsDir, exampleWorkflowFileName);
-    if (existsSync(helloWorldDestPath)) {
-        spinner.start("Checking example (hello-world) workflow...");
-        spinner.stop(`Example (hello-world) workflow already exists at ${helloWorldDestPath}`);
-        return;
-    }
-    spinner.start("Creating example (hello-world) workflow...");
-    writeFileSync(helloWorldDestPath, HELLO_WORLD_WORKFLOW, "utf8");
-    spinner.stop(`Created example (hello-world) workflow at ${helloWorldDestPath}`);
+    writeWorkflowFileIfMissing("example (hello-world) workflow", exampleWorkflowFileName, HELLO_WORLD_WORKFLOW);
 }
 /**
  * Update .gitignore for SQLite.
@@ -718,8 +770,8 @@ function updateGitignoreForSqlite() {
     const gitignorePath = path.join(process.cwd(), ".gitignore");
     const spinner = p.spinner();
     spinner.start("Updating .gitignore...");
-    const result = ensureGitignoreEntry(gitignorePath, "openworkflow/backend.db*");
-    spinner.stop(result.added
+    const added = ensureGitignoreEntry(gitignorePath, "openworkflow/backend.db*");
+    spinner.stop(added
         ? "Added openworkflow/backend.db* to .gitignore"
         : "openworkflow/backend.db* already in .gitignore");
 }
@@ -737,7 +789,7 @@ function addWorkerScriptToPackageJson() {
         const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
         packageJson.scripts ??= {};
         packageJson.scripts["worker"] = "npx @openworkflow/cli worker start";
-        writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n", "utf8");
+        writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
         spinner.stop('Added "worker" script to package.json');
     }
     catch {
@@ -745,38 +797,33 @@ function addWorkerScriptToPackageJson() {
         consola.warn("Could not add worker script to package.json");
     }
 }
+/**
+ * Append a line to a file if no existing line matches. Creates the file if it
+ * doesn't exist.
+ * @param filePath - Path to the file
+ * @param line - Line to append (without a trailing newline)
+ * @param matchesExisting - Predicate that returns true when an existing line
+ * should be treated as already representing `line`
+ * @returns Whether the line was appended
+ */
+function appendLineIfMissing(filePath, line, matchesExisting) {
+    const content = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    if (content.split("\n").some((existing) => matchesExisting(existing))) {
+        return false;
+    }
+    const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+    writeFileSync(filePath, `${content}${separator}${line}\n`, "utf8");
+    return true;
+}
 /**
  * Ensure a specific entry exists in a .gitignore file. Creates the file if it
  * doesn't exist, appends the entry if not present.
  * @param gitignorePath - Path to the .gitignore file
  * @param entry - The entry to add (e.g. "openworkflow/backend.db*")
- * @returns Object indicating whether the entry was added or already existed
+ * @returns Whether the entry was appended
  */
 function ensureGitignoreEntry(gitignorePath, entry) {
-    const fileExists = existsSync(gitignorePath);
-    let content = "";
-    if (fileExists) {
-        content = readFileSync(gitignorePath, "utf8");
-    }
-    // check if entry already exists
-    const lines = content.split("\n");
-    const hasEntry = lines.some((line) => line.trim() === entry);
-    if (hasEntry) {
-        return { added: false, created: false };
-    }
-    // add entry to .gitignore
-    let newContent;
-    if (content === "") {
-        newContent = `${entry}\n`;
-    }
-    else if (content.endsWith("\n")) {
-        newContent = `${content}${entry}\n`;
-    }
-    else {
-        newContent = `${content}\n${entry}\n`;
-    }
-    writeFileSync(gitignorePath, newContent, "utf8");
-    return { added: true, created: !fileExists };
+    return appendLineIfMissing(gitignorePath, entry, (line) => line.trim() === entry);
 }
 /**
  * Add OPENWORKFLOW_POSTGRES_URL to .env file.
@@ -785,22 +832,36 @@ function updateEnvForPostgres() {
     const envPath = path.join(process.cwd(), ".env");
     const spinner = p.spinner();
     spinner.start("Updating .env...");
-    const result = ensureEnvEntry(envPath, "OPENWORKFLOW_POSTGRES_URL", "postgresql://user:password@localhost:5432/openworkflow");
-    spinner.stop(result.added
+    const added = ensureEnvEntry(envPath, "OPENWORKFLOW_POSTGRES_URL", "postgresql://user:password@localhost:5432/openworkflow");
+    spinner.stop(added
         ? "Added OPENWORKFLOW_POSTGRES_URL to .env"
         : "OPENWORKFLOW_POSTGRES_URL already in .env");
 }
 /**
- * Load CLI config after loading .env, and wrap errors for user-facing output.
- * @param configPath - Optional explicit config file path
- * @returns Loaded config and metadata.
+ * Find the config and load its environment without importing it.
+ * @param options - Config and environment file paths
+ * @returns Config path, if found.
  */
-async function loadConfigWithEnv(configPath) {
-    loadDotenv({ quiet: true });
+function findConfigWithEnv(options) {
+    const { envFile } = options;
+    const configPath = options.config
+        ? path.resolve(options.config)
+        : findConfigFile();
+    const baseDir = configPath ? path.dirname(configPath) : process.cwd();
+    const { error } = loadDotenv({
+        path: envFile ?? path.join(baseDir, ".env"),
+        quiet: true,
+    });
+    if (envFile !== undefined && error) {
+        throw new CLIError(`Failed to load environment file: ${envFile}`, error.message);
+    }
+    return configPath;
+}
+// Load the environment before importing config for commands that use it.
+async function loadConfigWithEnv(options) {
+    const configPath = findConfigWithEnv(options);
     try {
-        return configPath
-            ? await loadConfigFromPath(configPath)
-            : await loadConfig();
+        return await loadConfigFromPath(configPath ?? "openworkflow.config.ts");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -824,16 +885,24 @@ function readPackageJsonForDoctor() {
         return null;
     }
 }
+/**
+ * Pick the script file extension for generated files based on whether the
+ * project uses TypeScript.
+ * @param packageJson - Parsed package.json (or null if missing)
+ * @returns ".ts" when TypeScript is a dependency, otherwise ".js"
+ */
+function getScriptExtension(packageJson) {
+    return packageJson && hasDependency(packageJson, "typescript")
+        ? ".ts"
+        : ".js";
+}
 /**
  * Determine the config filename to write during init.
  * @param packageJson - Parsed package.json (or null if missing)
  * @returns The config file name to create
  */
 export function getConfigFileName(packageJson) {
-    if (packageJson && hasDependency(packageJson, "typescript")) {
-        return "openworkflow.config.ts";
-    }
-    return "openworkflow.config.js";
+    return `openworkflow.config${getScriptExtension(packageJson)}`;
 }
 /**
  * Determine the example workflow filename to write during init.
@@ -841,9 +910,7 @@ export function getConfigFileName(packageJson) {
  * @returns The example workflow file name to create
  */
 export function getExampleWorkflowFileName(packageJson) {
-    const configFileName = getConfigFileName(packageJson);
-    const extension = path.extname(configFileName) || ".js";
-    return `hello-world${extension}`;
+    return `hello-world${getScriptExtension(packageJson)}`;
 }
 /**
  * Determine the hello-world runner filename to write during init.
@@ -851,9 +918,7 @@ export function getExampleWorkflowFileName(packageJson) {
  * @returns The runner file name to create
  */
 export function getRunFileName(packageJson) {
-    const configFileName = getConfigFileName(packageJson);
-    const extension = path.extname(configFileName) || ".js";
-    return `hello-world.run${extension}`;
+    return `hello-world.run${getScriptExtension(packageJson)}`;
 }
 /**
  * Determine the client filename to write during init.
@@ -861,9 +926,7 @@ export function getRunFileName(packageJson) {
  * @returns The client file name to create
  */
 export function getClientFileName(packageJson) {
-    const configFileName = getConfigFileName(packageJson);
-    const extension = path.extname(configFileName) || ".js";
-    return `client${extension}`;
+    return `client${getScriptExtension(packageJson)}`;
 }
 /**
  * Check whether a dependency is declared in package.json.
@@ -875,71 +938,18 @@ function hasDependency(packageJson, name) {
     return Boolean(packageJson.dependencies?.[name] ?? packageJson.devDependencies?.[name]);
 }
 /**
- * Warn when the configured backend is missing its package.
- * @param backendName - Configured backend name.
- * @param packageJson - Parsed package.json.
- */
-function warnIfMissingBackendPackage(backendName, packageJson) {
-    const backendNameLower = backendName.toLowerCase();
-    const isPostgres = backendNameLower.includes("postgres");
-    const isSqlite = backendNameLower.includes("sqlite");
-    if ((isPostgres || isSqlite) && !hasDependency(packageJson, "openworkflow")) {
-        consola.warn(`Backend is ${backendName} but openworkflow is not installed.`);
-    }
-    if (isPostgres && !hasDependency(packageJson, "postgres")) {
-        consola.warn(`Backend is ${backendName} but the postgres driver is not installed.`);
-    }
-}
-/**
- * Warn when TypeScript is installed but tsconfig.json is missing.
- * @param packageJson - Parsed package.json.
- */
-function warnIfMissingTsconfig(packageJson) {
-    if (!hasDependency(packageJson, "typescript")) {
-        return;
-    }
-    const tsconfigPath = path.join(process.cwd(), "tsconfig.json");
-    if (!existsSync(tsconfigPath)) {
-        consola.warn("TypeScript is installed but no tsconfig.json was found.");
-    }
-}
-/**
- * Ensure a specific environment variable exists in a .env file. Creates the file if it
- * doesn't exist, appends the variable if not present.
+ * Ensure a specific environment variable exists in a .env file. Creates the
+ * file if it doesn't exist, appends the variable if not present.
  * @param envPath - Path to the .env file
  * @param key - The environment variable key (e.g. "OPENWORKFLOW_POSTGRES_URL")
  * @param value - The default value for the environment variable
- * @returns Object indicating whether the entry was added or already existed
+ * @returns Whether the entry was appended
  */
 function ensureEnvEntry(envPath, key, value) {
-    const fileExists = existsSync(envPath);
-    let content = "";
-    if (fileExists) {
-        content = readFileSync(envPath, "utf8");
-    }
-    // check if key already exists (looking for KEY= at start of line)
-    const lines = content.split("\n");
-    const hasKey = lines.some((line) => {
+    return appendLineIfMissing(envPath, `${key}=${value}`, (line) => {
         const trimmed = line.trim();
         return trimmed.startsWith(`${key}=`) || trimmed.startsWith(`${key} =`);
     });
-    if (hasKey) {
-        return { added: false, created: false };
-    }
-    // add entry to .env
-    let newContent;
-    const envEntry = `${key}=${value}`;
-    if (content === "") {
-        newContent = `${envEntry}\n`;
-    }
-    else if (content.endsWith("\n")) {
-        newContent = `${content}${envEntry}\n`;
-    }
-    else {
-        newContent = `${content}\n${envEntry}\n`;
-    }
-    writeFileSync(envPath, newContent, "utf8");
-    return { added: true, created: !fileExists };
 }
 /**
  * Validate a numeric option is a positive integer.

package/dist/config.d.ts

@@ -46,5 +46,11 @@ export declare function loadConfigFromPath(configPath: string, startDir?: string
  * @returns The loaded configuration and metadata
  */
 export declare function loadConfig(startDir?: string): Promise<LoadedConfig>;
+/**
+ * Find the nearest config without executing it, so its environment can load first.
+ * @param startDir - Directory to search from
+ * @returns Config path, if found
+ */
+export declare function findConfigFile(startDir?: string): string | undefined;
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAE3E;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,CAKvB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAyBzE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAE3E;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,CAKvB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAgB,GAAG,MAAM,GAAG,SAAS,CAyB3E"}

package/dist/config.js

@@ -1,4 +1,4 @@
-import { createJiti } from "jiti";
+import { createModuleLoader } from "./module-loader.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -12,7 +12,6 @@ export function defineConfig(config) {
 }
 const CONFIG_NAME = "openworkflow.config";
 const CONFIG_EXTENSIONS = ["ts", "mts", "cts", "js", "mjs", "cjs"];
-const jiti = createJiti(import.meta.url);
 /**
  * Load OpenWorkflow config from an explicit path.
  * @param configPath - Explicit config file path
@@ -34,15 +33,24 @@ export async function loadConfigFromPath(configPath, startDir) {
  * @returns The loaded configuration and metadata
  */
 export async function loadConfig(startDir) {
-    let currentDir = path.resolve(startDir ?? process.cwd());
+    const configFile = findConfigFile(startDir);
+    return configFile ? importConfigFile(configFile) : getEmptyLoadedConfig();
+}
+/**
+ * Find the nearest config without executing it, so its environment can load first.
+ * @param startDir - Directory to search from
+ * @returns Config path, if found
+ */
+export function findConfigFile(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
     // search up the directory tree
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
     while (true) {
         for (const ext of CONFIG_EXTENSIONS) {
             const fileName = `${CONFIG_NAME}.${ext}`;
             const filePath = path.join(currentDir, fileName);
             if (existsSync(filePath)) {
-                return await importConfigFile(filePath);
+                return filePath;
             }
         }
         const parentDir = path.dirname(currentDir);
@@ -52,7 +60,7 @@ export async function loadConfig(startDir) {
         }
         currentDir = parentDir;
     }
-    return getEmptyLoadedConfig();
+    return undefined;
 }
 /**
  * Import a config file and wrap load errors with a stable message.
@@ -61,17 +69,23 @@ export async function loadConfig(startDir) {
  */
 async function importConfigFile(filePath) {
     try {
+        const jiti = createModuleLoader(filePath, { tryNative: false }); // bun compatibility
         const fileUrl = pathToFileURL(filePath).href;
         const config = await jiti.import(fileUrl, {
             default: true,
         });
+        if (typeof config !== "object" || config === null) {
+            throw new Error("Config must export an object.");
+        }
         return {
-            config,
+            config: config,
             configFile: filePath,
         };
     }
     catch (error) {
-        throw new Error(`Failed to load config file ${filePath}: ${String(error)}`);
+        throw new Error(`Failed to load config file ${filePath}: ${String(error)}`, {
+            cause: error,
+        });
     }
 }
 /**

package/dist/errors.d.ts

@@ -5,6 +5,11 @@ export declare class CLIError extends Error {
     readonly detail: string | undefined;
     constructor(message: string, detail?: string);
 }
+/**
+ * Finish writing CLI output before exiting, including when handles remain open.
+ * @param code - Process exit code
+ */
+export declare function exit(code: number): Promise<never>;
 /**
  * Wraps a CLI action / handler function with error handling that catches
  * errors, prints them to the console, then exits.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../errors.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,EACnD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACvC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAoB/B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../errors.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7C;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,EACnD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACvC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAiB/B"}

package/dist/errors.js

@@ -11,6 +11,17 @@ export class CLIError extends Error {
         this.detail = detail;
     }
 }
+/**
+ * Finish writing CLI output before exiting, including when handles remain open.
+ * @param code - Process exit code
+ */
+export async function exit(code) {
+    await Promise.all([process.stdout, process.stderr].map((stream) => new Promise((resolve) => {
+        stream.end(resolve);
+    })));
+    // oxlint-disable-next-line unicorn/no-process-exit
+    process.exit(code);
+}
 /**
  * Wraps a CLI action / handler function with error handling that catches
  * errors, prints them to the console, then exits.
@@ -24,19 +35,15 @@ export function withErrorHandling(fn) {
         }
         catch (error) {
             if (error instanceof CLIError) {
-                consola.error(error.message);
-                if (error.detail)
-                    consola.info(error.detail);
-                // eslint-disable-next-line unicorn/no-process-exit
-                process.exit(1);
+                consola.error([error.message, error.detail].filter(Boolean).join("\n"));
+                return exit(1);
             }
             const message = error instanceof Error ? error.message : String(error);
             consola.error(`Unexpected error: ${message}`);
             if (error instanceof Error && error.stack) {
                 consola.debug(error.stack);
             }
-            // eslint-disable-next-line unicorn/no-process-exit
-            process.exit(1);
+            return exit(1);
         }
     };
 }

package/dist/module-loader.d.ts

@@ -0,0 +1,9 @@
+import { type Jiti, type JitiOptions } from "jiti";
+/**
+ * Create a loader using the requested file's nearest tsconfig when available.
+ * @param filePath - Absolute path to the file being loaded.
+ * @param options - Runtime import options.
+ * @returns A loader with optional TypeScript path resolution.
+ */
+export declare function createModuleLoader(filePath: string, options?: JitiOptions): Jiti;
+//# sourceMappingURL=module-loader.d.ts.map

package/dist/module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../module-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,MAAM,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,IAAI,CAQN"}

package/dist/module-loader.js

@@ -0,0 +1,17 @@
+import { createJiti } from "jiti";
+/**
+ * Create a loader using the requested file's nearest tsconfig when available.
+ * @param filePath - Absolute path to the file being loaded.
+ * @param options - Runtime import options.
+ * @returns A loader with optional TypeScript path resolution.
+ */
+export function createModuleLoader(filePath, options = {}) {
+    try {
+        return createJiti(filePath, { ...options, tsconfigPaths: true });
+    }
+    catch {
+        // Deployments may omit development dependencies referenced by tsconfig.
+        // Fall back before executing user code so ordinary imports still work.
+        return createJiti(filePath, { ...options, tsconfigPaths: false });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openworkflow/cli",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {
@@ -27,18 +27,18 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@clack/prompts": "^1.2.0",
-    "commander": "^14.0.3",
+    "@clack/prompts": "^1.8.0",
+    "commander": "^15.0.0",
     "consola": "^3.4.2",
-    "dotenv": "^17.4.1",
-    "jiti": "^2.6.1",
-    "nypm": "^0.6.5"
+    "dotenv": "^17.4.2",
+    "jiti": "^2.7.0",
+    "nypm": "^0.6.10"
   },
   "devDependencies": {
     "openworkflow": "*",
-    "vitest": "^4.0.18"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
-    "openworkflow": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0"
+    "openworkflow": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0"
   }
 }