abelworkflow 0.9.2 → 1.0.0

package/lib/installer/links.mjs

@@ -0,0 +1,427 @@
+import * as fs from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { backupIfNeeded, pathExists, pathTargetExists } from "../config/store.mjs";
+import { isWindows } from "../paths.mjs";
+import { ensureManagedContainerDirectory, hashBytes } from "./assets.mjs";
+
+function shouldForceFileSymlinkFailure(kind) {
+  return process.env.ABELWORKFLOW_TEST_FORCE_FILE_SYMLINK_EPERM === "1" && isWindows() && kind === "file";
+}
+
+async function createManagedTargetState(targetPath, sourcePath, kind, mode, status) {
+  let targetHash;
+  if (kind === "file" && await pathTargetExists(targetPath)) {
+    targetHash = hashBytes(await fs.readFile(targetPath));
+  }
+  return { targetPath, sourcePath, kind, mode, status, ...(targetHash ? { targetHash } : {}) };
+}
+
+async function createSymlink(targetPath, sourcePath, linkType, kind) {
+  if (shouldForceFileSymlinkFailure(kind)) {
+    const error = new Error("simulated EPERM");
+    error.code = "EPERM";
+    throw error;
+  }
+  await fs.symlink(sourcePath, targetPath, linkType);
+}
+
+async function symlinkPointsTo(targetPath, sourcePath) {
+  try {
+    if (!(await fs.lstat(targetPath)).isSymbolicLink()) return false;
+    const existing = await fs.readlink(targetPath);
+    return resolve(dirname(targetPath), existing) === resolve(sourcePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function previousStateOwnsSource(previousState, sourcePath, kind) {
+  return Boolean(previousState)
+    && resolve(previousState.sourcePath) === resolve(sourcePath)
+    && previousState.kind === kind;
+}
+
+function isUnverifiedWindowsCopy(previousState, kind) {
+  return isWindows()
+    && kind === "file"
+    && previousState?.kind === "file"
+    && previousState.mode === "copy"
+    && !previousState.targetHash;
+}
+
+async function targetMatchesPreviousState(targetPath, previousState) {
+  if (!previousState || !(await pathExists(targetPath))) return false;
+  const targetStat = await fs.lstat(targetPath);
+  if (previousState.mode === "symlink") {
+    return targetStat.isSymbolicLink() && symlinkPointsTo(targetPath, previousState.sourcePath);
+  }
+  if (previousState.mode === "hardlink") {
+    if (!targetStat.isFile()) return false;
+    if (previousState.targetHash) {
+      return hashBytes(await fs.readFile(targetPath)) === previousState.targetHash;
+    }
+    try {
+      const sourceStat = await fs.stat(previousState.sourcePath);
+      if (targetStat.dev === sourceStat.dev && targetStat.ino === sourceStat.ino) return true;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    return false;
+  }
+  if (previousState.mode === "copy") {
+    if (previousState.kind !== "file" || !targetStat.isFile() || !previousState.targetHash) return false;
+    return hashBytes(await fs.readFile(targetPath)) === previousState.targetHash;
+  }
+  return false;
+}
+
+async function ordinaryFileMatchesSource(targetPath, sourcePath, kind) {
+  if (kind !== "file") return false;
+  try {
+    const targetStat = await fs.lstat(targetPath);
+    if (!targetStat.isFile()) return false;
+    const [targetContent, sourceContent] = await Promise.all([
+      fs.readFile(targetPath),
+      fs.readFile(sourcePath)
+    ]);
+    return targetContent.equals(sourceContent);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function moveReplaceableTarget(targetPath) {
+  const targetStat = await fs.lstat(targetPath);
+  if (targetStat.isDirectory() && !targetStat.isSymbolicLink()) return false;
+  await backupIfNeeded(targetPath);
+  return true;
+}
+
+async function ensureManagedLink(targetPath, sourcePath, kind, previousLinkedTargets = {}, options = {}) {
+  const force = options.force ?? false;
+  await fs.mkdir(dirname(targetPath), { recursive: true });
+  const sourceExists = await pathTargetExists(sourcePath);
+  const targetExists = await pathExists(targetPath);
+  const previousState = previousLinkedTargets[targetPath];
+  const wasPreviouslyManaged = previousStateOwnsSource(previousState, sourcePath, kind);
+  const isUnverifiedCopy = wasPreviouslyManaged && isUnverifiedWindowsCopy(previousState, kind);
+
+  if (targetExists && await symlinkPointsTo(targetPath, sourcePath)) {
+    if (!sourceExists) {
+      await fs.rm(targetPath, { recursive: true, force: true });
+      return { targetPath, status: "removed" };
+    }
+    return createManagedTargetState(targetPath, sourcePath, kind, "symlink", "unchanged");
+  }
+
+  if (!sourceExists) {
+    if (!targetExists) return { targetPath, status: "removed" };
+    if (!wasPreviouslyManaged) return { targetPath, status: "skipped" };
+    if (isUnverifiedCopy) return { targetPath, status: "conflict" };
+    if (await targetMatchesPreviousState(targetPath, previousState)) {
+      await fs.rm(targetPath, { recursive: true, force: true });
+      return { targetPath, status: "removed" };
+    }
+    if (force && await moveReplaceableTarget(targetPath)) return { targetPath, status: "removed" };
+    return { targetPath, status: "conflict" };
+  }
+
+  if (targetExists && !wasPreviouslyManaged && await ordinaryFileMatchesSource(targetPath, sourcePath, kind)) {
+    return createManagedTargetState(targetPath, sourcePath, kind, "copy", "unchanged");
+  }
+
+  if (targetExists) {
+    if (isUnverifiedCopy) {
+      if (await ordinaryFileMatchesSource(targetPath, sourcePath, kind)) {
+        return createManagedTargetState(targetPath, sourcePath, kind, "copy", "unchanged");
+      }
+      return { targetPath, status: "conflict" };
+    }
+    const matchesPrevious = wasPreviouslyManaged && await targetMatchesPreviousState(targetPath, previousState);
+    if (matchesPrevious && await ordinaryFileMatchesSource(targetPath, sourcePath, kind)) {
+      return createManagedTargetState(targetPath, sourcePath, kind, previousState.mode, "unchanged");
+    }
+    if ((!matchesPrevious && !force) || !(await moveReplaceableTarget(targetPath))) {
+      return { targetPath, status: "conflict" };
+    }
+  }
+
+  const linkType = isWindows() ? (kind === "dir" ? "junction" : "file") : kind;
+  try {
+    await createSymlink(targetPath, sourcePath, linkType, kind);
+    return createManagedTargetState(targetPath, sourcePath, kind, "symlink", "linked");
+  } catch (error) {
+    if (!shouldFallbackToManagedFile(error, kind)) throw error;
+  }
+
+  try {
+    await fs.link(sourcePath, targetPath);
+    return createManagedTargetState(targetPath, sourcePath, kind, "hardlink", "linked");
+  } catch (error) {
+    if (!shouldCopyManagedFile(error)) throw error;
+  }
+
+  await fs.cp(sourcePath, targetPath, { recursive: true, force: false, errorOnExist: true });
+  return createManagedTargetState(targetPath, sourcePath, kind, "copy", "linked");
+}
+
+function shouldFallbackToManagedFile(error, kind) {
+  return kind === "file" && isWindows() && ["EPERM", "EACCES"].includes(error?.code);
+}
+
+function shouldCopyManagedFile(error) {
+  return ["EPERM", "EACCES", "EXDEV", "EINVAL", "UNKNOWN"].includes(error?.code);
+}
+
+async function pathIsDirectory(path) {
+  try {
+    return (await fs.stat(path)).isDirectory();
+  } catch (error) {
+    if (["ENOENT", "ELOOP"].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function pathIsFile(path) {
+  try {
+    return (await fs.stat(path)).isFile();
+  } catch (error) {
+    if (["ENOENT", "ELOOP"].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function ensureProviderRootDirectory(homeDir, ...segments) {
+  await fs.mkdir(homeDir, { recursive: true });
+  let directory = homeDir;
+  for (const segment of segments) {
+    directory = join(directory, segment);
+    let stat;
+    try {
+      stat = await fs.lstat(directory);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      try {
+        await fs.mkdir(directory);
+      } catch (mkdirError) {
+        if (mkdirError?.code === "EEXIST") {
+          throw new Error(`Provider root conflict at ${directory}`, { cause: mkdirError });
+        }
+        throw mkdirError;
+      }
+      continue;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Provider root conflict at ${directory}`);
+    }
+  }
+  return directory;
+}
+
+async function getDirectoryNames(root) {
+  if (!(await pathIsDirectory(root))) return [];
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const names = await Promise.all(entries.map(async (entry) => {
+    if (entry.isDirectory()) return entry.name;
+    if (entry.isSymbolicLink() && await pathIsDirectory(join(root, entry.name))) return entry.name;
+    return null;
+  }));
+  return names.filter(Boolean);
+}
+
+async function getCommandNames(commandsDir) {
+  if (!(await pathIsDirectory(commandsDir))) return [];
+  const entries = await fs.readdir(commandsDir, { withFileTypes: true });
+  const names = await Promise.all(entries.map(async (entry) => {
+    if (!entry.name.endsWith(".md")) return null;
+    if (entry.isFile()) return entry.name;
+    if (entry.isSymbolicLink() && await pathIsFile(join(commandsDir, entry.name))) return entry.name;
+    return null;
+  }));
+  return names.filter(Boolean);
+}
+
+async function getPiExtensionNames(extensionsDir) {
+  if (!(await pathIsDirectory(extensionsDir))) return [];
+  const entries = await fs.readdir(extensionsDir, { withFileTypes: true });
+  const names = await Promise.all(entries.map(async (entry) => {
+    const entryPath = join(extensionsDir, entry.name);
+    if (entry.isDirectory()) return await pathIsFile(join(entryPath, "index.ts")) ? entry.name : null;
+    if (entry.isFile()) return entry.name.endsWith(".ts") ? entry.name : null;
+    if (!entry.isSymbolicLink()) return null;
+    if (entry.name.endsWith(".ts") && await pathIsFile(entryPath)) return entry.name;
+    return await pathIsFile(join(entryPath, "index.ts")) ? entry.name : null;
+  }));
+  return names.filter(Boolean);
+}
+
+function isWithinManagedRoot(targetPath, managedSourceRoot, pathOps = { isAbsolute, relative, sep }) {
+  const relativePath = pathOps.relative(managedSourceRoot, targetPath);
+  return relativePath !== ""
+    && !pathOps.isAbsolute(relativePath)
+    && relativePath !== ".."
+    && !relativePath.startsWith(`..${pathOps.sep}`);
+}
+
+async function pruneManagedTargets(targetDir, managedSourceRoot, expectedNames, previousLinkedTargets, options = {}) {
+  const resolvedTargetDir = resolve(targetDir);
+  const expectedNameSet = new Set(expectedNames);
+  const results = [];
+  for (const [targetPath, previousState] of Object.entries(previousLinkedTargets)) {
+    const resolvedTargetPath = resolve(targetPath);
+    if (targetPath !== resolvedTargetPath || dirname(resolvedTargetPath) !== resolvedTargetDir) continue;
+    if (!isWithinManagedRoot(resolve(previousState.sourcePath), resolve(managedSourceRoot))) continue;
+    if (expectedNameSet.has(basename(resolvedTargetPath)) && await pathTargetExists(previousState.sourcePath)) continue;
+    if (!(await pathExists(resolvedTargetPath))) {
+      results.push({ targetPath, status: "removed" });
+      continue;
+    }
+    const isUnverifiedCopy = isUnverifiedWindowsCopy(previousState, previousState.kind);
+    const matchesPrevious = await targetMatchesPreviousState(resolvedTargetPath, previousState)
+      || (isUnverifiedCopy && await ordinaryFileMatchesSource(
+        resolvedTargetPath,
+        previousState.sourcePath,
+        previousState.kind
+      ));
+    if (matchesPrevious) {
+      await fs.rm(resolvedTargetPath, { recursive: true, force: true });
+      results.push({ targetPath, status: "removed" });
+      continue;
+    }
+    if (isUnverifiedCopy) {
+      results.push({ targetPath, status: "conflict" });
+      continue;
+    }
+    if (options.force && await moveReplaceableTarget(resolvedTargetPath)) {
+      results.push({ targetPath, status: "removed" });
+      continue;
+    }
+    results.push({ targetPath, status: "conflict" });
+  }
+  return results;
+}
+
+async function linkSkillDirectories(baseDir, paths, previousLinkedTargets, options) {
+  const results = [];
+  const skillsRoot = join(paths.agentsDir, "skills");
+  const skillNames = (await getDirectoryNames(skillsRoot)).filter((skillName) => skillName !== ".system");
+  results.push(...await pruneManagedTargets(
+    join(baseDir, "skills"),
+    skillsRoot,
+    skillNames,
+    previousLinkedTargets,
+    options
+  ));
+  for (const skillName of skillNames) {
+    results.push(await ensureManagedLink(
+      join(baseDir, "skills", skillName),
+      join(skillsRoot, skillName),
+      "dir",
+      previousLinkedTargets,
+      options
+    ));
+  }
+  return results;
+}
+
+async function linkCommands(targetDir, paths, previousLinkedTargets, options) {
+  const commandsRoot = join(paths.agentsDir, "commands");
+  const commandFiles = await getCommandNames(commandsRoot);
+  const results = await pruneManagedTargets(targetDir, commandsRoot, commandFiles, previousLinkedTargets, options);
+  for (const fileName of commandFiles) {
+    results.push(await ensureManagedLink(
+      join(targetDir, fileName),
+      join(commandsRoot, fileName),
+      "file",
+      previousLinkedTargets,
+      options
+    ));
+  }
+  return results;
+}
+
+async function linkClaude(paths, previousLinkedTargets = {}, options = {}) {
+  const claudeDir = await ensureProviderRootDirectory(paths.homeDir, ".claude");
+  await ensureManagedContainerDirectory(join(claudeDir, "commands"), join(paths.agentsDir, "commands"));
+  await ensureManagedContainerDirectory(join(claudeDir, "skills"), join(paths.agentsDir, "skills"));
+  return [
+    await ensureManagedLink(
+      join(claudeDir, "CLAUDE.md"),
+      join(paths.agentsDir, "AGENTS.md"),
+      "file",
+      previousLinkedTargets,
+      options
+    ),
+    ...await linkCommands(join(claudeDir, "commands"), paths, previousLinkedTargets, options),
+    ...await linkSkillDirectories(claudeDir, paths, previousLinkedTargets, options)
+  ];
+}
+
+async function linkCodex(paths, previousLinkedTargets = {}, options = {}) {
+  const codexDir = await ensureProviderRootDirectory(paths.homeDir, ".codex");
+  await ensureManagedContainerDirectory(join(codexDir, "skills"), join(paths.agentsDir, "skills"));
+  await ensureManagedContainerDirectory(join(codexDir, "prompts"), join(paths.agentsDir, "commands"));
+  return [
+    await ensureManagedLink(
+      join(codexDir, "AGENTS.md"),
+      join(paths.agentsDir, "AGENTS.md"),
+      "file",
+      previousLinkedTargets,
+      options
+    ),
+    ...await linkSkillDirectories(codexDir, paths, previousLinkedTargets, options),
+    ...await linkCommands(join(codexDir, "prompts"), paths, previousLinkedTargets, options)
+  ];
+}
+
+async function linkPi(paths, previousLinkedTargets = {}, options = {}) {
+  const piAgentDir = await ensureProviderRootDirectory(paths.homeDir, ".pi", "agent");
+  await ensureManagedContainerDirectory(join(piAgentDir, "skills"), join(paths.agentsDir, "skills"));
+  await ensureManagedContainerDirectory(join(piAgentDir, "prompts"), join(paths.agentsDir, "commands"));
+  await ensureManagedContainerDirectory(join(piAgentDir, "extensions"), join(paths.agentsDir, "extensions"));
+  const results = [
+    await ensureManagedLink(
+      join(piAgentDir, "AGENTS.md"),
+      join(paths.agentsDir, "AGENTS.md"),
+      "file",
+      previousLinkedTargets,
+      options
+    ),
+    ...await linkSkillDirectories(piAgentDir, paths, previousLinkedTargets, options),
+    ...await linkCommands(join(piAgentDir, "prompts"), paths, previousLinkedTargets, options)
+  ];
+  const extensionsRoot = join(paths.agentsDir, "extensions");
+  const extensionNames = await getPiExtensionNames(extensionsRoot);
+  results.push(...await pruneManagedTargets(
+    join(piAgentDir, "extensions"),
+    extensionsRoot,
+    extensionNames,
+    previousLinkedTargets,
+    options
+  ));
+  for (const entryName of extensionNames) {
+    const sourcePath = join(extensionsRoot, entryName);
+    results.push(await ensureManagedLink(
+      join(piAgentDir, "extensions", entryName),
+      sourcePath,
+      await pathIsDirectory(sourcePath) ? "dir" : "file",
+      previousLinkedTargets,
+      options
+    ));
+  }
+  return results;
+}
+
+export {
+  ensureManagedLink,
+  getCommandNames,
+  isWithinManagedRoot,
+  linkClaude,
+  linkCodex,
+  linkPi,
+  pathIsDirectory,
+  pathIsFile,
+  pruneManagedTargets
+};

package/lib/installer/state.mjs

@@ -0,0 +1,163 @@
+import { join } from "node:path";
+import { readJsonFileSafe, writeJson } from "../config/store.mjs";
+
+function metadataPathFor(paths) {
+  return join(paths.agentsDir, paths.installMetadataName);
+}
+
+function sortObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+function isMetadataV2(previousMetadata) {
+  return previousMetadata?.schemaVersion === 2;
+}
+
+function objectField(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+
+function getPreviousManagedCodexAuthKeys(previousMetadata = {}) {
+  return isMetadataV2(previousMetadata)
+    ? stringArray(previousMetadata.managedCodexAuthKeys)
+    : [];
+}
+
+function normalizeManagedCodexAgentFiles(value = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return sortObject(Object.fromEntries(Object.entries(value).filter(([name, hash]) => (
+    name.endsWith(".toml")
+    && !name.includes("/")
+    && !name.includes("\\")
+    && typeof hash === "string"
+    && /^[a-f0-9]{64}$/u.test(hash)
+  ))));
+}
+
+function getPreviousManagedCodexAgentFiles(previousMetadata = {}) {
+  if (!isMetadataV2(previousMetadata)) return {};
+  return normalizeManagedCodexAgentFiles(previousMetadata.managedCodexAgentFiles);
+}
+
+async function readInstallMetadata(paths) {
+  const metadata = await readJsonFileSafe(metadataPathFor(paths), {});
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new TypeError(`Install metadata in ${metadataPathFor(paths)} must contain a JSON object`);
+  }
+  return metadata;
+}
+
+async function writeInstallMetadata(paths, metadata) {
+  return writeJson(metadataPathFor(paths), metadata, { backupLimit: 0 });
+}
+
+function buildInstallMetadata({
+  previousMetadata = {},
+  packageVersion,
+  managedFiles = {},
+  managedCodexAuthKeys = getPreviousManagedCodexAuthKeys(previousMetadata),
+  managedCodexAgentFiles = getPreviousManagedCodexAgentFiles(previousMetadata),
+  linkedTargets = {}
+}) {
+  const metadata = {
+    schemaVersion: 2,
+    packageVersion,
+    managedFiles: sortObject(managedFiles),
+    managedCodexAuthKeys: [...new Set(managedCodexAuthKeys)].sort(),
+    managedCodexAgentFiles: normalizeManagedCodexAgentFiles(managedCodexAgentFiles),
+    linkedTargets: sortObject(linkedTargets)
+  };
+  if (typeof previousMetadata.installedAt === "string") {
+    metadata.installedAt = previousMetadata.installedAt;
+  }
+  return metadata;
+}
+
+function finalizeProviderInstallMetadata({
+  previousMetadata = {},
+  packageVersion,
+  overrides = {}
+}) {
+  const isV2 = isMetadataV2(previousMetadata);
+  return buildInstallMetadata({
+    previousMetadata: isV2 ? previousMetadata : {},
+    packageVersion: isV2
+      && typeof previousMetadata.packageVersion === "string"
+      && previousMetadata.packageVersion
+      ? previousMetadata.packageVersion
+      : packageVersion,
+    managedFiles: isV2 ? objectField(previousMetadata.managedFiles) : {},
+    managedCodexAuthKeys: stringArray(
+      overrides.managedCodexAuthKeys ?? getPreviousManagedCodexAuthKeys(previousMetadata)
+    ),
+    managedCodexAgentFiles: overrides.managedCodexAgentFiles
+      ?? getPreviousManagedCodexAgentFiles(previousMetadata),
+    linkedTargets: objectField(previousMetadata.linkedTargets)
+  });
+}
+
+function linkedTargetsFromResults(results) {
+  return Object.fromEntries(results
+    .filter((result) => result.sourcePath)
+    .map((result) => [result.targetPath, {
+      sourcePath: result.sourcePath,
+      kind: result.kind,
+      mode: result.mode,
+      ...(result.targetHash ? { targetHash: result.targetHash } : {})
+    }]));
+}
+
+function mergeLinkedTargets(previousLinkedTargets = {}, results = []) {
+  const nextLinkedTargets = { ...previousLinkedTargets };
+  for (const result of results) {
+    if (result.sourcePath) {
+      nextLinkedTargets[result.targetPath] = {
+        sourcePath: result.sourcePath,
+        kind: result.kind,
+        mode: result.mode,
+        ...(result.targetHash ? { targetHash: result.targetHash } : {})
+      };
+    } else if (result.status === "removed") {
+      delete nextLinkedTargets[result.targetPath];
+    }
+  }
+  return sortObject(nextLinkedTargets);
+}
+
+function createInstallReport() {
+  return {
+    created: [],
+    updated: [],
+    unchanged: [],
+    preserved: [],
+    conflicts: [],
+    removed: [],
+    linked: []
+  };
+}
+
+function mergeInstallReports(...reports) {
+  const merged = createInstallReport();
+  for (const report of reports) {
+    for (const key of Object.keys(merged)) merged[key].push(...(report?.[key] ?? []));
+  }
+  return merged;
+}
+
+export {
+  buildInstallMetadata,
+  createInstallReport,
+  finalizeProviderInstallMetadata,
+  getPreviousManagedCodexAgentFiles,
+  getPreviousManagedCodexAuthKeys,
+  linkedTargetsFromResults,
+  mergeInstallReports,
+  mergeLinkedTargets,
+  metadataPathFor,
+  readInstallMetadata,
+  writeInstallMetadata
+};

package/lib/paths.mjs

@@ -0,0 +1,99 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const defaultPackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function createPaths({
+  homeDir = homedir(),
+  packageRoot = defaultPackageRoot,
+  agentsDir = join(homeDir, ".agents")
+} = {}) {
+  const absoluteHomeDir = resolve(homeDir);
+  const absolutePackageRoot = resolve(packageRoot);
+  const absoluteAgentsDir = resolve(agentsDir);
+  assertSeparateSourceAndDeployment(absolutePackageRoot, absoluteAgentsDir);
+
+  const codexTemplateRoot = join(absolutePackageRoot, "lib", "templates", "codex");
+  const workflowTemplateRoot = join(absolutePackageRoot, "lib", "templates", "workflow");
+  const piAgentDir = join(absoluteHomeDir, ".pi", "agent");
+  return {
+    homeDir: absoluteHomeDir,
+    packageRoot: absolutePackageRoot,
+    agentsDir: absoluteAgentsDir,
+    workflowTemplateRoot,
+    installMetadataName: ".abelworkflow-install.json",
+    claudeSettingsPath: join(absoluteHomeDir, ".claude", "settings.json"),
+    claudeMetaConfigPath: join(absoluteHomeDir, ".claude.json"),
+    codexConfigPath: join(absoluteHomeDir, ".codex", "config.toml"),
+    codexAuthPath: join(absoluteHomeDir, ".codex", "auth.json"),
+    codexTemplateConfigPath: join(codexTemplateRoot, "config-base.toml"),
+    codexTemplateAgentsPath: join(codexTemplateRoot, "agents"),
+    piAgentDir,
+    piAuthPath: join(piAgentDir, "auth.json"),
+    piModelsPath: join(piAgentDir, "models.json"),
+    piSettingsPath: join(piAgentDir, "settings.json")
+  };
+}
+
+function assertSeparateSourceAndDeployment(packageRoot, agentsDir) {
+  const canonicalPackageRoot = canonicalizeExistingPath(packageRoot);
+  const canonicalAgentsDir = canonicalizeExistingPath(agentsDir);
+  if (!containsPath(canonicalPackageRoot, canonicalAgentsDir)
+    && !containsPath(canonicalAgentsDir, canonicalPackageRoot)) {
+    return;
+  }
+
+  throw new Error(
+    `源码目录 packageRoot (${packageRoot}) 与部署目录 agentsDir (${agentsDir}) 不能相同或互相嵌套。`
+    + "请将源码克隆到独立目录（例如 ~/src/AbelWorkflow），再用 --agents-dir 指向 ~/.agents；"
+    + "请手动迁移已有源码克隆，安装器不会自动移动或删除数据，--force 也不能绕过此限制。"
+  );
+}
+
+function canonicalizeExistingPath(path) {
+  const missingParts = [];
+  let candidate = path;
+
+  while (true) {
+    try {
+      return resolve(realpathSync.native(candidate), ...missingParts);
+    } catch (error) {
+      const parent = dirname(candidate);
+      if (error?.code !== "ENOENT" || parent === candidate) return path;
+      missingParts.unshift(basename(candidate));
+      candidate = parent;
+    }
+  }
+}
+
+function containsPath(parent, child, pathOps = { isAbsolute, relative, sep }) {
+  const childRelativePath = pathOps.relative(parent, child);
+  return childRelativePath === ""
+    || (childRelativePath !== ".."
+      && !childRelativePath.startsWith(`..${pathOps.sep}`)
+      && !pathOps.isAbsolute(childRelativePath));
+}
+
+const defaultPaths = createPaths();
+
+function getPlatform() {
+  return process.env.ABELWORKFLOW_TEST_PLATFORM || process.platform;
+}
+
+function isWindows() {
+  return getPlatform() === "win32";
+}
+
+function pathToLabel(path, homeDir = defaultPaths.homeDir) {
+  return path.replace(homeDir, "~");
+}
+
+function maskSecret(value) {
+  if (!value) return "未配置";
+  if (value.length <= 4) return "*".repeat(value.length);
+  return `${"*".repeat(Math.max(4, value.length - 4))}${value.slice(-4)}`;
+}
+
+export { containsPath, createPaths, defaultPaths, getPlatform, isWindows, maskSecret, pathToLabel };