msdevflow 0.7.4 → 0.7.6

package/lib/bootstrap.js

@@ -11,6 +11,7 @@ import {
   readdirSync,
   readSync,
   renameSync,
+  rmdirSync,
   rmSync,
   unlinkSync,
   writeFileSync,
@@ -24,7 +25,27 @@ import { fileURLToPath } from "node:url";
 const REGISTRY = "https://registry.npmjs.org";
 const GITCODE_PACKAGE = "@gitcode-cli/cli@latest";
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const BUNDLED_SKILL_DIR = path.join(PACKAGE_ROOT, "skill", "msdevflow");
+const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skill");
+const CORE_SKILL_NAME = "msd";
+const LEGACY_SKILL_NAME = "msdevflow";
+const PYTHON_RUNTIME_MARKER = ".msdevflow-python-runtime";
+const PYTHON_RUNTIME_MARKER_CONTENT = "managed-by=msdevflow\n";
+export const ACTIONS = [
+  "discover",
+  "create-issue",
+  "issue",
+  "develop",
+  "pr",
+  "ci",
+  "openlibing-auth",
+  "feedback",
+  "code-review",
+  "merge",
+];
+export const MANAGED_SKILL_NAMES = [
+  CORE_SKILL_NAME,
+  ...ACTIONS.map((action) => `${CORE_SKILL_NAME}-${action}`),
+];
 const SUPPORTED_CLIENTS = ["claude", "codex", "opencode"];
 const REQUIRED_SCHEMAS = {
   "auth login": ["web"],
@@ -70,8 +91,8 @@ client is detected, interactive setup asks which clients to install; non-interac
 setup requires --targets. OpenCode reuses a Claude or shared Agent Skills target
 instead of creating a third copy.
 
-The setup installs or updates the bundled msdevflow skill, installs or upgrades
-the official GitCode npm CLI, and installs all reviewed Python runtime
+The setup installs or updates the bundled msd core and msd-<action> skills,
+installs or upgrades the official GitCode npm CLI, and installs all reviewed Python runtime
 dependencies. It never downloads or launches Chromium. If GitCode is not
 authenticated, it starts the CLI's official browser login; setup never reads or
 prints a token.`;
@@ -167,29 +188,33 @@ function defaultAgentsSkillsDir(options, environment, platform) {
     || path.join(environmentHome(environment, platform), ".agents", "skills");
 }
 
-function createSkillLayout(kind, clients, skillsDir, bundledSkillDir) {
+function createSkillLayout(kind, clients, skillsDir, bundledSkillsDir) {
   const resolvedSkillsDir = path.resolve(skillsDir);
-  const workflowDir = path.join(resolvedSkillsDir, "msdevflow");
-  const bundledWorkflowDir = path.resolve(bundledSkillDir);
+  const resolvedBundledSkillsDir = path.resolve(bundledSkillsDir);
+  const coreDir = path.join(resolvedSkillsDir, CORE_SKILL_NAME);
+  const bundledCoreDir = path.join(resolvedBundledSkillsDir, CORE_SKILL_NAME);
   return {
     kind,
     clients,
     skillsDir: resolvedSkillsDir,
-    workflowDir,
-    workflowManifest: path.join(workflowDir, "SKILL.md"),
-    pythonRequirements: path.join(workflowDir, "scripts", "requirements.txt"),
-    bundledSkillDir: bundledWorkflowDir,
-    bundledManifest: path.join(bundledWorkflowDir, "SKILL.md"),
-    bundledPythonRequirements: path.join(bundledWorkflowDir, "scripts", "requirements.txt"),
+    coreDir,
+    coreManifest: path.join(coreDir, "SKILL.md"),
+    pythonRequirements: path.join(coreDir, "scripts", "requirements.txt"),
+    legacyDir: path.join(resolvedSkillsDir, LEGACY_SKILL_NAME),
+    legacyManifest: path.join(resolvedSkillsDir, LEGACY_SKILL_NAME, "SKILL.md"),
+    bundledSkillsDir: resolvedBundledSkillsDir,
+    bundledCoreDir,
+    bundledCoreManifest: path.join(bundledCoreDir, "SKILL.md"),
+    bundledPythonRequirements: path.join(bundledCoreDir, "scripts", "requirements.txt"),
   };
 }
 
-export function resolveLayout(options, environment = process.env, bundledSkillDir = BUNDLED_SKILL_DIR) {
+export function resolveLayout(options, environment = process.env, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
   return createSkillLayout(
     "claude",
     ["claude"],
     defaultClaudeSkillsDir(options, environment, process.platform),
-    bundledSkillDir,
+    bundledSkillsDir,
   );
 }
 
@@ -197,7 +222,7 @@ export function resolveLayouts(
   options,
   clients,
   environment = process.env,
-  bundledSkillDir = BUNDLED_SKILL_DIR,
+  bundledSkillsDir = BUNDLED_SKILLS_DIR,
   platform = process.platform,
 ) {
   const layouts = [];
@@ -207,7 +232,7 @@ export function resolveLayouts(
       "claude",
       openCodeUsesClaude ? ["claude", "opencode"] : ["claude"],
       defaultClaudeSkillsDir(options, environment, platform),
-      bundledSkillDir,
+      bundledSkillsDir,
     ));
   }
   if (clients.includes("codex") || (clients.includes("opencode") && !openCodeUsesClaude)) {
@@ -219,12 +244,12 @@ export function resolveLayouts(
       "agents",
       sharedClients,
       defaultAgentsSkillsDir(options, environment, platform),
-      bundledSkillDir,
+      bundledSkillsDir,
     ));
   }
   const unique = new Map();
   for (const layout of layouts) {
-    const key = normalizedPath(layout.workflowDir, platform);
+    const key = normalizedPath(layout.skillsDir, platform);
     const existing = unique.get(key);
     if (existing) {
       existing.clients = [...new Set([...existing.clients, ...layout.clients])];
@@ -440,7 +465,7 @@ function requireFile(file, description) {
   verifyFile(file, `${description} not found: ${file}. Reinstall the msdevflow npm package.`);
 }
 
-function skillManifestIsOwned(file) {
+function skillManifestIsOwned(file, expectedName) {
   try {
     const metadata = lstatSync(file);
     if (metadata.isSymbolicLink() || !metadata.isFile()) {
@@ -451,7 +476,7 @@ function skillManifestIsOwned(file) {
       return false;
     }
     const names = [...frontmatter[1].matchAll(/^name:\s*([^\s#]+)\s*$/gm)];
-    return names.length === 1 && names[0][1] === "msdevflow";
+    return names.length === 1 && names[0][1] === expectedName;
   } catch (error) {
     if (error?.code === "ENOENT") {
       return false;
@@ -491,26 +516,25 @@ function skillDigest(root) {
   return digest.digest("hex");
 }
 
-function skillInstallDetails(layout) {
-  requireFile(layout.bundledManifest, "bundled msdevflow skill manifest");
-  requireFile(layout.bundledPythonRequirements, "bundled workflow Python requirements file");
-  if (!skillManifestIsOwned(layout.bundledManifest)) {
-    throw new BootstrapError("Bundled skill manifest does not identify msdevflow.", 3);
+function installedSkillDetails(source, target, name) {
+  const sourceManifest = path.join(source, "SKILL.md");
+  requireFile(sourceManifest, `bundled ${name} skill manifest`);
+  if (!skillManifestIsOwned(sourceManifest, name)) {
+    throw new BootstrapError(`Bundled skill manifest does not identify ${name}.`, 3);
   }
-  validatePythonRequirements(layout.bundledPythonRequirements);
-  const bundledDigest = skillDigest(layout.bundledSkillDir);
+  const bundledDigest = skillDigest(source);
   let status = "absent";
   let existingDigest = null;
   try {
-    const metadata = lstatSync(layout.workflowDir);
+    const metadata = lstatSync(target);
     if (metadata.isSymbolicLink() || !metadata.isDirectory()
-        || !skillManifestIsOwned(layout.workflowManifest)) {
+        || !skillManifestIsOwned(path.join(target, "SKILL.md"), name)) {
       throw new BootstrapError(
-        `Refusing to overwrite a skills entry not owned by msdevflow: ${layout.workflowDir}`,
+        `Refusing to overwrite a skills entry not owned by ${name}: ${target}`,
         3,
       );
     }
-    existingDigest = skillDigest(layout.workflowDir);
+    existingDigest = skillDigest(target);
     status = existingDigest === bundledDigest ? "current" : "update";
   } catch (error) {
     if (error?.code !== "ENOENT") {
@@ -518,70 +542,211 @@ function skillInstallDetails(layout) {
     }
   }
   return {
-    source: layout.bundledSkillDir,
-    target: layout.workflowDir,
+    name,
+    source,
+    target,
     status,
     bundledDigest,
     existingDigest,
   };
 }
 
-function installBundledSkill(details) {
-  const parent = path.dirname(details.target);
-  mkdirSync(parent, { recursive: true });
-  const current = skillInstallDetails({
-    bundledSkillDir: details.source,
-    bundledManifest: path.join(details.source, "SKILL.md"),
-    bundledPythonRequirements: path.join(details.source, "scripts", "requirements.txt"),
-    workflowDir: details.target,
-    workflowManifest: path.join(details.target, "SKILL.md"),
-  });
-  if (current.status !== details.status || current.existingDigest !== details.existingDigest) {
-    throw new BootstrapError("msdevflow skill target changed after confirmation; refusing to overwrite it.", 3);
+function legacySkillDetails(layout) {
+  try {
+    const metadata = lstatSync(layout.legacyDir);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()
+        || !skillManifestIsOwned(layout.legacyManifest, LEGACY_SKILL_NAME)) {
+      throw new BootstrapError(
+        `Refusing to migrate a legacy skills entry not owned by ${LEGACY_SKILL_NAME}: ${layout.legacyDir}`,
+        3,
+      );
+    }
+    return {
+      target: layout.legacyDir,
+      status: "migrate",
+      existingDigest: skillDigest(layout.legacyDir),
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return {
+        target: layout.legacyDir,
+        status: "absent",
+        existingDigest: null,
+      };
+    }
+    throw error;
   }
-  if (current.status === "current") {
-    return "current";
+}
+
+function skillInstallDetails(layout) {
+  requireFile(layout.bundledPythonRequirements, "bundled workflow Python requirements file");
+  validatePythonRequirements(layout.bundledPythonRequirements);
+  const entries = MANAGED_SKILL_NAMES.map((name) => installedSkillDetails(
+    path.join(layout.bundledSkillsDir, name),
+    path.join(layout.skillsDir, name),
+    name,
+  ));
+  return {
+    source: layout.bundledSkillsDir,
+    target: layout.skillsDir,
+    entries,
+    legacy: legacySkillDetails(layout),
+  };
+}
+
+function assertSkillInstallUnchanged(details) {
+  const layout = {
+    skillsDir: details.target,
+    bundledSkillsDir: details.source,
+    bundledPythonRequirements: path.join(
+      details.source,
+      CORE_SKILL_NAME,
+      "scripts",
+      "requirements.txt",
+    ),
+    legacyDir: path.join(details.target, LEGACY_SKILL_NAME),
+    legacyManifest: path.join(details.target, LEGACY_SKILL_NAME, "SKILL.md"),
+  };
+  const current = skillInstallDetails(layout);
+  for (let index = 0; index < details.entries.length; index += 1) {
+    const expected = details.entries[index];
+    const actual = current.entries[index];
+    if (actual.name !== expected.name || actual.status !== expected.status
+        || actual.existingDigest !== expected.existingDigest
+        || actual.bundledDigest !== expected.bundledDigest) {
+      throw new BootstrapError(
+        `Skill target changed after confirmation; refusing to overwrite it: ${expected.target}`,
+        3,
+      );
+    }
+  }
+  if (current.legacy.status !== details.legacy.status
+      || current.legacy.existingDigest !== details.legacy.existingDigest) {
+    throw new BootstrapError(
+      `Legacy skill target changed after confirmation; refusing to migrate it: ${details.legacy.target}`,
+      3,
+    );
+  }
+}
+
+function installedSuiteResult(details) {
+  const entries = details.entries.map((entry) => ({
+    name: entry.name,
+    status: entry.status === "current"
+      ? "current"
+      : entry.status === "absent" ? "installed" : "updated",
+    target: entry.target,
+  }));
+  let status = "current";
+  if (details.legacy.status === "migrate") {
+    status = "migrated";
+  } else if (entries.some((entry) => entry.status === "updated")) {
+    status = "updated";
+  } else if (entries.some((entry) => entry.status === "installed")) {
+    status = "installed";
+  }
+  return { status, entries, legacy: details.legacy.status };
+}
+
+function suiteTransactionPath(details, name, extension) {
+  const skillsRootName = path.basename(details.target) || "skills";
+  return path.join(
+    path.dirname(details.target),
+    `.${skillsRootName}-msdevflow-${name}-${randomUUID()}.${extension}`,
+  );
+}
+
+function installBundledSkillSuites(suites) {
+  for (const details of suites) {
+    mkdirSync(details.target, { recursive: true });
+    assertSkillInstallUnchanged(details);
   }
-  const staging = path.join(parent, `.msdevflow-${randomUUID()}.tmp`);
-  const backup = path.join(parent, `.msdevflow-${randomUUID()}.backup`);
-  let movedExisting = false;
+  const staged = [];
+  const switched = [];
+  const migrated = [];
   try {
-    cpSync(details.source, staging, { recursive: true, errorOnExist: true });
-    if (skillDigest(staging) !== details.bundledDigest) {
-      throw new BootstrapError("Bundled skill verification failed after staging.", 3);
+    for (const details of suites) {
+      for (const entry of details.entries.filter((item) => item.status !== "current")) {
+        const staging = suiteTransactionPath(details, entry.name, "tmp");
+        cpSync(entry.source, staging, { recursive: true, errorOnExist: true });
+        if (skillDigest(staging) !== entry.bundledDigest) {
+          throw new BootstrapError(`Bundled ${entry.name} verification failed after staging.`, 3);
+        }
+        staged.push({ details, entry, staging });
+      }
     }
-    if (current.status === "update") {
-      renameSync(details.target, backup);
-      movedExisting = true;
+    for (const details of suites) {
+      assertSkillInstallUnchanged(details);
     }
-    try {
-      renameSync(staging, details.target);
-    } catch (error) {
-      if (movedExisting) {
-        renameSync(backup, details.target);
-        movedExisting = false;
+    for (const item of staged) {
+      const backup = suiteTransactionPath(item.details, item.entry.name, "backup");
+      if (item.entry.status === "update") {
+        renameSync(item.entry.target, backup);
       }
-      throw error;
+      try {
+        renameSync(item.staging, item.entry.target);
+      } catch (error) {
+        if (item.entry.status === "update") {
+          renameSync(backup, item.entry.target);
+        }
+        throw error;
+      }
+      switched.push({ ...item, backup: item.entry.status === "update" ? backup : null });
+    }
+    for (const details of suites.filter((item) => item.legacy.status === "migrate")) {
+      const backup = suiteTransactionPath(details, LEGACY_SKILL_NAME, "backup");
+      renameSync(details.legacy.target, backup);
+      migrated.push({ details, backup });
     }
-    if (movedExisting) {
-      movedExisting = false;
+  } catch (error) {
+    const rollbackFailures = [];
+    for (const item of migrated.reverse()) {
       try {
-        rmSync(backup, { recursive: true, force: true });
-      } catch {
-        // The verified target is already live; stale backup cleanup must not invalidate it.
+        renameSync(item.backup, item.details.legacy.target);
+      } catch (rollbackError) {
+        rollbackFailures.push(rollbackError);
+      }
+    }
+    for (const item of switched.reverse()) {
+      try {
+        rmSync(item.entry.target, { recursive: true, force: true });
+        if (item.backup !== null) {
+          renameSync(item.backup, item.entry.target);
+        }
+      } catch (rollbackError) {
+        rollbackFailures.push(rollbackError);
       }
     }
-    return current.status === "absent" ? "installed" : "updated";
+    if (rollbackFailures.length) {
+      throw new BootstrapError(
+        `Skill suite installation failed and rollback was incomplete: ${error.message}; rollback: ${rollbackFailures.map((failure) => failure.message).join("; ")}`,
+        3,
+      );
+    }
+    throw error;
   } finally {
-    rmSync(staging, { recursive: true, force: true });
-    if (movedExisting) {
+    for (const item of staged) {
+      rmSync(item.staging, { recursive: true, force: true });
+    }
+  }
+
+  for (const item of switched) {
+    if (item.backup !== null) {
       try {
-        renameSync(backup, details.target);
+        rmSync(item.backup, { recursive: true, force: true });
       } catch {
-        throw new BootstrapError(`Failed to restore previous msdevflow skill from ${backup}.`, 3);
+        // The verified replacement is live; stale backup cleanup can be retried manually.
       }
     }
   }
+  for (const item of migrated) {
+    try {
+      rmSync(item.backup, { recursive: true, force: true });
+    } catch {
+      // The legacy entry is no longer discoverable; stale backup cleanup is non-blocking.
+    }
+  }
+  return suites.map(installedSuiteResult);
 }
 
 function validatePythonRequirements(file) {
@@ -628,7 +793,7 @@ async function selectClientTargets(input, output, promptOutput = output) {
   promptOutput.write("No supported agent client was detected. Available targets: claude, codex, opencode, all.\n");
   const terminal = createInterface({ input, output: promptOutput });
   try {
-    const answer = await terminal.question("Install msdevflow for: ");
+    const answer = await terminal.question("Install the msd skill suite for: ");
     return parseTargets(answer);
   } finally {
     terminal.close();
@@ -653,7 +818,7 @@ async function resolveClientTargets(options, run, platform, selectClients) {
 function clientTargetWarnings(clients, layouts) {
   if (clients.includes("opencode") && layouts.length > 1) {
     return [
-      "OpenCode can discover msdevflow from both installed paths; keep both copies managed by this setup to prevent version drift.",
+      "OpenCode can discover the msd skill suite from both installed paths; keep both copies managed by this setup to prevent version drift.",
     ];
   }
   return [];
@@ -784,6 +949,176 @@ function environmentHome(environment, platform) {
   return environment.HOME || homedir();
 }
 
+function pythonRuntimeAt(directory, python, platform) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  return {
+    baseExecutable: python.executable,
+    baseVersion: python.version,
+    directory,
+    executable: pathApi.join(
+      directory,
+      platform === "win32" ? "Scripts" : "bin",
+      platform === "win32" ? "python.exe" : "python",
+    ),
+    marker: pathApi.join(directory, PYTHON_RUNTIME_MARKER),
+    platform,
+  };
+}
+
+function expandHomePath(value, home, platform, variable) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  let expanded = value;
+  if (value === "~") {
+    expanded = home;
+  } else {
+    const homeRelative = platform === "win32" ? /^~[\\/]/ : /^~\//;
+    if (homeRelative.test(value)) {
+      expanded = pathApi.join(home, value.slice(2));
+    }
+  }
+  if (!pathApi.isAbsolute(expanded) && !path.isAbsolute(expanded)) {
+    throw new BootstrapError(`${variable} must be an absolute path or start with ~.`, 2);
+  }
+  return expanded;
+}
+
+export function pythonRuntimeDetails(
+  python,
+  environment = process.env,
+  platform = process.platform,
+) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const home = environmentHome(environment, platform);
+  const configured = environment.MSDEVFLOW_PYTHON_DIR;
+  const directory = configured
+    ? expandHomePath(configured, home, platform, "MSDEVFLOW_PYTHON_DIR")
+    : platform === "win32"
+      ? pathApi.join(environment.LOCALAPPDATA || pathApi.join(home, "AppData", "Local"), "msdevflow", "python")
+      : pathApi.join(
+          environment.XDG_DATA_HOME
+            ? expandHomePath(environment.XDG_DATA_HOME, home, platform, "XDG_DATA_HOME")
+            : pathApi.join(home, ".local", "share"),
+          "msdevflow",
+          "python",
+        );
+  return pythonRuntimeAt(directory, python, platform);
+}
+
+function validatePythonRuntime(runtime, run) {
+  let marker;
+  try {
+    const metadata = lstatSync(runtime.directory);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+      throw new BootstrapError(
+        `Refusing to use a Python runtime path not owned by msdevflow: ${runtime.directory}`,
+        3,
+      );
+    }
+    marker = readOptionalFile(
+      runtime.marker,
+      `Refusing to use an invalid msdevflow Python runtime marker: ${runtime.marker}`,
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "absent";
+    }
+    throw error;
+  }
+  if (marker !== PYTHON_RUNTIME_MARKER_CONTENT) {
+    throw new BootstrapError(
+      `Refusing to use a Python runtime directory not owned by msdevflow: ${runtime.directory}`,
+      3,
+    );
+  }
+  let descriptor;
+  try {
+    descriptor = openSync(runtime.executable, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "repair";
+    }
+    throw error;
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+  if (runOptional(run, {
+    command: runtime.executable,
+    args: ["-m", "pip", "--version"],
+  }).status !== 0) {
+    return "repair";
+  }
+  return "current";
+}
+
+function writePythonRuntimeMarker(runtime) {
+  const existing = readOptionalFile(
+    runtime.marker,
+    `Refusing to replace an invalid msdevflow Python runtime marker: ${runtime.marker}`,
+  );
+  if (existing === PYTHON_RUNTIME_MARKER_CONTENT) {
+    return;
+  }
+  if (existing !== null) {
+    throw new BootstrapError(
+      `Refusing to replace an unrelated Python runtime marker: ${runtime.marker}`,
+      3,
+    );
+  }
+  writeFileSync(runtime.marker, PYTHON_RUNTIME_MARKER_CONTENT, { encoding: "utf8", flag: "wx" });
+}
+
+async function ensurePythonRuntime(runtime, status, runLong, run) {
+  if (validatePythonRuntime(runtime, run) !== status) {
+    throw new BootstrapError(
+      `Managed Python runtime changed after confirmation: ${runtime.directory}`,
+      3,
+    );
+  }
+  if (status === "absent") {
+    mkdirSync(path.dirname(runtime.directory), { recursive: true });
+    try {
+      mkdirSync(runtime.directory);
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new BootstrapError(
+          `Managed Python runtime changed after confirmation: ${runtime.directory}`,
+          3,
+        );
+      }
+      throw error;
+    }
+    try {
+      writePythonRuntimeMarker(runtime);
+    } catch (error) {
+      try {
+        rmdirSync(runtime.directory);
+      } catch {
+        // Preserve the marker failure as the actionable error.
+      }
+      throw error;
+    }
+  }
+  if (status !== "current") {
+    try {
+      await runLong({
+        command: runtime.baseExecutable,
+        args: ["-m", "venv", runtime.directory],
+      });
+    } catch (error) {
+      throw new BootstrapError(
+        `Python venv is unavailable for ${runtime.baseExecutable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup. ${error.message}`,
+        2,
+      );
+    }
+  }
+  verifyFile(
+    runtime.executable,
+    `Managed Python runtime was not created correctly: ${runtime.executable}`,
+  );
+}
+
 export function gitcodeInstallDetails(
   classification,
   environment = process.env,
@@ -831,11 +1166,11 @@ export function gitcodeInstallDetails(
   };
 }
 
-function readOptionalFile(file) {
+function readOptionalFile(file, invalidMessage = `Refusing to overwrite unrelated wrapper: ${file}`) {
   try {
     const metadata = lstatSync(file);
     if (metadata.isSymbolicLink() || !metadata.isFile()) {
-      throw new BootstrapError(`Refusing to overwrite unrelated wrapper: ${file}`, 3);
+      throw new BootstrapError(invalidMessage, 3);
     }
     return readFileSync(file, "utf8");
   } catch (error) {
@@ -951,11 +1286,16 @@ function safeAuthStatus(output) {
 function printPlan(plan, write) {
   write("Setup plan (no changes made yet):");
   write(`  Client targets: ${plan.clientTargets.clients.join(", ")} (${plan.clientTargets.source})`);
-  write(`  Bundled skill: ${plan.skillInstalls[0].details.source}`);
+  write(`  Bundled skill suite: ${plan.skillInstalls[0].details.source}`);
   for (const { layout, details } of plan.skillInstalls) {
-    write(`  Skill target: ${details.target}`);
+    write(`  Skill root: ${details.target}`);
     write(`    Clients: ${layout.clients.join(", ")}`);
-    write(`    Action: ${details.status}`);
+    for (const entry of details.entries) {
+      write(`    ${entry.name}: ${entry.status}`);
+    }
+    if (details.legacy.status === "migrate") {
+      write(`    ${LEGACY_SKILL_NAME}: migrate after suite verification`);
+    }
   }
   for (const warning of plan.clientTargets.warnings) {
     write(`  Warning: ${warning}`);
@@ -975,7 +1315,11 @@ function printPlan(plan, write) {
     write(`  Wrapper target: ${plan.gitcodeInstall.cliTarget}`);
   }
   write(`  npm command: ${formatCommand(plan.installInvocation)}`);
-  write(`  Python: ${plan.python.executable} (${plan.python.version.join(".")})`);
+  write(`  Base Python: ${plan.python.executable} (${plan.python.version.join(".")})`);
+  write(`  Managed Python runtime: ${plan.pythonRuntime.directory} (${plan.pythonRuntime.status})`);
+  if (plan.pythonRuntime.status === "absent") {
+    write(`  Python venv command: ${formatCommand(plan.venvInvocation)}`);
+  }
   write(`  Python dependency command: ${formatCommand(plan.pipInvocation)}`);
   write("  Browser binary download: disabled");
   write(`  GitCode authentication command when needed: ${plan.gitcodeInstall.workflowCommand} auth login --web`);
@@ -1079,7 +1423,8 @@ function textResult(result, write) {
   write("Setup completed:");
   write(`  Client targets: ${result.clients.join(", ")}`);
   for (const skill of result.skills) {
-    write(`  Skill: ${skill.status} at ${skill.target} (${skill.clients.join(", ")})`);
+    write(`  Skill suite: ${skill.status} at ${skill.target} (${skill.clients.join(", ")})`);
+    write(`    Entries: ${skill.entries.map((entry) => entry.name).join(", ")}`);
   }
   for (const warning of result.warnings) {
     write(`  Warning: ${warning}`);
@@ -1091,8 +1436,9 @@ function textResult(result, write) {
   if (result.gitcode.authentication.username) {
     write(`  Username: ${result.gitcode.authentication.username}`);
   }
-  write(`  Python: ${result.python.executable} ${result.python.version}`);
-  write("  Playwright Python package: installed");
+  write(`  Base Python: ${result.python.baseExecutable} ${result.python.baseVersion}`);
+  write(`  Managed Python runtime: ${result.python.executable}`);
+  write("  Playwright Python package: installed in managed runtime");
   write("  Chromium: not downloaded");
 }
 
@@ -1124,7 +1470,10 @@ export async function runSetup(options, dependencies = {}) {
     options,
     targetSelection.clients,
     environment,
-    dependencies.bundledSkillDir,
+    dependencies.bundledSkillsDir
+      || (dependencies.bundledSkillDir
+        ? path.dirname(dependencies.bundledSkillDir)
+        : BUNDLED_SKILLS_DIR),
     platform,
   );
   const skillInstalls = layouts.map((layout) => ({
@@ -1163,9 +1512,27 @@ export async function runSetup(options, dependencies = {}) {
   );
 
   const python = detectPython(run, platform);
-  run({ command: python.executable, args: ["-m", "pip", "--version"] });
-  const pipInvocation = {
+  const venvCapability = runOptional(run, {
     command: python.executable,
+    args: ["-m", "venv", "--help"],
+  });
+  if (venvCapability.status !== 0) {
+    throw new BootstrapError(
+      `Python venv is unavailable for ${python.executable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup.`,
+      2,
+    );
+  }
+  const configuredPythonRuntime = pythonRuntimeDetails(python, environment, platform);
+  const pythonRuntime = dependencies.pythonRuntimeDir
+    ? pythonRuntimeAt(dependencies.pythonRuntimeDir, python, platform)
+    : configuredPythonRuntime;
+  pythonRuntime.status = validatePythonRuntime(pythonRuntime, run);
+  const venvInvocation = {
+    command: python.executable,
+    args: ["-m", "venv", pythonRuntime.directory],
+  };
+  const pipInvocation = {
+    command: pythonRuntime.executable,
     args: ["-m", "pip", "install", "-r", layouts[0].bundledPythonRequirements],
   };
   const plan = {
@@ -1176,6 +1543,8 @@ export async function runSetup(options, dependencies = {}) {
     installInvocation,
     gitcodeInstall,
     python,
+    pythonRuntime,
+    venvInvocation,
     pipInvocation,
   };
   printPlan(plan, writePlan);
@@ -1194,6 +1563,20 @@ export async function runSetup(options, dependencies = {}) {
     validateWrapper(gitcodeInstall, platform);
   }
 
+  await progress.run(
+    pythonRuntime.status === "absent"
+      ? "Creating the managed Python runtime"
+      : pythonRuntime.status === "repair"
+        ? "Repairing the managed Python runtime"
+        : "Validating the managed Python runtime",
+    () => ensurePythonRuntime(pythonRuntime, pythonRuntime.status, runLong, run),
+  );
+  await progress.run("Installing reviewed Python dependencies", () => runLong(pipInvocation));
+  await progress.run(
+    "Verifying the Playwright Python package",
+    () => runLong({ command: pythonRuntime.executable, args: ["-c", "import playwright.sync_api"] }),
+  );
+
   const installed = await progress.run(
     "Installing the official GitCode CLI",
     () => installGitcode(plan, runLong, run, platform),
@@ -1204,12 +1587,6 @@ export async function runSetup(options, dependencies = {}) {
   );
   gitcode.command = installed.command;
   gitcode.executable = installed.executable;
-
-  await progress.run("Installing reviewed Python dependencies", () => runLong(pipInvocation));
-  await progress.run(
-    "Verifying the Playwright Python package",
-    () => runLong({ command: python.executable, args: ["-c", "import playwright.sync_api"] }),
-  );
   gitcode.authentication = await authenticateGitcode(
     installed.executable,
     gitcode.authentication,
@@ -1220,14 +1597,17 @@ export async function runSetup(options, dependencies = {}) {
     progress,
     options.json,
   );
-  const skills = await progress.run("Installing msdevflow skill targets", async () => (
-    skillInstalls.map(({ layout, details }) => ({
-      kind: layout.kind,
-      clients: layout.clients,
-      status: installBundledSkill(details),
-      target: layout.workflowDir,
-    }))
-  ));
+  const skills = await progress.run("Installing msd skill suites", async () => {
+    const installedSuites = installBundledSkillSuites(
+      skillInstalls.map(({ details }) => details),
+    );
+    return installedSuites.map((installedSuite, index) => ({
+      kind: skillInstalls[index].layout.kind,
+      clients: skillInstalls[index].layout.clients,
+      target: skillInstalls[index].layout.skillsDir,
+      ...installedSuite,
+    }));
+  });
   const result = {
     state: "ready",
     git: gitVersion,
@@ -1237,8 +1617,10 @@ export async function runSetup(options, dependencies = {}) {
     skills,
     gitcode,
     python: {
-      executable: python.executable,
-      version: python.version.join("."),
+      baseExecutable: python.executable,
+      baseVersion: python.version.join("."),
+      runtimeDirectory: pythonRuntime.directory,
+      executable: pythonRuntime.executable,
       playwright: "installed",
       chromium: "not-downloaded",
     },