agents-inc 0.164.0 → 0.166.0

package/dist/chunk-Y3VIRVVE.js

@@ -0,0 +1,932 @@
+#!/usr/bin/env node
+import {
+  installPluginSkills,
+  pluginInstallFailureError,
+  unbackedPluginInstallError,
+  unbackedPluginSkillIds
+} from "./chunk-VAPTVR3J.js";
+import {
+  clearTerminalScreen,
+  formatTerminalTooSmallMessage,
+  isTerminalLargeEnough
+} from "./chunk-RZDXDMT6.js";
+import {
+  STATUS_MESSAGES,
+  claimSlug,
+  completedWithFailures,
+  computeFileHash,
+  copy,
+  defaultUsageGuidance,
+  directoryExists,
+  fetchMarketplace,
+  findConfigLoadFailures,
+  findUnusableSavedSkillMetadata,
+  getErrorMessage,
+  getStackSkillIds,
+  glob,
+  hostAt,
+  injectForkedFromMetadata,
+  installationConfigsUnreadable,
+  isHomeDirectory,
+  parseFrontmatter,
+  pluginsInstalled,
+  propagatedRecompileSummary,
+  readFile,
+  readForkedFromMetadata,
+  readLocalSkillMetadata,
+  readSkillMetadata,
+  refuseUnofferedPlacements,
+  refuseUnofferedStack,
+  refuseUnwritableStack,
+  registeredProjectConfigUnreadable,
+  registeredProjectGone,
+  registeredProjectOnAnotherProvider,
+  remove,
+  resolveBranding,
+  resolveInstallPaths,
+  savedSkillMetadataUnusableError,
+  scopeBlockedStackAssignment,
+  sharedConfigProjectScopeAtHome,
+  skillAssignedToNoAgent,
+  skillMetadataUnusableDetail,
+  validateSkillPath,
+  verbose,
+  warn,
+  writeFile,
+  writeMetadataYaml
+} from "./chunk-A4KDXNOT.js";
+import {
+  BUILT_IN_MATRIX,
+  getCategoryDomain,
+  typedEntries,
+  typedKeys
+} from "./chunk-V5WXIM2F.js";
+import {
+  CLI_COLORS,
+  DEFAULT_BRANDING,
+  GITHUB_SOURCE,
+  LOCAL_SKILLS_PATH,
+  MIN_TERMINAL_SIZE,
+  STANDARD_FILES,
+  isActiveAt,
+  seedExternalSkillSchema
+} from "./chunk-ENGYJCTF.js";
+
+// src/cli/lib/exit-codes.ts
+var EXIT_CODES = {
+  SUCCESS: 0,
+  ERROR: 1,
+  INVALID_ARGS: 2,
+  NETWORK_ERROR: 3,
+  CANCELLED: 4,
+  /**
+   * The command ran to the end and part of what it set out to do did not happen.
+   *
+   * Distinct from {@link EXIT_CODES.ERROR} because the two ask opposite things of whoever reads
+   * them: an `ERROR` aborted, so nothing landed and the run can be repeated; this one landed and
+   * the repeat is the wrong move — what is owed is the remedy the output names, per failure.
+   * Collapsing it into `ERROR` would re-make the defect it exists to close one value along, and
+   * a spec asserting `not.toBe(0)` cannot tell a refusal from a partial apply either.
+   *
+   * It is raised at the END of a command, never mid-flight: the work completes first, which is
+   * the whole difference between this and `this.error`.
+   */
+  COMPLETED_WITH_FAILURES: 5
+};
+
+// src/cli/lib/seed/external-skills.ts
+import os from "os";
+import path from "path";
+import { mkdtemp } from "fs/promises";
+import { isDeepEqual, omit } from "remeda";
+
+// ../compile/src/carried-skill.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
+var NAME_FIELD = /^name:.*$/m;
+function withInstalledName(manifest, { id, description }) {
+  const named = `name: ${id}`;
+  const block = FRONTMATTER_BLOCK.exec(manifest);
+  if (!block) {
+    return `---
+${named}
+description: ${description}
+---
+
+${manifest}`;
+  }
+  const [whole, fields = ""] = block;
+  const renamed = NAME_FIELD.test(fields) ? fields.replace(NAME_FIELD, named) : `${named}
+${fields}`;
+  return `---
+${renamed}
+---${manifest.slice(whole.length)}`;
+}
+function carriedSkillAuthor(repo) {
+  const [owner = repo] = repo.split("/");
+  return `@${owner}`;
+}
+function carriedSkillMetadata({
+  id,
+  skill,
+  domain,
+  usageGuidance,
+  shipped
+}) {
+  return {
+    author: carriedSkillAuthor(skill.repo),
+    usageGuidance,
+    ...shipped,
+    displayName: skill.displayName,
+    slug: id,
+    category: skill.categoryId,
+    domain,
+    cliDescription: shortLabel(skill.description),
+    custom: true
+  };
+}
+var CLI_DESCRIPTION_MAX_LENGTH = 60;
+var ELLIPSIS = "\u2026";
+function shortLabel(description) {
+  if (description.length <= CLI_DESCRIPTION_MAX_LENGTH) return description;
+  const room = description.slice(
+    0,
+    CLI_DESCRIPTION_MAX_LENGTH - ELLIPSIS.length
+  );
+  return `${toLastWholeWord(room)}${ELLIPSIS}`;
+}
+function toLastWholeWord(text) {
+  const lastBreak = text.lastIndexOf(" ");
+  return (lastBreak > 0 ? text.slice(0, lastBreak) : text).trimEnd();
+}
+
+// src/cli/lib/seed/external-skills.ts
+function pluginInstallError(ids) {
+  return [
+    "This configuration cannot be installed: these skills travel inside it, so no marketplace serves them and they cannot be installed as plugins:",
+    ...ids.map((id) => `  ${id}`),
+    "Re-share it with each skill above set to eject, which is the only way a carried skill installs."
+  ].join("\n");
+}
+function selectedExternals(payload) {
+  return typedEntries(payload.external ?? {}).flatMap(([id, skill]) => {
+    const entry = payload.skills[id];
+    return entry ? [{ id, skill, entry }] : [];
+  });
+}
+function askedForAsPlugin(externals) {
+  return externals.filter(({ entry }) => entry.install !== "eject").map(({ id }) => id);
+}
+function claimingACatalogueId(externals, matrix) {
+  return externals.filter(({ id }) => heldByEitherCatalogue(id, matrix)).map(({ id }) => id);
+}
+var CATALOGUE_SKILL_IDS = new Set(typedKeys(BUILT_IN_MATRIX.skills));
+function heldByEitherCatalogue(id, matrix) {
+  return heldByLoadedCatalogue(matrix.skills[id]) || CATALOGUE_SKILL_IDS.has(id);
+}
+function heldByLoadedCatalogue(incumbent) {
+  return incumbent !== void 0 && incumbent.local !== true;
+}
+function catalogueIdCollisionError(ids) {
+  return [
+    "This configuration cannot be installed: these skills travel inside it under ids a catalogue already owns:",
+    ...ids.map((id) => `  ${id}`),
+    "A skill id is the directory the skill installs into, so each would be written over the catalogue's own copy of that skill. Re-share it with each skill above added again, which mints an id \u2014 'external-<category>-<name>' \u2014 that no catalogue owns."
+  ].join("\n");
+}
+function externalSlug(id) {
+  return id;
+}
+function repoRef(repo) {
+  return `${GITHUB_SOURCE.GITHUB_PREFIX}${repo}`;
+}
+function externalSkillDir(id, scope, projectDir) {
+  return path.join(resolveInstallPaths(projectDir, scope).skillsDir, id);
+}
+function externalCatalogueEntry(install) {
+  return {
+    id: install.id,
+    slug: externalSlug(install.id),
+    displayName: install.skill.displayName,
+    description: install.skill.description,
+    // Boundary cast held by the guard above it: the category was confirmed against the catalogue
+    // the payload names, and this one has just been shown to declare it too.
+    category: install.skill.categoryId,
+    author: carriedSkillAuthor(install.skill.repo),
+    path: `${LOCAL_SKILLS_PATH}/${install.id}/`,
+    conflictsWith: [],
+    requires: [],
+    alternatives: [],
+    discourages: [],
+    // Local and custom for the same reason: the bytes are on this machine and nowhere else, and
+    // the skill was authored outside the vocabulary this catalogue ships.
+    local: true,
+    custom: true,
+    localPath: install.skillDir
+  };
+}
+function seatExternalSkill({ id, skill, entry }, matrix, projectDir) {
+  const domain = getCategoryDomain(skill.categoryId);
+  if (domain === void 0) return [];
+  const install = {
+    id,
+    skill,
+    domain,
+    scope: entry.scope,
+    skillDir: externalSkillDir(id, entry.scope, projectDir)
+  };
+  matrix.skills[id] = externalCatalogueEntry(install);
+  claimSlug(matrix.slugMap, externalSlug(id), id);
+  return [install];
+}
+function registerExternalSkills(payload, matrix, projectDir) {
+  const externals = selectedExternals(payload);
+  const asPlugin = askedForAsPlugin(externals);
+  const colliding = claimingACatalogueId(externals, matrix);
+  if (asPlugin.length > 0) throw new Error(pluginInstallError(asPlugin));
+  if (colliding.length > 0) throw new Error(catalogueIdCollisionError(colliding));
+  return externals.flatMap((external) => seatExternalSkill(external, matrix, projectDir));
+}
+async function writeExternalSkills(installs) {
+  await refuseUncarriedDestinations(installs);
+  const written = await Promise.all(installs.map(writeExternalSkill));
+  return changedIds(written);
+}
+var SCRATCH_DIR_PREFIX = "agents-inc-carried-";
+async function carriedSkillsThatDiffer(installs) {
+  if (installs.length === 0) return [];
+  const scratch = await mkdtemp(path.join(os.tmpdir(), SCRATCH_DIR_PREFIX));
+  try {
+    const written = await Promise.all(
+      installs.map(async (install) => writeExternalSkill(await scratchCopyOf(install, scratch)))
+    );
+    return changedIds(written);
+  } finally {
+    await remove(scratch);
+  }
+}
+async function scratchCopyOf(install, scratch) {
+  const skillDir = path.join(scratch, install.id);
+  if (await directoryExists(install.skillDir)) await copy(install.skillDir, skillDir);
+  return { ...install, skillDir };
+}
+function changedIds(written) {
+  return written.filter(({ changed }) => changed).map(({ id }) => id);
+}
+async function writeExternalSkill(install) {
+  const before = await readSkillDir(install.skillDir);
+  await writeSkillTree(install);
+  await writeSkillManifest(install);
+  await registerSkillOnDisk(install);
+  return { id: install.id, changed: !isDeepEqual(before, await readSkillDir(install.skillDir)) };
+}
+async function readSkillDir(skillDir) {
+  if (!await directoryExists(skillDir)) return null;
+  const files = omit(await readSkillTree(skillDir), [STANDARD_FILES.METADATA_YAML]);
+  return { files, metadata: undated(await readLocalSkillMetadata(skillDir)) };
+}
+function undated(metadata) {
+  if (metadata?.forkedFrom === void 0) return metadata;
+  return { ...metadata, forkedFrom: omit(metadata.forkedFrom, ["date"]) };
+}
+async function refuseUncarriedDestinations(installs) {
+  const judged = await Promise.all(installs.map(judgeDestination));
+  const blocked = judged.filter((destination) => destination !== null);
+  if (blocked.length > 0) throw new Error(uncarriedDestinationError(blocked));
+}
+async function judgeDestination(install) {
+  const { id, skillDir } = install;
+  if (!await directoryExists(skillDir)) return null;
+  if ((await readForkedFromMetadata(skillDir))?.path !== void 0) return null;
+  return { id, skillDir };
+}
+function uncarriedDestinationError(blocked) {
+  return [
+    "This configuration cannot be installed: these skills travel inside it under ids this installation already keeps a skill directory for, and no shared configuration put those directories there:",
+    ...blocked.map(({ id, skillDir }) => `  ${id}  ->  ${skillDir}`),
+    "A skill id is the directory the skill installs into, so each would be written over a skill written here by hand or ejected from a marketplace. Move or rename the directory above, or re-share the configuration with each skill added again, which mints an id \u2014 'external-<category>-<name>' \u2014 that nothing here holds."
+  ].join("\n");
+}
+async function writeSkillTree(install) {
+  for (const [relativePath, contents] of Object.entries(install.skill.files)) {
+    const filePath = path.join(install.skillDir, relativePath);
+    validateSkillPath(filePath, install.skillDir, relativePath);
+    await writeFile(filePath, contents);
+  }
+}
+async function writeSkillManifest(install) {
+  const manifestPath = path.join(install.skillDir, STANDARD_FILES.SKILL_MD);
+  await writeFile(
+    manifestPath,
+    withInstalledName(await readFile(manifestPath), {
+      id: install.id,
+      description: install.skill.description
+    })
+  );
+}
+async function registerSkillOnDisk(install) {
+  const metadataPath = path.join(install.skillDir, STANDARD_FILES.METADATA_YAML);
+  const shipped = await readLocalSkillMetadata(install.skillDir);
+  await writeMetadataYaml(
+    metadataPath,
+    carriedSkillMetadata({
+      id: install.id,
+      skill: install.skill,
+      domain: install.domain,
+      usageGuidance: defaultUsageGuidance(install.skill.categoryId),
+      shipped
+    })
+  );
+  await injectForkedFromMetadata(
+    install.skillDir,
+    install.id,
+    await computeFileHash(path.join(install.skillDir, STANDARD_FILES.SKILL_MD)),
+    { source: repoRef(install.skill.repo), path: install.skill.path }
+  );
+}
+function unnameableRepoMessage(id) {
+  return `${id} travels inside a shared configuration, and this installation does not record the repository its content came from`;
+}
+function uncarryableContentMessage(id, reason) {
+  return `${id} travels inside a shared configuration, and ${reason}`;
+}
+function repoFromRef(ref) {
+  if (ref === void 0 || !ref.startsWith(GITHUB_SOURCE.GITHUB_PREFIX)) return void 0;
+  return ref.slice(GITHUB_SOURCE.GITHUB_PREFIX.length);
+}
+var NO_MANIFEST_DESCRIPTION = `no description can be read from its ${STANDARD_FILES.SKILL_MD}`;
+function manifestDescription(files, skillDir) {
+  const manifest = files[STANDARD_FILES.SKILL_MD];
+  if (manifest === void 0) return null;
+  const frontmatter = parseFrontmatter(manifest, path.join(skillDir, STANDARD_FILES.SKILL_MD));
+  return frontmatter === null ? null : frontmatter.description;
+}
+async function readSkillTree(skillDir) {
+  const files = await glob("**/*", skillDir, { dot: true });
+  const entries = await Promise.all(
+    files.map(async (file) => [file, await readFile(path.join(skillDir, file))])
+  );
+  return Object.fromEntries(entries);
+}
+async function readCarriedSkill({ id, skillDir, provenance }) {
+  if (provenance.path === void 0) return { carries: "nothing" };
+  const repo = repoFromRef(provenance.source);
+  if (repo === void 0) return { carries: "unshareable", line: unnameableRepoMessage(id) };
+  const described = await readSkillMetadata(path.join(skillDir, STANDARD_FILES.METADATA_YAML));
+  if (!described.usable) {
+    return { carries: "unshareable", line: uncarryableContentMessage(id, described.reason) };
+  }
+  const files = await readSkillTree(skillDir);
+  const description = manifestDescription(files, skillDir);
+  if (description === null) {
+    return { carries: "unshareable", line: uncarryableContentMessage(id, NO_MANIFEST_DESCRIPTION) };
+  }
+  const parsed = seedExternalSkillSchema.safeParse({
+    displayName: described.metadata.displayName,
+    description,
+    categoryId: described.metadata.category,
+    repo,
+    path: provenance.path,
+    files
+  });
+  if (!parsed.success) {
+    const reason = parsed.error.issues.map((issue) => issue.message).join("; ");
+    return { carries: "unshareable", line: uncarryableContentMessage(id, reason) };
+  }
+  return { carries: "content", id, skill: parsed.data };
+}
+async function readCarriedSkills(owned) {
+  const reads = await Promise.all(owned.map(readCarriedSkill));
+  return {
+    external: Object.fromEntries(
+      reads.flatMap((read) => read.carries === "content" ? [[read.id, read.skill]] : [])
+    ),
+    uncarryable: reads.flatMap((read) => read.carries === "unshareable" ? [read.line] : [])
+  };
+}
+
+// src/cli/base-command.ts
+import { Command } from "@oclif/core";
+import chalk from "chalk";
+import { unique } from "remeda";
+
+// src/cli/lib/operations/source/ensure-marketplace.ts
+async function ensureMarketplace(sourceResult, host) {
+  const source = sourceResult.sourceConfig.source;
+  if (!sourceResult.marketplace) {
+    try {
+      const marketplaceResult = await fetchMarketplace(source);
+      sourceResult.marketplace = marketplaceResult.marketplace.name;
+    } catch (error) {
+      warn(`Could not resolve a marketplace from '${source}': ${getErrorMessage(error)}`);
+      return { marketplace: null, registered: false };
+    }
+  }
+  const marketplace = sourceResult.marketplace;
+  const exists = await host.marketplaceExists(marketplace);
+  if (!exists) {
+    const marketplaceSource = source.replace(/^github:/, "");
+    await host.addMarketplace(marketplaceSource);
+    return { marketplace, registered: true };
+  }
+  try {
+    await host.refreshMarketplace(marketplace);
+  } catch {
+    warn("Could not update marketplace \u2014 continuing with cached version");
+  }
+  return { marketplace, registered: false };
+}
+
+// src/cli/lib/operations/source/require-marketplace.ts
+async function requireMarketplace(sourceResult, purpose, host) {
+  const mpResult = await ensureMarketplace(sourceResult, host);
+  if (!mpResult.marketplace) {
+    return {
+      ok: false,
+      error: `Cannot ${purpose}: marketplace could not be resolved from '${sourceResult.sourceConfig.source}'. Plugin install mode requires a marketplace \u2014 fix the marketplace or switch the affected skills to eject mode.`
+    };
+  }
+  return { ok: true, marketplace: mpResult.marketplace, registered: mpResult.registered };
+}
+
+// src/cli/base-command.ts
+var TERMINAL_RESIZE_POLL_MS = 500;
+var terminalColumns = () => process.stdout.columns ?? MIN_TERMINAL_SIZE.COLS;
+var terminalRows = () => process.stdout.rows ?? MIN_TERMINAL_SIZE.ROWS;
+function isTerminalBigEnough() {
+  return isTerminalLargeEnough(terminalColumns(), terminalRows());
+}
+function waitForTerminal(isSatisfied) {
+  return new Promise((resolve) => {
+    const check = () => {
+      if (!isSatisfied()) return;
+      clearInterval(interval);
+      process.stdout.off("resize", check);
+      resolve();
+    };
+    const interval = setInterval(check, TERMINAL_RESIZE_POLL_MS);
+    process.stdout.on("resize", check);
+  });
+}
+function findUnassignedSkills(config, selected) {
+  const assignedIds = new Set(config.stack ? getStackSkillIds(config.stack) : []);
+  const selectedIds = new Set(selected.map((skill) => skill.id));
+  const globalAgentNames = config.agents.filter((agent) => isActiveAt(agent, "global")).map((agent) => agent.name);
+  const unassignedIds = unique(
+    config.skills.filter((skill) => !skill.excluded && selectedIds.has(skill.id)).map((skill) => skill.id).filter((skillId) => !assignedIds.has(skillId))
+  );
+  return unassignedIds.map((skillId) => ({
+    skillId,
+    blockedBy: hasActiveProjectEntry(config.skills, skillId) ? globalAgentNames : []
+  }));
+}
+function hasActiveProjectEntry(skills, skillId) {
+  return skills.some((skill) => skill.id === skillId && isActiveAt(skill, "project"));
+}
+function projectScopedContent(result) {
+  return {
+    skillIds: result.skills.filter((skill) => isActiveAt(skill, "project")).map((skill) => skill.id),
+    agentNames: result.agentConfigs.filter((agent) => isActiveAt(agent, "project")).map((agent) => agent.name)
+  };
+}
+var BaseCommand = class extends Command {
+  /**
+   * Everything this run set out to do and did not, in the order it hit them.
+   *
+   * Non-empty is the whole of the exit-code decision — see {@link exitIfWorkIncomplete}. It is
+   * deliberately not a boolean: a non-zero exit whose output does not say what failed and what
+   * finishes it is worse than the silent success it replaces.
+   *
+   * Private, with {@link hasIncompleteWork} the only reading a subclass gets. A command records
+   * through the two methods below and asks whether anything is owed; the list itself is this
+   * class's, because it is this class that answers for it.
+   */
+  incompleteWork = [];
+  async init() {
+    await super.init();
+    await this.ensureTerminalSize();
+  }
+  /**
+   * Blocks the command from launching in a terminal below
+   * {@link MIN_TERMINAL_SIZE}. This runs once, before Ink mounts; the terminal
+   * shrinking mid-session is caught by the matching guard in `WizardLayout`.
+   */
+  async ensureTerminalSize() {
+    if (isTerminalBigEnough()) return;
+    this.clearTerminal();
+    this.log(chalk.hex(CLI_COLORS.WARNING)(formatTerminalTooSmallMessage(terminalColumns())));
+    await waitForTerminal(isTerminalBigEnough);
+  }
+  handleError(error) {
+    const message = getErrorMessage(error);
+    this.error(message, { exit: EXIT_CODES.ERROR });
+  }
+  /**
+   * The name this run prints itself under: `branding.name` where a config supplies one, and
+   * {@link DEFAULT_BRANDING.NAME} everywhere else.
+   *
+   * **DEGRADE is the posture, and it is chosen here for every command that prints a name.**
+   * `loadSourceConfig` raises for a config that exists and cannot be evaluated, and two of the
+   * four callers must survive precisely that state: `doctor`'s whole job is naming it, and
+   * `uninstall` is the only way out of it. A heading is decoration — nothing about a display name
+   * is worth refusing a command over, and refusing here would turn the branding wiring into a new
+   * way for an unreadable config to abort two commands that survive it today. `init` and `eject`
+   * cannot reach the catch at all: {@link ensureConfigReadable} has already refused every config
+   * they would read.
+   *
+   * The cause is not swallowed: it goes to `verbose`, and the command's own config reader reports
+   * it in full where the user needs to act on it. Reporting it twice would put a warning about
+   * the configuration above a heading, which is the one line that has to be the first thing on
+   * screen.
+   */
+  async resolveBrandingName(projectDir) {
+    try {
+      const branding = await resolveBranding(projectDir);
+      return branding.name;
+    } catch (error) {
+      verbose(`Could not read branding from the config: ${getErrorMessage(error)}`);
+      return DEFAULT_BRANDING.NAME;
+    }
+  }
+  logSuccess(message) {
+    this.log(`\u2713 ${message}`);
+  }
+  logWarning(message) {
+    this.warn(message);
+  }
+  logInfo(message) {
+    this.log(message);
+  }
+  clearTerminal() {
+    clearTerminalScreen();
+  }
+  /**
+   * Resolves the marketplace required for a plugin operation, or hard-exits with
+   * an actionable error when it cannot be resolved. `onRegistered` is invoked
+   * (when provided) if the marketplace had to be registered — init uses it to log.
+   *
+   * `host` is the caller's because a marketplace registration is handed no directory of its own:
+   * every caller here holds the install root the run is about, and `hostAt` turns one into the
+   * host whose registry the marketplace has to land in.
+   */
+  async requireMarketplaceOrExit(sourceResult, purpose, host, onRegistered) {
+    const required = await requireMarketplace(sourceResult, purpose, host);
+    if (!required.ok) {
+      this.error(required.error, { exit: EXIT_CODES.ERROR });
+    }
+    if (required.registered) {
+      onRegistered?.(required.marketplace);
+    }
+    return required.marketplace;
+  }
+  /**
+   * Reports every constraint a completed selection breaks — a conflicting pair, an unmet
+   * requirement, an exclusive category with two picks.
+   *
+   * Shared by `init` and `edit` so one selection cannot be reported two ways. Both commands ask
+   * the same question of the same matrix, so a roster that draws a warning through one must draw
+   * the same warning through the other; `init` used to compute the answer and drop it, which is
+   * the whole reason this lives here rather than on either command.
+   *
+   * These are advisory (`ValidationError` in types/matrix.ts): the selection is installed either
+   * way and neither command's exit code turns on them, so they are warnings and not errors. The
+   * loop is its own guard — an accepted selection carries no errors and says nothing.
+   */
+  reportValidationErrors(validation) {
+    for (const error of validation.errors) {
+      this.warn(error.message);
+    }
+  }
+  /**
+   * Installs skill plugins and narrates the operation.
+   *
+   * Shared by `init` and `edit` for the same reason as {@link reportValidationErrors}:
+   * both run the SAME install against the same marketplace, so a line one prints about
+   * it the other owes. `edit` used to run it in silence — a real `claude plugin install`
+   * was indistinguishable in the output from nothing having happened.
+   *
+   * The skills nothing carries are refused FIRST, by name: an install no marketplace
+   * could serve is knowable before the Claude CLI is asked, and the generic
+   * install-failure advice is unfollowable for a skill the user wrote themselves.
+   */
+  async installPluginSkillsReported(skills, marketplace, projectDir, matrix) {
+    const unbacked = unbackedPluginSkillIds(skills, matrix);
+    if (unbacked.length > 0) {
+      this.error(unbackedPluginInstallError(unbacked), { exit: EXIT_CODES.ERROR });
+    }
+    this.announcePluginInstall();
+    const result = await installPluginSkills(skills, marketplace, projectDir);
+    this.reportPluginInstalls(result);
+    return result;
+  }
+  /**
+   * The opening half of the narration above, exposed for the one caller that cannot
+   * use the whole of it: an eject→plugin migration installs each plugin and deletes
+   * that skill's working copy in the same step (see `executeMigration`), so the
+   * install it performs is not this command's to run.
+   */
+  announcePluginInstall() {
+    this.log(STATUS_MESSAGES.INSTALLING_PLUGINS);
+  }
+  /**
+   * The closing half: what was installed, what was not, and the refusal to continue
+   * past a failure.
+   *
+   * The hard-error is part of the report rather than each caller's own postscript
+   * because it is the same rule everywhere — plugin install intent is inviolable, so
+   * a run that could not honor it must stop BEFORE any config records a marketplace
+   * `origin` for a skill with no plugin registration.
+   */
+  reportPluginInstalls(result) {
+    for (const item of result.installed) {
+      this.log(`  Installed ${item.ref}`);
+    }
+    for (const item of result.failed) {
+      this.warn(`Failed to install plugin ${item.id}: ${item.error}`);
+    }
+    if (result.failed.length > 0) {
+      this.error(pluginInstallFailureError(result.failed.length), { exit: EXIT_CODES.ERROR });
+    }
+    this.log(`${pluginsInstalled(result.installed.length)}
+`);
+  }
+  /**
+   * Renders what a gated write's fan-out did to the OTHER registered projects: one line for each
+   * it left alone because its config.ts cannot be loaded, then the recompile it performed.
+   *
+   * `uninstall` alone calls {@link reportPropagatedRecompile} directly, since it words the projects
+   * whose config it could not prune in its own terms.
+   */
+  reportFanOut(report) {
+    for (const projectPath of report.propagated.unreadable) {
+      this.warn(registeredProjectConfigUnreadable(projectPath));
+    }
+    this.reportPropagatedRecompile(report);
+  }
+  /**
+   * One line for each registered project a fan-out left alone because nothing of this
+   * installation is there to rewrite: nothing is installed at its path any more, or it is another
+   * provider's installation. `compile` and `uninstall` print it — neither project's config can
+   * hold what either run changed.
+   */
+  reportProjectsOutOfReach(propagated) {
+    for (const projectPath of propagated.gone) {
+      this.warn(registeredProjectGone(projectPath));
+    }
+    for (const projectPath of propagated.notOurs) {
+      this.warn(registeredProjectOnAnotherProvider(projectPath));
+    }
+  }
+  /**
+   * Renders the recompile a gated write already performed on every OTHER registered
+   * project this run's global change was propagated into.
+   *
+   * Shared by all four commands that fan out — the count and its wording are one
+   * statement about one operation, and four copies of it had already drifted into two
+   * spellings of the same sentence.
+   */
+  reportPropagatedRecompile(report) {
+    if (report.propagated.updated.length === 0) return;
+    const { rewrittenCount, unchangedCount, failedCount, warnings } = report.recompile;
+    for (const warning of warnings) {
+      this.warn(warning);
+    }
+    this.log(propagatedRecompileSummary(rewrittenCount, unchangedCount, failedCount));
+  }
+  /**
+   * Names every selected skill this save left in no sub-agent's stack, and — where the
+   * scope rule is why — every sub-agent it was kept away from.
+   *
+   * Shared by `init` and `edit` for the reason {@link reportValidationErrors} is: both
+   * build the stack from the same rules over the same selection, so a skill that reaches
+   * nothing through one reaches nothing through the other. The rule being reported is
+   * CORRECT and nothing here changes it — a project-scoped skill installs, is written to
+   * `config.ts`, and is loaded by nobody, which every other surface reports as a clean
+   * install.
+   *
+   * `compile` says the same thing about the same shape one layer over, for a config
+   * hand-edited into it — see `Compile.warnScopeDroppedStackPairs`.
+   */
+  reportUnassignedSkills(config, selected) {
+    for (const { skillId, blockedBy } of findUnassignedSkills(config, selected)) {
+      this.warn(skillAssignedToNoAgent(skillId));
+      if (blockedBy.length > 0) {
+        this.warn(scopeBlockedStackAssignment(blockedBy, skillId));
+      }
+    }
+  }
+  /**
+   * Refuses to run when a config file exists but cannot be loaded.
+   *
+   * Both configs this run would read are checked, because both are read on the way through: a
+   * project's own `config.ts` and the global one every project write inlines. Checking up
+   * front is the whole point — an unreadable GLOBAL config otherwise surfaced only at the
+   * config write, after the wizard had copied skills and installed plugins, as a warning that
+   * the write never happened.
+   *
+   * Every command that reads an installation's config calls it before anything else reads one:
+   * the writes (`init`, `edit`, `compile`, `update`, `share`, `eject`) and the two that only
+   * report (`search`, `list`). `doctor` reports the same file instead, and `uninstall` is the way
+   * out of it, so neither does.
+   *
+   * A MISSING config is not a corrupt one and passes here untouched: it is the legitimate
+   * state `init` exists for, and the state `edit` reports as "no installation".
+   */
+  async ensureConfigReadable(projectDir) {
+    const failures = await findConfigLoadFailures(projectDir);
+    if (failures.length > 0) {
+      this.error(installationConfigsUnreadable(failures), { exit: EXIT_CODES.ERROR });
+    }
+  }
+  /**
+   * Refuses to run when a saved skill entry names a local skill that IS installed and whose
+   * metadata.yaml describes no skill.
+   *
+   * One layer below {@link ensureConfigReadable} and for the same reason: the config parses,
+   * and a file it points at does not. Both wizards resolve their saved roster against the
+   * loaded catalogue, and an id nothing can be loaded for reaches no screen — so without this
+   * the entry is dropped and reported as a skill the marketplace no longer carries, which is a
+   * removal the user never asked for and a sentence blaming the wrong thing.
+   *
+   * Only entries the catalogue does not carry are looked at, so a healthy install pays a
+   * filesystem read for nothing. An entry whose files are simply GONE is not refused — there
+   * is no file to repair, so it is removed with a reason that says so
+   * (`unresolvedSkillRemovalReasons`).
+   *
+   * Runs before the wizard mounts, which is the whole point: past that, a refusal costs the
+   * user the session they had already spent, and everything this protects has been rewritten.
+   */
+  async ensureSavedSkillsReadable(savedSkills, matrix, projectDir) {
+    const unresolved = savedSkills.filter((saved) => !saved.excluded && !matrix.skills[saved.id]).map((saved) => saved.id);
+    if (unresolved.length === 0) return;
+    const unusable = await findUnusableSavedSkillMetadata(unresolved, savedSkills, projectDir);
+    if (unusable.length === 0) return;
+    for (const entry of unusable) {
+      this.log(skillMetadataUnusableDetail(entry));
+    }
+    this.error(savedSkillMetadataUnusableError(unusable), { exit: EXIT_CODES.ERROR });
+  }
+  /**
+   * Refuses a shared configuration carrying project-scoped content at the home directory.
+   *
+   * The home directory IS the global scope, and a global installation holds only global-scoped
+   * content. Both scopes read one config file there, and on Claude one skills directory and one
+   * agents directory as well — so a project-scoped entry lands in the global config wearing a
+   * label that contradicts the file it is in, and on Claude `toClaudePluginScope` maps that
+   * declared scope onward, registering the skill against `$HOME` as a project. Nothing
+   * below this point reads the scope again, so whatever the boundary lets through becomes the
+   * truth.
+   *
+   * Shared by `init --from` and `edit --from` for the reason {@link reportValidationErrors} is
+   * shared: it is a fact about the payload and the directory, identical whichever command asked,
+   * and an invariant enforced on one producer and not the other is enforced nowhere. It matters
+   * more on the destructive one — `edit --from` reaches the same contradiction through the other
+   * door and can remove global entries on the way.
+   *
+   * The interactive producer has always answered this for itself — `isHomeDirectory(projectDir)`
+   * reaches the wizard session as `isGlobalRoot` and the scope toggles are inert under it — so
+   * this puts both `--from` paths on the rule the wizard already follows.
+   *
+   * It takes the DECODED selection, so it must run after the decode and can run no earlier: an
+   * all-global configuration is exactly what a global installation is for, and only the decode
+   * says which entries survived this catalogue and what scope each rests at. Every caller runs it
+   * before it reports a skip and before it writes anything, so a run about to be refused neither
+   * narrates nor mutates.
+   */
+  refuseProjectScopedContentAtHome(result, projectDir) {
+    if (!isHomeDirectory(projectDir)) return;
+    const { skillIds, agentNames } = projectScopedContent(result);
+    if (skillIds.length === 0 && agentNames.length === 0) return;
+    this.error(sharedConfigProjectScopeAtHome(skillIds, agentNames), { exit: EXIT_CODES.ERROR });
+  }
+  /**
+   * The refusals a `--from` producer can decide only once it holds what it would install — the
+   * selection and the skills the configuration carries — asked before it lists any of it or asks
+   * whether to install it.
+   *
+   * A run that lists, asks, and is told yes has promised that a yes installs what was listed (the
+   * u01 ruling: "On yes, it installs what is listed"), so a refusal still to come after the
+   * question would ask a person to confirm an install that was never going to happen. Every other
+   * `--from` refusal is already decided above the lists — a carried skill asked for as a plugin or
+   * under a catalogue's id, project content at the home directory, an installation already here —
+   * and these four are the ones that need the decoded selection to be asked of:
+   *
+   * - **A placement the host does not offer.** Read off the selection and the host the run
+   *   installs through, nothing else, so nothing makes it wait for the yes.
+   * - **A stack the marketplace does not ship.** The stack supplies only the configuration's
+   *   description, yet the install refuses an id it cannot resolve — after the plugins are
+   *   installed and the skills copied. So it is asked here, through the lookup the install makes,
+   *   of the marketplace the install reads.
+   * - **A carried skill over a directory no shared configuration put there** — the user's own
+   *   skill at the id the configuration minted for it. Judged on the same set the producer writes,
+   *   so the skills already installed globally, which it does not write, are not asked about.
+   * - **A stack the config writer would refuse** — two skills in a category that holds one, as a
+   *   hand-written row or the kept skills an apply puts back can make. Asked through the writer's
+   *   own rule, because `edit --from` writes the config after its removals have landed.
+   *
+   * Shared by `init --from` and `edit --from` for the reason {@link refuseProjectScopedContentAtHome}
+   * is: an invariant enforced on one producer and not the other is enforced nowhere.
+   */
+  async refuseSharedConfigBeforeAsking(selection, carried, root, sourceResult) {
+    this.refuseUnofferablePlacementsBeforeWriting(selection.skills, root);
+    try {
+      await refuseUnofferedStack(selection.selectedStackId, sourceResult);
+      await refuseUncarriedDestinations(carried);
+      refuseUnwritableStack(selection.assignedStack, sourceResult.matrix);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Refuses a SELECTION asking for a mode/scope cell this host does not offer, before the run has
+   * touched anything.
+   *
+   * **`bindsItsOfferedPlacements` is not a pre-flight and cannot be made into one.** It refuses
+   * at `installPlugin`, which `installPluginSkills` calls once per skill inside a loop that
+   * collects per-skill failures — so a payload whose first plugin row is offerable and whose
+   * second is not installed a real plugin into the user's Codex registry and only then stopped,
+   * on a message ending "Nothing has been changed." Nothing removed it afterwards: no `config.ts`
+   * was written, so `uninstall` had no row naming it and `doctor` had no configuration to check
+   * it against — an orphan in the host's own registry that no command in this CLI can see. The
+   * single-row case cannot show it, because with one unofferable row the loop's first iteration
+   * IS the refusal. `edit --from` had no pre-flight at all until it came here, and met exactly
+   * that per-plugin guard after its own yes.
+   *
+   * It reads the whole selection — ejected rows included — because the roster is about CELLS
+   * rather than about plugins: a host that stopped offering `eject+project` would owe the same
+   * refusal, and a guard that only looked at plugin rows would go on writing files for it.
+   *
+   * The same function the read path calls (`refuseUnofferedPlacements`, off the same host
+   * roster), so `init`'s sentence and `compile`'s are one sentence rather than two that agree
+   * today. The per-call guard stays where it is: it is the backstop for a caller that did not
+   * come through here, and for the one host this release ships every cell is offered, so a
+   * backstop that never fires is what a deleted one would look like.
+   */
+  refuseUnofferablePlacementsBeforeWriting(skills, root) {
+    try {
+      refuseUnofferedPlacements(skills, hostAt(root));
+    } catch (error) {
+      this.error(getErrorMessage(error), { exit: EXIT_CODES.ERROR });
+    }
+  }
+  /** Whether this run owes an account — the one thing a command may ask about the list. */
+  get hasIncompleteWork() {
+    return this.incompleteWork.length > 0;
+  }
+  /**
+   * Warns about work this run attempted and did not complete, and records it for the ending.
+   *
+   * Both halves, always. The warning stays at the point of failure because that is where it is
+   * explicable and where the surrounding output says what was being attempted; the record is
+   * what decides the exit code, and a failure the user is told about while the process reports
+   * success is exactly the state this closes.
+   *
+   * What it must never do is abort. Every caller sits past the point where the mutation it is
+   * reporting on has already happened, so stopping would relabel a state already committed to
+   * disk rather than prevent it — and would abandon the steps after it that can still land.
+   *
+   * The `recovery` sentences live in `INCOMPLETE_WORK_RECOVERY` in `utils/messages.ts`. One
+   * spelling per remedy is what matters; three spellings of "run compile" read as three
+   * different instructions.
+   */
+  reportIncompleteWork(what, recovery) {
+    this.warn(what);
+    this.recordIncompleteWork(what, recovery);
+  }
+  /**
+   * The recording half alone, for a caller that has already said its piece: a recompile warns
+   * once per failed sub-agent with the compiler's own reason, so the ending names the roster
+   * those reasons belong to instead of repeating any of them.
+   */
+  recordIncompleteWork(what, recovery) {
+    this.incompleteWork.push({ what, recovery });
+  }
+  /**
+   * The command's last word: what did not happen, what finishes it, and a non-zero exit.
+   *
+   * `this.exit` raises oclif's `ExitError`, which the framework carries to the process exit
+   * code and prints nothing for — so the account printed here is the whole of the output, with
+   * none of the `Error:` framing `this.error` would add to a command that in fact completed.
+   *
+   * A command that records must call this, or it files failures into a list nothing reads —
+   * which is the original silence wearing the mechanism built to close it, and is what
+   * `failure-reporting-classification.test.ts` holds every command in `src/cli/commands/` to.
+   */
+  exitIfWorkIncomplete() {
+    if (!this.hasIncompleteWork) return;
+    this.log(`
+${chalk.hex(CLI_COLORS.WARNING)(completedWithFailures(this.incompleteWork))}
+`);
+    this.exit(EXIT_CODES.COMPLETED_WITH_FAILURES);
+  }
+};
+
+export {
+  EXIT_CODES,
+  registerExternalSkills,
+  writeExternalSkills,
+  carriedSkillsThatDiffer,
+  readCarriedSkills,
+  BaseCommand
+};
+//# sourceMappingURL=chunk-Y3VIRVVE.js.map