@newlandnpt/pep-cli 0.1.3 → 0.3.1

package/README.md

@@ -72,11 +72,16 @@ The issuer is fixed at build time:
 `--issuer` remains available only as a temporary override — it is **not** remembered, so every
 `auth login` needs it again. That is why the built-in default decides where most users land.
 
-⚠ **The npm release is built from `view`** (see `prepublishOnly`). As of 2026-09-08
-`https://pep.newlandnpt.us/.well-known/openid-configuration` returns **404** — the production
-domain does not serve the authorization server yet, so a `production` build would fail at
-discovery on the user's very first `auth login`. Switch `prepublishOnly` back to `production`
-once that endpoint is live.
+⚠ **The npm release is currently built from `development`** — it ships
+`https://pep-webapp-dev.onrender.com` (see `prepack` in `package.json`). This is a deliberate
+temporary state: production is not going live in the near term and this build is for other
+departments to use now.
+
+`https://pep.newlandnpt.us/.well-known/openid-configuration` still returns **404** (last checked
+2026-09-09) — the production domain does not serve the authorization server yet, so a
+`production` build fails at discovery on the user's very first `auth login`. **Switch `prepack`
+back to `production` and publish immediately once that endpoint is live**: the issuer is baked in
+at build time, so releases already out in the wild cannot be repointed.
 
 `pep auth token` writes only the access token to stdout, so agents can use it without parsing status
 text. Refresh occurs automatically shortly before expiry and the rotated refresh token replaces the old

package/dist/pep.cjs

@@ -11,15 +11,23 @@ var import_node_os = require("node:os");
 var import_node_path = require("node:path");
 var DEFAULT_CLIENT_ID = "pep-cli";
 var DEFAULT_REDIRECT_URI = "http://localhost:53682/callback";
-var DEFAULT_SCOPES = ["openid", "profile", "email", "docs:read", "skills:read"];
+var DEFAULT_SCOPES = [
+  "openid",
+  "profile",
+  "email",
+  "docs:read",
+  "skills:read",
+  "nexus-credentials:write"
+];
 var DEFAULT_RESOURCES = ["urn:newland:pep:docs"];
+var LEGACY_PACKAGE = "semi-integration";
 var DEFAULT_DOCS_URL = "https://pep-developer-docs.onrender.com";
 function issuerForEnvironment(environment) {
   if (environment === "production") return "https://pep.newlandnpt.us";
   if (environment === "view") return "https://pep-webapp-view.onrender.com";
   return "https://pep-webapp-dev.onrender.com";
 }
-var BUILD_ENVIRONMENT = false ? "development" : "production";
+var BUILD_ENVIRONMENT = false ? "development" : "development";
 var DEFAULT_ISSUER = issuerForEnvironment(BUILD_ENVIRONMENT);
 function configuredIssuer(explicitIssuer) {
   return explicitIssuer ?? DEFAULT_ISSUER;
@@ -76,15 +84,75 @@ function fileConfigStore(path = configPath()) {
 function isSkillsState(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
-  return candidate.version === 1 && typeof candidate.directory === "string" && Array.isArray(candidate.skills) && candidate.skills.every((one) => typeof one === "string") && (candidate.commit === void 0 || typeof candidate.commit === "string") && // 可选：0.1.1 及更早写下的 skills.json 没有这个键，读它们不该报「状态损坏」。
-  (candidate.linkedInto === void 0 || typeof candidate.linkedInto === "string");
+  if (candidate.version !== 3) return false;
+  if (typeof candidate.directory !== "string") return false;
+  if (candidate.linkedInto !== void 0 && typeof candidate.linkedInto !== "string") return false;
+  return isPackageMap(candidate.packages, (skills) => isStringMap(skills));
+}
+function isSkillsStateV2(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (candidate.version !== 2) return false;
+  if (typeof candidate.directory !== "string") return false;
+  if (candidate.linkedInto !== void 0 && typeof candidate.linkedInto !== "string") return false;
+  return isPackageMap(
+    candidate.packages,
+    (skills) => Array.isArray(skills) && skills.every((one) => typeof one === "string")
+  );
+}
+function isSkillsStateV1(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return candidate.version === 1 && typeof candidate.directory === "string" && Array.isArray(candidate.skills) && candidate.skills.every((one) => typeof one === "string") && (candidate.commit === void 0 || typeof candidate.commit === "string") && (candidate.linkedInto === void 0 || typeof candidate.linkedInto === "string");
+}
+function isPackageMap(value, skillsOk) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((one) => {
+    if (typeof one !== "object" || one === null || Array.isArray(one)) return false;
+    const pkg = one;
+    return skillsOk(pkg.skills) && (pkg.commit === void 0 || typeof pkg.commit === "string");
+  });
+}
+function isStringMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((one) => typeof one === "string");
+}
+function migrateSkillsState(old) {
+  const base = {
+    version: 3,
+    directory: old.directory,
+    ...old.linkedInto !== void 0 ? { linkedInto: old.linkedInto } : {}
+  };
+  const unknownHashes = (names) => Object.fromEntries(names.map((name) => [name, ""]));
+  if (old.version === 1) {
+    return {
+      ...base,
+      packages: {
+        [LEGACY_PACKAGE]: {
+          ...old.commit !== void 0 ? { commit: old.commit } : {},
+          skills: unknownHashes(old.skills)
+        }
+      }
+    };
+  }
+  return {
+    ...base,
+    packages: Object.fromEntries(
+      Object.entries(old.packages).map(([source, pkg]) => [
+        source,
+        { ...pkg.commit !== void 0 ? { commit: pkg.commit } : {}, skills: unknownHashes(pkg.skills) }
+      ])
+    )
+  };
 }
 function fileSkillsStateStore(path = skillsStatePath()) {
   return {
     async read() {
       try {
         const parsed = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
-        return isSkillsState(parsed) ? parsed : null;
+        if (isSkillsState(parsed)) return parsed;
+        if (isSkillsStateV2(parsed) || isSkillsStateV1(parsed)) return migrateSkillsState(parsed);
+        return null;
       } catch (error) {
         if (error.code === "ENOENT") return null;
         if (error instanceof SyntaxError) return null;
@@ -765,10 +833,173 @@ async function fetchDocContent(dependencies, path) {
   return response.text();
 }
 
-// src/skills-service.ts
+// src/maven-env.ts
 var import_promises3 = require("node:fs/promises");
 var import_node_os2 = require("node:os");
 var import_node_path3 = require("node:path");
+var import_node_child_process3 = require("node:child_process");
+var import_node_util = require("node:util");
+var run = (0, import_node_util.promisify)(import_node_child_process3.execFile);
+var USERNAME_VAR = "NEWLAND_MAVEN_USERNAME";
+var PASSWORD_VAR = "NEWLAND_MAVEN_PASSWORD";
+var BEGIN = "# >>> pep-cli: Newland Maven credentials >>>";
+var END = "# <<< pep-cli: Newland Maven credentials <<<";
+function resolveTarget(os = (0, import_node_os2.platform)(), shell = process.env.SHELL) {
+  if (os === "win32") return { kind: "windows" };
+  const file = shell?.endsWith("/bash") ? ".bash_profile" : ".zshrc";
+  return { kind: "profile", path: (0, import_node_path3.join)((0, import_node_os2.homedir)(), file) };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function exportLines(credential, os = (0, import_node_os2.platform)()) {
+  if (os === "win32") {
+    return `set ${USERNAME_VAR}=${credential.username}
+set ${PASSWORD_VAR}=${credential.password}`;
+  }
+  return [
+    `export ${USERNAME_VAR}=${shellQuote(credential.username)}`,
+    `export ${PASSWORD_VAR}=${shellQuote(credential.password)}`
+  ].join("\n");
+}
+function profileBlock(credential) {
+  return [
+    BEGIN,
+    "# \u7531 `pep nexus setup` \u5199\u5165\u3002\u8FD9\u4E00\u6BB5\u4F1A\u88AB\u4E0B\u4E00\u6B21\u8FD0\u884C\u6574\u4F53\u66FF\u6362\uFF0C\u624B\u6539\u65E0\u6548\u3002",
+    `export ${USERNAME_VAR}=${shellQuote(credential.username)}`,
+    `export ${PASSWORD_VAR}=${shellQuote(credential.password)}`,
+    END
+  ].join("\n");
+}
+function planProfile(existing, credential) {
+  const block = profileBlock(credential);
+  if (existing === null || existing.trim() === "") {
+    return { action: "append", content: `${block}
+` };
+  }
+  const begin = existing.indexOf(BEGIN);
+  const end = existing.indexOf(END);
+  if (begin === -1 && end === -1) {
+    const separator = existing.endsWith("\n") ? "" : "\n";
+    return { action: "append", content: `${existing}${separator}
+${block}
+` };
+  }
+  if (begin === -1 || end === -1 || end < begin) {
+    return {
+      action: "manual",
+      reason: "profile \u91CC pep-cli \u7684\u56F4\u680F\u53EA\u5269\u534A\u6761\uFF08\u88AB\u624B\u6539\u8FC7\uFF0C\u6216\u4E0A\u6B21\u5199\u4E86\u4E00\u534A\uFF09\uFF0C\u4E0D\u731C\u8FB9\u754C"
+    };
+  }
+  if (existing.indexOf(BEGIN, begin + 1) !== -1) {
+    return { action: "manual", reason: "profile \u91CC\u6709\u4E0D\u6B62\u4E00\u6BB5 pep-cli \u56F4\u680F\uFF0C\u4E0D\u731C\u8BE5\u6362\u54EA\u4E00\u6BB5" };
+  }
+  return {
+    action: "replace",
+    content: existing.slice(0, begin) + block + existing.slice(end + END.length)
+  };
+}
+function stamp(at) {
+  return at.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "");
+}
+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]);
+    return { status: "windows" };
+  }
+  const existing = await (0, import_promises3.readFile)(target.path, "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  const plan = planProfile(existing, credential);
+  if (plan.action === "manual") {
+    return { status: "manual", reason: plan.reason, path: target.path };
+  }
+  let backupPath;
+  if (existing !== null) {
+    backupPath = `${target.path}.bak-${stamp(now())}`;
+    try {
+      await (0, import_promises3.writeFile)(backupPath, existing, { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      return {
+        status: "manual",
+        reason: `\u5907\u4EFD\u5199\u4E0D\u6210\uFF08${backupPath}\uFF1A${error.message}\uFF09\uFF0C\u56E0\u6B64\u6CA1\u6709\u6539\u52A8 profile`,
+        path: target.path
+      };
+    }
+  }
+  await (0, import_promises3.writeFile)(target.path, plan.content, "utf8");
+  return plan.action === "replace" ? { status: "profile-replaced", path: target.path, backupPath } : { status: "profile-appended", path: target.path, ...backupPath ? { backupPath } : {} };
+}
+
+// src/nexus-service.ts
+var CREDENTIAL_PATH = "/api/nexus/credential";
+function describeFailure2(status, code) {
+  if (status === 401) {
+    return "PEP rejected the access token. Run `pep auth login` again.";
+  }
+  if (status === 403 && code === "32003") {
+    return "Your organisation's contract does not include Maven repository access. Contact your Newland representative \u2014 re-logging in will not change this.";
+  }
+  if (status === 403) {
+    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 organisation already has a Maven credential. PEP does not store the password, so it cannot be shown again \u2014 ask an operator to reset it in Nexus, or reuse the one you saved earlier.";
+  }
+  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.`;
+}
+async function errorCodeOf(response) {
+  try {
+    const body = await response.json();
+    return typeof body.code === "string" ? body.code : void 0;
+  } catch {
+    return void 0;
+  }
+}
+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"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(describeFailure2(response.status, await errorCodeOf(response)));
+  }
+  const body = await response.json();
+  const username = body.data?.username;
+  const password = body.data?.password;
+  if (typeof username !== "string" || typeof password !== "string") {
+    throw new Error("PEP returned a credential without a username or password.");
+  }
+  return { username, password };
+}
+async function setupNexusCredential(dependencies) {
+  const credential = await fetchNexusCredential(dependencies);
+  const target = dependencies.target ?? resolveTarget(dependencies.os);
+  const lines = exportLines(credential, dependencies.os);
+  const persisted = await persistMavenEnv(credential, target, dependencies.now).catch(
+    (error) => ({
+      status: "manual",
+      reason: error.message,
+      ...target.kind === "profile" ? { path: target.path } : {}
+    })
+  );
+  return { username: credential.username, lines, persisted };
+}
+
+// src/skills-service.ts
+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_zlib = require("node:zlib");
 
 // src/tar.ts
@@ -846,35 +1077,58 @@ function readTar(bytes) {
 
 // src/skills-service.ts
 var ARCHIVE_PATH = "/api/skills/archive";
-var SKILLS_SEGMENT = "skills";
+var SKILL_MANIFEST = "SKILL.md";
 function planSkillFiles(entries) {
-  const files = [];
+  const roots = [];
   for (const entry of entries) {
-    const segments = entry.path.split("/").filter((one) => one !== "" && one !== ".");
-    if (segments.some((one) => one === "..")) {
+    const segments = segmentsOf(entry.path);
+    if (segments.at(-1) !== SKILL_MANIFEST) continue;
+    const root = segments.slice(0, -1);
+    if (root.length < 2) continue;
+    roots.push(root);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const root of roots) {
+    const name = root[root.length - 1];
+    const where = root.join("/");
+    const first = seen.get(name);
+    if (first !== void 0) {
       throw new Error(
-        `Refusing an archive entry that escapes its directory: ${entry.path}`
+        `Two skills in this package would both be called "${name}": ${first} and ${where}. Skill names come from the directory name, so they must be unique within a package.`
       );
     }
-    const withoutRoot = segments.slice(1);
-    const relative2 = withoutRoot[0] === SKILLS_SEGMENT ? withoutRoot.slice(1) : withoutRoot;
-    if (relative2.length < 2) continue;
+    seen.set(name, where);
+  }
+  const files = [];
+  for (const entry of entries) {
+    const segments = segmentsOf(entry.path);
+    const root = roots.filter((r) => r.length < segments.length && r.every((seg, i) => segments[i] === seg)).sort((x, y) => y.length - x.length)[0];
+    if (!root) continue;
     files.push({
-      skill: relative2[0],
-      path: relative2.slice(1).join("/"),
+      skill: root[root.length - 1],
+      path: segments.slice(root.length).join("/"),
       data: entry.data
     });
   }
   return files;
 }
-function describeFailure2(status) {
+function segmentsOf(path) {
+  const segments = path.split("/").filter((one) => one !== "" && one !== ".");
+  if (segments.some((one) => one === "..")) {
+    throw new Error(`Refusing an archive entry that escapes its directory: ${path}`);
+  }
+  return segments;
+}
+function describeFailure3(status) {
   if (status === 401)
     return "PEP rejected the access token. Run `pep auth login` again.";
   if (status === 403) {
     return "This access token carries no `skills:read` 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 === 400)
+    return "PEP did not accept that repository address. It must be an https URL on the platform's GitLab host, or a <group>/<project> path on it.";
   if (status === 404) {
-    return "This PEP deployment does not serve skills \u2014 it has no /api/skills/archive endpoint. Ask an operator whether skills are enabled here.";
+    return "No such repository or ref on the platform's GitLab (or this PEP deployment has no /api/skills/archive endpoint at all). Check the address, then ask an operator whether skills are enabled here.";
   }
   if (status === 503) {
     return "PEP could not reach the skills repository. Retry shortly, or ask an operator whether this deployment serves skills.";
@@ -882,95 +1136,121 @@ function describeFailure2(status) {
   return `PEP answered ${status}.`;
 }
 async function physicalDir(path) {
-  const absolute = (0, import_node_path3.resolve)(path);
+  const absolute = (0, import_node_path4.resolve)(path);
   try {
-    return (0, import_node_path3.join)(await (0, import_promises3.realpath)((0, import_node_path3.dirname)(absolute)), (0, import_node_path3.basename)(absolute));
+    return (0, import_node_path4.join)(await (0, import_promises4.realpath)((0, import_node_path4.dirname)(absolute)), (0, import_node_path4.basename)(absolute));
   } catch {
     return absolute;
   }
 }
 async function linkSkill(canonicalSkillDir, linkPath) {
-  await (0, import_promises3.rm)(linkPath, { recursive: true, force: true });
-  const linkDir = (0, import_node_path3.dirname)(linkPath);
-  await (0, import_promises3.mkdir)(linkDir, { recursive: true });
+  await (0, import_promises4.rm)(linkPath, { recursive: true, force: true });
+  const linkDir = (0, import_node_path4.dirname)(linkPath);
+  await (0, import_promises4.mkdir)(linkDir, { recursive: true });
   try {
-    const junction = (0, import_node_os2.platform)() === "win32";
-    await (0, import_promises3.symlink)(
-      junction ? canonicalSkillDir : (0, import_node_path3.relative)(await physicalDir(linkDir), canonicalSkillDir),
+    const junction = (0, import_node_os3.platform)() === "win32";
+    await (0, import_promises4.symlink)(
+      junction ? canonicalSkillDir : (0, import_node_path4.relative)(await physicalDir(linkDir), canonicalSkillDir),
       linkPath,
       junction ? "junction" : void 0
     );
     return "linked";
   } catch {
-    await (0, import_promises3.cp)(canonicalSkillDir, linkPath, { recursive: true });
+    await (0, import_promises4.cp)(canonicalSkillDir, linkPath, { recursive: true });
     return "copied";
   }
 }
-async function syncSkills(dependencies) {
+function hashSkill(files) {
+  const hash = (0, import_node_crypto2.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");
+    hash.update(file.data);
+    hash.update("\0");
+  }
+  return hash.digest("hex").slice(0, 32);
+}
+async function updateSkills(dependencies) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
-  const response = await doFetch(`${dependencies.issuer}${ARCHIVE_PATH}`, {
+  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}` }
   });
   if (!response.ok) {
     await response.body?.cancel();
-    throw new Error(describeFailure2(response.status));
+    throw new Error(describeFailure3(response.status));
   }
   const commit = response.headers.get("x-skills-commit") ?? void 0;
-  const previous = await dependencies.stateStore.read();
-  if (commit !== void 0 && commit === previous?.commit && previous.directory === dependencies.directory) {
+  const state = await dependencies.stateStore.read();
+  const previous = state?.packages[name];
+  if (commit !== void 0 && commit === previous?.commit && state?.directory === dependencies.directory) {
     await response.body?.cancel();
-    return { status: "unchanged", commit };
+    return { status: "unchanged", name, commit };
   }
   const gzipped = new Uint8Array(await response.arrayBuffer());
   const files = planSkillFiles(readTar((0, import_node_zlib.gunzipSync)(gzipped)));
-  const skills = [...new Set(files.map((file) => file.skill))].sort();
+  const bySkill = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const group = bySkill.get(file.skill);
+    if (group) group.push(file);
+    else bySkill.set(file.skill, [file]);
+  }
+  const skills = [...bySkill.keys()].sort();
+  const hashes = {};
+  const updated = [];
+  const unchanged = [];
   for (const skill of skills) {
-    await (0, import_promises3.rm)((0, import_node_path3.join)(dependencies.directory, skill), {
-      recursive: true,
-      force: true
-    });
+    const hash = hashSkill(bySkill.get(skill));
+    hashes[skill] = hash;
+    const before = previous?.skills[skill];
+    if (before !== void 0 && before !== "" && before === hash) unchanged.push(skill);
+    else updated.push(skill);
+  }
+  for (const skill of skills) {
+    await (0, import_promises4.rm)((0, import_node_path4.join)(dependencies.directory, skill), { recursive: true, force: true });
   }
   for (const file of files) {
-    const target = (0, import_node_path3.join)(
-      dependencies.directory,
-      file.skill,
-      ...file.path.split("/")
-    );
-    await (0, import_promises3.mkdir)((0, import_node_path3.dirname)(target), { recursive: true });
-    await (0, import_promises3.writeFile)(target, file.data);
+    const target = (0, import_node_path4.join)(dependencies.directory, file.skill, ...file.path.split("/"));
+    await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(target), { recursive: true });
+    await (0, import_promises4.writeFile)(target, file.data);
   }
   let copiedCount = 0;
   if (dependencies.linkInto !== void 0) {
     for (const skill of skills) {
       const how = await linkSkill(
-        (0, import_node_path3.join)(dependencies.directory, skill),
-        (0, import_node_path3.join)(dependencies.linkInto, skill)
+        (0, import_node_path4.join)(dependencies.directory, skill),
+        (0, import_node_path4.join)(dependencies.linkInto, skill)
       );
       if (how === "copied") copiedCount += 1;
     }
   }
-  const removed = (previous?.skills ?? []).filter(
-    (skill) => !skills.includes(skill)
-  );
+  const removed = Object.keys(previous?.skills ?? {}).filter((skill) => !skills.includes(skill));
   for (const skill of removed) {
-    await (0, import_promises3.rm)((0, import_node_path3.join)(previous?.directory ?? dependencies.directory, skill), {
+    await (0, import_promises4.rm)((0, import_node_path4.join)(state?.directory ?? dependencies.directory, skill), {
       recursive: true,
       force: true
     });
-    if (previous?.linkedInto !== void 0) {
-      await (0, import_promises3.rm)((0, import_node_path3.join)(previous.linkedInto, skill), { recursive: true, force: true });
+    if (state?.linkedInto !== void 0) {
+      await (0, import_promises4.rm)((0, import_node_path4.join)(state.linkedInto, skill), { recursive: true, force: true });
     }
   }
-  const state = {
-    version: 1,
-    skills,
+  await dependencies.stateStore.write({
+    version: 3,
     directory: dependencies.directory,
     ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
-    ...commit ? { commit } : {}
-  };
-  await dependencies.stateStore.write(state);
+    packages: {
+      // 别的包的账原样留着 —— 装 B 不该把 A 的记录抹掉，那会让 A 铺的目录从此没人清理。
+      ...state?.packages ?? {},
+      [name]: { ...commit ? { commit } : {}, skills: hashes }
+    }
+  });
   return {
     status: "written",
+    name,
+    updated,
+    unchanged,
     skills,
     fileCount: files.length,
     removed,
@@ -980,9 +1260,13 @@ async function syncSkills(dependencies) {
     ...commit ? { commit } : {}
   };
 }
+async function installedPackages(store) {
+  const state = await store.read();
+  return Object.keys(state?.packages ?? {}).sort();
+}
 
 // src/cli.ts
-var VERSION = "0.1.3";
+var VERSION = "0.3.0";
 function usage() {
   return `PEP CLI ${VERSION}
 
@@ -991,9 +1275,12 @@ Usage:
   pep auth status
   pep auth token
   pep auth logout
-  pep skills sync [--dir <path>]
+  pep skills list
+  pep skills add <repo-url | group/project[@ref]> [--dir <path>]
+  pep skills update [<repo>...] [--dir <path>]
   pep docs list [--docs-url <url>]
   pep docs get <path> [--docs-url <url>]
+  pep nexus setup
 
 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.
@@ -1002,7 +1289,21 @@ one. It defaults to the docs platform \u2014 a token minted without it is reject
 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 sync\` fetches the latest skills from PEP and writes them to the shared agent
+\`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
@@ -1014,7 +1315,38 @@ 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.`;
+site is built in (${DEFAULT_DOCS_URL}); --docs-url overrides it and is then remembered.
+
+\`pep nexus setup\` asks PEP for this organisation's 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, so the two lines
+are also printed on stdout: \`eval "$(pep nexus setup)"\` uses them in the current one.
+Only Android needs this \u2014 the Windows and iOS SDKs are cloned from Git, not pulled from Maven.
+The password is shown by PEP once and never stored, so a second run reports 409 rather than
+handing it out again.`;
+}
+function reportUpdate(result) {
+  if (result.status === "unchanged") {
+    console.log(`${result.name}: already at ${result.commit}. Nothing to do.`);
+    return;
+  }
+  console.log(
+    result.updated.length > 0 ? `${result.name}: updated ${result.updated.join(" ")}` : `${result.name}: no skill changed (the repository moved, but not these)`
+  );
+  if (result.unchanged.length > 0) {
+    console.log(`  unchanged: ${result.unchanged.join(" ")}`);
+  }
+  console.log(`  ${result.fileCount} file(s) in ${result.directory}`);
+  if (result.linkedInto !== void 0) {
+    console.log(
+      result.copiedCount === void 0 ? `  linked into ${result.linkedInto} for Claude Code` : `  linked into ${result.linkedInto} for Claude Code (${result.copiedCount} copied instead \u2014 links unavailable here)`
+    );
+  }
+  if (result.commit) console.log(`  commit: ${result.commit}`);
+  if (result.removed.length > 0)
+    console.log(`  removed (gone upstream): ${result.removed.join(" ")}`);
 }
 function repeatedOption(args, name) {
   const values = [];
@@ -1062,7 +1394,7 @@ async function main() {
     return;
   }
   const group = args.shift();
-  if (group !== "auth" && group !== "skills" && group !== "docs")
+  if (group !== "auth" && group !== "skills" && group !== "docs" && group !== "nexus")
     throw new Error(`Unknown command.
 
 ${usage()}`);
@@ -1104,36 +1436,86 @@ ${usage()}`);
     process.stdout.write(await fetchDocContent(dependencies, path));
     return;
   }
-  if (group === "skills") {
-    if (command !== "sync") throw new Error(`Unknown skills command.
+  if (group === "nexus") {
+    if (command !== "setup") throw new Error(`Unknown nexus command.
 
 ${usage()}`);
-    const explicitDirectory = option(args, "--dir");
-    const directory = explicitDirectory ?? defaultSkillsDirectory();
     if (args.length > 0) throw new Error(`Unknown option: ${args[0]}`);
     const authorization = await auth.currentAuthorization();
-    const result = await syncSkills({
+    const result = await setupNexusCredential({
       issuer: authorization.issuer,
-      accessToken: authorization.accessToken,
-      directory,
-      ...explicitDirectory === void 0 ? { linkInto: claudeSkillsDirectory() } : {},
-      stateStore: fileSkillsStateStore()
+      accessToken: authorization.accessToken
     });
-    if (result.status === "unchanged") {
-      console.log(`Already at ${result.commit}. Nothing to do.`);
+    console.log(result.lines);
+    const persisted = result.persisted;
+    if (persisted.status === "windows") {
+      console.error(`Saved ${USERNAME_VAR} and ${PASSWORD_VAR} to your Windows user environment.`);
+      console.error("Existing terminals do not see them \u2014 open a new one (or use the lines above).");
+    } else if (persisted.status === "manual") {
+      console.error(
+        `Nothing was written${persisted.path ? ` to ${persisted.path}` : ""}: ${persisted.reason}`
+      );
+      console.error("The two lines above are the only copy \u2014 PEP does not store the password.");
+    } else {
+      console.error(
+        persisted.status === "profile-replaced" ? `Replaced the pep-cli block in ${persisted.path}` : `Appended a pep-cli block to ${persisted.path}`
+      );
+      if (persisted.backupPath) console.error(`Backup: ${persisted.backupPath}`);
+      console.error("New shells will have it; this one will not until you re-source the profile.");
+    }
+    console.error(`Nexus user: ${result.username}`);
+    return;
+  }
+  if (group === "skills") {
+    if (command !== "update" && command !== "add" && command !== "list") {
+      throw new Error(`Unknown skills command.
+
+${usage()}`);
+    }
+    const requested = command === "add" ? args.shift() : void 0;
+    const named = command === "update" ? args.filter((one) => !one.startsWith("--")) : [];
+    for (const one of named) args.splice(args.indexOf(one), 1);
+    if (command === "add" && !requested) {
+      throw new Error("pep skills add needs a repository: a full https URL, or <group>/<project>.");
+    }
+    const explicitDirectory = command === "list" ? void 0 : option(args, "--dir");
+    const directory = explicitDirectory ?? defaultSkillsDirectory();
+    if (args.length > 0) throw new Error(`Unknown option: ${args[0]}`);
+    const authorization = await auth.currentAuthorization();
+    const remote = { issuer: authorization.issuer, accessToken: authorization.accessToken };
+    if (command === "list") {
+      const installed2 = await installedPackages(fileSkillsStateStore());
+      if (installed2.length === 0) {
+        console.error("Nothing added yet. Run `pep skills add <repo>`.");
+        return;
+      }
+      for (const one of installed2) console.log(one);
+      console.error("\n`pep skills update` refreshes all of them.");
       return;
     }
-    console.log(
-      `Wrote ${result.fileCount} file(s) across ${result.skills.length} skill(s) to ${result.directory}`
-    );
-    if (result.linkedInto !== void 0) {
-      console.log(
-        result.copiedCount === void 0 ? `Linked into ${result.linkedInto} for Claude Code` : `Linked into ${result.linkedInto} for Claude Code (${result.copiedCount} copied instead \u2014 links unavailable here)`
+    const stateStore = fileSkillsStateStore();
+    const installed = await installedPackages(stateStore);
+    const targets = command === "add" ? [requested] : named.length > 0 ? named : installed;
+    if (targets.length === 0) {
+      console.error("Nothing added yet. Run `pep skills add <repo>`.");
+      return;
+    }
+    const unknown = named.filter((one) => !installed.includes(one));
+    if (unknown.length > 0) {
+      throw new Error(
+        `Not added yet: ${unknown.join(" ")}. Run \`pep skills add <repo>\` first, or \`pep skills list\` to see what is.`
       );
     }
-    if (result.commit) console.log(`Commit: ${result.commit}`);
-    if (result.removed.length > 0)
-      console.log(`Removed (gone upstream): ${result.removed.join(" ")}`);
+    for (const source of targets) {
+      const result = await updateSkills({
+        ...remote,
+        source,
+        directory,
+        ...explicitDirectory === void 0 ? { linkInto: claudeSkillsDirectory() } : {},
+        stateStore
+      });
+      reportUpdate(result);
+    }
     return;
   }
   if (command === "login") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newlandnpt/pep-cli",
-  "version": "0.1.3",
+  "version": "0.3.1",
   "description": "PEP CLI —— 凭 PEP 身份读取 Newland 开发者文档与 agent skills",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "build:installer": "node scripts/build-installer.mjs production",
     "build:installer:dev": "node scripts/build-installer.mjs development",
     "build:installer:prod": "node scripts/build-installer.mjs production",
-    "prepack": "node scripts/build-js.mjs production",
+    "prepack": "node scripts/build-js.mjs development",
     "build:exe:view": "node scripts/build-exe.mjs view",
     "build:installer:view": "node scripts/build-installer.mjs view"
   },