{"record":{"id":"9d08751fb32698c0","repo":"affaan-m/ECC","slug":"unsupported-install-target-scope-scope","errorCode":null,"errorMessage":"Unsupported install target scope: ${scope}","messagePattern":"Unsupported install target scope: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"scripts/lib/install-targets/helpers.js","lineNumber":53,"sourceCode":"  }\n\n  return false;\n}\n\nfunction resolveBaseRoot(scope, input = {}) {\n  if (scope === 'home') {\n    return input.homeDir || os.homedir();\n  }\n\n  if (scope === 'project') {\n    const projectRoot = input.projectRoot || input.repoRoot;\n    if (!projectRoot) {\n      throw new Error('projectRoot or repoRoot is required for project install targets');\n    }\n    return projectRoot;\n  }\n\n  throw new Error(`Unsupported install target scope: ${scope}`);\n}\n\nfunction buildValidationIssue(severity, code, message, extra = {}) {\n  return {\n    severity,\n    code,\n    message,\n    ...extra,\n  };\n}\n\nfunction listRelativeFiles(dirPath, prefix = '') {\n  if (!fs.existsSync(dirPath)) {\n    return [];\n  }\n\n  const entries = fs.readdirSync(dirPath, { withFileTypes: true }).sort((left, right) => (\n    left.name.localeCompare(right.name)","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/install-targets/helpers.js#L35-L71","documentation":"Thrown by resolveBaseRoot(scope, input) in scripts/lib/install-targets/helpers.js. The function translates an adapter's configured kind into a base directory on disk; only 'home' (returns input.homeDir || os.homedir()) and 'project' (returns input.projectRoot || input.repoRoot, throwing if both are absent) are supported. Any other scope is an internal invariant violation: createInstallTargetAdapter only constructs adapters whose kind is one of these two, so the throw indicates a custom adapter registered with a novel kind or a caller invoking resolveBaseRoot directly with an unsupported value.","triggerScenarios":"Registering a custom adapter via createInstallTargetAdapter({ kind: 'workspace', ... }) and calling adapter.resolveRoot({}); calling resolveBaseRoot('user', {}) directly from outside helpers.js; a fork that adds a third scope without extending resolveBaseRoot.","commonSituations":"Forking ECC to add a new install surface and reusing 'kind' for a value that is neither 'home' nor 'project'; passing a typo'd kind string when constructing an adapter; version drift where a newer adapter definition emits a kind this older helpers.js does not recognize.","solutions":["Confirm the adapter's kind is exactly the string 'home' or 'project' — those are the only two scopes resolveBaseRoot branches on.","If a genuinely new scope is required, add a branch in scripts/lib/install-targets/helpers.js that returns a concrete absolute path, and document it.","Stop calling resolveBaseRoot directly; use adapter.resolveRoot(input), which forwards the adapter's configured kind.","Audit the call site that produced the scope value — it almost certainly came from a hand-built adapter config object rather than createInstallTargetAdapter."],"exampleFix":"// before\nconst adapter = createInstallTargetAdapter({\n  id: 'foo', target: 'foo', kind: 'workspace',\n  rootSegments: ['.foo'], installStatePathSegments: ['state.json'],\n});\nadapter.resolveRoot({}); // throws: Unsupported install target scope: workspace\n\n// after\nconst adapter = createInstallTargetAdapter({\n  id: 'foo', target: 'foo', kind: 'project',\n  rootSegments: ['.foo'], installStatePathSegments: ['state.json'],\n});\nadapter.resolveRoot({ projectRoot: '/abs/path' });","handlingStrategy":"validation","validationCode":"const SUPPORTED_SCOPES = new Set(['home', 'project']);\nfunction isValidAdapterKind(kind) {\n  return SUPPORTED_SCOPES.has(kind);\n}\n// before registering or invoking:\nif (!isValidAdapterKind(adapterConfig.kind)) {\n  throw new TypeError(`Adapter kind '${adapterConfig.kind}' is unsupported; use 'home' or 'project'.`);\n}","typeGuard":"function isAdapterKind(value) {\n  return value === 'home' || value === 'project';\n}","tryCatchPattern":null,"preventionTips":["Only use createInstallTargetAdapter from helpers.js to build adapters; never hand-roll the kind field.","When forking ECC, decide upfront whether a new target lives under the user home (kind 'home') or a project root (kind 'project').","Treat resolveBaseRoot as internal — never call it directly from outside helpers.js."],"tags":["install-target","adapter","invariant","config-validation"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}