create-agdf 0.14.5 → 0.20.0

package/lib/install-setup/service.js

@@ -0,0 +1,441 @@
+import process from "node:process";
+import { defaultOpenCodeConfigDir } from "../installers/opencode.js";
+import { inspectGlobalInstallationStatus } from "../lifecycle/status.js";
+import { runMcpLifecycle } from "../mcp-lifecycle/service.js";
+import { pluginDefinition } from "../cli/runtime-context.js";
+import { codexHookReviewPending, codexPendingHookAction, createInstallSetupPreflight, createInstallSetupResult } from "./contract.js";
+import { inspectControlMigration, installationControlTarget, migrateInstallationControl } from "./control-migration.js";
+import { repairInstallationControl } from "./control-repair.js";
+
+const SURFACES = new Set(["codex", "claude", "copilot", "opencode"]);
+const SCOPE_DECISIONS = new Set(["project", "user", "back", "cancel"]);
+const MCP_CONFLICTS = new Map([
+  ["foreign", "mcp_foreign"],
+  ["precedence_conflict", "mcp_precedence_conflict"],
+  ["invalid", "mcp_invalid"],
+]);
+const PREFLIGHT_MCP_REPORTS = new WeakMap();
+
+function installationTarget(options, { interactive, cwd }) {
+  if (options.setupRequest === "full" && options.dirExplicit) {
+    return { target: options.dir, source: "explicit_dir" };
+  }
+  if (interactive && options.setupRequest !== "plugin_only") {
+    return { target: cwd, source: "interactive_invocation_cwd_proposal" };
+  }
+  return { target: null, source: "none" };
+}
+
+export function resolveInstallSetupPaths(options, {
+  interactive = false,
+  cwd = options.workingDirectory ?? process.cwd(),
+  env = process.env,
+} = {}) {
+  const effectiveInteractive = Boolean(interactive && !options.json);
+  const { target, source } = installationTarget(options, { interactive: effectiveInteractive, cwd });
+  const invocationDirectorySource = source === "explicit_dir"
+    ? "explicit_dir"
+    : source === "interactive_invocation_cwd_proposal"
+      ? options.workingDirectorySource ?? "process_cwd"
+      : "none";
+  const pluginConfiguration = options.target === "opencode"
+    ? options.setupRequest === "full"
+      ? env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir()
+      : options.dirExplicit ? options.dir : env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir()
+    : null;
+  return Object.freeze({
+    target,
+    target_source: source,
+    invocation_directory_source: invocationDirectorySource,
+    plugin_configuration: pluginConfiguration,
+    interactive: effectiveInteractive,
+  });
+}
+
+function preflightMcpState(report, { surface, target, scope }) {
+  const blockReason = fullBlockReason(report, target);
+  return Object.freeze({
+    status: report.result,
+    capability: report.capability,
+    selected_status: report.registration?.selected_status ?? report.registration?.status ?? "invalid",
+    effective_source: report.registration?.effective_source ?? "none",
+    registration_path: report.registration?.path ?? null,
+    available: blockReason === "none",
+    block_reason: blockReason,
+    removal_command: removalCommand(surface, target, scope),
+  });
+}
+
+function fullBlockReason(mcp, target) {
+  if (!target) return "target_required";
+  if (mcp.result === "failed" || mcp.status === "failed") return "mcp_preflight_failed";
+  const conflict = MCP_CONFLICTS.get(mcp.registration?.status ?? mcp.registration_status);
+  if (conflict) return conflict;
+  return "none";
+}
+
+function removalCommand(surface, target, scope) {
+  const base = `npx --yes @agdf/cli@latest uninstall --surface ${surface} --scope global`;
+  if (!target) return base;
+  const hasControlCharacter = /[\u0000-\u001f\u007f]/u.test(target);
+  let displayedTarget = "ABSOLUTE_TARGET_SHOWN_ABOVE";
+  if (!hasControlCharacter && process.platform === "win32"
+      && /^(?:[A-Za-z]:[\\/])[A-Za-z0-9 ._\\/:-]+$/u.test(target)) {
+    displayedTarget = '"' + target + '"';
+  } else if (!hasControlCharacter && process.platform !== "win32") {
+    displayedTarget = "'" + target.replaceAll("'", "'\"'\"'") + "'";
+  }
+  return `${base} --with-mcp --mcp-scope ${scope} --dir ${displayedTarget}`;
+}
+
+export function inspectInstallSetup({ options, interactive = false, env = process.env } = {}, {
+  inspectPlugin = inspectGlobalInstallationStatus,
+  mcpLifecycle = runMcpLifecycle,
+  exec,
+} = {}) {
+  if (!SURFACES.has(options?.target)) throw new Error("AGDF_INSTALL_SETUP_INPUT_INVALID");
+  const paths = resolveInstallSetupPaths(options, { interactive, env });
+  const requestedScope = options.setupRequest === "full"
+    ? options.scope ?? (paths.interactive ? null : "project")
+    : null;
+  let plugin;
+  try {
+    const observation = inspectPlugin({
+      surface: options.target,
+      configDir: paths.plugin_configuration ?? undefined,
+      dataRoot: env.AGDF_DATA_DIR,
+    }, { exec });
+    plugin = {
+      status: observation.status ?? "unknown",
+      evidence: [...(observation.evidence ?? [])].map(String),
+      observation,
+    };
+  } catch (error) {
+    plugin = { status: "unavailable", evidence: [String(error?.message || error)] };
+  }
+  const reports = {};
+  const mcpByScope = {};
+  for (const scope of ["project", "user"]) {
+    if (!paths.target) {
+      mcpByScope[scope] = {
+        status: "not_checked",
+        capability: "unverified",
+        selected_status: "absent",
+        effective_source: "none",
+        registration_path: null,
+        available: false,
+        block_reason: "target_required",
+        removal_command: removalCommand(options.target, paths.target, scope),
+      };
+      continue;
+    }
+    try {
+      const report = mcpLifecycle({ action: "status", surface: options.target, scope, target: paths.target, env, exec });
+      reports[scope] = report;
+      mcpByScope[scope] = preflightMcpState(report, { surface: options.target, target: paths.target, scope });
+    } catch (error) {
+      reports[scope] = null;
+      mcpByScope[scope] = {
+        status: "failed",
+        capability: "unverified",
+        selected_status: "invalid",
+        effective_source: "unknown",
+        registration_path: null,
+        available: false,
+        block_reason: "mcp_preflight_failed",
+        removal_command: removalCommand(options.target, paths.target, scope),
+      };
+    }
+  }
+  const availableScopes = ["project", "user"].filter((scope) => mcpByScope[scope].available);
+  const fullAvailable = requestedScope ? mcpByScope[requestedScope].available : availableScopes.length > 0;
+  const blockReason = fullAvailable ? "none"
+    : requestedScope ? mcpByScope[requestedScope].block_reason
+      : mcpByScope.project.block_reason;
+  const packageRequired = ["project", "user"].some((scope) => reports[scope]?.runtime?.package_status !== "matched");
+  const preflight = createInstallSetupPreflight({
+    surface: options.target,
+    version: pluginDefinition.version,
+    interaction: paths.interactive && !options.setupRequest ? "required" : "not_required",
+    plugin,
+    mcp_by_scope: mcpByScope,
+    target: paths.target,
+    target_source: paths.target_source,
+    invocation_directory_source: paths.invocation_directory_source,
+    requested_scope: requestedScope,
+    effective_scope: requestedScope ? reports[requestedScope]?.effective_scope ?? null : null,
+    plugin_configuration: paths.plugin_configuration,
+    local_execution: true,
+    package_acquisition_required: packageRequired,
+    removal_overview: `npx --yes @agdf/cli@latest uninstall --surface ${options.target} --scope global`,
+    full_available: fullAvailable,
+    full_block_reason: blockReason,
+    control: inspectControlMigration(installationControlTarget(options).root),
+    authorizes: false,
+  });
+  PREFLIGHT_MCP_REPORTS.set(preflight, Object.freeze({ ...reports }));
+  return preflight;
+}
+
+function cancelledResult({ surface, selection, preflight, runtimeChecks = { status: "not_run" } }) {
+  return createInstallSetupResult({
+    setup_request: selection,
+    surface,
+    target: null,
+    target_source: "none",
+    invocation_directory_source: "none",
+    requested_scope: null,
+    effective_scope: null,
+    plugin: { status: "not_run" },
+    runtime_checks: runtimeChecks,
+    mcp: { status: "not_requested" },
+    discovery: { status: "not_checked" },
+    restart: { required: false, reasons: [] },
+    failure: null,
+    next_action: { code: "cancelled", parameters: {}, text: null },
+    authorizes: false,
+  });
+}
+
+function failedBeforeMutation({ surface, selection, selectedScope, preflight, message }) {
+  const scopeState = selectedScope ? preflight.mcp_by_scope[selectedScope] : null;
+  const blockReason = scopeState?.block_reason ?? preflight.full_block_reason;
+  const mcpPreflightFailed = blockReason === "mcp_preflight_failed";
+  return createInstallSetupResult({
+    setup_request: selection,
+    surface,
+    target: preflight.target,
+    target_source: preflight.target_source === "interactive_invocation_cwd_proposal" ? "interactive_invocation_cwd_selection" : preflight.target_source,
+    invocation_directory_source: preflight.invocation_directory_source,
+    requested_scope: selectedScope,
+    effective_scope: null,
+    plugin: { status: "not_run" },
+    runtime_checks: { status: "not_run" },
+    mcp: PREFLIGHT_MCP_REPORTS.get(preflight)?.[selectedScope] ?? { status: "not_checked" },
+    discovery: { status: "not_checked" },
+    restart: { required: false, reasons: [] },
+    failure: {
+      phase: mcpPreflightFailed ? "mcp_preflight" : "setup_preflight",
+      code: mcpPreflightFailed ? "mcp_preflight_failed" : "setup_selection_blocked",
+      message,
+      evidence: [blockReason],
+    },
+    next_action: { code: blockReason === "target_required" ? "choose_plugin_only_or_cancel" : "resolve_mcp_registration", parameters: {}, text: null },
+    authorizes: false,
+  });
+}
+
+function pluginHealthy(report) {
+  return report?.result !== "failed"
+    && ["healthy", "configured", "configured_pending_restart"].includes(report?.verification?.status);
+}
+
+function pluginFailureReport(createPluginFailure, error) {
+  if (typeof createPluginFailure !== "function") throw error;
+  return createPluginFailure(error);
+}
+
+function failureEvidence(value) {
+  if (Array.isArray(value?.diagnostics) && value.diagnostics.length) return value.diagnostics.map((item) => item.code);
+  return value?.failure?.message ? [value.failure.message] : [];
+}
+
+function pluginFailurePhase(report) {
+  if (report?.failure?.phase === "verification") return "plugin_verification";
+  if (!report?.failure && !["healthy", "configured", "configured_pending_restart"].includes(report?.verification?.status)) {
+    return "plugin_verification";
+  }
+  return "plugin_operation";
+}
+
+function completedResult({ selection, selectedScope, preflight, pluginReport, runtimeChecks, mcpReport, control }) {
+  const full = selection === "full";
+  const reports = PREFLIGHT_MCP_REPORTS.get(preflight) ?? {};
+  // Plugin-managed hosts include the MCP server in plugin-only setup.
+  const mcp = full ? mcpReport ?? { status: "not_requested" }
+    : ["claude", "codex", "copilot"].includes(preflight.surface) ? { status: "plugin_managed" } : reports.project ?? { status: "not_checked" };
+  let failure = null;
+  let nextAction = "restart_host";
+  if (!pluginHealthy(pluginReport)) {
+    const phase = pluginFailurePhase(pluginReport);
+    failure = {
+      phase,
+      code: phase === "plugin_verification" ? "plugin_verification_failed" : "plugin_operation_failed",
+      message: pluginReport?.failure?.message || "The plugin operation was not verified.",
+      evidence: [...(pluginReport?.verification?.evidence ?? [])].map(String),
+    };
+    nextAction = "retry_plugin";
+  } else if (runtimeChecks?.failure) {
+    failure = {
+      phase: "runtime_check_permission",
+      code: "runtime_check_permission_failed",
+      message: runtimeChecks.failure.message || "The automatic-check choice could not be finalized.",
+      evidence: [runtimeChecks.failure.phase || "runtime_check_permission"],
+    };
+    nextAction = "review_runtime_checks";
+  } else if (full && ["failed", "degraded", "not_configured", "disabled"].includes(mcpReport?.result)) {
+    failure = {
+      phase: "mcp_enable",
+      code: "mcp_enable_failed",
+      message: "The plugin is installed, but MCP enable did not reach a configured state.",
+      evidence: failureEvidence(mcpReport),
+    };
+    nextAction = "retry_mcp";
+  } else if (!full && ["degraded", "failed"].includes(mcp?.result)) {
+    nextAction = "resolve_mcp_registration";
+  } else if (full && ["configured_unverified", "unchanged"].includes(mcpReport?.result)) {
+    nextAction = "verify_host_discovery";
+  } else if (!full && mcp.status === "plugin_managed" && codexHookReviewPending(preflight.surface, runtimeChecks?.state ?? runtimeChecks)) {
+    nextAction = codexPendingHookAction(runtimeChecks?.state ?? runtimeChecks);
+  }
+  const target = full ? preflight.target : null;
+  if (!failure && control?.status === "migration_required") nextAction = "migrate_control";
+  if (!failure && control?.status === "repair_required") nextAction = "repair_control";
+  const targetSource = full
+    ? preflight.target_source === "interactive_invocation_cwd_proposal" ? "interactive_invocation_cwd_selection" : preflight.target_source
+    : "none";
+  const mcpDiscovery = full && mcpReport?.discovery?.status === "pending_restart" ? "pending_restart" : "not_checked";
+  const reasons = ["plugin_reload", ...(full && ["configured_pending_restart", "configured_unverified", "unchanged"].includes(mcpReport?.result)
+    ? ["mcp_discovery"] : [])];
+  return createInstallSetupResult({
+    setup_request: selection,
+    surface: preflight.surface,
+    target,
+    target_source: targetSource,
+    invocation_directory_source: full ? preflight.invocation_directory_source : "none",
+    requested_scope: full ? selectedScope : null,
+    effective_scope: full ? mcpReport?.effective_scope ?? null : null,
+    plugin: pluginReport,
+    runtime_checks: runtimeChecks?.state ?? runtimeChecks ?? { status: "not_checked" },
+    mcp,
+    discovery: { status: mcpDiscovery },
+    restart: { required: pluginHealthy(pluginReport), reasons: pluginHealthy(pluginReport) ? reasons : [] },
+    failure,
+    next_action: { code: nextAction, parameters: {}, text: null },
+    control,
+    authorizes: false,
+  });
+}
+
+export async function runInstallSetup({ options, interactive = false, env = process.env } = {}, {
+  inspectPlugin,
+  mcpLifecycle = runMcpLifecycle,
+  exec,
+  chooseSetup,
+  chooseScope,
+  prepareRuntimeChecks,
+  installPlugin,
+  createPluginFailure,
+  finalizeRuntimeChecks,
+  confirmControlMigration,
+  chooseControlRepair,
+  confirmControlRepair,
+} = {}) {
+  if (!SURFACES.has(options?.target) || typeof installPlugin !== "function") {
+    throw new Error("AGDF_INSTALL_SETUP_INPUT_INVALID");
+  }
+  const effectiveInteractive = Boolean(interactive && !options.json);
+  // These runtime plugins declare their own MCP server, so plugin-only is the complete setup.
+  if (["claude", "codex", "copilot"].includes(options.target)) {
+    if (options.setupRequest === "full") {
+      const host = options.target === "claude" ? "Claude Code"
+        : options.target === "codex" ? "Codex" : "GitHub Copilot";
+      throw new Error(`${host} starts the AGDF MCP server from the AGDF plugin; omit --with-mcp.`);
+    }
+    options = { ...options, setupRequest: options.setupRequest ?? "plugin_only" };
+  }
+  if (options.setupRequest === "full" && !effectiveInteractive
+      && (!options.dirExplicit || !options.dirInputAbsolute)) {
+    throw new Error("Non-interactive --with-mcp requires an explicit absolute --dir target.");
+  }
+  const preflight = inspectInstallSetup({ options, interactive: effectiveInteractive, env }, { inspectPlugin, mcpLifecycle, exec });
+  let selection = options.setupRequest;
+  let selectedScope = preflight.requested_scope;
+  while (!selection || (selection === "full" && !selectedScope)) {
+    if (!selection) {
+      selection = effectiveInteractive && typeof chooseSetup === "function" ? await chooseSetup(preflight) : "plugin_only";
+    }
+    if (selection === "full" && !selectedScope) {
+      const scopeDecision = effectiveInteractive && typeof chooseScope === "function"
+        ? await chooseScope(preflight)
+        : "cancel";
+      if (!SCOPE_DECISIONS.has(scopeDecision)) throw new Error("AGDF_INSTALL_SETUP_SCOPE_SELECTION_INVALID");
+      if (scopeDecision === "back") { selection = null; continue; }
+      if (scopeDecision === "cancel") selection = "cancel";
+      else selectedScope = scopeDecision;
+    }
+  }
+  if (!new Set(["full", "plugin_only", "cancel"]).has(selection)) throw new Error("AGDF_INSTALL_SETUP_SELECTION_INVALID");
+  if (selection === "cancel") return Object.freeze({ report: cancelledResult({ surface: options.target, selection, preflight }), preflight, plugin_payload: null });
+  if (selection === "full" && !preflight.mcp_by_scope[selectedScope]?.available) {
+    return Object.freeze({
+      report: failedBeforeMutation({ surface: options.target, selection, selectedScope, preflight,
+        message: `Complete setup is unavailable: ${preflight.mcp_by_scope[selectedScope]?.block_reason ?? preflight.full_block_reason}` }),
+      preflight,
+      plugin_payload: null,
+    });
+  }
+  const consent = typeof prepareRuntimeChecks === "function"
+    ? await prepareRuntimeChecks(options.target, options)
+    : { decision: "manual", state: { requested: "manual", effective: "manual" } };
+  if (consent?.decision === "cancel") {
+    return Object.freeze({
+      report: cancelledResult({
+        surface: options.target,
+        selection,
+        preflight,
+        runtimeChecks: { ...(consent.state ?? {}), effective: "cancelled" },
+      }),
+      preflight,
+      plugin_payload: null,
+    });
+  }
+  let pluginPayload;
+  let pluginReport;
+  try {
+    pluginPayload = await installPlugin({
+      surface: options.target,
+      options,
+      plugin_configuration: preflight.plugin_configuration,
+      consent,
+    });
+    pluginReport = pluginPayload?.report ?? pluginPayload;
+  } catch (error) {
+    pluginReport = pluginFailureReport(createPluginFailure, error);
+  }
+  let runtimeChecks = { state: consent?.state ?? { requested: "manual", effective: "manual" }, failure: null };
+  if (pluginHealthy(pluginReport) && typeof finalizeRuntimeChecks === "function") {
+    try {
+      runtimeChecks = await finalizeRuntimeChecks(consent, pluginPayload);
+    } catch (error) {
+      runtimeChecks = {
+        state: consent?.state ?? { requested: consent?.decision ?? "manual", effective: "unknown" },
+        failure: { phase: "runtime_check_permission", message: String(error?.message || error) },
+      };
+    }
+  }
+  let mcpReport = null;
+  if (selection === "full" && pluginHealthy(pluginReport)) {
+    mcpReport = mcpLifecycle({
+      action: "enable",
+      surface: options.target,
+      scope: selectedScope,
+      target: preflight.target,
+      env,
+      exec,
+    });
+  }
+  const controlTarget = installationControlTarget(options);
+  const batchConfirmation = effectiveInteractive ? confirmControlMigration : undefined;
+  let control = pluginHealthy(pluginReport)
+    ? await migrateInstallationControl(controlTarget.root, {
+      mode: options.controlMigration === "inspect" || (!controlTarget.writable && !batchConfirmation) ? "inspect" : "safe",
+      confirmMigration: batchConfirmation,
+    })
+    : preflight.control;
+  if (pluginHealthy(pluginReport) && effectiveInteractive && options.controlMigration !== "inspect") {
+    control = await repairInstallationControl(control, { chooseRepair: chooseControlRepair, confirmRepair: confirmControlRepair });
+  }
+  const report = completedResult({ selection, selectedScope, preflight, pluginReport, runtimeChecks, mcpReport, control });
+  return Object.freeze({ report, preflight, plugin_payload: pluginPayload ?? null });
+}

package/lib/installers/copilot-marketplace-transport.js

@@ -0,0 +1,74 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import process from "node:process";
+
+export const COPILOT_TRANSPORT_REVISION = 1;
+
+export function copilotMarketplaceSpec(root, sourceDigest) {
+  if (!/^[a-f0-9]{64}$/.test(sourceDigest)) throw new Error("Invalid Copilot marketplace source digest.");
+  return `${pathToFileURL(resolve(root)).href}#agdf-${sourceDigest}`;
+}
+
+export function copilotMarketplaceSource(root, sourceDigest) {
+  copilotMarketplaceSpec(root, sourceDigest);
+  return { source: "git", url: pathToFileURL(resolve(root)).href, ref: `agdf-${sourceDigest}` };
+}
+
+function git(root, args, { exec = execFileSync } = {}) {
+  return String(exec("git", [
+    "--git-dir", join(root, ".git"), "--work-tree", root,
+    "-c", "core.autocrlf=false", "-c", "core.fsmonitor=false",
+    // Staged repositories are renamed or deleted immediately; no detached Git writer may outlive the transaction.
+    "-c", "maintenance.auto=false", "-c", "gc.auto=0",
+    "-c", `core.hooksPath=${join(root, ".git", "agdf-no-hooks")}`, "-c", "commit.gpgsign=false", ...args,
+  ], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000,
+    env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+      GIT_AUTHOR_NAME: "AGDF package builder", GIT_AUTHOR_EMAIL: "package@agdf.invalid",
+      GIT_COMMITTER_NAME: "AGDF package builder", GIT_COMMITTER_EMAIL: "package@agdf.invalid",
+      GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z" },
+  }));
+}
+
+function files(root, relative = "") {
+  return readdirSync(join(root, relative), { withFileTypes: true }).flatMap((entry) => {
+    if (!relative && entry.name === ".git") return [];
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Symlink in Copilot marketplace transport: ${path}`);
+    return entry.isDirectory() ? files(root, path) : [path];
+  }).sort();
+}
+
+export function verifyCopilotMarketplaceTransport(root, sourceDigest, adapters = {}) {
+  if (!lstatSync(join(root, ".git")).isDirectory()) throw new Error("Copilot marketplace Git metadata is missing or not owned.");
+  const branch = `agdf-${sourceDigest}`;
+  if (git(root, ["symbolic-ref", "--short", "HEAD"], adapters).trim() !== branch) {
+    throw new Error("Copilot marketplace Git branch does not match its source digest.");
+  }
+  const entries = git(root, ["ls-tree", "-r", "-z", "HEAD"], adapters).split("\0").filter(Boolean);
+  const tracked = new Map(entries.map((entry) => {
+    const match = /^(100644|100755) blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
+    if (!match) throw new Error("Unexpected Copilot marketplace Git tree entry.");
+    return [match[3], match[2]];
+  }));
+  const paths = files(root);
+  if (tracked.size !== paths.length) throw new Error("Copilot marketplace Git tree is incomplete.");
+  for (const path of paths) {
+    const content = readFileSync(join(root, path));
+    const hash = createHash("sha1").update(`blob ${content.length}\0`).update(content).digest("hex");
+    if (tracked.get(path) !== hash) throw new Error(`Copilot marketplace Git content mismatch: ${path}`);
+  }
+  return copilotMarketplaceSpec(root, sourceDigest);
+}
+
+export function buildCopilotMarketplaceTransport(root, sourceDigest, adapters = {}) {
+  // The canonical staged marketplace is the Git source. No second package tree
+  // or host-cache patch is needed; a new payload gets a new native Git ref.
+  writeFileSync(join(root, ".gitattributes"), "* -text\n");
+  git(root, ["init", "--quiet", "--template=", "--object-format=sha1", `--initial-branch=agdf-${sourceDigest}`], adapters);
+  git(root, ["add", "--force", "--all"], adapters);
+  git(root, ["commit", "--quiet", "--no-verify", "-m", "AGDF Copilot package"], adapters);
+  return verifyCopilotMarketplaceTransport(root, sourceDigest, adapters);
+}

package/lib/installers/copilot-settings.js

@@ -3,11 +3,13 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writ
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import process from "node:process";
-import { renameSyncWithRetry } from "../fs-swap.js";
+import { renameSyncWithRetry } from "#agdf-core/fs-swap.js";
+import { copilotMarketplaceSource } from "./copilot-marketplace-transport.js";
 
 const COPILOT_PLUGIN_SELECTOR = "agdf@agdf";
-const COPILOT_LOCAL_SETTINGS = join(".github", "copilot", "settings.local.json");
-const COPILOT_SHARED_SETTINGS = join(".github", "copilot", "settings.json");
+// Repository-relative Git paths: used as pathspecs and in .gitignore guidance, so always forward slashes.
+const COPILOT_LOCAL_SETTINGS = ".github/copilot/settings.local.json";
+const COPILOT_SHARED_SETTINGS = ".github/copilot/settings.json";
 
 export function defaultCopilotSettingsPath({ env = process.env, home = homedir() } = {}) {
   return join(resolve(env.COPILOT_HOME || join(home, ".copilot")), "settings.json");
@@ -25,6 +27,10 @@ export function readCopilotSettings(path = defaultCopilotSettingsPath()) {
         && (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object" || Array.isArray(settings.enabledPlugins))) {
       throw new Error("enabledPlugins must be an object");
     }
+    if (settings.extraKnownMarketplaces !== undefined
+        && (!settings.extraKnownMarketplaces || typeof settings.extraKnownMarketplaces !== "object" || Array.isArray(settings.extraKnownMarketplaces))) {
+      throw new Error("extraKnownMarketplaces must be an object");
+    }
     return { exists: true, settings, content };
   } catch (error) {
     throw new Error(`AGDF_COPILOT_SETTINGS_INVALID: ${error.message}`);
@@ -61,6 +67,31 @@ export function atomicSettingsWrite(path, settings, dependencies = {}) {
   atomicContentWrite(path, `${JSON.stringify(settings, null, 2)}\n`, dependencies);
 }
 
+export function configureCopilotMarketplace({ path = defaultCopilotSettingsPath(), root, sourceDigest }) {
+  const before = readCopilotSettings(path);
+  const next = structuredClone(before.settings);
+  const entry = { ...(next.extraKnownMarketplaces?.agdf ?? {}), source: copilotMarketplaceSource(root, sourceDigest) };
+  next.extraKnownMarketplaces = { ...(next.extraKnownMarketplaces ?? {}), agdf: entry };
+  if (JSON.stringify(before.settings.extraKnownMarketplaces?.agdf) !== JSON.stringify(entry)) atomicSettingsWrite(path, next);
+  return { path, source: entry.source };
+}
+
+export function restoreCopilotMarketplaceSettings(path, before) {
+  // Native install/uninstall can also change enablement. Restore only AGDF's
+  // entries, preserving any concurrent changes to unrelated user preferences.
+  const current = readCopilotSettings(path);
+  const next = structuredClone(current.settings);
+  for (const [key, entry] of [["extraKnownMarketplaces", "agdf"], ["enabledPlugins", COPILOT_PLUGIN_SELECTOR]]) {
+    next[key] = { ...(next[key] ?? {}) };
+    if (Object.hasOwn(before.settings[key] ?? {}, entry)) next[key][entry] = before.settings[key][entry];
+    else delete next[key][entry];
+    if (Object.keys(next[key]).length === 0) delete next[key];
+  }
+  if (!before.exists && Object.keys(next).length === 0) {
+    if (current.exists) rmSync(path);
+  } else atomicSettingsWrite(path, next);
+}
+
 export function repositoryCopilotSettingsPath(targetDir, { shared = false } = {}) {
   const root = resolve(targetDir);
   if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) {

package/lib/installers/copilot-skill-discovery.js

@@ -0,0 +1,27 @@
+import { basename, dirname, isAbsolute } from "node:path";
+import { digestNormalizedPluginSource } from "#agdf-core/runtime/plugin-provenance.js";
+
+export function verifyCopilotSkillDiscovery(output, { definition, sourceDigest }) {
+  let skills;
+  try { skills = JSON.parse(output); } catch { throw new Error("Copilot skill discovery returned invalid JSON."); }
+  if (!Array.isArray(skills)) throw new Error("Copilot skill discovery did not return a skill list.");
+  const expected = definition.skillSet.map(({ slug }) => `${definition.copilot.skillPrefix}${slug}`);
+  const roots = new Set();
+  for (const name of expected) {
+    const matches = skills.filter((skill) => skill?.name === name);
+    if (matches.length !== 1 || matches[0].source !== "plugin" || matches[0].enabled !== true) {
+      throw new Error(`Copilot plugin skill is missing, disabled or shadowed: ${name}`);
+    }
+    const path = matches[0].path;
+    if (typeof path !== "string" || !isAbsolute(path) || basename(path) !== name || basename(dirname(path)) !== "skills") {
+      throw new Error(`Copilot skill has an unexpected installed path: ${name}`);
+    }
+    roots.add(dirname(dirname(path)));
+  }
+  if (roots.size !== 1) throw new Error("Copilot skills resolve to different plugin installations.");
+  const [pluginRoot] = roots;
+  if (digestNormalizedPluginSource(pluginRoot, definition.version) !== sourceDigest) {
+    throw new Error("Copilot discovered a stale or modified AGDF plugin payload.");
+  }
+  return { pluginRoot, count: expected.length, names: expected };
+}