@newlandnpt/pep-cli 0.3.1 → 0.4.1

package/README.md

@@ -83,6 +83,64 @@ departments to use now.
 back to `production` and publish immediately once that endpoint is live**: the issuer is baked in
 at build time, so releases already out in the wild cannot be repointed.
 
+## Skills
+
+```powershell
+pep skills add https://git.newlandpayment.com/group/sub/project   # or group/sub/project[@ref]
+pep skills list
+pep skills update                                                 # all of them
+pep skills update group/sub/project                               # just this one
+pep skills add group/sub/project -p                               # into THIS project
+```
+
+PEP fetches the repository with its own read-only service account, so no GitLab credential ever
+reaches the machine. Only repositories on the platform's own GitLab host are accepted. One
+repository may hold several skills: every directory containing a `SKILL.md` becomes one, and
+`update` reports which of them actually changed rather than just that the repository moved.
+
+### Where skills are installed
+
+| Scope       | Flag        | Canonical copy            | Linked into                |
+| ----------- | ----------- | ------------------------- | -------------------------- |
+| **Personal**| (default)   | `~/.agents/skills/`       | `~/.claude/skills/`        |
+| **Project** | `-p`, `--project` | `./.agents/skills/`       | `./.claude/skills/`        |
+| **Raw**     | `--dir <p>` | `<p>/`                    | nothing — linking skipped  |
+
+`~/.agents/skills` is the cross-agent convention that Codex, Cursor, Amp and ~20 others read
+directly; Claude Code keeps its own directory, so each skill is also linked there — one copy on
+disk, updated in one place. The project paths are the same two names rooted at the current
+directory, matching what `npx skills` installs at project scope.
+
+Personal is the default because the project directories get committed: whether a synced skill
+counts as a change, and whether to gitignore it, is a question every repository would otherwise
+have to answer. Use `-p` when the skills genuinely belong to one repository.
+
+**The location is remembered per repository.** `pep skills update` refreshes each repository where
+it already lives, and never moves anything.
+
+On `update`, `-p` and `--dir` **narrow the run** rather than relocate — the same meaning they have
+in `npx skills`:
+
+```powershell
+pep skills update          # every repository, each where it lives
+pep skills update -p       # only the ones installed in this project
+```
+
+If the current project has none, `update -p` says so and does nothing. **To move a repository, add
+it again with the new flag** — `add` is where the location is decided, and the copy in the old
+location is then removed:
+
+```powershell
+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.
+
 `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
 credential atomically.

package/dist/pep.cjs

@@ -51,6 +51,15 @@ function defaultSkillsDirectory() {
 function claudeSkillsDirectory() {
   return (0, import_node_path.join)((0, import_node_os.homedir)(), ".claude", "skills");
 }
+function userSkillsTarget() {
+  return { directory: defaultSkillsDirectory(), linkInto: claudeSkillsDirectory() };
+}
+function projectSkillsTarget(cwd = process.cwd()) {
+  return {
+    directory: (0, import_node_path.join)(cwd, ".agents", "skills"),
+    linkInto: (0, import_node_path.join)(cwd, ".claude", "skills")
+  };
+}
 function isCliConfig(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
@@ -82,6 +91,16 @@ function fileConfigStore(path = configPath()) {
   };
 }
 function isSkillsState(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (candidate.version !== 4) return false;
+  return isPackageMap(candidate.packages, (skills, pkg) => {
+    if (typeof pkg.directory !== "string") return false;
+    if (pkg.linkedInto !== void 0 && typeof pkg.linkedInto !== "string") return false;
+    return isStringMap(skills);
+  });
+}
+function isSkillsStateV3(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
   if (candidate.version !== 3) return false;
@@ -110,7 +129,7 @@ function isPackageMap(value, skillsOk) {
   return Object.values(value).every((one) => {
     if (typeof one !== "object" || one === null || Array.isArray(one)) return false;
     const pkg = one;
-    return skillsOk(pkg.skills) && (pkg.commit === void 0 || typeof pkg.commit === "string");
+    return skillsOk(pkg.skills, pkg) && (pkg.commit === void 0 || typeof pkg.commit === "string");
   });
 }
 function isStringMap(value) {
@@ -118,29 +137,34 @@ function isStringMap(value) {
   return Object.values(value).every((one) => typeof one === "string");
 }
 function migrateSkillsState(old) {
-  const base = {
-    version: 3,
+  const where = {
     directory: old.directory,
     ...old.linkedInto !== void 0 ? { linkedInto: old.linkedInto } : {}
   };
   const unknownHashes = (names) => Object.fromEntries(names.map((name) => [name, ""]));
   if (old.version === 1) {
     return {
-      ...base,
+      version: 4,
       packages: {
         [LEGACY_PACKAGE]: {
           ...old.commit !== void 0 ? { commit: old.commit } : {},
+          ...where,
           skills: unknownHashes(old.skills)
         }
       }
     };
   }
   return {
-    ...base,
+    version: 4,
     packages: Object.fromEntries(
       Object.entries(old.packages).map(([source, pkg]) => [
         source,
-        { ...pkg.commit !== void 0 ? { commit: pkg.commit } : {}, skills: unknownHashes(pkg.skills) }
+        {
+          ...pkg.commit !== void 0 ? { commit: pkg.commit } : {},
+          ...where,
+          // v2 的 `skills` 是名字数组（哈希未知），v3 的已经是「名字 → 真哈希」。
+          skills: Array.isArray(pkg.skills) ? unknownHashes(pkg.skills) : pkg.skills
+        }
       ])
     )
   };
@@ -151,7 +175,8 @@ function fileSkillsStateStore(path = skillsStatePath()) {
       try {
         const parsed = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
         if (isSkillsState(parsed)) return parsed;
-        if (isSkillsStateV2(parsed) || isSkillsStateV1(parsed)) return migrateSkillsState(parsed);
+        if (isSkillsStateV3(parsed) || isSkillsStateV2(parsed) || isSkillsStateV1(parsed))
+          return migrateSkillsState(parsed);
         return null;
       } catch (error) {
         if (error.code === "ENOENT") return null;
@@ -1170,6 +1195,15 @@ 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;
+    }
+  }
+  return true;
+}
 async function updateSkills(dependencies) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
   const name = dependencies.source;
@@ -1185,7 +1219,9 @@ async function updateSkills(dependencies) {
   const commit = response.headers.get("x-skills-commit") ?? void 0;
   const state = await dependencies.stateStore.read();
   const previous = state?.packages[name];
-  if (commit !== void 0 && commit === previous?.commit && state?.directory === dependencies.directory) {
+  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) {
     await response.body?.cancel();
     return { status: "unchanged", name, commit };
   }
@@ -1208,6 +1244,16 @@ async function updateSkills(dependencies) {
     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));
+  if (previous !== void 0) {
+    const stale = sameTarget ? removed : Object.keys(previous.skills);
+    for (const skill of stale) {
+      await (0, import_promises4.rm)((0, import_node_path4.join)(previous.directory, skill), { recursive: true, force: true });
+      if (previous.linkedInto !== void 0) {
+        await (0, import_promises4.rm)((0, import_node_path4.join)(previous.linkedInto, skill), { recursive: true, force: true });
+      }
+    }
+  }
   for (const skill of skills) {
     await (0, import_promises4.rm)((0, import_node_path4.join)(dependencies.directory, skill), { recursive: true, force: true });
   }
@@ -1226,24 +1272,18 @@ async function updateSkills(dependencies) {
       if (how === "copied") copiedCount += 1;
     }
   }
-  const removed = Object.keys(previous?.skills ?? {}).filter((skill) => !skills.includes(skill));
-  for (const skill of removed) {
-    await (0, import_promises4.rm)((0, import_node_path4.join)(state?.directory ?? dependencies.directory, skill), {
-      recursive: true,
-      force: true
-    });
-    if (state?.linkedInto !== void 0) {
-      await (0, import_promises4.rm)((0, import_node_path4.join)(state.linkedInto, skill), { recursive: true, force: true });
-    }
-  }
   await dependencies.stateStore.write({
-    version: 3,
-    directory: dependencies.directory,
-    ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
+    version: 4,
     packages: {
       // 别的包的账原样留着 —— 装 B 不该把 A 的记录抹掉，那会让 A 铺的目录从此没人清理。
+      // v4 起每个包各记各的落点，所以这一份合并不会再把别人的落点带歪。
       ...state?.packages ?? {},
-      [name]: { ...commit ? { commit } : {}, skills: hashes }
+      [name]: {
+        ...commit ? { commit } : {},
+        directory: dependencies.directory,
+        ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
+        skills: hashes
+      }
     }
   });
   return {
@@ -1260,13 +1300,9 @@ async function updateSkills(dependencies) {
     ...commit ? { commit } : {}
   };
 }
-async function installedPackages(store) {
-  const state = await store.read();
-  return Object.keys(state?.packages ?? {}).sort();
-}
 
 // src/cli.ts
-var VERSION = "0.3.0";
+var VERSION = false ? "0.0.0-dev" : "0.4.1";
 function usage() {
   return `PEP CLI ${VERSION}
 
@@ -1276,8 +1312,8 @@ Usage:
   pep auth token
   pep auth logout
   pep skills list
-  pep skills add <repo-url | group/project[@ref]> [--dir <path>]
-  pep skills update [<repo>...] [--dir <path>]
+  pep skills add <repo-url | group/project[@ref]> [-p | --dir <path>]
+  pep skills update [<repo>...] [-p | --dir <path>]
   pep docs list [--docs-url <url>]
   pep docs get <path> [--docs-url <url>]
   pep nexus setup
@@ -1309,9 +1345,21 @@ directly. Claude Code keeps its own directory, so each skill is also linked into
 ${claudeSkillsDirectory()} \u2014 one copy on disk, updated in one place. Where links are not
 available the skill is copied instead and the run says so.
 
+-p, --project installs into the CURRENT PROJECT instead: ./.agents/skills plus the same link into
+./.claude/skills. Use it when the skills belong to one repository and should be committed with
+it; note both directories then show up in git status, which is why the personal location is the
+default.
+
 --dir <path> writes to that path ONLY and skips the linking, for an agent that reads neither
-directory. Either way sync only touches skills it wrote itself; anything you put there by
-hand is left alone.
+directory.
+
+Where a repository was installed is remembered, so \`pep skills update\` refreshes each one where
+it already lives and never moves anything. On update, -p and --dir instead NARROW the run to the
+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 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
@@ -1359,6 +1407,16 @@ function repeatedOption(args, name) {
     args.splice(index, 2);
   }
 }
+function flag(args, ...names) {
+  let found = false;
+  for (const name of names) {
+    for (let index = args.indexOf(name); index !== -1; index = args.indexOf(name)) {
+      args.splice(index, 1);
+      found = true;
+    }
+  }
+  return found;
+}
 function option(args, name) {
   const index = args.indexOf(name);
   if (index === -1) return void 0;
@@ -1383,6 +1441,33 @@ async function loginConfig(args, store = fileConfigStore()) {
     ...saved?.docsUrl !== void 0 ? { docsUrl: saved.docsUrl } : {}
   };
 }
+function parseSkillsArgs(command, args, cwd) {
+  const explicitDirectory = command === "list" ? void 0 : option(args, "--dir");
+  const project = command === "list" ? 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;
+  if (command === "add" && !requested) {
+    throw new Error("pep skills add needs a repository: a full https URL, or <group>/<project>.");
+  }
+  const named = command === "update" ? [...args] : [];
+  if (command !== "update" && args.length > 0) {
+    throw new Error(`Unexpected argument: ${args[0]}`);
+  }
+  const chosenTarget = explicitDirectory !== void 0 ? { directory: explicitDirectory } : project ? projectSkillsTarget(cwd) : void 0;
+  return { ...requested !== void 0 ? { requested } : {}, named, ...chosenTarget ? { chosenTarget } : {} };
+}
+function targetForSource(chosen, recorded) {
+  if (chosen) return chosen;
+  if (!recorded) return userSkillsTarget();
+  return {
+    directory: recorded.directory,
+    ...recorded.linkedInto !== void 0 ? { linkInto: recorded.linkedInto } : {}
+  };
+}
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -1472,31 +1557,39 @@ ${usage()}`);
 
 ${usage()}`);
     }
-    const requested = command === "add" ? args.shift() : void 0;
-    const named = command === "update" ? args.filter((one) => !one.startsWith("--")) : [];
-    for (const one of named) args.splice(args.indexOf(one), 1);
-    if (command === "add" && !requested) {
-      throw new Error("pep skills add needs a repository: a full https URL, or <group>/<project>.");
-    }
-    const explicitDirectory = command === "list" ? void 0 : option(args, "--dir");
-    const directory = explicitDirectory ?? defaultSkillsDirectory();
-    if (args.length > 0) throw new Error(`Unknown option: ${args[0]}`);
+    const { requested, named, chosenTarget } = parseSkillsArgs(command, args);
     const authorization = await auth.currentAuthorization();
     const remote = { issuer: authorization.issuer, accessToken: authorization.accessToken };
     if (command === "list") {
-      const installed2 = await installedPackages(fileSkillsStateStore());
-      if (installed2.length === 0) {
+      const listed = await fileSkillsStateStore().read();
+      const packages = Object.entries(listed?.packages ?? {}).sort(
+        ([a], [b]) => a.localeCompare(b)
+      );
+      if (packages.length === 0) {
         console.error("Nothing added yet. Run `pep skills add <repo>`.");
         return;
       }
-      for (const one of installed2) console.log(one);
-      console.error("\n`pep skills update` refreshes all of them.");
+      for (const [source, pkg] of packages) console.log(`${source}	${pkg.directory}`);
+      console.error("\n`pep skills update` refreshes all of them, each where it lives.");
       return;
     }
     const stateStore = fileSkillsStateStore();
-    const installed = await installedPackages(stateStore);
-    const targets = command === "add" ? [requested] : named.length > 0 ? named : installed;
-    if (targets.length === 0) {
+    const state = await stateStore.read();
+    const installed = Object.keys(state?.packages ?? {}).sort();
+    const run2 = async (source, target) => reportUpdate(
+      await updateSkills({
+        ...remote,
+        source,
+        directory: target.directory,
+        ...target.linkInto !== void 0 ? { linkInto: target.linkInto } : {},
+        stateStore
+      })
+    );
+    if (command === "add") {
+      await run2(requested, targetForSource(chosenTarget, state?.packages[requested]));
+      return;
+    }
+    if (installed.length === 0) {
       console.error("Nothing added yet. Run `pep skills add <repo>`.");
       return;
     }
@@ -1506,15 +1599,20 @@ ${usage()}`);
         `Not added yet: ${unknown.join(" ")}. Run \`pep skills add <repo>\` first, or \`pep skills list\` to see what is.`
       );
     }
+    const wanted = named.length > 0 ? named : installed;
+    const targets = chosenTarget ? wanted.filter((one) => state?.packages[one]?.directory === chosenTarget.directory) : wanted;
+    if (targets.length === 0) {
+      console.error(`No skills are installed in ${chosenTarget?.directory}.`);
+      console.error("`pep skills update` (no flag) refreshes every repository where it lives;");
+      console.error("`pep skills add <repo> -p` installs one into this project.");
+      return;
+    }
+    const skipped = wanted.filter((one) => !targets.includes(one));
+    if (skipped.length > 0) {
+      console.error(`Not installed in ${chosenTarget?.directory}, skipped: ${skipped.join(" ")}`);
+    }
     for (const source of targets) {
-      const result = await updateSkills({
-        ...remote,
-        source,
-        directory,
-        ...explicitDirectory === void 0 ? { linkInto: claudeSkillsDirectory() } : {},
-        stateStore
-      });
-      reportUpdate(result);
+      await run2(source, targetForSource(void 0, state?.packages[source]));
     }
     return;
   }

package/package.json

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