@ontrails/cli 1.0.0-beta.0

package/src/__tests__/layers.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, createTrailContext, trail } from '@ontrails/core';
+import type { Implementation, Trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { autoIterateLayer, dateShortcutsLayer } from '../layers.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const makeCtx = () => createTrailContext();
+
+interface DateInput {
+  readonly since?: string | undefined;
+  readonly until?: string | undefined;
+}
+
+const captureDateShortcutInput = async (
+  dateTrail: Trail<DateInput, DateInput>,
+  input: DateInput
+): Promise<DateInput> => {
+  let receivedInput: DateInput | undefined;
+  const impl: Implementation<DateInput, DateInput> = (value) => {
+    receivedInput = value;
+    return Promise.resolve(Result.ok(value));
+  };
+
+  const wrapped = dateShortcutsLayer.wrap(dateTrail, impl);
+  await wrapped(input, makeCtx());
+
+  expect(receivedInput).toBeDefined();
+  return receivedInput ?? {};
+};
+
+const expectSameDate = (value: string | undefined, expected: Date) => {
+  expect(value).toBeDefined();
+  const actual = new Date(value ?? '');
+  expect(actual.getFullYear()).toBe(expected.getFullYear());
+  expect(actual.getMonth()).toBe(expected.getMonth());
+  expect(actual.getDate()).toBe(expected.getDate());
+};
+
+// ---------------------------------------------------------------------------
+// autoIterateLayer
+// ---------------------------------------------------------------------------
+
+describe('autoIterateLayer', () => {
+  const paginatedTrail = trail('list-items', {
+    implementation: () => Result.ok({ hasMore: false, items: [] }),
+    input: z.object({
+      all: z.boolean().optional(),
+      cursor: z.string().optional(),
+    }),
+    output: z.object({
+      hasMore: z.boolean(),
+      items: z.array(z.string()),
+      nextCursor: z.string().optional(),
+    }),
+  });
+
+  test('collects paginated results with --all flag', async () => {
+    interface PageResult {
+      items: string[];
+      hasMore: boolean;
+      nextCursor?: string | undefined;
+    }
+    const pages: PageResult[] = [
+      { hasMore: true, items: ['a', 'b'], nextCursor: 'page2' },
+      { hasMore: false, items: ['c'] },
+    ];
+    let callCount = 0;
+    const impl: Implementation<
+      { cursor?: string | undefined; all?: boolean | undefined },
+      { items: string[]; hasMore: boolean; nextCursor?: string | undefined }
+    > = () => {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index bounded by page count
+      const page = pages[callCount]!;
+      callCount += 1;
+      return Promise.resolve(Result.ok(page));
+    };
+
+    const wrapped = autoIterateLayer.wrap(paginatedTrail, impl);
+    const result = await wrapped({ all: true }, makeCtx());
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().items).toEqual(['a', 'b', 'c']);
+    expect(result.unwrap().hasMore).toBe(false);
+    expect(callCount).toBe(2);
+  });
+
+  test('passes through when --all is not set', async () => {
+    let callCount = 0;
+    const impl: Implementation<
+      { cursor?: string | undefined; all?: boolean | undefined },
+      { items: string[]; hasMore: boolean; nextCursor?: string | undefined }
+    > = () => {
+      callCount += 1;
+      return Promise.resolve(
+        Result.ok({ hasMore: true, items: ['a'], nextCursor: 'x' })
+      );
+    };
+
+    const wrapped = autoIterateLayer.wrap(paginatedTrail, impl);
+    const result = await wrapped({}, makeCtx());
+
+    expect(callCount).toBe(1);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().items).toEqual(['a']);
+  });
+
+  test('ignores non-paginated trails', () => {
+    const simpleTrail = trail('simple', {
+      implementation: (input: { name: string }) => Result.ok(input.name),
+      input: z.object({ name: z.string() }),
+    });
+
+    const impl: Implementation<{ name: string }, string> = async (input) =>
+      await Promise.resolve(Result.ok(input.name));
+
+    // Should return the same implementation (no wrapping)
+    const wrapped = autoIterateLayer.wrap(simpleTrail, impl);
+    // Reference equality may not hold with async wrapper, just verify it works
+    expect(wrapped).toBe(impl);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dateShortcutsLayer
+// ---------------------------------------------------------------------------
+
+describe('dateShortcutsLayer', () => {
+  const dateTrail = trail('events', {
+    implementation: (input: {
+      since?: string | undefined;
+      until?: string | undefined;
+    }) => Result.ok(input),
+    input: z.object({
+      since: z.string().optional(),
+      until: z.string().optional(),
+    }),
+  });
+
+  test("expands 'today' to correct date", async () => {
+    const received = await captureDateShortcutInput(dateTrail, {
+      since: 'today',
+    });
+    expectSameDate(received.since, new Date());
+  });
+
+  test("expands '7d' to 7-day range", async () => {
+    const now = new Date();
+    const expectedDate = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() - 7
+    );
+    const received = await captureDateShortcutInput(dateTrail, { since: '7d' });
+    expectSameDate(received.since, expectedDate);
+  });
+
+  test('passes through non-shortcut values', async () => {
+    let receivedInput: unknown;
+    const impl: Implementation<
+      { since?: string | undefined; until?: string | undefined },
+      { since?: string | undefined; until?: string | undefined }
+    > = (input) => {
+      receivedInput = input;
+      return Promise.resolve(Result.ok(input));
+    };
+
+    const isoDate = '2025-01-15T00:00:00.000Z';
+    const wrapped = dateShortcutsLayer.wrap(dateTrail, impl);
+    await wrapped({ since: isoDate }, makeCtx());
+
+    const received = receivedInput as { since?: string };
+    expect(received.since).toBe(isoDate);
+  });
+
+  test('ignores trails without date range fields', () => {
+    const noDateTrail = trail('no-dates', {
+      implementation: (input: { name: string }) => Result.ok(input.name),
+      input: z.object({ name: z.string() }),
+    });
+
+    const impl: Implementation<{ name: string }, string> = async (input) =>
+      await Promise.resolve(Result.ok(input.name));
+
+    const wrapped = dateShortcutsLayer.wrap(noDateTrail, impl);
+    expect(wrapped).toBe(impl);
+  });
+
+  test("expands 'yesterday'", async () => {
+    let receivedInput: unknown;
+    const impl: Implementation<
+      { since?: string | undefined; until?: string | undefined },
+      { since?: string | undefined; until?: string | undefined }
+    > = (input) => {
+      receivedInput = input;
+      return Promise.resolve(Result.ok(input));
+    };
+
+    const wrapped = dateShortcutsLayer.wrap(dateTrail, impl);
+    await wrapped({ since: 'yesterday' }, makeCtx());
+
+    const received = receivedInput as { since?: string };
+    expect(received.since).toBeDefined();
+    const date = new Date(received.since as string);
+    const now = new Date();
+    const expected = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() - 1
+    );
+    expect(date.getDate()).toBe(expected.getDate());
+  });
+});

package/src/__tests__/on-result.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { Result } from '@ontrails/core';
+
+import type { ActionResultContext } from '../build.js';
+import { defaultOnResult } from '../on-result.js';
+
+// Minimal trail stub for testing
+const stubTrail = () =>
+  ({ id: 'test', kind: 'trail' }) as ActionResultContext['trail'];
+
+describe('defaultOnResult', () => {
+  let written: string[];
+  let originalWrite: typeof process.stdout.write;
+
+  beforeEach(() => {
+    written = [];
+    originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string) => {
+      written.push(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+  });
+
+  afterEach(() => {
+    process.stdout.write = originalWrite;
+  });
+
+  test('outputs success values in resolved mode (text)', async () => {
+    const ctx: ActionResultContext = {
+      args: {},
+      flags: {},
+      input: { name: 'test' },
+      result: Result.ok('hello'),
+      trail: stubTrail(),
+    };
+    await defaultOnResult(ctx);
+    expect(written.join('')).toBe('hello\n');
+  });
+
+  test('outputs success values in json mode', async () => {
+    const ctx: ActionResultContext = {
+      args: {},
+      flags: { json: true },
+      input: {},
+      result: Result.ok({ id: 1 }),
+      trail: stubTrail(),
+    };
+    await defaultOnResult(ctx);
+    expect(written.join('')).toBe(`${JSON.stringify({ id: 1 }, null, 2)}\n`);
+  });
+
+  test('throws on error results', () => {
+    const error = new Error('something broke');
+    const ctx: ActionResultContext = {
+      args: {},
+      flags: {},
+      input: {},
+      result: Result.err(error),
+      trail: stubTrail(),
+    };
+    expect(defaultOnResult(ctx)).rejects.toThrow('something broke');
+  });
+});

package/src/__tests__/output.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { output, resolveOutputMode } from '../output.js';
+
+describe('output', () => {
+  let written: string[];
+  let originalWrite: typeof process.stdout.write;
+
+  beforeEach(() => {
+    written = [];
+    originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string) => {
+      written.push(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+  });
+
+  afterEach(() => {
+    process.stdout.write = originalWrite;
+  });
+
+  test('text mode writes string directly', async () => {
+    await output('hello world', 'text');
+    expect(written.join('')).toBe('hello world\n');
+  });
+
+  test('text mode JSON-stringifies objects', async () => {
+    await output({ key: 'value' }, 'text');
+    expect(written.join('')).toBe(
+      `${JSON.stringify({ key: 'value' }, null, 2)}\n`
+    );
+  });
+
+  test('json mode writes JSON with indentation', async () => {
+    await output({ a: 1 }, 'json');
+    expect(written.join('')).toBe(`${JSON.stringify({ a: 1 }, null, 2)}\n`);
+  });
+
+  test('jsonl mode writes each array element as a line', async () => {
+    await output([{ id: 1 }, { id: 2 }], 'jsonl');
+    expect(written).toEqual([
+      `${JSON.stringify({ id: 1 })}\n`,
+      `${JSON.stringify({ id: 2 })}\n`,
+    ]);
+  });
+
+  test('jsonl mode writes single object as one line', async () => {
+    await output({ id: 1 }, 'jsonl');
+    expect(written.join('')).toBe(`${JSON.stringify({ id: 1 })}\n`);
+  });
+});
+
+describe('resolveOutputMode', () => {
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe('flag precedence', () => {
+    test('--json flag returns json', () => {
+      const result = resolveOutputMode({ json: true });
+      expect(result.mode).toBe('json');
+    });
+
+    test('--jsonl flag returns jsonl', () => {
+      const result = resolveOutputMode({ jsonl: true });
+      expect(result.mode).toBe('jsonl');
+    });
+
+    test('--json takes priority over --jsonl', () => {
+      const result = resolveOutputMode({ json: true, jsonl: true });
+      expect(result.mode).toBe('json');
+    });
+
+    test('--output flag returns specified mode', () => {
+      const result = resolveOutputMode({ output: 'jsonl' });
+      expect(result.mode).toBe('jsonl');
+    });
+
+    test('--json takes priority over --output', () => {
+      const result = resolveOutputMode({ json: true, output: 'text' });
+      expect(result.mode).toBe('json');
+    });
+  });
+
+  describe('environment fallback', () => {
+    test('TRAILS_JSON=1 env var returns json', () => {
+      process.env['TRAILS_JSON'] = '1';
+      const result = resolveOutputMode({});
+      expect(result.mode).toBe('json');
+    });
+
+    test('TRAILS_JSONL=1 env var returns jsonl', () => {
+      process.env['TRAILS_JSONL'] = '1';
+      const result = resolveOutputMode({});
+      expect(result.mode).toBe('jsonl');
+    });
+
+    test('flags take priority over env vars', () => {
+      process.env['TRAILS_JSON'] = '1';
+      const result = resolveOutputMode({ jsonl: true });
+      expect(result.mode).toBe('jsonl');
+    });
+
+    test('defaults to text when nothing specified', () => {
+      const result = resolveOutputMode({});
+      expect(result.mode).toBe('text');
+    });
+  });
+});

package/src/__tests__/to-commander.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { buildCliCommands } from '../build.js';
+import type { AnyTrail } from '../command.js';
+import { toCommander } from '../commander/to-commander.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 = (
+  program: ReturnType<typeof toCommander>,
+  name: string
+) => {
+  const command = program.commands.find((entry) => entry.name() === name);
+  expect(command).toBeDefined();
+  if (!command) {
+    throw new Error(`Expected command: ${name}`);
+  }
+  return command;
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('toCommander', () => {
+  test('creates a Commander program with correct commands', () => {
+    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);
+    const program = toCommander(commands, { name: 'test-cli' });
+
+    expect(program.name()).toBe('test-cli');
+    // Should have the greet subcommand
+    const sub = program.commands.find((c) => c.name() === 'greet');
+    expect(sub).toBeDefined();
+  });
+
+  test('grouped commands create parent/subcommand structure', () => {
+    const show = trail('entity.show', {
+      implementation: () => Result.ok({}),
+      input: z.object({ id: z.string() }),
+    });
+    const add = trail('entity.add', {
+      implementation: () => Result.ok({}),
+      input: z.object({ name: z.string() }),
+    });
+    const app = makeApp(show, add);
+    const commands = buildCliCommands(app);
+    const program = toCommander(commands);
+
+    // Should have an "entity" parent command
+    const entityCmd = program.commands.find((c) => c.name() === 'entity');
+    expect(entityCmd).toBeDefined();
+    // With "show" and "add" subcommands
+    const subNames = entityCmd?.commands.map((c) => c.name());
+    expect(subNames).toContain('show');
+    expect(subNames).toContain('add');
+  });
+
+  test('flag types map correctly to Commander options', () => {
+    const t = trail('search', {
+      implementation: () => Result.ok([]),
+      input: z.object({
+        format: z.enum(['json', 'text']).optional(),
+        limit: z.number().optional(),
+        query: z.string(),
+        tags: z.array(z.string()).optional(),
+        verbose: z.boolean().optional(),
+      }),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+    const program = toCommander(commands);
+
+    const opts = requireCommand(program, 'search').options;
+    expect(opts.length).toBeGreaterThanOrEqual(5);
+
+    const formatOpt = opts.find((entry) => entry.long === '--format');
+    expect(formatOpt).toBeDefined();
+    expect(formatOpt?.argChoices).toEqual(['json', 'text']);
+  });
+
+  test('sets version when provided', () => {
+    const t = trail('ping', {
+      implementation: () => Result.ok('pong'),
+      input: z.object({}),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+    const program = toCommander(commands, {
+      description: 'A test app',
+      name: 'myapp',
+      version: '1.2.3',
+    });
+
+    expect(program.name()).toBe('myapp');
+    expect(program.version()).toBe('1.2.3');
+    expect(program.description()).toBe('A test app');
+  });
+
+  test('error handling maps categories to exit codes', () => {
+    // This test verifies the error handling structure exists.
+    // Full integration would need process.exit mocking.
+    const t = trail('fail', {
+      implementation: () => Result.ok('ok'),
+      input: z.object({}),
+    });
+    const app = makeApp(t);
+    const commands = buildCliCommands(app);
+    const program = toCommander(commands);
+
+    // Verify the program was created (error handling is wired in action)
+    expect(program).toBeDefined();
+    expect(program.commands).toHaveLength(1);
+  });
+});