@ontrails/cli 1.0.0-beta.0

package/dist/output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Output formatting and mode resolution for CLI output.
+ */
+export type OutputMode = 'text' | 'json' | 'jsonl';
+export declare const output: (value: unknown, mode: OutputMode) => void;
+/**
+ * Determine the output mode from parsed CLI flags and environment.
+ *
+ * Resolution order (highest priority wins):
+ * 1. `flags.json === true` -> "json"
+ * 2. `flags.jsonl === true` -> "jsonl"
+ * 3. `flags.output` as string -> validate against OutputMode
+ * 4. `TRAILS_JSON=1` env var -> "json"
+ * 5. `TRAILS_JSONL=1` env var -> "jsonl"
+ * 6. Default: "text"
+ */
+export declare const resolveOutputMode: (flags: Record<string, unknown>) => {
+    mode: OutputMode;
+};
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAiCnD,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,EAAE,MAAM,UAAU,KAAG,IAGzD,CAAC;AAsCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B;IACD,IAAI,EAAE,UAAU,CAAC;CAIlB,CAAC"}

package/dist/output.js

@@ -0,0 +1,82 @@
+/**
+ * Output formatting and mode resolution for CLI output.
+ */
+// ---------------------------------------------------------------------------
+// output()
+// ---------------------------------------------------------------------------
+/**
+ * Write a value to stdout in the specified format.
+ *
+ * - **text**: strings written directly; objects JSON-stringified with 2-space indent
+ * - **json**: always JSON.stringify with 2-space indent
+ * - **jsonl**: arrays emit one JSON line per element; scalars emit one line
+ */
+const outputWriters = {
+    json: (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`),
+    jsonl: (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                process.stdout.write(`${JSON.stringify(item)}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(value)}\n`);
+        }
+    },
+    text: (value) => {
+        if (typeof value === 'string') {
+            process.stdout.write(`${value}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        }
+    },
+};
+export const output = (value, mode) => {
+    const writer = outputWriters[mode];
+    writer(value);
+};
+// ---------------------------------------------------------------------------
+// resolveOutputMode()
+// ---------------------------------------------------------------------------
+const VALID_MODES = new Set(['text', 'json', 'jsonl']);
+/** Resolve mode from flags alone (--json, --jsonl, --output). */
+const resolveFlagMode = (flags) => {
+    if (flags['json'] === true) {
+        return 'json';
+    }
+    if (flags['jsonl'] === true) {
+        return 'jsonl';
+    }
+    if (typeof flags['output'] === 'string' &&
+        VALID_MODES.has(flags['output'])) {
+        return flags['output'];
+    }
+    return undefined;
+};
+/** Resolve mode from environment variables. */
+const resolveEnvMode = () => {
+    if (process.env['TRAILS_JSON'] === '1') {
+        return 'json';
+    }
+    if (process.env['TRAILS_JSONL'] === '1') {
+        return 'jsonl';
+    }
+    return undefined;
+};
+/**
+ * Determine the output mode from parsed CLI flags and environment.
+ *
+ * Resolution order (highest priority wins):
+ * 1. `flags.json === true` -> "json"
+ * 2. `flags.jsonl === true` -> "jsonl"
+ * 3. `flags.output` as string -> validate against OutputMode
+ * 4. `TRAILS_JSON=1` env var -> "json"
+ * 5. `TRAILS_JSONL=1` env var -> "jsonl"
+ * 6. Default: "text"
+ */
+export const resolveOutputMode = (flags) => {
+    const mode = resolveFlagMode(flags) ?? resolveEnvMode() ?? 'text';
+    return { mode };
+};
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

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

package/dist/prompt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Surface-agnostic input resolution contracts for CLI commands.
+ *
+ * The core CLI package does not depend on any concrete prompt library.
+ * Callers can provide a resolver that gathers missing input however they want
+ * (Clack, forms, conversational UI, or no prompting at all).
+ */
+import type { Field } from '@ontrails/core';
+/**
+ * Options passed to an input resolver.
+ *
+ * `isTTY` is provided so callers can override interactivity in tests.
+ */
+export interface ResolveInputOptions {
+    readonly isTTY?: boolean | undefined;
+}
+/**
+ * A resolver that fills in missing values for derived schema fields.
+ *
+ * The resolver receives the current input as field-name keyed values and
+ * returns a merged record with any newly gathered answers.
+ */
+export type InputResolver = (fields: readonly Field[], provided: Record<string, unknown>, options?: ResolveInputOptions) => Promise<Record<string, unknown>>;
+/** Default passthrough resolver for non-interactive execution. */
+export declare const passthroughResolver: InputResolver;
+/** Shared TTY check for resolver implementations. */
+export declare const isInteractive: (options?: ResolveInputOptions) => boolean;
+export type { Field };
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtC,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,aAClB,CAAC;AAEjB,qDAAqD;AACrD,eAAO,MAAM,aAAa,GAAI,UAAU,mBAAmB,KAAG,OACd,CAAC;AAEjD,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/prompt.js

@@ -0,0 +1,12 @@
+/**
+ * Surface-agnostic input resolution contracts for CLI commands.
+ *
+ * The core CLI package does not depend on any concrete prompt library.
+ * Callers can provide a resolver that gathers missing input however they want
+ * (Clack, forms, conversational UI, or no prompting at all).
+ */
+/** Default passthrough resolver for non-interactive execution. */
+export const passthroughResolver = async (_fields, provided) => await provided;
+/** Shared TTY check for resolver implementations. */
+export const isInteractive = (options) => options?.isTTY ?? process.stdin.isTTY ?? false;
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyBH,kEAAkE;AAClE,MAAM,CAAC,MAAM,mBAAmB,GAAkB,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,CAC5E,MAAM,QAAQ,CAAC;AAEjB,qDAAqD;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA6B,EAAW,EAAE,CACtE,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ontrails/cli",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./commander": "./src/commander/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "commander": "^14.0.3",
+    "zod": "catalog:"
+  },
+  "peerDependenciesMeta": {
+    "commander": {
+      "optional": true
+    }
+  }
+}

package/src/__tests__/blaze.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { buildCliCommands } from '../build.js';
+import { toCommander } from '../commander/to-commander.js';
+import { defaultOnResult } from '../on-result.js';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('blaze', () => {
+  test('smoke test: buildCliCommands + toCommander wiring does not throw', () => {
+    const t = trail('ping', {
+      implementation: () => Result.ok('pong'),
+      input: z.object({}),
+    });
+    const app = topo('smoke-test', { ping: t });
+
+    // Reproduce blaze() steps without calling parse()
+    const commands = buildCliCommands(app, {
+      onResult: defaultOnResult,
+    });
+    const program = toCommander(commands, { name: 'smoke-test' });
+
+    expect(program.name()).toBe('smoke-test');
+    expect(program.commands).toHaveLength(1);
+    expect(program.commands[0]?.name()).toBe('ping');
+  });
+
+  test('uses defaultOnResult when none provided', () => {
+    const t = trail('echo', {
+      implementation: (input: { msg: string }) => Result.ok(input.msg),
+      input: z.object({ msg: z.string() }),
+    });
+    const app = topo('default-on-result', { echo: t });
+
+    // buildCliCommands without onResult should still work
+    const commands = buildCliCommands(app, {
+      onResult: defaultOnResult,
+    });
+    const program = toCommander(commands, { name: app.name });
+
+    expect(program.commands).toHaveLength(1);
+    expect(program.commands[0]?.name()).toBe('echo');
+  });
+
+  test('end-to-end: define trail, build commands, execute, verify output', async () => {
+    const written: string[] = [];
+    const originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string) => {
+      written.push(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      const t = trail('greet', {
+        implementation: (input: { name: string }) =>
+          Result.ok(`Hello, ${input.name}!`),
+        input: z.object({ name: z.string() }),
+      });
+      const app = topo('e2e-test', { greet: t });
+
+      const commands = buildCliCommands(app, {
+        onResult: defaultOnResult,
+      });
+
+      // Execute directly (bypassing Commander parse)
+      await commands[0]?.execute({}, { name: 'World' });
+
+      expect(written.join('')).toBe('Hello, World!\n');
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+  });
+});

package/src/__tests__/build.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, createTrailContext, trail, topo } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { ActionResultContext } from '../build.js';
+import { buildCliCommands } from '../build.js';
+import type { AnyTrail } from '../command.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const makeApp = (...trails: AnyTrail[]) => {
+  const mod: Record<string, unknown> = {};
+  for (const t of trails) {
+    mod[t.id] = t;
+  }
+  return topo('test-app', mod);
+};
+
+const requireCommand = (commands: ReturnType<typeof buildCliCommands>) => {
+  const [command] = commands;
+  expect(command).toBeDefined();
+  if (!command) {
+    throw new Error('Expected command');
+  }
+  return command;
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildCliCommands', () => {
+  test('builds commands from a simple app with one trail', () => {
+    const t = trail('greet', {
+      implementation: (input: { name: string }) =>
+        Result.ok(`Hello, ${input.name}`),
+      input: z.object({ name: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+    expect(commands).toHaveLength(1);
+    expect(commands[0]?.name).toBe('greet');
+    expect(commands[0]?.group).toBeUndefined();
+  });
+
+  test('builds grouped subcommands from dotted trail IDs', () => {
+    const show = trail('entity.show', {
+      implementation: (input: { id: string }) => Result.ok({ id: input.id }),
+      input: z.object({ id: z.string() }),
+    });
+    const add = trail('entity.add', {
+      implementation: (input: { name: string }) =>
+        Result.ok({ name: input.name }),
+      input: z.object({ name: z.string() }),
+    });
+    const app = makeApp(show, add);
+    const commands = buildCliCommands(app);
+    expect(commands).toHaveLength(2);
+    expect(commands[0]?.group).toBe('entity');
+    expect(commands[0]?.name).toBe('show');
+    expect(commands[1]?.group).toBe('entity');
+    expect(commands[1]?.name).toBe('add');
+  });
+
+  test('derives flags from input schema', () => {
+    const t = trail('search', {
+      implementation: () => Result.ok([]),
+      input: z.object({
+        limit: z.number().optional(),
+        query: z.string(),
+      }),
+    });
+    const app = makeApp(t);
+    const { flags } = requireCommand(buildCliCommands(app));
+
+    expect(flags).toHaveLength(2);
+    const queryFlag = flags.find((f) => f.name === 'query');
+    const limitFlag = flags.find((f) => f.name === 'limit');
+    expect(queryFlag?.required).toBe(true);
+    expect(limitFlag?.required).toBe(false);
+  });
+
+  test('adds --dry-run for destructive trails', () => {
+    const t = trail('entity.delete', {
+      destructive: true,
+      implementation: () => Result.ok(),
+      input: z.object({ id: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+    const dryRunFlag = commands[0]?.flags.find((f) => f.name === 'dry-run');
+    expect(dryRunFlag).toBeDefined();
+    expect(dryRunFlag?.type).toBe('boolean');
+  });
+
+  test('calls onResult with correct context', async () => {
+    let captured: ActionResultContext | undefined;
+    const t = trail('ping', {
+      implementation: (input: { msg: string }) => Result.ok(input.msg),
+      input: z.object({ msg: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app, {
+      onResult: (ctx) => {
+        captured = ctx;
+        return Promise.resolve();
+      },
+    });
+
+    await commands[0]?.execute({}, { msg: 'hello' });
+
+    expect(captured).toBeDefined();
+    expect(captured?.trail.id).toBe('ping');
+    expect(captured?.input).toEqual({ msg: 'hello' });
+    expect(captured?.result.isOk()).toBe(true);
+  });
+
+  test('validates input before calling implementation', async () => {
+    let implCalled = false;
+    const t = trail('strict', {
+      implementation: () => {
+        implCalled = true;
+        return Result.ok('done');
+      },
+      input: z.object({ name: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+
+    // Pass invalid input (missing name)
+    const [cmd] = commands;
+    expect(cmd).toBeDefined();
+    const result = await cmd?.execute({}, {});
+    expect(result).toBeDefined();
+    expect(result?.isErr()).toBe(true);
+    expect(implCalled).toBe(false);
+  });
+
+  test('applies layers in order', async () => {
+    const order: string[] = [];
+    const t = trail('layered', {
+      implementation: (input: { x: string }) => {
+        order.push('impl');
+        return Result.ok(input.x);
+      },
+      input: z.object({ x: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app, {
+      layers: [
+        {
+          name: 'outer',
+          wrap: (_trail, impl) => async (input, ctx) => {
+            order.push('outer-before');
+            const r = await impl(input, ctx);
+            order.push('outer-after');
+            return r;
+          },
+        },
+        {
+          name: 'inner',
+          wrap: (_trail, impl) => async (input, ctx) => {
+            order.push('inner-before');
+            const r = await impl(input, ctx);
+            order.push('inner-after');
+            return r;
+          },
+        },
+      ],
+    });
+
+    await commands[0]?.execute({}, { x: 'test' });
+    expect(order).toEqual([
+      'outer-before',
+      'inner-before',
+      'impl',
+      'inner-after',
+      'outer-after',
+    ]);
+  });
+
+  test('uses provided createContext factory', async () => {
+    let usedRequestId: string | undefined;
+    const t = trail('ctx-test', {
+      implementation: (_input: Record<string, never>, ctx: TrailContext) => {
+        usedRequestId = ctx.requestId;
+        return Result.ok('ok');
+      },
+      input: z.object({}),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app, {
+      createContext: () => createTrailContext({ requestId: 'custom-123' }),
+    });
+
+    await commands[0]?.execute({}, {});
+    expect(usedRequestId).toBe('custom-123');
+  });
+
+  test('converts kebab-case flags back to camelCase for input', async () => {
+    let receivedInput: unknown;
+    const t = trail('camel', {
+      implementation: (input) => {
+        receivedInput = input;
+        return Result.ok('ok');
+      },
+      input: z.object({ sortOrder: z.string() }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+
+    await commands[0]?.execute({}, { 'sort-order': 'asc' });
+    expect(receivedInput).toEqual({ sortOrder: 'asc' });
+  });
+});

package/src/__tests__/flags.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import {
+  cwdPreset,
+  deriveFlags,
+  dryRunPreset,
+  outputModePreset,
+} from '../flags.js';
+
+const requireFlag = (flags: ReturnType<typeof deriveFlags>, name: string) => {
+  const flag = flags.find((entry) => entry.name === name);
+  expect(flag).toBeDefined();
+  if (!flag) {
+    throw new Error(`Expected flag: ${name}`);
+  }
+  return flag;
+};
+
+describe('deriveFlags', () => {
+  describe('primitive fields', () => {
+    test('z.string() derives a string flag', () => {
+      const flags = deriveFlags(z.object({ name: z.string() }));
+      const flag = requireFlag(flags, 'name');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('string');
+      expect(flag.required).toBe(true);
+      expect(flag.variadic).toBe(false);
+    });
+
+    test('z.number() derives a number flag', () => {
+      const flags = deriveFlags(z.object({ count: z.number() }));
+      const flag = requireFlag(flags, 'count');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('number');
+      expect(flag.required).toBe(true);
+    });
+
+    test('z.boolean() derives a boolean flag', () => {
+      const flags = deriveFlags(z.object({ verbose: z.boolean() }));
+      const flag = requireFlag(flags, 'verbose');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('boolean');
+      expect(flag.required).toBe(true);
+    });
+  });
+
+  describe('complex field shapes', () => {
+    test('z.enum() derives a string flag with choices', () => {
+      const flags = deriveFlags(
+        z.object({ format: z.enum(['json', 'text', 'csv']) })
+      );
+      const flag = requireFlag(flags, 'format');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('string');
+      expect(flag.choices).toEqual(['json', 'text', 'csv']);
+    });
+
+    test('z.array(z.string()) derives a variadic string[] flag', () => {
+      const flags = deriveFlags(z.object({ tags: z.array(z.string()) }));
+      const flag = requireFlag(flags, 'tags');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('string[]');
+      expect(flag.variadic).toBe(true);
+    });
+
+    test('z.array(z.number()) derives a variadic number[] flag', () => {
+      const flags = deriveFlags(z.object({ ids: z.array(z.number()) }));
+      const flag = requireFlag(flags, 'ids');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.type).toBe('number[]');
+      expect(flag.variadic).toBe(true);
+    });
+  });
+
+  describe('modifiers and naming', () => {
+    test('z.optional() sets required: false', () => {
+      const flags = deriveFlags(z.object({ label: z.string().optional() }));
+      const flag = requireFlag(flags, 'label');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.required).toBe(false);
+    });
+
+    test('z.default() sets required: false and populates default', () => {
+      const flags = deriveFlags(z.object({ limit: z.number().default(10) }));
+      const flag = requireFlag(flags, 'limit');
+
+      expect(flags).toHaveLength(1);
+      expect(flag.required).toBe(false);
+      expect(flag.default).toBe(10);
+    });
+
+    test('.describe() populates flag description', () => {
+      const flags = deriveFlags(
+        z.object({ query: z.string().describe('Search query') })
+      );
+
+      expect(flags).toHaveLength(1);
+      expect(requireFlag(flags, 'query').description).toBe('Search query');
+    });
+
+    test('camelCase field names convert to kebab-case flag names', () => {
+      const flags = deriveFlags(
+        z.object({ maxItems: z.number(), sortOrder: z.string() })
+      );
+      const names = flags.map((f) => f.name);
+
+      expect(flags).toHaveLength(2);
+      expect(names).toContain('sort-order');
+      expect(names).toContain('max-items');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('non-object schema returns empty flags', () => {
+      const flags = deriveFlags(z.string());
+      expect(flags).toHaveLength(0);
+    });
+
+    test('handles multiple fields together', () => {
+      const schema = z.object({
+        count: z.number().optional(),
+        name: z.string(),
+        tags: z.array(z.string()),
+        verbose: z.boolean().default(false),
+      });
+      const flags = deriveFlags(schema);
+      expect(flags).toHaveLength(4);
+    });
+  });
+});
+
+describe('outputModePreset', () => {
+  test('returns --output, --json, --jsonl flags', () => {
+    const flags = outputModePreset();
+    expect(flags).toHaveLength(3);
+
+    const outputFlag = requireFlag(flags, 'output');
+    const jsonFlag = requireFlag(flags, 'json');
+    const jsonlFlag = requireFlag(flags, 'jsonl');
+
+    expect(outputFlag.short).toBe('o');
+    expect(outputFlag.choices).toEqual(['text', 'json', 'jsonl']);
+    expect(outputFlag.default).toBe('text');
+    expect(jsonFlag.type).toBe('boolean');
+    expect(jsonlFlag.type).toBe('boolean');
+  });
+});
+
+describe('cwdPreset', () => {
+  test('returns --cwd flag', () => {
+    const flags = cwdPreset();
+    expect(flags).toHaveLength(1);
+    expect(flags[0]?.name).toBe('cwd');
+    expect(flags[0]?.type).toBe('string');
+    expect(flags[0]?.required).toBe(false);
+  });
+});
+
+describe('dryRunPreset', () => {
+  test('returns --dry-run flag', () => {
+    const flags = dryRunPreset();
+    expect(flags).toHaveLength(1);
+    expect(flags[0]?.name).toBe('dry-run');
+    expect(flags[0]?.type).toBe('boolean');
+    expect(flags[0]?.default).toBe(false);
+  });
+});