@yep-ai/cli 0.0.0-stage → 1.0.1

package/bin/market.js

@@ -0,0 +1,1621 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { installClientDefinitions, normalizeClients, promptClients, resolveClients } from "./clients.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = resolve(__dirname, "../../..");
+const registryPath = join(rootDir, "registry", "skills.json");
+const defaultInstallDir = join(process.cwd(), ".yep", "skills");
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const defaultRemoteRegistry = "https://yep.nihao.cool";
+let isMarketplace = true;
+const cliName = "yep";
+const configHome = process.env.YEP_CONFIG_DIR ? resolve(process.env.YEP_CONFIG_DIR) : resolve(process.env.YEP_HOME || homedir(), ".config", "yep");
+const configPath = join(configHome, "config.json");
+const maxPackageFiles = 250;
+const maxPackageFileBytes = 8 * 1024 * 1024;
+const maxExpandedPackageBytes = 50 * 1024 * 1024;
+const maxPackagePathBytes = 512;
+const maxPackageSegmentBytes = 255;
+const skillVersionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+const commands = {
+  list,
+  search,
+  install,
+  uninstall,
+  client,
+  publish,
+  submit,
+  withdraw,
+  history,
+  diff,
+  info,
+  login,
+  logout,
+  whoami,
+  sync,
+  help
+};
+
+export async function runMarketplace(argv = process.argv.slice(2)) {
+  const { command, args, options } = parseArgs(argv);
+  isMarketplace = !options.local;
+  options.registry ??=
+    process.env.YEP_REGISTRY_URL ??
+    (isMarketplace ? readConfig().defaultRegistry : undefined);
+  options.token ??= process.env.YEP_TOKEN;
+  if (!options.to && options.kind === "skill") options.client ??= process.env.YEP_CLIENT?.trim() || undefined;
+  if (typeof options.token === "string") options.token = options.token.trim() || undefined;
+
+  if (isMarketplace && !options.registry) options.registry = defaultRemoteRegistry;
+  if (options.registry) options.registry = normalizeRegistry(options.registry);
+  if (options.registry && !options.token) options.token = storedAuth(options.registry)?.token;
+
+  if (command === "--version" || command === "-v") {
+    console.log(version);
+    return;
+  }
+
+  const runner = options.kind === "skill" && ["submit", "withdraw"].includes(command) ? undefined : commands[command ?? "help"];
+  if (!runner) {
+    fail(`Unknown command "${command}". Run "${cliName} help".`);
+  }
+
+  await runner(args, options);
+}
+
+async function list(args, options) {
+  if (options.kind !== "skill") return listResources(args, options);
+  if (options.mine) {
+    const registry = options.registry ?? defaultRemoteRegistry;
+    const token = requireRegistryToken(options.token, registry, "list your private Skills");
+    const data = await apiFetch(registry, "/api/me/skills", undefined, token);
+    const query = args.join(" ").toLowerCase();
+    printSkills((data?.skills ?? []).filter((skill) => [skill.name, skill.displayName, skill.summary].join(" ").toLowerCase().includes(query)), options);
+    return;
+  }
+  if (!options.remote && (isMarketplace || options.installed || options.client || options.to)) {
+    listInstalled(args, options);
+    return;
+  }
+  await listMarketplace(args, options.remote ? { ...options, registry: options.registry ?? defaultRemoteRegistry } : options);
+}
+
+async function listMarketplace(args, options) {
+  if (options.kind !== "skill") return listResources(args, { ...options, remote: true });
+  const query = args.join(" ");
+  const skills = options.registry ? (await apiList(options.registry, query, options.token, options.limit)).skills : localList(query);
+  printSkills(skills, options);
+}
+
+function printSkills(skills, options) {
+  const limited = Number.isInteger(options.limit) ? skills.slice(0, options.limit) : skills;
+
+  if (options.json) {
+    console.log(JSON.stringify(limited, null, 2));
+    return;
+  }
+
+  if (limited.length === 0) {
+    console.log("No skills found.");
+    return;
+  }
+
+  for (const skill of limited) {
+    const verified = skill.verified ? " verified" : "";
+    console.log(`${skill.name}@${skill.version}${verified}`);
+    console.log(`  ${skill.summary}`);
+    if (options.mine) console.log(`  ${skill.visibility} / ${skill.status}`);
+  }
+}
+
+async function search(args, options) {
+  if (args.length === 0) fail(`Usage: ${cliName} search <query> [--limit <n>]`);
+  await listMarketplace(args, { ...options, registry: options.registry ?? defaultRemoteRegistry });
+}
+
+async function info(args, options) {
+  if (options.kind !== "skill") return resourceInfo(args, options);
+  const { name, version: requestedVersion } = parseSkillSpec(requiredArg(args[0], `Usage: ${cliName} info <skill-name>`));
+  const skill = options.registry ? await apiInfoWithOwnerFallback(options.registry, name, options.token, requestedVersion) : findSkill(name);
+  assertRequestedVersion(requestedVersion, skill);
+  console.log(JSON.stringify(skill, null, 2));
+}
+
+async function install(args, options) {
+  if (options.kind !== "skill") return installResources(args, options);
+  if (args.length === 0) fail(`Usage: ${cliName} install <skill-name> [more-skills...] [--client <client>]`);
+  const specs = args.map(parseSkillSpec);
+  await selectOperationClients(options);
+  // Validate every destination before downloading or changing any package.
+  const destinations = new Map();
+  for (const { name } of specs) {
+    for (const target of resolveInstallTargets(name, options)) {
+      if (destinations.has(target.path) && destinations.get(target.path) !== name) throw new Error(`Package names share the same destination: ${destinations.get(target.path)} and ${name}`);
+      destinations.set(target.path, name);
+      assertInstallDestination(target, name);
+    }
+  }
+  for (const { name, version: requestedVersion } of specs) {
+    await installOne(name, requestedVersion, options);
+  }
+}
+
+async function installOne(name, requestedVersion, options) {
+  if (options.registry) {
+    const pkg = await apiPackageWithOwnerFallback(options.registry, name, options.token, requestedVersion);
+    assertRequestedVersion(requestedVersion, pkg?.skill);
+    const installTargets = resolveInstallTargets(name, options);
+    const validated = validateRemotePackage(pkg, dirname(installTargets[0].path), name, installTargets[0].path);
+    for (const target of installTargets) {
+      installRemotePackage(target.path, validated.files, validated.skill, options.registry, target.client);
+    }
+    const { skill } = validated;
+    console.log(`Fetched ${skill.displayName} v${skill.version}`);
+    for (const target of installTargets) console.log(`Installed to ${target.path} (${target.label})`);
+    console.log(skill.verified ? "Verified registry manifest" : "Installed community package");
+    if (shouldRecordDownload(skill)) await recordDownload(options.registry, name, options.token, "installed successfully");
+    return;
+  }
+
+  const skill = findSkill(name);
+  assertRequestedVersion(requestedVersion, skill);
+  const source = resolve(rootDir, skill.source);
+  const targets = resolveInstallTargets(name, options);
+
+  if (!existsSync(source)) {
+    fail(`Package source missing for ${skill.name}: ${source}`);
+  }
+
+  for (const target of targets) installLocalPackage(target.path, source, skill, target.client);
+
+  console.log(`Fetched ${skill.displayName} v${skill.version}`);
+  for (const target of targets) console.log(`Installed to ${target.path} (${target.label})`);
+  console.log(skill.verified ? "Verified registry manifest" : "Installed community package");
+}
+
+async function publish(args, options) {
+  if (options.kind !== "skill") return publishResource(args, options);
+  const packageDir = resolve(args[0] || ".");
+  const manifest = readLocalManifest(packageDir);
+  const registry = normalizeRegistry(options.registry ?? defaultRemoteRegistry);
+  if (!options.token && process.stdin.isTTY && process.stdout.isTTY) {
+    console.log(`Sign in to ${registry} to publish this Skill.`);
+    await login([], { ...options, registry });
+    options.token = storedAuth(registry)?.token;
+  }
+  const token = requireRegistryToken(options.token ?? storedAuth(registry)?.token, registry, "publish Skills");
+  const packageFiles = collectPackageFiles(packageDir);
+  let ownedSkill = await apiFindOwnedSkillIfSupported(registry, manifest.name, token);
+  if (ownedSkill?.version === manifest.version) {
+    throw new Error(`Version ${manifest.name}@${manifest.version} already exists. Bump the version before publishing another package.`);
+  }
+
+  let response;
+  try {
+    response = await apiUploadFiles(registry, manifest, packageFiles, token, ownedSkill?.id);
+  } catch (error) {
+    if (!(error instanceof RegistryError) || error.status !== 409 || ownedSkill) throw error;
+    ownedSkill = await apiFindOwnedSkill(registry, manifest.name, token);
+    if (!ownedSkill) throw error;
+    if (ownedSkill.version === manifest.version) {
+      throw new Error(`Version ${manifest.name}@${manifest.version} already exists. Bump the version before publishing another package.`);
+    }
+    response = await apiUploadFiles(registry, manifest, packageFiles, token, ownedSkill.id);
+  }
+
+  console.log(`Published ${response.name}@${response.version}`);
+  console.log("Status: private, no review submitted");
+  console.log(`Registry: ${trimSlash(registry)}`);
+  console.log(`Next: ${cliName} list --mine; ${cliName} install ${response.name}`);
+}
+
+function resourceRegistry(options) {
+  return normalizeRegistry(options.registry ?? defaultRemoteRegistry);
+}
+
+function resourceRoot(options) {
+  return { client: "project", label: `${options.kind} directory`, root: resolve(options.to ?? `${options.kind}s`), legacy: false, kind: options.kind };
+}
+
+async function apiResourceList(registry, kind, token, owned, name) {
+  const params = new URLSearchParams({ kind });
+  if (name) params.set("name", name);
+  const data = await apiFetch(registry, `${owned ? "/api/me/resources" : "/api/resources"}?${params}`, undefined, token);
+  if (!Array.isArray(data?.resources)) throw new Error("Registry returned an invalid resource list");
+  return data.resources.filter((resource) => resource?.kind === kind && (!name || resource.name === name));
+}
+
+async function findResource(registry, options, name, owned) {
+  const token = owned ? requireRegistryToken(options.token, registry, "read your private resources") : options.token;
+  const resources = await apiResourceList(registry, options.kind, token, owned, name);
+  if (resources.length > 1) throw new Error(`Registry returned duplicate ${options.kind} resources named ${name}`);
+  const resource = resources[0];
+  if (resource && (typeof resource.id !== "string" || !resource.id)) throw new Error("Registry returned a resource without its identity");
+  return resource;
+}
+
+async function listResources(args, options) {
+  if (!options.mine && !options.remote) return listInstalledResources(args, options);
+  const registry = resourceRegistry(options);
+  const token = options.mine ? requireRegistryToken(options.token, registry, "list your private resources") : options.token;
+  const query = args.join(" ").toLowerCase();
+  const resources = (await apiResourceList(registry, options.kind, token, options.mine)).filter((item) => [item.name, item.displayName, item.summary].join(" ").toLowerCase().includes(query));
+  if (!resources.length && !options.json) console.log(`No ${options.kind}s found.`);
+  else printSkills(resources, options);
+}
+
+function listInstalledResources(args, options) {
+  const root = resourceRoot(options);
+  const query = args.join(" ").toLowerCase();
+  const installed = [];
+  if (existsSync(root.root)) {
+    for (const entry of readdirSync(root.root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      try {
+        const path = join(root.root, entry.name);
+        const metadata = installedMetadata({ ...root, path });
+        if (metadata?.kind === options.kind && metadata.name.toLowerCase().includes(query)) installed.push({ ...metadata, path });
+      } catch (error) { console.warn(`Warning: ${error.message}`); }
+    }
+  }
+  installed.sort((a, b) => a.name.localeCompare(b.name));
+  const result = options.limit ? installed.slice(0, options.limit) : installed;
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else if (!result.length) console.log(`No installed ${options.kind}s found.`);
+  else for (const item of result) console.log(`${item.name}@${item.version}\n  ${item.path}`);
+}
+
+async function resourceInfo(args, options) {
+  const spec = parseSkillSpec(requiredArg(args[0], `Usage: ${cliName} info <name> --kind ${options.kind}`));
+  const registry = resourceRegistry(options);
+  let resource = await findResource(registry, options, spec.name, false);
+  if ((!resource || (spec.version && resource.version !== spec.version)) && options.token) resource = await findResource(registry, options, spec.name, true) ?? resource;
+  if (!resource) throw new Error(`${options.kind} not found: ${spec.name}`);
+  assertRequestedVersion(spec.version, resource);
+  console.log(JSON.stringify(resource, null, 2));
+}
+
+function readResourceManifest(packageDir, kind) {
+  const manifestPath = join(packageDir, "cpm.json");
+  if (!lstatSync(manifestPath).isFile()) throw new Error(`Manifest must be a regular file: ${manifestPath}`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  for (const field of ["name", "displayName", "version"]) if (typeof manifest[field] !== "string" || !manifest[field].trim()) throw new Error(`Manifest missing field: ${field}`);
+  if (manifest.kind && manifest.kind !== kind) throw new Error(`Manifest kind ${manifest.kind} does not match --kind ${kind}`);
+  safeInstallRelativePath(manifest.name);
+  if (!skillVersionPattern.test(manifest.version)) throw new Error(`Invalid resource version: ${manifest.version}`);
+  const entry = manifest.entry ?? (kind === "agent" ? "AGENT.md" : "plugin.json");
+  safePackageOutput(packageDir, entry);
+  resolveLocalSkillEntry(packageDir, entry);
+  return { kind, name: manifest.name, displayName: manifest.displayName, version: manifest.version, summary: manifest.summary ?? "", entry };
+}
+
+async function publishResource(args, options) {
+  const packageDir = resolve(args[0] ?? ".");
+  const manifest = readResourceManifest(packageDir, options.kind);
+  const registry = resourceRegistry(options);
+  if (!options.token && process.stdin.isTTY && process.stdout.isTTY) {
+    await login([], { ...options, registry });
+    options.token = storedAuth(registry)?.token;
+  }
+  const token = requireRegistryToken(options.token, registry, "publish resources");
+  const files = Object.entries(collectPackageFiles(packageDir)).map(([path, content]) => ({ path, contentBase64: Buffer.from(content).toString("base64") }));
+  if (!files.some((file) => file.path === manifest.entry)) throw new Error(`Package entry is excluded from publication: ${manifest.entry}`);
+  const existing = await findResource(registry, { ...options, token }, manifest.name, true);
+  if (existing?.status === "pending") throw new Error(`This resource is awaiting review; run "${cliName} withdraw ${manifest.name} --kind ${options.kind}" before editing it`);
+  const body = JSON.stringify({ ...manifest, files, ...(existing ? { expectedRevisionId: existing.currentRevisionId } : {}) });
+  const data = await apiFetch(registry, existing ? `/api/me/resources/${encodeURIComponent(existing.id)}` : "/api/me/resources", { method: existing ? "PUT" : "POST", headers: { "Content-Type": "application/json" }, body, signal: AbortSignal.timeout(120_000) }, token);
+  const resource = data?.resource;
+  if (!resource?.id || resource.name !== manifest.name || resource.kind !== options.kind || !resource.currentRevisionId) throw new Error("Registry returned a saved resource with an unexpected identity");
+  let submitted;
+  try {
+    submitted = (await apiFetch(registry, `/api/me/resources/${encodeURIComponent(resource.id)}/submit`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ expectedRevisionId: resource.currentRevisionId }) }, token))?.resource;
+  } catch (error) {
+    throw new Error(`Saved ${resource.name}@${resource.version} (revision ${resource.currentRevisionId}), but review submission failed: ${error.message}`);
+  }
+  if (options.json) console.log(JSON.stringify(submitted ?? resource, null, 2));
+  else {
+    console.log(`Saved ${resource.name}@${resource.version}`);
+    console.log("Submitted for review; it becomes public after administrator approval.");
+    console.log(`Next: ${cliName} history ${resource.name} --kind ${options.kind}; ${cliName} install ${resource.name} --kind ${options.kind}`);
+  }
+}
+
+async function transitionResource(args, options, action) {
+  if (options.kind === "skill") throw new Error(`${action} requires --kind agent or --kind plugin; Skill review remains available in the marketplace`);
+  const spec = parseSkillSpec(requiredArg(args[0], `Usage: ${cliName} ${action} <name> --kind <agent|plugin>`));
+  const registry = resourceRegistry(options);
+  const token = requireRegistryToken(options.token, registry, "change resource publication");
+  const resource = await findResource(registry, options, spec.name, true);
+  if (!resource) throw new Error(`Owned ${options.kind} not found: ${spec.name}`);
+  assertRequestedVersion(spec.version, resource);
+  const withdrawing = action === "withdraw";
+  const response = await apiFetch(registry, `/api/me/resources/${encodeURIComponent(resource.id)}/${withdrawing ? "visibility" : "submit"}`, {
+    method: withdrawing ? "PUT" : "POST", headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(withdrawing ? { visibility: "private" } : { expectedRevisionId: resource.currentRevisionId })
+  }, token);
+  if (options.json) console.log(JSON.stringify(response?.resource, null, 2));
+  else console.log(withdrawing ? `Withdrew ${spec.name}; it is private and can be edited.` : `Submitted ${spec.name} for review.`);
+}
+
+async function submit(args, options) { return transitionResource(args, options, "submit"); }
+async function withdraw(args, options) { return transitionResource(args, options, "withdraw"); }
+
+async function resourcePackage(registry, spec, options) {
+  let resource;
+  let owned = false;
+  if (options.revision) {
+    resource = await findResource(registry, options, spec.name, true);
+    owned = true;
+  } else {
+    resource = await findResource(registry, options, spec.name, false);
+    if ((!resource || (spec.version && resource.version !== spec.version)) && options.token) {
+      const privateResource = await findResource(registry, options, spec.name, true);
+      if (privateResource) { resource = privateResource; owned = true; }
+    }
+  }
+  if (!resource) throw new Error(`${options.kind} not found: ${spec.name}`);
+  const path = options.revision
+    ? `/api/me/resources/${encodeURIComponent(resource.id)}/revisions/${encodeURIComponent(options.revision)}/package`
+    : `${owned ? "/api/me/resources" : "/api/resources"}/${encodeURIComponent(resource.id)}/package`;
+  const pkg = await apiFetch(registry, path, { signal: AbortSignal.timeout(120_000) }, options.token);
+  if (pkg?.resource?.id !== resource.id || pkg.resource.name !== spec.name || pkg.resource.kind !== options.kind) throw new Error("Registry returned a package with an unexpected resource identity");
+  if (options.revision) {
+    const revision = pkg.revision;
+    if (!revision || revision.id !== options.revision || revision.resourceId !== resource.id) throw new Error("Registry returned an unexpected revision");
+    pkg.resource = { ...pkg.resource, version: revision.version, displayName: revision.displayName, summary: revision.summary, entry: revision.entry, currentRevisionId: revision.id, content: revision.content };
+  }
+  assertRequestedVersion(spec.version, pkg.resource);
+  return pkg;
+}
+
+async function installResources(args, options) {
+  if (!args.length) throw new Error(`Usage: ${cliName} install <name> --kind ${options.kind} [--target <dir>]`);
+  const specs = args.map(parseSkillSpec);
+  const root = resourceRoot(options);
+  const destinations = new Map();
+  for (const spec of specs) {
+    const target = installationTarget(root, spec.name);
+    if (destinations.has(target.path) && destinations.get(target.path) !== spec.name) throw new Error("Resource names share the same destination");
+    destinations.set(target.path, spec.name);
+    assertInstallDestination(target, spec.name);
+  }
+  const registry = resourceRegistry(options);
+  for (const spec of specs) {
+    const target = installationTarget(root, spec.name);
+    const pkg = await resourcePackage(registry, spec, options);
+    const validated = validateRemotePackage({ skill: pkg.resource, files: pkg.files }, root.root, spec.name, target.path, false);
+    installRemotePackage(target.path, validated.files, validated.skill, registry, "project");
+    console.log(`Installed ${spec.name}@${pkg.resource.version} to ${target.path}`);
+  }
+}
+
+async function uninstallResources(args, options) {
+  if (!args.length) throw new Error(`Usage: ${cliName} uninstall <name> --kind ${options.kind} [--target <dir>]`);
+  const root = resourceRoot(options);
+  const plan = new Map();
+  for (const spec of args.map(parseSkillSpec)) {
+    const target = installationTarget(root, spec.name);
+    const metadata = installedMetadata(target);
+    if (!metadata) {
+      if (pathStats(target.path)) throw new Error(`Refusing to remove a directory without installation metadata: ${target.path}`);
+      plan.set(target.path, { name: spec.name, path: target.path, status: "not-installed" });
+    } else {
+      if (metadata.name !== spec.name || metadata.kind !== options.kind) throw new Error(`Destination belongs to a different resource: ${target.path}`);
+      assertRequestedVersion(spec.version, metadata);
+      plan.set(target.path, { name: spec.name, version: metadata.version, path: target.path, status: "removed" });
+    }
+  }
+  for (const item of plan.values()) {
+    if (item.status === "removed") rmSync(item.path, { recursive: true });
+    if (!options.json) console.log(`${item.status === "removed" ? "Uninstalled" : "Not installed"}: ${item.name}`);
+  }
+  if (options.json) console.log(JSON.stringify([...plan.values()], null, 2));
+}
+
+async function ownedRevisionPath(args, options) {
+  const spec = parseSkillSpec(requiredArg(args[0], `Usage: ${cliName} history|diff <name> [--kind <kind>]`));
+  const registry = resourceRegistry(options);
+  const token = requireRegistryToken(options.token, registry, "read your revision history");
+  const resource = options.kind === "skill" ? await apiFindOwnedSkill(registry, spec.name, token) : await findResource(registry, options, spec.name, true);
+  if (!resource) throw new Error(`Owned ${options.kind} not found: ${spec.name}`);
+  assertRequestedVersion(spec.version, resource);
+  return { registry, token, path: `/api/me/${options.kind === "skill" ? "skills" : "resources"}/${encodeURIComponent(resource.id)}` };
+}
+
+async function history(args, options) {
+  const { registry, token, path } = await ownedRevisionPath(args, options);
+  const data = await apiFetch(registry, `${path}/revisions`, undefined, token);
+  if (!Array.isArray(data?.revisions)) throw new Error("Registry returned an invalid revision history");
+  const revisions = options.limit ? data.revisions.slice(0, options.limit) : data.revisions;
+  if (options.json) console.log(JSON.stringify(revisions, null, 2));
+  else if (!revisions.length) console.log("No saved Git revisions yet.");
+  else for (const revision of revisions) console.log(`${revision.id}  ${revision.version}  ${revision.createdAt}`);
+}
+
+async function diff(args, options) {
+  const { registry, token, path } = await ownedRevisionPath(args, options);
+  const params = new URLSearchParams({ base: options.base ?? "published", target: options.revision ?? "current" });
+  const data = await apiFetch(registry, `${path}/diff?${params}`, { signal: AbortSignal.timeout(120_000) }, token);
+  const result = options.kind === "skill" ? data?.diff : data;
+  if (!Array.isArray(result?.changes)) throw new Error("Registry returned an invalid diff");
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else if (!result.changes.length) console.log("No content changes.");
+  else for (const change of result.changes) {
+    console.log(`${change.status} ${change.path}${change.binary ? " (binary)" : ""}`);
+    if (change.patch) console.log(change.patch);
+    if (change.truncated) console.log("Diff output truncated by the server.");
+  }
+}
+
+async function sync(_args, options) {
+  if (options.registry) {
+    const data = await apiList(options.registry, "", options.token);
+    console.log(`Synced ${data.skills.length} skills from ${trimSlash(options.registry)}`);
+    return;
+  }
+  const registry = readRegistry();
+  registry.generatedAt = new Date().toISOString();
+  writeRegistry(registry);
+  console.log(`Synced ${registry.skills.length} skills`);
+}
+
+async function login(_args, options) {
+  const registry = trimSlash(options.registry ?? defaultRemoteRegistry);
+  const configuredUsername = options.username ?? process.env.YEP_USERNAME;
+  const configuredPassword = options.password ?? process.env.YEP_PASSWORD;
+  if (configuredUsername !== undefined || configuredPassword !== undefined) {
+    await passwordLogin(registry, configuredUsername, configuredPassword);
+    return;
+  }
+
+  const request = await apiFetch(registry, "/api/auth/cli-login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ client: cliName })
+  });
+  if (
+    typeof request?.requestId !== "string" ||
+    typeof request?.pollToken !== "string" ||
+    typeof request?.verificationUri !== "string" ||
+    !Number.isFinite(request?.expiresIn) ||
+    !Number.isFinite(request?.interval)
+  ) {
+    throw new Error("Registry returned an invalid browser login response");
+  }
+  const registryURL = new URL(`${registry}/`);
+  const verificationURL = new URL(request.verificationUri, registryURL);
+  if (verificationURL.origin !== registryURL.origin) {
+    throw new Error("Registry returned a browser login URL on a different origin");
+  }
+
+  console.log("Authenticate your account at:");
+  console.log(verificationURL.toString());
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    await waitForEnter("Press ENTER to open in the browser...");
+    try {
+      await openBrowser(verificationURL.toString());
+    } catch (error) {
+      console.warn(`Could not open the browser automatically: ${error.message}`);
+    }
+  } else {
+    console.log("Open this URL in your browser to continue.");
+  }
+  console.log("Waiting for browser authorization...");
+
+  const expiresAt = Date.now() + Math.max(1, Math.min(Number(request.expiresIn), 15 * 60)) * 1000;
+  const interval = Math.max(250, Math.min(Number(request.interval) * 1000, 10_000));
+  while (Date.now() < expiresAt) {
+    const auth = await apiFetch(registry, `/api/auth/cli-login/${encodeURIComponent(request.requestId)}/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ pollToken: request.pollToken })
+    });
+    if (auth?.status === "pending") {
+      await delay(interval);
+      continue;
+    }
+    if (!auth?.token || !auth?.user) throw new Error("Registry returned an invalid CLI session");
+    saveStoredAuth(registry, {
+      token: auth.token,
+      user: auth.user,
+      savedAt: new Date().toISOString()
+    });
+    console.log(`Signed in to ${registry} as ${auth.user.username ?? auth.user.email ?? "user"}.`);
+    return;
+  }
+  throw new Error("Browser login expired before it was confirmed");
+}
+
+async function passwordLogin(registry, configuredUsername, configuredPassword) {
+  const username = configuredUsername ?? (await promptText("Username or email: "));
+  const password = configuredPassword ?? (await promptSecret("Password: "));
+  if (!String(username).trim() || !password) fail("Username and password are required");
+  const auth = await apiFetch(registry, "/api/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ identity: String(username).trim(), password: String(password) })
+  });
+  if (!auth?.token || !auth?.user) throw new Error("Registry returned an invalid login response");
+  saveStoredAuth(registry, {
+    token: auth.token,
+    user: auth.user,
+    savedAt: new Date().toISOString()
+  });
+  console.log(`Signed in to ${registry} as ${auth.user.username ?? auth.user.email ?? "user"}.`);
+}
+
+async function logout(_args, options) {
+  const registry = trimSlash(options.registry ?? defaultRemoteRegistry);
+  const auth = storedAuth(registry);
+  if (auth?.token) {
+    try {
+      await apiFetch(registry, "/api/auth/logout", { method: "POST" }, auth.token);
+    } catch (error) {
+      if (!(error instanceof RegistryError) || error.status !== 401) throw error;
+    }
+  }
+  deleteStoredAuth(registry);
+  console.log(`Signed out from ${registry}.`);
+}
+
+async function whoami(_args, options) {
+  const registry = trimSlash(options.registry ?? defaultRemoteRegistry);
+  const token = options.token ?? storedAuth(registry)?.token;
+  if (!token) fail(`Not signed in. Run "${cliName} login --registry ${registry}".`);
+  const response = await apiFetch(registry, "/api/auth/me", undefined, token);
+  console.log(options.json ? JSON.stringify(response.user, null, 2) : `${response.user.username} (${response.user.email})`);
+}
+
+function help() {
+  console.log(`${cliName} ${version}
+
+Usage:
+  ${cliName} login                                   Sign in and save a registry token
+  ${cliName} logout                                  Revoke the current saved login
+  ${cliName} whoami                                  Show the signed-in account
+  ${cliName} search <query>                          Search marketplace skills
+  ${cliName} info <skill-name>                       Print skill metadata
+  ${cliName} client [list|set <clients>|reset]        Show, pin or clear default clients
+  ${cliName} install <skill> [more-skills...]        Fetch and install skills
+  ${cliName} list [query]                            List installed skills (offline)
+  ${cliName} list --remote | --mine                  List marketplace or your workspace
+  ${cliName} uninstall <skill> [more-skills...]      Remove skills from selected clients
+  ${cliName} publish [package-dir]                   Save Skill privately; submit Agent/Plugin for review
+  ${cliName} submit <name> --kind agent|plugin        Submit a saved resource for review
+  ${cliName} withdraw <name> --kind agent|plugin      Make a resource private and cancel pending review
+  ${cliName} history <name>                           List your saved Git revisions
+  ${cliName} diff <name>                              Compare your draft with the published revision
+
+Options:
+  --kind <skill|agent|plugin>                         Resource type (default: skill)
+  --base <published|empty|revision-id>                 Diff base (default: published)
+  --revision <revision-id>                            Diff target or Agent/Plugin install revision
+  --registry <url>                                   Yep Marketplace API URL
+  --token <token>                                    Use a token without saving it
+  --client <clients>                                 codex, claude, qoder, kiro, vscode, universal, project, auto, all
+  --to, --target <dir>                               Custom install destination
+  --limit <n>                                        Limit search results
+  --json                                             Print machine-readable output
+  --installed | --remote | --mine                    Select the list source
+  --local                                             Use the checkout local registry
+
+Device node:
+  yep device start [directories...] [--server <url>]  Connect this device
+  yep device login | status | logout                  Manage device authorization
+  yep device --help                                   Device command details
+
+Client selection:
+  --client > YEP_CLIENT > pinned clients > interactive selection.
+  In scripts, specify --client or --target; --client auto opts into detection.
+  list scans all clients unless --client/--target is provided.
+
+Environment:
+  YEP_REGISTRY_URL                         Default registry URL
+  YEP_TOKEN                                Authentication token override
+  YEP_CLIENT                               Default install client(s), or auto
+  YEP_USERNAME / YEP_PASSWORD    Non-interactive login credentials
+
+  YEP_CONFIG_DIR                                     Config directory (default: ~/.config/yep)
+  YEP_HOME                                           Home override for isolated environments
+`);
+}
+
+function parseArgs(argv) {
+  const args = [];
+  const options = {};
+  let command;
+  const valueOptions = new Set([
+    "registry",
+    "token",
+    "to",
+    "target",
+    "client",
+    "limit",
+    "username",
+    "password",
+    "kind",
+    "base",
+    "revision"
+  ]);
+  const booleanOptions = new Set(["json", "installed", "remote", "mine", "local"]);
+  const removedClientOptions = new Set(["--tool", "--agent", "-a"]);
+  for (let index = 0; index < argv.length; index++) {
+    const item = argv[index];
+    if (removedClientOptions.has(item) || [...removedClientOptions].some((option) => item.startsWith(`${option}=`))) {
+      fail(`Option ${item.split("=")[0]} has been removed; use --client.`);
+    } else if (item === "-h") {
+      command = "help";
+    } else if (item === "-v") {
+      command = "--version";
+    } else if (item.startsWith("--")) {
+      const equalsIndex = item.indexOf("=");
+      const name = item.slice(2, equalsIndex >= 0 ? equalsIndex : undefined);
+      if (!valueOptions.has(name) && !booleanOptions.has(name) && name !== "help" && name !== "version") {
+        fail(`Unknown option: --${name}`);
+      }
+      if (booleanOptions.has(name)) {
+        if (equalsIndex >= 0) fail(`Option --${name} does not take a value`);
+        options[name] = true;
+        continue;
+      }
+      if (name === "help") {
+        command = "help";
+        continue;
+      }
+      if (name === "version") {
+        command = "--version";
+        continue;
+      }
+      const value = equalsIndex >= 0 ? item.slice(equalsIndex + 1) : argv[++index];
+      const aliases = { target: "to" };
+      options[aliases[name] ?? name] = requiredArg(value, `Missing value for --${name}`);
+    } else if (item.startsWith("-")) {
+      fail(`Unknown option: ${item}`);
+    } else if (!command) {
+      command = item;
+    } else {
+      args.push(item);
+    }
+  }
+  options.kind ??= "skill";
+  if (!["skill", "agent", "plugin"].includes(options.kind)) fail("--kind must be skill, agent or plugin");
+  if (options.kind !== "skill" && ["sync", "client"].includes(command)) fail("This command applies to Skill client directories; omit --kind");
+  if (options.kind !== "skill" && options.client) fail("Agent/plugin packages use --target or the local agents/plugins directory");
+  if (options.base && command !== "diff") fail("--base is only supported by diff");
+  if (options.revision && !["install", "diff"].includes(command)) fail("--revision is only supported by install and diff");
+  if (options.revision && options.kind === "skill" && command === "install") fail("Skill installation accepts an exact version; --revision is available for agent/plugin installs");
+  if (options.limit !== undefined) {
+    options.limit = Number(options.limit);
+    if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100) {
+      fail("--limit must be an integer from 1 to 100");
+    }
+  }
+  const sources = ["installed", "remote", "mine"].filter((key) => options[key]);
+  if (sources.length > 1) fail("Choose only one of --installed, --remote or --mine");
+  if (sources.length && command !== "list") fail("--installed, --remote and --mine are only supported by list");
+  if (options.to && options.client) fail("--to/--target cannot be combined with --client");
+  if ((options.remote || options.mine) && (options.to || options.client)) fail("Remote lists cannot be combined with --client or --target");
+  return { command, args, options };
+}
+
+function readConfig() {
+  if (!existsSync(configPath)) return { registries: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : { registries: {} };
+  } catch (error) {
+    throw new Error(`Cannot read ${configPath}: ${error.message}`);
+  }
+}
+
+function writeConfig(config) {
+  mkdirSync(configHome, { recursive: true, mode: 0o700 });
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(configPath, 0o600);
+}
+
+function registryConfigKey(registry) {
+  return trimSlash(registry).toLowerCase();
+}
+
+function storedAuth(registry) {
+  return readConfig().registries?.[registryConfigKey(registry)];
+}
+
+function saveStoredAuth(registry, auth) {
+  const config = readConfig();
+  config.registries = config.registries && typeof config.registries === "object" ? config.registries : {};
+  config.registries[registryConfigKey(registry)] = auth;
+  config.defaultRegistry = trimSlash(registry);
+  writeConfig(config);
+}
+
+function deleteStoredAuth(registry) {
+  const config = readConfig();
+  if (config.registries) delete config.registries[registryConfigKey(registry)];
+  writeConfig(config);
+}
+
+async function promptText(label) {
+  if (!process.stdin.isTTY) fail(`${label.trim()} is required in a non-interactive terminal`);
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await prompt.question(label);
+  } finally {
+    prompt.close();
+  }
+}
+
+async function promptSecret(label) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== "function") {
+    fail("Set YEP_PASSWORD or pass --password in a non-interactive terminal");
+  }
+  process.stdout.write(label);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  return new Promise((resolvePromise, rejectPromise) => {
+    let value = "";
+    const finish = (error) => {
+      process.stdin.off("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+      if (error) rejectPromise(error);
+      else resolvePromise(value);
+    };
+    const onData = (chunk) => {
+      for (const character of chunk.toString("utf8")) {
+        if (character === "\r" || character === "\n") {
+          finish();
+          return;
+        }
+        if (character === "\u0003") {
+          finish(new Error("Login cancelled"));
+          return;
+        }
+        if (character === "\u007f" || character === "\b") {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (character >= " ") {
+          value += character;
+          process.stdout.write("*");
+        }
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+async function waitForEnter(label) {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await prompt.question(`${label}\n`);
+  } finally {
+    prompt.close();
+  }
+}
+
+function openBrowser(target) {
+  const command = process.platform === "win32" ? "cmd.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+  const args = process.platform === "win32" ? ["/d", "/s", "/c", "start", "", target] : [target];
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.once("error", rejectPromise);
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
+  });
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+}
+
+function parseSkillSpec(spec) {
+  const value = String(spec).trim();
+  const separator = value.lastIndexOf("@");
+  const hasVersion = separator > value.indexOf("/");
+  const name = hasVersion ? value.slice(0, separator) : value;
+  const requestedVersion = hasVersion ? value.slice(separator + 1) : undefined;
+  safeInstallRelativePath(name);
+  if (hasVersion && !skillVersionPattern.test(requestedVersion)) {
+    throw new Error(`Invalid skill version: ${requestedVersion}`);
+  }
+  return { name, version: requestedVersion };
+}
+
+function assertRequestedVersion(requestedVersion, skill) {
+  if (!requestedVersion) return;
+  if (!skill || skill.version !== requestedVersion) {
+    throw new Error(`Version ${requestedVersion} is not available; registry returned ${skill?.version ?? "no version"}`);
+  }
+}
+
+function scopedSkillDirectory(name) {
+  const match = /^@([^/]+)\/(.+)$/.exec(name);
+  if (!match) throw new Error(`Unsafe package name: ${name}`);
+  return `${match[1]}--${match[2]}`;
+}
+
+async function selectOperationClients(options) {
+  if (options.to) return;
+  options.client ??= readConfig().defaultClients?.join(",");
+  if (!options.client && !isMarketplace && !options.registry) return;
+  if (!options.client) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || options.json) {
+      throw new Error(`No client selected. Pass --client <clients> or --target <dir>, or run "${cliName} client set <clients>". Use --client auto for automatic detection.`);
+    }
+    options.client = (await promptClients()).join(",");
+    console.log(`To pin this selection: ${cliName} client set ${options.client}`);
+  }
+  options.client = resolveClients(options.client).join(",");
+}
+
+async function client(args, options) {
+  const action = args[0] ?? "list";
+  if (action === "set") {
+    if (args.length > 2) throw new Error(`Usage: ${cliName} client set codex,claude`);
+    if (!args[1] && (!process.stdin.isTTY || !process.stdout.isTTY || options.json)) throw new Error(`Usage: ${cliName} client set codex,claude`);
+    const selected = args[1] ? normalizeClients(args[1]) : await promptClients();
+    const config = readConfig();
+    config.defaultClients = selected;
+    writeConfig(config);
+    console.log(`Default clients: ${selected.join(", ")}`);
+    return;
+  }
+  if (action === "reset") {
+    if (args.length !== 1) throw new Error(`Usage: ${cliName} client reset`);
+    const config = readConfig();
+    delete config.defaultClients;
+    writeConfig(config);
+    console.log("Default clients cleared. The next interactive install or uninstall will ask you to choose.");
+    return;
+  }
+  if (action !== "list" || args.length > 1) throw new Error(`Usage: ${cliName} client [list|set <clients>|reset]`);
+  const config = readConfig();
+  const pinned = config.defaultClients ?? [];
+  const effective = options.client || pinned.join(",");
+  const selected = effective ? resolveClients(effective) : [];
+  const clients = Object.entries(installClientDefinitions()).map(([id, definition]) => ({
+    id, label: definition.label, path: definition.root,
+    detected: definition.detect.some((path) => existsSync(path)),
+    selected: selected.includes(id)
+  }));
+  if (options.json) {
+    console.log(JSON.stringify({ defaultClients: pinned, environmentClients: process.env.YEP_CLIENT || null, clients }, null, 2));
+    return;
+  }
+  console.log(`Pinned clients: ${pinned.join(", ") || "none"}`);
+  for (const entry of clients) console.log(`${entry.selected ? "*" : " "} ${entry.id} — ${entry.label}${entry.detected ? " [detected]" : ""}\n    ${entry.path}`);
+  console.log(`Pin: ${cliName} client set codex,claude | Clear: ${cliName} client reset`);
+}
+
+function installRoots(options, all = false) {
+  if (options.to || (!options.client && !isMarketplace && !all)) {
+    return [{ client: isMarketplace ? "project" : "local", label: isMarketplace ? "Custom target" : "Local registry", root: resolve(options.to ?? defaultInstallDir), legacy: !isMarketplace }];
+  }
+  const definitions = installClientDefinitions();
+  const clients = resolveClients(options.client ?? "all", definitions);
+  const roots = clients.map((id) => ({ client: id, label: definitions[id].label, root: definitions[id].root, legacy: false }));
+  return roots.filter((root, index) => roots.findIndex((candidate) => candidate.root === root.root) === index);
+}
+
+function resolveInstallTargets(name, options) {
+  if (options.to && options.client) throw new Error("--to/--target cannot be combined with --client");
+  return installRoots(options).map((root) => installationTarget(root, name));
+}
+
+function installationTarget(root, name) {
+  safeInstallRelativePath(name);
+  return { ...root, path: join(root.root, root.legacy ? safeInstallRelativePath(name) : scopedSkillDirectory(name)) };
+}
+
+function pathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function assertManagedPath(target) {
+  const segments = relative(target.root, target.path).split(process.platform === "win32" ? "\\" : "/");
+  if (segments.some((part) => !part || part === "..") || isAbsolute(relative(target.root, target.path))) {
+    throw new Error(`Unsafe install path: ${target.path}`);
+  }
+  let current = target.root;
+  for (const segment of segments) {
+    current = join(current, segment);
+    const stats = pathStats(current);
+    if (stats && !stats.isDirectory()) throw new Error(`Install path must be a regular directory, not a symbolic link: ${current}`);
+  }
+}
+
+function installedMetadata(target) {
+  assertManagedPath(target);
+  const names = target.legacy ? ["yep-installed.json", "cpm-installed.json"] : [".yep.json", ".skills-center.json"];
+  const path = names.map(name => join(target.path, name)).find(path => pathStats(path)) ?? join(target.path, names[0]);
+  const stats = pathStats(path);
+  if (!stats) return undefined;
+  if (!stats.isFile()) throw new Error(`Installation metadata must be a regular file: ${path}`);
+  let metadata;
+  try {
+    metadata = JSON.parse(readFileSync(path, "utf8"));
+    safeInstallRelativePath(metadata?.name);
+    if (typeof metadata.version !== "string" || !skillVersionPattern.test(metadata.version)) throw new Error("invalid version");
+    if (installationTarget(target, metadata.name).path !== target.path) throw new Error("package name does not match its directory");
+  } catch (error) {
+    throw new Error(`Invalid installation metadata at ${path}: ${error.message}`);
+  }
+  return metadata;
+}
+
+function assertInstallDestination(target, name) {
+  const existing = installedMetadata(target);
+  if (existing && (existing.kind ?? "skill") !== (target.kind ?? "skill")) throw new Error(`Destination contains a different resource kind: ${target.path}`);
+  if (existing && existing.name !== name) throw new Error(`Destination belongs to ${existing.name}, not ${name}: ${target.path}`);
+}
+
+function listInstalled(args, options) {
+  const installations = [];
+  const query = args.join(" ").toLowerCase();
+  for (const root of installRoots(options, isMarketplace)) {
+    if (!existsSync(root.root)) continue;
+    const directories = readdirSync(root.root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith("."));
+    const paths = root.legacy
+      ? directories.flatMap((scope) => readdirSync(join(root.root, scope.name), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(root.root, scope.name, entry.name)))
+      : directories.map((entry) => join(root.root, entry.name));
+    for (const path of paths) {
+      try {
+        const metadata = installedMetadata({ ...root, path });
+        if (!metadata || (metadata.kind ?? "skill") !== "skill" || !metadata.name.toLowerCase().includes(query)) continue;
+        installations.push({ ...metadata, client: root.client, path });
+      } catch (error) {
+        console.warn(`Warning: ${error.message}`);
+      }
+    }
+  }
+  installations.sort((a, b) => a.name.localeCompare(b.name) || a.client.localeCompare(b.client));
+  const result = options.limit ? installations.slice(0, options.limit) : installations;
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else if (!result.length) console.log("No installed skills found.");
+  else for (const item of result) console.log(`${item.name}@${item.version} (${item.client})\n  ${item.path}`);
+}
+
+async function uninstall(args, options) {
+  if (options.kind !== "skill") return uninstallResources(args, options);
+  if (!args.length) throw new Error(`Usage: ${cliName} uninstall <skill> [more-skills...] [--client <clients>|--target <dir>]`);
+  const specs = args.map(parseSkillSpec);
+  await selectOperationClients(options);
+  const plan = new Map();
+  // Validate all requested installations before removing any of them.
+  for (const spec of specs) {
+    for (const target of resolveInstallTargets(spec.name, options)) {
+      const metadata = installedMetadata(target);
+      if (!metadata) {
+        if (pathStats(target.path)) throw new Error(`Refusing to remove a directory without installation metadata: ${target.path}`);
+        plan.set(target.path, { name: spec.name, client: target.client, path: target.path, status: "not-installed" });
+        continue;
+      }
+      if ((metadata.kind ?? "skill") !== "skill") throw new Error(`Destination contains a different resource kind: ${target.path}`);
+      if (metadata.name !== spec.name) throw new Error(`Destination belongs to ${metadata.name}, not ${spec.name}: ${target.path}`);
+      assertRequestedVersion(spec.version, metadata);
+      plan.set(target.path, { name: metadata.name, version: metadata.version, client: target.client, path: target.path, status: "removed" });
+    }
+  }
+  for (const item of plan.values()) {
+    if (item.status === "removed") rmSync(item.path, { recursive: true });
+    if (!options.json) console.log(item.status === "removed" ? `Uninstalled ${item.name}@${item.version} from ${item.path} (${item.client})` : `Not installed: ${item.name} (${item.client})`);
+  }
+  if (options.json) console.log(JSON.stringify([...plan.values()], null, 2));
+}
+
+function readRegistry() {
+  return JSON.parse(readFileSync(registryPath, "utf8"));
+}
+
+function writeRegistry(registry) {
+  writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+}
+
+function localList(query) {
+  const registry = readRegistry();
+  const normalized = query.trim().toLowerCase();
+  return registry.skills.filter((skill) => {
+    if (!normalized) return true;
+    return [skill.name, skill.displayName, skill.summary, skill.category, ...(skill.tags ?? [])]
+      .join(" ")
+      .toLowerCase()
+      .includes(normalized);
+  });
+}
+
+function findSkill(name) {
+  const registry = readRegistry();
+  const skill = registry.skills.find((item) => item.name === name);
+  if (!skill) fail(`Skill not found: ${name}`);
+  return skill;
+}
+
+function readLocalManifest(packageDir) {
+  const manifestPath = join(packageDir, "cpm.json");
+
+  if (!existsSync(manifestPath)) fail(`Missing manifest: ${manifestPath}`);
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const required = ["name", "displayName", "version", "summary", "description", "author", "category", "entry"];
+  const missing = required.filter((key) => !manifest[key]);
+  if (missing.length > 0) fail(`Manifest missing fields: ${missing.join(", ")}`);
+  if (manifest.entry !== "SKILL.md") {
+    throw new Error("Manifest entry must be the root-level SKILL.md for client compatibility");
+  }
+  safeInstallRelativePath(manifest.name);
+  if (typeof manifest.version !== "string" || !skillVersionPattern.test(manifest.version)) throw new Error(`Invalid skill version: ${manifest.version}`);
+  const skillPath = resolveLocalSkillEntry(packageDir, manifest.entry);
+  return {
+    ...manifest,
+    readme: readFileSync(skillPath, "utf8")
+  };
+}
+
+function resolveLocalSkillEntry(packageDir, entry) {
+  if (
+    typeof entry !== "string" ||
+    entry === "" ||
+    entry.includes("\0") ||
+    entry.includes("\\") ||
+    isAbsolute(entry) ||
+    /^[A-Za-z]:/.test(entry) ||
+    entry.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new Error(`Unsafe manifest entry: ${String(entry)}`);
+  }
+
+  const segments = entry.split("/");
+  let current = resolve(packageDir);
+  for (const [index, segment] of segments.entries()) {
+    if (!readdirSync(current).includes(segment)) {
+      throw new Error(`Missing skill entry with exact casing: ${entry}`);
+    }
+    current = join(current, segment);
+    const stats = lstatSync(current);
+    if (index < segments.length - 1 && !stats.isDirectory()) {
+      throw new Error(`Skill entry parent must be a regular directory: ${entry}`);
+    }
+    if (index === segments.length - 1 && !stats.isFile()) {
+      throw new Error(`Skill entry must be a regular file: ${entry}`);
+    }
+  }
+  return current;
+}
+
+async function apiList(registry, query, token, requestedLimit) {
+  const defaultPageSize = Number.isInteger(requestedLimit) ? requestedLimit : 100;
+  const collected = [];
+  const categories = new Set();
+  let firstResponse;
+  let page = 1;
+  let nextPageSize = defaultPageSize;
+  let total;
+  let previousSignature;
+
+  // New registries expose total/pageSize so clients can walk the complete
+  // public catalogue. Older registries may ignore these query parameters;
+  // when their response has no pagination metadata we retain one-page
+  // compatibility instead of issuing an unbounded sequence of duplicate
+  // requests.
+  while (true) {
+    const params = new URLSearchParams();
+    if (query.trim()) params.set("q", query.trim());
+    // Keep the first request compatible with registries that predate the
+    // count-aware pagination fields. Subsequent requests opt into paging.
+    if (page > 1) {
+      params.set("page", String(page));
+      params.set("pageSize", String(nextPageSize));
+    }
+    const response = await apiFetch(registry, `/api/skills?${params.toString()}`, undefined, token);
+    if (!firstResponse) firstResponse = response;
+    const batch = Array.isArray(response?.skills) ? response.skills : [];
+    for (const category of Array.isArray(response?.categories) ? response.categories : []) {
+      if (typeof category === "string" && category.trim()) categories.add(category);
+    }
+
+    const responseTotal = typeof response?.total === "number" || (typeof response?.total === "string" && response.total.trim() !== "") ? Number(response.total) : NaN;
+    const hasTotal = Number.isSafeInteger(responseTotal) && responseTotal >= 0;
+    const responsePageSize = typeof response?.pageSize === "number" || (typeof response?.pageSize === "string" && response.pageSize.trim() !== "") ? Number(response.pageSize) : NaN;
+    if (Number.isSafeInteger(responsePageSize) && responsePageSize > 0) nextPageSize = responsePageSize;
+    const responsePage = typeof response?.page === "number" || (typeof response?.page === "string" && response.page.trim() !== "") ? Number(response.page) : NaN;
+    const hasPageMetadata = Number.isSafeInteger(responsePage) && responsePage >= 1;
+    const signature = JSON.stringify(batch);
+    if (page > 1 && signature === previousSignature) break;
+    previousSignature = signature;
+    collected.push(...batch);
+    if (hasTotal) total = responseTotal;
+
+    if (!hasTotal || batch.length === 0) break;
+    if (Number.isInteger(requestedLimit) && collected.length >= requestedLimit) break;
+    if (collected.length >= total) break;
+    if (hasPageMetadata && responsePage !== page) break;
+    page += 1;
+  }
+
+  const result = firstResponse && typeof firstResponse === "object" ? { ...firstResponse } : {};
+  result.skills = Number.isInteger(requestedLimit) ? collected.slice(0, requestedLimit) : collected;
+  if (categories.size > 0) result.categories = [...categories].sort();
+  if (Number.isSafeInteger(total)) result.total = total;
+  return result;
+}
+
+async function apiInfo(registry, name, token) {
+  return apiFetch(registry, `/api/skills/-/resolve?name=${encodeURIComponent(name)}`, undefined, token);
+}
+
+async function apiInfoWithOwnerFallback(registry, name, token, requestedVersion) {
+  let publicSkill;
+  try {
+    publicSkill = await apiInfo(registry, name, token);
+    if (!requestedVersion || publicSkill?.version === requestedVersion || !token) return publicSkill;
+  } catch (error) {
+    if (!(error instanceof RegistryError) || error.status !== 404 || !token) throw error;
+  }
+  const owned = await apiFindOwnedSkill(registry, name, token);
+  if (!owned) {
+    if (publicSkill) return publicSkill;
+    throw new RegistryError(`Skill not found: ${name}`, 404);
+  }
+  const pkg = await apiOwnedPackage(registry, owned.id, token);
+  assertOwnedPackageIdentity(pkg, owned, name);
+  return pkg.skill;
+}
+
+async function apiPackage(registry, name, token) {
+  return apiFetch(registry, `/api/skills/-/package?name=${encodeURIComponent(name)}`, undefined, token);
+}
+
+async function apiPackageWithOwnerFallback(registry, name, token, requestedVersion) {
+  let publicPackage;
+  try {
+    publicPackage = await apiPackage(registry, name, token);
+    if (!requestedVersion || publicPackage?.skill?.version === requestedVersion || !token) return publicPackage;
+  } catch (error) {
+    if (!(error instanceof RegistryError) || error.status !== 404 || !token) throw error;
+  }
+  const owned = await apiFindOwnedSkill(registry, name, token);
+  if (!owned) {
+    if (publicPackage) return publicPackage;
+    throw new RegistryError(`Skill not found: ${name}`, 404);
+  }
+  const pkg = await apiOwnedPackage(registry, owned.id, token);
+  assertOwnedPackageIdentity(pkg, owned, name);
+  return pkg;
+}
+
+async function apiOwnedPackage(registry, id, token) {
+  return apiFetch(registry, `/api/me/skills/${encodeURIComponent(id)}/package`, undefined, token);
+}
+
+function assertOwnedPackageIdentity(pkg, owned, requestedName) {
+  if (!pkg?.skill || String(pkg.skill.id ?? "") !== String(owned.id) || pkg.skill.name !== requestedName) {
+    throw new Error("Registry returned a package that does not match the authenticated owner's Skill");
+  }
+}
+
+async function apiDownload(registry, name, token) {
+  return apiFetch(registry, `/api/skills/-/download?name=${encodeURIComponent(name)}`, { method: "POST" }, token);
+}
+
+async function apiFindOwnedSkillIfSupported(registry, name, token) {
+  try {
+    return await apiFindOwnedSkill(registry, name, token);
+  } catch (error) {
+    if (error instanceof RegistryError && [404, 405].includes(error.status)) return undefined;
+    throw error;
+  }
+}
+
+async function apiFindOwnedSkill(registry, name, token) {
+  const data = await apiFetch(registry, "/api/me/skills", undefined, token);
+  const matches = Array.isArray(data?.skills) ? data.skills.filter((item) => item?.name === name && item?.id) : [];
+  if (matches.length > 1) throw new Error(`Registry returned duplicate owned Skills named ${name}`);
+  return matches[0] ? { ...matches[0], id: String(matches[0].id) } : undefined;
+}
+
+async function apiUploadFiles(registry, manifest, files, token, skillId) {
+  const form = new FormData();
+  const paths = Object.keys(files).sort();
+  form.append("paths", JSON.stringify(paths));
+  form.append("visibility", "private");
+  if (skillId) form.append("skillId", String(skillId));
+  paths.forEach((path, index) => form.append(`file:${index}`, new Blob([files[path]]), `file-${index}`));
+  try {
+    return await apiFetch(registry, "/api/me/skills/files", { method: "POST", body: form, signal: AbortSignal.timeout(300_000) }, token);
+  } catch (error) {
+    if (!(error instanceof RegistryError) || ![404, 405].includes(error.status)) throw error;
+    throw new Error("Registry does not support direct file uploads; upgrade the API server before publishing this package");
+  }
+}
+
+async function apiFetch(registry, path, init = {}, token) {
+  let response;
+  const headers = new Headers(init.headers);
+  if (token) headers.set("Authorization", `Bearer ${token}`);
+  try {
+    response = await fetch(`${trimSlash(registry)}${path}`, {
+      ...init,
+      headers,
+      signal: init.signal ?? AbortSignal.timeout(20_000)
+    });
+  } catch (error) {
+    const cause = error?.cause?.message ? ` (${error.cause.message})` : "";
+    throw new Error(`Registry request failed: ${error.message}${cause}`);
+  }
+  if (!response.ok) {
+    let message = `Registry request failed: ${response.status}`;
+    try {
+      const error = await response.json();
+      if (error?.error) message = error.error;
+    } catch {
+      // Keep status message when the server does not return JSON.
+    }
+    if (response.status === 401) message += `. Run "${cliName} login --registry ${registry}" to sign in again, or replace YEP_TOKEN/--token if set.`;
+    throw new RegistryError(message, response.status);
+  }
+  if (response.status === 204) return undefined;
+  return response.json();
+}
+
+class RegistryError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+
+async function recordDownload(registry, name, token, success = "downloaded successfully") {
+  try {
+    await apiDownload(registry, name, token);
+  } catch (error) {
+    console.warn(`Warning: ${success}, but could not update the download count: ${error.message}`);
+  }
+}
+
+function shouldRecordDownload(skill) {
+  return skill?.visibility !== "private" && !["draft", "pending", "rejected"].includes(skill?.status);
+}
+
+function collectPackageFiles(packageDir) {
+  const files = Object.create(null);
+  const seenPaths = new Map();
+  let count = 0;
+  let totalBytes = 0;
+
+  function visit(directory, prefix = "") {
+    for (const name of readdirSync(directory).sort()) {
+      const packagePath = prefix ? `${prefix}/${name}` : name;
+      if (shouldIgnorePackagePath(packagePath)) continue;
+      safePackageOutput(packageDir, packagePath);
+      const diskPath = join(directory, name);
+      const stats = lstatSync(diskPath);
+      const pathKey = packagePath.toLowerCase();
+      if (seenPaths.has(pathKey)) throw new Error(`Package paths differ only by case: ${seenPaths.get(pathKey)} and ${packagePath}`);
+      seenPaths.set(pathKey, packagePath);
+      if (stats.isSymbolicLink()) throw new Error(`Package cannot contain symbolic links: ${packagePath}`);
+      if (stats.isDirectory()) {
+        visit(diskPath, packagePath);
+        continue;
+      }
+      if (!stats.isFile()) continue;
+      count++;
+      totalBytes += stats.size;
+      if (count > maxPackageFiles) throw new Error(`Package exceeds ${maxPackageFiles} files`);
+      if (stats.size > maxPackageFileBytes) {
+        throw new Error(`Package file exceeds ${maxPackageFileBytes / 1024 / 1024} MiB: ${packagePath}`);
+      }
+      if (totalBytes > maxExpandedPackageBytes) {
+        throw new Error(`Package expands beyond ${maxExpandedPackageBytes / 1024 / 1024} MiB`);
+      }
+      files[packagePath] = new Uint8Array(readFileSync(diskPath));
+    }
+  }
+
+  visit(packageDir);
+  return files;
+}
+
+function shouldIgnorePackagePath(packagePath) {
+  const segments = packagePath.split("/");
+  const name = basename(packagePath);
+  return segments.includes(".git") || segments.includes("node_modules") || name === ".DS_Store" || name === "yep-installed.json" || name === ".yep.json" || name === "cpm-installed.json" || name === ".skills-center.json" || name === ".env" || name.startsWith(".env.");
+}
+
+function safePackageOutput(target, packagePath) {
+  const segments = typeof packagePath === "string" ? packagePath.split("/") : [];
+  if (
+    typeof packagePath !== "string" ||
+    packagePath === "" ||
+    Buffer.byteLength(packagePath, "utf8") > maxPackagePathBytes ||
+    packagePath.includes("\0") ||
+    packagePath.includes("\\") ||
+    isAbsolute(packagePath) ||
+    /^[A-Za-z]:/.test(packagePath) ||
+    /[\u0000-\u001f\u007f-\u009f]/u.test(packagePath) ||
+    segments.some((segment) => segment === "" || segment === "." || segment === ".." || !isPortablePackageSegment(segment))
+  ) {
+    throw new Error(`Unsafe package path: ${String(packagePath)}`);
+  }
+  const root = resolve(target);
+  const output = resolve(root, packagePath);
+  const rel = relative(root, output);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
+    throw new Error(`Unsafe package path: ${packagePath}`);
+  }
+  return output;
+}
+
+function isPortablePackageSegment(segment) {
+  if (
+    Buffer.byteLength(segment, "utf8") > maxPackageSegmentBytes ||
+    segment.endsWith(".") ||
+    segment.endsWith(" ") ||
+    /[<>:"|?*]/u.test(segment)
+  ) {
+    return false;
+  }
+  const base = segment.split(".", 1)[0].toUpperCase();
+  return !["CON", "PRN", "AUX", "NUL"].includes(base) && !/^(?:COM|LPT)[1-9]$/.test(base);
+}
+
+function validateRemotePackage(pkg, installRoot, requestedName, targetPath, normalizeSkillEntry = true) {
+  if (!pkg || typeof pkg !== "object" || !pkg.skill || typeof pkg.skill !== "object") {
+    throw new Error("Invalid remote package metadata");
+  }
+  for (const field of ["name", "displayName", "version", "entry"]) {
+    if (typeof pkg.skill[field] !== "string" || pkg.skill[field].trim() === "") {
+      throw new Error(`Invalid remote package skill.${field}`);
+    }
+  }
+  if (pkg.skill.name !== requestedName) throw new Error(`Registry returned package ${pkg.skill.name} for requested ${requestedName}`);
+  const requestedEntry = pkg.skill.entry;
+  safePackageOutput(targetPath ? resolve(targetPath) : installRoot, requestedEntry);
+  safeInstallRelativePath(pkg.skill.name);
+  if (!skillVersionPattern.test(pkg.skill.version)) throw new Error(`Invalid remote package skill.version: ${pkg.skill.version}`);
+  if (!Array.isArray(pkg.files)) throw new Error("Invalid remote package files");
+  if (pkg.files.length === 0) throw new Error("Remote package contains no files");
+  if (pkg.files.length > maxPackageFiles) throw new Error(`Package exceeds ${maxPackageFiles} files`);
+
+  const target = targetPath ? resolve(targetPath) : join(installRoot, safeInstallRelativePath(pkg.skill.name));
+  safePackageOutput(target, requestedEntry);
+  const files = [];
+  const seenPaths = new Set();
+  const exactPaths = new Set();
+  let totalBytes = 0;
+  for (const file of pkg.files) {
+    if (!file || typeof file !== "object") throw new Error("Invalid remote package file");
+    safePackageOutput(target, file.path);
+    const pathKey = file.path.toLowerCase();
+    if (seenPaths.has(pathKey)) throw new Error(`Duplicate package path: ${file.path}`);
+    seenPaths.add(pathKey);
+    exactPaths.add(file.path);
+
+    const content = decodePackageContent(file.contentBase64, file.path);
+    totalBytes += content.length;
+    if (totalBytes > maxExpandedPackageBytes) {
+      throw new Error(`Package expands beyond ${maxExpandedPackageBytes / 1024 / 1024} MiB`);
+    }
+    files.push({ path: file.path, pathKey, content });
+  }
+
+  const sortedPaths = files.map((file) => file.pathKey).sort();
+  for (let index = 0; index < sortedPaths.length - 1; index++) {
+    if (sortedPaths[index + 1].startsWith(`${sortedPaths[index]}/`)) {
+      throw new Error(`Conflicting package paths: ${sortedPaths[index]} and ${sortedPaths[index + 1]}`);
+    }
+  }
+  if (!exactPaths.has(requestedEntry)) throw new Error(`Remote package is missing its entry file: ${requestedEntry}`);
+  // Older registries may point at docs/SKILL.md. Normalize that entry at install time so
+  // Codex and Claude both receive the root-level SKILL.md they discover natively.
+  if (normalizeSkillEntry && requestedEntry !== "SKILL.md") {
+    const entryFile = files.find((file) => file.path === requestedEntry);
+    if (!entryFile) throw new Error(`Remote package is missing its entry file: ${requestedEntry}`);
+    const normalizedFiles = files.filter((file) => file.path !== requestedEntry && file.path !== "SKILL.md");
+    normalizedFiles.push({ ...entryFile, path: "SKILL.md" });
+    return { skill: { ...pkg.skill, entry: "SKILL.md" }, target, files: normalizedFiles };
+  }
+  return { skill: pkg.skill, target, files };
+}
+
+function decodePackageContent(contentBase64, packagePath) {
+  const maximumBase64Length = Math.ceil(maxPackageFileBytes / 3) * 4;
+  if (
+    typeof contentBase64 !== "string" ||
+    contentBase64.length > maximumBase64Length ||
+    contentBase64.length % 4 !== 0 ||
+    !hasValidBase64CharactersAndPadding(contentBase64)
+  ) {
+    throw new Error(`Invalid base64 content for package file: ${String(packagePath)}`);
+  }
+  const content = Buffer.from(contentBase64, "base64");
+  if (content.toString("base64") !== contentBase64) {
+    throw new Error(`Invalid base64 content for package file: ${packagePath}`);
+  }
+  if (content.length > maxPackageFileBytes) {
+    throw new Error(`Package file exceeds ${maxPackageFileBytes / 1024 / 1024} MiB: ${packagePath}`);
+  }
+  return content;
+}
+
+function hasValidBase64CharactersAndPadding(value) {
+  let padding = 0;
+  if (value.endsWith("=")) padding++;
+  if (value.endsWith("==")) padding++;
+  const contentLength = value.length - padding;
+
+  for (let index = 0; index < contentLength; index++) {
+    const code = value.charCodeAt(index);
+    const isBase64Character =
+      (code >= 65 && code <= 90) ||
+      (code >= 97 && code <= 122) ||
+      (code >= 48 && code <= 57) ||
+      code === 43 ||
+      code === 47;
+    if (!isBase64Character) return false;
+  }
+  for (let index = contentLength; index < value.length; index++) {
+    if (value.charCodeAt(index) !== 61) return false;
+  }
+  return padding <= 2;
+}
+
+function installRemotePackage(target, files, skill, registry, client = "local") {
+  installPackageAtomically(target, skill, registry, (staging) => {
+    for (const file of files) {
+      const output = safePackageOutput(staging, file.path);
+      mkdirSync(dirname(output), { recursive: true });
+      writeFileSync(output, file.content);
+    }
+  }, client);
+}
+
+function installLocalPackage(target, source, skill, client = "local") {
+  installPackageAtomically(target, skill, registryPath, (staging) => copyDir(source, staging), client);
+}
+
+function installPackageAtomically(target, skill, registry, populate, client = "local") {
+  const parent = dirname(target);
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, `.${basename(target)}.tmp-`));
+  try {
+    populate(staging);
+    writeInstalledManifest(staging, skill, registry, client);
+    replaceInstalledDirectory(staging, target);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function replaceInstalledDirectory(staging, target) {
+  if (!existsSync(target)) {
+    renameSync(staging, target);
+    return;
+  }
+
+  const previous = `${staging}.previous`;
+  renameSync(target, previous);
+  try {
+    renameSync(staging, target);
+  } catch (error) {
+    renameSync(previous, target);
+    throw error;
+  }
+
+  try {
+    rmSync(previous, { recursive: true, force: true });
+  } catch (error) {
+    renameSync(target, staging);
+    renameSync(previous, target);
+    throw error;
+  }
+}
+
+function writeInstalledManifest(target, skill, registry, client = "local") {
+  writeFileSync(
+    join(target, client === "local" ? "yep-installed.json" : ".yep.json"),
+    JSON.stringify(
+      {
+        name: skill.name,
+        version: skill.version,
+        installedAt: new Date().toISOString(),
+        registry,
+        client,
+        ...(skill.kind ? { kind: skill.kind, revisionId: skill.currentRevisionId } : {})
+      },
+      null,
+      2
+    )
+  );
+}
+
+function requiredArg(value, usage) {
+  if (!value || value.startsWith("--")) fail(usage);
+  return value;
+}
+
+function safePackageDir(name) {
+  safeInstallRelativePath(name);
+  return encodeURIComponent(name);
+}
+
+function safeInstallRelativePath(name) {
+  if (typeof name !== "string") throw new Error(`Unsafe package name: ${String(name)}`);
+  const match = /^@([a-z0-9][a-z0-9._-]{2,31})\/([a-z0-9][a-z0-9._-]{1,63})$/.exec(name);
+  if (!match) throw new Error(`Unsafe package name: ${name}`);
+  return join(match[1], match[2]);
+}
+
+function copyDir(source, target) {
+  mkdirSync(target, { recursive: true });
+  for (const entry of readdirSync(source)) {
+    const from = join(source, entry);
+    const to = join(target, entry);
+    const stats = lstatSync(from);
+    if (stats.isSymbolicLink()) throw new Error(`Package cannot contain symbolic links: ${from}`);
+    if (stats.isDirectory()) {
+      copyDir(from, to);
+    } else if (stats.isFile()) {
+      writeFileSync(to, readFileSync(from));
+    } else {
+      throw new Error(`Unsupported package entry: ${from}`);
+    }
+  }
+}
+
+function requireRegistryToken(token, registry, operation) {
+  if (typeof token === "string" && token.trim()) return token.trim();
+  throw new Error(`Authentication is required to ${operation}. Run "${cliName} login --registry ${registry}" or set YEP_TOKEN.`);
+}
+
+function normalizeRegistry(value) {
+  let url;
+  try {
+    url = new URL(String(value));
+  } catch {
+    throw new Error(`Invalid registry URL: ${String(value)}`);
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error("Registry URL must use HTTP(S) and cannot contain credentials, a query, or a fragment");
+  }
+  return trimSlash(url.toString());
+}
+
+function trimSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}