@newlandnpt/pep-cli 0.1.3 → 0.3.0

package/dist/pep.cjs

@@ -11,8 +11,16 @@ 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";
@@ -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.0",
   "description": "PEP CLI —— 凭 PEP 身份读取 Newland 开发者文档与 agent skills",
   "license": "UNLICENSED",
   "type": "module",