dialekt 0.1.0

package/src/cli/commands/unused.ts

@@ -0,0 +1,87 @@
+import { Command, Options } from '@effect/cli';
+import { Effect, Console, Option } from 'effect';
+import { loadConfig } from '../../config/load-config.js';
+import { resolveEffectiveConfig } from '../config-resolution.js';
+import { detectFormat, type OutputFormat } from '../format.js';
+import { formatUnusedKeys, formatError } from '../formatters.js';
+import type { DialektConfig } from '../../config/types.js';
+import type { TranslationAdapter, ResourceRef } from '../../adapter/types.js';
+
+export interface UnusedFlags {
+  readonly config: string;
+  readonly adapter: Option.Option<string>;
+  readonly baseLanguage: Option.Option<string>;
+  readonly format?: Option.Option<string>;
+}
+
+export function runUnused(
+  flags: UnusedFlags,
+  configLoader: (path: string) => Effect.Effect<DialektConfig, unknown> = loadConfig,
+  logger: (msg: string) => Effect.Effect<void> = (msg: string) => Console.log(msg),
+  errorLogger: (msg: string) => Effect.Effect<void> = (msg: string) => Console.error(msg),
+): Effect.Effect<void, never> {
+  return Effect.gen(function* () {
+    const loaded = yield* configLoader(flags.config);
+    const effective = resolveEffectiveConfig(
+      {
+        baseLanguage: Option.getOrUndefined(flags.baseLanguage),
+        adapter: Option.getOrUndefined(flags.adapter),
+      },
+      loaded,
+    );
+
+    const allEntries: Array<{
+      adapter: string;
+      locale: string;
+      resource: string;
+      key: string;
+    }> = [];
+
+    for (const a of effective.adapters) {
+      if (!a.capabilities.unusedKeyDetection) {
+        yield* errorLogger(
+          formatError(
+            `Adapter '${a.name}' does not support unused-key detection.`,
+            detectFormat(
+              flags.format !== undefined
+                ? (Option.getOrUndefined(flags.format) as OutputFormat | undefined)
+                : undefined,
+            ),
+          ),
+        );
+        continue;
+      }
+
+      const locales = yield* a.listLocales();
+      const sourceLocale = effective.sourceLocale;
+      const resources = yield* a.listResources(sourceLocale);
+
+      for (const resource of resources) {
+        const unused = yield* a.findUnusedKeys!(sourceLocale, resource);
+        for (const key of unused) {
+          allEntries.push({
+            adapter: a.name,
+            locale: sourceLocale,
+            resource: resource.label,
+            key,
+          });
+        }
+      }
+    }
+
+    const format = detectFormat(
+      flags.format !== undefined
+        ? (Option.getOrUndefined(flags.format) as OutputFormat | undefined)
+        : undefined,
+    );
+
+    yield* logger(formatUnusedKeys(allEntries, format));
+  }).pipe(Effect.mapError((e) => e as never)) as Effect.Effect<void, never, never>;
+}
+
+export const unusedCommand = Command.make('unused', {
+  config: Options.text('config').pipe(Options.withDefault('./dialekt.config.ts')),
+  adapter: Options.optional(Options.text('adapter')),
+  baseLanguage: Options.optional(Options.text('base-language')),
+  format: Options.optional(Options.text('format')),
+}, (flags) => runUnused(flags));

package/src/cli/commands/validate.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Option } from 'effect';
+import { runValidate, validateCommand } from './validate.js';
+import type { DialektConfig } from '../../config/types.js';
+import type { TranslationAdapter, ResourceRef } from '../../adapter/types.js';
+
+describe('runValidate', () => {
+  const baseConfig: DialektConfig = {
+    sourceLocale: 'en',
+    targetLocales: ['de', 'fr'],
+    strategy: 'one-shot',
+    model: { provider: 'openai', modelId: 'gpt-4o' },
+    fastModel: { provider: 'openai', modelId: 'gpt-4o-mini' },
+    chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    retry: { maxAttempts: 3, baseDelayMs: 1000 },
+    adapters: [],
+  };
+
+  function makeAdapter(opts: {
+    name: string;
+    locales?: readonly string[];
+    missing?: readonly { resource: ResourceRef; missing: readonly string[] }[];
+  }): TranslationAdapter {
+    return {
+      name: opts.name,
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(opts.locales ?? ['en', 'de']),
+      listResources: () => Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: () => Effect.succeed({}),
+      writeResource: () => Effect.void,
+    };
+  }
+
+  it('passes when no keys are missing', async () => {
+    const logs: string[] = [];
+    const adapter = makeAdapter({ name: 'test' });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () => Effect.succeed([]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    expect(logs).toHaveLength(1);
+    const parsed = JSON.parse(logs[0]!);
+    expect(parsed.passing).toBe(true);
+    expect(parsed.entries).toEqual([]);
+  });
+
+  it('fails and reports missing keys', async () => {
+    const logs: string[] = [];
+    const adapter = makeAdapter({ name: 'test' });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+    const resource: ResourceRef = { key: 'messages', label: 'messages' };
+
+    const originalExitCode = process.exitCode;
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () =>
+        Effect.succeed([
+          { adapter: 'test', locale: 'de', resource, missing: ['hello'] },
+        ]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    process.exitCode = originalExitCode;
+
+    expect(logs).toHaveLength(1);
+    const parsed = JSON.parse(logs[0]!);
+    expect(parsed.passing).toBe(false);
+    expect(parsed.entries).toHaveLength(1);
+    expect(parsed.entries[0]).toMatchObject({ adapter: 'test', locale: 'de', resource: 'messages', count: 1 });
+  });
+
+  it('reports missing keys for multiple adapters', async () => {
+    const logs: string[] = [];
+    const a1 = makeAdapter({ name: 'a1' });
+    const a2 = makeAdapter({ name: 'a2', locales: ['en', 'fr'] });
+    const config = { ...baseConfig, adapters: [a1, a2] as unknown as DialektConfig['adapters'] };
+    const resource: ResourceRef = { key: 'messages', label: 'messages' };
+
+    const originalExitCode = process.exitCode;
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      (a) =>
+        Effect.succeed([
+          { adapter: a.name, locale: a.name === 'a1' ? 'de' : 'fr', resource, missing: ['k1'] },
+        ]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    process.exitCode = originalExitCode;
+
+    expect(logs).toHaveLength(1);
+    const parsed = JSON.parse(logs[0]!);
+    expect(parsed.passing).toBe(false);
+    expect(parsed.entries).toHaveLength(2);
+  });
+
+  it('filters by --adapter flag', async () => {
+    let queriedAdapter: string | undefined;
+    const a1 = makeAdapter({ name: 'a1' });
+    const a2 = makeAdapter({ name: 'a2' });
+    const config = { ...baseConfig, adapters: [a1, a2] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.some('a2'), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      (a) =>
+        Effect.sync(() => {
+          queriedAdapter = a.name;
+          return [];
+        }),
+      () => Effect.void,
+    );
+
+    await Effect.runPromise(program);
+    expect(queriedAdapter).toBe('a2');
+  });
+
+  it('fails when configLoader fails', async () => {
+    const program = runValidate(
+      { config: './missing.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.fail(new Error('Config not found')),
+      () => Effect.succeed([]),
+      () => Effect.void,
+    );
+
+    await expect(Effect.runPromise(program)).rejects.toThrow('Config not found');
+  });
+
+  it('fails when listLocales fails', async () => {
+    const adapter: TranslationAdapter = {
+      name: 'broken',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.fail(new Error('disk error') as never),
+      listResources: () => Effect.succeed([]),
+      readResource: () => Effect.succeed({}),
+      writeResource: () => Effect.void,
+    };
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () => Effect.succeed([]),
+      () => Effect.void,
+    );
+
+    await expect(Effect.runPromise(program)).rejects.toThrow('disk error');
+  });
+
+  it('fails when missingKeysComputer fails', async () => {
+    const adapter = makeAdapter({ name: 'test' });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () => Effect.fail(new Error('read error')),
+      () => Effect.void,
+    );
+
+    await expect(Effect.runPromise(program)).rejects.toThrow('read error');
+  });
+
+  it('filters by --language flag', async () => {
+    let checkedLocale: string | undefined;
+    const adapter = makeAdapter({ name: 'test' });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.some('de') },
+      () => Effect.succeed(config),
+      (_a, _s, targets) =>
+        Effect.sync(() => {
+          checkedLocale = targets[0];
+          return [];
+        }),
+      () => Effect.void,
+    );
+
+    await Effect.runPromise(program);
+    expect(checkedLocale).toBe('de');
+  });
+
+  it('outputs pretty when --format pretty is passed', async () => {
+    const logs: string[] = [];
+    const adapter = makeAdapter({ name: 'test' });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none(), format: Option.some('pretty') },
+      () => Effect.succeed(config),
+      () => Effect.succeed([]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    expect(logs).toHaveLength(1);
+    expect(logs[0]).toContain('up to date');
+  });
+
+  it('handles empty adapter list', async () => {
+    const logs: string[] = [];
+    const config = { ...baseConfig, adapters: [] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () => Effect.succeed([]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    expect(logs).toHaveLength(1);
+    const parsed = JSON.parse(logs[0]!);
+    expect(parsed.passing).toBe(true);
+  });
+
+  it('handles adapter with only source locale (no targets)', async () => {
+    const logs: string[] = [];
+    const adapter = makeAdapter({ name: 'mono', locales: ['en'] });
+    const config = { ...baseConfig, adapters: [adapter] as unknown as DialektConfig['adapters'] };
+
+    const program = runValidate(
+      { config: './config.ts', adapter: Option.none(), baseLanguage: Option.none(), language: Option.none() },
+      () => Effect.succeed(config),
+      () => Effect.succeed([]),
+      (msg) => Effect.sync(() => logs.push(msg)),
+    );
+
+    await Effect.runPromise(program);
+    expect(logs).toHaveLength(1);
+    const parsed = JSON.parse(logs[0]!);
+    expect(parsed.passing).toBe(true);
+  });
+});

package/src/cli/commands/validate.ts

@@ -0,0 +1,96 @@
+import { Command, Options } from '@effect/cli';
+import { Effect, Console, Option } from 'effect';
+import { loadConfig } from '../../config/load-config.js';
+import { resolveEffectiveConfig } from '../config-resolution.js';
+import { computeMissingKeys } from '../../translation/missing-keys.js';
+import { detectFormat, type OutputFormat } from '../format.js';
+import { formatValidate, formatError } from '../formatters.js';
+import type { DialektConfig } from '../../config/types.js';
+import type { TranslationAdapter, ResourceRef } from '../../adapter/types.js';
+
+export interface ValidateFlags {
+  readonly config: string;
+  readonly adapter: Option.Option<string>;
+  readonly baseLanguage: Option.Option<string>;
+  readonly language: Option.Option<string>;
+  readonly format?: Option.Option<string>;
+}
+
+export interface MissingEntry {
+  readonly adapter: string;
+  readonly locale: string;
+  readonly resource: ResourceRef;
+  readonly missing: readonly string[];
+}
+
+export function runValidate(
+  flags: ValidateFlags,
+  configLoader: (path: string) => Effect.Effect<DialektConfig, unknown> = loadConfig,
+  missingKeysComputer: (
+    adapter: TranslationAdapter,
+    sourceLocale: string,
+    targetLocales: readonly string[],
+  ) => Effect.Effect<readonly MissingEntry[], unknown> = computeMissingKeys as unknown as typeof missingKeysComputer,
+  logger: (msg: string) => Effect.Effect<void> = (msg: string) => Console.log(msg),
+): Effect.Effect<void, Error> {
+  return Effect.gen(function* () {
+    const loaded = yield* configLoader(flags.config);
+    const effective = resolveEffectiveConfig(
+      {
+        baseLanguage: Option.getOrUndefined(flags.baseLanguage),
+        language: Option.isSome(flags.language) ? [flags.language.value] : undefined,
+        adapter: Option.getOrUndefined(flags.adapter),
+      },
+      loaded,
+    );
+
+    const entries: Array<{
+      adapter: string;
+      locale: string;
+      resource: string;
+      count: number;
+    }> = [];
+
+    for (const a of effective.adapters) {
+      const locales = yield* a.listLocales();
+      const sourceLocale = effective.sourceLocale;
+      const targets = locales.filter((l) => l !== sourceLocale);
+
+      const missingEntries = yield* missingKeysComputer(a, sourceLocale, targets);
+      for (const entry of missingEntries) {
+        entries.push({
+          adapter: entry.adapter,
+          locale: entry.locale,
+          resource: entry.resource.label,
+          count: entry.missing.length,
+        });
+      }
+    }
+
+    const format = detectFormat(
+      flags.format !== undefined
+        ? (Option.getOrUndefined(flags.format) as OutputFormat | undefined)
+        : undefined,
+    );
+
+    const passing = entries.length === 0;
+
+    yield* logger(
+      formatValidate({ passing, entries }, format),
+    );
+
+    if (!passing) {
+      yield* Effect.sync(() => {
+        process.exitCode = 1;
+      });
+    }
+  }).pipe(Effect.mapError((e) => e as Error)) as Effect.Effect<void, Error, never>;
+}
+
+export const validateCommand = Command.make('validate', {
+  config: Options.text('config').pipe(Options.withDefault('./dialekt.config.ts')),
+  adapter: Options.optional(Options.text('adapter')),
+  baseLanguage: Options.optional(Options.text('base-language')),
+  language: Options.optional(Options.text('language')),
+  format: Options.optional(Options.text('format')),
+}, (flags) => runValidate(flags));

package/src/cli/config-resolution.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { resolveEffectiveConfig } from './config-resolution.js';
+import type { DialektConfig } from '../config/types.js';
+
+const baseConfig: DialektConfig = {
+  sourceLocale: 'en',
+  targetLocales: ['de', 'fr'],
+  strategy: 'one-shot',
+  model: { provider: 'openai', modelId: 'gpt-4o' },
+  fastModel: { provider: 'openai', modelId: 'gpt-4o-mini' },
+  chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+  retry: { maxAttempts: 3, baseDelayMs: 1000 },
+  adapters: [],
+};
+
+describe('resolveEffectiveConfig', () => {
+  it('uses loaded config when no flags given', () => {
+    const result = resolveEffectiveConfig({}, baseConfig);
+    expect(result.sourceLocale).toBe('en');
+    expect(result.targetLocales).toEqual(['de', 'fr']);
+  });
+
+  it('overrides sourceLocale with flag', () => {
+    const result = resolveEffectiveConfig({ baseLanguage: 'fr' }, baseConfig);
+    expect(result.sourceLocale).toBe('fr');
+  });
+
+  it('overrides strategy with flag', () => {
+    const result = resolveEffectiveConfig({ strategy: 'tool-loop-agent' }, baseConfig);
+    expect(result.strategy).toBe('tool-loop-agent');
+  });
+
+  it('filters adapters by name flag', () => {
+    const adapterA = { name: 'a', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const adapterB = { name: 'b', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const config = { ...baseConfig, adapters: [adapterA, adapterB] };
+    const result = resolveEffectiveConfig({ adapter: 'b' }, config);
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0]!.name).toBe('b');
+  });
+
+  it('returns all adapters when adapter flag does not match any', () => {
+    const adapterA = { name: 'a', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const config = { ...baseConfig, adapters: [adapterA] };
+    const result = resolveEffectiveConfig({ adapter: 'nonexistent' }, config);
+    expect(result.adapters).toHaveLength(0);
+  });
+
+  it('overrides targetLocales with language flag', () => {
+    const result = resolveEffectiveConfig({ language: ['es'] }, baseConfig);
+    expect(result.targetLocales).toEqual(['es']);
+  });
+
+  it('preserves targetLocales when language flag is empty', () => {
+    const result = resolveEffectiveConfig({ language: [] }, baseConfig);
+    expect(result.targetLocales).toEqual(['de', 'fr']);
+  });
+
+  it('preserves targetLocales when language flag is undefined', () => {
+    const result = resolveEffectiveConfig({}, baseConfig);
+    expect(result.targetLocales).toEqual(['de', 'fr']);
+  });
+
+  it('does not override strategy when flag is undefined', () => {
+    const result = resolveEffectiveConfig({}, baseConfig);
+    expect(result.strategy).toBe('one-shot');
+  });
+
+  it('does not override sourceLocale when baseLanguage is undefined', () => {
+    const result = resolveEffectiveConfig({}, baseConfig);
+    expect(result.sourceLocale).toBe('en');
+  });
+
+  it('preserves other config fields unchanged', () => {
+    const result = resolveEffectiveConfig({}, baseConfig);
+    expect(result.model).toEqual(baseConfig.model);
+    expect(result.fastModel).toEqual(baseConfig.fastModel);
+    expect(result.chunking).toEqual(baseConfig.chunking);
+    expect(result.retry).toEqual(baseConfig.retry);
+  });
+
+  it('handles multiple adapter filters matching one', () => {
+    const a1 = { name: 'laravel', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const a2 = { name: 'paraglide', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const config = { ...baseConfig, adapters: [a1, a2] };
+    const result = resolveEffectiveConfig({ adapter: 'laravel' }, config);
+    expect(result.adapters).toHaveLength(1);
+    expect(result.adapters[0]!.name).toBe('laravel');
+  });
+
+  it('preserves adapter order after filtering', () => {
+    const a1 = { name: 'first', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const a2 = { name: 'second', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const a3 = { name: 'third', capabilities: { canCreateResource: true, unusedKeyDetection: false }, listLocales: () => { throw new Error(); }, listResources: () => { throw new Error(); }, readResource: () => { throw new Error(); }, writeResource: () => { throw new Error(); } } as unknown as import('../config/types.js').DialektConfig['adapters'][number];
+    const config = { ...baseConfig, adapters: [a1, a2, a3] };
+    const result = resolveEffectiveConfig({ adapter: 'second' }, config);
+    expect(result.adapters[0]!.name).toBe('second');
+  });
+});

package/src/cli/config-resolution.ts

@@ -0,0 +1,29 @@
+import type { DialektConfig } from '../config/types.js';
+
+export interface CliFlags {
+  readonly config?: string | undefined;
+  readonly adapter?: string | undefined;
+  readonly strategy?: 'one-shot' | 'tool-loop-agent' | undefined;
+  readonly baseLanguage?: string | undefined;
+  readonly language?: readonly string[] | undefined;
+  readonly name?: readonly string[] | undefined;
+  readonly skipNames?: boolean | undefined;
+  readonly skipLanguages?: boolean | undefined;
+  readonly fast?: boolean | undefined;
+  readonly langDir?: string | undefined;
+}
+
+export function resolveEffectiveConfig(
+  flags: CliFlags,
+  loaded: DialektConfig,
+): DialektConfig {
+  return {
+    ...loaded,
+    sourceLocale: flags.baseLanguage ?? loaded.sourceLocale,
+    targetLocales: flags.language && flags.language.length > 0 ? flags.language : loaded.targetLocales,
+    strategy: flags.strategy ?? loaded.strategy,
+    adapters: flags.adapter
+      ? loaded.adapters.filter((a: { name: string }) => a.name === flags.adapter)
+      : loaded.adapters,
+  };
+}

package/src/cli/format.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it, afterEach } from 'vitest';
+import {
+  detectFormat,
+  color,
+  drawTable,
+  banner,
+  sectionHeader,
+  success,
+  failure,
+  warning,
+  info,
+  keyValue,
+} from './format.js';
+
+describe('detectFormat', () => {
+  const originalTty = process.stdout.isTTY;
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    Object.assign(process.stdout, { isTTY: originalTty });
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) delete (process.env as Record<string, string | undefined>)[key];
+    }
+    Object.assign(process.env, originalEnv);
+  });
+
+  it('returns explicit format when provided', () => {
+    expect(detectFormat('json')).toBe('json');
+    expect(detectFormat('pretty')).toBe('pretty');
+  });
+
+  it('defaults to json when not a TTY', () => {
+    Object.assign(process.stdout, { isTTY: false });
+    expect(detectFormat()).toBe('json');
+  });
+
+  it('defaults to pretty when TTY and no agent env', () => {
+    Object.assign(process.stdout, { isTTY: true });
+    expect(detectFormat()).toBe('pretty');
+  });
+
+  it('defaults to json when agent env var is set', () => {
+    Object.assign(process.stdout, { isTTY: true });
+    process.env.CLAUDE_CODE = '1';
+    expect(detectFormat()).toBe('json');
+  });
+});
+
+describe('color', () => {
+  it('returns bare text when not a TTY', () => {
+    expect(color('hello', '\x1b[31m')).toBe('hello');
+  });
+});
+
+describe('drawTable', () => {
+  it('renders a table with headers and rows', () => {
+    const table = drawTable(
+      ['Name', 'Score'],
+      [
+        ['Alice', '10'],
+        ['Bob', '8'],
+      ],
+    );
+    expect(table).toContain('Name');
+    expect(table).toContain('Score');
+    expect(table).toContain('Alice');
+    expect(table).toContain('Bob');
+  });
+
+  it('handles empty rows', () => {
+    const table = drawTable(['A'], []);
+    expect(table).toContain('A');
+  });
+});
+
+describe('banner', () => {
+  it('includes the title', () => {
+    expect(banner('Results')).toContain('Results');
+  });
+});
+
+describe('sectionHeader', () => {
+  it('includes the label', () => {
+    expect(sectionHeader('Missing keys')).toContain('Missing keys');
+  });
+});
+
+describe('success', () => {
+  it('includes the text', () => {
+    expect(success('Done')).toContain('Done');
+  });
+});
+
+describe('failure', () => {
+  it('includes the text', () => {
+    expect(failure('Failed')).toContain('Failed');
+  });
+});
+
+describe('warning', () => {
+  it('includes the text', () => {
+    expect(warning('Warn')).toContain('Warn');
+  });
+});
+
+describe('info', () => {
+  it('returns dimmed text', () => {
+    expect(info('note')).toBe('note');
+  });
+});
+
+describe('keyValue', () => {
+  it('formats key and value', () => {
+    expect(keyValue('Name:', 'test')).toContain('Name:');
+    expect(keyValue('Name:', 'test')).toContain('test');
+  });
+});