{"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":"validation","errorClass":null,"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/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/ito.js#L199-L235","documentation":"Thrown by assertUsableExecutable at scripts/ito.js:216-219 when the realpath-resolved candidate does not end with the canonical entry segments cli/ito-compute-cli/dist/bin/ito.js (CANONICAL_ENTRY_SEGMENTS, case-insensitive on win32). isCanonicalItoEntry (ito.js:229-242) normalizes the path, splits on path.sep, and compares the trailing segments. This enforces that ECC is invoking the genuine canonical entry, not a similarly-named wrapper or a renamed fork — defense against an operator pointing at a hostile or stale CLI binary that happens to be a readable file.","triggerScenarios":"ECC_ITO_CLI_EXECUTABLE resolves (realpath succeeds) but the resolved path's trailing segments are not exactly [cli, ito-compute-cli, dist, bin, ito.js]. Examples: pointing at a vendored copy under vendor/ito.js; pointing at dist/bin/ito-cli.js (renamed); pointing at a sibling package's entry.","commonSituations":"Operator copied the dist into a different layout (`~/bin/ito.js`); used a fork with a different package name; pointed at a custom wrapper script that requires the real entry; renamed the file during local hacking.","solutions":["Point ECC_ITO_CLI_EXECUTABLE at the genuine built entry inside the canonical clone: .../cli/ito-compute-cli/dist/bin/ito.js.","If you symlinked the entry elsewhere, point ECC_ITO_CLI_EXECUTABLE at the symlink target's real location (realpath will resolve the link; the resolved path must still end in the canonical segments).","Do not rename ito.js or move it out of dist/bin/."],"exampleFix":"// before\n$ export ECC_ITO_CLI_EXECUTABLE=\"$HOME/bin/my-ito.js\"   # a renamed copy\n// after\n$ export ECC_ITO_CLI_EXECUTABLE=\"$HOME/ito-cloud-runtime/cli/ito-compute-cli/dist/bin/ito.js\"","handlingStrategy":"validation","validationCode":"const path = require('path');\nconst CANONICAL_TAIL = ['cli', 'ito-compute-cli', 'dist', 'bin', 'ito.js'];\nfunction isCanonicalEntry(candidate) {\n  const segs = path.normalize(candidate).split(path.sep).filter(Boolean);\n  if (segs.length < CANONICAL_TAIL.length) return false;\n  const tail = segs.slice(-CANONICAL_TAIL.length);\n  return tail.every((s, i) => process.platform === 'win32'\n    ? s.toLowerCase() === CANONICAL_TAIL[i].toLowerCase()\n    : s === CANONICAL_TAIL[i]);\n}\nfunction assertCanonical(candidate) {\n  if (!isCanonicalEntry(candidate)) throw new Error(`path does not end with ${CANONICAL_TAIL.join('/')}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never rename the canonical entry or move it out of dist/bin/.","If you symlink for convenience, point ECC_ITO_CLI_EXECUTABLE at the real path so realpath resolves to the canonical layout.","Avoid vendoring the CLI into a different package structure."],"tags":["cli","ito","security","path","validation","canonical-entry"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}