@newlandnpt/pep-cli 0.9.0-rc.3 → 0.9.0

package/README.md

@@ -77,6 +77,20 @@ pep setup --skip-skills                # only sign in and configure Maven
 pep setup group/sub -p                 # a different group, into THIS project
 ```
 
+### Seeing what a run would do
+
+```powershell
+pep setup --json
+```
+
+Prints the plan and **installs nothing**: which repositories the group holds right now, which of them
+are new, where each would land, and which entries on your list are no longer in the group — together
+with the skill names those occupy, which is what makes one block another. Useful before a first run,
+and when an install fails for a reason you would rather understand than guess at.
+
+It never opens a browser: with no valid sign-in it reports `"login": "required"` and exits non-zero.
+It does read the group, so it may refresh your token, exactly as `pep auth status` does.
+
 `--issuer`, `--client-id` and `--resource` work here exactly as on `pep auth login`, for pointing a
 run at another deployment:
 

package/dist/pep.cjs

@@ -4,6 +4,7 @@
 // src/auth-service.ts
 var import_promises2 = require("node:fs/promises");
 var import_node_path2 = require("node:path");
+var import_node_crypto2 = require("node:crypto");
 
 // src/config.ts
 var import_promises = require("node:fs/promises");
@@ -53,8 +54,18 @@ function defaultSkillsDirectory() {
 function claudeSkillsDirectory() {
   return (0, import_node_path.join)((0, import_node_os.homedir)(), ".claude", "skills");
 }
+function isStableDirectory(directory, api = {
+  isAbsolute: import_node_path.isAbsolute,
+  parse: import_node_path.parse,
+  sep: import_node_path.sep
+}) {
+  if (!api.isAbsolute(directory)) return false;
+  const root = api.parse(directory).root;
+  if (api.sep === "/") return true;
+  return root.length > 1;
+}
 function samePlace(a, b) {
-  return a.toLowerCase() === b.toLowerCase();
+  return (0, import_node_path.resolve)(a).toLowerCase() === (0, import_node_path.resolve)(b).toLowerCase();
 }
 function userSkillsTarget() {
   return { directory: defaultSkillsDirectory(), linkInto: claudeSkillsDirectory() };
@@ -294,12 +305,12 @@ async function waitForAuthorizationCallback(args) {
     throw new Error("CLI redirect URI must be an http://localhost URL with an explicit port.");
   }
   let server;
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const finish = (error, code) => {
       clearTimeout(timeout);
       server?.close();
       if (error) reject(error);
-      else resolve2(code);
+      else resolve4(code);
     };
     const timeout = setTimeout(
       () => finish(new Error("Login timed out while waiting for the browser callback.")),
@@ -342,7 +353,7 @@ async function waitForAuthorizationCallback(args) {
 function openBrowser(url) {
   const command = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
   const commandArgs = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = (0, import_node_child_process.spawn)(command, commandArgs, {
       detached: true,
       stdio: "ignore",
@@ -351,7 +362,7 @@ function openBrowser(url) {
     child.once("error", reject);
     child.once("spawn", () => {
       child.unref();
-      resolve2();
+      resolve4();
     });
   });
 }
@@ -462,7 +473,15 @@ var REFRESH_EARLY_MS = 60 * 1e3;
 var LOCK_STALE_MS = 30 * 1e3;
 var LOCK_WAIT_MS = 10 * 1e3;
 async function delay(milliseconds) {
-  await new Promise((resolve2) => setTimeout(resolve2, milliseconds));
+  await new Promise((resolve4) => setTimeout(resolve4, milliseconds));
+}
+async function releaseIfMine(path, stamp2) {
+  try {
+    if (await (0, import_promises2.readFile)(path, "utf8") !== stamp2) return;
+  } catch {
+    return;
+  }
+  await (0, import_promises2.unlink)(path).catch(() => void 0);
 }
 async function withAuthorizationLock(path, action) {
   await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
@@ -470,11 +489,13 @@ async function withAuthorizationLock(path, action) {
   while (true) {
     try {
       const handle = await (0, import_promises2.open)(path, "wx", 384);
+      const stamp2 = `${process.pid}:${(0, import_node_crypto2.randomUUID)()}`;
+      await handle.writeFile(stamp2, "utf8");
       try {
         return await action();
       } finally {
         await handle.close();
-        await (0, import_promises2.unlink)(path).catch(() => void 0);
+        await releaseIfMine(path, stamp2);
       }
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
@@ -542,17 +563,22 @@ function createAuthService(dependencies) {
         code,
         pkce.verifier
       );
-      const previous = await dependencies.credentialStore.read();
-      await dependencies.credentialStore.write(authorization);
-      await dependencies.configStore.write(normalized);
-      if (previous) {
-        try {
-          const previousDiscovery = await dependencies.oauth.discover(previous.issuer);
-          await dependencies.oauth.revoke(previousDiscovery, previous);
-        } catch {
+      return withAuthorizationLock(
+        dependencies.authorizationLockPath ?? lockPath(),
+        async () => {
+          const previous = await dependencies.credentialStore.read();
+          await dependencies.credentialStore.write(authorization);
+          await dependencies.configStore.write(normalized);
+          if (previous) {
+            try {
+              const previousDiscovery = await dependencies.oauth.discover(previous.issuer);
+              await dependencies.oauth.revoke(previousDiscovery, previous);
+            } catch {
+            }
+          }
+          return authorization;
         }
-      }
-      return authorization;
+      );
     },
     currentAuthorization,
     async status() {
@@ -581,6 +607,9 @@ function createAuthService(dependencies) {
   };
 }
 
+// src/cli.ts
+var import_node_path5 = require("node:path");
+
 // src/credential-store.ts
 var import_node_child_process2 = require("node:child_process");
 var CREDENTIAL_TARGET = "PEP CLI OAuth Tokens";
@@ -656,7 +685,7 @@ function encodedPowerShell(script) {
   return Buffer.from(script, "utf16le").toString("base64");
 }
 async function runPowerShell(script, input) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = (0, import_node_child_process2.spawn)(
       "powershell.exe",
       [
@@ -679,7 +708,7 @@ async function runPowerShell(script, input) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      if (code === 0) resolve2(stdout.trim());
+      if (code === 0) resolve4(stdout.trim());
       else
         reject(
           new Error(
@@ -700,14 +729,18 @@ function parseStoredAuthorization(raw) {
   }
   return candidate;
 }
+function psLiteral(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}
 function windowsCredentialStore(target = CREDENTIAL_TARGET) {
+  const quoted = psLiteral(target);
   const preamble = `Add-Type -TypeDefinition @'
 ${WINDOWS_CREDENTIAL_NATIVE}
 '@`;
   return {
     async read() {
       const script = `${preamble}
-$bytes = [PepCredential]::Read('${target}')
+$bytes = [PepCredential]::Read(${quoted})
 if ($null -ne $bytes) { [Convert]::ToBase64String($bytes) }`;
       const encoded = await runPowerShell(script);
       if (!encoded) return null;
@@ -718,18 +751,18 @@ if ($null -ne $bytes) { [Convert]::ToBase64String($bytes) }`;
     async write(authorization) {
       const script = `${preamble}
 $raw = [Console]::In.ReadToEnd()
-[PepCredential]::Write('${target}', 'oauth', [Text.Encoding]::UTF8.GetBytes($raw))`;
+[PepCredential]::Write(${quoted}, 'oauth', [Text.Encoding]::UTF8.GetBytes($raw))`;
       await runPowerShell(script, JSON.stringify(authorization));
     },
     async delete() {
       await runPowerShell(`${preamble}
-[PepCredential]::Delete('${target}')`);
+[PepCredential]::Delete(${quoted})`);
     }
   };
 }
 var SECURITY_NOT_FOUND = 44;
 async function runSecurity(args) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = (0, import_node_child_process2.spawn)("/usr/bin/security", [...args], {
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -744,7 +777,7 @@ async function runSecurity(args) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      resolve2({ code: code ?? -1, stdout, stderr });
+      resolve4({ code: code ?? -1, stdout, stderr });
     });
   });
 }
@@ -800,6 +833,45 @@ function systemCredentialStore() {
   );
 }
 
+// src/http.ts
+var HEADERS_TIMEOUT_MS = 15e3;
+function explainNetworkFailure(error, what, url) {
+  const host = (() => {
+    try {
+      return new URL(url).host;
+    } catch {
+      return url;
+    }
+  })();
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return new Error(
+      `${what}: ${host} did not respond within ${HEADERS_TIMEOUT_MS / 1e3}s. Check the network (VPN / proxy / firewall), then retry.`
+    );
+  }
+  const code = error?.cause?.code;
+  const hint = code === "ENOTFOUND" || code === "EAI_AGAIN" ? `${host} could not be resolved \u2014 check the address and your DNS.` : code === "ECONNREFUSED" ? `${host} refused the connection \u2014 it may be down, or you may need a VPN.` : code === "ECONNRESET" || code === "EPIPE" ? `the connection to ${host} was reset mid-flight. Retry; if it persists, suspect a proxy.` : typeof code === "string" && code.startsWith("CERT_") ? `${host} presented a certificate this machine does not trust (${code}).` : `could not reach ${host}${typeof code === "string" ? ` (${code})` : ""}.`;
+  return new Error(`${what}: ${hint}`);
+}
+async function fetchOrExplain(doFetch, url, init, what, timeoutMs = HEADERS_TIMEOUT_MS) {
+  const target = typeof url === "string" ? url : url.toString();
+  if (init.signal) {
+    try {
+      return await doFetch(url, init);
+    } catch (error) {
+      throw explainNetworkFailure(error, what, target);
+    }
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new DOMException("timed out", "TimeoutError")), timeoutMs);
+  try {
+    return await doFetch(url, { ...init, signal: controller.signal });
+  } catch (error) {
+    throw explainNetworkFailure(error, what, target);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/docs-service.ts
 var ENTRY = /^-\s*\[([^\]]*)\]\(([^)]+)\)(?::\s*(.*))?$/;
 function parseDocsIndex(text) {
@@ -845,9 +917,12 @@ function describeFailure(status, what) {
 }
 async function get(dependencies, path, accept) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
-  const response = await doFetch(`${dependencies.docsUrl.replace(/\/+$/, "")}${path}`, {
-    headers: { Authorization: `Bearer ${dependencies.accessToken}`, Accept: accept }
-  });
+  const response = await fetchOrExplain(
+    doFetch,
+    `${dependencies.docsUrl.replace(/\/+$/, "")}${path}`,
+    { headers: { Authorization: `Bearer ${dependencies.accessToken}`, Accept: accept } },
+    "Could not reach the documentation platform"
+  );
   if (!response.ok) {
     await response.body?.cancel();
     throw new Error(describeFailure(response.status, path));
@@ -966,7 +1041,10 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
       };
     }
   }
-  await (0, import_promises3.writeFile)(target.path, plan.content, "utf8");
+  const originalMode = await (0, import_promises3.stat)(target.path).then((info) => info.mode & 511).catch(() => 384);
+  const temporary = `${target.path}.${process.pid}.tmp`;
+  await (0, import_promises3.writeFile)(temporary, plan.content, { encoding: "utf8", mode: originalMode });
+  await (0, import_promises3.rename)(temporary, target.path);
   return plan.action === "replace" ? { status: "profile-replaced", path: target.path, backupPath } : { status: "profile-appended", path: target.path, ...backupPath ? { backupPath } : {} };
 }
 
@@ -1176,6 +1254,13 @@ never deleted. \`pep skills remove <repo>\` drops one for good.
 The group is baked into this build and is not remembered between runs: pass one
 to install from a different group, just for this run.
 
+--json prints what this run would do \u2014 which repositories the group holds, which
+of them are new, where each would land, and which entries on your list are no
+longer in the group (with the skill names they occupy, which is what makes one
+block another). It installs nothing, writes nothing and never opens a browser.
+It does need a valid sign-in to read the group, so it may refresh your token,
+exactly as \`pep auth status\` does.
+
 --issuer, --client-id and --resource are passed to step 1, exactly as on
 \`pep auth login\`, and are not remembered either. If you are already signed in to
 a different deployment, setup signs in again rather than silently using the one
@@ -1188,13 +1273,15 @@ replaces it \u2014 run \`pep auth login\` to go back.`,
       "--dir <path>       Install skills into this directory instead",
       `--issuer <url>     PEP server for this run (default: ${DEFAULT_ISSUER})`,
       "--client-id <id>   Registered OAuth client for this run",
+      "--json             Print what this run would do, install nothing",
       "--resource <uri>   Token audience; repeat for multiple resources"
     ],
     examples: [
       "pep setup",
       "pep setup --skip-nexus",
       `pep setup ${DEFAULT_SKILLS_GROUP} -p`,
-      "pep setup --issuer https://pep-dev.example --client-id <that deployment's id>"
+      "pep setup --issuer https://pep-dev.example --client-id <that deployment's id>",
+      "pep setup --json"
     ]
   }
 };
@@ -1301,13 +1388,18 @@ async function errorCodeOf(response) {
 }
 async function fetchNexusCredential(dependencies) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
-  const response = await doFetch(`${dependencies.issuer.replace(/\/+$/, "")}${CREDENTIAL_PATH}`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${dependencies.accessToken}`,
-      Accept: "application/json"
-    }
-  });
+  const response = await fetchOrExplain(
+    doFetch,
+    `${dependencies.issuer.replace(/\/+$/, "")}${CREDENTIAL_PATH}`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${dependencies.accessToken}`,
+        Accept: "application/json"
+      }
+    },
+    "Could not reach PEP for Maven credentials"
+  );
   if (!response.ok) {
     throw new Error(describeFailure2(response.status, await errorCodeOf(response)));
   }
@@ -1341,7 +1433,7 @@ async function setupNexusCredential(dependencies) {
 var import_promises4 = require("node:fs/promises");
 var import_node_os3 = require("node:os");
 var import_node_path4 = require("node:path");
-var import_node_crypto2 = require("node:crypto");
+var import_node_crypto3 = require("node:crypto");
 var import_node_zlib = require("node:zlib");
 
 // src/tar.ts
@@ -1392,6 +1484,9 @@ function readTar(bytes) {
     const size = readOctal(header, SIZE_OFFSET, SIZE_LENGTH);
     const type = String.fromCharCode(header[TYPE_OFFSET]);
     const dataStart = offset + BLOCK;
+    if (dataStart + size > bytes.length) {
+      throw new Error("Malformed archive: an entry extends past the end of the stream.");
+    }
     const data = bytes.subarray(dataStart, dataStart + size);
     offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
     if (type === "L") {
@@ -1429,6 +1524,11 @@ function tooBig(what, limit) {
   );
 }
 var SKILL_MANIFEST = "SKILL.md";
+function nameClash(owner, skill, directory) {
+  return new Error(
+    `${owner} already installs a skill named "${skill}" in ${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.`
+  );
+}
 function planSkillFiles(entries) {
   const roots = [];
   for (const entry of entries) {
@@ -1551,9 +1651,12 @@ async function listGroupRepos(dependencies) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
   const url = new URL(`${dependencies.issuer.replace(/\/+$/, "")}${GROUP_PATH}`);
   url.searchParams.set("path", dependencies.group);
-  const response = await doFetch(url, {
-    headers: { Authorization: `Bearer ${dependencies.accessToken}` }
-  });
+  const response = await fetchOrExplain(
+    doFetch,
+    url,
+    { headers: { Authorization: `Bearer ${dependencies.accessToken}` } },
+    "Could not list the skills group"
+  );
   if (!response.ok) {
     await response.body?.cancel();
     throw new Error(describeGroupFailure(response.status));
@@ -1561,8 +1664,8 @@ async function listGroupRepos(dependencies) {
   const raw = await readCapped(response, dependencies.maxListBytes ?? MAX_GROUP_LIST_BYTES);
   return parseGroupList(new TextDecoder().decode(raw));
 }
-function groupMemberPath(ledgerKey, group) {
-  let path = ledgerKey.trim();
+function repoIdentity(address) {
+  let path = address.trim();
   if (/^https?:\/\//i.test(path)) {
     try {
       path = new URL(path).pathname;
@@ -1570,13 +1673,22 @@ function groupMemberPath(ledgerKey, group) {
       return void 0;
     }
   }
-  path = (path.split("@")[0] ?? "").replace(/\.git$/i, "");
-  const segments = path.split("/").filter((one) => one !== "");
-  const groupSegments = group.split("/").filter((one) => one !== "");
-  if (groupSegments.length === 0 || segments.length <= groupSegments.length) return void 0;
-  const lower = segments.map((one) => one.toLowerCase());
-  if (!groupSegments.every((one, index) => one.toLowerCase() === lower[index])) return void 0;
-  return lower.join("/");
+  path = path.split("@")[0] ?? "";
+  const webRoute = path.indexOf("/-/");
+  if (webRoute !== -1) path = path.slice(0, webRoute);
+  path = path.replace(/\.git$/i, "");
+  const segments = path.split("/").filter((one) => one !== "").map((one) => one.toLowerCase());
+  return segments.length === 0 ? void 0 : segments.join("/");
+}
+function groupMemberPath(ledgerKey, group) {
+  const path = repoIdentity(ledgerKey);
+  const groupPath = repoIdentity(group);
+  if (path === void 0 || groupPath === void 0) return void 0;
+  const segments = path.split("/");
+  const groupSegments = groupPath.split("/");
+  if (segments.length <= groupSegments.length) return void 0;
+  if (!groupSegments.every((one, index) => one === segments[index])) return void 0;
+  return path;
 }
 async function physicalDir(path) {
   const absolute = (0, import_node_path4.resolve)(path);
@@ -1604,7 +1716,7 @@ async function linkSkill(canonicalSkillDir, linkPath) {
   }
 }
 function hashSkill(files) {
-  const hash = (0, import_node_crypto2.createHash)("sha256");
+  const hash = (0, import_node_crypto3.createHash)("sha256");
   for (const file of [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
     hash.update(file.path);
     hash.update("\0");
@@ -1619,12 +1731,20 @@ function otherClaimant(packages, self, directory, skill) {
     ([other, pkg]) => other !== self && samePlace(pkg.directory, directory) && Object.keys(pkg.skills).some((one) => one.toLowerCase() === wanted)
   )?.[0];
 }
+function deletableLedgerDirectory(directory) {
+  return isStableDirectory(directory) ? directory : void 0;
+}
 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.`);
   }
+  if (deletableLedgerDirectory(pkg.directory) === void 0) {
+    throw new Error(
+      `${name} was recorded with a relative install directory (${pkg.directory}) by an older pep-cli, so its real location is unknown \u2014 removing it here could delete files in the wrong project. Delete that directory yourself, then run \`pep skills add ${name}\` to re-record it with an absolute path.`
+    );
+  }
   const deleted = [];
   const keptForOthers = [];
   for (const skill of Object.keys(pkg.skills).sort()) {
@@ -1660,9 +1780,12 @@ async function updateSkills(dependencies) {
   const name = dependencies.source;
   const url = new URL(`${dependencies.issuer.replace(/\/+$/, "")}${ARCHIVE_PATH}`);
   url.searchParams.set("source", name);
-  const response = await doFetch(url, {
-    headers: { Authorization: `Bearer ${dependencies.accessToken}` }
-  });
+  const response = await fetchOrExplain(
+    doFetch,
+    url,
+    { headers: { Authorization: `Bearer ${dependencies.accessToken}` } },
+    "Could not download the skills archive"
+  );
   if (!response.ok) {
     await response.body?.cancel();
     throw new Error(describeFailure3(response.status));
@@ -1672,15 +1795,21 @@ async function updateSkills(dependencies) {
   const previous = state?.packages[name];
   const sameTarget = previous !== void 0 && samePlace(previous.directory, dependencies.directory) && (previous.linkedInto === void 0 ? dependencies.linkInto === void 0 : dependencies.linkInto !== void 0 && samePlace(previous.linkedInto, dependencies.linkInto));
   const claimedElsewhere = (skill) => otherClaimant(state?.packages ?? {}, name, dependencies.directory, skill);
-  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 previousSkills = Object.keys(previous?.skills ?? {});
+  const gone = previous !== void 0 && sameTarget ? await missingSkills(previous.directory, previousSkills) : /* @__PURE__ */ new Set();
+  const linksGone = dependencies.restoreMissing && previous !== void 0 && sameTarget && previous.linkedInto !== void 0 && dependencies.linkInto !== void 0 ? await missingSkills(previous.linkedInto, previousSkills) : /* @__PURE__ */ new Set();
+  const nothingToRestore = !dependencies.restoreMissing || gone.size === 0 && linksGone.size === 0;
   const standing = Object.keys(previous?.skills ?? {}).flatMap((skill) => {
     const owner = claimedElsewhere(skill);
     return owner ? [{ skill, owner }] : [];
   });
+  if (dependencies.restoreMissing && standing.length > 0) {
+    const [first] = standing;
+    throw nameClash(first.owner, first.skill, dependencies.directory);
+  }
   if (commit !== void 0 && commit === previous?.commit && sameTarget && nothingToRestore) {
     await response.body?.cancel();
-    return { status: "unchanged", name, commit, conflicts: standing };
+    return { status: "unchanged", name, commit, conflicts: standing, skipped: [...gone] };
   }
   const gzipped = await readCapped(response, dependencies.maxArchiveBytes ?? MAX_ARCHIVE_BYTES);
   let unpacked;
@@ -1712,11 +1841,7 @@ async function updateSkills(dependencies) {
   for (const skill of candidates) {
     const owner = claimedElsewhere(skill);
     if (owner === void 0) continue;
-    if (dependencies.restoreMissing) {
-      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.`
-      );
-    }
+    if (dependencies.restoreMissing) throw nameClash(owner, skill, dependencies.directory);
     conflicts.push({ skill, owner });
   }
   const skills = candidates.filter((skill) => !conflicts.some((one) => one.skill === skill));
@@ -1736,7 +1861,9 @@ async function updateSkills(dependencies) {
     const stale = sameTarget ? removed : Object.keys(previous.skills);
     for (const skill of stale) {
       if (otherClaimant(state?.packages ?? {}, name, previous.directory, skill)) continue;
-      await (0, import_promises4.rm)((0, import_node_path4.join)(previous.directory, skill), { recursive: true, force: true });
+      const stalePlace = deletableLedgerDirectory(previous.directory);
+      if (stalePlace === void 0) continue;
+      await (0, import_promises4.rm)((0, import_node_path4.join)(stalePlace, 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 });
       }
@@ -1821,11 +1948,11 @@ function driftedFromGroup(installedSources, groupRepos, group) {
     return member !== void 0 && !present.has(member);
   }).sort();
 }
-async function installGroup(dependencies, remote) {
+async function installGroup(dependencies, remoteNow) {
   const group = dependencies.group;
   let repos;
   try {
-    repos = await dependencies.listGroupRepos(remote);
+    repos = await dependencies.listGroupRepos(await remoteNow());
   } catch (error) {
     const message = messageOf(error);
     dependencies.onProgress(`   \u2717 ${message}`);
@@ -1834,7 +1961,11 @@ async function installGroup(dependencies, remote) {
   if (repos.length === 0) {
     dependencies.onProgress(`   ${group} lists no repositories \u2014 nothing to install.`);
   }
-  const drifted = driftedFromGroup(dependencies.installedSources, repos, group);
+  const drifted = driftedFromGroup(
+    dependencies.installed.map((one) => one.source),
+    repos,
+    group
+  );
   if (drifted.length > 0) {
     dependencies.onProgress(`   \u26A0 On your list but no longer in ${group}:`);
     for (const source of drifted) dependencies.onProgress(`       ${source}`);
@@ -1846,7 +1977,7 @@ async function installGroup(dependencies, remote) {
   for (const [index, source] of repos.entries()) {
     dependencies.onProgress(`   [${index + 1}/${repos.length}] ${source}`);
     try {
-      installed.push({ source, ...await dependencies.installSkills(remote, source) });
+      installed.push({ source, ...await dependencies.installSkills(await remoteNow(), source) });
     } catch (error) {
       const message = messageOf(error);
       failed.push({ source, message });
@@ -1886,15 +2017,17 @@ async function runSetup(dependencies) {
     login = { alreadySignedIn: false, account };
     dependencies.onProgress(`   Signed in as ${account}.`);
   }
-  const authorization = signedIn?.authorization ?? await dependencies.auth.currentAuthorization();
-  const remote = { issuer: authorization.issuer, accessToken: authorization.accessToken };
+  const remoteNow = async () => {
+    const authorization = await dependencies.auth.currentAuthorization();
+    return { issuer: authorization.issuer, accessToken: authorization.accessToken };
+  };
   let skills;
   if (dependencies.skipSkills) {
     skills = { status: "skipped", reason: "--skip-skills" };
     dependencies.onProgress("\u2461 Installing skills\u2026 skipped (--skip-skills).");
   } else {
     dependencies.onProgress(`\u2461 Listing skills repositories in ${dependencies.group}\u2026`);
-    skills = await installGroup(dependencies, remote);
+    skills = await installGroup(dependencies, remoteNow);
   }
   let nexus;
   if (dependencies.skipNexus) {
@@ -1903,7 +2036,7 @@ async function runSetup(dependencies) {
   } else {
     dependencies.onProgress("\u2462 Setting up Maven credentials\u2026");
     try {
-      nexus = { status: "done", result: await dependencies.setupNexus(remote) };
+      nexus = { status: "done", result: await dependencies.setupNexus(await remoteNow()) };
     } catch (error) {
       nexus = { status: "failed", message: messageOf(error) };
       dependencies.onProgress(`   \u2717 ${nexus.message}`);
@@ -1923,9 +2056,79 @@ function setupFailureSummary(report) {
   if (failed.length === 0) return void 0;
   return `Setup finished with problems: ${failed.join(", ")} did not complete.`;
 }
+async function planSetup(dependencies) {
+  const group = dependencies.group;
+  const nexus = dependencies.skipNexus ? "skipped" : "planned";
+  let current;
+  try {
+    current = await dependencies.auth.status();
+  } catch {
+  }
+  if (current === void 0) {
+    return {
+      group,
+      issuer: null,
+      account: null,
+      login: "required",
+      skills: { status: "unavailable", reason: "not signed in \u2014 run `pep auth login` first" },
+      nexus
+    };
+  }
+  const issuer = current.authorization.issuer;
+  if (dependencies.requestedIssuer !== void 0 && !sameIssuer(issuer, dependencies.requestedIssuer)) {
+    return {
+      group,
+      issuer,
+      account: accountOf(current.user),
+      login: "different-deployment",
+      skills: {
+        status: "unavailable",
+        reason: `signed in to ${issuer}, but --issuer names ${dependencies.requestedIssuer}; a real run would sign in again first`
+      },
+      nexus
+    };
+  }
+  const plan = {
+    group,
+    issuer,
+    account: accountOf(current.user),
+    login: "reuse",
+    nexus
+  };
+  if (dependencies.skipSkills) {
+    return { ...plan, skills: { status: "skipped", reason: "--skip-skills" } };
+  }
+  let repos;
+  try {
+    repos = await dependencies.listGroupRepos({
+      issuer,
+      accessToken: current.authorization.accessToken
+    });
+  } catch (error) {
+    return { ...plan, skills: { status: "unavailable", reason: messageOf(error) } };
+  }
+  let repositories;
+  try {
+    repositories = repos.map((path) => {
+      const known = dependencies.recordFor(path);
+      const directory = dependencies.directoryFor(path);
+      return known === void 0 ? { path, state: "new", directory } : {
+        path,
+        state: "installed",
+        directory,
+        ...known.commit !== void 0 ? { commit: known.commit } : {}
+      };
+    });
+  } catch (error) {
+    return { ...plan, skills: { status: "unavailable", reason: messageOf(error) } };
+  }
+  const gone = new Set(driftedFromGroup(dependencies.installed.map((one) => one.source), repos, group));
+  const drifted = dependencies.installed.filter((one) => gone.has(one.source));
+  return { ...plan, skills: { status: "planned", repositories, drifted } };
+}
 
 // src/cli.ts
-var VERSION = false ? "0.0.0-dev" : "0.9.0-rc.3";
+var VERSION = false ? "0.0.0-dev" : "0.9.0";
 var SKILLS_ADD_DEPRECATION = "\u26A0 `pep skills add` will be removed in a future release.";
 function reportUpdate(result) {
   const conflicts = () => {
@@ -1934,8 +2137,14 @@ function reportUpdate(result) {
       console.error(`    each other. \`pep skills remove\` one of them to settle it.`);
     }
   };
+  const skipped = (list, name) => {
+    if (list.length === 0) return;
+    console.log(`  deleted locally, left alone: ${list.join(" ")}`);
+    console.log(`  (\`pep skills add ${name}\` puts them back)`);
+  };
   if (result.status === "unchanged") {
     console.log(`${result.name}: already at ${result.commit}. Nothing to do.`);
+    skipped(result.skipped, result.name);
     conflicts();
     return;
   }
@@ -1945,10 +2154,7 @@ 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)`);
-  }
+  skipped(result.skipped, result.name);
   conflicts();
   console.log(`  ${result.fileCount} file(s) in ${result.directory}`);
   if (result.linkedInto !== void 0) {
@@ -2039,17 +2245,52 @@ function parseSkillsArgs(command, args, cwd) {
   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;
+  const chosenTarget = explicitDirectory !== void 0 ? (
+    // ⚠ **立刻转成绝对路径**，相对路径绝不能进账本。
+    //   账上记的落点会在**另一个工作目录**下被重新使用（`targetForSource` 的中间那一档）：
+    //   A 项目里 `--dir ./skills` 存下字面量 `./skills`，到 B 项目再跑，它就指向 B 的
+    //   `./skills` —— 写进去是覆盖别人的文件，换落点清理和 `remove` 那两条路更是直接
+    //   `rm -rf` 到 B 头上。`--project` 没有这个问题，因为它走 `join(cwd, …)`。
+    //   基准用 `cwd` 而不是 `process.cwd()`：与同一处的 `projectSkillsTarget(cwd)` 同源，
+    //   也让这条分支可测。
+    { directory: (0, import_node_path5.resolve)(cwd ?? process.cwd(), explicitDirectory) }
+  ) : project ? projectSkillsTarget(cwd) : void 0;
   return { ...requested !== void 0 ? { requested } : {}, named, ...chosenTarget ? { chosenTarget } : {} };
 }
-function targetForSource(chosen, recorded) {
+async function readLedger(store, skipSkills, warn) {
+  try {
+    return await store.read();
+  } catch (error) {
+    if (!skipSkills) throw error;
+    const detail = error instanceof Error ? error.message : String(error);
+    warn(`   \u26A0 Could not read the skills ledger (${detail}). Continuing because --skip-skills was given.`);
+    return null;
+  }
+}
+function targetForSource(chosen, recorded, source = "this repository") {
   if (chosen) return chosen;
   if (!recorded) return userSkillsTarget();
+  if (!isStableDirectory(recorded.directory)) {
+    throw new Error(
+      `${source} was recorded with a relative install directory (${recorded.directory}) by an older pep-cli, so its real location depends on where you run this from \u2014 continuing could overwrite files in the current project. Pass --dir <absolute path> (or --project) to say where it belongs, or run \`pep skills remove\` on it first.`
+    );
+  }
   return {
     directory: recorded.directory,
     ...recorded.linkedInto !== void 0 ? { linkInto: recorded.linkedInto } : {}
   };
 }
+function recordedFor(packages, source) {
+  if (!packages) return void 0;
+  const exact = packages[source];
+  if (exact !== void 0) return { key: source, pkg: exact };
+  const wanted = repoIdentity(source);
+  if (wanted === void 0) return void 0;
+  for (const [key, pkg] of Object.entries(packages)) {
+    if (repoIdentity(key) === wanted) return { key, pkg };
+  }
+  return void 0;
+}
 function nexusReport(result, printEnv) {
   const stdout = printEnv ? [result.lines] : [];
   const stderr = [];
@@ -2144,11 +2385,41 @@ async function main() {
     const skipNexus = flag(args, "--skip-nexus");
     const skipSkills = flag(args, "--skip-skills");
     const loginOptions = takeLoginOptions(args);
+    const wantsJson = flag(args, "--json");
     const { requested, chosenTarget } = parseSkillsArgs("setup", args);
     const skillsGroup = requested ?? DEFAULT_SKILLS_GROUP;
     const { configStore: configStore2, auth: auth2 } = createCliServices();
     const stateStore = fileSkillsStateStore();
-    const state = await stateStore.read();
+    const state = await readLedger(stateStore, skipSkills, (line) => console.error(line));
+    const installed = Object.entries(state?.packages ?? {}).map(([source, pkg]) => ({
+      source,
+      directory: pkg.directory,
+      skills: Object.keys(pkg.skills).sort(),
+      ...pkg.commit !== void 0 ? { commit: pkg.commit } : {}
+    }));
+    if (wantsJson) {
+      const plan = await planSetup({
+        auth: auth2,
+        ...issuerOf(loginOptions) !== void 0 ? { requestedIssuer: issuerOf(loginOptions) } : {},
+        group: skillsGroup,
+        skipSkills,
+        skipNexus,
+        listGroupRepos: (remote) => listGroupRepos({ ...remote, group: skillsGroup }),
+        installed,
+        // ⚠ 与真跑**同一条推导**（`targetForSource`）：干跑报的落点要是和真跑落的地方
+        // 不一样，那它比没有还坏。
+        directoryFor: (source) => targetForSource(chosenTarget, recordedFor(state?.packages, source)?.pkg, source).directory,
+        // ⚠ 与真跑**共用同一个查账函数**。干跑自己再建一份索引的话，两边的重复键策略会分叉
+        //   （Map 是后者覆盖，`recordedFor` 是精确优先），于是预览的落点与 commit 可能来自
+        //   账上两条不同的记录。
+        recordFor: (source) => recordedFor(state?.packages, source)?.pkg
+      });
+      console.log(JSON.stringify(plan, null, 2));
+      if (plan.skills.status === "unavailable") {
+        throw new Error(`--json could not plan the skills step: ${plan.skills.reason}`);
+      }
+      return;
+    }
     const report = await runSetup({
       auth: auth2,
       // ⚠ 传 `loginOptions` 而不是 `args`：后者到这里**恒为空**（`parseSkillsArgs` 要么抛、
@@ -2160,10 +2431,12 @@ async function main() {
       skipSkills,
       listGroupRepos: (remote) => listGroupRepos({ ...remote, group: skillsGroup }),
       installSkills: async (remote, source) => {
-        const target = targetForSource(chosenTarget, state?.packages[source]);
+        const recorded = recordedFor(state?.packages, source);
+        const target = targetForSource(chosenTarget, recorded?.pkg, source);
         const result = await updateSkills({
           ...remote,
-          source,
+          // 原键还回去 —— 更新那一行，而不是按裸路径另起一条。
+          source: recorded?.key ?? source,
           directory: target.directory,
           ...target.linkInto !== void 0 ? { linkInto: target.linkInto } : {},
           // `add` 那一档的语义：盘上被删掉的那些由它补回来（`update` 不管）。
@@ -2174,7 +2447,7 @@ async function main() {
       },
       // 漂移比对的另一半。取**这一趟开始前**的账 —— 装完再读的话，本轮刚装上的那些也在
       // 里头，而它们当然都还在群里，比出来一样，只是白读一遍。
-      installedSources: Object.keys(state?.packages ?? {}),
+      installed,
       skipNexus,
       setupNexus: (remote) => setupNexusCredential(remote),
       onProgress: (line) => console.error(line),
@@ -2319,7 +2592,7 @@ ${usage(VERSION, ["skills"])}`);
       console.error(SKILLS_ADD_DEPRECATION);
       await run2(
         requested,
-        targetForSource(chosenTarget, state?.packages[requested]),
+        targetForSource(chosenTarget, state?.packages[requested], requested),
         true
       );
       return;
@@ -2350,7 +2623,7 @@ ${usage(VERSION, ["skills"])}`);
       console.error(`Not installed in ${chosenTarget?.directory}, skipped: ${skipped.join(" ")}`);
     }
     for (const source of targets) {
-      await run2(source, targetForSource(void 0, state?.packages[source]));
+      await run2(source, targetForSource(void 0, state?.packages[source], source));
     }
     return;
   }

package/package.json

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