@newlandnpt/pep-cli 0.9.0-rc.2 → 0.9.0-rc.4

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

@@ -1176,6 +1176,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 +1195,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"
     ]
   }
 };
@@ -1834,6 +1843,17 @@ async function installGroup(dependencies, remote) {
   if (repos.length === 0) {
     dependencies.onProgress(`   ${group} lists no repositories \u2014 nothing to install.`);
   }
+  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}`);
+    dependencies.onProgress("     Nothing was deleted. If one of them blocks an install below,");
+    dependencies.onProgress("     `pep skills remove <repo>` drops it for good.");
+  }
   const installed = [];
   const failed = [];
   for (const [index, source] of repos.entries()) {
@@ -1846,13 +1866,7 @@ async function installGroup(dependencies, remote) {
       dependencies.onProgress(`   \u2717 ${source}: ${message}`);
     }
   }
-  return {
-    status: "installed",
-    group,
-    installed,
-    failed,
-    drifted: driftedFromGroup(dependencies.installedSources, repos, group)
-  };
+  return { status: "installed", group, installed, failed, drifted };
 }
 async function runSetup(dependencies) {
   dependencies.onProgress("\u2460 Signing in to PEP\u2026");
@@ -1922,9 +1936,74 @@ 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";
+  const bySource = new Map(dependencies.installed.map((one) => [one.source, one]));
+  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) } };
+  }
+  const repositories = repos.map((path) => {
+    const known = bySource.get(path);
+    return known === void 0 ? { path, state: "new", directory: dependencies.directoryFor(path) } : {
+      path,
+      state: "installed",
+      directory: known.directory,
+      ...known.commit !== void 0 ? { commit: known.commit } : {}
+    };
+  });
+  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.2";
+var VERSION = false ? "0.0.0-dev" : "0.9.0-rc.4";
 var SKILLS_ADD_DEPRECATION = "\u26A0 `pep skills add` will be removed in a future release.";
 function reportUpdate(result) {
   const conflicts = () => {
@@ -2108,12 +2187,14 @@ function reportSetup(report) {
       console.error(`  \u2717 ${source}: ${message}`);
     }
     if (skills.drifted.length > 0) {
-      console.error(`
-\u26A0 Still on your list, but no longer in ${skills.group}:`);
-      for (const source of skills.drifted) console.error(`    ${source}`);
-      console.error("  They were left in place \u2014 nothing was deleted. `pep skills update` will");
-      console.error("  report 404 for each of them (which reads exactly like a typo, but is not).");
-      console.error("  `pep skills remove <repo>` drops one for good.");
+      const n = skills.drifted.length;
+      console.error(
+        `
+\u26A0 ${n} ${n === 1 ? "repository" : "repositories"} on your list ${n === 1 ? "is" : "are"} no longer in ${skills.group} (listed above).`
+      );
+      console.error("  Nothing was deleted. `pep skills update` will report 404 for each of them");
+      console.error("  (which reads exactly like a typo, but is not). `pep skills remove <repo>`");
+      console.error("  drops one for good.");
     }
   }
   if (report.nexus.status === "skipped") {
@@ -2141,11 +2222,37 @@ 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 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, state?.packages[source]).directory
+      });
+      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` 要么抛、
@@ -2171,7 +2278,7 @@ async function main() {
       },
       // 漂移比对的另一半。取**这一趟开始前**的账 —— 装完再读的话，本轮刚装上的那些也在
       // 里头，而它们当然都还在群里，比出来一样，只是白读一遍。
-      installedSources: Object.keys(state?.packages ?? {}),
+      installed,
       skipNexus,
       setupNexus: (remote) => setupNexusCredential(remote),
       onProgress: (line) => console.error(line),

package/package.json

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