{"record":{"id":"49cdb889ba802a53","repo":"affaan-m/ECC","slug":"usage-legacy-sync-state-js-begin-record-finalize","errorCode":null,"errorMessage":"Usage: legacy-sync-state.js <begin|record|finalize|rollback> [options]","messagePattern":"Usage: legacy-sync-state\\.js <begin\\|record\\|finalize\\|rollback> \\[options\\]","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/codex/legacy-sync-state.js","lineNumber":54,"sourceCode":"    if (!statePath || !filePath) throw new Error('record requires --state and --path');\n    recordLegacySyncPath({ statePath, filePath });\n    return;\n  }\n  if (command === 'finalize') {\n    const statePath = readFlag(argv, '--state');\n    if (!statePath) throw new Error('finalize requires --state');\n    finalizeLegacySyncState({ statePath });\n    return;\n  }\n  if (command === 'rollback') {\n    const statePath = readFlag(argv, '--state');\n    if (!statePath) throw new Error('rollback requires --state');\n    const result = rollbackLegacyCodexSync({ statePath });\n    process.stdout.write(`${JSON.stringify(result)}\\n`);\n    if (result.status !== 'rolled-back') process.exitCode = 1;\n    return;\n  }\n  throw new Error('Usage: legacy-sync-state.js <begin|record|finalize|rollback> [options]');\n}\n\nmodule.exports = { main, readFlag };\n\nif (require.main === module) {\n  try {\n    main();\n  } catch (error) {\n    process.stderr.write(`[ecc-sync] ERROR: ${error.message}\\n`);\n    process.exit(1);\n  }\n}\n","sourceCodeStart":36,"sourceCodeEnd":67,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/codex/legacy-sync-state.js#L36-L67","documentation":"This is the fall-through usage error at the bottom of main() in scripts/codex/legacy-sync-state.js. If the first positional argument does not equal 'begin', 'record', 'finalize', or 'rollback', none of the if-branches return and the script throws this usage message; the process exits 1 with an '[ecc-sync] ERROR:' prefix. It is the script's only mechanism for listing valid subcommands.","triggerScenarios":"Running the script with no arguments at all; a typo'd subcommand such as `finallize` or `rec`; passing flags before the subcommand (e.g. `--state x finalize`) so argv parsing sees '--state' as the command; passing an extra positional like `node legacy-sync-state.js finalize extra` still works, but any other first token hits the fall-through.","commonSituations":"Exploring the script without reading its source and guessing subcommand names; shell aliases or npm scripts that prepend flags before the subcommand; automated pipelines invoking the script with an empty argument string.","solutions":["Use one of the four subcommands: `node scripts/codex/legacy-sync-state.js <begin|record|finalize|rollback> [options]`","Put the subcommand first: `begin --state <path>`, not `--state <path> begin`","Read the top of the file for each subcommand's required flags (begin/rollback: --state; record: --state and --path; finalize: --state)"],"exampleFix":"// before\nnode scripts/codex/legacy-sync-state.js sync\n// after\nnode scripts/codex/legacy-sync-state.js begin --state .codex-sync-state.json","handlingStrategy":"validation","validationCode":"const SUBCOMMANDS = new Set(['begin', 'record', 'finalize', 'rollback']);\nconst cmd = process.argv[2];\nif (!SUBCOMMANDS.has(cmd)) {\n  console.error('Usage: legacy-sync-state.js <begin|record|finalize|rollback> [options]');\n  process.exit(2);\n}","typeGuard":"const isLegacySyncSubcommand = (c) => ['begin', 'record', 'finalize', 'rollback'].includes(c);","tryCatchPattern":null,"preventionTips":["Always put the subcommand as the first positional argument","When wrapping the script programmatically, whitelist subcommands before spawning"],"tags":["cli","usage","unknown-command","codex"],"backgroundTag":"unknown-cli-command","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}