{"record":{"id":"d7148f9e42f641ff","repo":"Hmbown/CodeWhale","slug":"choose-one-input-source-an-unused-output-path-or-resume-and","errorCode":null,"errorMessage":"Choose one input source, an unused --output path (or --resume), and JSONL for live recording. Runtime requires --thread.","messagePattern":"Choose one input source, an unused --output path \\(or --resume\\), and JSONL for live recording\\. Runtime requires --thread\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"pet/scripts/pet.mjs","lineNumber":25,"sourceCode":"import { compilePetTelemetry, encodePetJSONL, encodePetTSV } from '../dist/core/pet-telemetry.js';\nimport { petDemoEvents } from '../dist/core/pet-demo.js';\nimport { followRuntime } from './lib/pet-runtime.mjs';\nimport { createPetRecorder } from './lib/pet-recorder.mjs';\n\nconst args = process.argv.slice(2);\nconst option = name => args.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);\nif (args.includes('--help')) {\n  console.log('node scripts/pet.mjs --input=trace.jsonl --output=pet.jsonl [--trace=ID] [--format=jsonl|tsv] [--watch]\\nnode scripts/pet.mjs --runtime=http://127.0.0.1:7878 --thread=ID --output=pet.jsonl [--segment-buckets=216000] [--resume]\\nUse --demo instead of --input for synthetic telemetry. Output must not already exist unless --resume is used for live recording. A resumed recorder preserves the previous segment and starts unknown at the same path.\\nLive recording rotates at 216000 buckets or 64 MiB into OUTPUT.segment-NNNNNN.jsonl and continues at the same live path. All archives are retained.\\nRuntime reads only the existing local event journal. Optional authentication comes from CODEWHALE_RUNTIME_TOKEN; never put a token in the URL. No agent or provider is started.');\n  process.exit(0);\n}\nlet output, recorder, monitor, timer, runtime;\ntry {\n  for (const a of args) if (!['--demo', '--watch', '--resume'].includes(a) && !/^--(input|output|trace|format|runtime|thread|segment-buckets)=.+/.test(a)) throw new Error('Unknown or empty option. Use --help.');\n  const input = option('input'), runtimeURL = option('runtime'), path = option('output'), format = option('format') ?? 'jsonl', live = args.includes('--watch') || !!runtimeURL;\n  if (!path || [!!input, args.includes('--demo'), !!runtimeURL].filter(Boolean).length !== 1\n    || !['jsonl', 'tsv'].includes(format) || live && format !== 'jsonl' || args.includes('--watch') && !input\n    || !!runtimeURL !== !!option('thread') || option('trace') && !input || option('segment-buckets') && !live || args.includes('--resume') && !live)\n    throw new Error('Choose one input source, an unused --output path (or --resume), and JSONL for live recording. Runtime requires --thread.');\n  const load = async () => {\n    if (!input) return { events: petDemoEvents(), duration: 80_000 };\n    if ((await stat(input)).size > 64 * 1024 * 1024) throw new Error('Input exceeds 64 MiB.');\n    const traces = importTrace(await readFile(input, 'utf8'), input, { privacy: 'metadata' });\n    const trace = option('trace') ? traces.find(t => t.id === option('trace')) : traces.length === 1 ? traces[0] : undefined;\n    if (!trace) throw new Error('Select an existing --trace ID when input contains multiple traces.');\n    return trace;\n  };\n  let trace = runtimeURL ? undefined : await load(), buckets = compilePetTelemetry(trace?.events ?? [], trace?.duration ?? 0);\n  if (live) recorder = await createPetRecorder(path, { resume: args.includes('--resume'), maxBuckets: option('segment-buckets') === undefined ? 216_000 : Number(option('segment-buckets')), report: text => console.error(text) });\n  else output = await open(path, 'wx', 0o600);\n  if (runtimeURL) runtime = await followRuntime({ baseUrl: runtimeURL, threadId: option('thread'),\n    token: process.env.CODEWHALE_RUNTIME_TOKEN, report: text => console.error(text) });\n  if (!live) {\n    await output.writeFile(format === 'tsv' ? encodePetTSV(buckets) : encodePetJSONL(buckets));\n    await output.close(); output = undefined;\n    console.log(`Wrote ${buckets.length} pet buckets (${args.includes('--demo') ? 'demo' : 'trace replay'}).`);\n  } else {","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/pet/scripts/pet.mjs#L7-L43","documentation":"After syntax validation, pet.mjs enforces its input-source contract: --output is required; exactly one of --input, --demo, --runtime must be given; live modes (--watch or --runtime) require --format=jsonl; --watch requires --input; --runtime requires --thread (and vice versa); --trace requires --input; --segment-buckets requires live mode; --resume requires live mode. Any violation of these mutual constraints throws this combined-message error.","triggerScenarios":"No --output path; combining two or three of --input/--demo/--runtime; --runtime without --thread (or --thread without --runtime); using --format=tsv with --watch or --runtime; --watch without --input; --trace without --input; --segment-buckets with a non-live source; --resume without live recording.","commonSituations":"Forgot --thread when pointing at a Runtime URL; tried TSV output for a live recording; combined --demo with --input while experimenting; added --resume to a one-shot file conversion.","solutions":["Pick exactly one source: either --input=<file>, or --demo, or --runtime=<url> with --thread=<id>.","Always pass --output=<path> that doesn't already exist (unless resuming a live recording).","Use --format=jsonl (the default) for --watch or --runtime recording; reserve tsv for file conversion.","Drop --resume and --segment-buckets unless doing live recording; drop --trace unless converting an --input file.","Run --help to see the full accepted usage line."],"exampleFix":"// before\nnode scripts/pet.mjs --runtime=http://127.0.0.1:7878 --output=pet.jsonl\n// after\nnode scripts/pet.mjs --runtime=http://127.0.0.1:7878 --thread=abc123 --output=pet.jsonl","handlingStrategy":"validation","validationCode":"function validatePetArgs(args) {\n  const opt = n => (args.find(a => a.startsWith(`--${n}=`)) ?? '').split('=')[1];\n  const has = f => args.includes(f);\n  const sources = [!!opt('input'), has('--demo'), !!opt('runtime')].filter(Boolean).length;\n  return opt('output') && sources === 1 && ['jsonl','tsv'].includes(opt('format') ?? 'jsonl') &&\n    (!opt('runtime') || !!opt('thread'));\n}\nif (!validatePetArgs(args)) console.error('pick one source + --output (+ --thread for --runtime)');","typeGuard":null,"tryCatchPattern":"try {\n  await runPetCli(args);\n} catch (err) {\n  if (err.message.startsWith('Choose one input source')) {\n    console.error('Usage: node scripts/pet.mjs --help'); process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Choose exactly one of --input, --demo, --runtime per invocation.","Remember --runtime always pairs with --thread, and live modes require jsonl output.","Only use --resume, --segment-buckets, and --watch in live-recording scenarios.","Build command lines from the --help usage string, not ad hoc."],"tags":["cli","mutually-exclusive","argument-validation"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-22T21:17:16.096Z"}