create-agdf 0.14.4 → 0.20.0

package/lib/host-command.js

@@ -0,0 +1,112 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { win32 } from "node:path";
+import process from "node:process";
+
+// Host CLIs installed through npm on Windows are .cmd shims, which execFile cannot start (ENOENT for
+// the bare name, EINVAL for the shim itself since CVE-2024-27980). Recognized npm shims start their
+// target directly, so no argument passes through cmd.exe; any other shim fails closed.
+const LAUNCHABLE_EXTENSIONS = new Set([".com", ".exe"]);
+const SHIM_EXTENSIONS = new Set([".bat", ".cmd"]);
+const SHIM_BOILERPLATE = new Set([
+  "@echo off", "goto start", ":find_dp0", "set dp0=%~dp0", "exit /b", ":start", "setlocal", "call :find_dp0",
+  "endlocal", "exit /b %errorlevel%",
+  "if exist \"%dp0%\\node.exe\" (", "set \"_prog=%dp0%\\node.exe\"", ") else (", "set \"_prog=node\"",
+  "set pathext=%pathext:;.js;=;%", ")",
+]);
+const LAUNCH_PREFIX = /^endlocal & goto #_undefined_# 2>nul \|\| title %comspec% & /i;
+const DIRECT_LAUNCH = /^"%dp0%\\([^"%*]+)"\s+%\*$/i;
+const NODE_LAUNCH = /^"%_prog%"\s+((?:[^\s"%*]+\s+)*?)"%dp0%\\([^"%*]+)"\s+%\*$/i;
+
+// Like Node's spawn on Windows, the lexicographically first case-insensitive match wins, so
+// { ...process.env, PATH } resolves against the PATH the child process will actually receive.
+function envValue(env, name) {
+  const key = Object.keys(env).filter((candidate) => candidate.toUpperCase() === name).sort()[0];
+  return key === undefined ? undefined : env[key];
+}
+
+function isFile(path, fs) {
+  try {
+    return fs.statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function unsupportedShim(path) {
+  const error = new Error(`AGDF_HOST_COMMAND_UNSUPPORTED_SHIM: ${path} is not a recognized npm command shim; AGDF does not start host commands through cmd.exe.`);
+  error.code = "AGDF_HOST_COMMAND_UNSUPPORTED_SHIM";
+  return error;
+}
+
+export function findWindowsCommand(command, { env = process.env, fs = { statSync }, extensions } = {}) {
+  const candidates = extensions ?? (envValue(env, "PATHEXT") || ".COM;.EXE;.BAT;.CMD").split(";")
+    .map((extension) => extension.trim().toLowerCase())
+    .filter((extension) => LAUNCHABLE_EXTENSIONS.has(extension) || SHIM_EXTENSIONS.has(extension));
+  const directories = (envValue(env, "PATH") || "").split(";")
+    .map((directory) => directory.trim().replace(/^"(.*)"$/, "$1"))
+    .filter((directory) => directory && win32.isAbsolute(directory));
+  for (const directory of directories) {
+    for (const extension of candidates) {
+      const candidate = win32.join(directory, `${command}${extension}`);
+      if (isFile(candidate, fs)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function parseNpmCmdShim(shimPath, content) {
+  const lines = content.replace(/\r\n/g, "\n").split("\n").map((line) => line.trim()).filter(Boolean);
+  const launches = lines.filter((line) => line.includes("%*"));
+  if (launches.length !== 1 || lines.some((line) => !line.includes("%*") && !SHIM_BOILERPLATE.has(line.toLowerCase()))) return null;
+  const directory = win32.dirname(shimPath);
+  const launch = launches[0].replace(LAUNCH_PREFIX, "");
+  const direct = launch.match(DIRECT_LAUNCH);
+  if (direct) {
+    return LAUNCHABLE_EXTENSIONS.has(win32.extname(direct[1]).toLowerCase())
+      ? { executable: win32.resolve(directory, direct[1]), prefixArgs: [] }
+      : null;
+  }
+  const viaNode = launch.match(NODE_LAUNCH);
+  if (!viaNode || !lines.some((line) => line.toLowerCase() === "set \"_prog=node\"")) return null;
+  return {
+    node: win32.join(directory, "node.exe"),
+    prefixArgs: [...viaNode[1].split(/\s+/).filter(Boolean), win32.resolve(directory, viaNode[2])],
+  };
+}
+
+export function resolveHostCommand(command, {
+  env = process.env, platform = process.platform, execPath = process.execPath, fs = { readFileSync, statSync },
+} = {}) {
+  const unresolved = { executable: command, prefixArgs: [] };
+  if (platform !== "win32") return unresolved;
+  const explicitShim = /[\\/]/.test(command) && SHIM_EXTENSIONS.has(win32.extname(command).toLowerCase());
+  if (!explicitShim && (/[\\/]/.test(command) || win32.extname(command))) return unresolved;
+  if (explicitShim && !isFile(command, fs)) {
+    throw Object.assign(new Error(`spawn ${command} ENOENT`), { code: "ENOENT", syscall: `spawn ${command}`, path: command });
+  }
+  const found = explicitShim ? command : findWindowsCommand(command, { env, fs });
+  if (!found) return unresolved;
+  if (LAUNCHABLE_EXTENSIONS.has(win32.extname(found).toLowerCase())) return { executable: found, prefixArgs: [] };
+  const shim = parseNpmCmdShim(found, fs.readFileSync(found, "utf8"));
+  if (!shim) throw unsupportedShim(found);
+  if (shim.executable) return { executable: shim.executable, prefixArgs: [] };
+  const node = isFile(shim.node, fs) ? shim.node
+    : findWindowsCommand("node", { env, fs, extensions: [".com", ".exe"] }) ?? execPath;
+  return { executable: node, prefixArgs: shim.prefixArgs };
+}
+
+export function execHostFileSync(command, args = [], options = {}) {
+  const { executable, prefixArgs } = resolveHostCommand(command, { env: options.env ?? process.env });
+  return execFileSync(executable, [...prefixArgs, ...args], options);
+}
+
+export function spawnHostSync(command, args = [], options = {}) {
+  let resolved;
+  try {
+    resolved = resolveHostCommand(command, { env: options.env ?? process.env });
+  } catch (error) {
+    return { pid: 0, output: [null, "", ""], stdout: "", stderr: "", status: null, signal: null, error };
+  }
+  return spawnSync(resolved.executable, [...resolved.prefixArgs, ...args], options);
+}

package/lib/install-setup/contract.js

@@ -0,0 +1,319 @@
+import { INSTALL_SETUP_STATES, INSTALL_ACTIONS, INSTALL_FAILURE_PHASES, INSTALL_FAILURE_CODES, codexHookState } from "#agdf-core/interaction-catalog.js";
+import { isAbsolute } from "node:path";
+import { assertLifecycleResult } from "../lifecycle/result.js";
+import { mcpCapabilityProfileContract } from "../mcp-lifecycle/profile.js";
+import { assertControlMigration, uncheckedControl } from "./control-migration.js";
+
+const SURFACES = new Set(mcpCapabilityProfileContract.surfaces);
+const SETUP_REQUESTS = new Set(["plugin_only", "full", "cancel"]);
+const EFFECTIVE_STATES = new Set(Object.keys(INSTALL_SETUP_STATES));
+const RESULTS = new Set(["success", "partial", "failed", "cancelled"]);
+const TARGET_SOURCES = new Set(["explicit_dir", "interactive_invocation_cwd_selection", "none"]);
+const PREFLIGHT_TARGET_SOURCES = new Set(["explicit_dir", "interactive_invocation_cwd_proposal", "none"]);
+const INVOCATION_DIRECTORY_SOURCES = new Set(["explicit_dir", "npm_init_cwd", "process_cwd", "none"]);
+const SCOPES = new Set(["project", "user"]);
+const INTERACTIONS = new Set(["required", "not_required"]);
+const PLUGIN_PREFLIGHT_STATES = new Set(["observed", "healthy", "degraded", "not_installed", "unavailable", "unknown"]);
+const MCP_STATES = new Set([...mcpCapabilityProfileContract.resultStates, "not_requested", "not_checked", "plugin_managed"]);
+const RUNTIME_CHECK_STATES = new Set([
+  "not_run",
+  "not_checked",
+  "cancelled",
+  "manual",
+  "decision_required",
+  "enabled",
+  "renewal_required",
+  "degraded",
+  "failed",
+  "unavailable",
+  "receipt_missing",
+  "receipt_unowned",
+  "receipt_invalid",
+  "unknown",
+]);
+const FULL_BLOCK_REASONS = new Set(["none", "target_required", "mcp_foreign", "mcp_precedence_conflict", "mcp_invalid", "mcp_preflight_failed"]);
+const MCP_EFFECTIVE_SOURCES = new Set([
+  "none", "unknown", "user", "project", "project_override", "local", "shared_project", "inline", "custom",
+]);
+const FAILURE_PHASES = new Set(INSTALL_FAILURE_PHASES);
+const FAILURE_CODES = new Set(INSTALL_FAILURE_CODES);
+const NEXT_ACTION_CODES = new Set(INSTALL_ACTIONS);
+
+
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed, code) {
+  if (!plainObject(value) || Object.keys(value).some((key) => !allowed.includes(key))) throw new Error(code);
+}
+
+function cloneAndFreeze(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(cloneAndFreeze));
+  if (plainObject(value)) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cloneAndFreeze(child)])));
+  }
+  return value;
+}
+
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function assertCodedAction(action) {
+  exactKeys(action, ["code", "parameters", "text"], "AGDF_INSTALL_SETUP_RESULT_INVALID");
+  if (!NEXT_ACTION_CODES.has(action.code) || !plainObject(action.parameters)
+      || Object.values(action.parameters).some((value) => !["string", "number", "boolean"].includes(typeof value))
+      || !(action.text === null || typeof action.text === "string")) {
+    throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+  }
+}
+
+function assertFailure(failure) {
+  if (failure === null) return;
+  exactKeys(failure, ["phase", "code", "message", "evidence"], "AGDF_INSTALL_SETUP_RESULT_INVALID");
+  if (!FAILURE_PHASES.has(failure.phase) || !FAILURE_CODES.has(failure.code)
+      || typeof failure.message !== "string" || !failure.message.trim() || !stringArray(failure.evidence ?? [])) {
+    throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+  }
+}
+
+function pluginVerified(plugin) {
+  if (plugin?.status === "not_run") return false;
+  try { assertLifecycleResult(plugin); } catch { return false; }
+  return plugin.result !== "failed"
+    && ["healthy", "configured", "configured_pending_restart"].includes(plugin.verification?.status);
+}
+
+function mcpState(mcp) {
+  if (mcp?.status && ["not_requested", "not_checked", "plugin_managed"].includes(mcp.status)) return mcp.status;
+  return mcp?.result;
+}
+
+function assertMcpPart(mcp) {
+  if (mcp?.status && ["not_requested", "not_checked", "plugin_managed"].includes(mcp.status)) {
+    exactKeys(mcp, ["status"], "AGDF_INSTALL_SETUP_RESULT_INVALID");
+    return;
+  }
+  if (!plainObject(mcp) || mcp.schema_version !== 2 || mcp.contract_version !== 2
+      || !MCP_STATES.has(mcp.result) || mcp.authorizes !== false
+      || !SURFACES.has(mcp.surface) || !SCOPES.has(mcp.scope)) {
+    throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+  }
+}
+
+function assertPluginPart(plugin, setupRequest) {
+  if (plugin?.status === "not_run") {
+    exactKeys(plugin, ["status"], "AGDF_INSTALL_SETUP_RESULT_INVALID");
+    return;
+  }
+  assertLifecycleResult(plugin);
+}
+
+function runtimeCheckState(runtimeChecks) {
+  return runtimeChecks?.effective ?? runtimeChecks?.status;
+}
+
+export function codexHookReviewPending(surface, runtimeChecks) {
+  return surface === "codex" && runtimeChecks?.requested === "enabled"
+    && runtimeChecks.effective === "decision_required"
+    && runtimeChecks.mcp_approval?.status === "configured";
+}
+
+export function codexPendingHookAction(runtimeChecks) {
+  return codexHookState(runtimeChecks?.verification).action;
+}
+
+export function deriveInstallSetupState({ setup_request: setupRequest, surface, plugin, runtime_checks: runtimeChecks, mcp, failure, control }) {
+  if (setupRequest === "cancel") return "cancelled";
+  if (plugin?.status === "not_run" && ["cancel", "cancelled"].includes(runtimeCheckState(runtimeChecks))) return "cancelled";
+  if (!pluginVerified(plugin)) return "failed";
+  if (failure?.phase === "runtime_check_permission") return "partial";
+  if (!failure && control?.status === "repair_required") return "control_repair_required";
+  if (!failure && control?.status === "migration_required") return "control_migration_required";
+  const state = mcpState(mcp);
+  if (setupRequest === "plugin_only") {
+    if (state === "plugin_managed" && !failure && codexHookReviewPending(surface, runtimeChecks)) {
+      return codexHookState(runtimeChecks.verification).state;
+    }
+    if (state === "plugin_managed") return "plugin_ready_mcp_in_plugin";
+    if (["foreign", "owned_mismatch", "precedence_conflict", "invalid"].includes(mcp?.registration?.status)
+        || state === "degraded") return "degraded_or_foreign";
+    if (["not_requested", "not_checked", "not_configured"].includes(state)) return "plugin_ready_mcp_absent";
+    return "plugin_ready_mcp_unchanged";
+  }
+  if (["failed", "degraded", "not_configured", "disabled"].includes(state)) return "partial";
+  if (state === "configured_pending_restart") return "configured_pending_restart";
+  if (["configured_unverified", "unchanged"].includes(state)) return "configured_unverified";
+  if (state === "discovered_ready") return "discovered_ready";
+  throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+}
+
+function resultForState(state) {
+  return INSTALL_SETUP_STATES[state]?.result;
+}
+
+export function createInstallSetupPreflight(input = {}) {
+  exactKeys(input, [
+    "surface", "version", "interaction", "plugin", "mcp_by_scope", "target", "target_source",
+    "invocation_directory_source", "requested_scope", "effective_scope", "plugin_configuration", "local_execution",
+    "package_acquisition_required", "removal_overview", "full_available", "full_block_reason", "control", "authorizes",
+  ], "AGDF_INSTALL_SETUP_PREFLIGHT_INVALID");
+  const target = input.target ?? null;
+  const requestedScope = input.requested_scope ?? null;
+  const effectiveScope = input.effective_scope ?? null;
+  const pluginConfiguration = input.plugin_configuration ?? null;
+  const invocationDirectorySource = input.invocation_directory_source ?? "none";
+  const fullBlockReason = input.full_block_reason ?? "none";
+  const control = assertControlMigration(input.control ?? uncheckedControl());
+  const scopeStateValid = (state) => plainObject(state)
+    && Object.keys(state).every((key) => [
+      "status", "capability", "selected_status", "effective_source", "registration_path",
+      "available", "block_reason", "removal_command",
+    ].includes(key))
+    && MCP_STATES.has(state.status)
+    && typeof state.capability === "string" && state.capability.trim()
+    && mcpCapabilityProfileContract.registrationStates.includes(state.selected_status)
+    && MCP_EFFECTIVE_SOURCES.has(state.effective_source)
+    && (state.registration_path === null || (typeof state.registration_path === "string" && state.registration_path.trim()))
+    && typeof state.available === "boolean" && FULL_BLOCK_REASONS.has(state.block_reason)
+    && ((state.available && state.block_reason === "none") || (!state.available && state.block_reason !== "none"))
+    && typeof state.removal_command === "string" && state.removal_command.trim();
+  if (!SURFACES.has(input.surface) || typeof input.version !== "string" || !input.version.trim()
+      || !INTERACTIONS.has(input.interaction) || !plainObject(input.plugin)
+      || !PLUGIN_PREFLIGHT_STATES.has(input.plugin.status) || !stringArray(input.plugin.evidence ?? [])
+      || !plainObject(input.mcp_by_scope) || Object.keys(input.mcp_by_scope).length !== 2
+      || !scopeStateValid(input.mcp_by_scope.project) || !scopeStateValid(input.mcp_by_scope.user)
+      || !(target === null || (typeof target === "string" && isAbsolute(target)))
+      || !PREFLIGHT_TARGET_SOURCES.has(input.target_source)
+      || !INVOCATION_DIRECTORY_SOURCES.has(invocationDirectorySource)
+      || !(requestedScope === null || SCOPES.has(requestedScope))
+      || !(effectiveScope === null || SCOPES.has(effectiveScope))
+      || !(pluginConfiguration === null || (typeof pluginConfiguration === "string" && isAbsolute(pluginConfiguration)))
+      || typeof input.local_execution !== "boolean" || typeof input.package_acquisition_required !== "boolean"
+      || typeof input.removal_overview !== "string" || !input.removal_overview.trim()
+      || typeof input.full_available !== "boolean" || !FULL_BLOCK_REASONS.has(fullBlockReason)
+      || input.authorizes !== false
+      || (input.full_available && fullBlockReason !== "none")
+      || (!input.full_available && fullBlockReason === "none")
+      || ((input.target_source === "none") !== (target === null))
+      || (input.target_source === "explicit_dir" && invocationDirectorySource !== "explicit_dir")
+      || (input.target_source === "interactive_invocation_cwd_proposal"
+        && !["npm_init_cwd", "process_cwd"].includes(invocationDirectorySource))
+      || (input.target_source === "none" && invocationDirectorySource !== "none")) {
+    throw new Error("AGDF_INSTALL_SETUP_PREFLIGHT_INVALID");
+  }
+  return cloneAndFreeze({
+    schema_version: 1,
+    surface: input.surface,
+    version: input.version,
+    interaction: input.interaction,
+    plugin: input.plugin,
+    mcp_by_scope: input.mcp_by_scope,
+    target,
+    target_source: input.target_source,
+    invocation_directory_source: invocationDirectorySource,
+    requested_scope: requestedScope,
+    effective_scope: effectiveScope,
+    plugin_configuration: pluginConfiguration,
+    local_execution: input.local_execution,
+    package_acquisition_required: input.package_acquisition_required,
+    removal_overview: input.removal_overview,
+    full_available: input.full_available,
+    full_block_reason: fullBlockReason,
+    control,
+    authorizes: false,
+  });
+}
+
+export function createInstallSetupResult(input = {}) {
+  exactKeys(input, [
+    "result", "setup_request", "effective_state", "surface", "target", "target_source",
+    "invocation_directory_source", "requested_scope", "effective_scope", "plugin", "runtime_checks", "mcp", "discovery",
+    "restart", "failure", "next_action", "control", "authorizes",
+  ], "AGDF_INSTALL_SETUP_RESULT_INVALID");
+  const target = input.target ?? null;
+  const requestedScope = input.requested_scope ?? null;
+  const effectiveScope = input.effective_scope ?? null;
+  const invocationDirectorySource = input.invocation_directory_source ?? "none";
+  const control = assertControlMigration(input.control ?? uncheckedControl());
+  if (!SETUP_REQUESTS.has(input.setup_request) || !SURFACES.has(input.surface)
+      || !(target === null || (typeof target === "string" && isAbsolute(target)))
+      || !TARGET_SOURCES.has(input.target_source)
+      || !INVOCATION_DIRECTORY_SOURCES.has(invocationDirectorySource)
+      || !(requestedScope === null || SCOPES.has(requestedScope))
+      || !(effectiveScope === null || SCOPES.has(effectiveScope))
+      || !plainObject(input.runtime_checks) || !RUNTIME_CHECK_STATES.has(runtimeCheckState(input.runtime_checks))
+      || !plainObject(input.discovery)
+      || !["not_checked", "pending_restart", "discovered"].includes(input.discovery.status)
+      || !plainObject(input.restart) || typeof input.restart.required !== "boolean"
+      || !stringArray(input.restart.reasons) || input.authorizes !== false
+      || ((input.target_source === "none") !== (target === null))
+      || (input.target_source === "explicit_dir" && invocationDirectorySource !== "explicit_dir")
+      || (input.target_source === "interactive_invocation_cwd_selection"
+        && !["npm_init_cwd", "process_cwd"].includes(invocationDirectorySource))
+      || (input.target_source === "none" && invocationDirectorySource !== "none")) {
+    throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+  }
+  assertPluginPart(input.plugin, input.setup_request);
+  assertMcpPart(input.mcp);
+  assertFailure(input.failure ?? null);
+  assertCodedAction(input.next_action);
+  const effectiveState = deriveInstallSetupState(input);
+  const result = resultForState(effectiveState);
+  const cancelledShapeInvalid = effectiveState === "cancelled"
+    && (target !== null || input.target_source !== "none" || requestedScope !== null || effectiveScope !== null
+      || input.plugin?.status !== "not_run" || mcpState(input.mcp) !== "not_requested"
+      || input.discovery.status !== "not_checked" || input.restart.required || input.failure !== null);
+  const fullBindingInvalid = effectiveState !== "cancelled" && input.setup_request === "full"
+    && (target === null || input.target_source === "none" || requestedScope === null);
+  const pluginOnlyBindingInvalid = effectiveState !== "cancelled" && input.setup_request === "plugin_only"
+    && (target !== null || input.target_source !== "none" || requestedScope !== null || effectiveScope !== null);
+  if ((input.effective_state && input.effective_state !== effectiveState)
+      || (input.result && input.result !== result) || !EFFECTIVE_STATES.has(effectiveState) || !RESULTS.has(result)
+      || cancelledShapeInvalid || fullBindingInvalid || pluginOnlyBindingInvalid
+      || !INSTALL_SETUP_STATES[effectiveState]?.actions.includes(input.next_action.code)
+      || (effectiveState.startsWith("mcp_ready_hook_") && input.next_action.code !== codexPendingHookAction(input.runtime_checks))
+      || (effectiveState === "discovered_ready" && input.discovery.status !== "discovered")
+      || (result === "failed" && !input.failure)
+      || (result !== "failed" && input.failure && effectiveState !== "partial")) {
+    throw new Error("AGDF_INSTALL_SETUP_RESULT_INVALID");
+  }
+  return cloneAndFreeze({
+    schema_version: 1,
+    contract_version: 1,
+    operation: "install_setup",
+    result,
+    setup_request: input.setup_request,
+    effective_state: effectiveState,
+    surface: input.surface,
+    target,
+    target_source: input.target_source,
+    invocation_directory_source: invocationDirectorySource,
+    requested_scope: requestedScope,
+    effective_scope: effectiveScope,
+    plugin: input.plugin,
+    runtime_checks: input.runtime_checks,
+    mcp: input.mcp,
+    discovery: input.discovery,
+    restart: input.restart,
+    failure: input.failure ?? null,
+    next_action: input.next_action,
+    control,
+    authorizes: false,
+  });
+}
+
+export const installSetupContract = Object.freeze({
+  surfaces: Object.freeze([...SURFACES]),
+  setupRequests: Object.freeze([...SETUP_REQUESTS]),
+  effectiveStates: Object.freeze([...EFFECTIVE_STATES]),
+  resultStates: Object.freeze([...RESULTS]),
+  targetSources: Object.freeze([...TARGET_SOURCES]),
+  preflightTargetSources: Object.freeze([...PREFLIGHT_TARGET_SOURCES]),
+  invocationDirectorySources: Object.freeze([...INVOCATION_DIRECTORY_SOURCES]),
+  failurePhases: Object.freeze([...FAILURE_PHASES]),
+  failureCodes: Object.freeze([...FAILURE_CODES]),
+  nextActionCodes: Object.freeze([...NEXT_ACTION_CODES]),
+  runtimeCheckStates: Object.freeze([...RUNTIME_CHECK_STATES]),
+});

package/lib/install-setup/control-migration.js

@@ -0,0 +1,10 @@
+export { CONTROL_MIGRATION_STATUSES, uncheckedControl, inspectControlMigration, assertControlMigration } from "#agdf-core/control-maintenance/compatibility.js";
+export { migrateInstallationControl } from "#agdf-core/control-maintenance/migration.js";
+
+export function installationControlTarget(options) {
+  if (options.controlDir) return { root: options.controlDir, writable: true };
+  if (options.dirExplicit && (options.target !== "opencode" || options.setupRequest === "full")) {
+    return { root: options.dir, writable: true };
+  }
+  return { root: options.workingDirectory ?? null, writable: false };
+}

package/lib/install-setup/control-repair.js

@@ -0,0 +1 @@
+export { inspectControlRepair, repairInstallationControl } from "../control-maintenance/repair.js";

package/lib/install-setup/interaction.js

@@ -0,0 +1,157 @@
+export { selectControlMigration, promptControlMigration, selectControlRepair, promptControlRepair } from "../control-maintenance/interaction.js";
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+import { interactionLocales } from "../cli/runtime-context.js";
+import { localePack } from "#agdf-core/interaction-presentation.js";
+import {
+  installSetupChoiceOptions,
+  installSetupScopeOptions,
+  renderInstallSetupPreflight,
+  renderInstallSetupScopePreflight,
+} from "./presentation.js";
+
+const CHOICES = Object.freeze({
+  "1": "full",
+  f: "full",
+  full: "full",
+  "2": "plugin_only",
+  p: "plugin_only",
+  plugin_only: "plugin_only",
+  "plugin-only": "plugin_only",
+  "3": "cancel",
+  c: "cancel",
+  cancel: "cancel",
+});
+
+const SCOPE_CHOICES = Object.freeze({
+  "1": "project",
+  p: "project",
+  project: "project",
+  "2": "user",
+  u: "user",
+  user: "user",
+  "3": "back",
+  b: "back",
+  back: "back",
+});
+
+export function normalizeInstallSetupChoice(value) {
+  if (typeof value !== "string") return value === null || value === undefined ? "eof" : "invalid";
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return "empty";
+  return CHOICES[normalized] ?? "invalid";
+}
+
+export function normalizeInstallScopeChoice(value) {
+  if (typeof value !== "string") return value === null || value === undefined ? "eof" : "invalid";
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return "empty";
+  return SCOPE_CHOICES[normalized] ?? "invalid";
+}
+
+export async function selectInstallSetup(preflight, {
+  readChoice,
+  write = () => {},
+  registry = interactionLocales,
+  language = "en",
+  present = true,
+} = {}) {
+  if (typeof readChoice !== "function") throw new Error("AGDF_INSTALL_SETUP_INTERACTION_READER_REQUIRED");
+  const pack = localePack(registry, language).installSetup;
+  const options = installSetupChoiceOptions(preflight, { registry, language });
+  if (present) write(renderInstallSetupPreflight(preflight, { registry, language }));
+  while (true) {
+    let raw;
+    try {
+      raw = await readChoice(Object.freeze({ options, default: null, prompt: pack.choicePrompt }));
+    } catch {
+      return "cancel";
+    }
+    const decision = normalizeInstallSetupChoice(raw);
+    if (decision === "eof") return "cancel";
+    if (decision === "empty") {
+      write(pack.emptyChoice);
+      continue;
+    }
+    if (decision === "invalid") {
+      write(pack.invalidChoice);
+      continue;
+    }
+    if (decision === "full" && !preflight.full_available) {
+      const option = options.find(({ value }) => value === "full");
+      write(pack.blockedChoice.replaceAll("{reason}", option.blocked_reason));
+      continue;
+    }
+    return decision;
+  }
+}
+
+export async function selectInstallScope(preflight, {
+  readChoice,
+  write = () => {},
+  registry = interactionLocales,
+  language = "en",
+  present = true,
+} = {}) {
+  if (typeof readChoice !== "function") throw new Error("AGDF_INSTALL_SETUP_SCOPE_READER_REQUIRED");
+  const pack = localePack(registry, language).installSetup;
+  const options = installSetupScopeOptions(preflight, { registry, language });
+  if (present) write(renderInstallSetupScopePreflight(preflight, { registry, language }));
+  while (true) {
+    let raw;
+    try {
+      raw = await readChoice(Object.freeze({ options, default: null, prompt: pack.scopeChoicePrompt }));
+    } catch {
+      return "cancel";
+    }
+    const decision = normalizeInstallScopeChoice(raw);
+    if (decision === "eof") return "cancel";
+    if (decision === "empty") { write(pack.emptyScopeChoice); continue; }
+    if (decision === "invalid") { write(pack.invalidScopeChoice); continue; }
+    if (decision === "back") return decision;
+    const option = options.find(({ value }) => value === decision);
+    if (!option?.enabled) {
+      write(pack.blockedScopeChoice.replaceAll("{reason}", option?.blocked_reason ?? "unknown"));
+      continue;
+    }
+    return decision;
+  }
+}
+
+export async function promptInstallSetup(preflight, {
+  input = process.stdin,
+  output = process.stdout,
+  registry = interactionLocales,
+  language = "en",
+} = {}) {
+  const prompt = createInterface({ input, output });
+  try {
+    return await selectInstallSetup(preflight, {
+      registry,
+      language,
+      write(value) { output.write(`${value}\n`); },
+      readChoice({ prompt: question }) { return prompt.question(question); },
+    });
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function promptInstallScope(preflight, {
+  input = process.stdin,
+  output = process.stdout,
+  registry = interactionLocales,
+  language = "en",
+} = {}) {
+  const prompt = createInterface({ input, output });
+  try {
+    return await selectInstallScope(preflight, {
+      registry,
+      language,
+      write(value) { output.write(`${value}\n`); },
+      readChoice({ prompt: question }) { return prompt.question(question); },
+    });
+  } finally {
+    prompt.close();
+  }
+}