runspec-node 0.3.0

package/src/types.ts

@@ -0,0 +1,96 @@
+import * as path from 'path';
+import type { ArgSpec } from './models';
+import { formatInvalidChoice } from './errors';
+
+export type TypeCoercer = (value: unknown, spec: ArgSpec) => unknown;
+
+const registry = new Map<string, TypeCoercer>();
+
+export function registerType(name: string, coercer: TypeCoercer): void {
+  registry.set(name, coercer);
+}
+
+export function coerce(value: unknown, spec: ArgSpec): unknown {
+  const typeName = spec.type ?? 'str';
+  const coercer = registry.get(typeName);
+  if (!coercer) {
+    throw new TypeError(
+      `Unknown type '${typeName}' for argument '${spec.name}'. Registered types: ${[...registry.keys()].sort().join(', ')}\nRegister custom types with registerType().`,
+    );
+  }
+  try {
+    return coercer(value, spec);
+  } catch (e) {
+    throw new Error(
+      `Cannot coerce value ${JSON.stringify(value)} to type '${typeName}' for argument '--${spec.name ?? '?'}': ${(e as Error).message}`,
+    );
+  }
+}
+
+export function listTypes(): string[] {
+  return [...registry.keys()].sort();
+}
+
+function coerceStr(value: unknown): string {
+  return String(value);
+}
+
+function coerceInt(value: unknown, spec: ArgSpec): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    throw new Error(`invalid integer: ${JSON.stringify(value)}`);
+  }
+  checkRange(n, spec);
+  return n;
+}
+
+function coerceFloat(value: unknown, spec: ArgSpec): number {
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`invalid number: ${JSON.stringify(value)}`);
+  checkRange(n, spec);
+  return n;
+}
+
+function coerceBool(value: unknown): boolean {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    if (['true', '1', 'yes', 'on'].includes(value.toLowerCase())) return true;
+    if (['false', '0', 'no', 'off'].includes(value.toLowerCase())) return false;
+  }
+  throw new Error(`Cannot interpret ${JSON.stringify(value)} as bool`);
+}
+
+function coerceFlag(value: unknown): boolean {
+  if (typeof value === 'boolean') return value;
+  return Boolean(value);
+}
+
+function coercePath(value: unknown): string {
+  return path.resolve(String(value));
+}
+
+function coerceChoice(value: unknown, spec: ArgSpec): string {
+  const v = String(value);
+  const options = spec.options ?? [];
+  if (options.length > 0 && !options.includes(v)) {
+    throw new Error(formatInvalidChoice(v, options, spec.name ?? '?'));
+  }
+  return v;
+}
+
+function checkRange(value: number, spec: ArgSpec): void {
+  if (spec.range) {
+    const [min, max] = spec.range;
+    if (value < min || value > max) {
+      throw new Error(`Value ${value} is out of range [${min}, ${max}]`);
+    }
+  }
+}
+
+registerType('str', coerceStr);
+registerType('int', coerceInt);
+registerType('float', coerceFloat);
+registerType('bool', coerceBool);
+registerType('flag', coerceFlag);
+registerType('path', coercePath);
+registerType('choice', coerceChoice);

package/src/validator.ts

@@ -0,0 +1,64 @@
+import type { ArgSpec, GroupSpec } from './models';
+import {
+  RunSpecError,
+  formatMissingRequired,
+  formatGroupExclusive,
+  formatGroupInclusive,
+  formatGroupAtLeastOne,
+  formatGroupExactlyOne,
+  formatDeprecated,
+} from './errors';
+
+export function validateArgs(parsedValues: Record<string, unknown>, argSpecs: Record<string, ArgSpec>): string[] {
+  const errors: string[] = [];
+
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    const value = parsedValues[name];
+    const missing = value === null || value === undefined;
+
+    if (spec.required && missing) {
+      errors.push(formatMissingRequired(name, spec as unknown as Record<string, unknown>));
+      continue;
+    }
+
+    if (!missing && spec.deprecated) {
+      process.stderr.write(formatDeprecated(name, spec.deprecated) + '\n');
+    }
+  }
+
+  return errors;
+}
+
+export function validateGroups(parsedValues: Record<string, unknown>, groupSpecs: Record<string, GroupSpec>): string[] {
+  const errors: string[] = [];
+
+  for (const [groupName, group] of Object.entries(groupSpecs)) {
+    const groupArgs = group.args ?? [];
+    const provided = groupArgs.filter((a) => parsedValues[a] !== null && parsedValues[a] !== undefined);
+
+    if (group.exclusive && provided.length > 1) {
+      errors.push(formatGroupExclusive(groupName, provided));
+    } else if (group.inclusive && provided.length > 0 && provided.length < groupArgs.length) {
+      errors.push(formatGroupInclusive(groupName, groupArgs.filter((a) => !provided.includes(a))));
+    } else if (group.atLeastOne && provided.length === 0) {
+      errors.push(formatGroupAtLeastOne(groupName, groupArgs));
+    } else if (group.exactlyOne && provided.length !== 1) {
+      errors.push(formatGroupExactlyOne(groupName, groupArgs, provided));
+    } else if (group.condition) {
+      const condVal = parsedValues[group.condition];
+      if (condVal !== null && condVal !== undefined) {
+        const requires = group.requires ?? [];
+        const missing = requires.filter((a) => parsedValues[a] === null || parsedValues[a] === undefined);
+        if (missing.length > 0) errors.push(formatGroupInclusive(groupName, missing));
+      }
+    }
+  }
+
+  return errors;
+}
+
+export function raiseIfErrors(errorMessages: string[]): void {
+  if (errorMessages.length > 0) {
+    throw new RunSpecError(errorMessages.join('\n\n'));
+  }
+}

package/tests/test_inference.test.ts

@@ -0,0 +1,153 @@
+import { inferArg, inferScript, effectiveAutonomy, isMoreRestrictive } from '../src/inference';
+import { RunSpecError } from '../src/errors';
+import type { ArgSpec, ScriptSpec } from '../src/models';
+
+function makeArg(overrides: Partial<ArgSpec> = {}): ArgSpec {
+  return { name: 'test', args: [], ...overrides } as unknown as ArgSpec;
+}
+
+// ── inferArg — type inference ─────────────────────────────────────────────────
+
+test('infers flag from boolean default', () => {
+  const result = inferArg(makeArg({ default: false }));
+  expect(result.type).toBe('flag');
+});
+
+test('infers flag from true default', () => {
+  const result = inferArg(makeArg({ default: true }));
+  expect(result.type).toBe('flag');
+});
+
+test('infers int from integer default', () => {
+  const result = inferArg(makeArg({ default: 42 }));
+  expect(result.type).toBe('int');
+});
+
+test('infers float from float default', () => {
+  const result = inferArg(makeArg({ default: 3.14 }));
+  expect(result.type).toBe('float');
+});
+
+test('infers str from string default', () => {
+  const result = inferArg(makeArg({ default: 'json' }));
+  expect(result.type).toBe('str');
+});
+
+test('infers choice when options present', () => {
+  const result = inferArg(makeArg({ options: ['a', 'b'] }));
+  expect(result.type).toBe('choice');
+});
+
+test('choice wins over type inference when options present', () => {
+  const result = inferArg(makeArg({ options: ['a', 'b'], default: 'a' }));
+  expect(result.type).toBe('choice');
+});
+
+test('defaults to str when no clues', () => {
+  const result = inferArg(makeArg({}));
+  expect(result.type).toBe('str');
+});
+
+test('preserves explicit type', () => {
+  const result = inferArg(makeArg({ type: 'path' }));
+  expect(result.type).toBe('path');
+});
+
+// ── inferArg — required inference ────────────────────────────────────────────
+
+test('required=true when no default and not flag', () => {
+  const result = inferArg(makeArg({ name: 'input' }));
+  expect(result.required).toBe(true);
+});
+
+test('required=false when default present', () => {
+  const result = inferArg(makeArg({ default: 'hello' }));
+  expect(result.required).toBe(false);
+});
+
+test('required=false for flag with no default', () => {
+  const result = inferArg(makeArg({ type: 'flag' }));
+  expect(result.required).toBe(false);
+});
+
+test('required=false for flag with false default', () => {
+  const result = inferArg(makeArg({ default: false }));
+  expect(result.required).toBe(false);
+});
+
+test('preserves explicit required=false', () => {
+  const result = inferArg(makeArg({ required: false }));
+  expect(result.required).toBe(false);
+});
+
+// ── inferArg — errors ─────────────────────────────────────────────────────────
+
+test('throws when type=choice but no options', () => {
+  expect(() => inferArg(makeArg({ type: 'choice' }))).toThrow(RunSpecError);
+});
+
+// ── inferScript ───────────────────────────────────────────────────────────────
+
+test('fills autonomy from config default', () => {
+  const script: ScriptSpec = { name: 'test', args: {}, groups: {}, commands: {} };
+  const result = inferScript(script, 'confirm');
+  expect(result.autonomy).toBe('confirm');
+});
+
+test('preserves explicit autonomy', () => {
+  const script: ScriptSpec = { name: 'test', autonomy: 'autonomous', args: {}, groups: {}, commands: {} };
+  const result = inferScript(script, 'confirm');
+  expect(result.autonomy).toBe('autonomous');
+});
+
+test('infers all args', () => {
+  const script: ScriptSpec = {
+    name: 'test',
+    args: { verbose: { name: 'verbose', default: false }, workers: { name: 'workers', default: 4 } },
+    groups: {},
+    commands: {},
+  };
+  const result = inferScript(script, 'confirm');
+  expect(result.args['verbose'].type).toBe('flag');
+  expect(result.args['workers'].type).toBe('int');
+});
+
+test('recurses into subcommands', () => {
+  const script: ScriptSpec = {
+    name: 'test',
+    args: {},
+    groups: {},
+    commands: {
+      run: { name: 'run', args: { input: { name: 'input', type: 'path' } }, groups: {}, commands: {} },
+    },
+  };
+  const result = inferScript(script, 'confirm');
+  expect(result.commands['run'].autonomy).toBe('confirm');
+  expect(result.commands['run'].args['input'].required).toBe(true);
+});
+
+// ── effectiveAutonomy ─────────────────────────────────────────────────────────
+
+test('returns script autonomy when no arg overrides', () => {
+  expect(effectiveAutonomy('confirm', {}, {})).toBe('confirm');
+});
+
+test('escalates to more restrictive arg autonomy', () => {
+  const argSpecs = { apiKey: { name: 'api-key', autonomy: 'manual' } };
+  expect(effectiveAutonomy('confirm', { apiKey: 'abc' }, argSpecs)).toBe('manual');
+});
+
+test('does not de-escalate', () => {
+  const argSpecs = { verbose: { name: 'verbose', autonomy: 'autonomous' } };
+  expect(effectiveAutonomy('confirm', { verbose: true }, argSpecs)).toBe('confirm');
+});
+
+// ── isMoreRestrictive ─────────────────────────────────────────────────────────
+
+test('manual is more restrictive than confirm', () => {
+  expect(isMoreRestrictive('manual', 'confirm')).toBe(true);
+});
+
+test('autonomous is not more restrictive than confirm', () => {
+  expect(isMoreRestrictive('autonomous', 'confirm')).toBe(false);
+});

package/tests/test_integration.test.ts

@@ -0,0 +1,197 @@
+import * as path from 'path';
+import { loadRaw } from '../src/loader';
+import { inferArg, inferScript } from '../src/inference';
+import { RunSpecError } from '../src/errors';
+
+const FIXTURES = path.resolve(__dirname, '../../../tests/integration/fixtures');
+const SIMPLE = path.join(FIXTURES, 'simple.toml');
+const COMPLEX = path.join(FIXTURES, 'complex.toml');
+
+// ── simple.toml ───────────────────────────────────────────────────────────────
+
+describe('simple.toml', () => {
+  test('loads config section', () => {
+    const raw = loadRaw(SIMPLE, 'runspec');
+    expect(raw.config.autonomyDefault).toBe('confirm');
+  });
+
+  test('greet runnable present', () => {
+    const raw = loadRaw(SIMPLE, 'runspec');
+    expect(raw.runnables['greet']).toBeDefined();
+    expect(raw.runnables['greet'].description).toBe('Greet someone from the command line');
+    expect(raw.runnables['greet'].autonomy).toBe('autonomous');
+  });
+
+  test('greet args: name is str and required', () => {
+    const raw = loadRaw(SIMPLE, 'runspec');
+    const inferred = inferScript(raw.runnables['greet'], raw.config.autonomyDefault);
+    expect(inferred.args['name'].type).toBe('str');
+    expect(inferred.args['name'].required).toBe(true);
+  });
+
+  test('greet args: loud inferred as flag', () => {
+    const raw = loadRaw(SIMPLE, 'runspec');
+    const inferred = inferScript(raw.runnables['greet'], raw.config.autonomyDefault);
+    expect(inferred.args['loud'].type).toBe('flag');
+    expect(inferred.args['loud'].required).toBe(false);
+    expect(inferred.args['loud'].default).toBe(false);
+  });
+
+  test('greet args: times inferred as int', () => {
+    const raw = loadRaw(SIMPLE, 'runspec');
+    const inferred = inferScript(raw.runnables['greet'], raw.config.autonomyDefault);
+    expect(inferred.args['times'].type).toBe('int');
+    expect(inferred.args['times'].default).toBe(1);
+  });
+});
+
+// ── complex.toml ──────────────────────────────────────────────────────────────
+
+describe('complex.toml', () => {
+  test('loads config section', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    expect(raw.config.autonomyDefault).toBe('confirm');
+    expect(raw.config.lang).toBe('python');
+    expect(raw.config.version).toBe('1');
+  });
+
+  test('pipeline runnable present', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    expect(raw.runnables['pipeline']).toBeDefined();
+    expect(raw.runnables['pipeline'].description).toBe('Process and validate data pipeline files');
+  });
+
+  test('pipeline has run and validate subcommands', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const cmds = raw.runnables['pipeline'].commands;
+    expect(cmds['run']).toBeDefined();
+    expect(cmds['validate']).toBeDefined();
+  });
+
+  test('run subcommand: input is path and required', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['input'].type).toBe('path');
+    expect(run.args['input'].required).toBe(true);
+  });
+
+  test('run subcommand: format is choice with default', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['format'].type).toBe('choice');
+    expect(run.args['format'].options).toEqual(['json', 'csv', 'parquet']);
+    expect(run.args['format'].default).toBe('json');
+    expect(run.args['format'].required).toBe(false);
+  });
+
+  test('run subcommand: workers inferred as int with range', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['workers'].type).toBe('int');
+    expect(run.args['workers'].default).toBe(4);
+    expect(run.args['workers'].range).toEqual([1, 32]);
+  });
+
+  test('run subcommand: dry-run inferred as flag', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['dry-run'].type).toBe('flag');
+    expect(run.args['dry-run'].default).toBe(false);
+  });
+
+  test('run subcommand: tag is multiple', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['tag'].multiple).toBe(true);
+    expect(run.args['tag'].type).toBe('str');
+  });
+
+  test('run subcommand: fields has delimiter', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['fields'].delimiter).toBe(',');
+    expect(run.args['fields'].multiple).toBe(true);
+  });
+
+  test('run subcommand: api-key has env and autonomy', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['api-key'].env).toBe('PIPELINE_API_KEY');
+    expect(run.args['api-key'].autonomy).toBe('manual');
+  });
+
+  test('run subcommand: verbose has short flag', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['verbose'].short).toBe('-v');
+  });
+
+  test('run subcommand: threads has deprecated field', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.args['threads'].deprecated).toBe('use --workers instead');
+  });
+
+  test('run subcommand: groups defined', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.groups['input-format']).toBeDefined();
+    expect(run.groups['input-format'].exclusive).toBe(true);
+    expect(run.groups['api-auth']).toBeDefined();
+    expect(run.groups['api-auth'].inclusive).toBe(true);
+  });
+
+  test('validate subcommand: is autonomous', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const validate = inferred.commands['validate'];
+    expect(validate.autonomy).toBe('autonomous');
+  });
+
+  test('validate subcommand: format is choice', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const validate = inferred.commands['validate'];
+    expect(validate.args['format'].type).toBe('choice');
+  });
+
+  test('run subcommand: autonomy-reason preserved', () => {
+    const raw = loadRaw(COMPLEX, 'runspec');
+    const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
+    const run = inferred.commands['run'];
+    expect(run.autonomyReason).toBe('Writes output files and may call external APIs');
+  });
+});
+
+// ── cross-fixture: inference rules ────────────────────────────────────────────
+
+test('bool checked before int in inference (bool is not int)', () => {
+  const arg = inferArg({ name: 'verbose', default: false } as any);
+  expect(arg.type).toBe('flag');
+  expect(typeof arg.default).toBe('boolean');
+});
+
+test('type=path with no default is required', () => {
+  const arg = inferArg({ name: 'input', type: 'path' } as any);
+  expect(arg.required).toBe(true);
+});
+
+test('choice type with options is not required when default present', () => {
+  const arg = inferArg({ name: 'format', options: ['json', 'csv'], default: 'json' } as any);
+  expect(arg.required).toBe(false);
+  expect(arg.type).toBe('choice');
+});
+
+test('choice type with no options throws', () => {
+  expect(() => inferArg({ name: 'fmt', type: 'choice' } as any)).toThrow(RunSpecError);
+});

package/tests/test_loader.test.ts

@@ -0,0 +1,169 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { loadRaw } from '../src/loader';
+
+function tmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-test-'));
+}
+
+afterEach(() => {
+  // tmp dirs cleaned up by OS
+});
+
+// ── runspec.toml format ───────────────────────────────────────────────────────
+
+test('loads simple runspec.toml', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[greet]
+description = "Greet someone"
+autonomy = "autonomous"
+
+[greet.args]
+name = {type = "str"}
+loud = {default = false}
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.runnables['greet']).toBeDefined();
+  expect(raw.runnables['greet'].description).toBe('Greet someone');
+  expect(raw.runnables['greet'].args['name'].type).toBe('str');
+  expect(raw.runnables['greet'].args['loud'].default).toBe(false);
+});
+
+test('normalises hyphenated field names', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[deploy]
+autonomy-reason = "Irreversible"
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.runnables['deploy'].autonomyReason).toBe('Irreversible');
+});
+
+test('parses config section', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[config]
+autonomy-default = "autonomous"
+version = "1"
+
+[greet]
+description = "hi"
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.config.autonomyDefault).toBe('autonomous');
+  expect(raw.config.version).toBe('1');
+});
+
+test('config excluded from runnables', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[config]
+autonomy-default = "confirm"
+
+[greet]
+description = "hi"
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect('config' in raw.runnables).toBe(false);
+  expect('greet' in raw.runnables).toBe(true);
+});
+
+// ── pyproject.toml format ─────────────────────────────────────────────────────
+
+test('loads pyproject.toml format', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'pyproject.toml');
+  fs.writeFileSync(file, `
+[project]
+name = "myproject"
+
+[tool.runspec.greet]
+description = "Greet"
+autonomy = "confirm"
+
+[tool.runspec.greet.args]
+name = {type = "str"}
+`);
+  const raw = loadRaw(file, 'pyproject');
+  expect(raw.runnables['greet']).toBeDefined();
+  expect(raw.runnables['greet'].args['name'].type).toBe('str');
+});
+
+test('reads entry points from pyproject.toml', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'pyproject.toml');
+  fs.writeFileSync(file, `
+[project.scripts]
+greet = "myapp.greet:main"
+
+[tool.runspec.greet]
+description = "Greet"
+`);
+  const raw = loadRaw(file, 'pyproject');
+  expect(raw.entryPoints['greet']).toBe('myapp.greet:main');
+});
+
+// ── arg normalisation ─────────────────────────────────────────────────────────
+
+test('normalises bare value shorthand', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[greet]
+description = "hi"
+
+[greet.args]
+loud = false
+times = 1
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.runnables['greet'].args['loud'].default).toBe(false);
+  expect(raw.runnables['greet'].args['times'].default).toBe(1);
+});
+
+test('normalises range field', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[greet]
+description = "hi"
+
+[greet.args]
+workers = {default = 4, range = [1, 32]}
+`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.runnables['greet'].args['workers'].range).toEqual([1, 32]);
+});
+
+test('normalises group fields', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[pipeline]
+description = "hi"
+
+[pipeline.groups.formats]
+exclusive = true
+args = ["json", "csv"]
+`);
+  const raw = loadRaw(file, 'runspec');
+  const group = raw.runnables['pipeline'].groups['formats'];
+  expect(group.exclusive).toBe(true);
+  expect(group.args).toEqual(['json', 'csv']);
+});
+
+// ── defaults ──────────────────────────────────────────────────────────────────
+
+test('autonomy-default falls back to confirm', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `[greet]\ndescription = "hi"\n`);
+  const raw = loadRaw(file, 'runspec');
+  expect(raw.config.autonomyDefault).toBe('confirm');
+});