@metagptx/deepflow-suite-cli 0.0.0-stage → 0.1.1

package/src/bundle-installer.mjs

@@ -0,0 +1,189 @@
+import { access, cp, lstat, mkdir, mkdtemp, readdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { CLI_NAME, DISTRIBUTION, PACKAGE_NAME, RELEASE_FILE, SKILL_NAMES } from "./constants.mjs";
+import { listFiles } from "./bundle.mjs";
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function assertRegularTree(root) {
+  const rootStats = await lstat(root);
+  if (rootStats.isSymbolicLink()) throw new Error(`bundle contains a symbolic link: ${root}`);
+  if (!rootStats.isDirectory()) throw new Error(`bundle path is not a directory: ${root}`);
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    const stats = await lstat(entryPath);
+    if (stats.isSymbolicLink()) throw new Error(`bundle contains a symbolic link: ${entryPath}`);
+    if (entry.isDirectory()) await assertRegularTree(entryPath);
+    else if (!stats.isFile()) throw new Error(`bundle contains a non-regular file: ${entryPath}`);
+  }
+}
+
+function validateRelease(release, expectedVersion) {
+  if (!release || typeof release !== "object") throw new Error("invalid DeepFlow bundle release metadata");
+  if (release.schemaVersion !== 1) throw new Error("unsupported DeepFlow bundle schema version");
+  if (release.distribution !== DISTRIBUTION) throw new Error(`bundle distribution must be ${DISTRIBUTION}`);
+  if (release.package !== PACKAGE_NAME) throw new Error(`bundle package must be ${PACKAGE_NAME}`);
+  if (typeof release.version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(release.version)) {
+    throw new Error("bundle version must be a semantic version");
+  }
+  if (expectedVersion && release.version !== expectedVersion) {
+    throw new Error(`bundle version ${release.version} does not match ${expectedVersion}`);
+  }
+  if (!release.cli || release.cli.name !== CLI_NAME || release.cli.package !== PACKAGE_NAME
+      || release.cli.version !== release.version || release.cli.command !== CLI_NAME) {
+    throw new Error("bundle CLI metadata does not match deepflow-suite");
+  }
+  if (!["any", process.platform].includes(release.platform)) {
+    throw new Error(`bundle platform ${release.platform} does not match ${process.platform}`);
+  }
+  if (!["any", process.arch].includes(release.arch)) {
+    throw new Error(`bundle architecture ${release.arch} does not match ${process.arch}`);
+  }
+  if (!Array.isArray(release.skills) || release.skills.length !== SKILL_NAMES.length) {
+    throw new Error("bundle must contain exactly seven skills, including deepflow-suite");
+  }
+  const names = release.skills.map((skill) => skill?.name);
+  if (new Set(names).size !== names.length || JSON.stringify([...names].sort()) !== JSON.stringify([...SKILL_NAMES].sort())) {
+    throw new Error("bundle must contain exactly the manifest skills, including deepflow-suite");
+  }
+  for (const skill of release.skills) {
+    if (!Array.isArray(skill.files) || skill.files.length === 0) {
+      throw new Error(`bundle skill ${skill.name} is missing file metadata`);
+    }
+    for (const file of skill.files) {
+      if (!file || typeof file.path !== "string" || path.isAbsolute(file.path) || file.path.split(/[\\/]/).includes("..")) {
+        throw new Error(`bundle skill ${skill.name} contains an invalid file path`);
+      }
+      if (!Number.isSafeInteger(file.size) || file.size < 0 || !/^[a-f0-9]{64}$/.test(file.sha256)) {
+        throw new Error(`bundle skill ${skill.name} contains invalid file metadata`);
+      }
+    }
+  }
+}
+
+async function verifySkillFiles(bundleDir, skill) {
+  const source = path.join(bundleDir, "skills", skill.name);
+  await assertRegularTree(source);
+  const actual = await listFiles(source);
+  const expected = [...skill.files].sort((left, right) => left.path.localeCompare(right.path));
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`bundle skill ${skill.name} file size or sha256 does not match release metadata`);
+  }
+  const skillFile = path.join(source, "SKILL.md");
+  if (!await exists(skillFile)) throw new Error(`bundle skill ${skill.name} is missing SKILL.md`);
+}
+
+async function verifyInstalledSkill(targetDir, skill) {
+  const source = path.join(targetDir, skill.name);
+  await assertRegularTree(source);
+  const actual = await listFiles(source);
+  const expected = [...skill.files].sort((left, right) => left.path.localeCompare(right.path));
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`installed Skill ${skill.name} file size or sha256 does not match release metadata`);
+  }
+  if (!await exists(path.join(source, "SKILL.md"))) {
+    throw new Error(`installed Skill ${skill.name} is missing SKILL.md`);
+  }
+}
+
+async function inspect(pathname) {
+  try {
+    return await lstat(pathname);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function installTransaction({ bundleDir, targetDir, names, force }) {
+  if (!targetDir) throw new Error("Skill target directory is required");
+  const resolvedTarget = path.resolve(targetDir);
+  const parent = path.dirname(resolvedTarget);
+  await mkdir(parent, { recursive: true });
+  const targetStats = await inspect(resolvedTarget);
+  if (targetStats && !targetStats.isDirectory()) throw new Error(`Skill target is not a directory: ${resolvedTarget}`);
+
+  for (const name of names) {
+    const target = path.join(resolvedTarget, name);
+    const stats = await inspect(target);
+    if (stats && !force && !stats.isSymbolicLink()) {
+      throw new Error(`refusing to replace existing Skill without --force: ${target}`);
+    }
+  }
+
+  const staging = await mkdtemp(path.join(parent, `.${path.basename(resolvedTarget)}.tmp-`));
+  try {
+    for (const name of names) {
+      await cp(path.join(bundleDir, "skills", name), path.join(staging, name), {
+        recursive: true,
+        dereference: false,
+      });
+    }
+    await mkdir(resolvedTarget, { recursive: true });
+    const backup = await mkdtemp(path.join(resolvedTarget, ".deepflow-backup-"));
+    const installed = [];
+    const backedUp = [];
+    try {
+      for (const name of names) {
+        const target = path.join(resolvedTarget, name);
+        if (await inspect(target)) {
+          await rename(target, path.join(backup, name));
+          backedUp.push(name);
+        }
+        await rename(path.join(staging, name), target);
+        installed.push(name);
+      }
+      await rm(backup, { recursive: true, force: true });
+      return { targetDir: resolvedTarget, installed };
+    } catch (error) {
+      for (const name of installed) await rm(path.join(resolvedTarget, name), { recursive: true, force: true });
+      for (const name of backedUp) await rename(path.join(backup, name), path.join(resolvedTarget, name));
+      await rm(backup, { recursive: true, force: true });
+      throw error;
+    }
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+export async function verifyBundle({ bundleDir, expectedVersion }) {
+  if (!bundleDir) throw new Error("bundle directory is required");
+  const release = JSON.parse(await readFile(path.join(bundleDir, RELEASE_FILE), "utf8"));
+  validateRelease(release, expectedVersion);
+  const sourceDir = path.join(bundleDir, "skills");
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  if (entries.some((entry) => !entry.isDirectory())) {
+    throw new Error("bundle skills directory must contain only Skill directories");
+  }
+  const actual = entries.map((entry) => entry.name).sort();
+  if (JSON.stringify(actual) !== JSON.stringify([...SKILL_NAMES].sort())) {
+    throw new Error("bundle must contain exactly the manifest skills, including deepflow-suite");
+  }
+  for (const skill of release.skills) await verifySkillFiles(bundleDir, skill);
+  return release;
+}
+
+export async function verifyInstalledBundle({ bundleDir, targetDir, expectedVersion }) {
+  const release = await verifyBundle({ bundleDir, expectedVersion });
+  if (!targetDir) throw new Error("Skill target directory is required");
+  const stats = await inspect(path.resolve(targetDir));
+  if (!stats || !stats.isDirectory()) throw new Error(`Skill target directory is missing: ${targetDir}`);
+  for (const skill of release.skills) await verifyInstalledSkill(path.resolve(targetDir), skill);
+  return release;
+}
+
+export async function installBundleSkills({ bundleDir, targetDir, force = false, expectedVersion }) {
+  await verifyBundle({ bundleDir, expectedVersion });
+  return installTransaction({ bundleDir, targetDir, names: SKILL_NAMES, force });
+}
+
+export { validateRelease };

package/src/bundle.mjs

@@ -0,0 +1,128 @@
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { CLI_NAME, PACKAGE_NAME, RELEASE_FILE } from "./constants.mjs";
+import { loadManifest, resolveSkillSources } from "./manifest.mjs";
+
+async function hashFile(filePath) {
+  const contents = await readFile(filePath);
+  return {
+    size: contents.byteLength,
+    sha256: createHash("sha256").update(contents).digest("hex"),
+  };
+}
+
+async function assertNoSymlinks(root) {
+  const rootStats = await lstat(root);
+  if (rootStats.isSymbolicLink()) throw new Error(`bundle source contains a symbolic link: ${root}`);
+  if (!rootStats.isDirectory()) throw new Error(`bundle source is not a directory: ${root}`);
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    const stats = await lstat(entryPath);
+    if (stats.isSymbolicLink()) {
+      throw new Error(`bundle contains a symbolic link: ${entryPath}`);
+    }
+    if (entry.isDirectory()) await assertNoSymlinks(entryPath);
+  }
+}
+
+async function listFiles(root, current = root) {
+  const entries = await readdir(current, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const absolute = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFiles(root, absolute));
+      continue;
+    }
+    const stats = await lstat(absolute);
+    if (!stats.isFile()) throw new Error(`bundle contains a non-regular file: ${absolute}`);
+    const digest = await hashFile(absolute);
+    files.push({
+      path: path.relative(root, absolute).split(path.sep).join("/"),
+      ...digest,
+    });
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+async function assembleInto({ workspaceRoot, outputDir, manifestPath }) {
+  const manifest = await loadManifest(manifestPath);
+  const sources = resolveSkillSources(manifest, workspaceRoot);
+  await mkdir(path.join(outputDir, "skills"), { recursive: true });
+
+  const skills = [];
+  for (const skill of sources) {
+    await assertNoSymlinks(skill.sourcePath);
+    const skillFile = path.join(skill.sourcePath, "SKILL.md");
+    const skillStats = await lstat(skillFile).catch((error) => {
+      if (error.code === "ENOENT") throw new Error(`missing Skill source: ${skillFile}`);
+      throw error;
+    });
+    if (!skillStats.isFile() || skillStats.size === 0) {
+      throw new Error(`missing or empty Skill source: ${skillFile}`);
+    }
+    const destination = path.join(outputDir, "skills", skill.name);
+    await cp(skill.sourcePath, destination, { recursive: true, dereference: false });
+    skills.push({
+      name: skill.name,
+      source: skill.source,
+      files: await listFiles(destination),
+    });
+  }
+
+  const release = {
+    schemaVersion: 1,
+    distribution: manifest.distribution,
+    package: PACKAGE_NAME,
+    version: manifest.version,
+    platform: process.platform,
+    arch: process.arch,
+    cli: {
+      name: CLI_NAME,
+      package: PACKAGE_NAME,
+      version: manifest.version,
+      command: CLI_NAME,
+    },
+    skills,
+    clis: manifest.clis,
+  };
+  await writeFile(
+    path.join(outputDir, RELEASE_FILE),
+    `${JSON.stringify(release, null, 2)}\n`,
+  );
+  return { skills: skills.map((skill) => skill.name), manifest: release };
+}
+
+export async function assembleBundle({ workspaceRoot, outputDir, manifestPath }) {
+  if (!outputDir) throw new Error("bundle output directory is required");
+  const resolvedOutput = path.resolve(outputDir);
+  await mkdir(path.dirname(resolvedOutput), { recursive: true });
+  const staging = await mkdtemp(path.join(path.dirname(resolvedOutput), `.${path.basename(resolvedOutput)}.tmp-`));
+  try {
+    const result = await assembleInto({ workspaceRoot, outputDir: staging, manifestPath });
+    const backup = `${resolvedOutput}.backup-${process.pid}-${Date.now()}`;
+    let movedExisting = false;
+    try {
+      await rename(resolvedOutput, backup);
+      movedExisting = true;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    try {
+      await rename(staging, resolvedOutput);
+    } catch (error) {
+      if (movedExisting) await rename(backup, resolvedOutput);
+      throw error;
+    }
+    if (movedExisting) await rm(backup, { recursive: true, force: true });
+    return { ...result, outputDir: resolvedOutput };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export { listFiles };

package/src/cli-install.mjs

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import { access, lstat, mkdir, mkdtemp, readlink, rename, rm, symlink, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+function run(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, stdio: "inherit", env: options.env });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} ${args.join(" ")} exited with ${code ?? signal}`));
+    });
+  });
+}
+
+async function replaceLink(source, target) {
+  await mkdir(path.dirname(target), { recursive: true });
+  try {
+    const stats = await lstat(target);
+    if (!stats.isSymbolicLink()) {
+      throw new Error(`refusing to replace non-symlink CLI target: ${target}`);
+    }
+    const current = path.resolve(path.dirname(target), await readlink(target));
+    if (current === source) return "unchanged";
+    await unlink(target);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  await symlink(path.relative(path.dirname(target), source), target);
+  return "created";
+}
+
+async function sourceExists(source) {
+  try {
+    await access(source);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function installWorkspaceClis({ workspaceRoot, manifest, binDir, force = false }) {
+  const destination = binDir
+    ? path.resolve(binDir)
+    : path.join(process.env.HOME ?? os.homedir(), ".local", "bin");
+  const result = { linked: [], built: [] };
+
+  await mkdir(destination, { recursive: true });
+  const targets = manifest.clis.map((cli) => ({ cli, target: path.join(destination, cli.name) }));
+  for (const { cli, target } of targets) {
+    try {
+      const stats = await lstat(target);
+      if (!force) {
+        throw new Error(`refusing to replace existing CLI without --force: ${target}`);
+      }
+      if (stats.isDirectory()) throw new Error(`refusing to replace CLI directory: ${target}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+
+  const backup = await mkdtemp(path.join(destination, ".deepflow-cli-backup-"));
+  const backedUp = [];
+  const touched = [];
+  try {
+    for (const { cli, target } of targets) {
+      try {
+        await lstat(target);
+        await rename(target, path.join(backup, cli.name));
+        backedUp.push(cli.name);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+
+  for (const cli of manifest.clis) {
+    const projectRoot = path.join(workspaceRoot, cli.project);
+    const target = path.join(destination, cli.name);
+
+    if (cli.name === "df-workbench") {
+      const source = path.join(projectRoot, "cli", "df-workbench.mjs");
+      if (!(await sourceExists(source))) throw new Error(`missing CLI source: ${source}`);
+      await replaceLink(source, target);
+      touched.push(cli.name);
+      result.linked.push(cli.name);
+      continue;
+    }
+
+    if (cli.name === "df-agentrt") {
+      await run("make", ["build"], { cwd: projectRoot, env: process.env });
+      const source = path.join(projectRoot, "deploy", "bin", "df-agentrt");
+      if (!(await sourceExists(source))) throw new Error(`missing built CLI: ${source}`);
+      await replaceLink(source, target);
+      touched.push(cli.name);
+      result.built.push(cli.name);
+      continue;
+    }
+
+    await run("make", ["install-cli", `BIN_DIR=${destination}`], {
+      cwd: projectRoot,
+      env: process.env,
+    });
+    touched.push(cli.name);
+    result.built.push(cli.name);
+  }
+
+  await rm(backup, { recursive: true, force: true });
+  return { binDir: destination, ...result };
+  } catch (error) {
+    for (const { cli } of targets) await rm(path.join(destination, cli.name), { recursive: true, force: true });
+    for (const name of backedUp) await rename(path.join(backup, name), path.join(destination, name));
+    throw error;
+  } finally {
+    await rm(backup, { recursive: true, force: true });
+  }
+}
+
+export async function verifyWorkspaceClis({ workspaceRoot, manifest, binDir }) {
+  const destination = binDir
+    ? path.resolve(binDir)
+    : path.join(process.env.HOME ?? os.homedir(), ".local", "bin");
+  const missing = [];
+  const invalid = [];
+  for (const cli of manifest.clis) {
+    try {
+      const target = path.join(destination, cli.name);
+      const stats = await lstat(target);
+      await access(target);
+      if (stats.isDirectory()) invalid.push({ name: cli.name, reason: "target is a directory" });
+    } catch (error) {
+      if (error.code === "ENOENT") {
+      missing.push(cli.name);
+      } else {
+        invalid.push({ name: cli.name, reason: error.message });
+      }
+    }
+  }
+  return { binDir: destination, missing, invalid };
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,35 @@
+import path from "node:path";
+
+import { defaultCodexSkillsDir } from "../constants.mjs";
+import { verifyInstalledBundle } from "../bundle-installer.mjs";
+import { verifyWorkspaceSkills } from "../linker.mjs";
+import { verifyWorkspaceClis } from "../cli-install.mjs";
+import { loadManifest } from "../manifest.mjs";
+
+export async function doctor(options) {
+  if (options.source === "package" || options.source === "bundle") {
+    const bundleDir = options.bundleDir ?? path.join(path.dirname(options.manifestPath), "bundle");
+    const targetDir = options.targetDir ?? defaultCodexSkillsDir();
+    try {
+      const manifest = await loadManifest(options.manifestPath);
+      const release = await verifyInstalledBundle({ bundleDir, targetDir, expectedVersion: manifest.version });
+      return {
+        ok: true,
+        bundleDir,
+        targetDir,
+        release,
+      };
+    } catch (error) {
+      return { ok: false, bundleDir, error: error.message };
+    }
+  }
+  const links = await verifyWorkspaceSkills(options);
+  const manifest = await loadManifest(options.manifestPath);
+  const clis = await verifyWorkspaceClis({ ...options, manifest });
+  return {
+    ok: links.missing.length === 0 && links.invalid.length === 0 && links.sources.length === 0
+      && clis.missing.length === 0 && clis.invalid.length === 0,
+    skills: links,
+    clis,
+  };
+}

package/src/commands/install.mjs

@@ -0,0 +1,32 @@
+import path from "node:path";
+
+import { defaultCodexSkillsDir } from "../constants.mjs";
+import { installBundleSkills } from "../bundle-installer.mjs";
+import { installWorkspaceSkills } from "../linker.mjs";
+import { installWorkspaceClis } from "../cli-install.mjs";
+import { loadManifest } from "../manifest.mjs";
+
+export async function install(options) {
+  if (options.source === "package") {
+    const packageRoot = path.dirname(options.manifestPath);
+    const manifest = await loadManifest(options.manifestPath);
+    const bundleDir = options.bundleDir ?? path.join(packageRoot, "bundle");
+    return {
+      skills: await installBundleSkills({
+        bundleDir,
+        targetDir: options.targetDir ?? defaultCodexSkillsDir(),
+        force: options.force,
+        expectedVersion: manifest.version,
+      }),
+      clis: { package: "@metagptx/deepflow-suite-cli" },
+    };
+  }
+  if (options.source !== "workspace") {
+    throw new Error("--source must be workspace or package");
+  }
+  const skills = await installWorkspaceSkills(options);
+  if (options.skipCli) return { skills, clis: { skipped: true } };
+  const manifest = await loadManifest(options.manifestPath);
+  const clis = await installWorkspaceClis({ ...options, manifest });
+  return { skills, clis };
+}

package/src/constants.mjs

@@ -0,0 +1,30 @@
+import os from "node:os";
+import path from "node:path";
+
+export const DISTRIBUTION = "deepflow-suite";
+export const PACKAGE_NAME = "@metagptx/deepflow-suite-cli";
+export const CLI_NAME = "deepflow-suite";
+export const RELEASE_FILE = "deepflow-release.json";
+
+export const SKILL_NAMES = [
+  "deepflow-suite",
+  "df-workbench",
+  "df-task",
+  "df-taskdriver",
+  "df-agentctrl",
+  "df-agentrt",
+  "df-agentrt-repo",
+];
+
+export const CLI_NAMES = [
+  "df-workbench",
+  "df-task",
+  "df-taskdriver",
+  "df-agentctrl",
+  "df-agentrt",
+];
+
+export function defaultCodexSkillsDir() {
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}

package/src/linker.mjs

@@ -0,0 +1,96 @@
+import { lstat, mkdir, readlink, symlink, unlink, access, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { loadManifest, resolveSkillSources } from "./manifest.mjs";
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function inspectTarget(targetPath) {
+  try {
+    const stats = await lstat(targetPath);
+    return stats.isSymbolicLink() ? "symlink" : "other";
+  } catch (error) {
+    if (error.code === "ENOENT") return "missing";
+    throw error;
+  }
+}
+
+export async function installWorkspaceSkills({ workspaceRoot, targetDir, force = false, manifestPath }) {
+  const manifest = await loadManifest(manifestPath);
+  const skills = resolveSkillSources(manifest, workspaceRoot, "workspace");
+  const destination = targetDir ?? path.join(workspaceRoot, ".agents", "skills");
+
+  for (const skill of skills) {
+    if (!(await exists(path.join(skill.sourcePath, "SKILL.md")))) {
+      throw new Error(`missing Skill source: ${skill.sourcePath}/SKILL.md`);
+    }
+    const targetPath = path.join(destination, skill.name);
+    const kind = await inspectTarget(targetPath);
+    if (kind === "other" && !force) {
+      throw new Error(`refusing to replace non-symlink Skill target: ${targetPath}`);
+    }
+  }
+
+  await mkdir(destination, { recursive: true });
+  const result = { created: [], updated: [], unchanged: [] };
+  for (const skill of skills) {
+    const targetPath = path.join(destination, skill.name);
+    const relativeSource = path.relative(destination, skill.sourcePath);
+    const kind = await inspectTarget(targetPath);
+    if (kind === "symlink") {
+      const current = await readlink(targetPath);
+      const currentAbsolute = path.resolve(destination, current);
+      if (currentAbsolute === skill.sourcePath) {
+        result.unchanged.push(skill.name);
+        continue;
+      }
+      await unlink(targetPath);
+      await symlink(relativeSource, targetPath, "dir");
+      result.updated.push(skill.name);
+      continue;
+    }
+    if (kind === "other") {
+      if (!force) throw new Error(`refusing to replace non-symlink Skill target: ${targetPath}`);
+      await rm(targetPath, { recursive: true, force: true });
+    }
+    await symlink(relativeSource, targetPath, "dir");
+    result.created.push(skill.name);
+  }
+  return result;
+}
+
+export async function verifyWorkspaceSkills({ workspaceRoot, targetDir, manifestPath }) {
+  const manifest = await loadManifest(manifestPath);
+  const skills = resolveSkillSources(manifest, workspaceRoot, "workspace");
+  const destination = targetDir ?? path.join(workspaceRoot, ".agents", "skills");
+  const missing = [];
+  const invalid = [];
+  const sources = [];
+  for (const skill of skills) {
+    if (!(await exists(path.join(skill.sourcePath, "SKILL.md")))) {
+      sources.push({ name: skill.name, path: skill.sourcePath });
+    }
+    const targetPath = path.join(destination, skill.name);
+    const kind = await inspectTarget(targetPath);
+    if (kind === "missing") {
+      missing.push(skill.name);
+      continue;
+    }
+    if (kind !== "symlink") {
+      invalid.push({ name: skill.name, reason: "target is not a symlink" });
+      continue;
+    }
+    const current = path.resolve(destination, await readlink(targetPath));
+    if (current !== skill.sourcePath) {
+      invalid.push({ name: skill.name, reason: `points to ${current}` });
+    }
+  }
+  return { missing, invalid, sources };
+}