{"record":{"id":"3bf5314970c54df7","repo":"affaan-m/ECC","slug":"record-requires-state-and-path","errorCode":null,"errorMessage":"record requires --state and --path","messagePattern":"record requires --state and --path","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/codex/legacy-sync-state.js","lineNumber":36,"sourceCode":"\nfunction main(argv = process.argv.slice(2)) {\n  const command = argv[0];\n  if (command === 'begin') {\n    const codexHome = readFlag(argv, '--codex-home');\n    const backupDir = readFlag(argv, '--backup-dir');\n    if (!codexHome || !backupDir) throw new Error('begin requires --codex-home and --backup-dir');\n    process.stdout.write(`${beginLegacySyncState({\n      codexHome,\n      backupDir,\n      previousHooksPath: readFlag(argv, '--previous-hooks-path') || '',\n      installedHooksPath: readFlag(argv, '--installed-hooks-path'),\n    })}\\n`);\n    return;\n  }\n  if (command === 'record') {\n    const statePath = readFlag(argv, '--state');\n    const filePath = readFlag(argv, '--path');\n    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]');","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/codex/legacy-sync-state.js#L18-L54","documentation":"The `record` step appends a migrated file path to the sync-state journal created by `begin`, so it needs the state file location (--state) and the affected file path (--path). readFlag() returns null for a missing flag, a missing value, or a value starting with '--'; if either --state or --path yields null, this error is thrown before anything is journaled.","triggerScenarios":"`record` invoked without --state or without --path; the state path from `begin` not captured (begin prints it to stdout, which wrappers must thread through); a value slot occupied by the next flag.","commonSituations":"Wrapper scripts that call begin but forget to capture its printed state path before calling record; manual invocation while debugging the sync; empty variables interpolated as values.","solutions":["Capture begin's output and pass both values: `STATE=$(node scripts/codex/legacy-sync-state.js begin --codex-home ... --backup-dir ...)`, then `record --state \"$STATE\" --path <file>`","Ensure both values are non-empty and neither starts with '--'","If the state file was lost, restart the sequence with a fresh `begin` before recording"],"exampleFix":"# before\nnode scripts/codex/legacy-sync-state.js record --path hooks.json\n# after\nSTATE=$(node scripts/codex/legacy-sync-state.js begin --codex-home ~/.codex --backup-dir /tmp/bak)\nnode scripts/codex/legacy-sync-state.js record --state \"$STATE\" --path hooks.json","handlingStrategy":"validation","validationCode":"function readFlag(args, name) {\n  const i = args.indexOf(name);\n  if (i === -1) return null;\n  const v = args[i + 1];\n  return v && !v.startsWith('--') ? v : null;\n}\nif (!readFlag(argv, '--state') || !readFlag(argv, '--path')) {\n  throw new Error('record requires --state and --path');\n}","typeGuard":"function hasRequiredRecordFlags(argv) {\n  const get = n => { const i = argv.indexOf(n); const v = argv[i + 1]; return i !== -1 && v && !v.startsWith('--'); };\n  return get('--state') && get('--path');\n}","tryCatchPattern":"try {\n  main(argv);\n} catch (error) {\n  if (/^record requires/.test(error.message)) {\n    process.stderr.write('Usage: legacy-sync-state.js record --state <file> --path <file>\\n');\n  }\n}","preventionTips":["Capture begin's stdout state path and thread it into every record call","Assert both --state and --path are non-empty before spawning","Restart with a fresh begin if the state file is lost"],"tags":["cli","codex","argument-parsing","legacy-sync"],"backgroundTag":"missing-cli-option-value","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}