{"record":{"id":"3a267fd01bc789cf","repo":"affaan-m/ECC","slug":"begin-requires-codex-home-and-backup-dir","errorCode":null,"errorMessage":"begin requires --codex-home and --backup-dir","messagePattern":"begin requires --codex-home and --backup-dir","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/codex/legacy-sync-state.js","lineNumber":24,"sourceCode":"  finalizeLegacySyncState,\n  recordLegacySyncPath,\n  rollbackLegacyCodexSync,\n} = require('../lib/codex-legacy-sync');\n\nfunction readFlag(args, name) {\n  const index = args.indexOf(name);\n  if (index === -1) return null;\n  const value = args[index + 1];\n  if (!value || value.startsWith('--')) return null;\n  return value;\n}\n\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');","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/codex/legacy-sync-state.js#L6-L42","documentation":"scripts/codex/legacy-sync-state.js is a small state-machine CLI (begin/record/finalize/rollback) used by the Codex legacy sync to migrate hooks atomically with backup/rollback. `begin` must know where CODEX_HOME lives and where backups are written, so it requires both --codex-home and --backup-dir; readFlag() returns null when a flag is absent, its value is missing, or the next token starts with '--', and any null triggers this throw.","triggerScenarios":"Invoking `begin` without one of the two flags; ordering mistakes such as `--backup-dir --previous-hooks-path x` where the value slot holds the next flag; a path argument that itself begins with '--'.","commonSituations":"Running the helper manually without the full argument set the sync wrapper normally supplies; misordered arguments in wrapper scripts; quoting or variable-expansion mistakes eating a value.","solutions":["Provide both required flags with values: `node scripts/codex/legacy-sync-state.js begin --codex-home ~/.codex --backup-dir /tmp/ecc-backup`","Keep optional flags (--previous-hooks-path, --installed-hooks-path) after the required pair, each immediately followed by its own value","If a legitimate path starts with '-', express it absolutely (e.g. /home/user/-weird) so it does not look like a flag"],"exampleFix":"# before\nnode scripts/codex/legacy-sync-state.js begin --codex-home ~/.codex\n# after\nnode scripts/codex/legacy-sync-state.js begin --codex-home ~/.codex --backup-dir /tmp/ecc-backup","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, '--codex-home') || !readFlag(argv, '--backup-dir')) {\n  throw new Error('begin requires --codex-home and --backup-dir');\n}","typeGuard":"function hasRequiredBeginFlags(argv) {\n  const get = n => { const i = argv.indexOf(n); const v = argv[i + 1]; return i !== -1 && v && !v.startsWith('--'); };\n  return get('--codex-home') && get('--backup-dir');\n}","tryCatchPattern":"try {\n  main(argv);\n} catch (error) {\n  if (/^begin requires/.test(error.message)) {\n    process.stderr.write('Usage: legacy-sync-state.js begin --codex-home <dir> --backup-dir <dir>\\n');\n  }\n}","preventionTips":["Keep required flags and their values adjacent in wrapper scripts","Validate flag/value pairs before invoking the state-machine CLI","Express unusual paths absolutely so they never look like flags"],"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-14T00:17:10.932Z"}