@openworkflow/cli 0.3.1 → 0.4.1

package/dist/cli.js

@@ -3,22 +3,24 @@
 import { dashboard, doctor, getVersion, init, workerStart, } from "./commands.js";
 import { withErrorHandling } from "./errors.js";
 import { Command } from "commander";
-// openworkflow | ow
+// openworkflow
 const program = new Command();
 program
     .name("openworkflow")
-    .alias("ow")
     .description("OpenWorkflow CLI - learn more at https://openworkflow.dev")
+    .usage("<command> [options]")
     .version(getVersion());
 // init
 program
     .command("init")
     .description("initialize OpenWorkflow")
+    .option("--config <path>", "path to OpenWorkflow config file")
     .action(withErrorHandling(init));
 // doctor
 program
     .command("doctor")
     .description("check configuration and list available workflows")
+    .option("--config <path>", "path to OpenWorkflow config file")
     .action(withErrorHandling(doctor));
 // worker
 const workerCmd = program.command("worker").description("manage workers");
@@ -27,10 +29,12 @@ workerCmd
     .command("start")
     .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")
     .action(withErrorHandling(workerStart));
 // dashboard
 program
     .command("dashboard")
     .description("start the dashboard to view workflow runs")
+    .option("--config <path>", "path to OpenWorkflow config file")
     .action(withErrorHandling(dashboard));
 await program.parseAsync(process.argv);

package/dist/commands.d.ts

@@ -1,23 +1,34 @@
 import { WorkerConfig } from "./config.js";
+interface CommandOptions {
+    config?: string;
+}
 /**
  * openworkflow -V | --version
  * @returns the version string, or "-" if it cannot be determined
  */
 export declare function getVersion(): string;
-/** openworkflow init */
-export declare function init(): Promise<void>;
-/** openworkflow doctor */
-export declare function doctor(): Promise<void>;
+/**
+ * openworkflow init
+ * @param options - Command options
+ */
+export declare function init(options?: CommandOptions): Promise<void>;
+/**
+ * openworkflow doctor
+ * @param options - Command options
+ */
+export declare function doctor(options?: CommandOptions): Promise<void>;
+export type WorkerStartOptions = WorkerConfig & CommandOptions;
 /**
  * openworkflow worker start
- * @param cliOptions - Worker config overrides
+ * @param options - Worker config and command options
  */
-export declare function workerStart(cliOptions: WorkerConfig): Promise<void>;
+export declare function workerStart(options?: WorkerStartOptions): Promise<void>;
 /**
  * openworkflow dashboard
  * Starts the dashboard by delegating to `@openworkflow/dashboard` via npx.
+ * @param options - Command options
  */
-export declare function dashboard(): Promise<void>;
+export declare function dashboard(options?: CommandOptions): Promise<void>;
 /**
  * Discover workflow files from directories. Recursively scans directories for
  * workflow files with supported extensions (.ts, .js, .mjs, .cjs).

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAiCvD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAoBnC;AAED,wBAAwB;AACxB,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmI1C;AAED,0BAA0B;AAC1B,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAkD5C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsEzE;AAED;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CA0D/C;AAwOD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAAO,GAC5B,MAAM,EAAE,CA4CV;AAuVD,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,EAAE,YAAY,EAAkC,MAAM,aAAa,CAAC;AAiC3E,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;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;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2D3E;AAwOD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAAO,GAC5B,MAAM,EAAE,CA4CV;AA8VD,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"}

package/dist/commands.js

@@ -1,4 +1,4 @@
-import { loadConfig } from "./config.js";
+import { loadConfig, loadConfigFromPath } from "./config.js";
 import { CLIError } from "./errors.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";
@@ -36,10 +36,14 @@ export function getVersion() {
     }
     return "-";
 }
-/** openworkflow init */
-export async function init() {
+/**
+ * openworkflow init
+ * @param options - Command options
+ */
+export async function init(options = {}) {
+    const configPath = options.config;
     p.intro("Initializing OpenWorkflow...");
-    const { configFile } = await loadConfigWithEnv();
+    const { configFile } = await loadConfigWithEnv(configPath);
     let configFileToDelete = null;
     if (configFile) {
         const shouldOverride = await p.confirm({
@@ -89,7 +93,7 @@ export async function init() {
     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 = getConfigFileName(packageJson);
+    const configFileName = configPath ?? getConfigFileName(packageJson);
     const clientFileName = getClientFileName(packageJson);
     const exampleWorkflowFileName = getExampleWorkflowFileName(packageJson);
     const runFileName = getRunFileName(packageJson);
@@ -141,12 +145,16 @@ export async function init() {
     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!");
 }
-/** openworkflow doctor */
-export async function doctor() {
+/**
+ * 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();
+    const { config, configFile } = await loadConfigWithEnv(configPath);
     if (!configFile) {
-        throw new CLIError("No config file found.", "Run `ow init` to create a config file.");
+        throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file.");
     }
     const backend = config.backend;
     try {
@@ -181,13 +189,14 @@ export async function doctor() {
 }
 /**
  * openworkflow worker start
- * @param cliOptions - Worker config overrides
+ * @param options - Worker config and command options
  */
-export async function workerStart(cliOptions) {
+export async function workerStart(options = {}) {
+    const { config: configPath, ...workerConfig } = options;
     consola.start("Starting worker...");
-    const { config, configFile } = await loadConfigWithEnv();
+    const { config, configFile } = await loadConfigWithEnv(configPath);
     if (!configFile) {
-        throw new CLIError("No config file found.", "Run `ow init` to create a config file.");
+        throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file.");
     }
     const backend = config.backend;
     const ow = new OpenWorkflow({ backend });
@@ -216,7 +225,7 @@ export async function workerStart(cliOptions) {
         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, cliOptions);
+        const workerOptions = mergeDefinedOptions(config.worker, workerConfig);
         if (workerOptions.concurrency !== undefined) {
             assertPositiveInteger("concurrency", workerOptions.concurrency);
         }
@@ -238,12 +247,14 @@ export async function workerStart(cliOptions) {
 /**
  * openworkflow dashboard
  * Starts the dashboard by delegating to `@openworkflow/dashboard` via npx.
+ * @param options - Command options
  */
-export async function dashboard() {
+export async function dashboard(options = {}) {
+    const configPath = options.config;
     consola.start("Starting dashboard...");
-    const { configFile } = await loadConfigWithEnv();
+    const { configFile } = await loadConfigWithEnv(configPath);
     if (!configFile) {
-        throw new CLIError("No config file found.", "Run `ow init` to create a config file before starting the dashboard.");
+        throw new CLIError("No config file found.", "Run `npx @openworkflow/cli init` to create a config file before starting the dashboard.");
     }
     consola.info(`Using config: ${configFile}`);
     // eslint-disable-next-line sonarjs/no-os-command-from-path
@@ -596,7 +607,9 @@ function getDevDependenciesToInstall() {
 function createConfigFile(configFileName) {
     const spinner = p.spinner();
     spinner.start("Writing config...");
-    const configDestPath = path.join(process.cwd(), configFileName);
+    const configDestPath = path.resolve(process.cwd(), configFileName);
+    // mkdir if the user specified a config file, and they want it in a dir
+    mkdirSync(path.dirname(configDestPath), { recursive: true });
     writeFileSync(configDestPath, CONFIG, "utf8");
     spinner.stop(`Config written to ${configDestPath}`);
 }
@@ -747,12 +760,15 @@ function updateEnvForPostgres() {
 }
 /**
  * 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.
  */
-async function loadConfigWithEnv() {
+async function loadConfigWithEnv(configPath) {
     loadDotenv({ quiet: true });
     try {
-        return await loadConfig();
+        return configPath
+            ? await loadConfigFromPath(configPath)
+            : await loadConfig();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/config.d.ts

@@ -30,6 +30,13 @@ interface LoadedConfig {
     config: OpenWorkflowConfig;
     configFile: string | undefined;
 }
+/**
+ * Load OpenWorkflow config from an explicit path.
+ * @param configPath - Explicit config file path
+ * @param startDir - Optional base directory for resolving relative paths
+ * @returns The loaded configuration and metadata
+ */
+export declare function loadConfigFromPath(configPath: string, startDir?: string): Promise<LoadedConfig>;
 /**
  * Load the OpenWorkflow config at openworkflow.config.{ts,mts,cts,js,mjs,cjs}.
  * Searches up the directory tree from the starting directory to find the

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;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA8CzE"}
+{"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"}

package/dist/config.js

@@ -13,6 +13,18 @@ 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
+ * @param startDir - Optional base directory for resolving relative paths
+ * @returns The loaded configuration and metadata
+ */
+export async function loadConfigFromPath(configPath, startDir) {
+    const filePath = path.resolve(startDir ?? process.cwd(), configPath);
+    return existsSync(filePath)
+        ? importConfigFile(filePath)
+        : getEmptyLoadedConfig();
+}
 /**
  * Load the OpenWorkflow config at openworkflow.config.{ts,mts,cts,js,mjs,cjs}.
  * Searches up the directory tree from the starting directory to find the
@@ -30,19 +42,7 @@ export async function loadConfig(startDir) {
             const fileName = `${CONFIG_NAME}.${ext}`;
             const filePath = path.join(currentDir, fileName);
             if (existsSync(filePath)) {
-                try {
-                    const fileUrl = pathToFileURL(filePath).href;
-                    const config = await jiti.import(fileUrl, {
-                        default: true,
-                    });
-                    return {
-                        config,
-                        configFile: filePath,
-                    };
-                }
-                catch (error) {
-                    throw new Error(`Failed to load config file ${filePath}: ${String(error)}`);
-                }
+                return await importConfigFile(filePath);
             }
         }
         const parentDir = path.dirname(currentDir);
@@ -52,6 +52,33 @@ export async function loadConfig(startDir) {
         }
         currentDir = parentDir;
     }
+    return getEmptyLoadedConfig();
+}
+/**
+ * Import a config file and wrap load errors with a stable message.
+ * @param filePath - Absolute config file path.
+ * @returns Loaded config metadata.
+ */
+async function importConfigFile(filePath) {
+    try {
+        const fileUrl = pathToFileURL(filePath).href;
+        const config = await jiti.import(fileUrl, {
+            default: true,
+        });
+        return {
+            config,
+            configFile: filePath,
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to load config file ${filePath}: ${String(error)}`);
+    }
+}
+/**
+ * Return an empty config result when no config file is found.
+ * @returns Empty config metadata.
+ */
+function getEmptyLoadedConfig() {
     return {
         // not great, but meant to match the c12 api since that is what was used in
         // the initial implementation of loadConfig

package/dist/skills.d.ts

@@ -0,0 +1,61 @@
+declare const SUPPORTED_SKILL_AGENTS: readonly ["codex", "claude"];
+export type SkillAgent = (typeof SUPPORTED_SKILL_AGENTS)[number];
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+}
+export interface InstallOpenWorkflowSkillsOptions {
+    agent: SkillAgent;
+    force: boolean;
+    requestedSkillNames?: string[];
+    targetDirectory?: string;
+    workspaceDirectory: string;
+}
+export interface InstalledSkill {
+    name: string;
+    overwritten: boolean;
+    path: string;
+}
+export interface InstallOpenWorkflowSkillsResult {
+    installedSkills: InstalledSkill[];
+    targetDirectory: string;
+}
+/**
+ * True when the provided value is a supported skill agent.
+ * @param value - Agent value from CLI options
+ * @returns Whether the value is supported
+ */
+export declare function isSkillAgent(value: string): value is SkillAgent;
+/**
+ * Returns the default skill directory for an agent.
+ * @param agent - Skill agent
+ * @returns Relative target directory
+ */
+export declare function getDefaultSkillDirectory(agent: SkillAgent): string;
+/**
+ * List available OpenWorkflow skills.
+ * @returns Skill catalog entries
+ */
+export declare function listOpenWorkflowSkills(): SkillCatalogEntry[];
+/**
+ * Resolve requested skill names, defaulting to all.
+ * @param requestedSkillNames - Skill names from CLI options
+ * @returns Unique, validated skill names
+ * @throws {Error} When one or more skill names are unknown
+ */
+export declare function resolveSkillNames(requestedSkillNames?: string[]): string[];
+/**
+ * Install OpenWorkflow skills to an agent skill directory.
+ * @param options - Install options
+ * @returns Install result metadata
+ * @throws {Error} When skill names are invalid or files already exist without force
+ */
+export declare function installOpenWorkflowSkills(options: InstallOpenWorkflowSkillsOptions): InstallOpenWorkflowSkillsResult;
+/**
+ * Read a skill file from disk. Used by tests.
+ * @param skillPath - Path to the skill file
+ * @returns File content
+ */
+export declare function readSkillFile(skillPath: string): string;
+export {};
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../skills.ts"],"names":[],"mappings":"AASA,QAAA,MAAM,sBAAsB,8BAA+B,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,+BAA+B;IAC9C,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;CACzB;AAyMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,iBAAiB,EAAE,CAK5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAiB1E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,+BAA+B,CA2CjC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/skills.js

@@ -0,0 +1,286 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+const SUPPORTED_SKILL_AGENTS = ["codex", "claude"];
+const DEFAULT_SKILL_DIRECTORIES = {
+    codex: path.join(".agents", "skills"),
+    claude: path.join(".claude", "skills"),
+};
+const OPENWORKFLOW_SKILLS = [
+    {
+        name: "openworkflow-quickstart",
+        description: "Scaffold, implement, and run durable workflows with the OpenWorkflow CLI.",
+        files: {
+            "SKILL.md": `---
+name: openworkflow-quickstart
+description: Use when a user asks to create, run, or update OpenWorkflow workflows in an app codebase.
+---
+
+# OpenWorkflow Quickstart
+
+Use this skill when the user wants to build or update a workflow quickly.
+
+## Standard flow
+
+1. Confirm the project has OpenWorkflow set up. If not, run \`npx @openworkflow/cli init\`.
+2. Create or update workflow code in \`openworkflow/\` with \`defineWorkflow\`.
+3. Keep side effects inside \`step.run(...)\` calls, and keep step names stable.
+4. Start a worker with \`npx @openworkflow/cli worker start\`.
+5. Trigger the workflow with \`ow.runWorkflow(workflow.spec, input)\`.
+6. Validate setup with \`npx @openworkflow/cli doctor\`.
+
+## Guardrails
+
+- Keep workflow replay deterministic outside of \`step.run\`.
+- Use explicit, descriptive, stable step names.
+- Use \`step.sleep\` for durable waits instead of process timers.
+- Return JSON-serializable values from steps and workflow output.
+
+## Useful commands
+
+\`\`\`bash
+npx @openworkflow/cli init
+npx @openworkflow/cli worker start
+npx @openworkflow/cli doctor
+npx @openworkflow/cli dashboard
+\`\`\`
+`,
+        },
+    },
+    {
+        name: "openworkflow-patterns",
+        description: "Apply durable workflow patterns for retries, idempotency, and versioning.",
+        files: {
+            "SKILL.md": `---
+name: openworkflow-patterns
+description: Use when a user asks for production workflow design patterns in OpenWorkflow.
+---
+
+# OpenWorkflow Patterns
+
+Use this skill for architecture and implementation guidance on durable workflows.
+
+## Patterns to apply
+
+1. Prefer many small \`step.run\` calls over one large step.
+2. Keep external side effects in steps with stable names to preserve memoization.
+3. Use idempotency keys for enqueue endpoints that may be retried.
+4. Use workflow versioning when behavior changes in non-backward-compatible ways.
+5. Use \`step.sleep\` for delays and backoff scheduling.
+
+## Failure handling
+
+- Let transient failures throw from step functions so retries can reschedule runs.
+- Use explicit deadlines for workflows that should fail fast.
+- Add compensation steps for side effects that need rollback behavior.
+
+## Review checklist
+
+- Is workflow code deterministic between checkpoints?
+- Are step names stable across deployments?
+- Are retry expectations documented for each external dependency?
+- Are deadline and workflow cancel paths tested?
+`,
+        },
+    },
+    {
+        name: "openworkflow-sql-inspector",
+        description: "Inspect workflow and step state directly in SQLite or PostgreSQL with read-only SQL.",
+        files: {
+            "SKILL.md": `---
+name: openworkflow-sql-inspector
+description: Use when a user asks why workflows are stuck, slow, failed, or repeatedly retried.
+---
+
+# OpenWorkflow SQL Inspector
+
+Use this skill to answer workflow runtime questions from database state.
+
+## Safety rules
+
+1. Use read-only SQL only.
+2. Do not run INSERT, UPDATE, DELETE, ALTER, DROP, TRUNCATE, or CREATE.
+3. Always add \`LIMIT\` to exploratory queries (default 100).
+4. Redact sensitive values before sharing query output.
+
+## Database notes
+
+- SQLite default path from CLI init: \`openworkflow/backend.db\`.
+- PostgreSQL default schema: \`openworkflow\`.
+- Core tables: \`workflow_runs\`, \`step_attempts\`.
+
+Read [references/sql-queries.md](references/sql-queries.md) for practical query templates.
+`,
+            "references/sql-queries.md": `# SQL Query Templates
+
+## PostgreSQL
+
+Use a read-only transaction for ad hoc inspection:
+
+\`\`\`sql
+BEGIN READ ONLY;
+SELECT
+  namespace_id,
+  id,
+  workflow_name,
+  status,
+  attempts,
+  available_at,
+  deadline_at,
+  created_at,
+  updated_at
+FROM openworkflow.workflow_runs
+ORDER BY created_at DESC
+LIMIT 100;
+COMMIT;
+\`\`\`
+
+Recent step attempts for a workflow run:
+
+\`\`\`sql
+SELECT
+  namespace_id,
+  id,
+  workflow_run_id,
+  step_name,
+  kind,
+  status,
+  started_at,
+  finished_at,
+  created_at
+FROM openworkflow.step_attempts
+WHERE workflow_run_id = $1
+ORDER BY created_at DESC
+LIMIT 200;
+\`\`\`
+
+## SQLite
+
+List recent workflow runs:
+
+\`\`\`sql
+SELECT
+  namespace_id,
+  id,
+  workflow_name,
+  status,
+  attempts,
+  available_at,
+  deadline_at,
+  created_at,
+  updated_at
+FROM workflow_runs
+ORDER BY created_at DESC
+LIMIT 100;
+\`\`\`
+
+List step attempts for one run:
+
+\`\`\`sql
+SELECT
+  namespace_id,
+  id,
+  workflow_run_id,
+  step_name,
+  kind,
+  status,
+  started_at,
+  finished_at,
+  created_at
+FROM step_attempts
+WHERE workflow_run_id = ?
+ORDER BY created_at DESC
+LIMIT 200;
+\`\`\`
+`,
+        },
+    },
+];
+/**
+ * True when the provided value is a supported skill agent.
+ * @param value - Agent value from CLI options
+ * @returns Whether the value is supported
+ */
+export function isSkillAgent(value) {
+    return SUPPORTED_SKILL_AGENTS.includes(value);
+}
+/**
+ * Returns the default skill directory for an agent.
+ * @param agent - Skill agent
+ * @returns Relative target directory
+ */
+export function getDefaultSkillDirectory(agent) {
+    return DEFAULT_SKILL_DIRECTORIES[agent];
+}
+/**
+ * List available OpenWorkflow skills.
+ * @returns Skill catalog entries
+ */
+export function listOpenWorkflowSkills() {
+    return OPENWORKFLOW_SKILLS.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+    }));
+}
+/**
+ * Resolve requested skill names, defaulting to all.
+ * @param requestedSkillNames - Skill names from CLI options
+ * @returns Unique, validated skill names
+ * @throws {Error} When one or more skill names are unknown
+ */
+export function resolveSkillNames(requestedSkillNames) {
+    const requested = requestedSkillNames && requestedSkillNames.length > 0
+        ? requestedSkillNames
+        : OPENWORKFLOW_SKILLS.map((skill) => skill.name);
+    const deduped = [...new Set(requested)];
+    const unknownSkills = deduped.filter((name) => OPENWORKFLOW_SKILLS.every((skill) => skill.name !== name));
+    if (unknownSkills.length > 0) {
+        throw new Error(`Unknown skill name${unknownSkills.length === 1 ? "" : "s"}: ${unknownSkills.join(", ")}`);
+    }
+    return deduped;
+}
+/**
+ * Install OpenWorkflow skills to an agent skill directory.
+ * @param options - Install options
+ * @returns Install result metadata
+ * @throws {Error} When skill names are invalid or files already exist without force
+ */
+export function installOpenWorkflowSkills(options) {
+    const requestedSkillNames = resolveSkillNames(options.requestedSkillNames);
+    const defaultDirectory = getDefaultSkillDirectory(options.agent);
+    const targetDirectory = path.resolve(options.workspaceDirectory, options.targetDirectory ?? defaultDirectory);
+    mkdirSync(targetDirectory, { recursive: true });
+    const installedSkills = [];
+    for (const skillName of requestedSkillNames) {
+        const skill = OPENWORKFLOW_SKILLS.find((item) => item.name === skillName);
+        if (!skill) {
+            continue;
+        }
+        const skillDirectory = path.join(targetDirectory, skill.name);
+        const hadExistingDirectory = existsSync(skillDirectory);
+        if (hadExistingDirectory && !options.force) {
+            throw new Error(`Skill "${skill.name}" already exists at ${skillDirectory}. Use --force to overwrite.`);
+        }
+        if (hadExistingDirectory) {
+            rmSync(skillDirectory, { force: true, recursive: true });
+        }
+        for (const [relativePath, content] of Object.entries(skill.files)) {
+            const destinationPath = path.join(skillDirectory, relativePath);
+            mkdirSync(path.dirname(destinationPath), { recursive: true });
+            writeFileSync(destinationPath, content, "utf8");
+        }
+        installedSkills.push({
+            name: skill.name,
+            overwritten: hadExistingDirectory,
+            path: skillDirectory,
+        });
+    }
+    return { installedSkills, targetDirectory };
+}
+/**
+ * Read a skill file from disk. Used by tests.
+ * @param skillPath - Path to the skill file
+ * @returns File content
+ */
+export function readSkillFile(skillPath) {
+    return readFileSync(skillPath, "utf8");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openworkflow/cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": {
@@ -13,8 +13,7 @@
     }
   },
   "bin": {
-    "openworkflow": "./dist/cli.js",
-    "ow": "./dist/cli.js"
+    "openworkflow": "./dist/cli.js"
   },
   "files": [
     "dist",
@@ -30,15 +29,15 @@
     "@clack/prompts": "^1.0.0",
     "commander": "^14.0.3",
     "consola": "^3.4.2",
-    "dotenv": "^17.2.3",
+    "dotenv": "^17.2.4",
     "jiti": "^2.6.1",
-    "nypm": "^0.6.4"
+    "nypm": "^0.6.5"
   },
   "devDependencies": {
     "openworkflow": "*",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "openworkflow": "^0.6.0"
+    "openworkflow": "^0.6.0 || ^0.7.0"
   }
 }