@openworkflow/cli 0.4.5 → 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,CAwHtE;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;AA8OD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAAO,GAC5B,MAAM,EAAE,CA4CV;AAwVD,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;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"}
+{"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,12 +41,21 @@ 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,
@@ -54,71 +64,84 @@ export async function init(options = {}) {
             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))
+    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,
-    });
+    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);
@@ -136,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.");
     }
@@ -208,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(", ")}`);
@@ -216,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);
         }
@@ -231,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;
     }
 }
@@ -274,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.");
     }
@@ -320,9 +383,25 @@ export async function dashboard(options = {}) {
  */
 function cancelSetup() {
     p.cancel("Setup canceled.");
-    // eslint-disable-next-line unicorn/no-process-exit
+    // 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
@@ -354,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;
@@ -382,29 +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) {
-        consola.warn(`Duplicate workflow detected: ${formatWorkflowIdentity(duplicate.name, duplicate.version)}`);
-        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"];
@@ -476,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
@@ -487,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
@@ -512,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);
             }
@@ -533,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.
@@ -543,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) {
@@ -558,11 +629,12 @@ async function importWorkflows(files) {
         for (const [key, value] of Object.entries(module)) {
             if (isWorkflow(value)) {
                 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.
@@ -717,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 {
@@ -766,16 +838,30 @@ function updateEnvForPostgres() {
         : "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);
@@ -851,35 +937,6 @@ export function getClientFileName(packageJson) {
 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.

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, { tryNative: false }); // bun compatibility
 /**
  * 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.5",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {
@@ -27,18 +27,18 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
+    "@clack/prompts": "^1.8.0",
     "commander": "^15.0.0",
     "consola": "^3.4.2",
     "dotenv": "^17.4.2",
     "jiti": "^2.7.0",
-    "nypm": "^0.6.8"
+    "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"
   }
 }