abelworkflow 0.9.2 → 1.0.0

package/lib/installer/assets.mjs

@@ -0,0 +1,324 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import {
+  backupIfNeeded,
+  pathExists,
+  pathTargetExists,
+  readJsonFileSafe,
+  writeText
+} from "../config/store.mjs";
+import { createInstallReport, readInstallMetadata } from "./state.mjs";
+
+const ignoredSkillPathPatterns = [
+  /(^|\/)\.env$/u,
+  /(^|\/)\.skill-lock\.json$/u,
+  /(^|\/)\.venv(\/|$)/u,
+  /(^|\/)__pycache__(\/|$)/u,
+  /(^|\/)node_modules(\/|$)/u,
+  /(^|\/)tmp(\/|$)/u,
+  /(^|\/)build(\/|$)/u,
+  /^dev-browser\/profiles(\/|$)/u,
+  /^dev-browser\/tmp(\/|$)/u
+];
+
+function normalizeRelativePath(path) {
+  return path.replaceAll("\\", "/");
+}
+
+function validateManagedFilePath(candidate) {
+  if (typeof candidate !== "string") {
+    throw new Error(`Invalid managed file path: ${String(candidate)}`);
+  }
+  const normalized = normalizeRelativePath(candidate);
+  const segments = normalized.split("/");
+  if (!normalized
+    || candidate !== normalized
+    || normalized.startsWith("/")
+    || /^[A-Za-z]:/u.test(normalized)
+    || normalized.includes("\0")
+    || segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error(`Invalid managed file path: ${candidate}`);
+  }
+  return normalized;
+}
+
+async function resolveManagedFilePath(paths, candidate) {
+  const normalized = validateManagedFilePath(candidate);
+  const rootPath = resolve(paths.agentsDir);
+  const targetPath = resolve(rootPath, normalized);
+  if (normalizeRelativePath(relative(rootPath, targetPath)) !== normalized) {
+    throw new Error(`Invalid managed file path: ${candidate}`);
+  }
+  let ancestorPath = rootPath;
+  for (const segment of normalized.split("/").slice(0, -1)) {
+    ancestorPath = join(ancestorPath, segment);
+    try {
+      if ((await fs.lstat(ancestorPath)).isSymbolicLink()) {
+        throw new Error(`Invalid managed file path: ${candidate}`);
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") break;
+      throw error;
+    }
+  }
+  return targetPath;
+}
+
+function mapGitignoreTemplate(relativePath) {
+  return relativePath.replace(/(^|\/)gitignore\.template$/u, "$1.gitignore");
+}
+
+function hashBytes(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function shouldCopySkillPath(skillsRoot, sourcePath) {
+  const relativePath = normalizeRelativePath(relative(skillsRoot, sourcePath));
+  if (!relativePath) return true;
+  if (/(^|\/)dist(\/|$)/u.test(relativePath) && !/^dev-browser\/dist(\/|$)/u.test(relativePath)) return false;
+  return !ignoredSkillPathPatterns.some((pattern) => pattern.test(relativePath));
+}
+
+async function collectFiles(root, outputPrefix, { filter, mapTargetPath } = {}) {
+  const assets = new Map();
+  async function visit(directory) {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const sourcePath = join(directory, entry.name);
+      if (filter && !filter(root, sourcePath)) continue;
+      if (entry.isDirectory()) {
+        const nested = await visit(sourcePath);
+        for (const [key, value] of nested) assets.set(key, value);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+      const sourceRelativePath = normalizeRelativePath(relative(root, sourcePath));
+      if (sourceRelativePath.endsWith(".skill-lock.json")) continue;
+      const sourceContent = await fs.readFile(sourcePath);
+      const sourceStat = await fs.stat(sourcePath);
+      const targetRelativePath = normalizeRelativePath(join(
+        outputPrefix,
+        mapTargetPath ? mapTargetPath(sourceRelativePath) : sourceRelativePath
+      ));
+      assets.set(targetRelativePath, {
+        content: sourceContent,
+        hash: hashBytes(sourceContent),
+        sourceHash: hashBytes(sourceContent),
+        mode: sourceStat.mode & 0o777,
+        sourcePath
+      });
+    }
+    return assets;
+  }
+  return visit(root);
+}
+
+async function addAssetTree(manifest, root, outputPrefix, options = {}) {
+  if (!(await pathTargetExists(root))) {
+    if (options.required) throw new Error(`Missing managed asset root: ${root}`);
+    return;
+  }
+  for (const [key, value] of await collectFiles(root, outputPrefix, options)) manifest.set(key, value);
+}
+
+async function collectManagedAssets(paths) {
+  const manifest = new Map();
+  await addAssetTree(manifest, paths.workflowTemplateRoot, "", {
+    required: true,
+    mapTargetPath: mapGitignoreTemplate
+  });
+
+  const readmePath = join(paths.packageRoot, "README.md");
+  if (!(await pathTargetExists(readmePath))) throw new Error(`Missing managed asset: ${readmePath}`);
+  const readmeContent = await fs.readFile(readmePath);
+  manifest.set("README.md", {
+    content: readmeContent,
+    hash: hashBytes(readmeContent),
+    sourceHash: hashBytes(readmeContent),
+    mode: (await fs.stat(readmePath)).mode & 0o777,
+    sourcePath: readmePath
+  });
+
+  const skillsRoot = join(paths.packageRoot, "skills");
+  await addAssetTree(manifest, skillsRoot, "skills", {
+    filter: shouldCopySkillPath,
+    mapTargetPath: mapGitignoreTemplate
+  });
+  await addAssetTree(manifest, join(paths.packageRoot, "extensions"), "extensions");
+  return manifest;
+}
+
+async function readManagedFiles(paths, metadata) {
+  if (metadata.schemaVersion !== 2) return {};
+  const managedFiles = { ...(metadata.managedFiles ?? {}) };
+  for (const relativePath of Object.keys(managedFiles)) {
+    await resolveManagedFilePath(paths, relativePath);
+  }
+  return managedFiles;
+}
+
+function recordConflict(report, relativePath) {
+  report.conflicts.push(relativePath);
+  report.preserved.push(relativePath);
+}
+
+async function readRegularTarget(targetPath) {
+  try {
+    const targetStat = await fs.lstat(targetPath);
+    if (targetStat.isSymbolicLink()) {
+      return {
+        exists: true,
+        regular: false,
+        symbolicLink: true
+      };
+    }
+    if (!targetStat.isFile()) return { exists: true, regular: false };
+    const content = await fs.readFile(targetPath);
+    return { exists: true, regular: true, hash: hashBytes(content) };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { exists: false, regular: false };
+    throw error;
+  }
+}
+
+async function applyManifestEntry(paths, relativePath, asset, previousHash, force, report) {
+  const targetPath = await resolveManagedFilePath(paths, relativePath);
+  const current = await readRegularTarget(targetPath);
+  if (!current.exists) {
+    await writeText(targetPath, asset.content, { backupLimit: 3, mode: asset.mode });
+    report.created.push(relativePath);
+    return asset.hash;
+  }
+  if (!current.regular) {
+    if (force && current.symbolicLink) {
+      await backupIfNeeded(targetPath);
+      await writeText(targetPath, asset.content, { backupLimit: 3, mode: asset.mode });
+      report.updated.push(relativePath);
+      return asset.hash;
+    }
+    recordConflict(report, relativePath);
+    return previousHash;
+  }
+  if (current.hash === asset.hash) {
+    const result = await writeText(targetPath, asset.content, { backupLimit: 3, mode: asset.mode });
+    report[result.status === "permission-repaired" ? "updated" : "unchanged"].push(relativePath);
+    return asset.hash;
+  }
+  if (!previousHash && current.hash === asset.sourceHash) {
+    await writeText(targetPath, asset.content, { backupLimit: 3, mode: asset.mode });
+    report.updated.push(relativePath);
+    return asset.hash;
+  }
+  if (previousHash && current.hash === previousHash || force) {
+    await writeText(targetPath, asset.content, { backupLimit: 3, mode: asset.mode });
+    report.updated.push(relativePath);
+    return asset.hash;
+  }
+  recordConflict(report, relativePath);
+  return previousHash;
+}
+
+async function removeStaleManagedFile(paths, relativePath, previousHash, force, report) {
+  if (relativePath.endsWith(".skill-lock.json")) return;
+  const targetPath = await resolveManagedFilePath(paths, relativePath);
+  const current = await readRegularTarget(targetPath);
+  if (!current.exists) return undefined;
+  if (!current.regular) {
+    recordConflict(report, relativePath);
+    return undefined;
+  }
+  if (current.regular && current.hash === previousHash) {
+    await fs.rm(targetPath, { force: true });
+    report.removed.push(relativePath);
+    return undefined;
+  }
+  if (force) {
+    await backupIfNeeded(targetPath);
+    report.removed.push(relativePath);
+    return undefined;
+  }
+  recordConflict(report, relativePath);
+  return previousHash;
+}
+
+async function readPackageVersion(paths) {
+  const packagePath = join(paths.packageRoot, "package.json");
+  const packageData = await readJsonFileSafe(packagePath);
+  if (typeof packageData.version !== "string" || !packageData.version) {
+    throw new Error(`Missing package version in ${packagePath}`);
+  }
+  return packageData.version;
+}
+
+async function syncManagedFiles({
+  paths,
+  force = false,
+  pathPrefix = null
+}) {
+  const previousMetadata = await readInstallMetadata(paths);
+  const previousManagedFiles = await readManagedFiles(paths, previousMetadata);
+  const manifest = await collectManagedAssets(paths);
+  const report = createInstallReport();
+  const managedFiles = pathPrefix ? { ...previousManagedFiles } : {};
+
+  for (const [relativePath, asset] of manifest) {
+    if (pathPrefix && !relativePath.startsWith(pathPrefix)) continue;
+    const managedHash = await applyManifestEntry(
+      paths,
+      relativePath,
+      asset,
+      previousManagedFiles[relativePath],
+      force,
+      report
+    );
+    if (managedHash) managedFiles[relativePath] = managedHash;
+    else delete managedFiles[relativePath];
+  }
+  for (const [relativePath, previousHash] of Object.entries(previousManagedFiles)) {
+    if (pathPrefix && !relativePath.startsWith(pathPrefix)) continue;
+    if (!manifest.has(relativePath)) {
+      const managedHash = await removeStaleManagedFile(paths, relativePath, previousHash, force, report);
+      if (managedHash) managedFiles[relativePath] = managedHash;
+      else delete managedFiles[relativePath];
+    }
+  }
+
+  return {
+    previousMetadata,
+    packageVersion: await readPackageVersion(paths),
+    managedFiles,
+    report
+  };
+}
+
+async function pathsReferToSameEntry(sourcePath, targetPath) {
+  if (resolve(sourcePath) === resolve(targetPath)) return true;
+  try {
+    return await fs.realpath(sourcePath) === await fs.realpath(targetPath);
+  } catch {
+    return false;
+  }
+}
+
+async function ensureManagedContainerDirectory(targetPath, sourcePath) {
+  if (await pathExists(targetPath)) {
+    const targetStat = await fs.lstat(targetPath);
+    if (targetStat.isSymbolicLink() && await pathsReferToSameEntry(targetPath, sourcePath)) {
+      await fs.unlink(targetPath);
+    } else if (!targetStat.isDirectory()) {
+      throw new Error(`Managed container conflict at ${targetPath}`);
+    }
+  }
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+export {
+  collectManagedAssets,
+  ensureManagedContainerDirectory,
+  hashBytes,
+  pathsReferToSameEntry,
+  readManagedFiles,
+  shouldCopySkillPath,
+  syncManagedFiles
+};

package/lib/installer/install.mjs

@@ -0,0 +1,153 @@
+import { join } from "node:path";
+import { pathExists, readJsonFileSafe } from "../config/store.mjs";
+import { createPaths, defaultPaths } from "../paths.mjs";
+import { readManagedFiles, syncManagedFiles } from "./assets.mjs";
+import { linkClaude, linkCodex, linkPi } from "./links.mjs";
+import {
+  buildInstallMetadata,
+  createInstallReport,
+  mergeInstallReports,
+  mergeLinkedTargets,
+  readInstallMetadata,
+  writeInstallMetadata
+} from "./state.mjs";
+
+function validatedPaths(paths) {
+  if (!paths || typeof paths !== "object" || [
+    paths.homeDir,
+    paths.packageRoot,
+    paths.agentsDir
+  ].some((path) => typeof path !== "string")) {
+    throw new TypeError("Expected a canonical Paths object");
+  }
+  return createPaths({
+    homeDir: paths.homeDir,
+    packageRoot: paths.packageRoot,
+    agentsDir: paths.agentsDir
+  });
+}
+
+function resolveInstallPaths(options = {}) {
+  if (options.paths) return validatedPaths(options.paths);
+  return createPaths({
+    homeDir: options.homeDir ?? defaultPaths.homeDir,
+    packageRoot: options.packageRoot ?? defaultPaths.packageRoot,
+    agentsDir: options.agentsDir ?? defaultPaths.agentsDir
+  });
+}
+
+function reportFromLinkResults(results) {
+  const report = createInstallReport();
+  for (const result of results) {
+    if (result.status === "linked" || result.status === "copied") report.linked.push(result.targetPath);
+    else if (result.status === "unchanged") report.unchanged.push(result.targetPath);
+    else if (result.status === "removed") report.removed.push(result.targetPath);
+    else if (result.status === "conflict") {
+      report.conflicts.push(result.targetPath);
+      report.preserved.push(result.targetPath);
+    } else if (result.status === "skipped") {
+      report.preserved.push(result.targetPath);
+    }
+  }
+  return report;
+}
+
+async function packageVersionFor(paths, previousMetadata) {
+  if (previousMetadata.schemaVersion === 2
+    && typeof previousMetadata.packageVersion === "string"
+    && previousMetadata.packageVersion) {
+    return previousMetadata.packageVersion;
+  }
+  const packagePath = join(paths.packageRoot, "package.json");
+  const packageData = await readJsonFileSafe(packagePath);
+  if (typeof packageData.version !== "string" || !packageData.version) {
+    throw new Error(`Missing package version in ${packagePath}`);
+  }
+  return packageData.version;
+}
+
+async function installWorkflow(options) {
+  const paths = validatedPaths(options.paths);
+  const previousMetadata = await readInstallMetadata(paths);
+  let assetResult;
+
+  if (options.relinkOnly) {
+    if (!(await pathExists(paths.agentsDir))) {
+      throw new Error(`${paths.agentsDir} does not exist; remove --link-only or install first`);
+    }
+    assetResult = {
+      previousMetadata,
+      packageVersion: await packageVersionFor(paths, previousMetadata),
+      managedFiles: await readManagedFiles(paths, previousMetadata),
+      report: createInstallReport()
+    };
+  } else {
+    assetResult = await syncManagedFiles({
+      paths,
+      force: options.force ?? false
+    });
+  }
+
+  const previousLinkedTargets = previousMetadata.linkedTargets ?? {};
+  const linkOptions = { force: options.force ?? false };
+  const claudeResults = await linkClaude(paths, previousLinkedTargets, linkOptions);
+  const codexResults = await linkCodex(paths, previousLinkedTargets, linkOptions);
+  const piResults = await linkPi(paths, previousLinkedTargets, linkOptions);
+  const linkResults = [...claudeResults, ...codexResults, ...piResults];
+  const linkedTargets = mergeLinkedTargets(previousLinkedTargets, linkResults);
+
+  const metadata = buildInstallMetadata({
+    previousMetadata,
+    packageVersion: assetResult.packageVersion,
+    managedFiles: assetResult.managedFiles,
+    linkedTargets
+  });
+  await writeInstallMetadata(paths, metadata);
+  return mergeInstallReports(assetResult.report, reportFromLinkResults(linkResults));
+}
+
+async function installManagedWorkflow(options = {}) {
+  return installWorkflow({ ...options, paths: resolveInstallPaths(options) });
+}
+
+async function ensureSkillPresent(inputPaths, skillName) {
+  const paths = validatedPaths(inputPaths);
+  const previousMetadata = await readInstallMetadata(paths);
+  const assetResult = await syncManagedFiles({
+    paths,
+    force: false,
+    pathPrefix: `skills/${skillName}/`
+  });
+  const metadata = buildInstallMetadata({
+    previousMetadata,
+    packageVersion: assetResult.packageVersion,
+    managedFiles: assetResult.managedFiles,
+    linkedTargets: previousMetadata.linkedTargets ?? {}
+  });
+  await writeInstallMetadata(paths, metadata);
+  return assetResult.report;
+}
+
+async function ensurePiResourcesLinked(inputPaths) {
+  const paths = validatedPaths(inputPaths);
+  const previousMetadata = await readInstallMetadata(paths);
+  const assetResult = await syncManagedFiles({ paths, force: false });
+  const previousLinkedTargets = previousMetadata.linkedTargets ?? {};
+  const piResults = await linkPi(paths, previousLinkedTargets, { force: false });
+  const metadata = buildInstallMetadata({
+    previousMetadata,
+    packageVersion: assetResult.packageVersion,
+    managedFiles: assetResult.managedFiles,
+    linkedTargets: mergeLinkedTargets(previousLinkedTargets, piResults)
+  });
+  await writeInstallMetadata(paths, metadata);
+  return mergeInstallReports(assetResult.report, reportFromLinkResults(piResults));
+}
+
+export {
+  ensurePiResourcesLinked,
+  ensureSkillPresent,
+  installManagedWorkflow,
+  installWorkflow,
+  packageVersionFor
+};