{"record":{"id":"71265d98b6a980c3","repo":"affaan-m/ECC","slug":"executable-override-must-point-to-the-canonical","errorCode":null,"errorMessage":"${EXECUTABLE_OVERRIDE} must point to the canonical dist/bin/ito.js entry.","messagePattern":"(.+?) must point to the canonical dist/bin/ito\\.js entry\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/ito.js","lineNumber":217,"sourceCode":"  if (!path.isAbsolute(configured)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} must be an absolute path explicitly configured by the operator.`\n    );\n  }\n  return assertUsableExecutable(configured);\n}\n\nfunction assertUsableExecutable(candidate) {\n  let canonicalCandidate;\n  try {\n    canonicalCandidate = fs.realpathSync.native(candidate);\n  } catch {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`\n    );\n  }\n  if (!isCanonicalItoEntry(canonicalCandidate)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} must point to the canonical dist/bin/ito.js entry.`\n    );\n  }\n  if (!isUsableExecutable(canonicalCandidate)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`\n    );\n  }\n  return canonicalCandidate;\n}\n\nfunction isCanonicalItoEntry(candidate) {\n  const pathSegments = path\n    .normalize(candidate)\n    .split(path.sep)\n    .filter(Boolean);\n  if (pathSegments.length < CANONICAL_ENTRY_SEGMENTS.length) return false;\n  const candidateTail = pathSegments.slice(-CANONICAL_ENTRY_SEGMENTS.length);","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/ito.js#L199-L235","documentation":"After realpath succeeds, isCanonicalItoEntry verifies that the normalized absolute path ends with the exact canonical segment sequence CANONICAL_ENTRY_SEGMENTS (dist/bin/ito.js beneath cli/ito-compute-cli — see scripts/ito.js:16). This rejects wrappers, renamed entries, and alternative launchers so ECC only ever execs the audited entry file. Any path whose trailing segments do not match exactly fails here.","triggerScenarios":"Pointing ECC_ITO_CLI_EXECUTABLE at the package root, bin/ito.js (a source-level shim) instead of dist/bin/ito.js, a copied/renamed ito.js, or an out-directory like build/bin/ito.js.","commonSituations":"Operators 'simplifying' the path or symlinking a friendly name like ~/.local/bin/ito-cli (realpath resolves it, but the underlying path must still end in the canonical segments); custom fork builds writing to a different out dir.","solutions":["Point the variable at the exact built entry: <repo>/cli/ito-compute-cli/dist/bin/ito.js.","If your build writes elsewhere, symlink or copy the artifact so the real path ends in cli/ito-compute-cli/dist/bin/ito.js, then point there.","Run `node -e \"console.log(require('fs').realpathSync.native(process.env.ECC_ITO_CLI_EXECUTABLE))\"` to see what path ECC actually checks."],"exampleFix":"# before\nexport ECC_ITO_CLI_EXECUTABLE=\"$HOME/src/ito-cloud-runtime/cli/ito-compute-cli/bin/ito.js\"\n\n# after\nexport ECC_ITO_CLI_EXECUTABLE=\"$HOME/src/ito-cloud-runtime/cli/ito-compute-cli/dist/bin/ito.js\"","handlingStrategy":"validation","validationCode":"import path from 'node:path';\nconst CANONICAL_SUFFIX = path.join('cli', 'ito-compute-cli', 'dist', 'bin', 'ito.js');\nfunction isCanonicalEntry(p) {\n  return path.normalize(p).endsWith(CANONICAL_SUFFIX);\n}\nfunction assertCanonicalItoEntry(p) {\n  if (!isCanonicalEntry(p)) throw new Error(`Expected path ending in ${CANONICAL_SUFFIX}, got ${p}`);\n  return p;\n}","typeGuard":"function isCanonicalItoEntryPath(p) {\n  return typeof p === 'string' && path.normalize(p).endsWith(path.join('cli', 'ito-compute-cli', 'dist', 'bin', 'ito.js'));\n}","tryCatchPattern":null,"preventionTips":["Always point the env var at the built dist/bin/ito.js, never bin/, src/, or a renamed copy.","Note that symlinks are resolved first — the underlying real path must end in the canonical segments."],"tags":["path-validation","configuration","ito"],"backgroundTag":"invalid-config-path","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}