avenic 1.0.0

package/vendor/core-src/skills/install.mjs

@@ -0,0 +1,357 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fail } from "../util/fail.mjs";
+import { isInside, removeEmptyDirectory } from "../util/fs.mjs";
+import { readJson, writeJson } from "../util/json.mjs";
+import { ensureCatalog, loadDefaultCatalogSpec, parseCatalogSpec } from "./catalog.mjs";
+import { assertSafeId, assertSafeSkillName } from "./ids.mjs";
+import { loadPacks, resolvePacks } from "./packs.mjs";
+import { buildCatalog, loadSources } from "./sources.mjs";
+import { normalizePackIds, parsePackArguments } from "./packs.mjs";
+import {
+  GLOBAL_TARGETS,
+  LEGACY_PROFILE_FILE,
+  PROJECT_CONFIG_FILE,
+  PROJECT_LOCK_FILE,
+  PROJECT_TARGETS,
+  globalConfigFile,
+  globalLockFile,
+  migrateLegacyProjectFiles,
+} from "./paths.mjs";
+
+export function isCatalogDirectory(directory) {
+  return (
+    existsSync(path.join(directory, "sources.lock.json")) &&
+    existsSync(path.join(directory, "skills")) &&
+    existsSync(path.join(directory, "packs"))
+  );
+}
+
+export function createInstallContext(global, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const environment = options.environment ?? process.env;
+  if (global) {
+    return {
+      configFile: globalConfigFile(environment),
+      environment,
+      global: true,
+      label: "Global",
+      lockFile: globalLockFile(environment),
+      root: environment.USERPROFILE || environment.HOME || os.homedir(),
+      targets: GLOBAL_TARGETS,
+    };
+  }
+  migrateLegacyProjectFiles(cwd);
+  return {
+    configFile: path.join(cwd, PROJECT_CONFIG_FILE),
+    environment,
+    global: false,
+    label: "Project",
+    legacyProfileFile: path.join(cwd, LEGACY_PROFILE_FILE),
+    lockFile: path.join(cwd, PROJECT_LOCK_FILE),
+    root: cwd,
+    targets: PROJECT_TARGETS.map((target) => ({
+      ...target,
+      destination: path.join(cwd, ...target.relativePath),
+    })),
+  };
+}
+
+export async function resolveInstallPacks(context, explicitPacks) {
+  const requested = parsePackArguments(explicitPacks);
+  if (requested.length > 0) {
+    return normalizePackIds(requested);
+  }
+  if (existsSync(context.configFile)) {
+    const config = await readJson(context.configFile);
+    return normalizePackIds(config.packs ?? (config.pack ? [config.pack] : []));
+  }
+  if (context.legacyProfileFile && existsSync(context.legacyProfileFile)) {
+    return normalizePackIds(
+      parsePackArguments([(await readFile(context.legacyProfileFile, "utf8")).trim()]),
+    );
+  }
+  return ["common"];
+}
+
+export async function previousManagedState(context) {
+  if (!existsSync(context.lockFile)) {
+    return new Map();
+  }
+  const manifest = await readJson(context.lockFile);
+  const managed = new Map();
+  for (const source of manifest.sources ?? []) {
+    for (const skillName of source.skills ?? []) {
+      managed.set(skillName, { sourceId: source.id, revision: source.revision });
+    }
+  }
+  return managed;
+}
+
+export async function installedPackIds(context) {
+  if (existsSync(context.configFile)) {
+    const config = await readJson(context.configFile);
+    return normalizePackIds(config.packs ?? (config.pack ? [config.pack] : []));
+  }
+  if (existsSync(context.lockFile)) {
+    const lock = await readJson(context.lockFile);
+    return normalizePackIds(
+      (lock.packs ?? (lock.pack ? [lock.pack] : [])).map((pack) => pack.id ?? pack),
+    );
+  }
+  return null;
+}
+
+export async function writeInstallMetadata(context, resolvedPacks, catalogInfo = {}) {
+  const packageMetadata = catalogInfo.packageMetadata ?? null;
+  const packageSpec = catalogInfo.spec ?? packageMetadata?.agentSkills?.packageSpec ?? packageMetadata?.repository?.url;
+  const previousConfig = existsSync(context.configFile) ? await readJson(context.configFile) : {};
+  const previousLock = existsSync(context.lockFile) ? await readJson(context.lockFile) : {};
+  const config = {
+    schemaVersion: 3,
+    catalog: packageSpec,
+    packs: resolvedPacks.packs.map((pack) => pack.id),
+    ...(previousConfig.direct ? { direct: previousConfig.direct } : {}),
+  };
+  const lock = {
+    schemaVersion: 3,
+    packs: resolvedPacks.packs.map((pack) => ({
+      id: pack.id,
+      name: pack.name,
+      description: pack.description ?? "",
+    })),
+    catalog: {
+      spec: packageSpec,
+      repository: catalogInfo.repository ?? null,
+      revision: catalogInfo.revision ?? null,
+    },
+    ...(previousLock.directSources ? { directSources: previousLock.directSources } : {}),
+    agents: context.targets.flatMap((target) => target.agents).filter((agent) => agent !== "universal"),
+    sources: resolvedPacks.groups.map((group) => ({
+      id: group.source.id,
+      name: group.source.name,
+      repository: group.source.repository,
+      revision: group.source.revision,
+      skills: group.skills.map((skill) => skill.name),
+    })),
+  };
+  await mkdir(path.dirname(context.configFile), { recursive: true });
+  await writeJson(context.configFile, config);
+  await writeJson(context.lockFile, lock);
+  if (context.legacyProfileFile && existsSync(context.legacyProfileFile)) {
+    await rm(context.legacyProfileFile);
+  }
+}
+
+export async function installCopies(context, resolvedPacks, io = console) {
+  const selectedSkills = resolvedPacks.groups.flatMap((group) => group.skills);
+  const selectedNames = new Set(selectedSkills.map((skill) => skill.name));
+  const previousState = await previousManagedState(context);
+  const staleNames = [...previousState.keys()].filter((name) => !selectedNames.has(name));
+  for (const targetConfig of context.targets) {
+    const destination = targetConfig.destination;
+    await mkdir(destination, { recursive: true });
+    const result = { added: 0, updated: 0, unchanged: 0, removed: 0 };
+    for (const skill of selectedSkills) {
+      const target = path.join(destination, skill.name);
+      if (!isInside(destination, target)) {
+        fail(`Install path escaped its target: ${target}`);
+      }
+      const previous = previousState.get(skill.name);
+      if (
+        existsSync(path.join(target, "SKILL.md")) &&
+        previous?.sourceId === skill.source.id &&
+        previous?.revision === skill.source.revision
+      ) {
+        result.unchanged += 1;
+        continue;
+      }
+      const existed = existsSync(target);
+      await rm(target, { recursive: true, force: true });
+      await cp(skill.directory, target, { recursive: true });
+      result[existed ? "updated" : "added"] += 1;
+    }
+    for (const staleName of staleNames) {
+      assertSafeSkillName(staleName);
+      const target = path.join(destination, staleName);
+      if (!isInside(destination, target)) {
+        fail(`Cleanup path escaped its target: ${target}`);
+      }
+      await rm(target, { recursive: true, force: true });
+      result.removed += 1;
+    }
+    io.log(`✓ ${targetConfig.label}`);
+    io.log(`  Path: ${destination}`);
+    io.log(
+      `  Added ${result.added} · Updated ${result.updated} · Unchanged ${result.unchanged} · Removed ${result.removed}`,
+    );
+  }
+}
+
+export async function removeAllManagedSkills(context, managed, io = console) {
+  let total = 0;
+  for (const targetConfig of context.targets) {
+    let removed = 0;
+    for (const skillName of managed.keys()) {
+      assertSafeSkillName(skillName);
+      const target = path.join(targetConfig.destination, skillName);
+      if (!isInside(targetConfig.destination, target)) {
+        fail(`Uninstall path escaped its target: ${target}`);
+      }
+      if (existsSync(target)) {
+        await rm(target, { recursive: true, force: true });
+        removed += 1;
+      }
+    }
+    await removeEmptyDirectory(targetConfig.destination);
+    total += removed;
+    io.log(`${targetConfig.label}: Removed ${removed}`);
+  }
+  return total;
+}
+
+export async function removeSkillDirectories(context, skillNames, io = console) {
+  let total = 0;
+  for (const targetConfig of context.targets) {
+    let removed = 0;
+    for (const skillName of skillNames) {
+      const target = path.join(targetConfig.destination, skillName);
+      if (!isInside(targetConfig.destination, target)) {
+        fail(`Uninstall path escaped its target: ${target}`);
+      }
+      if (existsSync(target)) {
+        await rm(target, { recursive: true, force: true });
+        removed += 1;
+      }
+    }
+    total += removed;
+    io.log(`${targetConfig.label}: ${removed > 0 ? `Removed ${removed}` : "Unchanged"}`);
+  }
+  return total;
+}
+
+export async function removeInstallationFiles(context) {
+  await rm(context.configFile, { force: true });
+  await rm(context.lockFile, { force: true });
+  if (context.legacyProfileFile) {
+    await rm(context.legacyProfileFile, { force: true });
+  }
+}
+
+// Structured `skills status` data: the manifest's packs and per-target
+// presence counts. Returns null when nothing is installed.
+export async function skillsInstallationStatus(context) {
+  if (!existsSync(context.lockFile)) {
+    return null;
+  }
+  const manifest = await readJson(context.lockFile);
+  const groups = (manifest.sources ?? []).map((source) => ({
+    source,
+    skills: (source.skills ?? []).map((name) => ({ name })),
+  }));
+  const manifestPacks = manifest.packs ?? (manifest.pack ? [manifest.pack] : []);
+  const names = groups.flatMap((group) => group.skills.map((skill) => skill.name));
+  const targets = context.targets.map((targetConfig) => {
+    const directory = targetConfig.destination;
+    const present = names.filter((name) => existsSync(path.join(directory, name, "SKILL.md"))).length;
+    return { ...targetConfig, present, total: names.length, complete: present === names.length };
+  });
+  return { groups, packs: manifestPacks, names, targets };
+}
+
+async function pinnedCatalogSpec(spec, context) {
+  if (!existsSync(context.lockFile)) {
+    return spec;
+  }
+  const lock = await readJson(context.lockFile);
+  const { repository, revision } = lock.catalog ?? {};
+  if (!repository || !revision) {
+    return spec;
+  }
+  if (parseCatalogSpec(spec).repository !== repository) {
+    return spec;
+  }
+  return `${repository}#${revision}`;
+}
+
+// Resolve the catalog for an install context. The project lock pins the
+// catalog commit for cross-device reproducibility; a refresh (bare
+// `avenic skills`) intentionally bypasses the pin to pick up the latest.
+export async function resolveInstallSource(options, { refresh = false } = {}) {
+  const spec = await loadDefaultCatalogSpec(options.environment);
+  const context = createInstallContext(options.global ?? false, options);
+  const pinnedSpec = refresh ? spec : await pinnedCatalogSpec(spec, context);
+  const catalogInfo = await ensureCatalog(pinnedSpec, {
+    environment: options.environment,
+    io: options.io ?? console,
+  });
+  const packageMetadata = existsSync(path.join(catalogInfo.catalogRoot, "package.json"))
+    ? await readJson(path.join(catalogInfo.catalogRoot, "package.json"))
+    : null;
+  return { ...catalogInfo, packageMetadata };
+}
+
+// Install Packs into a scope: resolve the catalog, resolve the Packs,
+// hand the plan to the presentation hook, copy the Skills, and write the
+// config/lock metadata. Bare invocations (no explicit Packs) refresh the
+// configured Packs against the latest catalog.
+export async function installPacks(context, explicitPacks = [], options = {}) {
+  const io = options.io ?? console;
+  if (!context.global && isCatalogDirectory(context.root)) {
+    fail("Run installation from a work project, not from the Avenic catalog");
+  }
+  const catalogInfo = await resolveInstallSource({
+    global: context.global,
+    cwd: context.root,
+    environment: context.environment,
+    io,
+  }, { refresh: explicitPacks.length === 0 });
+  const sourceConfig = await loadSources(catalogInfo.catalogRoot);
+  const catalog = await buildCatalog(sourceConfig, path.join(catalogInfo.catalogRoot, "skills"));
+  const packs = await loadPacks(catalogInfo.catalogRoot);
+  const packIds = await resolveInstallPacks(context, explicitPacks);
+  const resolvedPacks = resolvePacks(catalog, sourceConfig, packs, packIds);
+  await options.onPlan?.(resolvedPacks);
+  await installCopies(context, resolvedPacks, io);
+  await writeInstallMetadata(context, resolvedPacks, catalogInfo);
+  return { catalogInfo, packIds, resolvedPacks };
+}
+
+// Uninstall Packs from a scope: validate the request, reinstall the
+// remaining Packs (common is always included and can never be removed),
+// and rewrite the metadata. The no-argument full cleanup stays in the CLI.
+export async function uninstallPacks(context, packArguments = [], options = {}) {
+  const io = options.io ?? console;
+  const requested = parsePackArguments(packArguments);
+  requested.forEach((packId) => assertSafeId(packId, "Pack id"));
+  const current = await installedPackIds(context);
+  if (!current) {
+    io.log(`No managed ${context.label.toLowerCase()} skills installation found`);
+    return { changed: false, removed: [], absent: requested, skippedCommon: false, current: null };
+  }
+  const removable = new Set(requested.filter((packId) => packId !== "common"));
+  const removed = current.filter((packId) => removable.has(packId));
+  const absent = requested.filter((packId) => packId !== "common" && !current.includes(packId));
+  const skippedCommon = requested.includes("common");
+  if (removed.length === 0) {
+    return { changed: false, removed: [], absent, skippedCommon, current };
+  }
+  const catalogInfo = await resolveInstallSource({
+    global: context.global,
+    cwd: context.root,
+    environment: context.environment,
+    io,
+  });
+  const sourceConfig = await loadSources(catalogInfo.catalogRoot);
+  const catalog = await buildCatalog(sourceConfig, path.join(catalogInfo.catalogRoot, "skills"));
+  const packs = await loadPacks(catalogInfo.catalogRoot);
+  const remaining = current.filter((packId) => !removable.has(packId));
+  const resolvedPacks = resolvePacks(catalog, sourceConfig, packs, remaining);
+  await options.onPlan?.(resolvedPacks, removed);
+  await installCopies(context, resolvedPacks, io);
+  await writeInstallMetadata(context, resolvedPacks, catalogInfo);
+  return { changed: true, removed, absent, skippedCommon, current, resolvedPacks };
+}

package/vendor/core-src/skills/packs.mjs

@@ -0,0 +1,256 @@
+import { existsSync } from "node:fs";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fail } from "../util/fail.mjs";
+import { isInside } from "../util/fs.mjs";
+import { readJson, writeJson } from "../util/json.mjs";
+import { assertSafeId, assertSafeSkillName } from "./ids.mjs";
+import { saveSources } from "./sources.mjs";
+
+export async function loadPacks(catalogRoot) {
+  const packsRoot = path.join(catalogRoot, "packs");
+  const files = (await readdir(packsRoot)).filter((file) => file.endsWith(".json")).sort();
+  const packs = new Map();
+  for (const file of files) {
+    const pack = await readJson(path.join(packsRoot, file));
+    assertSafeId(pack.id, "Pack id");
+    if (file !== `${pack.id}.json`) {
+      fail(`Pack filename must match its id: ${file} != ${pack.id}.json`);
+    }
+    if (!pack.name || !Array.isArray(pack.sources)) {
+      fail(`Invalid Pack: ${pack.id}`);
+    }
+    if (packs.has(pack.id)) {
+      fail(`Duplicate Pack: ${pack.id}`);
+    }
+    packs.set(pack.id, pack);
+  }
+  return packs;
+}
+
+export function resolvePack(catalog, sourceConfig, pack) {
+  const sourceById = new Map(sourceConfig.sources.map((source) => [source.id, source]));
+  const selectedNames = new Set();
+  const groups = [];
+  for (const selection of pack.sources) {
+    const source = sourceById.get(selection.source);
+    if (!source) {
+      fail(`Pack ${pack.id} references unknown source: ${selection.source}`);
+    }
+    if (!Array.isArray(selection.skills) || selection.skills.length === 0) {
+      fail(`Pack ${pack.id} has an empty source selection: ${selection.source}`);
+    }
+    const skills = [];
+    for (const name of selection.skills) {
+      assertSafeSkillName(name);
+      if (selectedNames.has(name)) {
+        fail(`Pack ${pack.id} contains duplicate Skill: ${name}`);
+      }
+      const skill = catalog.byName.get(name);
+      if (!skill) {
+        fail(`Pack ${pack.id} references missing Skill: ${name}`);
+      }
+      if (skill.source.id !== source.id) {
+        fail(`Pack ${pack.id} records the wrong source for ${name}: ${source.id}`);
+      }
+      selectedNames.add(name);
+      skills.push(skill);
+    }
+    groups.push({ source, skills });
+  }
+  return { groups, names: [...selectedNames], pack };
+}
+
+export function parsePackArguments(argumentsList) {
+  return argumentsList
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+export function normalizePackIds(packIds) {
+  const unique = [...new Set(packIds)];
+  if (!unique.includes("common")) {
+    unique.unshift("common");
+  }
+  return unique;
+}
+
+export function resolvePacks(catalog, sourceConfig, packs, requestedPackIds) {
+  const packIds = normalizePackIds(requestedPackIds);
+  const selectedPacks = packIds.map((packId) => {
+    const pack = packs.get(packId);
+    if (!pack) {
+      fail(`Unknown Pack: ${packId}`);
+    }
+    return pack;
+  });
+  const sourceOrder = new Map(sourceConfig.sources.map((source, index) => [source.id, index]));
+  const groupsBySource = new Map();
+  const selectedNames = new Set();
+  let requestedSkills = 0;
+
+  for (const pack of selectedPacks) {
+    const resolved = resolvePack(catalog, sourceConfig, pack);
+    requestedSkills += resolved.names.length;
+    for (const group of resolved.groups) {
+      let combined = groupsBySource.get(group.source.id);
+      if (!combined) {
+        combined = { source: group.source, skills: [] };
+        groupsBySource.set(group.source.id, combined);
+      }
+      for (const skill of group.skills) {
+        if (!selectedNames.has(skill.name)) {
+          selectedNames.add(skill.name);
+          combined.skills.push(skill);
+        }
+      }
+    }
+  }
+
+  const groups = [...groupsBySource.values()]
+    .filter((group) => group.skills.length > 0)
+    .sort((left, right) => sourceOrder.get(left.source.id) - sourceOrder.get(right.source.id));
+  return {
+    groups,
+    names: [...selectedNames],
+    packs: selectedPacks,
+    duplicateSelections: requestedSkills - selectedNames.size,
+  };
+}
+
+export function packContainsSkill(pack, sourceId, skillName) {
+  return pack.sources.some(
+    (selection) => selection.source === sourceId && selection.skills.includes(skillName),
+  );
+}
+
+export function skillCoveredByPacks(packs, packIds, sourceId, skillName) {
+  if (packIds.some((packId) => packContainsSkill(packs.get(packId), sourceId, skillName))) {
+    return true;
+  }
+  const common = packs.get("common");
+  return Boolean(common && packContainsSkill(common, sourceId, skillName));
+}
+
+export function catalogReferences(packs) {
+  const references = new Set();
+  for (const pack of packs.values()) {
+    for (const selection of pack.sources) {
+      for (const skillName of selection.skills) {
+        references.add(`${selection.source}\0${skillName}`);
+      }
+    }
+  }
+  return references;
+}
+
+export async function addSkillsToPacks(catalogRoot, packIds, sourceId, skillNames) {
+  const packsRoot = path.join(catalogRoot, "packs");
+  const loadedPacks = new Map();
+  for (const packId of packIds) {
+    assertSafeId(packId, "Pack id");
+    const packFile = path.join(packsRoot, `${packId}.json`);
+    if (!isInside(packsRoot, packFile) || !existsSync(packFile)) {
+      fail(`Unknown Pack: ${packId}`);
+    }
+    loadedPacks.set(packId, { file: packFile, pack: await readJson(packFile) });
+  }
+
+  const commonEntry = loadedPacks.get("common") ?? {
+    file: path.join(packsRoot, "common.json"),
+    pack: await readJson(path.join(packsRoot, "common.json")),
+  };
+  const commonSkills = new Set(
+    commonEntry.pack.sources.flatMap((selection) => selection.skills),
+  );
+  if (loadedPacks.has("common")) {
+    skillNames.forEach((skillName) => commonSkills.add(skillName));
+  }
+
+  const added = [];
+  const inherited = new Set();
+  for (const packId of packIds) {
+    const { file: packFile, pack } = loadedPacks.get(packId);
+    const applicableSkills =
+      packId === "common"
+        ? skillNames
+        : skillNames.filter((skillName) => {
+            if (commonSkills.has(skillName)) {
+              inherited.add(skillName);
+              return false;
+            }
+            return true;
+          });
+    if (applicableSkills.length === 0) {
+      continue;
+    }
+    let selection = pack.sources.find((item) => item.source === sourceId);
+    if (!selection) {
+      selection = { source: sourceId, skills: [] };
+      pack.sources.push(selection);
+    }
+    let changed = false;
+    for (const skillName of applicableSkills) {
+      if (!selection.skills.includes(skillName)) {
+        selection.skills.push(skillName);
+        added.push({ packId, skillName });
+        changed = true;
+      }
+    }
+    if (changed) {
+      await writeJson(packFile, pack);
+    }
+  }
+  return { added, inherited: [...inherited] };
+}
+
+export async function pruneCatalogSkills(catalogRoot, sourceConfig, packs, candidates) {
+  const skillsRoot = path.join(catalogRoot, "skills");
+  const references = catalogReferences(packs);
+  const removed = [];
+  const affectedSources = new Set();
+  for (const candidate of candidates) {
+    const key = `${candidate.sourceId}\0${candidate.skillName}`;
+    if (references.has(key)) {
+      continue;
+    }
+    const directory = path.join(skillsRoot, candidate.sourceId, candidate.skillName);
+    if (existsSync(directory)) {
+      await rm(directory, { recursive: true, force: true });
+      removed.push(candidate);
+      affectedSources.add(candidate.sourceId);
+    }
+    const source = sourceConfig.sources.find((item) => item.id === candidate.sourceId);
+    if (source?.skillPaths?.[candidate.skillName]) {
+      delete source.skillPaths[candidate.skillName];
+      if (Object.keys(source.skillPaths).length === 0) {
+        delete source.skillPaths;
+      }
+      affectedSources.add(candidate.sourceId);
+    }
+  }
+
+  const removedSources = [];
+  for (const sourceId of affectedSources) {
+    const source = sourceConfig.sources.find((item) => item.id === sourceId);
+    if (!source) continue;
+    const directory = path.join(skillsRoot, sourceId);
+    const entries = existsSync(directory)
+      ? await readdir(directory, { withFileTypes: true })
+      : [];
+    if (entries.some((entry) => entry.isDirectory())) {
+      continue;
+    }
+    if (source.licenseFile) {
+      await rm(path.join(catalogRoot, source.licenseFile), { force: true });
+    }
+    await rm(directory, { recursive: true, force: true });
+    sourceConfig.sources = sourceConfig.sources.filter((item) => item.id !== sourceId);
+    removedSources.push(sourceId);
+  }
+  if (removed.length > 0 || affectedSources.size > 0) {
+    await saveSources(catalogRoot, sourceConfig);
+  }
+  return { removed, removedSources };
+}

package/vendor/core-src/skills/paths.mjs

@@ -0,0 +1,92 @@
+import { existsSync, renameSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+export const PROJECT_CONFIG_FILE = ".avenic.json";
+export const PROJECT_LOCK_FILE = ".avenic.lock.json";
+export const LEGACY_PROJECT_CONFIG_FILE = ".agent-skills.json";
+export const LEGACY_PROJECT_LOCK_FILE = ".agent-skills.lock.json";
+export const LEGACY_PROFILE_FILE = ".agent-skills-profile"; // 保持旧名：仅历史读取
+
+export function migrateLegacyProjectFiles(cwd) {
+  for (const [legacy, current] of [
+    [LEGACY_PROJECT_CONFIG_FILE, PROJECT_CONFIG_FILE],
+    [LEGACY_PROJECT_LOCK_FILE, PROJECT_LOCK_FILE],
+  ]) {
+    const from = path.join(cwd, legacy);
+    const to = path.join(cwd, current);
+    if (!existsSync(to) && existsSync(from)) renameSync(from, to); // 同目录原子 rename
+  }
+}
+
+export const PROJECT_TARGETS = [
+  { agents: ["claude-code"], label: "Claude Code", relativePath: [".claude", "skills"] },
+  {
+    agents: ["codex", "opencode", "universal"],
+    label: "Codex / OpenCode / universal agents",
+    relativePath: [".agents", "skills"],
+  },
+];
+
+// Read an environment variable under its current name, falling back to a
+// deprecated legacy name with a deprecation warning on stderr.
+export function deprecatedEnvironmentValue(environment, primary, legacy) {
+  if (environment[primary]) return environment[primary];
+  if (environment[legacy]) {
+    console.warn(`Environment variable ${legacy} is deprecated; use ${primary}`);
+    return environment[legacy];
+  }
+  return undefined;
+}
+
+export function stateRoot(environment = process.env) {
+  const override = deprecatedEnvironmentValue(environment, "AVENIC_STATE_DIR", "AGENTHOME_STATE_DIR");
+  if (override) return override;
+  const root = environment.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  const current = path.join(root, "avenic");
+  const legacy = path.join(root, "agent-skills");
+  if (existsSync(legacy) && !statSync(current, { throwIfNoEntry: false })?.isDirectory()) {
+    // 新路径被同名非目录占用：不能迁移进去，也绝不覆盖删除，降级继续用旧目录
+    if (existsSync(current)) return legacy;
+    try {
+      renameSync(legacy, current); // 同父目录原子 rename，一次性迁移
+    } catch {
+      return legacy; // 迁移失败降级：继续用旧目录，不丢数据
+    }
+  }
+  return current;
+}
+
+export const GLOBAL_TARGETS = [
+  {
+    agents: ["claude-code"],
+    label: "Claude Code",
+    destination: path.join(os.homedir(), ".claude", "skills"),
+  },
+  {
+    agents: ["codex", "opencode", "universal"],
+    label: "Codex / OpenCode / universal agents",
+    destination: path.join(os.homedir(), ".agents", "skills"),
+  },
+];
+
+export function catalogCacheRoot(environment = process.env) {
+  return path.join(stateRoot(environment), "catalog");
+}
+
+export function defaultCatalogFile(environment = process.env) {
+  return path.join(stateRoot(environment), "catalog.json");
+}
+
+export function knownCatalogsFile(environment = process.env) {
+  return path.join(stateRoot(environment), "catalogs.json");
+}
+
+export function globalConfigFile(environment = process.env) {
+  return path.join(stateRoot(environment), "config.json");
+}
+
+export function globalLockFile(environment = process.env) {
+  return path.join(stateRoot(environment), "lock.json");
+}