@newlandnpt/pep-cli 0.8.1 → 0.9.0-rc.1

package/README.md

@@ -52,8 +52,66 @@ node scripts/oauth-bootstrap.mjs --client --public \
 If one PEP deployment serves multiple customer tenants, register a distinct client ID for each tenant
 and pass it with `--client-id`.
 
+## First run
+
+```powershell
+pep setup
+```
+
+Runs the three first-run steps in order — sign in, install the integration guide skills, configure
+Maven credentials — and **skips what is already done**.
+
+Step 2 installs **every skills repository in a group**. It asks the platform which repositories that
+group holds right now, then installs each one, so a new skills repository reaches everybody without
+a CLI release. A repository that fails does not stop the others: the command reports how many went
+in, which ones did not, and exits non-zero.
+
+Steps 2 and 3 are independent: if one fails the other still runs, and the command names which ones
+did not complete (and exits non-zero). Every step is idempotent, so running it again is safe — that
+is the intended way to recover from a partial run.
+
+```powershell
+pep setup                              # all three steps
+pep setup --skip-nexus                 # skip Maven (only Android needs it)
+pep setup --skip-skills                # only sign in and configure Maven
+pep setup group/sub -p                 # a different group, into THIS project
+```
+
+The integration guide **group** is baked in at build time (currently `distribution/skills`). Passing
+one overrides it **for that run only** — it is deliberately not remembered, unlike `--docs-url`.
+Where each repository installs *is* remembered, in the local ledger, so `pep skills update` later
+returns each one to the same place.
+
+If a repository you installed earlier has since left the group, `pep setup` says so and **leaves it
+alone** — nothing on your disk is deleted. It stays in the ledger, so `pep skills update` will report
+404 for it (which reads exactly like a typo, but is not). `pep skills remove <repo>` drops it for
+good.
+
+Step 3 needs a contract that includes Maven repository access (`ADMIN`, `US-ISO`, `US-ISV`); other
+contracts get a 403 there, which is why it fails softly rather than aborting the run. It also never
+prints the password — run `pep nexus setup --print-env` yourself if you need that.
+
+Each step's own command still exists and does exactly the same thing; `pep setup` only chains them.
+
 ## Use
 
+Use `--help` (or `-h`) at any level for the relevant commands, purpose, flags and examples:
+
+```powershell
+pep --help
+pep setup --help
+pep auth --help
+pep auth login --help
+pep docs get --help
+pep skills add --help
+pep skills update --help
+pep nexus setup --help
+```
+
+`pep help auth login` is equivalent to `pep auth login --help`. Help is available without
+logging in and does not access credentials or contact any service. The `pep-cli` alias supports
+the same commands.
+
 ```powershell
 pep auth login
 pep auth status
@@ -86,6 +144,9 @@ pep auth login --issuer https://pep-webapp-dev.onrender.com --client-id <that de
 
 ## Skills
 
+> **`pep skills add` will be removed in a future release.** It still works and behaves exactly as
+> before; using it now prints that notice.
+
 ```powershell
 pep skills add https://git.newlandpayment.com/group/sub/project   # or group/sub/project[@ref]
 pep skills list
@@ -163,8 +224,8 @@ updating.
 
 ```
 ⚠ 3 repositories all install "semi-integration" here:
-    https://git.example.com/team-a/skill
-    https://git.example.com/team-b/skill-testing
+    https://git.newlandpayment.com/ai-projects/research-projects/skills/semi-integration-skill
+    https://git.newlandpayment.com/distribution/skills/semi-integration-skill-testing
   They overwrite each other. `pep skills remove <repo>` keeps just one.
 ```
 
@@ -204,16 +265,18 @@ Asks PEP for your Maven repository credential and saves it as the two environmen
 Newland Android SDK reads (`NEWLAND_MAVEN_USERNAME` / `NEWLAND_MAVEN_PASSWORD`). Windows uses
 `setx`; macOS keeps a marked block in your shell profile, backed up first.
 
-**The password is never printed.** The credential is derived from who you are, so running this
-again — on this machine or any other — hands you the same one; nothing is lost by not showing it.
-Use `--print-env` when you want the two lines on stdout instead:
+**The password is never printed.** The credential is derived from your organisation's identity, so
+running this again — on this machine or any other — hands you the same one; nothing is lost by not
+showing it. Use `--print-env` when you want the two lines on stdout instead:
 
 ```bash
 eval "$(pep nexus setup --print-env)"    # the shell you are in gets them now
 ```
 
-The credential is per person, not per company — colleagues get their own, and so does the same
-account on a second machine.
+The credential is **per company, not per person**: colleagues who run this get the same username and
+password. It is a read-only credential for the SDK repositories, not a personal account — it says
+which company is pulling, not who. Nothing about it is per-machine either, which is the point: a
+second laptop just runs the command again.
 
 ⚠ Persistence only reaches **new** processes. A running IDE keeps the environment it started with,
 and the Gradle daemon outlives the IDE, so after the first setup: quit Android Studio completely,

package/dist/pep.cjs

@@ -22,6 +22,8 @@ var DEFAULT_SCOPES = [
 var DEFAULT_RESOURCES = ["urn:newland:pep:docs"];
 var LEGACY_PACKAGE = "semi-integration";
 var DEFAULT_DOCS_URL = "https://docs.newlandnpt.us";
+var DEFAULT_SKILLS_GROUP = "distribution/skills";
+var EXAMPLE_SKILLS_REPO = `${DEFAULT_SKILLS_GROUP}/semi-integration-skill`;
 function issuerForEnvironment(environment) {
   if (environment === "production") return "https://pep.newlandnpt.us";
   if (environment === "view") return "https://pep-webapp-view.onrender.com";
@@ -932,8 +934,15 @@ function stamp(at) {
 }
 async function persistMavenEnv(credential, target = resolveTarget(), now = () => /* @__PURE__ */ new Date()) {
   if (target.kind === "windows") {
-    await run("setx", [USERNAME_VAR, credential.username]);
-    await run("setx", [PASSWORD_VAR, credential.password]);
+    try {
+      await run("setx", [USERNAME_VAR, credential.username]);
+      await run("setx", [PASSWORD_VAR, credential.password]);
+    } catch {
+      return {
+        status: "manual",
+        reason: "setx could not write the user environment. The original error is omitted on purpose: it contains the password."
+      };
+    }
     return { status: "windows" };
   }
   const existing = await (0, import_promises3.readFile)(target.path, "utf8").catch((error) => {
@@ -961,6 +970,294 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
   return plan.action === "replace" ? { status: "profile-replaced", path: target.path, backupPath } : { status: "profile-appended", path: target.path, ...backupPath ? { backupPath } : {} };
 }
 
+// src/help.ts
+var EXAMPLE_PATH = EXAMPLE_SKILLS_REPO;
+var EXAMPLE_REPO = `https://git.newlandpayment.com/${EXAMPLE_PATH}.git`;
+var PROJECT_FLAG = "-p, --project   Install into ./.agents/skills of the current directory instead";
+var groups = {
+  auth: {
+    summary: "Sign in to PEP and manage your local authorization.",
+    commands: {
+      login: {
+        summary: "Sign in to PEP through your browser.",
+        usage: "pep auth login [flags]",
+        description: `Opens your browser to sign in, then saves tokens in the OS keychain.
+Tokens are refreshed automatically when needed by other commands.
+Issuer, client ID and resources use this build's defaults for each new login;
+overrides apply to this login only and are not reused by the next login.`,
+        flags: [
+          `--issuer <url>     PEP server for this login (default: ${DEFAULT_ISSUER})`,
+          `--client-id <id>   Registered OAuth client (default: ${DEFAULT_CLIENT_ID})`,
+          `--resource <uri>   Token audience; repeat for multiple resources (default: ${DEFAULT_RESOURCES.join(", ")})`
+        ],
+        examples: ["pep auth login", "pep auth login --issuer http://localhost:3000"]
+      },
+      status: {
+        summary: "Show the current account and authorization status.",
+        usage: "pep auth status",
+        description: "Shows the issuer, client, account, granted scopes and access-token expiry.\nRequires a saved login and contacts PEP to retrieve account information.",
+        examples: ["pep auth status"]
+      },
+      token: {
+        summary: "Print a current access token for scripts and API clients.",
+        usage: "pep auth token",
+        description: "Requires a saved login. Refreshes the token if needed and writes only the\naccess token to stdout, so another command can capture it.",
+        examples: ["pep auth token", "$token = pep auth token  # PowerShell"]
+      },
+      logout: {
+        summary: "Sign out and remove local authorization.",
+        usage: "pep auth logout",
+        description: "Attempts to revoke the saved authorization on PEP, then removes local tokens\nand login configuration. Local data is removed even if remote revocation fails.",
+        examples: ["pep auth logout"]
+      }
+    }
+  },
+  skills: {
+    summary: "Download and update PEP agent skills.",
+    commands: {
+      list: {
+        summary: "List the skill repositories you have added.",
+        usage: "pep skills list",
+        description: "Requires a saved PEP login. Lists locally registered repositories.\nUse pep skills add to add a repository, or pep skills update to refresh it.",
+        examples: ["pep skills list"]
+      },
+      add: {
+        summary: "Add skills from a repository on PEP's GitLab.",
+        usage: "pep skills add <repo> [flags]",
+        description: `Accepts a full HTTPS repository URL or group/project[@ref]. URLs with
+/-/tree/<ref> are also supported. PEP fetches the repository with its own service
+account; no GitLab credential is needed locally. Other hosts are refused.
+Each directory containing SKILL.md is installed as a skill.
+Requires a saved PEP login.
+
+Installs for your user account by default. Pass --project to install into the
+current directory instead, so the skills travel with the repository and everyone
+working on it gets the same set. The choice is remembered per repository, so
+pep skills update does not need the flag again.
+
+Also re-installs skills you removed with pep skills remove. This is the only
+command that does; pep skills update leaves them removed.`,
+        flags: [
+          "--dir <path>    Install only to this directory; skip links into Claude Code",
+          `${PROJECT_FLAG}`
+        ],
+        examples: [
+          `pep skills add ${EXAMPLE_REPO}`,
+          `pep skills add ${EXAMPLE_PATH}@main`,
+          `pep skills add ${EXAMPLE_REPO} --project`,
+          `pep skills add ${EXAMPLE_PATH} --dir "./my-skills"`
+        ]
+      },
+      update: {
+        summary: "Update installed skill repositories and report changed skills.",
+        usage: "pep skills update [<repo>...] [flags]",
+        description: `Requires a saved PEP login. Downloads skills to:
+  ${defaultSkillsDirectory()}
+Also links them into ${claudeSkillsDirectory()} for Claude Code,
+or copies them if links are unavailable. Only skills managed by pep are updated
+or removed; files you added yourself are left alone.
+With no repository arguments, updates all added repositories. Named repositories
+must already have been added. Reports which individual skills changed.
+
+Each repository is updated where it was installed, so the flags you used with
+pep skills add do not need repeating.
+
+Skills you removed with pep skills remove stay removed: update refreshes what is
+installed and does not bring anything back. Run pep skills add to reinstate them.`,
+        flags: [
+          "--dir <path>    Install only to this directory; skip links into Claude Code",
+          `${PROJECT_FLAG}`
+        ],
+        examples: [
+          "pep skills update",
+          `pep skills update ${EXAMPLE_PATH}`,
+          'pep skills update --dir "./my-skills"'
+        ]
+      },
+      remove: {
+        summary: "Remove the skills a repository installed.",
+        usage: "pep skills remove <repo>",
+        description: `Deletes the skills this repository installed, wherever they were installed,
+and stops tracking it. Takes no --dir or --project: the location comes from what
+pep recorded when it installed them.
+
+Only files pep installed from this repository are deleted. A skill another added
+repository also provides is left in place, and so is anything you wrote yourself.
+
+pep skills update will not bring the skills back. Run pep skills add to do that.`,
+        examples: [
+          `pep skills remove ${EXAMPLE_PATH}`,
+          `pep skills remove ${EXAMPLE_REPO}`
+        ]
+      }
+    }
+  },
+  docs: {
+    summary: "Find and read PEP developer documentation.",
+    commands: {
+      list: {
+        summary: "List the documents your account can read.",
+        usage: "pep docs list [flags]",
+        description: "Requires a saved PEP login. Prints each document's path and description.\nPass a path from this list to pep docs get to read its Markdown content.",
+        flags: [`--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`],
+        examples: ["pep docs list", "pep docs list --docs-url http://localhost:3001"]
+      },
+      get: {
+        summary: "Read a document as Markdown.",
+        usage: "pep docs get <path> [flags]",
+        description: "Requires a saved PEP login. Use a document path returned by pep docs list.\nWrites the document's Markdown to stdout, ready to pipe or save to a file.",
+        flags: [`--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`],
+        examples: ['pep docs get "<path-from-pep-docs-list>"', 'pep docs get "<path-from-pep-docs-list>" > document.md']
+      }
+    }
+  },
+  nexus: {
+    summary: "Configure Maven repository access for the Newland Android SDK.",
+    commands: {
+      setup: {
+        summary: "Save your organisation's Maven credentials for the Newland SDK.",
+        usage: "pep nexus setup [flags]",
+        description: `Requires a saved PEP login and Maven access in your organisation's contract.
+Saves ${USERNAME_VAR} and ${PASSWORD_VAR} to the Windows user
+environment or your macOS shell profile.
+
+Safe to run again, on as many machines as you like: the credential is derived
+from your organisation's identity, so every run produces the same one. Losing it
+is not a problem \u2014 run this again.
+
+One credential per organisation: colleagues who run this get the same username
+and password. It is a read-only credential for the Newland SDK repositories, not
+a personal account, so it identifies your company rather than you.
+
+Neither value is printed. Pass --print-env to write the two export lines to
+stdout instead, for the current shell:
+  eval "$(pep nexus setup --print-env)"
+
+Saved values only reach new processes. After setup:
+  - open a new terminal;
+  - fully quit and reopen Android Studio / IntelliJ, whose built-in terminal
+    inherits the environment it was started with;
+  - stop the Gradle daemon, which outlives the IDE: gradlew --stop.
+A daemon started before setup keeps the old environment and fails to resolve the
+SDK even once everything else is correct.`,
+        flags: ["--print-env   Also write the export lines to stdout for the current shell"],
+        examples: ["pep nexus setup", 'eval "$(pep nexus setup --print-env)"']
+      }
+    }
+  }
+};
+function flagBlock(flags) {
+  const split = flags.map((one) => {
+    const gap = one.search(/ {2,}/);
+    return gap === -1 ? [one, ""] : [one.slice(0, gap), one.slice(gap).trimStart()];
+  });
+  const width = Math.max(...split.map(([name]) => name.length)) + 3;
+  return split.map(([name, text]) => `  ${text === "" ? name : name.padEnd(width) + text}`).join("\n");
+}
+var topLevel = {
+  setup: {
+    summary: "Sign in, install the integration guide and configure Maven in one go.",
+    usage: "pep setup [<group>] [flags]",
+    description: `Runs the three first-run steps in order, skipping what is already done:
+  1. Sign in \u2014 skipped when you are already signed in (tokens refresh themselves).
+  2. Install every skills repository in a group (default: ${DEFAULT_SKILLS_GROUP}).
+  3. Configure Maven credentials \u2014 only Android development needs this.
+
+Step 2 asks the platform which repositories that group holds right now, then
+installs each one. A repository that fails does not stop the others: the command
+reports how many went in, which ones did not, and exits non-zero.
+
+Steps 2 and 3 are independent: if one fails the other still runs. Safe to run
+again \u2014 every step is idempotent.
+
+Repositories you installed earlier that have since left the group are reported,
+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.`,
+    flags: [
+      "--skip-skills   Skip the integration guide step",
+      "--skip-nexus    Skip the Maven credential step (not needed outside Android)",
+      PROJECT_FLAG,
+      "--dir <path>    Install skills into this directory instead"
+    ],
+    examples: [
+      "pep setup",
+      "pep setup --skip-nexus",
+      `pep setup ${DEFAULT_SKILLS_GROUP} -p`
+    ]
+  }
+};
+function renderCommand(command) {
+  return `${command.summary}
+
+${command.description}
+
+USAGE
+  ${command.usage}
+
+FLAGS
+${flagBlock([...command.flags ?? [], "-h, --help  Show help for this command"])}
+
+EXAMPLES
+${command.examples.map((example) => `  ${example}`).join("\n")}`;
+}
+function usage(version, path = []) {
+  const [groupName, commandName] = path;
+  if (!groupName) {
+    return `PEP CLI ${version}
+Sign in to PEP, read developer documentation and configure development tools.
+
+USAGE
+  pep <command> <subcommand> [flags]
+
+COMMANDS
+${Object.entries(topLevel).map(([name, command]) => `  ${name.padEnd(10)}${command.summary}`).join("\n")}
+${Object.entries(groups).map(([name, group2]) => `  ${name.padEnd(10)}${group2.summary}`).join("\n")}
+
+FLAGS
+  -h, --help      Show help for a command
+  -v, --version   Show the CLI version
+
+EXAMPLES
+  pep setup
+  pep docs list
+  pep nexus setup --help
+
+LEARN MORE
+  Use pep <command> --help or pep <command> <subcommand> --help.
+  You can also use pep help <command> <subcommand>.
+  pep-cli is an alias for pep.`;
+  }
+  if (Object.hasOwn(topLevel, groupName)) {
+    if (path.length > 2) {
+      throw new Error(`Unknown ${groupName} argument: ${path.slice(1).join(" ")}. Run pep ${groupName} --help.`);
+    }
+    return renderCommand(topLevel[groupName]);
+  }
+  if (!Object.hasOwn(groups, groupName)) throw new Error(`Unknown command: ${groupName}. Run pep --help.`);
+  const group = groups[groupName];
+  if (!commandName) {
+    return `${group.summary}
+
+USAGE
+  pep ${groupName} <command> [flags]
+
+COMMANDS
+${Object.entries(group.commands).map(([name, command]) => `  ${name.padEnd(10)}${command.summary}`).join("\n")}
+
+FLAGS
+  -h, --help   Show help for this command
+
+LEARN MORE
+  Use pep ${groupName} <command> --help for details and examples.`;
+  }
+  if (path.length > 2 || !Object.hasOwn(group.commands, commandName)) {
+    throw new Error(`Unknown ${groupName} command: ${path.slice(1).join(" ")}. Run pep ${groupName} --help.`);
+  }
+  return renderCommand(group.commands[commandName]);
+}
+
 // src/nexus-service.ts
 var CREDENTIAL_PATH = "/api/nexus/credential";
 function describeFailure2(status, code) {
@@ -974,13 +1271,16 @@ function describeFailure2(status, code) {
     return "This access token carries no `nexus-credentials:write` scope. Ask an operator to add it to this client's allowed_scopes in PEP, then run `pep auth login` again \u2014 existing tokens do not gain new scopes.";
   }
   if (status === 409) {
-    return "This PEP deployment still issues one Maven credential per company, so it cannot give you yours again. Newer PEP issues one per person and can always re-derive it \u2014 ask an operator to upgrade this deployment; until then, copy the credential from the machine that has it.";
+    return "This PEP deployment issues a random Maven password once and does not store it, so it cannot give you yours again. Newer PEP derives it and can always re-issue the same one \u2014 ask an operator to upgrade this deployment; until then, copy the credential from the machine that has it.";
   }
   if (status === 503) {
     return "PEP could not reach Nexus (not configured, or upstream is down). This is a platform-side problem \u2014 retrying will not help. Report it to a PEP operator.";
   }
   return `PEP answered ${status} when asking for a Maven credential.`;
 }
+function scrub(text, password) {
+  return password === "" ? text : text.split(password).join("<redacted>");
+}
 async function errorCodeOf(response) {
   try {
     const body = await response.json();
@@ -1016,7 +1316,11 @@ async function setupNexusCredential(dependencies) {
   const persisted = await persistMavenEnv(credential, target, dependencies.now).catch(
     (error) => ({
       status: "manual",
-      reason: error.message,
+      // ⚠ **兜底要洗一遍密码。** `reason` 会被 `nexusReport` 原样打到 stderr，而异常消息里
+      // 带密码是有过先例的：`execFile` 被拒时的 message 含**完整命令行**，`setx` 的密码就是
+      // 它的一个参数。那一处已经在 `maven-env.ts` 里就地接住了，这里是第二道 —— 往后谁在
+      // 那条路上新加一个 throw，不必先想起这条注释也不会漏出去。
+      reason: scrub(error.message, credential.password),
       ...target.kind === "profile" ? { path: target.path } : {}
     })
   );
@@ -1105,6 +1409,7 @@ function readTar(bytes) {
 
 // src/skills-service.ts
 var ARCHIVE_PATH = "/api/skills/archive";
+var GROUP_PATH = "/api/skills/group";
 var MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
 var MAX_UNPACKED_BYTES = 256 * 1024 * 1024;
 var MAX_ENTRIES = 1e4;
@@ -1200,6 +1505,69 @@ function describeFailure3(status) {
   }
   return `PEP answered ${status}.`;
 }
+function describeGroupFailure(status) {
+  if (status === 400)
+    return "PEP did not accept that group path. It must be a <group> or <group>/<subgroup> path on the platform's GitLab host, or an https URL to that group.";
+  if (status === 404) {
+    return "No such group on the platform's GitLab (or this PEP deployment has no /api/skills/group endpoint at all). Check the path, then ask an operator whether this deployment serves skills.";
+  }
+  if (status === 503)
+    return "PEP could not reach GitLab to list that group. Retry shortly, or ask an operator whether this deployment serves skills.";
+  return describeFailure3(status);
+}
+var MAX_GROUP_LIST_BYTES = 4 * 1024 * 1024;
+function parseGroupList(body) {
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    throw new Error("PEP returned a group listing this CLI cannot read (not JSON).");
+  }
+  const items = payload?.data?.items;
+  if (!Array.isArray(items)) {
+    throw new Error("PEP returned a group listing this CLI cannot read (no data.items array).");
+  }
+  const paths = [];
+  for (const item of items) {
+    const path = item?.path;
+    if (typeof path !== "string" || path.trim() === "") {
+      throw new Error("PEP returned a group listing this CLI cannot read (an entry has no path).");
+    }
+    paths.push(path.trim());
+  }
+  return [...new Set(paths)].sort();
+}
+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}` }
+  });
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(describeGroupFailure(response.status));
+  }
+  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();
+  if (/^https?:\/\//i.test(path)) {
+    try {
+      path = new URL(path).pathname;
+    } catch {
+      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("/");
+}
 async function physicalDir(path) {
   const absolute = (0, import_node_path4.resolve)(path);
   try {
@@ -1425,98 +1793,110 @@ async function updateSkills(dependencies) {
   };
 }
 
-// src/cli.ts
-var VERSION = false ? "0.0.0-dev" : "0.8.1";
-function usage() {
-  return `PEP CLI ${VERSION}
-
-Usage:
-  pep auth login [--issuer <url>] [--client-id <id>] [--resource <uri> ...]
-  pep auth status
-  pep auth token
-  pep auth logout
-  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 [--print-env]
-
-The issuer is built into this executable. --issuer overrides it for that one command and is
-NOT remembered \u2014 pass it every time you log in against a non-default deployment.
---resource names which resource server the token is for (RFC 8707); repeat it for more than
-one. It defaults to the docs platform \u2014 a token minted without it is rejected by every
-resource server, and their answer looks exactly like "this token does not exist".
-Use \`pep auth token\` when another agent needs a fresh bearer token.
-
-\`pep skills add\` takes a repository on the platform's own GitLab, either as a full https URL or
-as the path with the host left off:
-
-  pep skills add https://git.example.com/group/sub/project
-  pep skills add https://git.example.com/group/sub/project/-/tree/some-branch
-  pep skills add group/sub/project
-  pep skills add group/sub/project@some-branch
-
-Anything on another host is refused. PEP fetches it with its own read-only service account, so no
-GitLab credential ever reaches this machine. \`pep skills list\` shows what you have added and
-\`pep skills update\` refreshes it \u2014 all of it, or just the repositories you name. One repository
-may hold more than one skill: every directory containing a SKILL.md becomes one, wherever it sits,
-and update reports which of them actually changed rather than just that the repository moved.
-
-\`pep skills update\` fetches the latest skills from PEP and writes them to the shared agent
-directory (${defaultSkillsDirectory()}), which Codex, Cursor, Amp and ~20 other agents read
-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.
-
-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.
-\`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. add refuses, naming
-the repository already there. update never fails over it: it leaves that one skill untouched,
-refreshes everything else, and reports it every run until you remove one. Installing them into
-different directories (-p, or --dir) is fine.
-
-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
-site is built in (${DEFAULT_DOCS_URL}); --docs-url overrides it and is then remembered.
-
-\`pep nexus setup\` asks PEP for your Maven repository credential and saves it as the two
-environment variables the Newland Android SDK reads \u2014 \`${USERNAME_VAR}\` and \`${PASSWORD_VAR}\`
-\u2014 so you do not copy anything by hand. On Windows it writes them to your user environment
-(\`setx\`); on macOS it keeps a marked block in your shell profile, backing the file up first and
-touching nothing else. Either way persistence only affects NEW shells.
-
-**The password is never printed.** The credential is derived from who you are, so running this
-again \u2014 on this machine or any other \u2014 hands you the same one. Nothing is lost by not showing it.
-\`--print-env\` writes the two lines to stdout instead, for
-\`eval "$(pep nexus setup --print-env)"\` when you want the shell you are in to have them now.
-
-The credential is per person, not per company: your colleagues get their own, and so does the same
-account on a second machine. Only Android needs this \u2014 the Windows and iOS SDKs are cloned from
-Git, not pulled from Maven.`;
+// src/setup-flow.ts
+function accountOf(user) {
+  return user.email ?? user.name ?? user.sub;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function driftedFromGroup(installedSources, groupRepos, group) {
+  const present = new Set(groupRepos.map((one) => one.trim().toLowerCase()));
+  return installedSources.filter((key) => {
+    const member = groupMemberPath(key, group);
+    return member !== void 0 && !present.has(member);
+  }).sort();
+}
+async function installGroup(dependencies, remote) {
+  const group = dependencies.group;
+  let repos;
+  try {
+    repos = await dependencies.listGroupRepos(remote);
+  } catch (error) {
+    const message = messageOf(error);
+    dependencies.onProgress(`   \u2717 ${message}`);
+    return { status: "failed", group, message };
+  }
+  if (repos.length === 0) {
+    dependencies.onProgress(`   ${group} lists no repositories \u2014 nothing to install.`);
+  }
+  const installed = [];
+  const failed = [];
+  for (const [index, source] of repos.entries()) {
+    dependencies.onProgress(`   [${index + 1}/${repos.length}] ${source}`);
+    try {
+      installed.push({ source, ...await dependencies.installSkills(remote, source) });
+    } catch (error) {
+      const message = messageOf(error);
+      failed.push({ source, message });
+      dependencies.onProgress(`   \u2717 ${source}: ${message}`);
+    }
+  }
+  return {
+    status: "installed",
+    group,
+    installed,
+    failed,
+    drifted: driftedFromGroup(dependencies.installedSources, repos, group)
+  };
 }
+async function runSetup(dependencies) {
+  dependencies.onProgress("\u2460 Signing in to PEP\u2026");
+  let login;
+  let signedIn;
+  try {
+    signedIn = await dependencies.auth.status();
+    login = { alreadySignedIn: true, account: accountOf(signedIn.user) };
+    dependencies.onProgress(`   Already signed in as ${login.account} \u2014 skipped.`);
+  } catch {
+    const config = await dependencies.loginConfig();
+    dependencies.onProgress("   Opening your browser to sign in\u2026");
+    await dependencies.auth.login(config, dependencies.onAuthorizationUrl);
+    const account = await dependencies.auth.status().then((it) => accountOf(it.user)).catch(() => "(account name unavailable)");
+    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 };
+  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);
+  }
+  let nexus;
+  if (dependencies.skipNexus) {
+    nexus = { status: "skipped", reason: "--skip-nexus" };
+    dependencies.onProgress("\u2462 Maven credentials\u2026 skipped (--skip-nexus).");
+  } else {
+    dependencies.onProgress("\u2462 Setting up Maven credentials\u2026");
+    try {
+      nexus = { status: "done", result: await dependencies.setupNexus(remote) };
+    } catch (error) {
+      nexus = { status: "failed", message: messageOf(error) };
+      dependencies.onProgress(`   \u2717 ${nexus.message}`);
+    }
+  }
+  return { login, skills, nexus };
+}
+function setupFailureSummary(report) {
+  const failed = [];
+  if (report.skills.status === "failed") {
+    failed.push("skills (could not list the group)");
+  } else if (report.skills.status === "installed" && report.skills.failed.length > 0) {
+    const total = report.skills.installed.length + report.skills.failed.length;
+    failed.push(`skills (${report.skills.failed.length} of ${total} repositories)`);
+  }
+  if (report.nexus.status === "failed") failed.push("Maven credentials");
+  if (failed.length === 0) return void 0;
+  return `Setup finished with problems: ${failed.join(", ")} did not complete.`;
+}
+
+// src/cli.ts
+var VERSION = false ? "0.0.0-dev" : "0.9.0-rc.1";
+var SKILLS_ADD_DEPRECATION = "\u26A0 `pep skills add` will be removed in a future release.";
 function reportUpdate(result) {
   const conflicts = () => {
     for (const { skill, owner } of result.conflicts) {
@@ -1604,7 +1984,7 @@ function parseSkillsArgs(command, args, cwd) {
   }
   const unknownOption = args.find((one) => one.startsWith("-"));
   if (unknownOption) throw new Error(`Unknown option: ${unknownOption}`);
-  const takesOne = command === "add" || command === "remove";
+  const takesOne = command === "add" || command === "remove" || command === "setup";
   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>.");
@@ -1642,6 +2022,8 @@ function nexusReport(result, printEnv) {
       `Nothing was written${persisted.path ? ` to ${persisted.path}` : ""}: ${persisted.reason}`
     );
     stderr.push("Run this again to get the same credential \u2014 it is derived, not stored.");
+    stderr.push(`Nexus user: ${result.username}`);
+    return { stdout, stderr, failure: "Maven credentials could not be fully saved." };
   } else {
     stderr.push(
       persisted.status === "profile-replaced" ? `Replaced the pep-cli block in ${persisted.path}` : `Appended a pep-cli block to ${persisted.path}`
@@ -1654,10 +2036,58 @@ function nexusReport(result, printEnv) {
   stderr.push(`Nexus user: ${result.username}`);
   return { stdout, stderr };
 }
+function createCliServices() {
+  const configStore = fileConfigStore(configPath());
+  return {
+    configStore,
+    auth: createAuthService({
+      configStore,
+      credentialStore: systemCredentialStore(),
+      oauth: createOAuthClient()
+    })
+  };
+}
+function reportSetup(report) {
+  console.log("");
+  const skills = report.skills;
+  if (skills.status === "skipped") {
+    console.error(`Skills: ${skills.reason}`);
+  } else if (skills.status === "failed") {
+    console.error(`Skills: could not list ${skills.group} \u2014 ${skills.message}`);
+  } else {
+    const total = skills.installed.length + skills.failed.length;
+    for (const directory of [...new Set(skills.installed.map((one) => one.directory))].sort()) {
+      console.log(`Next: read ${directory}/<name>/SKILL.md`);
+    }
+    console.error(
+      total === 0 ? `Skills: ${skills.group} lists no repositories \u2014 nothing was installed.` : `Skills: installed ${skills.installed.length} of ${total} repositories in ${skills.group}.`
+    );
+    for (const { source, message } of skills.failed) {
+      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.");
+    }
+  }
+  if (report.nexus.status === "skipped") {
+    console.error(`Maven credentials: skipped (${report.nexus.reason}).`);
+  }
+}
 async function main() {
   const args = process.argv.slice(2);
+  if (args[0] === "help") {
+    console.log(usage(VERSION, args.slice(1).filter((arg) => arg !== "--help" && arg !== "-h")));
+    return;
+  }
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-    console.log(usage());
+    const path = args.filter((arg) => arg !== "--help" && arg !== "-h").slice(0, 2);
+    const flagIndex = path.findIndex((arg) => arg.startsWith("-"));
+    console.log(usage(VERSION, flagIndex === -1 ? path : path.slice(0, flagIndex)));
     return;
   }
   if (args[0] === "--version" || args[0] === "-v") {
@@ -1665,22 +2095,71 @@ async function main() {
     return;
   }
   const group = args.shift();
+  if (group === "setup") {
+    const skipNexus = flag(args, "--skip-nexus");
+    const skipSkills = flag(args, "--skip-skills");
+    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 report = await runSetup({
+      auth: auth2,
+      loginConfig: () => loginConfig(args, configStore2),
+      group: skillsGroup,
+      skipSkills,
+      listGroupRepos: (remote) => listGroupRepos({ ...remote, group: skillsGroup }),
+      installSkills: async (remote, source) => {
+        const target = targetForSource(chosenTarget, state?.packages[source]);
+        const result = await updateSkills({
+          ...remote,
+          source,
+          directory: target.directory,
+          ...target.linkInto !== void 0 ? { linkInto: target.linkInto } : {},
+          // `add` 那一档的语义：盘上被删掉的那些由它补回来（`update` 不管）。
+          restoreMissing: true,
+          stateStore
+        });
+        return { result, directory: target.directory };
+      },
+      // 漂移比对的另一半。取**这一趟开始前**的账 —— 装完再读的话，本轮刚装上的那些也在
+      // 里头，而它们当然都还在群里，比出来一样，只是白读一遍。
+      installedSources: Object.keys(state?.packages ?? {}),
+      skipNexus,
+      setupNexus: (remote) => setupNexusCredential(remote),
+      onProgress: (line) => console.error(line),
+      onAuthorizationUrl: (url) => console.error(`If the browser does not open, visit:
+${url}`)
+    });
+    if (report.skills.status === "installed") {
+      for (const one of report.skills.installed) reportUpdate(one.result);
+    }
+    if (report.nexus.status === "done") {
+      const nexus = nexusReport(report.nexus.result, false);
+      for (const line of nexus.stdout) console.log(line);
+      for (const line of nexus.stderr) console.error(line);
+      if (nexus.failure) report.nexus = { status: "failed", message: nexus.failure };
+    }
+    reportSetup(report);
+    const failure = setupFailureSummary(report);
+    if (failure) throw new Error(failure);
+    return;
+  }
   if (group !== "auth" && group !== "skills" && group !== "docs" && group !== "nexus")
     throw new Error(`Unknown command.
 
-${usage()}`);
+${usage(VERSION)}`);
   const command = args.shift();
-  const configStore = fileConfigStore(configPath());
-  const auth = createAuthService({
-    configStore,
-    credentialStore: systemCredentialStore(),
-    oauth: createOAuthClient()
-  });
+  if (!command) {
+    console.log(usage(VERSION, [group]));
+    return;
+  }
+  const { configStore, auth } = createCliServices();
   if (group === "docs") {
     if (command !== "list" && command !== "get") {
       throw new Error(`Unknown docs command.
 
-${usage()}`);
+${usage(VERSION, ["docs"])}`);
     }
     const explicitDocsUrl = option(args, "--docs-url");
     const path = command === "get" ? args.shift() : void 0;
@@ -1708,9 +2187,11 @@ ${usage()}`);
     return;
   }
   if (group === "nexus") {
-    if (command !== "setup") throw new Error(`Unknown nexus command.
+    if (command !== "setup") {
+      throw new Error(`Unknown nexus command.
 
-${usage()}`);
+${usage(VERSION, ["nexus"])}`);
+    }
     const printEnv = flag(args, "--print-env");
     if (args.length > 0) throw new Error(`Unknown option: ${args[0]}`);
     const authorization = await auth.currentAuthorization();
@@ -1721,13 +2202,14 @@ ${usage()}`);
     const report = nexusReport(result, printEnv);
     for (const line of report.stdout) console.log(line);
     for (const line of report.stderr) console.error(line);
+    if (report.failure) throw new Error(report.failure);
     return;
   }
   if (group === "skills") {
     if (command !== "update" && command !== "add" && command !== "list" && command !== "remove") {
       throw new Error(`Unknown skills command.
 
-${usage()}`);
+${usage(VERSION, ["skills"])}`);
     }
     const { requested, named, chosenTarget } = parseSkillsArgs(command, args);
     const stateStore = fileSkillsStateStore();
@@ -1784,6 +2266,7 @@ ${usage()}`);
       })
     );
     if (command === "add") {
+      console.error(SKILLS_ADD_DEPRECATION);
       await run2(
         requested,
         targetForSource(chosenTarget, state?.packages[requested]),
@@ -1862,7 +2345,7 @@ ${url}`)
   }
   throw new Error(`Unknown auth command.
 
-${usage()}`);
+${usage(VERSION, ["auth"])}`);
 }
 
 // src/main.ts

package/package.json

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