@oh-my-tool/cli 0.2.0

package/src/extension/manifest.ts

@@ -0,0 +1,115 @@
+import { OMT_API_VERSION, type ExtensionManifest } from "@oh-my-tool/sdk";
+
+export class ManifestError extends Error {}
+
+export function parseManifest(raw: string): ExtensionManifest {
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new ManifestError("manifest is not valid JSON");
+  }
+  const obj = data as Partial<ExtensionManifest>;
+  if (!obj.id || typeof obj.id !== "string") {
+    throw new ManifestError("manifest must contain a string 'id'");
+  }
+  if (!Array.isArray(obj.tools)) {
+    throw new ManifestError("manifest must contain a 'tools' array");
+  }
+  return obj as ExtensionManifest;
+}
+
+export function validateManifest(manifest: ExtensionManifest): void {
+  if (!manifest.name || typeof manifest.name !== "string") {
+    throw new ManifestError("manifest must contain a string 'name'");
+  }
+  if (!manifest.version || typeof manifest.version !== "string") {
+    throw new ManifestError("manifest must contain a string 'version'");
+  }
+  if (!manifest.sdkVersion || typeof manifest.sdkVersion !== "string") {
+    throw new ManifestError("manifest must contain a string 'sdkVersion'");
+  }
+
+  const seen = new Set<string>();
+  for (const tool of manifest.tools) {
+    if (!tool.name || typeof tool.name !== "string") {
+      throw new ManifestError("each tool must have a string 'name'");
+    }
+    if (seen.has(tool.name)) {
+      throw new ManifestError(`duplicate tool name '${tool.name}'`);
+    }
+    seen.add(tool.name);
+
+    const prefix = `${manifest.id}.`;
+    if (!tool.name.startsWith(prefix)) {
+      throw new ManifestError(
+        `tool '${tool.name}' must be prefixed by extension id '${manifest.id}.'`,
+      );
+    }
+  }
+}
+
+const FULL_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const PARTIAL_VERSION_RE = /^(\d+|x|X|\*)(\.(\d+|x|X|\*))?(\.(\d+|x|X|\*))?$/;
+
+function isValidVersionToken(token: string): boolean {
+  return FULL_VERSION_RE.test(token) || PARTIAL_VERSION_RE.test(token);
+}
+
+function isValidSemverRange(range: string): boolean {
+  const trimmed = range.trim();
+  if (!trimmed) return false;
+  for (const orPart of trimmed.split("||")) {
+    const pieces = orPart.trim().split(/\s+/).filter(Boolean);
+    if (pieces.length === 0) return false;
+    for (let i = 0; i < pieces.length; i++) {
+      const piece = pieces[i];
+      if (piece === "-") {
+        if (i === 0 || i === pieces.length - 1) return false;
+        continue;
+      }
+      const m = piece.match(/^(>=|<=|>|<|=|\^|~)?(.*)$/);
+      if (!m || m[2] === "" || !isValidVersionToken(m[2])) return false;
+    }
+  }
+  return true;
+}
+
+export function checkSdkCompatibility(requiredRange: string): void {
+  if (typeof requiredRange !== "string" || requiredRange.trim() === "") {
+    throw new ManifestError("extension must declare a non-empty 'sdkVersion'");
+  }
+  if (!isValidSemverRange(requiredRange)) {
+    throw new ManifestError(
+      `invalid sdkVersion '${requiredRange}': not a valid semver range`,
+    );
+  }
+  if (!Bun.semver.satisfies(OMT_API_VERSION, requiredRange)) {
+    throw new ManifestError(
+      `extension requires sdk '${requiredRange}' but core provides '${OMT_API_VERSION}'`,
+    );
+  }
+}
+
+export function validateHandlers(
+  manifest: ExtensionManifest,
+  handlerNames: string[],
+): void {
+  const handlerSet = new Set(handlerNames);
+  const manifestSet = new Set(manifest.tools.map((t) => t.name));
+
+  for (const name of manifest.tools.map((t) => t.name)) {
+    if (!handlerSet.has(name)) {
+      throw new ManifestError(
+        `manifest declares tool '${name}' but runtime has no handler`,
+      );
+    }
+  }
+  for (const name of handlerNames) {
+    if (!manifestSet.has(name)) {
+      throw new ManifestError(
+        `runtime registers tool '${name}' not declared in manifest`,
+      );
+    }
+  }
+}

package/src/integration/adapters.ts

@@ -0,0 +1,98 @@
+import { homedir } from "node:os";
+import { basename, delimiter, extname, join } from "node:path";
+import { existsSync } from "node:fs";
+import type { AgentDetection, AgentId } from "./types";
+
+export type FindCommand = (candidates: string[]) => Promise<string | undefined> | string | undefined;
+
+export interface DetectionOptions {
+  userHome?: string;
+  findCommand?: FindCommand;
+}
+
+interface AdapterDefinition {
+  id: AgentId;
+  displayName: string;
+  commands: string[];
+  target(userHome: string, command: string): string;
+  variant?(command: string): string | undefined;
+}
+
+const definitions: AdapterDefinition[] = [
+  {
+    id: "codex",
+    displayName: "Codex",
+    commands: ["codex"],
+    target: (home) => join(home, ".agents", "skills", "oh-my-tool"),
+  },
+  {
+    id: "omp",
+    displayName: "OMP",
+    commands: ["omp"],
+    target: (home) => join(home, ".omp", "agent", "skills", "oh-my-tool"),
+  },
+  {
+    id: "qoder",
+    displayName: "Qoder",
+    commands: ["qoderclicn", "qodercli", "qoder"],
+    target: (home, command) =>
+      commandName(command) === "qoderclicn"
+        ? join(home, ".qoder-cn", "skills", "oh-my-tool")
+        : join(home, ".qoder", "skills", "oh-my-tool"),
+    variant: (command) => (commandName(command) === "qoderclicn" ? "Qoder CLI CN" : undefined),
+  },
+  {
+    id: "pi",
+    displayName: "Pi",
+    commands: ["pi"],
+    target: (home) => join(home, ".agents", "skills", "oh-my-tool"),
+  },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    commands: ["cursor"],
+    target: (home) => join(home, ".agents", "skills", "oh-my-tool"),
+  },
+  {
+    id: "claude",
+    displayName: "Claude Code",
+    commands: ["claude"],
+    target: (home) => join(home, ".claude", "skills", "oh-my-tool"),
+  },
+];
+
+function commandName(command: string): string {
+  return basename(command, extname(command)).toLowerCase();
+}
+
+export function findCommandOnPath(candidates: string[]): string | undefined {
+  const pathEntries = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const suffixes = process.platform === "win32" ? [".exe", ".cmd", ".bat", ".ps1", ""] : [""];
+  for (const candidate of candidates) {
+    for (const directory of pathEntries) {
+      for (const suffix of suffixes) {
+        const path = join(directory, candidate + suffix);
+        if (existsSync(path)) return path;
+      }
+    }
+  }
+  return undefined;
+}
+
+export async function detectAgents(options: DetectionOptions = {}): Promise<AgentDetection[]> {
+  const userHome = options.userHome ?? homedir();
+  const findCommand = options.findCommand ?? findCommandOnPath;
+  const detected: AgentDetection[] = [];
+  for (const definition of definitions) {
+    const command = await findCommand(definition.commands);
+    if (!command) continue;
+    detected.push({
+      id: definition.id,
+      displayName: definition.displayName,
+      command,
+      target: definition.target(userHome, command),
+      variant: definition.variant?.(command),
+    });
+  }
+  return detected;
+}

package/src/integration/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./adapters";
+export * from "./skill";
+export * from "./manager";

package/src/integration/manager.ts

@@ -0,0 +1,375 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { bundledSkillPath, stageCanonicalSkill } from "./skill";
+import { detectAgents, type FindCommand } from "./adapters";
+import type {
+  AgentDetection,
+  AgentId,
+  IntegrationResult,
+  IntegrationState,
+  ManagedAgentState,
+} from "./types";
+
+export class IntegrationConflictError extends Error {
+  constructor(target: string) {
+    super(`Integration target already exists and is not managed by OMT: ${target}`);
+    this.name = "IntegrationConflictError";
+  }
+}
+
+export interface IntegrationManagerOptions {
+  omtHome: string;
+  userHome?: string;
+  skillSource?: string;
+  skillVersion: string;
+  findCommand?: FindCommand;
+  platform?: NodeJS.Platform;
+  now?: () => Date;
+  linkDirectory?: (source: string, target: string, platform: NodeJS.Platform) => void;
+}
+
+export interface InstallOptions {
+  force?: boolean;
+}
+
+interface LinkOperation {
+  target: string;
+  previous?: string;
+  created: boolean;
+}
+
+function emptyState(): IntegrationState {
+  return { schemaVersion: 1, skills: {} };
+}
+
+function safeRealpath(path: string): string | undefined {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+function isLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function pathPresent(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isManagedLink(path: string, canonical: string): boolean {
+  if (!isLink(path)) return false;
+  const actual = safeRealpath(path);
+  const expected = safeRealpath(canonical);
+  if (actual && expected) return actual === expected;
+  try {
+    const linked = readlinkSync(path);
+    return resolve(dirname(path), linked) === resolve(canonical);
+  } catch {
+    return false;
+  }
+}
+
+function samePath(left: string, right: string, platform: NodeJS.Platform): boolean {
+  const a = resolve(left);
+  const b = resolve(right);
+  return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+export function assertSafeAgentTarget(
+  agent: AgentDetection,
+  userHome: string,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  const agentsSkills = join(userHome, ".agents", "skills");
+  const allowedParents: Record<AgentId, string[]> = {
+    codex: [agentsSkills],
+    omp: [join(userHome, ".omp", "agent", "skills")],
+    qoder: [join(userHome, ".qoder", "skills"), join(userHome, ".qoder-cn", "skills")],
+    pi: [agentsSkills],
+    cursor: [agentsSkills],
+    claude: [join(userHome, ".claude", "skills")],
+  };
+  const target = resolve(agent.target);
+  const parentAllowed = allowedParents[agent.id].some((parent) => samePath(dirname(target), parent, platform));
+  if (basename(target) !== "oh-my-tool" || !parentAllowed) {
+    throw new Error(`Unsafe agent skill target: ${agent.target}`);
+  }
+}
+
+function unlinkOnly(path: string): void {
+  if (!pathPresent(path)) return;
+  if (!isLink(path)) throw new Error(`Refusing to delete non-link path: ${path}`);
+  unlinkSync(path);
+}
+
+function assertSafeManagedState(
+  agent: AgentDetection,
+  recorded: ManagedAgentState,
+  omtHome: string,
+  platform: NodeJS.Platform,
+): void {
+  if (!samePath(recorded.target, agent.target, platform)) {
+    throw new Error(`Unsafe managed target in state: ${recorded.target}`);
+  }
+  const canonicalRoot = resolve(omtHome, "integrations", "skills", "oh-my-tool");
+  if (!samePath(dirname(recorded.canonical), canonicalRoot, platform)) {
+    throw new Error(`Unsafe managed canonical path: ${recorded.canonical}`);
+  }
+  if (recorded.backup) {
+    const backup = resolve(recorded.backup);
+    const expectedPrefix = `${resolve(agent.target)}.backup-`;
+    const prefixMatches = platform === "win32"
+      ? backup.toLowerCase().startsWith(expectedPrefix.toLowerCase())
+      : backup.startsWith(expectedPrefix);
+    if (!prefixMatches || !samePath(dirname(backup), dirname(agent.target), platform)) {
+      throw new Error(`Unsafe managed backup path: ${recorded.backup}`);
+    }
+  }
+}
+
+export function createIntegrationManager(options: IntegrationManagerOptions) {
+  const userHome = options.userHome ?? homedir();
+  const source = options.skillSource ?? bundledSkillPath();
+  const statePath = join(options.omtHome, "integrations", "state.json");
+  const platform = options.platform ?? process.platform;
+  const now = options.now ?? (() => new Date());
+
+  function loadState(): IntegrationState {
+    if (!existsSync(statePath)) return emptyState();
+    const parsed = JSON.parse(readFileSync(statePath, "utf8")) as IntegrationState;
+    return parsed.schemaVersion === 1 ? parsed : emptyState();
+  }
+
+  function saveState(state: IntegrationState): void {
+    mkdirSync(dirname(statePath), { recursive: true });
+    const staging = `${statePath}.tmp-${process.pid}`;
+    writeFileSync(staging, JSON.stringify(state, null, 2) + "\n", "utf8");
+    renameSync(staging, statePath);
+  }
+
+  async function detections(): Promise<AgentDetection[]> {
+    const found = await detectAgents({ userHome, findCommand: options.findCommand });
+    for (const agent of found) assertSafeAgentTarget(agent, userHome, platform);
+    return found;
+  }
+
+  async function selected(ids?: AgentId[]): Promise<AgentDetection[]> {
+    const found = await detections();
+    if (!ids?.length) return found;
+    const byId = new Map(found.map((agent) => [agent.id, agent]));
+    return ids.map((id) => {
+      const agent = byId.get(id);
+      if (!agent) throw new Error(`Agent is not detected: ${id}`);
+      return agent;
+    });
+  }
+
+  function createManagedLink(canonical: string, target: string): void {
+    mkdirSync(dirname(target), { recursive: true });
+    const staging = `${target}.omt-tmp-${process.pid}-${Date.now()}`;
+    if (pathPresent(staging)) throw new Error(`Refusing to replace existing staging path: ${staging}`);
+    try {
+      if (options.linkDirectory) options.linkDirectory(canonical, staging, platform);
+      else symlinkSync(canonical, staging, platform === "win32" ? "junction" : "dir");
+      renameSync(staging, target);
+    } catch (error) {
+      if (isLink(staging)) unlinkSync(staging);
+      throw error;
+    }
+  }
+
+  async function install(ids?: AgentId[], installOptions: InstallOptions = {}): Promise<IntegrationResult[]> {
+    const agents = await selected(ids);
+    if (!agents.length) return [];
+    const canonical = stageCanonicalSkill(options.omtHome, source, options.skillVersion);
+    const state = loadState();
+    const skillState = state.skills["oh-my-tool"] ?? {
+      version: options.skillVersion,
+      digest: canonical.digest,
+      agents: {},
+    };
+    const operations: LinkOperation[] = [];
+    const results: IntegrationResult[] = [];
+
+    try {
+      for (const agent of agents) {
+        const recorded = skillState.agents[agent.id];
+        if (recorded) assertSafeManagedState(agent, recorded, options.omtHome, platform);
+        const targetRealpath = safeRealpath(agent.target);
+        const canonicalRealpath = realpathSync(canonical.path);
+        if (targetRealpath === canonicalRealpath && isLink(agent.target)) {
+          skillState.agents[agent.id] = managedState(agent.target, canonical.path, canonical.digest);
+          results.push(result(agent, "current"));
+          continue;
+        }
+
+        let previous: string | undefined;
+        let backup: string | undefined;
+        if (pathPresent(agent.target)) {
+          const isRecordedLink = recorded && isManagedLink(agent.target, recorded.canonical);
+          if (!isRecordedLink && !installOptions.force) throw new IntegrationConflictError(agent.target);
+          backup = installOptions.force && !isRecordedLink
+            ? `${agent.target}.backup-${timestamp(now())}`
+            : `${agent.target}.omt-old-${process.pid}-${Date.now()}`;
+          renameSync(agent.target, backup);
+          previous = backup;
+        }
+
+        const operation: LinkOperation = { target: agent.target, previous, created: false };
+        operations.push(operation);
+        createManagedLink(canonical.path, agent.target);
+        operation.created = true;
+        const managed = managedState(agent.target, canonical.path, canonical.digest);
+        if (installOptions.force && previous && !previous.includes(".omt-old-")) managed.backup = previous;
+        skillState.agents[agent.id] = managed;
+        results.push(result(agent, "installed"));
+      }
+      skillState.version = options.skillVersion;
+      skillState.digest = canonical.digest;
+      state.skills["oh-my-tool"] = skillState;
+      saveState(state);
+      for (const operation of operations) {
+        if (operation.previous?.includes(".omt-old-") && pathPresent(operation.previous)) {
+          unlinkOnly(operation.previous);
+        }
+      }
+      return results;
+    } catch (error) {
+      for (const operation of operations.reverse()) {
+        if (operation.created) unlinkOnly(operation.target);
+        if (operation.previous && pathPresent(operation.previous)) renameSync(operation.previous, operation.target);
+      }
+      throw error;
+    }
+  }
+
+  async function status(): Promise<IntegrationResult[]> {
+    const agents = await detections();
+    const state = loadState();
+    const records = state.skills["oh-my-tool"]?.agents ?? {};
+    return agents.map((agent) => {
+      const recorded = records[agent.id];
+      if (!recorded) {
+        if (!pathPresent(agent.target)) {
+          return result(agent, "not-installed", "not installed; run `omt integrate` to install");
+        }
+        return result(agent, "conflict", "target exists but is not managed by OMT");
+      }
+      try {
+        assertSafeManagedState(agent, recorded, options.omtHome, platform);
+      } catch {
+        return result(agent, "conflict", "recorded state is unsafe; run `omt integrate repair`");
+      }
+      if (!pathPresent(agent.target) || !safeRealpath(agent.target)) {
+        return result(agent, "broken", "link is missing; run `omt integrate repair`");
+      }
+      if (!isManagedLink(agent.target, recorded.canonical)) {
+        return result(agent, "conflict", "target was replaced by unmanaged content");
+      }
+      if (recorded.version === options.skillVersion) {
+        return result(agent, "current");
+      }
+      return result(agent, "update-available", `new version ${options.skillVersion} available; run \`omt integrate\``);
+    });
+  }
+
+  async function repair(ids?: AgentId[]): Promise<IntegrationResult[]> {
+    const state = loadState();
+    const records = state.skills["oh-my-tool"]?.agents ?? {};
+    for (const agent of await selected(ids)) {
+      const recorded = records[agent.id];
+      if (recorded) assertSafeManagedState(agent, recorded, options.omtHome, platform);
+      if (pathPresent(agent.target) && (!recorded || !isManagedLink(agent.target, recorded.canonical))) {
+        throw new IntegrationConflictError(agent.target);
+      }
+    }
+    const installed = await install(ids);
+    return installed.map((item) => ({ ...item, status: item.status === "installed" ? "repaired" : item.status }));
+  }
+
+  async function uninstall(ids?: AgentId[]): Promise<IntegrationResult[]> {
+    const agents = await selected(ids);
+    const state = loadState();
+    const skillState = state.skills["oh-my-tool"];
+    const results: IntegrationResult[] = [];
+    for (const agent of agents) {
+      const recorded = skillState?.agents[agent.id];
+      if (!recorded) {
+        results.push(result(agent, "not-installed"));
+        continue;
+      }
+      assertSafeManagedState(agent, recorded, options.omtHome, platform);
+      const remaining = Object.entries(skillState!.agents).filter(
+        ([id, other]) => id !== agent.id && other && samePath(other.target, agent.target, platform),
+      );
+      if (remaining.length) {
+        if (recorded.backup) remaining[0][1]!.backup = recorded.backup;
+      } else {
+        if (pathPresent(agent.target)) {
+          if (!isManagedLink(agent.target, recorded.canonical)) {
+            throw new IntegrationConflictError(agent.target);
+          }
+          unlinkOnly(agent.target);
+        }
+        if (recorded.backup && existsSync(recorded.backup)) renameSync(recorded.backup, agent.target);
+      }
+      delete skillState!.agents[agent.id];
+      results.push(result(agent, "uninstalled"));
+    }
+    saveState(state);
+    return results;
+  }
+
+  return { detect: detections, install, status, repair, uninstall };
+
+  function managedState(target: string, canonical: string, digest: string): ManagedAgentState {
+    return {
+      target,
+      canonical,
+      version: options.skillVersion,
+      digest,
+      mode: platform === "win32" ? "junction" : "symlink",
+    };
+  }
+}
+
+function result(
+  agent: AgentDetection,
+  status: IntegrationResult["status"],
+  detail?: string,
+): IntegrationResult {
+  return {
+    agent: agent.id,
+    displayName: agent.variant ?? agent.displayName,
+    target: agent.target,
+    status,
+    detail,
+  };
+}
+
+function timestamp(date: Date): string {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}

package/src/integration/skill.ts

@@ -0,0 +1,84 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface SkillMetadata {
+  name: string;
+  description: string;
+}
+
+export function bundledSkillPath(): string {
+  return fileURLToPath(new URL("../../assets/skills/oh-my-tool", import.meta.url));
+}
+
+export function validateSkill(directory: string): SkillMetadata {
+  const skillFile = join(directory, "SKILL.md");
+  if (!existsSync(skillFile)) throw new Error(`Skill is missing SKILL.md: ${directory}`);
+  const content = readFileSync(skillFile, "utf8");
+  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter) throw new Error("Skill SKILL.md is missing YAML frontmatter");
+  const name = frontmatter[1].match(/^name:\s*(.+?)\s*$/m)?.[1];
+  const description = frontmatter[1].match(/^description:\s*(.+?)\s*$/m)?.[1];
+  if (!name || !description) throw new Error("Skill frontmatter requires name and description");
+  if (name !== "oh-my-tool") throw new Error(`Unexpected bundled skill name: ${name}`);
+  return { name, description };
+}
+
+function filesUnder(directory: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...filesUnder(path));
+    else if (entry.isFile()) files.push(path);
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+export function skillDigest(directory: string): string {
+  const hash = createHash("sha256");
+  for (const file of filesUnder(directory)) {
+    hash.update(relative(directory, file).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(readFileSync(file));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function stageCanonicalSkill(
+  omtHome: string,
+  source: string,
+  version: string,
+): { path: string; digest: string } {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid skill version: ${version}`);
+  }
+  validateSkill(source);
+  const digest = skillDigest(source);
+  const canonicalRoot = resolve(omtHome, "integrations", "skills", "oh-my-tool");
+  const target = resolve(canonicalRoot, version);
+  if (dirname(target) !== canonicalRoot) throw new Error(`Invalid skill version path: ${version}`);
+  if (existsSync(target)) {
+    validateSkill(target);
+    if (skillDigest(target) !== digest) {
+      throw new Error(`Immutable skill version ${version} already exists with different content`);
+    }
+    return { path: target, digest };
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  const staging = `${target}.tmp-${process.pid}-${Date.now()}`;
+  if (existsSync(staging)) throw new Error(`Skill staging path already exists: ${staging}`);
+  cpSync(source, staging, { recursive: true, errorOnExist: true });
+  validateSkill(staging);
+  if (statSync(staging).isDirectory()) renameSync(staging, target);
+  return { path: target, digest };
+}