@newlandnpt/pep-cli 0.4.1 → 0.6.0

package/README.md

@@ -137,9 +137,55 @@ pep skills add group/sub/project -p    # move it into this project
 `pep skills list` prints each repository with the directory it lives in, which is what `-p` matches
 against.
 
-Deleting a skill folder by hand is fine — `pep skills update` notices it is missing and writes it
-again. It checks the disk, not just its own ledger, so it cannot report "already up to date" about
-files that are no longer there.
+### Removing a repository
+
+```powershell
+pep skills remove group/sub/project
+```
+
+Deletes the skills that repository installed (in both the canonical directory and the linked one)
+and drops it from the list. It only removes what it installed itself — anything you put there by
+hand stays — and it needs no login, since nothing leaves the machine.
+
+### Two repositories, one skill name
+
+A skill's name is the folder name **inside** the repository, not the repository's own name. So two
+different repositories that each ship a `semi-integration/SKILL.md` both want
+`~/.agents/skills/semi-integration/`, and the second would silently overwrite the first.
+
+Adding a second such repository is refused, and the error names the one already there. If you
+already have a colliding pair from an older version, nothing breaks — every command reports it
+until you `remove` one:
+
+```
+⚠ 3 repositories all install "semi-integration" here:
+    https://git.example.com/team-a/skill
+    https://git.example.com/team-b/skill-testing
+  They overwrite each other. `pep skills remove <repo>` keeps just one.
+```
+
+Installing them into **different** directories is fine — that is what `-p` is for.
+
+`remove` leaves a shared skill's files on disk (which copy it is can no longer be told) and says
+so, rather than deleting what might be the other repository's content.
+
+### Deleting a skill
+
+Delete a skill folder by hand and it **stays deleted**. `update` refreshes what is still on disk
+and leaves the rest alone, naming them so the run is not silent:
+
+```
+group/sub/project: updated b
+  deleted locally, left alone: a
+  (`pep skills add group/sub/project` puts them back)
+```
+
+`add` is the command that installs, so that is what brings a deleted skill back. This split is
+deliberate: `update` means "bring what I have up to date", not "refill everything the repository
+offers".
+
+Skills that are **new upstream** are still installed by `update` — the test is "was mine and is now
+gone", not "is absent".
 
 `pep auth token` writes only the access token to stdout, so agents can use it without parsing status
 text. Refresh occurs automatically shortly before expiry and the rotated refresh token replaces the old

package/dist/pep.cjs

@@ -1195,14 +1195,43 @@ function hashSkill(files) {
   }
   return hash.digest("hex").slice(0, 32);
 }
-async function allPresent(directory, skills, linkedInto) {
-  for (const skill of skills) {
-    if (!await (0, import_promises4.stat)((0, import_node_path4.join)(directory, skill)).catch(() => null)) return false;
-    if (linkedInto !== void 0 && !await (0, import_promises4.stat)((0, import_node_path4.join)(linkedInto, skill)).catch(() => null)) {
-      return false;
+async function removeSkills(name, store) {
+  const state = await store.read();
+  const pkg = state?.packages[name];
+  if (!state || !pkg) {
+    throw new Error(`Not added: ${name}. Run \`pep skills list\` to see what is.`);
+  }
+  const deleted = [];
+  const keptForOthers = [];
+  for (const skill of Object.keys(pkg.skills).sort()) {
+    const owner = Object.entries(state.packages).find(
+      ([other, one]) => other !== name && one.directory === pkg.directory && skill in one.skills
+    )?.[0];
+    if (owner !== void 0) {
+      keptForOthers.push({ skill, owner });
+      continue;
+    }
+    await (0, import_promises4.rm)((0, import_node_path4.join)(pkg.directory, skill), { recursive: true, force: true });
+    if (pkg.linkedInto !== void 0) {
+      await (0, import_promises4.rm)((0, import_node_path4.join)(pkg.linkedInto, skill), { recursive: true, force: true });
     }
+    deleted.push(skill);
   }
-  return true;
+  const { [name]: _dropped, ...rest } = state.packages;
+  await store.write({ version: 4, packages: rest });
+  return { name, deleted, keptForOthers, directory: pkg.directory };
+}
+function pickSkipped(previous, skipped) {
+  return Object.fromEntries(
+    skipped.map((skill) => [skill, previous?.skills[skill] ?? ""])
+  );
+}
+async function missingSkills(directory, skills) {
+  const gone = /* @__PURE__ */ new Set();
+  for (const skill of skills) {
+    if (!await (0, import_promises4.stat)((0, import_node_path4.join)(directory, skill)).catch(() => null)) gone.add(skill);
+  }
+  return gone;
 }
 async function updateSkills(dependencies) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
@@ -1220,10 +1249,18 @@ async function updateSkills(dependencies) {
   const state = await dependencies.stateStore.read();
   const previous = state?.packages[name];
   const sameTarget = previous?.directory === dependencies.directory && previous?.linkedInto === dependencies.linkInto;
-  const intact = sameTarget && previous !== void 0 && await allPresent(previous.directory, Object.keys(previous.skills), previous.linkedInto);
-  if (commit !== void 0 && commit === previous?.commit && intact) {
+  const claimedElsewhere = (skill) => Object.entries(state?.packages ?? {}).find(
+    ([other, pkg]) => other !== name && pkg.directory === dependencies.directory && skill in pkg.skills
+  )?.[0];
+  const gone = previous !== void 0 && sameTarget ? await missingSkills(previous.directory, Object.keys(previous.skills)) : /* @__PURE__ */ new Set();
+  const nothingToRestore = !dependencies.restoreMissing || gone.size === 0;
+  const standing = Object.keys(previous?.skills ?? {}).flatMap((skill) => {
+    const owner = claimedElsewhere(skill);
+    return owner ? [{ skill, owner }] : [];
+  });
+  if (commit !== void 0 && commit === previous?.commit && sameTarget && nothingToRestore) {
     await response.body?.cancel();
-    return { status: "unchanged", name, commit };
+    return { status: "unchanged", name, commit, conflicts: standing };
   }
   const gzipped = new Uint8Array(await response.arrayBuffer());
   const files = planSkillFiles(readTar((0, import_node_zlib.gunzipSync)(gzipped)));
@@ -1233,7 +1270,9 @@ async function updateSkills(dependencies) {
     if (group) group.push(file);
     else bySkill.set(file.skill, [file]);
   }
-  const skills = [...bySkill.keys()].sort();
+  const inArchive = [...bySkill.keys()].sort();
+  const skipped = dependencies.restoreMissing ? [] : inArchive.filter((skill) => gone.has(skill));
+  const skills = inArchive.filter((skill) => !skipped.includes(skill));
   const hashes = {};
   const updated = [];
   const unchanged = [];
@@ -1241,10 +1280,23 @@ async function updateSkills(dependencies) {
     const hash = hashSkill(bySkill.get(skill));
     hashes[skill] = hash;
     const before = previous?.skills[skill];
-    if (before !== void 0 && before !== "" && before === hash) unchanged.push(skill);
+    if (gone.has(skill)) updated.push(skill);
+    else if (before !== void 0 && before !== "" && before === hash) unchanged.push(skill);
     else updated.push(skill);
   }
-  const removed = Object.keys(previous?.skills ?? {}).filter((skill) => !skills.includes(skill));
+  const conflicts = [];
+  for (const skill of skills) {
+    const owner = claimedElsewhere(skill);
+    if (owner === void 0) continue;
+    if (previous !== void 0 && skill in previous.skills) {
+      conflicts.push({ skill, owner });
+      continue;
+    }
+    throw new Error(
+      `${owner} already installs a skill named "${skill}" in ${dependencies.directory}. Two repositories cannot both provide "${skill}" there \u2014 the second would silently overwrite the first. Install this one elsewhere (-p, or --dir <path>), or run \`pep skills remove ${owner}\` first.`
+    );
+  }
+  const removed = Object.keys(previous?.skills ?? {}).filter((skill) => !inArchive.includes(skill));
   if (previous !== void 0) {
     const stale = sameTarget ? removed : Object.keys(previous.skills);
     for (const skill of stale) {
@@ -1258,6 +1310,7 @@ async function updateSkills(dependencies) {
     await (0, import_promises4.rm)((0, import_node_path4.join)(dependencies.directory, skill), { recursive: true, force: true });
   }
   for (const file of files) {
+    if (skipped.includes(file.skill)) continue;
     const target = (0, import_node_path4.join)(dependencies.directory, file.skill, ...file.path.split("/"));
     await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(target), { recursive: true });
     await (0, import_promises4.writeFile)(target, file.data);
@@ -1282,7 +1335,9 @@ async function updateSkills(dependencies) {
         ...commit ? { commit } : {},
         directory: dependencies.directory,
         ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
-        skills: hashes
+        // 跳过的那些**原样留着上次的哈希** —— 账上仍然认它是这个包的（将来 add 能补回来，
+        // 上游删掉时也还清得动），只是这次没去碰它。
+        skills: { ...pickSkipped(previous, skipped), ...hashes }
       }
     }
   });
@@ -1292,8 +1347,10 @@ async function updateSkills(dependencies) {
     updated,
     unchanged,
     skills,
-    fileCount: files.length,
+    fileCount: files.filter((one) => !skipped.includes(one.skill)).length,
     removed,
+    skipped,
+    conflicts,
     directory: dependencies.directory,
     ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
     ...copiedCount > 0 ? { copiedCount } : {},
@@ -1302,7 +1359,7 @@ async function updateSkills(dependencies) {
 }
 
 // src/cli.ts
-var VERSION = false ? "0.0.0-dev" : "0.4.1";
+var VERSION = false ? "0.0.0-dev" : "0.6.0";
 function usage() {
   return `PEP CLI ${VERSION}
 
@@ -1314,6 +1371,7 @@ Usage:
   pep skills list
   pep skills add <repo-url | group/project[@ref]> [-p | --dir <path>]
   pep skills update [<repo>...] [-p | --dir <path>]
+  pep skills remove <repo>
   pep docs list [--docs-url <url>]
   pep docs get <path> [--docs-url <url>]
   pep nexus setup
@@ -1358,8 +1416,18 @@ it already lives and never moves anything. On update, -p and --dir instead NARRO
 repositories installed there: \`pep skills update -p\` refreshes only this project's, and reports
 nothing to do when the project has none. To move a repository, add it again with the new flag \u2014
 add is where the location is decided, and the copy in the old location is then removed.
-Deleting a skill folder by hand is fine: update notices it is gone and writes it again.
-Either way update only touches skills it wrote itself; anything you put there by hand is left alone.
+\`pep skills remove <repo>\` deletes the skills that repository installed and drops it from the
+list. It only removes what it installed itself, and it needs no login. A skill that another
+repository also installs is left on disk (which copy it is can no longer be told) and reported.
+
+Two repositories cannot both provide a skill with the SAME NAME in one directory \u2014 the skill name
+is the folder name inside the repository, so they would overwrite each other. Adding a second one
+is refused; if you already have such a pair, every command says so until you remove one.
+
+Delete a skill folder by hand and update LEAVES IT DELETED \u2014 it refreshes what is still there and
+reports the ones it left alone. Run \`pep skills add <repo>\` to put them back; add is the command
+that installs. Either way update only touches skills it wrote itself; anything you put there by
+hand is left alone.
 
 \`pep docs list\` prints the documents this account can read (path + description); feed a path
 straight to \`pep docs get\` to print that document as markdown on stdout. The documentation
@@ -1376,8 +1444,15 @@ The password is shown by PEP once and never stored, so a second run reports 409
 handing it out again.`;
 }
 function reportUpdate(result) {
+  const conflicts = () => {
+    for (const { skill, owner } of result.conflicts) {
+      console.error(`  \u26A0 "${skill}" is also installed here by ${owner} \u2014 they overwrite`);
+      console.error(`    each other. \`pep skills remove\` one of them to settle it.`);
+    }
+  };
   if (result.status === "unchanged") {
     console.log(`${result.name}: already at ${result.commit}. Nothing to do.`);
+    conflicts();
     return;
   }
   console.log(
@@ -1386,6 +1461,11 @@ function reportUpdate(result) {
   if (result.unchanged.length > 0) {
     console.log(`  unchanged: ${result.unchanged.join(" ")}`);
   }
+  if (result.skipped.length > 0) {
+    console.log(`  deleted locally, left alone: ${result.skipped.join(" ")}`);
+    console.log(`  (\`pep skills add ${result.name}\` puts them back)`);
+  }
+  conflicts();
   console.log(`  ${result.fileCount} file(s) in ${result.directory}`);
   if (result.linkedInto !== void 0) {
     console.log(
@@ -1442,17 +1522,22 @@ async function loginConfig(args, store = fileConfigStore()) {
   };
 }
 function parseSkillsArgs(command, args, cwd) {
-  const explicitDirectory = command === "list" ? void 0 : option(args, "--dir");
-  const project = command === "list" ? false : flag(args, "--project", "-p");
+  const local = command === "list" || command === "remove";
+  const explicitDirectory = local ? void 0 : option(args, "--dir");
+  const project = local ? false : flag(args, "--project", "-p");
   if (explicitDirectory !== void 0 && project) {
     throw new Error("--dir and --project/-p cannot be used together: they name different places.");
   }
   const unknownOption = args.find((one) => one.startsWith("-"));
   if (unknownOption) throw new Error(`Unknown option: ${unknownOption}`);
-  const requested = command === "add" ? args.shift() : void 0;
+  const takesOne = command === "add" || command === "remove";
+  const requested = takesOne ? args.shift() : void 0;
   if (command === "add" && !requested) {
     throw new Error("pep skills add needs a repository: a full https URL, or <group>/<project>.");
   }
+  if (command === "remove" && !requested) {
+    throw new Error("pep skills remove needs a repository. Run `pep skills list` to see them.");
+  }
   const named = command === "update" ? [...args] : [];
   if (command !== "update" && args.length > 0) {
     throw new Error(`Unexpected argument: ${args[0]}`);
@@ -1552,16 +1637,15 @@ ${usage()}`);
     return;
   }
   if (group === "skills") {
-    if (command !== "update" && command !== "add" && command !== "list") {
+    if (command !== "update" && command !== "add" && command !== "list" && command !== "remove") {
       throw new Error(`Unknown skills command.
 
 ${usage()}`);
     }
     const { requested, named, chosenTarget } = parseSkillsArgs(command, args);
-    const authorization = await auth.currentAuthorization();
-    const remote = { issuer: authorization.issuer, accessToken: authorization.accessToken };
+    const stateStore = fileSkillsStateStore();
     if (command === "list") {
-      const listed = await fileSkillsStateStore().read();
+      const listed = await stateStore.read();
       const packages = Object.entries(listed?.packages ?? {}).sort(
         ([a], [b]) => a.localeCompare(b)
       );
@@ -1570,23 +1654,54 @@ ${usage()}`);
         return;
       }
       for (const [source, pkg] of packages) console.log(`${source}	${pkg.directory}`);
+      const byPlace = /* @__PURE__ */ new Map();
+      for (const [source, pkg] of packages) {
+        for (const skill of Object.keys(pkg.skills)) {
+          const key = `${pkg.directory}\0${skill}`;
+          byPlace.set(key, [...byPlace.get(key) ?? [], source]);
+        }
+      }
+      for (const [key, owners] of byPlace) {
+        if (owners.length < 2) continue;
+        const skill = key.split("\0")[1];
+        console.error(`
+\u26A0 ${owners.length} repositories all install "${skill}" here:`);
+        for (const one of owners) console.error(`    ${one}`);
+        console.error("  They overwrite each other. `pep skills remove <repo>` keeps just one.");
+      }
       console.error("\n`pep skills update` refreshes all of them, each where it lives.");
       return;
     }
-    const stateStore = fileSkillsStateStore();
+    if (command === "remove") {
+      const result = await removeSkills(requested, stateStore);
+      console.log(
+        result.deleted.length > 0 ? `${result.name}: removed ${result.deleted.join(" ")} from ${result.directory}` : `${result.name}: nothing on disk to delete; dropped it from the list`
+      );
+      for (const { skill, owner } of result.keptForOthers) {
+        console.error(`  kept "${skill}" \u2014 ${owner} also installs it here`);
+      }
+      return;
+    }
+    const authorization = await auth.currentAuthorization();
+    const remote = { issuer: authorization.issuer, accessToken: authorization.accessToken };
     const state = await stateStore.read();
     const installed = Object.keys(state?.packages ?? {}).sort();
-    const run2 = async (source, target) => reportUpdate(
+    const run2 = async (source, target, restoreMissing = false) => reportUpdate(
       await updateSkills({
         ...remote,
         source,
         directory: target.directory,
         ...target.linkInto !== void 0 ? { linkInto: target.linkInto } : {},
+        ...restoreMissing ? { restoreMissing: true } : {},
         stateStore
       })
     );
     if (command === "add") {
-      await run2(requested, targetForSource(chosenTarget, state?.packages[requested]));
+      await run2(
+        requested,
+        targetForSource(chosenTarget, state?.packages[requested]),
+        true
+      );
       return;
     }
     if (installed.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newlandnpt/pep-cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "PEP CLI —— 凭 PEP 身份读取 Newland 开发者文档与 agent skills",
   "license": "UNLICENSED",
   "type": "module",