@jskit-ai/jskit-cli 0.2.27 → 0.2.28

package/src/server/cliRuntime.js

@@ -1,4956 +0,0 @@
-import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import {
-  access,
-  constants as fsConstants,
-  mkdtemp,
-  mkdir,
-  readFile,
-  readdir,
-  rm,
-  writeFile
-} from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import process from "node:process";
-import { pathToFileURL } from "node:url";
-import { createCliError } from "./cliError.js";
-import {
-  ensureArray,
-  ensureObject,
-  sortStrings
-} from "./collectionUtils.js";
-import {
-  createColorFormatter,
-  resolveWrapWidth,
-  writeWrappedItems
-} from "./outputFormatting.js";
-import {
-  BUNDLES_ROOT,
-  CATALOG_PACKAGES_PATH,
-  CLI_PACKAGE_ROOT
-} from "./pathResolution.js";
-import {
-  appendTextSnippet,
-  escapeRegExp,
-  interpolateOptionValue,
-  normalizeSkipChecks,
-  promptForRequiredOption
-} from "./optionInterpolation.js";
-import { createCommandHandlers } from "./commandHandlers.js";
-import { parseArgs, printUsage } from "./argParser.js";
-import { createCommandHandlerDeps } from "./runtimeDeps.js";
-import { createRunCli } from "./runCli.js";
-import {
-  toScopedPackageId,
-  resolvePackageIdInput,
-  resolveInstalledPackageIdInput
-} from "./packageIdHelpers.js";
-
-const LOCK_RELATIVE_PATH = ".jskit/lock.json";
-const LOCK_VERSION = 1;
-const VITE_DEV_PROXY_CONFIG_RELATIVE_PATH = ".jskit/vite.dev.proxy.json";
-const VITE_DEV_PROXY_CONFIG_VERSION = 1;
-const PUBLIC_APP_CONFIG_RELATIVE_PATH = "config/public.js";
-const SERVER_APP_CONFIG_RELATIVE_PATH = "config/server.js";
-const PACKAGE_KIND_RUNTIME = "runtime";
-const PACKAGE_KIND_GENERATOR = "generator";
-const PACKAGE_KINDS = Object.freeze([PACKAGE_KIND_RUNTIME, PACKAGE_KIND_GENERATOR]);
-const WORKSPACE_VISIBILITY_LEVELS = Object.freeze(["workspace", "workspace_user"]);
-const WORKSPACE_VISIBILITY_SET = new Set(WORKSPACE_VISIBILITY_LEVELS);
-const MATERIALIZED_PACKAGE_ROOTS = new Map();
-const MATERIALIZED_PACKAGE_TEMP_DIRECTORIES = new Set();
-const LOCAL_WORKSPACE_PACKAGE_ROOTS = new Map();
-let LOCAL_WORKSPACE_PACKAGE_ID_INDEX = null;
-const BUILTIN_CAPABILITY_PROVIDERS = Object.freeze({
-  "runtime.actions": Object.freeze(["@jskit-ai/kernel"])
-});
-const SETTINGS_FIELDS_CONTRACT_TARGETS = Object.freeze({
-  "packages/main/src/shared/resources/consoleSettingsFields.js": Object.freeze({
-    contractId: "users.settings-fields.console.v1",
-    marker: "@jskit-contract users.settings-fields.console.v1",
-    requiredSnippets: Object.freeze([
-      "defineField",
-      "resetConsoleSettingsFields"
-    ])
-  }),
-  "packages/main/src/shared/resources/workspaceSettingsFields.js": Object.freeze({
-    contractId: "users.settings-fields.workspace.v1",
-    marker: "@jskit-contract users.settings-fields.workspace.v1",
-    requiredSnippets: Object.freeze([
-      "defineField",
-      "resetWorkspaceSettingsFields"
-    ])
-  })
-});
-
-function normalizeMutationExtension(value) {
-  const extension = String(value || "").trim();
-  if (!extension) {
-    return "";
-  }
-  if (extension.startsWith(".")) {
-    return extension;
-  }
-  return `.${extension}`;
-}
-
-function normalizeTemplateContextRecord(value) {
-  const record = ensureObject(value);
-  const entrypoint = String(record.entrypoint || "").trim();
-  const exportName = String(record.export || "").trim();
-  if (!entrypoint && !exportName) {
-    return null;
-  }
-
-  return Object.freeze({
-    entrypoint,
-    export: exportName || "buildTemplateContext"
-  });
-}
-
-function normalizeFileMutationRecord(value) {
-  const record = ensureObject(value);
-  const op = String(record.op || "copy-file").trim().toLowerCase() || "copy-file";
-  return {
-    op,
-    from: String(record.from || "").trim(),
-    to: String(record.to || "").trim(),
-    toSurface: String(record.toSurface || "").trim(),
-    toSurfacePath: String(record.toSurfacePath || "").trim(),
-    toSurfaceRoot: record.toSurfaceRoot === true,
-    toDir: String(record.toDir || "").trim(),
-    extension: normalizeMutationExtension(record.extension),
-    preserveOnRemove: record.preserveOnRemove === true,
-    id: String(record.id || "").trim(),
-    category: String(record.category || "").trim(),
-    reason: String(record.reason || "").trim(),
-    templateContext: normalizeTemplateContextRecord(record.templateContext),
-    when: normalizeMutationWhen(record.when)
-  };
-}
-
-function normalizeMutationWhen(value) {
-  const source = ensureObject(value);
-  const option = String(source.option || "").trim();
-  const config = String(source.config || "").trim();
-  const equals = String(source.equals || "").trim();
-  const notEquals = String(source.notEquals || "").trim();
-  const includes = ensureArray(source.in).map((entry) => String(entry || "").trim()).filter(Boolean);
-  const excludes = ensureArray(source.notIn).map((entry) => String(entry || "").trim()).filter(Boolean);
-
-  if (!option && !config) {
-    return null;
-  }
-
-  return {
-    option,
-    config,
-    equals,
-    notEquals,
-    includes,
-    excludes
-  };
-}
-
-function readObjectPath(source, rawPath) {
-  const valueSource = ensureObject(source);
-  const fullPath = String(rawPath || "").trim();
-  if (!fullPath) {
-    return undefined;
-  }
-
-  if (Object.prototype.hasOwnProperty.call(valueSource, fullPath)) {
-    return valueSource[fullPath];
-  }
-
-  const segments = fullPath
-    .split(".")
-    .map((entry) => String(entry || "").trim())
-    .filter(Boolean);
-  if (segments.length < 1) {
-    return undefined;
-  }
-
-  let cursor = valueSource;
-  for (const segment of segments) {
-    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) {
-      return undefined;
-    }
-    if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {
-      return undefined;
-    }
-    cursor = cursor[segment];
-  }
-
-  return cursor;
-}
-
-function normalizeWhenSourceValue(value) {
-  if (value == null) {
-    return "";
-  }
-  if (typeof value === "string") {
-    return value.trim();
-  }
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value).trim();
-  }
-  return "";
-}
-
-function normalizeWhenComparisonValue(value) {
-  const normalizedValue = normalizeWhenSourceValue(value);
-  if (!normalizedValue.includes(",")) {
-    return normalizedValue;
-  }
-
-  return normalizedValue
-    .split(",")
-    .map((entry) => String(entry || "").trim())
-    .filter(Boolean)
-    .join(",");
-}
-
-function splitWhenComparisonTokens(value) {
-  return normalizeWhenComparisonValue(value)
-    .split(",")
-    .map((entry) => String(entry || "").trim())
-    .filter(Boolean);
-}
-
-function matchesWhenComparisonValue(optionValue, optionTokens, expectedValue) {
-  const expected = normalizeWhenComparisonValue(expectedValue);
-  if (!expected) {
-    return false;
-  }
-
-  const expectedTokens = splitWhenComparisonTokens(expected);
-  if (expectedTokens.length > 1) {
-    return optionValue === expected;
-  }
-
-  if (optionTokens.length > 1) {
-    return optionTokens.includes(expectedTokens[0]);
-  }
-
-  return optionValue === expectedTokens[0];
-}
-
-function resolveWhenConfigValue(configContext = {}, configPath = "") {
-  const normalizedPath = String(configPath || "").trim();
-  if (!normalizedPath) {
-    return "";
-  }
-
-  const publicConfig = ensureObject(configContext.public);
-  const serverConfig = ensureObject(configContext.server);
-  const mergedConfig = ensureObject(configContext.merged);
-  if (normalizedPath === "public") {
-    return publicConfig;
-  }
-  if (normalizedPath === "server") {
-    return serverConfig;
-  }
-  if (normalizedPath === "merged") {
-    return mergedConfig;
-  }
-
-  if (normalizedPath.startsWith("public.")) {
-    return readObjectPath(publicConfig, normalizedPath.slice("public.".length));
-  }
-  if (normalizedPath.startsWith("server.")) {
-    return readObjectPath(serverConfig, normalizedPath.slice("server.".length));
-  }
-  if (normalizedPath.startsWith("merged.")) {
-    return readObjectPath(mergedConfig, normalizedPath.slice("merged.".length));
-  }
-
-  return readObjectPath(mergedConfig, normalizedPath);
-}
-
-function shouldApplyMutationWhen(
-  when,
-  {
-    options = {},
-    configContext = {},
-    packageId = "",
-    mutationContext = "mutation"
-  } = {}
-) {
-  if (!when || typeof when !== "object") {
-    return true;
-  }
-
-  const optionName = String(when.option || "").trim();
-  const configPath = String(when.config || "").trim();
-  if (!optionName && !configPath) {
-    return true;
-  }
-  if (optionName && configPath) {
-    const packagePrefix = packageId ? `${packageId} ` : "";
-    throw createCliError(
-      `Invalid ${packagePrefix}${mutationContext}: when cannot declare both "option" and "config".`
-    );
-  }
-
-  const sourceValue = optionName
-    ? readObjectPath(options, optionName)
-    : resolveWhenConfigValue(configContext, configPath);
-  const optionValue = normalizeWhenComparisonValue(sourceValue);
-  const optionTokens = splitWhenComparisonTokens(optionValue);
-  const equals = normalizeWhenComparisonValue(when.equals);
-  const notEquals = normalizeWhenComparisonValue(when.notEquals);
-  const includes = ensureArray(when.includes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
-  const excludes = ensureArray(when.excludes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
-
-  if (equals && optionValue !== equals) {
-    return false;
-  }
-  if (notEquals && optionValue === notEquals) {
-    return false;
-  }
-  if (includes.length > 0 && !includes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
-    return false;
-  }
-  if (excludes.length > 0 && excludes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
-    return false;
-  }
-
-  return true;
-}
-
-function buildFileWriteGroups(fileMutations, { packageId = "" } = {}) {
-  const groups = [];
-  const groupsByKey = new Map();
-
-  for (const mutation of ensureArray(fileMutations)) {
-    const normalized = normalizeFileMutationRecord(mutation);
-    if (normalized.op === "install-migration") {
-      if (!normalized.from || !normalized.id) {
-        continue;
-      }
-    } else if (!normalized.from || (!normalized.to && !normalized.toSurface)) {
-      continue;
-    }
-
-    const destinationLabel = normalized.to
-      ? normalized.to
-      : normalized.toSurfaceRoot
-        ? `surface:${normalized.toSurface}.root`
-        : `surface:${normalized.toSurface}/${normalized.toSurfacePath}`;
-
-    const key = normalized.id
-      ? `id:${normalized.id}`
-      : normalized.category || normalized.reason
-        ? `meta:${normalized.category}::${normalized.reason}`
-        : `path:${destinationLabel}`;
-
-    let group = groupsByKey.get(key);
-    if (!group) {
-      group = {
-        id: normalized.id,
-        category: normalized.category,
-        reason: normalized.reason,
-        files: []
-      };
-      groupsByKey.set(key, group);
-      groups.push(group);
-    } else {
-      if (!group.category && normalized.category) {
-        group.category = normalized.category;
-      }
-      if (!group.reason && normalized.reason) {
-        group.reason = normalized.reason;
-      }
-    }
-
-    if (normalized.op === "install-migration") {
-      const toDir = normalized.toDir || "migrations";
-      const extension = normalized.extension || ".cjs";
-      group.files.push({
-        from: normalized.from,
-        to: buildManagedMigrationRelativePathLabel({
-          toDir,
-          packageId,
-          migrationId: normalized.id,
-          extension
-        })
-      });
-      continue;
-    }
-
-    group.files.push({
-      from: normalized.from,
-      to: destinationLabel
-    });
-  }
-
-  return groups;
-}
-
-function normalizeRelativePath(fromRoot, absolutePath) {
-  return path.relative(fromRoot, absolutePath).split(path.sep).join("/");
-}
-
-function hashBuffer(buffer) {
-  return createHash("sha256").update(buffer).digest("hex");
-}
-
-function normalizeMigrationExtension(value = "", fallback = ".cjs") {
-  const normalizedFallback = String(fallback || ".cjs").trim() || ".cjs";
-  const raw = String(value || "").trim();
-  const candidate = raw ? (raw.startsWith(".") ? raw : `.${raw}`) : normalizedFallback;
-  if (!/^\.[a-z0-9]+$/i.test(candidate)) {
-    throw createCliError(`Invalid install-migration extension: ${candidate}`);
-  }
-  return candidate.toLowerCase();
-}
-
-const MIGRATION_ID_PATTERN = /^[a-z0-9._-]+$/;
-
-function normalizeMigrationId(value, packageId) {
-  const normalized = String(value || "").trim();
-  if (!normalized) {
-    throw createCliError(`Invalid install-migration mutation in ${packageId}: \"id\" is required.`);
-  }
-  if (!MIGRATION_ID_PATTERN.test(normalized)) {
-    throw createCliError(
-      `Invalid install-migration mutation in ${packageId}: "id" must match ${MIGRATION_ID_PATTERN.source}.`
-    );
-  }
-  return normalized;
-}
-
-function resolveAppRelativePathWithinRoot(appRoot, relativePath, contextLabel = "path") {
-  const normalized = normalizeRelativePosixPath(String(relativePath || "").trim());
-  if (!normalized) {
-    throw createCliError(`Invalid ${contextLabel}: path is required.`);
-  }
-  const segments = normalized.split("/");
-  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
-    throw createCliError(`Invalid ${contextLabel}: path must be a safe relative path.`);
-  }
-
-  const appRootAbsolute = path.resolve(appRoot);
-  const absolutePath = path.resolve(appRootAbsolute, normalized);
-  const relativeFromRoot = path.relative(appRootAbsolute, absolutePath);
-  if (
-    relativeFromRoot === ".." ||
-    relativeFromRoot.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(relativeFromRoot)
-  ) {
-    throw createCliError(`Invalid ${contextLabel}: path must stay within app root.`);
-  }
-
-  return {
-    relativePath: normalized,
-    absolutePath
-  };
-}
-
-function normalizeMigrationDirectory(value, packageId) {
-  const normalized = normalizeRelativePosixPath(String(value || "").trim() || "migrations");
-  if (!normalized) {
-    throw createCliError(`Invalid install-migration mutation in ${packageId}: "toDir" cannot be empty.`);
-  }
-
-  const segments = normalized.split("/");
-  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
-    throw createCliError(`Invalid install-migration mutation in ${packageId}: "toDir" must be a safe relative path.`);
-  }
-
-  return segments.join("/");
-}
-
-function formatMigrationTimestamp(date = new Date()) {
-  const source = date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
-  const year = String(source.getUTCFullYear()).padStart(4, "0");
-  const month = String(source.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(source.getUTCDate()).padStart(2, "0");
-  const hour = String(source.getUTCHours()).padStart(2, "0");
-  const minute = String(source.getUTCMinutes()).padStart(2, "0");
-  const second = String(source.getUTCSeconds()).padStart(2, "0");
-  return `${year}${month}${day}${hour}${minute}${second}`;
-}
-
-function buildManagedMigrationFileName({ packageId = "", migrationId = "", extension = ".cjs", timestamp = "" } = {}) {
-  const normalizedMigrationId = normalizeMigrationId(migrationId, packageId);
-  const normalizedExtension = normalizeMigrationExtension(extension, ".cjs");
-  const normalizedTimestamp = String(timestamp || "").trim();
-  if (!/^\d{14}$/.test(normalizedTimestamp)) {
-    throw createCliError(
-      `Invalid install-migration mutation in ${packageId}: timestamp must be a 14-digit UTC string (YYYYMMDDHHmmss).`
-    );
-  }
-  return `${normalizedTimestamp}_${normalizedMigrationId}${normalizedExtension}`;
-}
-
-function buildManagedMigrationRelativePath({ toDir = "migrations", packageId = "", migrationId = "", extension = ".cjs", timestamp = "" } = {}) {
-  const normalizedDirectory = normalizeMigrationDirectory(toDir, packageId);
-  const fileName = buildManagedMigrationFileName({
-    packageId,
-    migrationId,
-    extension,
-    timestamp
-  });
-  return path.posix.join(normalizedDirectory, fileName);
-}
-
-function buildManagedMigrationRelativePathLabel({ toDir = "migrations", migrationId = "", extension = ".cjs" } = {}) {
-  const directory = normalizeRelativePosixPath(String(toDir || "").trim() || "migrations") || "migrations";
-  const id = String(migrationId || "<migration-id>").trim() || "<migration-id>";
-  const rawExtension = String(extension || ".cjs").trim() || ".cjs";
-  const ext = rawExtension.startsWith(".") ? rawExtension : `.${rawExtension}`;
-  return `${directory}/<timestamp>_${id}${ext}`.replace(/\/{2,}/g, "/");
-}
-
-async function findExistingManagedMigrationPathById({
-  appRoot,
-  toDir = "migrations",
-  packageId = "",
-  migrationId = "",
-  extension = ".cjs"
-} = {}) {
-  const normalizedDirectory = normalizeMigrationDirectory(toDir, packageId);
-  const resolvedDirectory = resolveAppRelativePathWithinRoot(
-    appRoot,
-    normalizedDirectory,
-    `${packageId} migration directory for ${migrationId}`
-  );
-  if (!(await fileExists(resolvedDirectory.absolutePath))) {
-    return null;
-  }
-
-  const normalizedMigrationId = normalizeMigrationId(migrationId, packageId);
-  const normalizedExtension = normalizeMigrationExtension(extension, ".cjs");
-  const suffix = `_${normalizedMigrationId}${normalizedExtension}`;
-  const entries = await readdir(resolvedDirectory.absolutePath, { withFileTypes: true }).catch(() => []);
-  const matches = [];
-
-  for (const entry of entries) {
-    if (!entry.isFile()) {
-      continue;
-    }
-    const fileName = String(entry.name || "").trim();
-    if (!fileName.endsWith(suffix)) {
-      continue;
-    }
-    const timestamp = fileName.slice(0, fileName.length - suffix.length);
-    if (!/^\d{14}$/.test(timestamp)) {
-      continue;
-    }
-    matches.push({
-      relativePath: path.posix.join(resolvedDirectory.relativePath, fileName),
-      absolutePath: path.join(resolvedDirectory.absolutePath, fileName)
-    });
-  }
-
-  matches.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
-  if (matches.length > 1) {
-    throw createCliError(
-      `${packageId}: found multiple migration files for ${normalizedMigrationId} in ${resolvedDirectory.relativePath}. Keep one file for this migration id.`
-    );
-  }
-  return matches[0] || null;
-}
-
-function upsertManagedMigrationRecord(managedMigrations, record) {
-  const records = ensureArray(managedMigrations);
-  const normalizedId = String(ensureObject(record).id || "").trim();
-  if (!normalizedId) {
-    return;
-  }
-
-  const nextRecord = {
-    ...ensureObject(record),
-    id: normalizedId
-  };
-  const existingIndex = records.findIndex(
-    (entry) => String(ensureObject(entry).id || "").trim() === normalizedId
-  );
-  if (existingIndex >= 0) {
-    records[existingIndex] = nextRecord;
-    return;
-  }
-
-  records.push(nextRecord);
-}
-
-async function fileExists(absolutePath) {
-  try {
-    await access(absolutePath, fsConstants.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function readJsonFile(absolutePath) {
-  const source = await readFile(absolutePath, "utf8");
-  return JSON.parse(source);
-}
-
-async function writeJsonFile(absolutePath, value) {
-  await mkdir(path.dirname(absolutePath), { recursive: true });
-  await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-}
-
-async function readFileBufferIfExists(absolutePath) {
-  if (!(await fileExists(absolutePath))) {
-    return {
-      exists: false,
-      buffer: Buffer.alloc(0)
-    };
-  }
-
-  return {
-    exists: true,
-    buffer: await readFile(absolutePath)
-  };
-}
-
-async function loadAppConfigModuleConfig(appRoot, relativePath) {
-  const absolutePath = path.join(appRoot, relativePath);
-  if (!(await fileExists(absolutePath))) {
-    return {};
-  }
-
-  let moduleNamespace = null;
-  try {
-    moduleNamespace = await import(`${pathToFileURL(absolutePath).href}?t=${Date.now()}_${Math.random()}`);
-  } catch (error) {
-    throw createCliError(
-      `Unable to load ${relativePath}: ${String(error?.message || error || "unknown error")}`
-    );
-  }
-
-  const defaultExport = ensureObject(moduleNamespace?.default);
-  const fromNamedExport = ensureObject(moduleNamespace?.config);
-  const fromDefaultConfig = ensureObject(defaultExport?.config);
-
-  if (Object.keys(fromNamedExport).length > 0) {
-    return fromNamedExport;
-  }
-  if (Object.keys(fromDefaultConfig).length > 0) {
-    return fromDefaultConfig;
-  }
-  return defaultExport;
-}
-
-async function loadMutationWhenConfigContext(appRoot) {
-  const publicConfig = await loadAppConfigModuleConfig(appRoot, PUBLIC_APP_CONFIG_RELATIVE_PATH);
-  const serverConfig = await loadAppConfigModuleConfig(appRoot, SERVER_APP_CONFIG_RELATIVE_PATH);
-  return {
-    public: publicConfig,
-    server: serverConfig,
-    merged: {
-      ...publicConfig,
-      ...serverConfig
-    }
-  };
-}
-
-function createEmptyViteDevProxyConfig() {
-  return Object.freeze({
-    version: VITE_DEV_PROXY_CONFIG_VERSION,
-    entries: Object.freeze([])
-  });
-}
-
-function normalizeViteDevProxyPath(value = "", { context = "vite proxy entry" } = {}) {
-  const normalizedPath = String(value || "").trim();
-  if (!normalizedPath || !normalizedPath.startsWith("/")) {
-    throw createCliError(`${context} requires "path" starting with "/".`);
-  }
-  return normalizedPath.replace(/\/{2,}/g, "/");
-}
-
-function normalizeViteDevProxyEntry(value = {}, { context = "vite proxy entry" } = {}) {
-  const source = ensureObject(value);
-  const packageId = String(source.packageId || "").trim();
-  const entryId = String(source.id || "").trim();
-  if (!packageId) {
-    throw createCliError(`${context} requires "packageId".`);
-  }
-  if (!entryId) {
-    throw createCliError(`${context} requires "id".`);
-  }
-
-  const normalized = {
-    packageId,
-    id: entryId,
-    path: normalizeViteDevProxyPath(source.path, {
-      context: `${context} (${packageId}:${entryId})`
-    })
-  };
-
-  const target = String(source.target || "").trim();
-  if (target) {
-    normalized.target = target;
-  }
-  if (Object.prototype.hasOwnProperty.call(source, "changeOrigin")) {
-    normalized.changeOrigin = source.changeOrigin === true;
-  }
-  if (Object.prototype.hasOwnProperty.call(source, "ws")) {
-    normalized.ws = source.ws === true;
-  }
-
-  return Object.freeze(normalized);
-}
-
-function normalizeViteDevProxyConfig(value = {}, { context = "vite proxy config" } = {}) {
-  const source = ensureObject(value);
-  const normalizedEntries = [];
-  const seenEntryKeys = new Set();
-  const seenPaths = new Set();
-
-  for (const [index, entry] of ensureArray(source.entries).entries()) {
-    const normalizedEntry = normalizeViteDevProxyEntry(entry, {
-      context: `${context}.entries[${index}]`
-    });
-    const entryKey = `${normalizedEntry.packageId}::${normalizedEntry.id}`;
-    if (seenEntryKeys.has(entryKey)) {
-      throw createCliError(`${context} has duplicate entry "${entryKey}".`);
-    }
-    if (seenPaths.has(normalizedEntry.path)) {
-      throw createCliError(`${context} has duplicate path "${normalizedEntry.path}".`);
-    }
-
-    seenEntryKeys.add(entryKey);
-    seenPaths.add(normalizedEntry.path);
-    normalizedEntries.push(normalizedEntry);
-  }
-
-  normalizedEntries.sort((left, right) => {
-    const pathDiff = left.path.localeCompare(right.path);
-    if (pathDiff !== 0) {
-      return pathDiff;
-    }
-    const packageDiff = left.packageId.localeCompare(right.packageId);
-    if (packageDiff !== 0) {
-      return packageDiff;
-    }
-    return left.id.localeCompare(right.id);
-  });
-
-  return Object.freeze({
-    version: VITE_DEV_PROXY_CONFIG_VERSION,
-    entries: Object.freeze(normalizedEntries)
-  });
-}
-
-function resolveViteDevProxyConfigAbsolutePath(appRoot) {
-  return path.join(appRoot, VITE_DEV_PROXY_CONFIG_RELATIVE_PATH);
-}
-
-async function loadViteDevProxyConfig(appRoot, { context = "vite proxy config" } = {}) {
-  const absolutePath = resolveViteDevProxyConfigAbsolutePath(appRoot);
-  const existing = await readFileBufferIfExists(absolutePath);
-  if (!existing.exists) {
-    return Object.freeze({
-      absolutePath,
-      exists: false,
-      config: createEmptyViteDevProxyConfig()
-    });
-  }
-
-  const relativePath = normalizeRelativePath(appRoot, absolutePath);
-  let parsed = {};
-  try {
-    parsed = JSON.parse(existing.buffer.toString("utf8"));
-  } catch {
-    throw createCliError(`Invalid ${context} at ${relativePath}: expected valid JSON.`);
-  }
-
-  return Object.freeze({
-    absolutePath,
-    exists: true,
-    config: normalizeViteDevProxyConfig(parsed, {
-      context: `${context} (${relativePath})`
-    })
-  });
-}
-
-async function writeViteDevProxyConfig(appRoot, config = {}, touchedFiles = null) {
-  const absolutePath = resolveViteDevProxyConfigAbsolutePath(appRoot);
-  const relativePath = normalizeRelativePath(appRoot, absolutePath);
-  const normalizedConfig = normalizeViteDevProxyConfig(config);
-
-  if (normalizedConfig.entries.length < 1) {
-    if (await fileExists(absolutePath)) {
-      await rm(absolutePath);
-      if (touchedFiles && typeof touchedFiles.add === "function") {
-        touchedFiles.add(relativePath);
-      }
-    }
-    return;
-  }
-
-  await writeJsonFile(absolutePath, normalizedConfig);
-  if (touchedFiles && typeof touchedFiles.add === "function") {
-    touchedFiles.add(relativePath);
-  }
-}
-
-function normalizeViteProxyMutationRecord(value = {}) {
-  const source = ensureObject(value);
-  const changeOrigin = Object.prototype.hasOwnProperty.call(source, "changeOrigin")
-    ? source.changeOrigin === true
-    : undefined;
-  const ws = Object.prototype.hasOwnProperty.call(source, "ws") ? source.ws === true : undefined;
-  return Object.freeze({
-    id: String(source.id || "").trim(),
-    path: String(source.path || "").trim(),
-    target: String(source.target || "").trim(),
-    changeOrigin,
-    ws,
-    when: normalizeMutationWhen(source.when)
-  });
-}
-
-async function applyViteMutations(packageEntry, appRoot, viteMutations, options, managedVite, touchedFiles) {
-  const mutations = ensureArray(ensureObject(viteMutations).proxy).map((entry) => normalizeViteProxyMutationRecord(entry));
-  if (mutations.length < 1) {
-    return;
-  }
-
-  const { config: currentConfig } = await loadViteDevProxyConfig(appRoot, {
-    context: `vite proxy config for ${packageEntry.packageId}`
-  });
-  const nextEntries = [...currentConfig.entries];
-  let changed = false;
-
-  for (const mutation of mutations) {
-    const configContext = mutation.when?.config ? await loadMutationWhenConfigContext(appRoot) : {};
-    if (
-      !shouldApplyMutationWhen(mutation.when, {
-        options,
-        configContext,
-        packageId: packageEntry.packageId,
-        mutationContext: "vite proxy mutation"
-      })
-    ) {
-      continue;
-    }
-
-    const normalizedId = interpolateOptionValue(
-      mutation.id,
-      options,
-      packageEntry.packageId,
-      "mutations.vite.proxy.id"
-    );
-    if (!normalizedId) {
-      throw createCliError(`Invalid vite proxy mutation in ${packageEntry.packageId}: "id" is required.`);
-    }
-
-    const normalizedPath = normalizeViteDevProxyPath(
-      interpolateOptionValue(
-        mutation.path,
-        options,
-        packageEntry.packageId,
-        `mutations.vite.proxy.${normalizedId}.path`
-      ),
-      {
-        context: `Invalid vite proxy mutation in ${packageEntry.packageId} (${normalizedId})`
-      }
-    );
-
-    const normalizedTarget = mutation.target
-      ? String(
-          interpolateOptionValue(
-            mutation.target,
-            options,
-            packageEntry.packageId,
-            `mutations.vite.proxy.${normalizedId}.target`
-          ) || ""
-        ).trim()
-      : "";
-
-    for (let index = nextEntries.length - 1; index >= 0; index -= 1) {
-      const entry = nextEntries[index];
-      if (entry.packageId === packageEntry.packageId && entry.id === normalizedId) {
-        nextEntries.splice(index, 1);
-        changed = true;
-      }
-    }
-
-    const conflictingEntry = nextEntries.find((entry) => entry.path === normalizedPath);
-    if (conflictingEntry) {
-      throw createCliError(
-        `Invalid vite proxy mutation in ${packageEntry.packageId}: path "${normalizedPath}" conflicts with ${conflictingEntry.packageId} (${conflictingEntry.id}).`
-      );
-    }
-
-    nextEntries.push(
-      Object.freeze({
-        packageId: packageEntry.packageId,
-        id: normalizedId,
-        path: normalizedPath,
-        ...(normalizedTarget ? { target: normalizedTarget } : {}),
-        ...(typeof mutation.changeOrigin === "boolean" ? { changeOrigin: mutation.changeOrigin } : {}),
-        ...(typeof mutation.ws === "boolean" ? { ws: mutation.ws } : {})
-      })
-    );
-    changed = true;
-
-    const mutationKey = `${normalizedPath}::${normalizedId}`;
-    managedVite[mutationKey] = Object.freeze({
-      op: "upsert-vite-proxy",
-      id: normalizedId,
-      path: normalizedPath
-    });
-  }
-
-  if (!changed) {
-    return;
-  }
-
-  const nextConfig = normalizeViteDevProxyConfig(
-    {
-      entries: nextEntries
-    },
-    {
-      context: `vite proxy config for ${packageEntry.packageId}`
-    }
-  );
-
-  if (JSON.stringify(currentConfig) === JSON.stringify(nextConfig)) {
-    return;
-  }
-
-  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles);
-}
-
-async function removeManagedViteProxyEntries({ appRoot, packageId, managedViteChanges = {}, touchedFiles = null } = {}) {
-  const managedChanges = Object.values(ensureObject(managedViteChanges))
-    .map((entry) => ensureObject(entry))
-    .filter((entry) => String(entry.op || "").trim() === "upsert-vite-proxy");
-  if (managedChanges.length < 1) {
-    return;
-  }
-
-  const { exists, config: currentConfig } = await loadViteDevProxyConfig(appRoot, {
-    context: `vite proxy config while removing ${packageId}`
-  });
-  if (!exists) {
-    return;
-  }
-
-  let nextEntries = [...currentConfig.entries];
-  for (const change of managedChanges) {
-    const changeId = String(change.id || "").trim();
-    const changePath = String(change.path || "").trim();
-    if (!changeId) {
-      continue;
-    }
-    nextEntries = nextEntries.filter((entry) => {
-      if (entry.packageId !== packageId || entry.id !== changeId) {
-        return true;
-      }
-      if (changePath && entry.path !== changePath) {
-        return true;
-      }
-      return false;
-    });
-  }
-
-  const nextConfig = normalizeViteDevProxyConfig(
-    {
-      entries: nextEntries
-    },
-    {
-      context: `vite proxy config while removing ${packageId}`
-    }
-  );
-  if (JSON.stringify(currentConfig) === JSON.stringify(nextConfig)) {
-    return;
-  }
-
-  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles);
-}
-
-async function resolveAppRootFromCwd(cwd) {
-  const startDirectory = path.resolve(String(cwd || process.cwd()));
-  let currentDirectory = startDirectory;
-
-  while (true) {
-    const packageJsonPath = path.join(currentDirectory, "package.json");
-    if (await fileExists(packageJsonPath)) {
-      return currentDirectory;
-    }
-
-    const parentDirectory = path.dirname(currentDirectory);
-    if (parentDirectory === currentDirectory) {
-      throw createCliError(
-        `Could not locate package.json starting from ${startDirectory}. Run jskit from an app directory (or a child directory of one).`
-      );
-    }
-    currentDirectory = parentDirectory;
-  }
-}
-
-async function loadAppPackageJson(appRoot) {
-  const packageJsonPath = path.join(appRoot, "package.json");
-  const packageJson = await readJsonFile(packageJsonPath);
-  return {
-    packageJsonPath,
-    packageJson
-  };
-}
-
-function createDefaultLock() {
-  return {
-    lockVersion: LOCK_VERSION,
-    installedPackages: {}
-  };
-}
-
-async function loadLockFile(appRoot) {
-  const lockPath = path.join(appRoot, LOCK_RELATIVE_PATH);
-  if (!(await fileExists(lockPath))) {
-    return {
-      lockPath,
-      lock: createDefaultLock()
-    };
-  }
-
-  const lock = await readJsonFile(lockPath);
-  const installedPackages = ensureObject(lock?.installedPackages);
-  const lockVersion = Number(lock?.lockVersion);
-  return {
-    lockPath,
-    lock: {
-      lockVersion: Number.isFinite(lockVersion) && lockVersion > 0 ? lockVersion : LOCK_VERSION,
-      installedPackages
-    }
-  };
-}
-
-function createManagedPackageJsonChange(hadPrevious, previousValue, value) {
-  return {
-    hadPrevious: Boolean(hadPrevious),
-    previousValue: hadPrevious ? String(previousValue) : "",
-    value: String(value)
-  };
-}
-
-function ensurePackageJsonSection(packageJson, sectionName) {
-  const sectionValue = ensureObject(packageJson[sectionName]);
-  packageJson[sectionName] = sectionValue;
-  return sectionValue;
-}
-
-function applyPackageJsonField(packageJson, sectionName, key, value) {
-  const section = ensurePackageJsonSection(packageJson, sectionName);
-  const nextValue = String(value);
-  const hadPrevious = Object.prototype.hasOwnProperty.call(section, key);
-  const previousValue = hadPrevious ? String(section[key]) : "";
-  const changed = !hadPrevious || previousValue !== nextValue;
-  section[key] = nextValue;
-  return {
-    changed,
-    managed: createManagedPackageJsonChange(hadPrevious, previousValue, nextValue)
-  };
-}
-
-function removePackageJsonField(packageJson, sectionName, key) {
-  const section = ensureObject(packageJson[sectionName]);
-  if (!Object.prototype.hasOwnProperty.call(section, key)) {
-    return false;
-  }
-  delete section[key];
-  if (Object.keys(section).length < 1) {
-    delete packageJson[sectionName];
-  }
-  return true;
-}
-
-function restorePackageJsonField(packageJson, sectionName, key, managedChange) {
-  const section = ensurePackageJsonSection(packageJson, sectionName);
-  const currentValue = Object.prototype.hasOwnProperty.call(section, key) ? String(section[key]) : "";
-  if (currentValue !== String(managedChange?.value || "")) {
-    return false;
-  }
-
-  if (managedChange?.hadPrevious) {
-    section[key] = String(managedChange.previousValue || "");
-  } else {
-    delete section[key];
-  }
-  return true;
-}
-
-function parseEnvLineValue(line, key) {
-  const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
-  if (!pattern.test(line)) {
-    return null;
-  }
-  const index = line.indexOf("=");
-  if (index === -1) {
-    return "";
-  }
-  return line.slice(index + 1);
-}
-
-function upsertEnvValue(content, key, value) {
-  const lines = String(content || "").split(/\r?\n/);
-  const lookupPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
-  let index = -1;
-
-  for (let cursor = 0; cursor < lines.length; cursor += 1) {
-    if (lookupPattern.test(lines[cursor])) {
-      index = cursor;
-      break;
-    }
-  }
-
-  const hadPrevious = index >= 0;
-  const previousValue = hadPrevious ? String(parseEnvLineValue(lines[index], key) || "") : "";
-  const nextLine = `${key}=${value}`;
-
-  if (hadPrevious) {
-    lines[index] = nextLine;
-  } else {
-    if (lines.length === 1 && lines[0] === "") {
-      lines[0] = nextLine;
-    } else {
-      lines.push(nextLine);
-    }
-  }
-
-  const normalized = `${lines.join("\n").replace(/\n+$/, "")}\n`;
-  return {
-    hadPrevious,
-    previousValue,
-    content: normalized
-  };
-}
-
-function removeEnvValue(content, key, expectedValue, previous) {
-  const lines = String(content || "").split(/\r?\n/);
-  const lookupPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
-  let index = -1;
-
-  for (let cursor = 0; cursor < lines.length; cursor += 1) {
-    if (lookupPattern.test(lines[cursor])) {
-      index = cursor;
-      break;
-    }
-  }
-
-  if (index < 0) {
-    return {
-      changed: false,
-      content: content
-    };
-  }
-
-  const currentValue = String(parseEnvLineValue(lines[index], key) || "");
-  if (currentValue !== String(expectedValue || "")) {
-    return {
-      changed: false,
-      content: content
-    };
-  }
-
-  if (previous?.hadPrevious) {
-    lines[index] = `${key}=${String(previous.previousValue || "")}`;
-  } else {
-    lines.splice(index, 1);
-  }
-
-  const normalized = `${lines.join("\n").replace(/\n+$/, "")}\n`;
-  return {
-    changed: true,
-    content: normalized
-  };
-}
-
-function normalizePackageKind(rawValue, descriptorPath) {
-  const normalized = String(rawValue || "").trim().toLowerCase();
-  if (!normalized) {
-    throw createCliError(
-      `Invalid package descriptor at ${descriptorPath}: missing kind (expected ${PACKAGE_KINDS.join(" | ")}).`
-    );
-  }
-  if (!PACKAGE_KINDS.includes(normalized)) {
-    throw createCliError(
-      `Invalid package descriptor at ${descriptorPath}: kind must be one of: ${PACKAGE_KINDS.join(", ")}.`
-    );
-  }
-  return normalized;
-}
-
-function validateInstallMigrationMutationShape(descriptor, descriptorPath) {
-  const packageId = String(ensureObject(descriptor).packageId || "").trim() || "unknown-package";
-  const mutations = ensureObject(ensureObject(descriptor).mutations);
-  const files = ensureArray(mutations.files);
-  for (const fileMutation of files) {
-    const normalized = normalizeFileMutationRecord(fileMutation);
-    if (normalized.op !== "install-migration") {
-      continue;
-    }
-    if (!normalized.from) {
-      throw createCliError(
-        `Invalid package descriptor at ${descriptorPath}: install-migration in ${packageId} requires "from".`
-      );
-    }
-    if (!normalized.id) {
-      throw createCliError(
-        `Invalid package descriptor at ${descriptorPath}: install-migration in ${packageId} requires "id".`
-      );
-    }
-  }
-}
-
-function validatePackageDescriptorShape(descriptor, descriptorPath) {
-  const normalized = ensureObject(descriptor);
-  const packageId = String(normalized.packageId || "").trim();
-  const version = String(normalized.version || "").trim();
-
-  if (!packageId.startsWith("@jskit-ai/")) {
-    throw createCliError(`Invalid package descriptor at ${descriptorPath}: packageId must start with @jskit-ai/.`);
-  }
-  if (!version) {
-    throw createCliError(`Invalid package descriptor at ${descriptorPath}: missing version.`);
-  }
-
-  const runtime = ensureObject(normalized.runtime);
-  const server = ensureObject(runtime.server);
-  const client = ensureObject(runtime.client);
-  const hasServerProviders = Array.isArray(server.providers);
-  const hasClientProviders = Array.isArray(client.providers);
-  if (!hasServerProviders && !hasClientProviders) {
-    throw createCliError(
-      `Invalid package descriptor at ${descriptorPath}: runtime.server.providers or runtime.client.providers must be declared.`
-    );
-  }
-
-  validateInstallMigrationMutationShape(normalized, descriptorPath);
-
-  return {
-    ...normalized,
-    kind: normalizePackageKind(normalized.kind, descriptorPath)
-  };
-}
-
-function isGeneratorPackageEntry(packageEntry) {
-  const descriptor = ensureObject(packageEntry?.descriptor);
-  return String(descriptor.kind || "").trim().toLowerCase() === PACKAGE_KIND_GENERATOR;
-}
-
-function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { expectedPackageId = "", fallbackVersion = "" } = {}) {
-  const normalized = ensureObject(descriptor);
-  const packageId = String(normalized.packageId || "").trim();
-  const version = String(normalized.version || "").trim() || String(fallbackVersion || "").trim();
-
-  if (!packageId) {
-    throw createCliError(`Invalid app-local package descriptor at ${descriptorPath}: missing packageId.`);
-  }
-  if (expectedPackageId && packageId !== expectedPackageId) {
-    throw createCliError(
-      `Descriptor/package mismatch at ${descriptorPath}: package.descriptor.mjs has ${packageId} but package.json has ${expectedPackageId}.`
-    );
-  }
-  if (!version) {
-    throw createCliError(`Invalid app-local package descriptor at ${descriptorPath}: missing version.`);
-  }
-
-  validateInstallMigrationMutationShape(normalized, descriptorPath);
-
-  return {
-    ...normalized,
-    packageId,
-    version,
-    kind: normalizePackageKind(normalized.kind, descriptorPath)
-  };
-}
-
-function createPackageEntry({
-  packageId,
-  version,
-  descriptor,
-  rootDir = "",
-  relativeDir = "",
-  descriptorRelativePath = "",
-  packageJson = {},
-  sourceType = "",
-  source = {}
-}) {
-  const normalizedSourceType = String(sourceType || "").trim() || "package";
-  const normalizedDescriptorPath = String(descriptorRelativePath || "").trim();
-  const normalizedSource = {
-    type: normalizedSourceType,
-    ...ensureObject(source)
-  };
-  if (!normalizedSource.descriptorPath && normalizedDescriptorPath) {
-    normalizedSource.descriptorPath = normalizedDescriptorPath;
-  }
-  return {
-    packageId: String(packageId || "").trim(),
-    version: String(version || "").trim(),
-    descriptor: ensureObject(descriptor),
-    rootDir: String(rootDir || "").trim(),
-    relativeDir: String(relativeDir || "").trim(),
-    descriptorRelativePath: normalizedDescriptorPath,
-    packageJson: ensureObject(packageJson),
-    sourceType: normalizedSourceType,
-    source: normalizedSource
-  };
-}
-
-function mergePackageRegistries(...registries) {
-  const merged = new Map();
-  for (const registry of registries) {
-    if (!(registry instanceof Map)) {
-      continue;
-    }
-    for (const [packageId, packageEntry] of registry.entries()) {
-      merged.set(packageId, packageEntry);
-    }
-  }
-  return merged;
-}
-
-function validateBundleDescriptorShape(descriptor, descriptorPath) {
-  const normalized = ensureObject(descriptor);
-  const bundleId = String(normalized.bundleId || "").trim();
-  const version = String(normalized.version || "").trim();
-  const packages = ensureArray(normalized.packages).map((value) => String(value));
-
-  if (!bundleId) {
-    throw createCliError(`Invalid bundle descriptor at ${descriptorPath}: missing bundleId.`);
-  }
-  if (!version) {
-    throw createCliError(`Invalid bundle descriptor at ${descriptorPath}: missing version.`);
-  }
-  if (packages.length < 2) {
-    throw createCliError(`Invalid bundle descriptor at ${descriptorPath}: bundles must contain at least two packages.`);
-  }
-
-  return normalized;
-}
-
-async function loadAppLocalPackageRegistry(appRoot) {
-  const localPackagesRoot = path.join(appRoot, "packages");
-  if (!(await fileExists(localPackagesRoot))) {
-    return new Map();
-  }
-
-  const registry = new Map();
-  const entries = await readdir(localPackagesRoot, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith(".")) {
-      continue;
-    }
-
-    const packageRoot = path.join(localPackagesRoot, entry.name);
-    const packageJsonPath = path.join(packageRoot, "package.json");
-    const descriptorPath = path.join(packageRoot, "package.descriptor.mjs");
-    if (!(await fileExists(packageJsonPath)) || !(await fileExists(descriptorPath))) {
-      continue;
-    }
-
-    const packageJson = await readJsonFile(packageJsonPath);
-    const packageId = String(packageJson?.name || "").trim();
-    if (!packageId) {
-      throw createCliError(`Invalid app-local package at ${normalizeRelativePath(appRoot, packageRoot)}: package.json missing name.`);
-    }
-
-    const descriptorModule = await import(pathToFileURL(descriptorPath).href + `?t=${Date.now()}_${Math.random()}`);
-    const descriptor = validateAppLocalPackageDescriptorShape(descriptorModule?.default, descriptorPath, {
-      expectedPackageId: packageId,
-      fallbackVersion: String(packageJson?.version || "").trim()
-    });
-
-    const relativeDir = normalizeRelativePath(appRoot, packageRoot);
-    const descriptorRelativePath = normalizeRelativePath(appRoot, descriptorPath);
-    registry.set(
-      packageId,
-      createPackageEntry({
-        packageId: descriptor.packageId,
-        version: descriptor.version,
-        descriptor,
-        rootDir: packageRoot,
-        relativeDir,
-        descriptorRelativePath,
-        packageJson,
-        sourceType: "app-local-package",
-        source: {
-          packagePath: normalizeRelativePosixPath(relativeDir),
-          descriptorPath: descriptorRelativePath
-        }
-      })
-    );
-  }
-
-  return registry;
-}
-
-async function loadCatalogPackageRegistry() {
-  if (!(await fileExists(CATALOG_PACKAGES_PATH))) {
-    return new Map();
-  }
-
-  const catalog = await readJsonFile(CATALOG_PACKAGES_PATH);
-  const packageRecords = ensureArray(catalog?.packages);
-  const registry = new Map();
-
-  for (const packageRecord of packageRecords) {
-    const record = ensureObject(packageRecord);
-    const packageId = String(record.packageId || "").trim();
-    const descriptorPath = `${normalizeRelativePath(CLI_PACKAGE_ROOT, CATALOG_PACKAGES_PATH)}#${packageId || "unknown"}`;
-    const descriptor = validatePackageDescriptorShape(record.descriptor, descriptorPath);
-    if (!packageId) {
-      throw createCliError(`Invalid catalog package entry at ${descriptorPath}: missing packageId.`);
-    }
-    if (descriptor.packageId !== packageId) {
-      throw createCliError(
-        `Invalid catalog package entry at ${descriptorPath}: descriptor packageId ${descriptor.packageId} does not match catalog packageId ${packageId}.`
-      );
-    }
-
-    const version = String(record.version || descriptor.version || "").trim();
-    if (!version) {
-      throw createCliError(`Invalid catalog package entry at ${descriptorPath}: missing version.`);
-    }
-
-    registry.set(
-      packageId,
-      createPackageEntry({
-        packageId,
-        version,
-        descriptor: {
-          ...descriptor,
-          version
-        },
-        rootDir: "",
-        relativeDir: "",
-        descriptorRelativePath: descriptorPath,
-        packageJson: {
-          name: packageId,
-          version
-        },
-        sourceType: "catalog",
-        source: {
-          descriptorPath
-        }
-      })
-    );
-  }
-
-  return registry;
-}
-
-async function loadPackageRegistry() {
-  const catalogRegistry = await loadCatalogPackageRegistry();
-  if (catalogRegistry.size === 0) {
-    throw createCliError(
-      "Unable to load package registry from @jskit-ai/jskit-catalog. Install it alongside @jskit-ai/jskit-cli or set JSKIT_CATALOG_PACKAGES_PATH."
-    );
-  }
-
-  return catalogRegistry;
-}
-
-async function loadInstalledNodeModulePackageEntry({ appRoot, packageId }) {
-  const normalizedPackageId = String(packageId || "").trim();
-  if (!normalizedPackageId) {
-    return null;
-  }
-
-  const packageRoot = path.resolve(appRoot, "node_modules", ...normalizedPackageId.split("/"));
-  const packageJsonPath = path.join(packageRoot, "package.json");
-  if (!(await fileExists(packageJsonPath))) {
-    return null;
-  }
-
-  const packageJson = await readJsonFile(packageJsonPath);
-  const resolvedPackageId = String(packageJson?.name || "").trim() || normalizedPackageId;
-  const descriptorPath = path.join(packageRoot, "package.descriptor.mjs");
-  if (!(await fileExists(descriptorPath))) {
-    return null;
-  }
-
-  const descriptorModule = await import(pathToFileURL(descriptorPath).href + `?t=${Date.now()}_${Math.random()}`);
-  const descriptor = validateAppLocalPackageDescriptorShape(descriptorModule?.default, descriptorPath, {
-    expectedPackageId: resolvedPackageId,
-    fallbackVersion: String(packageJson?.version || "").trim()
-  });
-  const relativeDir = normalizeRelativePath(appRoot, packageRoot);
-  const descriptorRelativePath = normalizeRelativePath(appRoot, descriptorPath);
-
-  return createPackageEntry({
-    packageId: descriptor.packageId,
-    version: descriptor.version,
-    descriptor,
-    rootDir: packageRoot,
-    relativeDir,
-    descriptorRelativePath,
-    packageJson,
-    sourceType: "npm-installed-package",
-    source: {
-      packagePath: normalizeRelativePosixPath(relativeDir),
-      descriptorPath: descriptorRelativePath
-    }
-  });
-}
-
-async function resolveInstalledNodeModulePackageEntry({ appRoot, packageId }) {
-  const raw = String(packageId || "").trim();
-  if (!raw) {
-    return null;
-  }
-
-  const candidates = [];
-  const seen = new Set();
-  const appendCandidate = (value) => {
-    const candidate = String(value || "").trim();
-    if (!candidate || seen.has(candidate)) {
-      return;
-    }
-    seen.add(candidate);
-    candidates.push(candidate);
-  };
-
-  appendCandidate(raw);
-  appendCandidate(toScopedPackageId(raw));
-
-  for (const candidateId of candidates) {
-    const entry = await loadInstalledNodeModulePackageEntry({
-      appRoot,
-      packageId: candidateId
-    });
-    if (entry) {
-      return entry;
-    }
-  }
-
-  return null;
-}
-
-async function hydratePackageRegistryFromInstalledNodeModules({
-  appRoot,
-  packageRegistry,
-  seedPackageIds = []
-}) {
-  const queue = ensureArray(seedPackageIds)
-    .map((value) => String(value || "").trim())
-    .filter(Boolean);
-  const visited = new Set();
-
-  while (queue.length > 0) {
-    const packageId = queue.shift();
-    if (!packageId || visited.has(packageId)) {
-      continue;
-    }
-    visited.add(packageId);
-
-    let packageEntry = packageRegistry.get(packageId);
-    if (!packageEntry) {
-      const resolvedEntry = await resolveInstalledNodeModulePackageEntry({
-        appRoot,
-        packageId
-      });
-      if (!resolvedEntry) {
-        continue;
-      }
-
-      packageRegistry.set(resolvedEntry.packageId, resolvedEntry);
-      packageEntry = resolvedEntry;
-      if (resolvedEntry.packageId !== packageId && !visited.has(resolvedEntry.packageId)) {
-        queue.push(resolvedEntry.packageId);
-      }
-    }
-
-    const dependsOn = ensureArray(packageEntry?.descriptor?.dependsOn).map((value) => String(value || "").trim()).filter(Boolean);
-    for (const dependencyId of dependsOn) {
-      if (!visited.has(dependencyId)) {
-        queue.push(dependencyId);
-      }
-    }
-  }
-}
-
-async function loadBundleRegistry() {
-  if (!(await fileExists(BUNDLES_ROOT))) {
-    return new Map();
-  }
-
-  const bundles = new Map();
-  const entries = await readdir(BUNDLES_ROOT, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith(".")) {
-      continue;
-    }
-
-    const descriptorPath = path.join(BUNDLES_ROOT, entry.name, "bundle.descriptor.mjs");
-    if (!(await fileExists(descriptorPath))) {
-      continue;
-    }
-
-    const descriptorModule = await import(pathToFileURL(descriptorPath).href);
-    const descriptor = validateBundleDescriptorShape(descriptorModule?.default, descriptorPath);
-    bundles.set(descriptor.bundleId, descriptor);
-  }
-
-  return bundles;
-}
-
-function resolvePackageDependencySpecifier(packageEntry, { existingValue = "" } = {}) {
-  const source = ensureObject(packageEntry?.source);
-  const sourceType = String(source.type || packageEntry?.sourceType || "").trim();
-  if (sourceType === "app-local-package" || sourceType === "local-package") {
-    const packagePath = normalizeRelativePosixPath(String(source.packagePath || packageEntry?.relativeDir || "").trim());
-    if (!packagePath) {
-      throw createCliError(`Unable to resolve local package path for ${String(packageEntry?.packageId || "unknown package")}.`);
-    }
-    return toFileDependencySpecifier(packagePath);
-  }
-  if (sourceType === "npm-installed-package") {
-    const normalizedExisting = String(existingValue || "").trim();
-    if (normalizedExisting) {
-      return normalizedExisting;
-    }
-  }
-
-  const descriptorVersion = String(packageEntry?.version || "").trim();
-  if (descriptorVersion) {
-    return normalizeJskitDependencySpecifier(packageEntry?.packageId, descriptorVersion);
-  }
-  const packageJsonVersion = String(packageEntry?.packageJson?.version || "").trim();
-  if (packageJsonVersion) {
-    return normalizeJskitDependencySpecifier(packageEntry?.packageId, packageJsonVersion);
-  }
-  throw createCliError(`Unable to resolve dependency specifier for ${String(packageEntry?.packageId || "unknown package")}.`);
-}
-
-function normalizeJskitDependencySpecifier(packageId, dependencySpecifier) {
-  const normalizedPackageId = String(packageId || "").trim();
-  const normalizedSpecifier = String(dependencySpecifier || "").trim();
-  if (!normalizedSpecifier || !normalizedPackageId.startsWith("@jskit-ai/")) {
-    return normalizedSpecifier;
-  }
-
-  const semverMatch = /^(\d+)\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?$/.exec(normalizedSpecifier);
-  if (!semverMatch) {
-    return normalizedSpecifier;
-  }
-
-  return `${semverMatch[1]}.x`;
-}
-
-function normalizePackageNameSegment(rawValue, { label = "package name" } = {}) {
-  const lowered = String(rawValue || "")
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^[._-]+|[._-]+$/g, "");
-  if (!lowered) {
-    throw createCliError(`Invalid ${label}. Use letters, numbers, dash, underscore, or dot.`);
-  }
-  return lowered;
-}
-
-function normalizeScopeName(rawScope) {
-  const normalized = String(rawScope || "").trim().replace(/^@+/, "");
-  return normalizePackageNameSegment(normalized, { label: "scope" });
-}
-
-function resolveDefaultLocalScopeFromAppName(appPackageName) {
-  const appName = String(appPackageName || "").trim();
-  if (!appName) {
-    return "app";
-  }
-
-  const unscoped = appName.startsWith("@")
-    ? appName.slice(appName.indexOf("/") + 1)
-    : appName;
-  return normalizeScopeName(unscoped || "app");
-}
-
-function normalizeRelativePosixPath(pathValue) {
-  return String(pathValue || "")
-    .trim()
-    .replace(/\\/g, "/")
-    .replace(/^\/+|\/+$/g, "")
-    .replace(/\/{2,}/g, "/");
-}
-
-function toFileDependencySpecifier(relativePath) {
-  const normalized = normalizeRelativePosixPath(relativePath);
-  if (!normalized) {
-    throw createCliError("Cannot create file: dependency specifier from empty relative path.");
-  }
-  return `file:${normalized}`;
-}
-
-function resolveLocalPackageId({ rawName, appPackageName, inlineOptions }) {
-  const explicitPackageId = String(inlineOptions["package-id"] || "").trim();
-  if (explicitPackageId) {
-    const scopedPattern = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
-    if (!scopedPattern.test(explicitPackageId)) {
-      throw createCliError(
-        `Invalid --package-id ${explicitPackageId}. Expected format: @scope/name (lowercase alphanumeric, ., _, -).`
-      );
-    }
-    const packageName = explicitPackageId.slice(explicitPackageId.indexOf("/") + 1);
-    return {
-      packageId: explicitPackageId,
-      packageDirName: normalizePackageNameSegment(packageName)
-    };
-  }
-
-  const packageDirName = normalizePackageNameSegment(rawName);
-  const scopeName = String(inlineOptions.scope || "").trim()
-    ? normalizeScopeName(inlineOptions.scope)
-    : resolveDefaultLocalScopeFromAppName(appPackageName);
-  return {
-    packageId: `@${scopeName}/${packageDirName}`,
-    packageDirName
-  };
-}
-
-function createLocalPackageDescriptorTemplate({ packageId, description }) {
-  return `export default Object.freeze({
-  packageVersion: 1,
-  packageId: "${packageId}",
-  version: "0.1.0",
-  kind: "runtime",
-  description: ${JSON.stringify(String(description || ""))},
-  dependsOn: [
-    // "@jskit-ai/kernel"
-  ],
-  capabilities: {
-    provides: [
-      // "example.feature"
-    ],
-    requires: [
-      // "example.dependency"
-    ]
-  },
-  options: {
-    // "example-option": {
-    //   required: true,
-    //   promptLabel: "Enter option value",
-    //   promptHint: "Used by mutations.text interpolation",
-    //   defaultValue: "example"
-    // }
-  },
-  runtime: {
-    server: {
-      providers: [
-        // {
-        //   entrypoint: "src/server/providers/ExampleServerProvider.js",
-        //   export: "ExampleServerProvider"
-        // }
-      ]
-    },
-    client: {
-      providers: [
-        // {
-        //   entrypoint: "src/client/providers/ExampleClientProvider.js",
-        //   export: "ExampleClientProvider"
-        // }
-      ]
-    }
-  },
-  metadata: {
-    server: {
-      routes: [
-        // {
-        //   method: "GET",
-        //   path: "/api/example",
-        //   summary: "Describe server route validator"
-        // }
-      ]
-    },
-    ui: {
-      routes: [
-        // {
-        //   id: "example.route",
-        //   path: "/example",
-        //   scope: "global",
-        //   name: "example-route",
-        //   componentKey: "example-route",
-        //   autoRegister: true,
-        //   guard: {
-        //     policy: "public"
-        //   },
-        //   purpose: "Describe what this route is for."
-        // }
-      ],
-      elements: [
-        // {
-        //   key: "example-route",
-        //   export: "ExampleView",
-        //   entrypoint: "src/client/views/ExampleView.vue",
-        //   purpose: "UI element exposed by this package."
-        // }
-      ],
-      overrides: [
-        // {
-        //   targetId: "some.existing.route",
-        //   mode: "replace",
-        //   reason: "Explain override intent."
-        // }
-      ]
-    }
-  },
-  mutations: {
-    dependencies: {
-      runtime: {
-        // "@example/runtime-dependency": "^1.0.0"
-      },
-      dev: {
-        // "@example/dev-dependency": "^1.0.0"
-      }
-    },
-    packageJson: {
-      scripts: {
-        // "lint:example": "eslint src/example"
-      }
-    },
-    procfile: {
-      // worker: "node ./bin/worker.js"
-    },
-    vite: {
-      proxy: [
-        // {
-        //   id: "example-socket-proxy",
-        //   path: "/socket.io",
-        //   changeOrigin: true,
-        //   ws: true,
-        //   target: "http://localhost:3000",
-        //   reason: "Explain why this proxy is needed."
-        // }
-      ]
-    },
-    text: [
-      // {
-      //   op: "upsert-env",
-      //   file: ".env",
-      //   key: "EXAMPLE_ENV",
-      //   value: "\${option:example-option}",
-      //   reason: "Explain why this env var is needed.",
-      //   category: "runtime-config",
-      //   id: "example-env"
-      // }
-    ],
-    files: [
-      // {
-      //   from: "templates/src/pages/example/index.vue",
-      //   to: "src/pages/example/index.vue",
-      //   reason: "Explain what is scaffolded.",
-      //   category: "example",
-      //   id: "example-file"
-      // }
-    ]
-  }
-});
-`;
-}
-
-function createLocalPackageScaffoldFiles({ packageId, packageDescription }) {
-  return [
-    {
-      relativePath: "package.json",
-      content: `${JSON.stringify(
-        {
-          name: packageId,
-          version: "0.1.0",
-          private: true,
-          type: "module",
-          exports: {
-            ".": "./src/index.js",
-            "./client": "./src/client/index.js",
-            "./server": "./src/server/index.js",
-            "./shared": "./src/shared/index.js"
-          }
-        },
-        null,
-        2
-      )}\n`
-    },
-    {
-      relativePath: "package.descriptor.mjs",
-      content: createLocalPackageDescriptorTemplate({
-        packageId,
-        description: packageDescription
-      })
-    },
-    {
-      relativePath: "src/index.js",
-      content: "export {};\n"
-    },
-    {
-      relativePath: "src/server/index.js",
-      content: "export {};\n"
-    },
-    {
-      relativePath: "src/client/index.js",
-      content: [
-        "const routeComponents = Object.freeze({});",
-        "",
-        "async function bootClient({ logger } = {}) {",
-        "  if (logger && typeof logger.debug === \"function\") {",
-        `    logger.debug({ packageId: ${JSON.stringify(packageId)} }, "bootClient executed.");`,
-        "  }",
-        "}",
-        "",
-        "export { routeComponents, bootClient };",
-        ""
-      ].join("\n")
-    },
-    {
-      relativePath: "src/shared/index.js",
-      content: "export {};\n"
-    },
-    {
-      relativePath: "README.md",
-      content: [
-        `# ${packageId}`,
-        "",
-        "App-local JSKIT module scaffold.",
-        "",
-        "## Next Steps",
-        "",
-        "- Define runtime providers in `package.descriptor.mjs`.",
-        "- Add client/server exports under `src/`.",
-        "- Keep package version in sync with descriptor version.",
-        ""
-      ].join("\n")
-    }
-  ];
-}
-
-function resolveLocalDependencyOrder(initialPackageIds, packageRegistry) {
-  const ordered = [];
-  const visited = new Set();
-  const visiting = new Set();
-  const externalDependencies = new Set();
-
-  function visit(packageId, lineage = []) {
-    if (visited.has(packageId)) {
-      return;
-    }
-    if (visiting.has(packageId)) {
-      const cyclePath = [...lineage, packageId].join(" -> ");
-      throw createCliError(`Dependency cycle detected: ${cyclePath}`);
-    }
-
-    const packageEntry = packageRegistry.get(packageId);
-    if (!packageEntry) {
-      throw createCliError(`Unknown package: ${packageId}`);
-    }
-
-    visiting.add(packageId);
-    for (const dependencyId of ensureArray(packageEntry.descriptor.dependsOn).map((value) => String(value))) {
-      if (packageRegistry.has(dependencyId)) {
-        visit(dependencyId, [...lineage, packageId]);
-      } else {
-        externalDependencies.add(dependencyId);
-      }
-    }
-    visiting.delete(packageId);
-    visited.add(packageId);
-    ordered.push(packageId);
-  }
-
-  for (const packageId of initialPackageIds) {
-    visit(packageId);
-  }
-
-  return {
-    ordered,
-    externalDependencies: sortStrings([...externalDependencies])
-  };
-}
-
-function listDeclaredCapabilities(capabilitiesSection, fieldName) {
-  const section = ensureObject(capabilitiesSection);
-  const source = ensureArray(section[fieldName]);
-  const normalized = [];
-  const seen = new Set();
-  for (const value of source) {
-    const capabilityId = String(value || "").trim();
-    if (!capabilityId || seen.has(capabilityId)) {
-      continue;
-    }
-    seen.add(capabilityId);
-    normalized.push(capabilityId);
-  }
-  return normalized;
-}
-
-function buildCapabilityGraph(packageRegistry) {
-  const graph = new Map();
-  const ensureNode = (capabilityId) => {
-    if (!graph.has(capabilityId)) {
-      graph.set(capabilityId, {
-        providers: new Set(),
-        requirers: new Set()
-      });
-    }
-    return graph.get(capabilityId);
-  };
-
-  for (const [packageId, packageEntry] of packageRegistry.entries()) {
-    const capabilities = ensureObject(packageEntry?.descriptor?.capabilities);
-    for (const capabilityId of listDeclaredCapabilities(capabilities, "provides")) {
-      ensureNode(capabilityId).providers.add(packageId);
-    }
-    for (const capabilityId of listDeclaredCapabilities(capabilities, "requires")) {
-      ensureNode(capabilityId).requirers.add(packageId);
-    }
-  }
-
-  for (const [capabilityId, providers] of Object.entries(BUILTIN_CAPABILITY_PROVIDERS)) {
-    const node = ensureNode(capabilityId);
-    for (const providerId of ensureArray(providers).map((value) => String(value || "").trim()).filter(Boolean)) {
-      node.providers.add(providerId);
-    }
-  }
-
-  const normalizedGraph = new Map();
-  for (const [capabilityId, node] of graph.entries()) {
-    normalizedGraph.set(capabilityId, {
-      providers: sortStrings([...node.providers]),
-      requirers: sortStrings([...node.requirers])
-    });
-  }
-  return normalizedGraph;
-}
-
-function createCapabilityPackageDetail(packageId, packageRegistry) {
-  const packageEntry = packageRegistry.get(packageId);
-  return {
-    packageId,
-    version: String(packageEntry?.version || packageEntry?.descriptor?.version || "").trim(),
-    descriptorPath: String(packageEntry?.descriptorRelativePath || "").trim()
-  };
-}
-
-function buildCapabilityDetailsForPackage({ packageRegistry, packageId, dependsOn = [], provides = [], requires = [] }) {
-  const graph = buildCapabilityGraph(packageRegistry);
-  const dependsOnSet = new Set(ensureArray(dependsOn).map((value) => String(value || "").trim()).filter(Boolean));
-
-  function buildCapabilityRecord(capabilityId) {
-    const node = graph.get(capabilityId) || {
-      providers: [],
-      requirers: []
-    };
-    const providers = sortStrings(ensureArray(node.providers));
-    const requirers = sortStrings(ensureArray(node.requirers));
-    const providersInDependsOn = providers.filter((providerId) => dependsOnSet.has(providerId));
-    return {
-      capabilityId,
-      providers,
-      requirers,
-      providersInDependsOn,
-      providerDetails: providers.map((providerId) => createCapabilityPackageDetail(providerId, packageRegistry)),
-      requirerDetails: requirers.map((requirerId) => createCapabilityPackageDetail(requirerId, packageRegistry)),
-      isProvidedByCurrentPackage: providers.includes(packageId),
-      isRequiredByCurrentPackage: requirers.includes(packageId)
-    };
-  }
-
-  return {
-    provides: ensureArray(provides).map((capabilityId) => buildCapabilityRecord(capabilityId)),
-    requires: ensureArray(requires).map((capabilityId) => buildCapabilityRecord(capabilityId))
-  };
-}
-
-function escapeRegexLiteral(value) {
-  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function parseQuotedStringLiteral(value) {
-  const source = String(value || "").trim();
-  if (source.length < 2) {
-    return null;
-  }
-
-  const quote = source[0];
-  if ((quote !== "\"" && quote !== "'") || source[source.length - 1] !== quote) {
-    return null;
-  }
-
-  if (quote === "\"") {
-    try {
-      return JSON.parse(source);
-    } catch {
-      return null;
-    }
-  }
-
-  return source
-    .slice(1, -1)
-    .replace(/\\\\/g, "\\")
-    .replace(/\\'/g, "'")
-    .replace(/\\"/g, "\"")
-    .replace(/\\n/g, "\n")
-    .replace(/\\r/g, "\r")
-    .replace(/\\t/g, "\t");
-}
-
-function resolveLineNumberAtIndex(source, index) {
-  const text = String(source || "");
-  const maxIndex = Math.max(0, Math.min(Number(index) || 0, text.length));
-  let line = 1;
-  for (let cursor = 0; cursor < maxIndex; cursor += 1) {
-    if (text[cursor] === "\n") {
-      line += 1;
-    }
-  }
-  return line;
-}
-
-function findMatchingBraceIndex(source, openBraceIndex) {
-  const text = String(source || "");
-  const startIndex = Number(openBraceIndex);
-  if (!Number.isInteger(startIndex) || startIndex < 0 || startIndex >= text.length || text[startIndex] !== "{") {
-    return -1;
-  }
-
-  let depth = 0;
-  let inSingleQuote = false;
-  let inDoubleQuote = false;
-  let inTemplateQuote = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  for (let cursor = startIndex; cursor < text.length; cursor += 1) {
-    const current = text[cursor];
-    const next = text[cursor + 1] || "";
-
-    if (inLineComment) {
-      if (current === "\n") {
-        inLineComment = false;
-      }
-      continue;
-    }
-
-    if (inBlockComment) {
-      if (current === "*" && next === "/") {
-        inBlockComment = false;
-        cursor += 1;
-      }
-      continue;
-    }
-
-    if (inSingleQuote) {
-      if (current === "\\") {
-        cursor += 1;
-        continue;
-      }
-      if (current === "'") {
-        inSingleQuote = false;
-      }
-      continue;
-    }
-
-    if (inDoubleQuote) {
-      if (current === "\\") {
-        cursor += 1;
-        continue;
-      }
-      if (current === "\"") {
-        inDoubleQuote = false;
-      }
-      continue;
-    }
-
-    if (inTemplateQuote) {
-      if (current === "\\") {
-        cursor += 1;
-        continue;
-      }
-      if (current === "`") {
-        inTemplateQuote = false;
-      }
-      continue;
-    }
-
-    if (current === "/" && next === "/") {
-      inLineComment = true;
-      cursor += 1;
-      continue;
-    }
-    if (current === "/" && next === "*") {
-      inBlockComment = true;
-      cursor += 1;
-      continue;
-    }
-    if (current === "'") {
-      inSingleQuote = true;
-      continue;
-    }
-    if (current === "\"") {
-      inDoubleQuote = true;
-      continue;
-    }
-    if (current === "`") {
-      inTemplateQuote = true;
-      continue;
-    }
-
-    if (current === "{") {
-      depth += 1;
-      continue;
-    }
-    if (current === "}") {
-      depth -= 1;
-      if (depth === 0) {
-        return cursor;
-      }
-    }
-  }
-
-  return -1;
-}
-
-function extractProviderLifecycleMethodRanges(source, providerExportName) {
-  const text = String(source || "");
-  const providerName = String(providerExportName || "").trim();
-  if (!text) {
-    return [];
-  }
-
-  const fallback = [
-    {
-      lifecycle: "unknown",
-      start: 0,
-      end: text.length
-    }
-  ];
-  if (!providerName) {
-    return fallback;
-  }
-
-  const classPattern = new RegExp(`\\bclass\\s+${escapeRegexLiteral(providerName)}\\b`);
-  const classMatch = classPattern.exec(text);
-  if (!classMatch) {
-    return fallback;
-  }
-
-  const classOpenBraceIndex = text.indexOf("{", classMatch.index + classMatch[0].length);
-  if (classOpenBraceIndex < 0) {
-    return fallback;
-  }
-  const classCloseBraceIndex = findMatchingBraceIndex(text, classOpenBraceIndex);
-  if (classCloseBraceIndex < 0) {
-    return fallback;
-  }
-
-  const classBody = text.slice(classOpenBraceIndex + 1, classCloseBraceIndex);
-  const methodPattern = /\b(?:async\s+)?(register|boot)\s*\([^)]*\)\s*\{/g;
-  const ranges = [];
-  let methodMatch = methodPattern.exec(classBody);
-  while (methodMatch) {
-    const lifecycle = String(methodMatch[1] || "").trim() || "unknown";
-    const methodOpenOffset = methodMatch[0].lastIndexOf("{");
-    if (methodOpenOffset < 0) {
-      methodMatch = methodPattern.exec(classBody);
-      continue;
-    }
-    const methodOpenIndex = classOpenBraceIndex + 1 + methodMatch.index + methodOpenOffset;
-    const methodCloseIndex = findMatchingBraceIndex(text, methodOpenIndex);
-    if (methodCloseIndex < 0) {
-      methodMatch = methodPattern.exec(classBody);
-      continue;
-    }
-    ranges.push({
-      lifecycle,
-      start: methodOpenIndex + 1,
-      end: methodCloseIndex
-    });
-    methodMatch = methodPattern.exec(classBody);
-  }
-
-  if (ranges.length > 0) {
-    return ranges;
-  }
-  return [
-    {
-      lifecycle: "class",
-      start: classOpenBraceIndex + 1,
-      end: classCloseBraceIndex
-    }
-  ];
-}
-
-function collectConstTokenAssignments(source) {
-  const text = String(source || "");
-  const assignments = new Map();
-  const pattern = /^\s*const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*([^;]+);\s*$/gm;
-  let match = pattern.exec(text);
-  while (match) {
-    const identifier = String(match[1] || "").trim();
-    const expression = String(match[2] || "").trim();
-    if (identifier && expression) {
-      assignments.set(identifier, expression);
-    }
-    match = pattern.exec(text);
-  }
-  return assignments;
-}
-
-function resolveTokenFromExpression(expression, constAssignments, visited = new Set()) {
-  let normalized = String(expression || "").trim();
-  if (!normalized) {
-    return {
-      token: "",
-      resolved: false,
-      kind: "empty"
-    };
-  }
-
-  while (normalized.startsWith("(") && normalized.endsWith(")")) {
-    normalized = normalized.slice(1, -1).trim();
-  }
-
-  const quoted = parseQuotedStringLiteral(normalized);
-  if (quoted !== null) {
-    return {
-      token: quoted,
-      resolved: true,
-      kind: "string"
-    };
-  }
-
-  const symbolMatch = /^Symbol\.for\(\s*(['"])(.*?)\1\s*\)$/.exec(normalized);
-  if (symbolMatch) {
-    return {
-      token: `Symbol.for(${symbolMatch[2]})`,
-      resolved: true,
-      kind: "symbol"
-    };
-  }
-
-  if (/^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)+$/.test(normalized)) {
-    return {
-      token: normalized,
-      resolved: true,
-      kind: "member"
-    };
-  }
-
-  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(normalized)) {
-    const identifier = normalized;
-    if (visited.has(identifier)) {
-      return {
-        token: identifier,
-        resolved: false,
-        kind: "cyclic-identifier"
-      };
-    }
-    const nextExpression = constAssignments.get(identifier);
-    if (nextExpression) {
-      return resolveTokenFromExpression(nextExpression, constAssignments, new Set([...visited, identifier]));
-    }
-    return {
-      token: identifier,
-      resolved: false,
-      kind: "identifier"
-    };
-  }
-
-  return {
-    token: normalized,
-    resolved: false,
-    kind: "expression"
-  };
-}
-
-function collectContainerBindingsFromProviderSource({ source, providerLabel, entrypoint, providerExportName }) {
-  const text = String(source || "");
-  if (!text) {
-    return [];
-  }
-
-  const constAssignments = collectConstTokenAssignments(text);
-  const methodRanges = extractProviderLifecycleMethodRanges(text, providerExportName);
-  const records = [];
-
-  for (const range of methodRanges) {
-    const lifecycle = String(range?.lifecycle || "unknown").trim() || "unknown";
-    const start = Number(range?.start) || 0;
-    const end = Number(range?.end) || text.length;
-    const slice = text.slice(start, end);
-    const bindingPattern = /\bapp\.(singleton|bind|scoped|instance)\s*\(\s*([\s\S]*?)\s*,/g;
-    let match = bindingPattern.exec(slice);
-    while (match) {
-      const binding = String(match[1] || "").trim();
-      const tokenExpression = String(match[2] || "")
-        .replace(/\s+/g, " ")
-        .trim();
-      if (!tokenExpression) {
-        match = bindingPattern.exec(slice);
-        continue;
-      }
-      const tokenResolution = resolveTokenFromExpression(tokenExpression, constAssignments);
-      const line = resolveLineNumberAtIndex(text, start + match.index);
-      records.push({
-        provider: providerLabel,
-        entrypoint: String(entrypoint || "").trim(),
-        exportName: String(providerExportName || "").trim(),
-        lifecycle,
-        binding,
-        token: String(tokenResolution.token || "").trim(),
-        tokenExpression,
-        tokenResolved: Boolean(tokenResolution.resolved),
-        tokenKind: String(tokenResolution.kind || "").trim(),
-        location: `${String(entrypoint || "").trim()}:${line}`,
-        line
-      });
-      match = bindingPattern.exec(slice);
-    }
-  }
-
-  return records;
-}
-
-function collectPackageExportEntries(exportsField) {
-  const entries = [];
-  const normalizeExportSubpath = (subpath) => {
-    const normalized = String(subpath || ".").trim() || ".";
-    if (normalized === "." || normalized === "./") {
-      return {
-        normalized: ".",
-        segments: []
-      };
-    }
-
-    const withoutPrefix = normalized.startsWith("./") ? normalized.slice(2) : normalized;
-    const segments = withoutPrefix.split("/").map((value) => String(value || "").trim()).filter(Boolean);
-    return {
-      normalized: normalized.startsWith("./") ? normalized : `./${withoutPrefix}`,
-      segments
-    };
-  };
-
-  const resolveSubpathSortPriority = (subpath) => {
-    const normalized = normalizeExportSubpath(subpath);
-    const firstSegment = String(normalized.segments[0] || "").trim();
-    if (firstSegment === "client") {
-      return 0;
-    }
-    if (firstSegment === "server") {
-      return 1;
-    }
-    if (firstSegment === "shared") {
-      return 2;
-    }
-    if (normalized.normalized === ".") {
-      return 3;
-    }
-    return 10;
-  };
-
-  const appendEntry = (subpath, conditions, target) => {
-    const normalizedSubpath = String(subpath || ".").trim() || ".";
-    const normalizedTarget = String(target || "").trim();
-    if (!normalizedTarget) {
-      return;
-    }
-    const normalizedConditions = ensureArray(conditions).map((value) => String(value || "").trim()).filter(Boolean);
-    entries.push({
-      subpath: normalizedSubpath,
-      condition: normalizedConditions.length > 0 ? normalizedConditions.join(".") : "default",
-      target: normalizedTarget
-    });
-  };
-
-  const visit = (subpath, value, conditionStack = []) => {
-    if (typeof value === "string") {
-      appendEntry(subpath, conditionStack, value);
-      return;
-    }
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        visit(subpath, item, conditionStack);
-      }
-      return;
-    }
-    if (!value || typeof value !== "object") {
-      return;
-    }
-    for (const [conditionName, nested] of Object.entries(value)) {
-      visit(subpath, nested, [...conditionStack, conditionName]);
-    }
-  };
-
-  if (typeof exportsField === "string" || Array.isArray(exportsField)) {
-    visit(".", exportsField, []);
-  } else if (exportsField && typeof exportsField === "object") {
-    const root = ensureObject(exportsField);
-    const rootKeys = Object.keys(root);
-    const hasSubpathKeys = rootKeys.some((key) => key.startsWith("."));
-    if (hasSubpathKeys) {
-      for (const [subpath, value] of Object.entries(root)) {
-        visit(subpath, value, []);
-      }
-    } else {
-      visit(".", root, []);
-    }
-  }
-
-  const deduplicated = [];
-  const seen = new Set();
-  for (const entry of entries) {
-    const key = `${entry.subpath}::${entry.condition}::${entry.target}`;
-    if (seen.has(key)) {
-      continue;
-    }
-    seen.add(key);
-    deduplicated.push(entry);
-  }
-  return deduplicated.sort((left, right) => {
-    const leftPriority = resolveSubpathSortPriority(left.subpath);
-    const rightPriority = resolveSubpathSortPriority(right.subpath);
-    if (leftPriority !== rightPriority) {
-      return leftPriority - rightPriority;
-    }
-
-    const leftParts = normalizeExportSubpath(left.subpath);
-    const rightParts = normalizeExportSubpath(right.subpath);
-    const leftRoot = String(leftParts.segments[0] || "");
-    const rightRoot = String(rightParts.segments[0] || "");
-    const rootComparison = leftRoot.localeCompare(rightRoot);
-    if (rootComparison !== 0) {
-      return rootComparison;
-    }
-
-    const depthComparison = leftParts.segments.length - rightParts.segments.length;
-    if (depthComparison !== 0) {
-      return depthComparison;
-    }
-
-    const subpathComparison = left.subpath.localeCompare(right.subpath);
-    if (subpathComparison !== 0) {
-      return subpathComparison;
-    }
-    const conditionComparison = left.condition.localeCompare(right.condition);
-    if (conditionComparison !== 0) {
-      return conditionComparison;
-    }
-    return left.target.localeCompare(right.target);
-  });
-}
-
-async function describePackageExports({ packageRoot, packageJson }) {
-  const rootDir = String(packageRoot || "").trim();
-  if (!rootDir) {
-    return [];
-  }
-
-  const exportsField = ensureObject(packageJson).exports;
-  const entries = collectPackageExportEntries(exportsField);
-  const records = [];
-
-  for (const entry of entries) {
-    const subpath = String(entry.subpath || ".").trim() || ".";
-    const condition = String(entry.condition || "default").trim() || "default";
-    const target = String(entry.target || "").trim();
-    const isPattern = subpath.includes("*") || target.includes("*");
-    const isRelativeTarget = target.startsWith("./");
-    let targetExists = null;
-    if (isRelativeTarget && !isPattern) {
-      const absoluteTargetPath = path.resolve(rootDir, target);
-      targetExists = await fileExists(absoluteTargetPath);
-    }
-
-    let targetType = "external";
-    if (isPattern) {
-      targetType = "pattern";
-    } else if (isRelativeTarget) {
-      targetType = "file";
-    }
-
-    records.push({
-      subpath,
-      condition,
-      target,
-      targetType,
-      targetExists
-    });
-  }
-
-  return records;
-}
-
-function parseNamedExportSpecifiers(specifierSource) {
-  const source = String(specifierSource || "");
-  return source
-    .split(",")
-    .map((entry) => entry.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/g, "").trim())
-    .filter(Boolean)
-    .map((entry) => entry.replace(/\s+/g, " "))
-    .map((entry) => {
-      const aliasMatch = /^(.+?)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/.exec(entry);
-      if (aliasMatch) {
-        return aliasMatch[2];
-      }
-      return entry;
-    })
-    .filter((entry) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(entry));
-}
-
-function parseExportedSymbolsFromSource(source) {
-  const text = String(source || "");
-  const symbols = new Set();
-  const starReExports = new Set();
-  const namedReExports = new Set();
-
-  const namespaceStarPattern = /export\s+\*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+["']([^"']+)["']\s*;?/g;
-  let match = namespaceStarPattern.exec(text);
-  while (match) {
-    symbols.add(String(match[1] || "").trim());
-    starReExports.add(String(match[2] || "").trim());
-    match = namespaceStarPattern.exec(text);
-  }
-
-  const starPattern = /export\s+\*\s+from\s+["']([^"']+)["']\s*;?/g;
-  match = starPattern.exec(text);
-  while (match) {
-    starReExports.add(String(match[1] || "").trim());
-    match = starPattern.exec(text);
-  }
-
-  const namedPattern = /export\s*\{([\s\S]*?)\}\s*(?:from\s*["']([^"']+)["'])?\s*;?/g;
-  match = namedPattern.exec(text);
-  while (match) {
-    const listSource = String(match[1] || "");
-    for (const symbol of parseNamedExportSpecifiers(listSource)) {
-      symbols.add(symbol);
-    }
-    if (match[2]) {
-      namedReExports.add(String(match[2] || "").trim());
-    }
-    match = namedPattern.exec(text);
-  }
-
-  const functionPattern = /export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/g;
-  match = functionPattern.exec(text);
-  while (match) {
-    symbols.add(String(match[1] || "").trim());
-    match = functionPattern.exec(text);
-  }
-
-  const classPattern = /export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/g;
-  match = classPattern.exec(text);
-  while (match) {
-    symbols.add(String(match[1] || "").trim());
-    match = classPattern.exec(text);
-  }
-
-  const variablePattern = /export\s+(?:const|let|var)\s+([\s\S]*?);/g;
-  match = variablePattern.exec(text);
-  while (match) {
-    const declaration = String(match[1] || "");
-    const names = declaration.split(",").map((entry) => String(entry || "").trim());
-    for (const name of names) {
-      const declarationMatch = /^([A-Za-z_$][A-Za-z0-9_$]*)\b/.exec(name);
-      if (declarationMatch) {
-        symbols.add(String(declarationMatch[1] || "").trim());
-      }
-    }
-    match = variablePattern.exec(text);
-  }
-
-  const hasDefaultExport = /\bexport\s+default\b/.test(text);
-  return {
-    symbols: sortStrings([...symbols]),
-    starReExports: sortStrings([...starReExports]),
-    namedReExports: sortStrings([...namedReExports]),
-    hasDefaultExport
-  };
-}
-
-function classifyExportedSymbols(symbols = []) {
-  const source = ensureArray(symbols).map((value) => String(value || "").trim()).filter(Boolean);
-  const providers = [];
-  const constants = [];
-  const functions = [];
-  const classesOrTypes = [];
-  const internals = [];
-  const others = [];
-
-  for (const symbol of source) {
-    if (/Provider$/.test(symbol)) {
-      providers.push(symbol);
-      continue;
-    }
-    if (/^__/.test(symbol)) {
-      internals.push(symbol);
-      continue;
-    }
-    if (/^[A-Z0-9_]+$/.test(symbol)) {
-      constants.push(symbol);
-      continue;
-    }
-    if (/^[a-z]/.test(symbol)) {
-      functions.push(symbol);
-      continue;
-    }
-    if (/^[A-Z]/.test(symbol)) {
-      classesOrTypes.push(symbol);
-      continue;
-    }
-    others.push(symbol);
-  }
-
-  return {
-    providers: sortStrings(providers),
-    constants: sortStrings(constants),
-    functions: sortStrings(functions),
-    classesOrTypes: sortStrings(classesOrTypes),
-    internals: sortStrings(internals),
-    others: sortStrings(others)
-  };
-}
-
-function formatPackageSubpathImport(packageId, subpath) {
-  const normalizedPackageId = String(packageId || "").trim();
-  const normalizedSubpath = String(subpath || "").trim();
-  if (!normalizedPackageId) {
-    return normalizedSubpath;
-  }
-  if (!normalizedSubpath || normalizedSubpath === ".") {
-    return normalizedPackageId;
-  }
-  if (normalizedSubpath.startsWith("./")) {
-    return `${normalizedPackageId}/${normalizedSubpath.slice(2)}`;
-  }
-  if (normalizedSubpath.startsWith("/")) {
-    return `${normalizedPackageId}${normalizedSubpath}`;
-  }
-  return `${normalizedPackageId}/${normalizedSubpath}`;
-}
-
-function normalizePlacementOutlets(value) {
-  const outlets = [];
-  const source = ensureArray(value);
-  for (const entry of source) {
-    const record = ensureObject(entry);
-    const host = String(record.host || "").trim();
-    const position = String(record.position || "").trim();
-    if (!host || !position) {
-      continue;
-    }
-
-    const surfaces = [...new Set(ensureArray(record.surfaces).map((item) => String(item || "").trim()).filter(Boolean))];
-    const description = String(record.description || "").trim();
-    const sourceLabel = String(record.source || "").trim();
-    outlets.push(
-      Object.freeze({
-        host,
-        position,
-        surfaces: Object.freeze(surfaces),
-        description,
-        source: sourceLabel
-      })
-    );
-  }
-
-  return Object.freeze(
-    [...outlets].sort((left, right) => {
-      const hostCompare = left.host.localeCompare(right.host);
-      if (hostCompare !== 0) {
-        return hostCompare;
-      }
-      return left.position.localeCompare(right.position);
-    })
-  );
-}
-
-function normalizePlacementContributions(value) {
-  const contributions = [];
-  for (const entry of ensureArray(value)) {
-    const record = ensureObject(entry);
-    const id = String(record.id || "").trim();
-    const host = String(record.host || "").trim();
-    const position = String(record.position || "").trim();
-    if (!id || !host || !position) {
-      continue;
-    }
-
-    const surfaces = [...new Set(ensureArray(record.surfaces).map((item) => String(item || "").trim()).filter(Boolean))];
-    const componentToken = String(record.componentToken || "").trim();
-    const when = String(record.when || "").trim();
-    const description = String(record.description || "").trim();
-    const source = String(record.source || "").trim();
-    const parsedOrder = Number(record.order);
-    const order = Number.isFinite(parsedOrder) ? Math.trunc(parsedOrder) : null;
-    contributions.push(
-      Object.freeze({
-        id,
-        host,
-        position,
-        surfaces: Object.freeze(surfaces),
-        order,
-        componentToken,
-        when,
-        description,
-        source
-      })
-    );
-  }
-
-  return Object.freeze(
-    [...contributions].sort((left, right) => {
-      const hostCompare = left.host.localeCompare(right.host);
-      if (hostCompare !== 0) {
-        return hostCompare;
-      }
-      const positionCompare = left.position.localeCompare(right.position);
-      if (positionCompare !== 0) {
-        return positionCompare;
-      }
-      const leftOrder = Number.isFinite(left.order) ? left.order : Number.POSITIVE_INFINITY;
-      const rightOrder = Number.isFinite(right.order) ? right.order : Number.POSITIVE_INFINITY;
-      if (leftOrder !== rightOrder) {
-        return leftOrder - rightOrder;
-      }
-      return left.id.localeCompare(right.id);
-    })
-  );
-}
-
-function deriveCanonicalExportTargetForSubpath(subpath) {
-  const normalizedSubpath = String(subpath || "").trim();
-  if (!normalizedSubpath) {
-    return "";
-  }
-  if (normalizedSubpath === ".") {
-    return "./src/index.js";
-  }
-  if (!normalizedSubpath.startsWith("./")) {
-    return "";
-  }
-
-  const bareSubpath = normalizedSubpath.slice(2);
-  if (!bareSubpath) {
-    return "";
-  }
-  if (bareSubpath === "client" || bareSubpath === "server" || bareSubpath === "shared") {
-    return `./src/${bareSubpath}/index.js`;
-  }
-
-  const roots = ["client", "server", "shared"];
-  for (const root of roots) {
-    if (!bareSubpath.startsWith(`${root}/`)) {
-      continue;
-    }
-    const suffix = bareSubpath.slice(root.length + 1);
-    if (!suffix) {
-      return "";
-    }
-    const hasJsExtension = /\.(?:c|m)?js$/.test(suffix);
-    const normalizedSuffix = hasJsExtension ? suffix : `${suffix}.js`;
-    return `./src/${root}/${normalizedSuffix}`;
-  }
-
-  return "";
-}
-
-function shouldShowPackageExportTarget({ subpath, target, targetType }) {
-  if (String(targetType || "").trim() !== "file") {
-    return true;
-  }
-
-  const canonicalTarget = deriveCanonicalExportTargetForSubpath(subpath);
-  if (!canonicalTarget) {
-    return true;
-  }
-
-  const normalizeTarget = (value) => {
-    const raw = String(value || "").trim();
-    if (!raw) {
-      return "";
-    }
-    const withoutPrefix = raw.startsWith("./") ? raw.slice(2) : raw;
-    return `./${normalizeRelativePosixPath(withoutPrefix)}`;
-  };
-
-  return normalizeTarget(target) !== normalizeTarget(canonicalTarget);
-}
-
-function deriveProviderDisplayName(bindingRecord) {
-  const binding = ensureObject(bindingRecord);
-  const providerLabel = String(binding.provider || "").trim();
-  if (!providerLabel) {
-    return "";
-  }
-
-  const hashIndex = providerLabel.lastIndexOf("#");
-  if (hashIndex > -1 && hashIndex < providerLabel.length - 1) {
-    return providerLabel.slice(hashIndex + 1);
-  }
-
-  const entrypoint = String(binding.entrypoint || "").trim();
-  if (!entrypoint) {
-    return providerLabel;
-  }
-  const basename = path.posix.basename(entrypoint);
-  return basename.replace(/\.(?:c|m)?js$/i, "") || providerLabel;
-}
-
-async function collectExportFileSymbolSummaries({ packageRoot, packageExports, notes }) {
-  const rootDir = String(packageRoot || "").trim();
-  if (!rootDir) {
-    return [];
-  }
-
-  const exportTargets = new Map();
-  for (const entry of ensureArray(packageExports)) {
-    const record = ensureObject(entry);
-    if (record.targetType !== "file" || record.targetExists !== true) {
-      continue;
-    }
-
-    const target = String(record.target || "").trim();
-    if (!target.startsWith("./")) {
-      continue;
-    }
-    const normalizedTarget = normalizeRelativePosixPath(target.replace(/^\.\//, ""));
-    const basename = path.posix.basename(normalizedTarget);
-    if (!/\.(?:js|mjs|cjs)$/i.test(basename)) {
-      continue;
-    }
-
-    if (!exportTargets.has(normalizedTarget)) {
-      exportTargets.set(normalizedTarget, {
-        file: normalizedTarget,
-        subpaths: new Set(),
-        conditions: new Set()
-      });
-    }
-    const bucket = exportTargets.get(normalizedTarget);
-    bucket.subpaths.add(String(record.subpath || ".").trim() || ".");
-    const condition = String(record.condition || "default").trim() || "default";
-    if (condition !== "default") {
-      bucket.conditions.add(condition);
-    }
-  }
-
-  const summaries = [];
-  for (const [relativeTargetPath, bucket] of exportTargets.entries()) {
-    const absoluteTargetPath = path.resolve(rootDir, relativeTargetPath);
-    if (!(await fileExists(absoluteTargetPath))) {
-      ensureArray(notes).push(`Export file missing: ${relativeTargetPath}`);
-      continue;
-    }
-
-    let source = "";
-    try {
-      source = await readFile(absoluteTargetPath, "utf8");
-    } catch (error) {
-      ensureArray(notes).push(
-        `Failed to read export file ${relativeTargetPath}: ${String(error?.message || error || "unknown error")}`
-      );
-      continue;
-    }
-
-    const summary = parseExportedSymbolsFromSource(source);
-    summaries.push({
-      file: normalizeRelativePosixPath(relativeTargetPath),
-      subpaths: sortStrings([...bucket.subpaths]),
-      conditions: sortStrings([...bucket.conditions]),
-      symbols: ensureArray(summary.symbols),
-      hasDefaultExport: Boolean(summary.hasDefaultExport),
-      starReExports: ensureArray(summary.starReExports),
-      namedReExports: ensureArray(summary.namedReExports)
-    });
-  }
-
-  return summaries.sort((left, right) => String(left.file || "").localeCompare(String(right.file || "")));
-}
-
-async function inspectPackageOfferings({ packageEntry }) {
-  const rootDir = String(packageEntry?.rootDir || "").trim();
-  const notes = [];
-  const details = {
-    available: Boolean(rootDir),
-    notes,
-    packageExports: [],
-    containerBindings: {
-      server: [],
-      client: []
-    },
-    exportedSymbols: []
-  };
-
-  if (!rootDir) {
-    notes.push("Source files are unavailable for static introspection (catalog metadata only).");
-    return details;
-  }
-
-  const packageJson = ensureObject(packageEntry?.packageJson);
-  details.packageExports = await describePackageExports({
-    packageRoot: rootDir,
-    packageJson
-  });
-
-  const runtime = ensureObject(packageEntry?.descriptor?.runtime);
-  const runtimeSides = [
-    {
-      side: "server",
-      providers: ensureArray(ensureObject(runtime.server).providers)
-    },
-    {
-      side: "client",
-      providers: ensureArray(ensureObject(runtime.client).providers)
-    }
-  ];
-
-  for (const runtimeSide of runtimeSides) {
-    const side = String(runtimeSide.side || "").trim();
-    if (!side) {
-      continue;
-    }
-    const bindings = [];
-    for (const provider of runtimeSide.providers) {
-      const record = ensureObject(provider);
-      const entrypoint = String(record.entrypoint || "").trim();
-      const exportName = String(record.export || "").trim();
-      if (!entrypoint) {
-        continue;
-      }
-
-      const providerLabel = exportName ? `${entrypoint}#${exportName}` : entrypoint;
-      if (entrypoint.includes("*")) {
-        notes.push(`Skipped wildcard provider entrypoint during introspection: ${providerLabel}`);
-        continue;
-      }
-
-      const providerPath = path.resolve(rootDir, entrypoint);
-      if (!(await fileExists(providerPath))) {
-        notes.push(`Provider file missing during introspection: ${providerLabel}`);
-        continue;
-      }
-
-      let source = "";
-      try {
-        source = await readFile(providerPath, "utf8");
-      } catch (error) {
-        notes.push(`Failed reading provider ${providerLabel}: ${String(error?.message || error || "unknown error")}`);
-        continue;
-      }
-
-      bindings.push(
-        ...collectContainerBindingsFromProviderSource({
-          source,
-          providerLabel,
-          entrypoint,
-          providerExportName: exportName
-        })
-      );
-    }
-
-    details.containerBindings[side] = bindings.sort((left, right) => {
-      const tokenComparison = String(left?.token || "").localeCompare(String(right?.token || ""));
-      if (tokenComparison !== 0) {
-        return tokenComparison;
-      }
-      const providerComparison = String(left?.provider || "").localeCompare(String(right?.provider || ""));
-      if (providerComparison !== 0) {
-        return providerComparison;
-      }
-      return Number(left?.line || 0) - Number(right?.line || 0);
-    });
-  }
-
-  details.exportedSymbols = await collectExportFileSymbolSummaries({
-    packageRoot: rootDir,
-    packageExports: details.packageExports,
-    notes
-  });
-
-  return details;
-}
-
-function collectPlannedCapabilityIssues(plannedPackageIds, packageRegistry) {
-  const selectedPackageIds = sortStrings(
-    [...new Set(ensureArray(plannedPackageIds).map((value) => String(value || "").trim()).filter(Boolean))]
-  );
-  const selectedPackageSet = new Set(selectedPackageIds);
-  const providersByCapability = new Map();
-
-  for (const [capabilityId, providers] of Object.entries(BUILTIN_CAPABILITY_PROVIDERS)) {
-    if (!providersByCapability.has(capabilityId)) {
-      providersByCapability.set(capabilityId, new Set());
-    }
-    for (const providerId of ensureArray(providers).map((value) => String(value || "").trim()).filter(Boolean)) {
-      providersByCapability.get(capabilityId).add(providerId);
-    }
-  }
-
-  for (const packageId of selectedPackageIds) {
-    const packageEntry = packageRegistry.get(packageId);
-    if (!packageEntry) {
-      continue;
-    }
-    const provides = listDeclaredCapabilities(packageEntry.descriptor.capabilities, "provides");
-    for (const capabilityId of provides) {
-      if (!providersByCapability.has(capabilityId)) {
-        providersByCapability.set(capabilityId, new Set());
-      }
-      providersByCapability.get(capabilityId).add(packageId);
-    }
-  }
-
-  const issues = [];
-  for (const packageId of selectedPackageIds) {
-    const packageEntry = packageRegistry.get(packageId);
-    if (!packageEntry) {
-      continue;
-    }
-    const requires = listDeclaredCapabilities(packageEntry.descriptor.capabilities, "requires");
-    for (const capabilityId of requires) {
-      const selectedProviders = providersByCapability.get(capabilityId);
-      if (selectedProviders && selectedProviders.size > 0) {
-        continue;
-      }
-
-      const availableProviders = [];
-      for (const [candidatePackageId, candidatePackageEntry] of packageRegistry.entries()) {
-        if (selectedPackageSet.has(candidatePackageId)) {
-          continue;
-        }
-        const candidateProvides = listDeclaredCapabilities(candidatePackageEntry.descriptor.capabilities, "provides");
-        if (candidateProvides.includes(capabilityId)) {
-          availableProviders.push(candidatePackageId);
-        }
-      }
-
-      issues.push({
-        packageId,
-        capabilityId,
-        availableProviders: sortStrings(availableProviders)
-      });
-    }
-  }
-
-  return issues;
-}
-
-function validatePlannedCapabilityClosure(plannedPackageIds, packageRegistry, actionLabel) {
-  const issues = collectPlannedCapabilityIssues(plannedPackageIds, packageRegistry);
-  if (issues.length === 0) {
-    return;
-  }
-
-  const lines = [`Cannot ${actionLabel}: capability requirements are not satisfied.`];
-  for (const issue of issues) {
-    const providersHint = issue.availableProviders.length > 0
-      ? ` Available providers: ${issue.availableProviders.join(", ")}.`
-      : "";
-    lines.push(
-      `- ${issue.packageId} requires capability ${issue.capabilityId}, but no selected package provides it.${providersHint}`
-    );
-  }
-
-  throw createCliError(lines.join("\n"));
-}
-
-function resolveSurfaceVisibilityOptionPolicy(packageEntry = {}) {
-  const descriptor = ensureObject(packageEntry?.descriptor);
-  const optionPolicies = ensureObject(descriptor.optionPolicies);
-  const surfaceVisibilityPolicy = optionPolicies.surfaceVisibility;
-  if (!surfaceVisibilityPolicy || surfaceVisibilityPolicy === false) {
-    return null;
-  }
-
-  let policy = {};
-  if (surfaceVisibilityPolicy === true) {
-    policy = {};
-  } else if (typeof surfaceVisibilityPolicy === "object" && !Array.isArray(surfaceVisibilityPolicy)) {
-    policy = ensureObject(surfaceVisibilityPolicy);
-  } else {
-    throw createCliError(
-      `Invalid option policy in package ${packageEntry.packageId}: surfaceVisibility must be true or an object.`
-    );
-  }
-
-  const surfaceOption = String(policy.surfaceOption || "surface").trim();
-  const visibilityOption = String(policy.visibilityOption || "visibility").trim();
-  if (!surfaceOption || !visibilityOption) {
-    throw createCliError(
-      `Invalid option policy in package ${packageEntry.packageId}: surfaceVisibility requires non-empty surfaceOption and visibilityOption.`
-    );
-  }
-
-  return Object.freeze({
-    surfaceOption,
-    visibilityOption,
-    allowAuto: policy.allowAuto !== false
-  });
-}
-
-function resolveSurfaceDefinitionsForOptionPolicy(configContext = {}) {
-  const publicConfig = ensureObject(configContext.public);
-  const mergedConfig = ensureObject(configContext.merged);
-  const sourceDefinitions = ensureObject(publicConfig.surfaceDefinitions);
-  const fallbackDefinitions = ensureObject(mergedConfig.surfaceDefinitions);
-  const surfaceDefinitions =
-    Object.keys(sourceDefinitions).length > 0 ? sourceDefinitions : fallbackDefinitions;
-
-  const normalizedDefinitions = {};
-  for (const [key, value] of Object.entries(surfaceDefinitions)) {
-    const definition = ensureObject(value);
-    const definitionId = normalizeSurfaceIdForMutation(definition.id || key);
-    if (!definitionId) {
-      continue;
-    }
-
-    normalizedDefinitions[definitionId] = Object.freeze({
-      id: definitionId,
-      enabled: definition.enabled !== false,
-      requiresWorkspace: definition.requiresWorkspace === true
-    });
-  }
-
-  return Object.freeze(normalizedDefinitions);
-}
-
-function normalizeResolvedOptionValue(value = "") {
-  return String(value || "").trim().toLowerCase();
-}
-
-function validateSurfaceVisibilityOptionPolicy({
-  packageEntry,
-  resolvedOptions = {},
-  policy,
-  configContext = {}
-} = {}) {
-  const packageId = String(packageEntry?.packageId || "").trim() || "unknown-package";
-  const surfaceIds = parseSurfaceIdListForMutation(resolvedOptions?.[policy.surfaceOption]);
-  const visibility = normalizeResolvedOptionValue(resolvedOptions?.[policy.visibilityOption]);
-  if (surfaceIds.length < 1 || !visibility) {
-    return;
-  }
-  const skipWorkspaceRequirement = policy.allowAuto && visibility === "auto";
-
-  const surfaceDefinitions = resolveSurfaceDefinitionsForOptionPolicy(configContext);
-  for (const surfaceId of surfaceIds) {
-    const surfaceDefinition = surfaceDefinitions[surfaceId];
-    if (!surfaceDefinition) {
-      throw createCliError(
-        `Invalid option combination for package ${packageId}: --${policy.surfaceOption} includes unknown surface "${surfaceId}" in config/public.js.`
-      );
-    }
-    if (surfaceDefinition.enabled !== true) {
-      throw createCliError(
-        `Invalid option combination for package ${packageId}: surface "${surfaceId}" is disabled in config/public.js.`
-      );
-    }
-
-    if (!skipWorkspaceRequirement && WORKSPACE_VISIBILITY_SET.has(visibility) && surfaceDefinition.requiresWorkspace !== true) {
-      throw createCliError(
-        `Invalid option combination for package ${packageId}: --${policy.visibilityOption} "${visibility}" requires surfaces with requiresWorkspace=true, but "${surfaceId}" has requiresWorkspace=false.`
-      );
-    }
-  }
-}
-
-async function validateResolvedOptionPolicies({
-  packageEntry,
-  resolvedOptions = {},
-  appRoot = "",
-  resolveConfigContext
-} = {}) {
-  const policy = resolveSurfaceVisibilityOptionPolicy(packageEntry);
-  if (!policy) {
-    return;
-  }
-  if (!appRoot) {
-    return;
-  }
-
-  const configContext = await resolveConfigContext();
-  validateSurfaceVisibilityOptionPolicy({
-    packageEntry,
-    resolvedOptions,
-    policy,
-    configContext
-  });
-}
-
-async function resolvePackageOptions(packageEntry, inlineOptions, io, { appRoot = "" } = {}) {
-  const optionSchemas = ensureObject(packageEntry.descriptor.options);
-  const optionNames = Object.keys(optionSchemas);
-  const resolved = {};
-  const inlineOptionValues = ensureObject(inlineOptions);
-  const hasInlineOption = (name) => Object.prototype.hasOwnProperty.call(inlineOptionValues, name);
-  let configContext = null;
-
-  async function loadConfigContext() {
-    if (!configContext) {
-      configContext = await loadMutationWhenConfigContext(appRoot);
-    }
-    return configContext;
-  }
-
-  async function resolveOptionDefaultFromConfig(configPath = "") {
-    const normalizedConfigPath = String(configPath || "").trim();
-    if (!normalizedConfigPath || !appRoot) {
-      return "";
-    }
-
-    await loadConfigContext();
-    return normalizeWhenSourceValue(resolveWhenConfigValue(configContext, normalizedConfigPath));
-  }
-
-  for (const optionName of optionNames) {
-    const schema = ensureObject(optionSchemas[optionName]);
-    const allowEmpty = schema.allowEmpty === true;
-    if (hasInlineOption(optionName)) {
-      const inlineValue = String(inlineOptionValues[optionName] || "").trim();
-      if (inlineValue || allowEmpty) {
-        resolved[optionName] = inlineValue;
-        continue;
-      }
-      if (schema.required) {
-        throw createCliError(`Package ${packageEntry.packageId} option ${optionName} requires a non-empty value.`);
-      }
-    }
-
-    const defaultFromConfigPath = String(schema.defaultFromConfig || "").trim();
-    if (defaultFromConfigPath) {
-      const defaultFromConfigValue = await resolveOptionDefaultFromConfig(defaultFromConfigPath);
-      if (defaultFromConfigValue || allowEmpty) {
-        resolved[optionName] = defaultFromConfigValue;
-        continue;
-      }
-    }
-
-    if (typeof schema.defaultValue === "string" && schema.defaultValue.trim()) {
-      resolved[optionName] = schema.defaultValue.trim();
-      continue;
-    }
-
-    if (schema.required) {
-      resolved[optionName] = await promptForRequiredOption({
-        ownerType: "package",
-        ownerId: packageEntry.packageId,
-        optionName,
-        optionSchema: schema,
-        stdin: io.stdin,
-        stdout: io.stdout
-      });
-      continue;
-    }
-
-    resolved[optionName] = "";
-  }
-
-  await validateResolvedOptionPolicies({
-    packageEntry,
-    resolvedOptions: resolved,
-    appRoot,
-    resolveConfigContext: loadConfigContext
-  });
-
-  return resolved;
-}
-
-function validateInlineOptionsForPackage(packageEntry, inlineOptions) {
-  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
-  const allowedOptionNames = Object.keys(optionSchemas);
-  const allowed = new Set(allowedOptionNames);
-  const providedOptionNames = Object.keys(ensureObject(inlineOptions));
-  const unknownOptionNames = providedOptionNames.filter((optionName) => !allowed.has(optionName));
-
-  if (unknownOptionNames.length < 1) {
-    return;
-  }
-
-  const sortedUnknown = sortStrings(unknownOptionNames);
-  const suffix = allowedOptionNames.length > 0
-    ? ` Allowed options: ${sortStrings(allowedOptionNames).join(", ")}.`
-    : " This package does not accept inline options.";
-
-  throw createCliError(
-    `Unknown option(s) for package ${packageEntry.packageId}: ${sortedUnknown.join(", ")}.${suffix}`
-  );
-}
-
-function createManagedRecordBase(packageEntry, options) {
-  const sourceRecord = {
-    type: String(packageEntry?.sourceType || "packages-directory"),
-    ...ensureObject(packageEntry?.source)
-  };
-  if (!sourceRecord.descriptorPath && String(packageEntry?.descriptorRelativePath || "").trim()) {
-    sourceRecord.descriptorPath = String(packageEntry.descriptorRelativePath).trim();
-  }
-
-  return {
-    packageId: packageEntry.packageId,
-    version: packageEntry.version,
-    source: sourceRecord,
-    managed: {
-      packageJson: {
-        dependencies: {},
-        devDependencies: {},
-        scripts: {}
-      },
-      text: {},
-      vite: {},
-      files: [],
-      migrations: []
-    },
-    options,
-    installedAt: new Date().toISOString()
-  };
-}
-
-async function runCommandCapture(command, args, { cwd } = {}) {
-  return await new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-
-    let stdout = "";
-    let stderr = "";
-
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString("utf8");
-    });
-
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) {
-        resolve({
-          stdout,
-          stderr
-        });
-        return;
-      }
-      const details = String(stderr || stdout || "").trim();
-      reject(createCliError(`${command} ${args.join(" ")} failed with exit code ${code}.${details ? ` ${details}` : ""}`));
-    });
-  });
-}
-
-function extractPackTarballName(packStdout) {
-  const lines = String(packStdout || "")
-    .split(/\r?\n/)
-    .map((value) => value.trim())
-    .filter(Boolean);
-  return lines.length > 0 ? lines[lines.length - 1] : "";
-}
-
-async function materializePackageRootFromRegistry({ packageEntry, appRoot }) {
-  const cacheKey = `${packageEntry.packageId}@${packageEntry.version}`;
-  if (MATERIALIZED_PACKAGE_ROOTS.has(cacheKey)) {
-    return MATERIALIZED_PACKAGE_ROOTS.get(cacheKey);
-  }
-
-  const tempRoot = await mkdtemp(path.join(tmpdir(), "jskit-cli-pack-"));
-  MATERIALIZED_PACKAGE_TEMP_DIRECTORIES.add(tempRoot);
-  const packageSpec = `${packageEntry.packageId}@${packageEntry.version}`;
-  const packResult = await runCommandCapture(
-    "npm",
-    ["pack", packageSpec, "--silent", "--pack-destination", tempRoot],
-    { cwd: appRoot }
-  );
-  const tarballName = extractPackTarballName(packResult.stdout);
-  if (!tarballName) {
-    throw createCliError(`Unable to materialize ${packageSpec}: npm pack produced no tarball name.`);
-  }
-
-  const tarballPath = path.join(tempRoot, tarballName);
-  if (!(await fileExists(tarballPath))) {
-    throw createCliError(`Unable to materialize ${packageSpec}: tarball missing at ${tarballPath}.`);
-  }
-
-  const extractedRoot = path.join(tempRoot, "extracted");
-  await mkdir(extractedRoot, { recursive: true });
-  await runCommandCapture("tar", ["-xzf", tarballPath, "-C", extractedRoot], { cwd: appRoot });
-  const packageRoot = path.join(extractedRoot, "package");
-  const descriptorPath = path.join(packageRoot, "package.descriptor.mjs");
-  if (!(await fileExists(descriptorPath))) {
-    throw createCliError(`Materialized package ${packageSpec} does not contain package.descriptor.mjs.`);
-  }
-
-  MATERIALIZED_PACKAGE_ROOTS.set(cacheKey, packageRoot);
-  return packageRoot;
-}
-
-async function resolvePackageRootFromNodeModules({ appRoot, packageId }) {
-  const normalizedAppRoot = path.resolve(String(appRoot || "").trim());
-  const normalizedPackageId = String(packageId || "").trim();
-  if (!normalizedAppRoot || !normalizedPackageId) {
-    return "";
-  }
-
-  const candidateRoot = path.resolve(normalizedAppRoot, "node_modules", ...normalizedPackageId.split("/"));
-  const candidateDescriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
-  if (!(await fileExists(candidateDescriptorPath))) {
-    return "";
-  }
-
-  return candidateRoot;
-}
-
-async function loadLocalWorkspacePackageIdIndex() {
-  if (LOCAL_WORKSPACE_PACKAGE_ID_INDEX instanceof Map) {
-    return LOCAL_WORKSPACE_PACKAGE_ID_INDEX;
-  }
-
-  const repoRoot = path.resolve(CLI_PACKAGE_ROOT, "..", "..");
-  const parentDirectories = [
-    path.join(repoRoot, "packages"),
-    path.join(repoRoot, "tooling")
-  ];
-  const packageIdIndex = new Map();
-
-  for (const parentDirectory of parentDirectories) {
-    if (!(await fileExists(parentDirectory))) {
-      continue;
-    }
-
-    const entries = await readdir(parentDirectory, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) {
-        continue;
-      }
-
-      const candidateRoot = path.join(parentDirectory, entry.name);
-      const packageJsonPath = path.join(candidateRoot, "package.json");
-      const descriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
-      if (!(await fileExists(packageJsonPath)) || !(await fileExists(descriptorPath))) {
-        continue;
-      }
-
-      let packageJson = {};
-      try {
-        packageJson = await readJsonFile(packageJsonPath);
-      } catch {
-        continue;
-      }
-
-      const packageId = String(packageJson?.name || "").trim();
-      if (!packageId.startsWith("@jskit-ai/")) {
-        continue;
-      }
-      if (packageIdIndex.has(packageId)) {
-        continue;
-      }
-      packageIdIndex.set(packageId, candidateRoot);
-    }
-  }
-
-  LOCAL_WORKSPACE_PACKAGE_ID_INDEX = packageIdIndex;
-  return packageIdIndex;
-}
-
-async function resolvePackageRootFromLocalWorkspace({ packageId }) {
-  const normalizedPackageId = String(packageId || "").trim();
-  if (!normalizedPackageId.startsWith("@jskit-ai/")) {
-    return "";
-  }
-  if (LOCAL_WORKSPACE_PACKAGE_ROOTS.has(normalizedPackageId)) {
-    return LOCAL_WORKSPACE_PACKAGE_ROOTS.get(normalizedPackageId);
-  }
-
-  const packageIdIndex = await loadLocalWorkspacePackageIdIndex();
-  const packageRoot = String(packageIdIndex.get(normalizedPackageId) || "").trim();
-  LOCAL_WORKSPACE_PACKAGE_ROOTS.set(normalizedPackageId, packageRoot);
-  return packageRoot;
-}
-
-async function resolvePackageTemplateRoot({ packageEntry, appRoot }) {
-  const packageRoot = String(packageEntry?.rootDir || "").trim();
-  if (packageRoot) {
-    return packageRoot;
-  }
-
-  const installedPackageRoot = await resolvePackageRootFromNodeModules({
-    appRoot,
-    packageId: packageEntry?.packageId
-  });
-  if (installedPackageRoot) {
-    return installedPackageRoot;
-  }
-
-  const localWorkspacePackageRoot = await resolvePackageRootFromLocalWorkspace({
-    packageId: packageEntry?.packageId
-  });
-  if (localWorkspacePackageRoot) {
-    return localWorkspacePackageRoot;
-  }
-
-  return await materializePackageRootFromRegistry({ packageEntry, appRoot });
-}
-
-async function cleanupMaterializedPackageRoots() {
-  for (const tempDirectory of MATERIALIZED_PACKAGE_TEMP_DIRECTORIES) {
-    await rm(tempDirectory, { recursive: true, force: true }).catch(() => {});
-  }
-  MATERIALIZED_PACKAGE_TEMP_DIRECTORIES.clear();
-  MATERIALIZED_PACKAGE_ROOTS.clear();
-  LOCAL_WORKSPACE_PACKAGE_ROOTS.clear();
-  LOCAL_WORKSPACE_PACKAGE_ID_INDEX = null;
-}
-
-function interpolateFileMutationRecord(mutation, options, packageId) {
-  const mutationKey = String(
-    mutation?.id || mutation?.to || mutation?.toSurface || mutation?.from || "files"
-  ).trim();
-  const interpolate = (value, field) =>
-    interpolateOptionValue(String(value || ""), options, packageId, `${mutationKey}.${field}`);
-
-  return {
-    ...mutation,
-    from: interpolate(mutation.from, "from"),
-    to: interpolate(mutation.to, "to"),
-    toSurface: interpolate(mutation.toSurface, "toSurface"),
-    toSurfacePath: interpolate(mutation.toSurfacePath, "toSurfacePath"),
-    toDir: interpolate(mutation.toDir, "toDir"),
-    extension: interpolate(mutation.extension, "extension"),
-    id: interpolate(mutation.id, "id"),
-    category: interpolate(mutation.category, "category"),
-    reason: interpolate(mutation.reason, "reason"),
-    templateContext: mutation.templateContext
-      ? {
-          entrypoint: interpolate(mutation.templateContext.entrypoint, "templateContext.entrypoint"),
-          export: interpolate(mutation.templateContext.export, "templateContext.export")
-        }
-      : null
-  };
-}
-
-function applyTemplateContextReplacements(sourceContent, replacements) {
-  let output = String(sourceContent || "");
-  for (const [placeholder, value] of Object.entries(ensureObject(replacements))) {
-    const normalizedPlaceholder = String(placeholder || "");
-    if (!normalizedPlaceholder) {
-      continue;
-    }
-    output = output.split(normalizedPlaceholder).join(String(value == null ? "" : value));
-  }
-  return output;
-}
-
-async function copyTemplateFile(
-  sourcePath,
-  targetPath,
-  options,
-  packageId,
-  interpolationKey,
-  templateContextReplacements = null
-) {
-  const sourceContent = await readFile(sourcePath, "utf8");
-  let renderedContent = sourceContent.includes("${")
-    ? interpolateOptionValue(sourceContent, options, packageId, interpolationKey)
-    : sourceContent;
-  if (templateContextReplacements) {
-    renderedContent = applyTemplateContextReplacements(renderedContent, templateContextReplacements);
-  }
-
-  await mkdir(path.dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, renderedContent, "utf8");
-}
-
-async function resolveTemplateContextReplacementsForMutation({
-  packageEntry,
-  mutation,
-  options,
-  appRoot,
-  sourcePath,
-  targetPaths
-} = {}) {
-  const templateContext = ensureObject(mutation?.templateContext);
-  const hasTemplateContext = Object.keys(templateContext).length > 0;
-  const entrypoint = String(templateContext.entrypoint || "").trim();
-  if (!hasTemplateContext) {
-    return null;
-  }
-  if (!entrypoint) {
-    throw createCliError(
-      `Invalid files mutation in ${packageEntry.packageId}: templateContext.entrypoint is required when templateContext is set.`
-    );
-  }
-  const exportName = String(templateContext.export || "").trim() || "buildTemplateContext";
-  const resolvedEntrypointPath = resolveAppRelativePathWithinRoot(
-    packageEntry.rootDir,
-    entrypoint,
-    `${packageEntry.packageId} files mutation templateContext.entrypoint`
-  );
-  const absoluteEntrypointPath = resolvedEntrypointPath.absolutePath;
-  if (!(await fileExists(absoluteEntrypointPath))) {
-    throw createCliError(
-      `Invalid files mutation in ${packageEntry.packageId}: templateContext.entrypoint not found at ${entrypoint}.`
-    );
-  }
-
-  let moduleNamespace = null;
-  try {
-    moduleNamespace = await import(`${pathToFileURL(absoluteEntrypointPath).href}?t=${Date.now()}_${Math.random()}`);
-  } catch (error) {
-    throw createCliError(
-      `Unable to load templateContext entrypoint ${entrypoint} for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
-    );
-  }
-
-  const resolver = moduleNamespace?.[exportName];
-  if (typeof resolver !== "function") {
-    throw createCliError(
-      `Invalid files mutation in ${packageEntry.packageId}: templateContext export "${exportName}" is not a function.`
-    );
-  }
-
-  let replacements = null;
-  try {
-    replacements = await resolver({
-      packageId: packageEntry.packageId,
-      packageRoot: packageEntry.rootDir,
-      appRoot,
-      options: Object.freeze({ ...ensureObject(options) }),
-      mutation: Object.freeze({ ...ensureObject(mutation) }),
-      sourcePath,
-      targetPaths: Object.freeze([...ensureArray(targetPaths)])
-    });
-  } catch (error) {
-    throw createCliError(
-      `templateContext export "${exportName}" failed for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
-    );
-  }
-
-  if (replacements == null) {
-    return null;
-  }
-  if (!replacements || typeof replacements !== "object" || Array.isArray(replacements)) {
-    throw createCliError(
-      `Invalid files mutation in ${packageEntry.packageId}: templateContext export "${exportName}" must return an object map of placeholder replacements.`
-    );
-  }
-
-  const normalizedReplacements = {};
-  for (const [placeholder, value] of Object.entries(replacements)) {
-    const normalizedPlaceholder = String(placeholder || "").trim();
-    if (!normalizedPlaceholder) {
-      continue;
-    }
-    normalizedReplacements[normalizedPlaceholder] = String(value == null ? "" : value);
-  }
-
-  return Object.freeze(normalizedReplacements);
-}
-
-function normalizeSurfaceIdForMutation(value = "") {
-  return String(value || "")
-    .trim()
-    .toLowerCase();
-}
-
-function parseSurfaceIdListForMutation(value = "") {
-  const sourceValues = Array.isArray(value) ? value : [value];
-  const surfaceIds = [];
-  const seen = new Set();
-
-  for (const sourceValue of sourceValues) {
-    const parsed = String(sourceValue || "")
-      .split(",")
-      .map((entry) => normalizeSurfaceIdForMutation(entry))
-      .filter(Boolean);
-    for (const surfaceId of parsed) {
-      if (seen.has(surfaceId)) {
-        continue;
-      }
-      seen.add(surfaceId);
-      surfaceIds.push(surfaceId);
-    }
-  }
-
-  return Object.freeze(surfaceIds);
-}
-
-function normalizeSurfacePagesRootForMutation(value = "") {
-  const rawValue = String(value || "").trim();
-  if (!rawValue || rawValue === "/") {
-    return "";
-  }
-
-  return rawValue
-    .replace(/\\/g, "/")
-    .replace(/\/{2,}/g, "/")
-    .replace(/^\/+|\/+$/g, "");
-}
-
-function normalizeSurfacePathForMutation(value = "", { context = "toSurfacePath" } = {}) {
-  const rawValue = String(value || "").trim();
-  if (!rawValue) {
-    return "";
-  }
-
-  const normalized = rawValue
-    .replace(/\\/g, "/")
-    .replace(/\/{2,}/g, "/")
-    .replace(/^\.\/+/, "")
-    .replace(/^\/+/, "");
-  const segments = normalized.split("/");
-  const materializedSegments = [];
-  for (const segmentValue of segments) {
-    const segment = String(segmentValue || "").trim();
-    if (!segment || segment === ".") {
-      continue;
-    }
-    if (segment === "..") {
-      throw createCliError(`Invalid ${context}: path traversal is not allowed.`);
-    }
-    materializedSegments.push(segment);
-  }
-
-  return materializedSegments.join("/");
-}
-
-function resolveSurfaceDefinitionFromConfigForMutation({
-  configContext = {},
-  surfaceId = "",
-  packageId = ""
-} = {}) {
-  const normalizedSurfaceId = normalizeSurfaceIdForMutation(surfaceId);
-  if (!normalizedSurfaceId) {
-    throw createCliError(`Invalid files mutation in ${packageId}: "toSurface" is required when using surface targeting.`);
-  }
-
-  const publicConfig = ensureObject(configContext.public);
-  const mergedConfig = ensureObject(configContext.merged);
-  const sourceDefinitions = ensureObject(publicConfig.surfaceDefinitions);
-  const fallbackDefinitions = ensureObject(mergedConfig.surfaceDefinitions);
-  const surfaceDefinitions =
-    Object.keys(sourceDefinitions).length > 0 ? sourceDefinitions : fallbackDefinitions;
-
-  for (const [key, value] of Object.entries(surfaceDefinitions)) {
-    const definition = ensureObject(value);
-    const definitionId = normalizeSurfaceIdForMutation(definition.id || key);
-    if (definitionId !== normalizedSurfaceId) {
-      continue;
-    }
-    if (definition.enabled === false) {
-      throw createCliError(
-        `Invalid files mutation in ${packageId}: surface "${normalizedSurfaceId}" is disabled.`
-      );
-    }
-    if (!Object.prototype.hasOwnProperty.call(definition, "pagesRoot")) {
-      throw createCliError(
-        `Invalid files mutation in ${packageId}: surface "${normalizedSurfaceId}" is missing pagesRoot in config/public.js.`
-      );
-    }
-
-    return Object.freeze({
-      ...definition,
-      id: definitionId,
-      pagesRoot: normalizeSurfacePagesRootForMutation(definition.pagesRoot)
-    });
-  }
-
-  throw createCliError(
-    `Invalid files mutation in ${packageId}: unknown surface "${normalizedSurfaceId}" in config/public.js.`
-  );
-}
-
-function resolveSurfaceTargetPathsForMutation({
-  appRoot,
-  packageId,
-  mutation,
-  configContext
-} = {}) {
-  const normalizedSurfaceIds = parseSurfaceIdListForMutation(mutation.toSurface);
-  if (normalizedSurfaceIds.length < 1) {
-    throw createCliError(`Invalid files mutation in ${packageId}: "toSurface" is required when using surface targeting.`);
-  }
-
-  if (mutation.toSurfaceRoot === true) {
-    if (String(mutation.toSurfacePath || "").trim()) {
-      throw createCliError(
-        `Invalid files mutation in ${packageId}: "toSurfacePath" cannot be combined with "toSurfaceRoot".`
-      );
-    }
-
-    const targetPaths = [];
-    for (const surfaceId of normalizedSurfaceIds) {
-      const definition = resolveSurfaceDefinitionFromConfigForMutation({
-        configContext,
-        surfaceId,
-        packageId
-      });
-      if (!definition.pagesRoot) {
-        throw createCliError(
-          `Invalid files mutation in ${packageId}: root surface "${surfaceId}" cannot use "toSurfaceRoot".`
-        );
-      }
-      targetPaths.push(path.join(appRoot, "src/pages", `${definition.pagesRoot}.vue`));
-    }
-    return Object.freeze(targetPaths);
-  }
-
-  const normalizedSurfacePath = normalizeSurfacePathForMutation(mutation.toSurfacePath, {
-    context: "toSurfacePath"
-  });
-  if (!normalizedSurfacePath) {
-    throw createCliError(
-      `Invalid files mutation in ${packageId}: "toSurfacePath" is required when using "toSurface".`
-    );
-  }
-
-  const targetPaths = [];
-  for (const surfaceId of normalizedSurfaceIds) {
-    const definition = resolveSurfaceDefinitionFromConfigForMutation({
-      configContext,
-      surfaceId,
-      packageId
-    });
-    const basePagesDirectory = definition.pagesRoot
-      ? path.join(appRoot, "src/pages", definition.pagesRoot)
-      : path.join(appRoot, "src/pages");
-    targetPaths.push(path.join(basePagesDirectory, normalizedSurfacePath));
-  }
-  return Object.freeze(targetPaths);
-}
-
-async function applyFileMutations(
-  packageEntry,
-  options,
-  appRoot,
-  fileMutations,
-  managedFiles,
-  managedMigrations,
-  touchedFiles,
-  warnings = [],
-  precomputedTemplateContextByMutationIndex = null
-) {
-  const mutationList = ensureArray(fileMutations);
-  const managedMigrationById = new Map();
-  for (const managedMigrationValue of ensureArray(managedMigrations)) {
-    const managedMigration = ensureObject(managedMigrationValue);
-    const migrationId = String(managedMigration.id || "").trim();
-    if (!migrationId) {
-      continue;
-    }
-    managedMigrationById.set(migrationId, managedMigration);
-  }
-
-  for (const [mutationIndex, mutationValue] of mutationList.entries()) {
-    const normalizedMutation = normalizeFileMutationRecord(mutationValue);
-    const requiresConfigContext = Boolean(normalizedMutation.when?.config || normalizedMutation.toSurface);
-    const configContext = requiresConfigContext ? await loadMutationWhenConfigContext(appRoot) : {};
-    if (
-      !shouldApplyMutationWhen(normalizedMutation.when, {
-        options,
-        configContext,
-        packageId: packageEntry.packageId,
-        mutationContext: "files mutation"
-      })
-    ) {
-      continue;
-    }
-
-    const mutation = interpolateFileMutationRecord(normalizedMutation, options, packageEntry.packageId);
-    const operation = mutation.op || "copy-file";
-
-    if (operation === "install-migration") {
-      const rawMutation = ensureObject(mutationValue);
-      if (Object.hasOwn(rawMutation, "preserveOnRemove")) {
-        warnings.push(
-          `${packageEntry.packageId}: install-migration ignores preserveOnRemove (migrations are always preserved on remove).`
-        );
-      }
-
-      const from = mutation.from;
-      const toDir = mutation.toDir || "migrations";
-      if (!from) {
-        throw createCliError(`Invalid install-migration mutation in ${packageEntry.packageId}: \"from\" is required.`);
-      }
-      const migrationId = normalizeMigrationId(mutation.id, packageEntry.packageId);
-
-      const sourcePath = path.join(packageEntry.rootDir, from);
-      if (!(await fileExists(sourcePath))) {
-        throw createCliError(`Missing migration template source ${sourcePath} for ${packageEntry.packageId}.`);
-      }
-
-      const hasPrecomputedTemplateContext =
-        precomputedTemplateContextByMutationIndex instanceof Map &&
-        precomputedTemplateContextByMutationIndex.has(mutationIndex);
-      const templateContextReplacements = hasPrecomputedTemplateContext
-        ? precomputedTemplateContextByMutationIndex.get(mutationIndex)
-        : await resolveTemplateContextReplacementsForMutation({
-            packageEntry,
-            mutation,
-            options,
-            appRoot,
-            sourcePath,
-            targetPaths: [path.join(appRoot, toDir)]
-          });
-
-      const sourceContent = await readFile(sourcePath, "utf8");
-      let renderedSourceContent = sourceContent.includes("${")
-        ? interpolateOptionValue(sourceContent, options, packageEntry.packageId, `${mutation.id || from}.source`)
-        : sourceContent;
-      if (templateContextReplacements) {
-        renderedSourceContent = applyTemplateContextReplacements(renderedSourceContent, templateContextReplacements);
-      }
-      const sourceExtension = normalizeMigrationExtension(path.extname(from), ".cjs");
-      const extension = normalizeMigrationExtension(mutation.extension, sourceExtension);
-      const sourceHash = hashBuffer(Buffer.from(renderedSourceContent, "utf8"));
-
-      const existingManagedRecord = managedMigrationById.get(migrationId);
-      if (existingManagedRecord) {
-        const existingManagedPath = normalizeRelativePosixPath(String(existingManagedRecord.path || "").trim());
-        if (!existingManagedPath) {
-          throw createCliError(
-            `${packageEntry.packageId}: managed migration ${migrationId} is missing path in lock.`
-          );
-        }
-        const resolvedManagedPath = resolveAppRelativePathWithinRoot(
-          appRoot,
-          existingManagedPath,
-          `${packageEntry.packageId} managed migration path for ${migrationId}`
-        );
-        const relativePath = resolvedManagedPath.relativePath;
-        const absolutePath = resolvedManagedPath.absolutePath;
-        let existingSourceHash = String(existingManagedRecord.hash || "").trim();
-        if (!existingSourceHash && existingManagedPath && (await fileExists(absolutePath))) {
-          const existingSource = await readFile(absolutePath);
-          existingSourceHash = hashBuffer(existingSource);
-        }
-
-        if (existingSourceHash && existingSourceHash !== sourceHash) {
-          throw createCliError(
-            `${packageEntry.packageId}: migration ${migrationId} changed after install. Keep migrations immutable and create a new migration id.`
-          );
-        }
-
-        if (!(await fileExists(absolutePath))) {
-          await mkdir(path.dirname(absolutePath), { recursive: true });
-          await writeFile(absolutePath, renderedSourceContent, "utf8");
-          touchedFiles.add(relativePath);
-        }
-
-        const nextManagedRecord = {
-          ...existingManagedRecord,
-          id: migrationId,
-          path: relativePath,
-          hash: sourceHash,
-          skipped: true,
-          reason: mutation.reason || String(existingManagedRecord.reason || ""),
-          category: mutation.category || String(existingManagedRecord.category || "")
-        };
-        managedMigrationById.set(migrationId, nextManagedRecord);
-        upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
-        warnings.push(
-          `${packageEntry.packageId}: skipped migration ${migrationId} (already managed at ${nextManagedRecord.path}).`
-        );
-        continue;
-      }
-
-      const existingPathById = await findExistingManagedMigrationPathById({
-        appRoot,
-        toDir,
-        packageId: packageEntry.packageId,
-        migrationId,
-        extension
-      });
-      if (existingPathById) {
-        const existingSource = await readFile(existingPathById.absolutePath);
-        const existingSourceHash = hashBuffer(existingSource);
-        if (existingSourceHash !== sourceHash) {
-          throw createCliError(
-            `${packageEntry.packageId}: migration ${migrationId} changed after install. Keep migrations immutable and create a new migration id.`
-          );
-        }
-        const nextManagedRecord = {
-          id: migrationId,
-          path: existingPathById.relativePath,
-          hash: sourceHash,
-          skipped: true,
-          reason: mutation.reason,
-          category: mutation.category
-        };
-        managedMigrationById.set(migrationId, nextManagedRecord);
-        upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
-        warnings.push(
-          `${packageEntry.packageId}: skipped migration ${migrationId} (already exists at ${nextManagedRecord.path}).`
-        );
-        continue;
-      }
-
-      const baseNowMs = Date.now();
-      let targetPath = null;
-      for (let secondOffset = 0; secondOffset < 86400; secondOffset += 1) {
-        const timestamp = formatMigrationTimestamp(new Date(baseNowMs + secondOffset * 1000));
-        const candidateRelativePath = buildManagedMigrationRelativePath({
-          toDir,
-          packageId: packageEntry.packageId,
-          migrationId,
-          extension,
-          timestamp
-        });
-        const candidatePath = resolveAppRelativePathWithinRoot(
-          appRoot,
-          candidateRelativePath,
-          `${packageEntry.packageId} migration path for ${migrationId}`
-        );
-        if (await fileExists(candidatePath.absolutePath)) {
-          continue;
-        }
-        targetPath = candidatePath;
-        break;
-      }
-
-      if (!targetPath) {
-        throw createCliError(
-          `${packageEntry.packageId}: unable to allocate migration filename for ${migrationId} in ${toDir}.`
-        );
-      }
-
-      const relativePath = targetPath.relativePath;
-      const absolutePath = targetPath.absolutePath;
-      await mkdir(path.dirname(absolutePath), { recursive: true });
-      await writeFile(absolutePath, renderedSourceContent, "utf8");
-      touchedFiles.add(relativePath);
-
-      const nextManagedRecord = {
-        id: migrationId,
-        path: relativePath,
-        hash: sourceHash,
-        skipped: false,
-        reason: mutation.reason,
-        category: mutation.category
-      };
-      managedMigrationById.set(migrationId, nextManagedRecord);
-      upsertManagedMigrationRecord(managedMigrations, nextManagedRecord);
-      continue;
-    }
-
-    if (operation !== "copy-file") {
-      throw createCliError(`Unsupported files mutation op \"${operation}\" in ${packageEntry.packageId}.`);
-    }
-
-    const from = mutation.from;
-    const to = mutation.to;
-    const toSurface = mutation.toSurface;
-    if (to && toSurface) {
-      throw createCliError(
-        `Invalid files mutation in ${packageEntry.packageId}: "to" and "toSurface" cannot both be set.`
-      );
-    }
-    if (!from || (!to && !toSurface)) {
-      throw createCliError(
-        `Invalid files mutation in ${packageEntry.packageId}: "from" plus one destination ("to" or "toSurface") are required.`
-      );
-    }
-
-    const sourcePath = path.join(packageEntry.rootDir, from);
-    if (!(await fileExists(sourcePath))) {
-      throw createCliError(`Missing template source ${sourcePath} for ${packageEntry.packageId}.`);
-    }
-
-    const targetPaths = toSurface
-      ? resolveSurfaceTargetPathsForMutation({
-          appRoot,
-          packageId: packageEntry.packageId,
-          mutation,
-          configContext
-        })
-      : [path.join(appRoot, to)];
-    const hasPrecomputedTemplateContext =
-      precomputedTemplateContextByMutationIndex instanceof Map &&
-      precomputedTemplateContextByMutationIndex.has(mutationIndex);
-    const templateContextReplacements = hasPrecomputedTemplateContext
-      ? precomputedTemplateContextByMutationIndex.get(mutationIndex)
-      : await resolveTemplateContextReplacementsForMutation({
-          packageEntry,
-          mutation,
-          options,
-          appRoot,
-          sourcePath,
-          targetPaths
-        });
-    for (const targetPath of targetPaths) {
-      const previous = await readFileBufferIfExists(targetPath);
-      await copyTemplateFile(
-        sourcePath,
-        targetPath,
-        options,
-        packageEntry.packageId,
-        `${mutation.id || to || from}.source`,
-        templateContextReplacements
-      );
-      const nextBuffer = await readFile(targetPath);
-
-      managedFiles.push({
-        path: normalizeRelativePath(appRoot, targetPath),
-        hash: hashBuffer(nextBuffer),
-        hadPrevious: previous.exists,
-        previousContentBase64: previous.exists ? previous.buffer.toString("base64") : "",
-        preserveOnRemove: mutation.preserveOnRemove,
-        reason: mutation.reason,
-        category: mutation.category,
-        id: mutation.id
-      });
-      touchedFiles.add(normalizeRelativePath(appRoot, targetPath));
-    }
-  }
-}
-
-async function preflightFileMutationTemplateContexts(
-  packageEntry,
-  options,
-  appRoot,
-  fileMutations
-) {
-  const mutationList = ensureArray(fileMutations);
-  const replacementsByMutationIndex = new Map();
-
-  for (const [mutationIndex, mutationValue] of mutationList.entries()) {
-    const normalizedMutation = normalizeFileMutationRecord(mutationValue);
-    const requiresConfigContext = Boolean(normalizedMutation.when?.config || normalizedMutation.toSurface);
-    const configContext = requiresConfigContext ? await loadMutationWhenConfigContext(appRoot) : {};
-    if (
-      !shouldApplyMutationWhen(normalizedMutation.when, {
-        options,
-        configContext,
-        packageId: packageEntry.packageId,
-        mutationContext: "files mutation"
-      })
-    ) {
-      continue;
-    }
-
-    const mutation = interpolateFileMutationRecord(normalizedMutation, options, packageEntry.packageId);
-    const templateContext = ensureObject(mutation.templateContext);
-    if (Object.keys(templateContext).length < 1) {
-      continue;
-    }
-
-    const operation = mutation.op || "copy-file";
-    if (operation !== "copy-file" && operation !== "install-migration") {
-      continue;
-    }
-
-    const from = mutation.from;
-    const to = mutation.to;
-    const toSurface = mutation.toSurface;
-    if (!from) {
-      throw createCliError(
-        `Invalid files mutation in ${packageEntry.packageId}: "from" is required.`
-      );
-    }
-    if (operation === "copy-file") {
-      if (to && toSurface) {
-        throw createCliError(
-          `Invalid files mutation in ${packageEntry.packageId}: "to" and "toSurface" cannot both be set.`
-        );
-      }
-      if (!to && !toSurface) {
-        throw createCliError(
-          `Invalid files mutation in ${packageEntry.packageId}: "from" plus one destination ("to" or "toSurface") are required.`
-        );
-      }
-    }
-
-    const sourcePath = path.join(packageEntry.rootDir, from);
-    if (!(await fileExists(sourcePath))) {
-      throw createCliError(`Missing template source ${sourcePath} for ${packageEntry.packageId}.`);
-    }
-
-    const targetPaths = operation === "copy-file"
-      ? toSurface
-        ? resolveSurfaceTargetPathsForMutation({
-            appRoot,
-            packageId: packageEntry.packageId,
-            mutation,
-            configContext
-          })
-        : [path.join(appRoot, to)]
-      : [path.join(appRoot, mutation.toDir || "migrations")];
-    const replacements = await resolveTemplateContextReplacementsForMutation({
-      packageEntry,
-      mutation,
-      options,
-      appRoot,
-      sourcePath,
-      targetPaths
-    });
-    replacementsByMutationIndex.set(mutationIndex, replacements);
-  }
-
-  return replacementsByMutationIndex;
-}
-
-async function applyTextMutations(packageEntry, appRoot, textMutations, options, managedText, touchedFiles) {
-  for (const mutation of textMutations) {
-    const when = normalizeMutationWhen(mutation?.when);
-    const configContext = when?.config ? await loadMutationWhenConfigContext(appRoot) : {};
-    if (
-      !shouldApplyMutationWhen(when, {
-        options,
-        configContext,
-        packageId: packageEntry.packageId,
-        mutationContext: "text mutation"
-      })
-    ) {
-      continue;
-    }
-
-    const operation = String(mutation?.op || "").trim();
-    if (operation === "upsert-env") {
-      const relativeFile = String(mutation?.file || "").trim();
-      const key = String(mutation?.key || "").trim();
-      if (!relativeFile || !key) {
-        throw createCliError(`Invalid upsert-env mutation in ${packageEntry.packageId}: "file" and "key" are required.`);
-      }
-
-      const absoluteFile = path.join(appRoot, relativeFile);
-      const previous = await readFileBufferIfExists(absoluteFile);
-      const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
-      const resolvedValue = interpolateOptionValue(mutation?.value || "", options, packageEntry.packageId, key);
-      const upserted = upsertEnvValue(previousContent, key, resolvedValue);
-
-      await mkdir(path.dirname(absoluteFile), { recursive: true });
-      await writeFile(absoluteFile, upserted.content, "utf8");
-
-      const recordKey = `${relativeFile}::${String(mutation?.id || key)}`;
-      managedText[recordKey] = {
-        file: relativeFile,
-        op: "upsert-env",
-        key,
-        value: resolvedValue,
-        hadPrevious: upserted.hadPrevious,
-        previousValue: upserted.previousValue,
-        reason: String(mutation?.reason || ""),
-        category: String(mutation?.category || ""),
-        id: String(mutation?.id || "")
-      };
-      touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
-      continue;
-    }
-
-    if (operation === "append-text") {
-      const relativeFile = String(mutation?.file || "").trim();
-      const snippet = String(mutation?.value || "");
-      const position = String(mutation?.position || "bottom").trim().toLowerCase();
-      if (!relativeFile) {
-        throw createCliError(`Invalid append-text mutation in ${packageEntry.packageId}: "file" is required.`);
-      }
-      if (position !== "top" && position !== "bottom") {
-        throw createCliError(`Invalid append-text mutation in ${packageEntry.packageId}: "position" must be "top" or "bottom".`);
-      }
-      await validateSettingsFieldsContractMutationTarget({
-        appRoot,
-        relativeFile,
-        packageId: packageEntry.packageId
-      });
-
-      const absoluteFile = path.join(appRoot, relativeFile);
-      const previous = await readFileBufferIfExists(absoluteFile);
-      const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
-      const mutationId = String(mutation?.id || "").trim() || "append-text";
-      const resolvedSnippet = interpolateOptionValue(snippet, options, packageEntry.packageId, mutationId);
-      const skipChecks = normalizeSkipChecks(mutation?.skipIfContains)
-        .map((entry) => interpolateOptionValue(entry, options, packageEntry.packageId, `${mutationId}.skipIfContains`))
-        .filter((entry) => String(entry || "").trim().length > 0);
-
-      const shouldSkip = skipChecks.some((pattern) => previousContent.includes(String(pattern)));
-      if (shouldSkip) {
-        continue;
-      }
-
-      const appended = appendTextSnippet(previousContent, resolvedSnippet, position);
-      if (!appended.changed) {
-        continue;
-      }
-
-      await mkdir(path.dirname(absoluteFile), { recursive: true });
-      await writeFile(absoluteFile, appended.content, "utf8");
-
-      const recordKey = `${relativeFile}::${mutationId}`;
-      managedText[recordKey] = {
-        file: relativeFile,
-        op: "append-text",
-        value: resolvedSnippet,
-        position,
-        reason: String(mutation?.reason || ""),
-        category: String(mutation?.category || ""),
-        id: String(mutation?.id || "")
-      };
-      touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
-      continue;
-    }
-
-    throw createCliError(`Unsupported text mutation op "${operation}" in ${packageEntry.packageId}.`);
-  }
-}
-
-function normalizeMutationRelativeFilePath(value = "") {
-  return String(value || "")
-    .trim()
-    .replace(/\\/g, "/")
-    .replace(/\/{2,}/g, "/")
-    .replace(/^\.\/+/, "")
-    .replace(/^\/+/, "");
-}
-
-function resolveSettingsFieldsContractTarget(relativeFile = "") {
-  const normalizedRelativeFile = normalizeMutationRelativeFilePath(relativeFile);
-  if (!normalizedRelativeFile) {
-    return null;
-  }
-  const target = SETTINGS_FIELDS_CONTRACT_TARGETS[normalizedRelativeFile];
-  if (!target) {
-    return null;
-  }
-  return {
-    normalizedRelativeFile,
-    target
-  };
-}
-
-async function validateSettingsFieldsContractMutationTarget({
-  appRoot,
-  relativeFile,
-  packageId
-} = {}) {
-  const contractTarget = resolveSettingsFieldsContractTarget(relativeFile);
-  if (!contractTarget) {
-    return;
-  }
-
-  const { normalizedRelativeFile, target } = contractTarget;
-  const absoluteFile = path.join(appRoot, normalizedRelativeFile);
-  const existing = await readFileBufferIfExists(absoluteFile);
-  if (!existing.exists) {
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing. ` +
-      `Install @jskit-ai/users-core to scaffold ${target.contractId}.`
-    );
-  }
-
-  const source = existing.buffer.toString("utf8");
-  if (!source.includes(target.marker)) {
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing contract marker "${target.marker}".`
-    );
-  }
-  for (const snippet of target.requiredSnippets) {
-    if (source.includes(snippet)) {
-      continue;
-    }
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} must include "${snippet}" for ${target.contractId}.`
-    );
-  }
-}
-
-function isPositioningTextMutation(value = {}) {
-  const mutation = ensureObject(value);
-  const operation = String(mutation.op || "").trim();
-  if (operation !== "append-text") {
-    return false;
-  }
-  return normalizeMutationRelativeFilePath(mutation.file) === "src/placement.js";
-}
-
-function resolvePositioningMutations(descriptorMutations = {}) {
-  const mutations = ensureObject(descriptorMutations);
-  const files = ensureArray(mutations.files).filter((mutationValue) => {
-    const normalized = normalizeFileMutationRecord(mutationValue);
-    return Boolean(normalized.toSurface);
-  });
-  const text = ensureArray(mutations.text).filter((mutationValue) => isPositioningTextMutation(mutationValue));
-  return {
-    files,
-    text
-  };
-}
-
-function cloneManagedMap(value = {}) {
-  const cloned = {};
-  for (const [key, entry] of Object.entries(ensureObject(value))) {
-    cloned[key] = {
-      ...ensureObject(entry)
-    };
-  }
-  return cloned;
-}
-
-function cloneManagedArray(value = []) {
-  return ensureArray(value).map((entry) => ({
-    ...ensureObject(entry)
-  }));
-}
-
-function resolveManagedSourceRecord(packageEntry, existingInstall = {}) {
-  const existingSource = ensureObject(existingInstall.source);
-  if (Object.keys(existingSource).length > 0) {
-    return {
-      ...existingSource
-    };
-  }
-
-  const sourceRecord = {
-    type: String(packageEntry?.sourceType || "packages-directory"),
-    ...ensureObject(packageEntry?.source)
-  };
-  if (!sourceRecord.descriptorPath && String(packageEntry?.descriptorRelativePath || "").trim()) {
-    sourceRecord.descriptorPath = String(packageEntry.descriptorRelativePath).trim();
-  }
-  return sourceRecord;
-}
-
-async function applyPackagePositioning({
-  packageEntry,
-  packageOptions,
-  appRoot,
-  lock,
-  touchedFiles
-}) {
-  const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
-  if (Object.keys(existingInstall).length < 1) {
-    throw createCliError(`Package is not installed: ${packageEntry.packageId}`);
-  }
-
-  const existingManaged = ensureObject(existingInstall.managed);
-  const existingPackageJsonManaged = ensureObject(existingManaged.packageJson);
-  const nextManaged = {
-    packageJson: {
-      dependencies: cloneManagedMap(existingPackageJsonManaged.dependencies),
-      devDependencies: cloneManagedMap(existingPackageJsonManaged.devDependencies),
-      scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
-    },
-    text: cloneManagedMap(existingManaged.text),
-    vite: cloneManagedMap(existingManaged.vite),
-    files: cloneManagedArray(existingManaged.files),
-    migrations: cloneManagedArray(existingManaged.migrations)
-  };
-
-  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
-  const packageEntryForMutations =
-    templateRoot === packageEntry.rootDir
-      ? packageEntry
-      : {
-          ...packageEntry,
-          rootDir: templateRoot
-        };
-
-  const mutations = ensureObject(packageEntry.descriptor.mutations);
-  const positioningMutations = resolvePositioningMutations(mutations);
-  const appliedManagedFiles = [];
-  const appliedManagedText = {};
-  if (positioningMutations.files.length > 0) {
-    await applyFileMutations(
-      packageEntryForMutations,
-      packageOptions,
-      appRoot,
-      positioningMutations.files,
-      appliedManagedFiles,
-      [],
-      touchedFiles
-    );
-  }
-  if (positioningMutations.text.length > 0) {
-    await applyTextMutations(
-      packageEntryForMutations,
-      appRoot,
-      positioningMutations.text,
-      packageOptions,
-      appliedManagedText,
-      touchedFiles
-    );
-  }
-
-  if (appliedManagedFiles.length > 0) {
-    const replacedPaths = new Set(
-      appliedManagedFiles
-        .map((entry) => String(ensureObject(entry).path || "").trim())
-        .filter(Boolean)
-    );
-    const retainedFiles = nextManaged.files.filter((entry) => {
-      const managedPath = String(ensureObject(entry).path || "").trim();
-      return !managedPath || !replacedPaths.has(managedPath);
-    });
-    nextManaged.files = [...retainedFiles, ...appliedManagedFiles];
-  }
-
-  if (Object.keys(appliedManagedText).length > 0) {
-    nextManaged.text = {
-      ...nextManaged.text,
-      ...appliedManagedText
-    };
-  }
-
-  const managedRecord = {
-    ...existingInstall,
-    packageId: packageEntry.packageId,
-    version: packageEntry.version,
-    source: resolveManagedSourceRecord(packageEntry, existingInstall),
-    managed: nextManaged,
-    options: {
-      ...ensureObject(packageOptions)
-    },
-    installedAt: String(existingInstall.installedAt || new Date().toISOString())
-  };
-  lock.installedPackages[packageEntry.packageId] = managedRecord;
-  return managedRecord;
-}
-
-async function applyPackageMigrationsOnly({
-  packageEntry,
-  packageOptions,
-  appRoot,
-  lock,
-  touchedFiles
-}) {
-  const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
-  if (Object.keys(existingInstall).length < 1) {
-    throw createCliError(`Package is not installed: ${packageEntry.packageId}`);
-  }
-
-  const existingManaged = ensureObject(existingInstall.managed);
-  const existingPackageJsonManaged = ensureObject(existingManaged.packageJson);
-  const nextManaged = {
-    packageJson: {
-      dependencies: cloneManagedMap(existingPackageJsonManaged.dependencies),
-      devDependencies: cloneManagedMap(existingPackageJsonManaged.devDependencies),
-      scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
-    },
-    text: cloneManagedMap(existingManaged.text),
-    vite: cloneManagedMap(existingManaged.vite),
-    files: cloneManagedArray(existingManaged.files),
-    migrations: cloneManagedArray(existingManaged.migrations)
-  };
-
-  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
-  const packageEntryForMutations =
-    templateRoot === packageEntry.rootDir
-      ? packageEntry
-      : {
-          ...packageEntry,
-          rootDir: templateRoot
-        };
-  const mutations = ensureObject(packageEntry.descriptor.mutations);
-  const migrationFileMutations = ensureArray(mutations.files).filter((mutationValue) => {
-    const normalized = normalizeFileMutationRecord(mutationValue);
-    const operation = String(normalized.op || "copy-file").trim();
-    return operation === "install-migration";
-  });
-  const mutationWarnings = [];
-
-  if (migrationFileMutations.length > 0) {
-    await applyFileMutations(
-      packageEntryForMutations,
-      packageOptions,
-      appRoot,
-      migrationFileMutations,
-      [],
-      nextManaged.migrations,
-      touchedFiles,
-      mutationWarnings
-    );
-  }
-
-  const managedRecord = {
-    ...existingInstall,
-    packageId: packageEntry.packageId,
-    source: resolveManagedSourceRecord(packageEntry, existingInstall),
-    managed: nextManaged,
-    options: {
-      ...ensureObject(packageOptions)
-    },
-    migrationSyncVersion: packageEntry.version,
-    installedAt: String(existingInstall.installedAt || new Date().toISOString())
-  };
-  lock.installedPackages[packageEntry.packageId] = managedRecord;
-  if (mutationWarnings.length > 0) {
-    managedRecord.warnings = mutationWarnings;
-  }
-  return managedRecord;
-}
-
-async function applyPackageInstall({
-  packageEntry,
-  packageOptions,
-  appRoot,
-  appPackageJson,
-  lock,
-  packageRegistry,
-  touchedFiles
-}) {
-  const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
-  const existingManaged = ensureObject(existingInstall.managed);
-  await removeManagedViteProxyEntries({
-    appRoot,
-    packageId: packageEntry.packageId,
-    managedViteChanges: ensureObject(existingManaged.vite),
-    touchedFiles
-  });
-
-  const managedRecord = createManagedRecordBase(packageEntry, packageOptions);
-  managedRecord.managed.migrations = cloneManagedArray(existingManaged.migrations);
-  const generatorPackage = isGeneratorPackageEntry(packageEntry);
-  const mutationWarnings = [];
-  const mutations = ensureObject(packageEntry.descriptor.mutations);
-  const fileMutations = ensureArray(mutations.files);
-  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
-  const packageEntryForMutations =
-    templateRoot === packageEntry.rootDir
-      ? packageEntry
-      : {
-          ...packageEntry,
-          rootDir: templateRoot
-        };
-
-  const precomputedTemplateContextByMutationIndex = await preflightFileMutationTemplateContexts(
-    packageEntryForMutations,
-    packageOptions,
-    appRoot,
-    fileMutations
-  );
-
-  const mutationDependencies = ensureObject(mutations.dependencies);
-  const runtimeDependencies = ensureObject(mutationDependencies.runtime);
-  const devDependencies = ensureObject(mutationDependencies.dev);
-  const mutationScripts = ensureObject(ensureObject(mutations.packageJson).scripts);
-
-  for (const [rawDependencyId, rawDependencyVersion] of Object.entries(runtimeDependencies)) {
-    const dependencyId = interpolateOptionValue(
-      rawDependencyId,
-      packageOptions,
-      packageEntry.packageId,
-      `dependencies.runtime.${rawDependencyId}.id`
-    );
-    const dependencyVersion = interpolateOptionValue(
-      String(rawDependencyVersion || ""),
-      packageOptions,
-      packageEntry.packageId,
-      `dependencies.runtime.${rawDependencyId}.value`
-    );
-    if (!dependencyId) {
-      throw createCliError(
-        `Invalid runtime dependency key after option interpolation in ${packageEntry.packageId}: ${rawDependencyId}`
-      );
-    }
-
-    const localPackage = packageRegistry.get(dependencyId);
-    const existingRuntimeDependencyValue = String(ensureObject(appPackageJson.dependencies)[dependencyId] || "").trim();
-    const resolvedValue = localPackage
-      ? resolvePackageDependencySpecifier(localPackage, { existingValue: existingRuntimeDependencyValue })
-      : String(dependencyVersion);
-    const normalizedResolvedValue = normalizeJskitDependencySpecifier(dependencyId, resolvedValue);
-    const applied = applyPackageJsonField(appPackageJson, "dependencies", dependencyId, normalizedResolvedValue);
-    if (applied.changed) {
-      managedRecord.managed.packageJson.dependencies[dependencyId] = applied.managed;
-      touchedFiles.add("package.json");
-    }
-  }
-
-  for (const [rawDependencyId, rawDependencyVersion] of Object.entries(devDependencies)) {
-    const dependencyId = interpolateOptionValue(
-      rawDependencyId,
-      packageOptions,
-      packageEntry.packageId,
-      `dependencies.dev.${rawDependencyId}.id`
-    );
-    const dependencyVersion = interpolateOptionValue(
-      String(rawDependencyVersion || ""),
-      packageOptions,
-      packageEntry.packageId,
-      `dependencies.dev.${rawDependencyId}.value`
-    );
-    if (!dependencyId) {
-      throw createCliError(
-        `Invalid dev dependency key after option interpolation in ${packageEntry.packageId}: ${rawDependencyId}`
-      );
-    }
-
-    const localPackage = packageRegistry.get(dependencyId);
-    const existingDevDependencyValue = String(ensureObject(appPackageJson.devDependencies)[dependencyId] || "").trim();
-    const resolvedValue = localPackage
-      ? resolvePackageDependencySpecifier(localPackage, { existingValue: existingDevDependencyValue })
-      : String(dependencyVersion);
-    const normalizedResolvedValue = normalizeJskitDependencySpecifier(dependencyId, resolvedValue);
-    const applied = applyPackageJsonField(appPackageJson, "devDependencies", dependencyId, normalizedResolvedValue);
-    if (applied.changed) {
-      managedRecord.managed.packageJson.devDependencies[dependencyId] = applied.managed;
-      touchedFiles.add("package.json");
-    }
-  }
-
-  if (generatorPackage) {
-    const removedRuntimeDependency = removePackageJsonField(appPackageJson, "dependencies", packageEntry.packageId);
-    const removedDevDependency = removePackageJsonField(appPackageJson, "devDependencies", packageEntry.packageId);
-    if (removedRuntimeDependency || removedDevDependency) {
-      touchedFiles.add("package.json");
-    }
-  } else {
-    const existingSelfDependencyValue = String(ensureObject(appPackageJson.dependencies)[packageEntry.packageId] || "").trim();
-    const selfDependencyValue = resolvePackageDependencySpecifier(packageEntry, {
-      existingValue: existingSelfDependencyValue
-    });
-    const normalizedSelfDependencyValue = normalizeJskitDependencySpecifier(packageEntry.packageId, selfDependencyValue);
-    const selfApplied = applyPackageJsonField(
-      appPackageJson,
-      "dependencies",
-      packageEntry.packageId,
-      normalizedSelfDependencyValue
-    );
-    if (selfApplied.changed) {
-      managedRecord.managed.packageJson.dependencies[packageEntry.packageId] = selfApplied.managed;
-      touchedFiles.add("package.json");
-    }
-  }
-
-  for (const [scriptName, scriptValue] of Object.entries(mutationScripts)) {
-    const applied = applyPackageJsonField(appPackageJson, "scripts", scriptName, scriptValue);
-    if (applied.changed) {
-      managedRecord.managed.packageJson.scripts[scriptName] = applied.managed;
-      touchedFiles.add("package.json");
-    }
-  }
-
-  await applyFileMutations(
-    packageEntryForMutations,
-    packageOptions,
-    appRoot,
-    fileMutations,
-    managedRecord.managed.files,
-    managedRecord.managed.migrations,
-    touchedFiles,
-    mutationWarnings,
-    precomputedTemplateContextByMutationIndex
-  );
-
-  await applyTextMutations(
-    packageEntryForMutations,
-    appRoot,
-    ensureArray(mutations.text),
-    packageOptions,
-    managedRecord.managed.text,
-    touchedFiles
-  );
-
-  await applyViteMutations(
-    packageEntryForMutations,
-    appRoot,
-    ensureObject(mutations.vite),
-    packageOptions,
-    managedRecord.managed.vite,
-    touchedFiles
-  );
-
-  if (generatorPackage) {
-    delete lock.installedPackages[packageEntry.packageId];
-  } else {
-    managedRecord.migrationSyncVersion = packageEntry.version;
-    lock.installedPackages[packageEntry.packageId] = managedRecord;
-  }
-  if (mutationWarnings.length > 0) {
-    managedRecord.warnings = mutationWarnings;
-  }
-  return managedRecord;
-}
-
-async function adoptAppLocalPackageDependencies({
-  appRoot,
-  appPackageJson,
-  lock
-}) {
-  const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
-  const runtimeDependencies = ensureObject(appPackageJson.dependencies);
-  const adoptedPackageIds = [];
-
-  for (const dependencyId of sortStrings(Object.keys(runtimeDependencies))) {
-    if (lock.installedPackages[dependencyId]) {
-      continue;
-    }
-
-    const localPackageEntry = appLocalRegistry.get(dependencyId);
-    if (!localPackageEntry) {
-      continue;
-    }
-
-    lock.installedPackages[dependencyId] = createManagedRecordBase(localPackageEntry, {});
-    adoptedPackageIds.push(dependencyId);
-  }
-
-  return {
-    appLocalRegistry,
-    adoptedPackageIds: sortStrings(adoptedPackageIds)
-  };
-}
-
-const commandHandlers = createCommandHandlers(
-  createCommandHandlerDeps({
-    createCliError,
-    createColorFormatter,
-    resolveWrapWidth,
-    writeWrappedItems,
-    normalizeRelativePath,
-    normalizeRelativePosixPath,
-    resolveAppRootFromCwd,
-    loadLockFile,
-    loadPackageRegistry,
-    loadBundleRegistry,
-    loadAppLocalPackageRegistry,
-    mergePackageRegistries,
-    resolvePackageIdInput,
-    resolveInstalledPackageIdInput,
-    resolveInstalledNodeModulePackageEntry,
-    hydratePackageRegistryFromInstalledNodeModules,
-    validateInlineOptionsForPackage,
-    resolveLocalDependencyOrder,
-    validatePlannedCapabilityClosure,
-    resolvePackageOptions,
-    applyPackageInstall,
-    applyPackageMigrationsOnly,
-    applyPackagePositioning,
-    adoptAppLocalPackageDependencies,
-    loadAppPackageJson,
-    resolveLocalPackageId,
-    createLocalPackageScaffoldFiles,
-    fileExists,
-    applyPackageJsonField,
-    toFileDependencySpecifier,
-    writeJsonFile,
-    writeFile,
-    mkdir,
-    path,
-    inspectPackageOfferings,
-    buildFileWriteGroups,
-    listDeclaredCapabilities,
-    buildCapabilityDetailsForPackage,
-    formatPackageSubpathImport,
-    normalizePlacementOutlets,
-    normalizePlacementContributions,
-    shouldShowPackageExportTarget,
-    classifyExportedSymbols,
-    deriveProviderDisplayName,
-    restorePackageJsonField,
-    readFileBufferIfExists,
-    removeEnvValue,
-    removeManagedViteProxyEntries,
-    hashBuffer,
-    rm
-  })
-);
-
-const runCli = createRunCli({
-  parseArgs,
-  printUsage,
-  commandHandlers,
-  cleanupMaterializedPackageRoots,
-  createCliError
-});
-
-export { runCli };