@newlandnpt/pep-cli 0.9.0 → 0.9.2

package/dist/pep.cjs

@@ -305,12 +305,12 @@ async function waitForAuthorizationCallback(args) {
     throw new Error("CLI redirect URI must be an http://localhost URL with an explicit port.");
   }
   let server;
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const finish = (error, code) => {
       clearTimeout(timeout);
       server?.close();
       if (error) reject(error);
-      else resolve4(code);
+      else resolve5(code);
     };
     const timeout = setTimeout(
       () => finish(new Error("Login timed out while waiting for the browser callback.")),
@@ -353,7 +353,7 @@ async function waitForAuthorizationCallback(args) {
 function openBrowser(url) {
   const command = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
   const commandArgs = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = (0, import_node_child_process.spawn)(command, commandArgs, {
       detached: true,
       stdio: "ignore",
@@ -362,7 +362,7 @@ function openBrowser(url) {
     child.once("error", reject);
     child.once("spawn", () => {
       child.unref();
-      resolve4();
+      resolve5();
     });
   });
 }
@@ -473,7 +473,7 @@ var REFRESH_EARLY_MS = 60 * 1e3;
 var LOCK_STALE_MS = 30 * 1e3;
 var LOCK_WAIT_MS = 10 * 1e3;
 async function delay(milliseconds) {
-  await new Promise((resolve4) => setTimeout(resolve4, milliseconds));
+  await new Promise((resolve5) => setTimeout(resolve5, milliseconds));
 }
 async function releaseIfMine(path, stamp2) {
   try {
@@ -608,7 +608,7 @@ function createAuthService(dependencies) {
 }
 
 // src/cli.ts
-var import_node_path5 = require("node:path");
+var import_node_path6 = require("node:path");
 
 // src/credential-store.ts
 var import_node_child_process2 = require("node:child_process");
@@ -685,7 +685,7 @@ function encodedPowerShell(script) {
   return Buffer.from(script, "utf16le").toString("base64");
 }
 async function runPowerShell(script, input) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = (0, import_node_child_process2.spawn)(
       "powershell.exe",
       [
@@ -708,7 +708,7 @@ async function runPowerShell(script, input) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      if (code === 0) resolve4(stdout.trim());
+      if (code === 0) resolve5(stdout.trim());
       else
         reject(
           new Error(
@@ -762,7 +762,7 @@ $raw = [Console]::In.ReadToEnd()
 }
 var SECURITY_NOT_FOUND = 44;
 async function runSecurity(args) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = (0, import_node_child_process2.spawn)("/usr/bin/security", [...args], {
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -777,7 +777,7 @@ async function runSecurity(args) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      resolve4({ code: code ?? -1, stdout, stderr });
+      resolve5({ code: code ?? -1, stdout, stderr });
     });
   });
 }
@@ -874,6 +874,8 @@ async function fetchOrExplain(doFetch, url, init, what, timeoutMs = HEADERS_TIME
 
 // src/docs-service.ts
 var ENTRY = /^-\s*\[([^\]]*)\]\(([^)]+)\)(?::\s*(.*))?$/;
+var INDEX_PATH = "/llms.txt";
+var REGIONS_PATH = "/api/docs/regions";
 function parseDocsIndex(text) {
   const entries = [];
   for (const line of text.split("\n")) {
@@ -900,6 +902,50 @@ function contentPathFor(path) {
   const after = segments.slice(docsAt);
   return `/${[...before, "llms.mdx", ...after, "content.md"].join("/")}`;
 }
+async function fetchRegions(dependencies) {
+  const doFetch = dependencies.fetch ?? globalThis.fetch;
+  const response = await fetchOrExplain(
+    doFetch,
+    `${dependencies.docsUrl.replace(/\/+$/, "")}${REGIONS_PATH}`,
+    { headers: { Accept: "application/json" } },
+    "Could not reach the documentation platform"
+  );
+  if (!response.ok) {
+    await response.body?.cancel();
+    if (response.status === 404) {
+      throw new Error(
+        "This documentation deployment has no /api/docs/regions endpoint \u2014 it predates region support. Ask an operator to deploy a newer build."
+      );
+    }
+    throw new Error(describeFailure(response.status, REGIONS_PATH));
+  }
+  const body = await response.json();
+  const regions = body?.regions;
+  if (!Array.isArray(regions) || regions.length === 0) {
+    throw new Error("The documentation platform returned no regions.");
+  }
+  return body;
+}
+function resolveRegion(known, ref) {
+  const wanted = ref.trim().toLowerCase();
+  if (!wanted) return void 0;
+  return known.regions.find(
+    (region) => region.id.toLowerCase() === wanted || (region.aliases ?? []).some((alias) => alias.toLowerCase() === wanted)
+  );
+}
+function unknownRegion(known, ref) {
+  const names = known.regions.map((one) => one.aliases?.length ? `${one.id} (${one.aliases.join(", ")})` : one.id).join(", ");
+  return new Error(`No such documentation region: ${ref}. Available: ${names}.`);
+}
+function withRegion(path, region) {
+  const clean = `/${path.replace(/^\/+/, "").replace(/\/+$/, "")}`;
+  const segments = clean.split("/").filter(Boolean);
+  const marker = segments.findIndex((one) => one === "llms.mdx" || one === "docs");
+  if (marker === -1) {
+    throw new Error(`Not a documentation path (expected \u2026/docs/\u2026): ${path}`);
+  }
+  return `/${[region.id, region.defaultLanguage, ...segments.slice(marker)].join("/")}`;
+}
 function describeFailure(status, what) {
   if (status === 401) {
     return `The documentation platform rejected the access token. Run \`pep auth login\` again.`;
@@ -910,12 +956,15 @@ function describeFailure(status, what) {
   if (status === 404) {
     return `No such document, or your account cannot read it: ${what}`;
   }
+  if (status === 400) {
+    return `The documentation platform rejected that request: ${what}`;
+  }
   if (status === 502) {
     return "The documentation platform could not reach PEP to verify the token. Retry shortly.";
   }
   return `The documentation platform answered ${status} for ${what}.`;
 }
-async function get(dependencies, path, accept) {
+async function get(dependencies, path, accept, explain) {
   const doFetch = dependencies.fetch ?? globalThis.fetch;
   const response = await fetchOrExplain(
     doFetch,
@@ -924,13 +973,22 @@ async function get(dependencies, path, accept) {
     "Could not reach the documentation platform"
   );
   if (!response.ok) {
-    await response.body?.cancel();
-    throw new Error(describeFailure(response.status, path));
+    const custom = explain ? await explain(response) : void 0;
+    if (!response.bodyUsed) await response.body?.cancel().catch(() => void 0);
+    throw new Error(custom ?? describeFailure(response.status, path));
   }
   return response;
 }
-async function fetchDocsIndex(dependencies) {
-  const response = await get(dependencies, "/llms.txt", "text/plain");
+async function fetchDocsIndex(dependencies, region) {
+  const path = region === void 0 ? INDEX_PATH : `${INDEX_PATH}?site=${encodeURIComponent(region)}`;
+  const response = await get(dependencies, path, "text/plain", async (bad) => {
+    if (bad.status !== 400) return void 0;
+    const available = await bad.json().then((body) => body?.available).catch(() => void 0);
+    if (!Array.isArray(available) || available.length === 0) {
+      return `No such documentation region: ${region}.`;
+    }
+    return `No such documentation region: ${region}. Available: ${available.join(", ")}.`;
+  });
   return parseDocsIndex(await response.text());
 }
 async function fetchDocContent(dependencies, path) {
@@ -938,10 +996,208 @@ async function fetchDocContent(dependencies, path) {
   return response.text();
 }
 
-// src/maven-env.ts
+// src/docs-resources.ts
+var import_node_crypto3 = require("node:crypto");
+var import_node_fs = require("node:fs");
 var import_promises3 = require("node:fs/promises");
-var import_node_os2 = require("node:os");
 var import_node_path3 = require("node:path");
+var import_node_stream = require("node:stream");
+var import_promises4 = require("node:stream/promises");
+var RESOURCES_SLUG = "docs/Terminal/References/Developer-Resources";
+var PLATFORMS = ["Android", "Windows", "iOS"];
+function resolvePlatform(ref) {
+  const wanted = ref.trim().toLowerCase();
+  return PLATFORMS.find((one) => one.toLowerCase() === wanted);
+}
+function extractResourceLinks(markdown, platform3) {
+  const text = markdown.replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/<img\b[^>]*>/gi, "");
+  const found = [];
+  for (const match of text.matchAll(/\[[^\]]*\]\(([^)\s]+)/g)) {
+    const url = match[1];
+    if (url.startsWith("#")) continue;
+    const external = /^https?:\/\//i.test(url);
+    const pathPart = external ? safePath(url) : url;
+    if (pathPart === void 0) continue;
+    if (!external && !pathPart.startsWith("/assets/")) continue;
+    const inSitePool = pathPart.startsWith("/assets/");
+    const file = decodeURIComponent((0, import_node_path3.basename)(pathPart));
+    if (!file) continue;
+    found.push({ file, url, platforms: [platform3], external: external && !inSitePool });
+  }
+  return found;
+}
+function safePath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return void 0;
+  }
+}
+function mergeResources(all) {
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const one of all) {
+    const seen = byUrl.get(one.url);
+    if (!seen) {
+      byUrl.set(one.url, { ...one, platforms: [...one.platforms] });
+      continue;
+    }
+    for (const p of one.platforms) if (!seen.platforms.includes(p)) seen.platforms.push(p);
+  }
+  return [...byUrl.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+async function fetchResources(dependencies, platform3) {
+  const page = withRegion(`/${RESOURCES_SLUG}`, dependencies.region);
+  const wanted = platform3 ? [platform3] : [...PLATFORMS];
+  const all = [];
+  for (const one of wanted) {
+    const markdown = await fetchTab(dependencies, page, one);
+    all.push(...extractResourceLinks(markdown, one));
+  }
+  return mergeResources(all);
+}
+async function fetchTab(dependencies, page, platform3) {
+  const doFetch = dependencies.fetch ?? globalThis.fetch;
+  const url = new URL(
+    `${dependencies.docsUrl.replace(/\/+$/, "")}${contentPathFor(page)}`
+  );
+  url.searchParams.set("lang", platform3);
+  const response = await fetchOrExplain(
+    doFetch,
+    url,
+    {
+      headers: {
+        Authorization: `Bearer ${dependencies.accessToken}`,
+        Accept: "text/markdown"
+      }
+    },
+    "Could not read the developer resources page"
+  );
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => void 0);
+    if (response.status === 404) {
+      throw new Error(
+        `The developer resources page is not available to this account (or this region has no such page): ${page}`
+      );
+    }
+    throw new Error(`The documentation platform answered ${response.status} for ${page}.`);
+  }
+  return response.text();
+}
+function pickResource(all, file) {
+  const hits = all.filter((one) => one.file === file);
+  if (hits.length === 0) {
+    throw new Error(
+      `No such file on the developer resources page: ${file}. Run \`pep docs resources\` to see what is there.`
+    );
+  }
+  if (hits.length > 1) {
+    const urls = hits.map((one) => `  ${one.url}`).join("\n");
+    throw new Error(
+      `${file} appears more than once with different addresses:
+${urls}
+The page is ambiguous \u2014 ask an operator which one is current.`
+    );
+  }
+  const only = hits[0];
+  if (only.external) {
+    throw new Error(
+      `${file} is hosted outside the documentation platform (${only.url}). Open that page in a browser \u2014 pep does not send your PEP token to third parties.`
+    );
+  }
+  return only;
+}
+function expectedBlobSha(url) {
+  return /\/assets\/_shared\/([0-9a-f]{12})\//.exec(url)?.[1];
+}
+async function blobShaOfFile(path) {
+  const size = (await (0, import_promises3.stat)(path)).size;
+  const digest = (0, import_node_crypto3.createHash)("sha1").update(`blob ${size}\0`);
+  await (0, import_promises4.pipeline)((0, import_node_fs.createReadStream)(path), async function* (source) {
+    for await (const chunk of source) digest.update(chunk);
+  });
+  return digest.digest("hex");
+}
+async function downloadResource(dependencies, resource, options) {
+  const file = (0, import_node_path3.basename)(resource.file);
+  if (file !== resource.file || file === "." || file === "..") {
+    throw new Error(`Refusing to write a file named ${resource.file}.`);
+  }
+  const directory = (0, import_node_path3.resolve)(options.directory);
+  const target = (0, import_node_path3.resolve)(directory, file);
+  if (!target.startsWith(directory + "/") && !target.startsWith(directory + "\\")) {
+    throw new Error(`Refusing to write outside ${directory}.`);
+  }
+  if (!options.force && await (0, import_promises3.stat)(target).catch(() => null)) {
+    throw new Error(
+      `${target} already exists. Pass --force to replace it (the existing file is kept until the new one has downloaded completely).`
+    );
+  }
+  const doFetch = dependencies.fetch ?? globalThis.fetch;
+  const absolute = resource.url.startsWith("/") ? `${dependencies.docsUrl.replace(/\/+$/, "")}${resource.url}` : resource.url;
+  const response = await fetchOrExplain(
+    doFetch,
+    absolute,
+    { headers: { Authorization: `Bearer ${dependencies.accessToken}` } },
+    `Could not download ${file}`
+  );
+  if (!response.ok || !response.body) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new Error(describeDownloadFailure(response.status, file));
+  }
+  const declared = Number(response.headers.get("content-length") ?? "");
+  const expected = expectedBlobSha(resource.url);
+  await (0, import_promises3.mkdir)(directory, { recursive: true });
+  const temporary = `${target}.${process.pid}.part`;
+  try {
+    await (0, import_promises4.pipeline)(
+      import_node_stream.Readable.fromWeb(response.body),
+      (0, import_node_fs.createWriteStream)(temporary)
+    );
+    const bytes = (await (0, import_promises3.stat)(temporary)).size;
+    if (Number.isFinite(declared) && declared > 0 && bytes !== declared) {
+      throw new Error(
+        `${file} stopped after ${bytes} of ${declared} bytes. Nothing was written \u2014 run this again.`
+      );
+    }
+    let verified = "none";
+    if (expected !== void 0) {
+      const actual = (await blobShaOfFile(temporary)).slice(0, 12);
+      if (actual !== expected) {
+        throw new Error(
+          `${file} does not match the content hash in its address (expected ${expected}, got ${actual}). Nothing was written.`
+        );
+      }
+      verified = "blob-sha";
+    } else if (Number.isFinite(declared) && declared > 0) {
+      verified = "content-length";
+    }
+    await (0, import_promises3.rename)(temporary, target);
+    return { path: target, bytes, verified };
+  } catch (error) {
+    await (0, import_promises3.unlink)(temporary).catch(() => void 0);
+    throw error;
+  }
+}
+function describeDownloadFailure(status, file) {
+  if (status === 401) {
+    return "The documentation platform rejected the access token. Run `pep auth login` again.";
+  }
+  if (status === 403) {
+    return "This client is not allowed to read documentation \u2014 it needs the `docs:read` scope.";
+  }
+  if (status === 404) {
+    return `${file} is no longer on the documentation platform. Run \`pep docs resources\` for the current list.`;
+  }
+  if (status === 502) {
+    return "The documentation platform could not reach PEP to verify the token. Retry shortly.";
+  }
+  return `The documentation platform answered ${status} for ${file}.`;
+}
+
+// src/maven-env.ts
+var import_promises5 = require("node:fs/promises");
+var import_node_os2 = require("node:os");
+var import_node_path4 = 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);
@@ -952,7 +1208,7 @@ 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) };
+  return { kind: "profile", path: (0, import_node_path4.join)((0, import_node_os2.homedir)(), file) };
 }
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -1020,7 +1276,7 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
     }
     return { status: "windows" };
   }
-  const existing = await (0, import_promises3.readFile)(target.path, "utf8").catch((error) => {
+  const existing = await (0, import_promises5.readFile)(target.path, "utf8").catch((error) => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
@@ -1032,7 +1288,7 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
   if (existing !== null) {
     backupPath = `${target.path}.bak-${stamp(now())}`;
     try {
-      await (0, import_promises3.writeFile)(backupPath, existing, { encoding: "utf8", flag: "wx" });
+      await (0, import_promises5.writeFile)(backupPath, existing, { encoding: "utf8", flag: "wx" });
     } catch (error) {
       return {
         status: "manual",
@@ -1041,10 +1297,10 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
       };
     }
   }
-  const originalMode = await (0, import_promises3.stat)(target.path).then((info) => info.mode & 511).catch(() => 384);
+  const originalMode = await (0, import_promises5.stat)(target.path).then((info) => info.mode & 511).catch(() => 384);
   const temporary = `${target.path}.${process.pid}.tmp`;
-  await (0, import_promises3.writeFile)(temporary, plan.content, { encoding: "utf8", mode: originalMode });
-  await (0, import_promises3.rename)(temporary, target.path);
+  await (0, import_promises5.writeFile)(temporary, plan.content, { encoding: "utf8", mode: originalMode });
+  await (0, import_promises5.rename)(temporary, target.path);
   return plan.action === "replace" ? { status: "profile-replaced", path: target.path, backupPath } : { status: "profile-appended", path: target.path, ...backupPath ? { backupPath } : {} };
 }
 
@@ -1052,6 +1308,7 @@ async function persistMavenEnv(credential, target = resolveTarget(), now = () =>
 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 REGION_FLAG = "--region <id>      Documentation region for this run only (see pep docs regions)";
 var groups = {
   auth: {
     summary: "Sign in to PEP and manage your local authorization.",
@@ -1176,16 +1433,72 @@ pep skills update will not bring the skills back. Run pep skills add to do that.
       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"]
+        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.\n\nWithout --region you get the Global English documentation. The region applies to\nthis run only and is never remembered.",
+        flags: [
+          `--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`,
+          REGION_FLAG
+        ],
+        examples: [
+          "pep docs list",
+          "pep docs list --region na",
+          "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.",
+        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.\n\nThe path already names its region, so a path from pep docs list --region na reads\nthe North American version. Pass --region to read that same document from another\nregion instead.",
+        flags: [
+          `--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`,
+          REGION_FLAG
+        ],
+        examples: [
+          'pep docs get "<path-from-pep-docs-list>"',
+          'pep docs get "<path-from-pep-docs-list>" --region na',
+          'pep docs get "<path-from-pep-docs-list>" > document.md'
+        ]
+      },
+      regions: {
+        summary: "List the documentation regions this deployment serves.",
+        usage: "pep docs regions [flags]",
+        description: 'Prints one region per line: id, aliases, default language, name.\nThe list comes from the documentation server, so a region added there shows up\nwithout upgrading the CLI.\n\nThis is the one docs command that needs no login: "what do I pass to --region?"\nis a question you have before signing in.',
         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']
+        examples: ["pep docs regions"]
+      }
+    }
+  },
+  resources: {
+    summary: "List and download SDKs, demos and tools.",
+    commands: {
+      list: {
+        summary: "List the SDKs, demos and tools you can download.",
+        usage: "pep resources list [flags]",
+        description: 'Requires a saved PEP login. Prints one file per line: name, platforms, address.\nThe list is read from the documentation page itself, so a new release shows up as\nsoon as that page is updated \u2014 the CLI keeps no version list of its own.\n\nWithout --platform it reads all three platform tabs and merges them; a file that\nappears in several is listed once with every platform named. Entries marked\n"external" are hosted elsewhere and cannot be fetched with pep resources download.',
+        flags: [
+          `--platform <name>  Only this platform (${PLATFORMS.join(", ")})`,
+          REGION_FLAG,
+          `--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`
+        ],
+        examples: [
+          "pep resources list",
+          "pep resources list --platform windows",
+          "pep resources list --region na --platform android"
+        ]
+      },
+      download: {
+        summary: "Download a file from the developer resources page.",
+        usage: "pep resources download <file> [flags]",
+        description: "Requires a saved PEP login. Use a file name exactly as pep resources list prints\nit. Saves into the current directory unless --dir says otherwise, and prints the\nfull path of the finished file to stdout.\n\nThe download goes to a temporary file beside the target and is renamed only once\nit is complete and verified, so an interrupted run never leaves a half file \u2014 and\nwith --force your existing copy survives until the new one has arrived.\n\nWhere the address carries a content hash the downloaded bytes are checked against\nit; otherwise the declared length is checked. Which one happened is reported on\nstderr.",
+        flags: [
+          "--dir <path>       Directory to save into; created if missing (default: the current directory)",
+          "--force            Replace an existing file of the same name",
+          REGION_FLAG,
+          `--docs-url <url>   Documentation server; saved for later use (default: ${DEFAULT_DOCS_URL})`
+        ],
+        examples: [
+          "pep resources download SaleSystemDemo-4.8.0.2-win-x64.zip",
+          "pep resources download PayExplorerECRDemo.apk --region na --dir ./downloads"
+        ]
       }
     }
   },
@@ -1299,6 +1612,7 @@ ${flagBlock([...command.flags ?? [], "-h, --help  Show help for this command"])}
 EXAMPLES
 ${command.examples.map((example) => `  ${example}`).join("\n")}`;
 }
+var GROUP_NAMES = Object.keys(groups);
 function usage(version, path = []) {
   const [groupName, commandName] = path;
   if (!groupName) {
@@ -1309,8 +1623,8 @@ 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")}
+${Object.entries(topLevel).map(([name, command]) => `  ${name.padEnd(11)}${command.summary}`).join("\n")}
+${Object.entries(groups).map(([name, group2]) => `  ${name.padEnd(11)}${group2.summary}`).join("\n")}
 
 FLAGS
   -h, --help      Show help for a command
@@ -1319,6 +1633,7 @@ FLAGS
 EXAMPLES
   pep setup
   pep docs list
+  pep resources list
   pep nexus setup --help
 
 LEARN MORE
@@ -1341,7 +1656,7 @@ USAGE
   pep ${groupName} <command> [flags]
 
 COMMANDS
-${Object.entries(group.commands).map(([name, command]) => `  ${name.padEnd(10)}${command.summary}`).join("\n")}
+${Object.entries(group.commands).map(([name, command]) => `  ${name.padEnd(11)}${command.summary}`).join("\n")}
 
 FLAGS
   -h, --help   Show help for this command
@@ -1430,10 +1745,10 @@ async function setupNexusCredential(dependencies) {
 }
 
 // src/skills-service.ts
-var import_promises4 = require("node:fs/promises");
+var import_promises6 = require("node:fs/promises");
 var import_node_os3 = require("node:os");
-var import_node_path4 = require("node:path");
-var import_node_crypto3 = require("node:crypto");
+var import_node_path5 = require("node:path");
+var import_node_crypto4 = require("node:crypto");
 var import_node_zlib = require("node:zlib");
 
 // src/tar.ts
@@ -1524,6 +1839,11 @@ function tooBig(what, limit) {
   );
 }
 var SKILL_MANIFEST = "SKILL.md";
+function occupiedByOutsider(skill, path) {
+  return new Error(
+    `${path} already exists and pep did not install it. Installing "${skill}" would delete it, so this repository was left alone. Move that directory aside (or delete it yourself), then run this again \u2014 pep never overwrites what it does not track.`
+  );
+}
 function nameClash(owner, skill, directory) {
   return new Error(
     `${owner} already installs a skill named "${skill}" in ${directory}. Two repositories cannot both provide "${skill}" there \u2014 the second would silently overwrite the first. Install this one elsewhere (-p, or --dir <path>), or run \`pep skills remove ${owner}\` first.`
@@ -1587,8 +1907,8 @@ async function readCapped(response, limit) {
   return out;
 }
 function assertInside(base, target) {
-  const rel = (0, import_node_path4.relative)((0, import_node_path4.resolve)(base), (0, import_node_path4.resolve)(target));
-  if (rel === "" || rel.startsWith("..") || (0, import_node_path4.isAbsolute)(rel)) {
+  const rel = (0, import_node_path5.relative)((0, import_node_path5.resolve)(base), (0, import_node_path5.resolve)(target));
+  if (rel === "" || rel.startsWith("..") || (0, import_node_path5.isAbsolute)(rel)) {
     throw new Error(`Refusing an archive entry that escapes its directory: ${target}`);
   }
 }
@@ -1691,32 +2011,32 @@ function groupMemberPath(ledgerKey, group) {
   return path;
 }
 async function physicalDir(path) {
-  const absolute = (0, import_node_path4.resolve)(path);
+  const absolute = (0, import_node_path5.resolve)(path);
   try {
-    return (0, import_node_path4.join)(await (0, import_promises4.realpath)((0, import_node_path4.dirname)(absolute)), (0, import_node_path4.basename)(absolute));
+    return (0, import_node_path5.join)(await (0, import_promises6.realpath)((0, import_node_path5.dirname)(absolute)), (0, import_node_path5.basename)(absolute));
   } catch {
     return absolute;
   }
 }
 async function linkSkill(canonicalSkillDir, linkPath) {
-  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 });
+  await (0, import_promises6.rm)(linkPath, { recursive: true, force: true });
+  const linkDir = (0, import_node_path5.dirname)(linkPath);
+  await (0, import_promises6.mkdir)(linkDir, { recursive: true });
   try {
     const junction = (0, import_node_os3.platform)() === "win32";
-    await (0, import_promises4.symlink)(
-      junction ? canonicalSkillDir : (0, import_node_path4.relative)(await physicalDir(linkDir), canonicalSkillDir),
+    await (0, import_promises6.symlink)(
+      junction ? canonicalSkillDir : (0, import_node_path5.relative)(await physicalDir(linkDir), canonicalSkillDir),
       linkPath,
       junction ? "junction" : void 0
     );
     return "linked";
   } catch {
-    await (0, import_promises4.cp)(canonicalSkillDir, linkPath, { recursive: true });
+    await (0, import_promises6.cp)(canonicalSkillDir, linkPath, { recursive: true });
     return "copied";
   }
 }
 function hashSkill(files) {
-  const hash = (0, import_node_crypto3.createHash)("sha256");
+  const hash = (0, import_node_crypto4.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");
@@ -1753,9 +2073,9 @@ async function removeSkills(name, store) {
       keptForOthers.push({ skill, owner });
       continue;
     }
-    await (0, import_promises4.rm)((0, import_node_path4.join)(pkg.directory, skill), { recursive: true, force: true });
+    await (0, import_promises6.rm)((0, import_node_path5.join)(pkg.directory, skill), { recursive: true, force: true });
     if (pkg.linkedInto !== void 0) {
-      await (0, import_promises4.rm)((0, import_node_path4.join)(pkg.linkedInto, skill), { recursive: true, force: true });
+      await (0, import_promises6.rm)((0, import_node_path5.join)(pkg.linkedInto, skill), { recursive: true, force: true });
     }
     deleted.push(skill);
   }
@@ -1768,10 +2088,19 @@ function pickSkipped(previous, skipped) {
     skipped.map((skill) => [skill, previous?.skills[skill] ?? ""])
   );
 }
+async function outsidersAt(directory, skills, ours) {
+  const blocked = [];
+  for (const skill of skills) {
+    if (ours.has(skill)) continue;
+    const path = (0, import_node_path5.join)(directory, skill);
+    if (await (0, import_promises6.stat)(path).catch(() => null)) blocked.push({ skill, path });
+  }
+  return blocked;
+}
 async function missingSkills(directory, skills) {
   const gone = /* @__PURE__ */ new Set();
   for (const skill of skills) {
-    if (!await (0, import_promises4.stat)((0, import_node_path4.join)(directory, skill)).catch(() => null)) gone.add(skill);
+    if (!await (0, import_promises6.stat)((0, import_node_path5.join)(directory, skill)).catch(() => null)) gone.add(skill);
   }
   return gone;
 }
@@ -1809,7 +2138,14 @@ async function updateSkills(dependencies) {
   }
   if (commit !== void 0 && commit === previous?.commit && sameTarget && nothingToRestore) {
     await response.body?.cancel();
-    return { status: "unchanged", name, commit, conflicts: standing, skipped: [...gone] };
+    return {
+      status: "unchanged",
+      name,
+      commit,
+      conflicts: standing,
+      skipped: [...gone],
+      blocked: []
+    };
   }
   const gzipped = await readCapped(response, dependencies.maxArchiveBytes ?? MAX_ARCHIVE_BYTES);
   let unpacked;
@@ -1844,7 +2180,22 @@ async function updateSkills(dependencies) {
     if (dependencies.restoreMissing) throw nameClash(owner, skill, dependencies.directory);
     conflicts.push({ skill, owner });
   }
-  const skills = candidates.filter((skill) => !conflicts.some((one) => one.skill === skill));
+  const unclashed = candidates.filter((skill) => !conflicts.some((one) => one.skill === skill));
+  const ours = new Set(
+    sameTarget ? Object.keys(previous?.skills ?? {}) : []
+  );
+  const blocked = [];
+  for (const one of [
+    ...await outsidersAt(dependencies.directory, unclashed, ours),
+    ...dependencies.linkInto !== void 0 ? await outsidersAt(dependencies.linkInto, unclashed, ours) : []
+  ]) {
+    if (!blocked.some((seen) => seen.skill === one.skill)) blocked.push(one);
+  }
+  if (dependencies.restoreMissing && blocked.length > 0) {
+    const [first] = blocked;
+    throw occupiedByOutsider(first.skill, first.path);
+  }
+  const skills = unclashed.filter((skill) => !blocked.some((one) => one.skill === skill));
   const hashes = {};
   const updated = [];
   const unchanged = [];
@@ -1863,29 +2214,33 @@ async function updateSkills(dependencies) {
       if (otherClaimant(state?.packages ?? {}, name, previous.directory, skill)) continue;
       const stalePlace = deletableLedgerDirectory(previous.directory);
       if (stalePlace === void 0) continue;
-      await (0, import_promises4.rm)((0, import_node_path4.join)(stalePlace, skill), { recursive: true, force: true });
+      await (0, import_promises6.rm)((0, import_node_path5.join)(stalePlace, skill), { recursive: true, force: true });
       if (previous.linkedInto !== void 0) {
-        await (0, import_promises4.rm)((0, import_node_path4.join)(previous.linkedInto, skill), { recursive: true, force: true });
+        await (0, import_promises6.rm)((0, import_node_path5.join)(previous.linkedInto, skill), { recursive: true, force: true });
       }
     }
   }
   for (const skill of skills) {
-    await (0, import_promises4.rm)((0, import_node_path4.join)(dependencies.directory, skill), { recursive: true, force: true });
+    await (0, import_promises6.rm)((0, import_node_path5.join)(dependencies.directory, skill), { recursive: true, force: true });
   }
-  const untouched = /* @__PURE__ */ new Set([...skipped, ...conflicts.map((one) => one.skill)]);
+  const untouched = /* @__PURE__ */ new Set([
+    ...skipped,
+    ...conflicts.map((one) => one.skill),
+    ...blocked.map((one) => one.skill)
+  ]);
   for (const file of files) {
     if (untouched.has(file.skill)) continue;
-    const target = (0, import_node_path4.join)(dependencies.directory, file.skill, ...file.path.split("/"));
+    const target = (0, import_node_path5.join)(dependencies.directory, file.skill, ...file.path.split("/"));
     assertInside(dependencies.directory, target);
-    await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(target), { recursive: true });
-    await (0, import_promises4.writeFile)(target, file.data);
+    await (0, import_promises6.mkdir)((0, import_node_path5.dirname)(target), { recursive: true });
+    await (0, import_promises6.writeFile)(target, file.data);
   }
   let copiedCount = 0;
   if (dependencies.linkInto !== void 0) {
     for (const skill of skills) {
       const how = await linkSkill(
-        (0, import_node_path4.join)(dependencies.directory, skill),
-        (0, import_node_path4.join)(dependencies.linkInto, skill)
+        (0, import_node_path5.join)(dependencies.directory, skill),
+        (0, import_node_path5.join)(dependencies.linkInto, skill)
       );
       if (how === "copied") copiedCount += 1;
     }
@@ -1923,6 +2278,7 @@ async function updateSkills(dependencies) {
     removed,
     skipped,
     conflicts,
+    blocked,
     directory: dependencies.directory,
     ...dependencies.linkInto !== void 0 ? { linkedInto: dependencies.linkInto } : {},
     ...copiedCount > 0 ? { copiedCount } : {},
@@ -2128,7 +2484,7 @@ async function planSetup(dependencies) {
 }
 
 // src/cli.ts
-var VERSION = false ? "0.0.0-dev" : "0.9.0";
+var VERSION = false ? "0.0.0-dev" : "0.9.2";
 var SKILLS_ADD_DEPRECATION = "\u26A0 `pep skills add` will be removed in a future release.";
 function reportUpdate(result) {
   const conflicts = () => {
@@ -2137,6 +2493,12 @@ function reportUpdate(result) {
       console.error(`    each other. \`pep skills remove\` one of them to settle it.`);
     }
   };
+  const blocked = () => {
+    for (const { skill, path } of result.blocked) {
+      console.error(`  \u26A0 "${skill}" was not installed \u2014 ${path} already exists`);
+      console.error(`    and pep did not put it there. Move it aside, then run this again.`);
+    }
+  };
   const skipped = (list, name) => {
     if (list.length === 0) return;
     console.log(`  deleted locally, left alone: ${list.join(" ")}`);
@@ -2146,6 +2508,7 @@ function reportUpdate(result) {
     console.log(`${result.name}: already at ${result.commit}. Nothing to do.`);
     skipped(result.skipped, result.name);
     conflicts();
+    blocked();
     return;
   }
   console.log(
@@ -2156,6 +2519,7 @@ function reportUpdate(result) {
   }
   skipped(result.skipped, result.name);
   conflicts();
+  blocked();
   console.log(`  ${result.fileCount} file(s) in ${result.directory}`);
   if (result.linkedInto !== void 0) {
     console.log(
@@ -2253,7 +2617,7 @@ function parseSkillsArgs(command, args, cwd) {
     //   `rm -rf` 到 B 头上。`--project` 没有这个问题，因为它走 `join(cwd, …)`。
     //   基准用 `cwd` 而不是 `process.cwd()`：与同一处的 `projectSkillsTarget(cwd)` 同源，
     //   也让这条分支可测。
-    { directory: (0, import_node_path5.resolve)(cwd ?? process.cwd(), explicitDirectory) }
+    { directory: (0, import_node_path6.resolve)(cwd ?? process.cwd(), explicitDirectory) }
   ) : project ? projectSkillsTarget(cwd) : void 0;
   return { ...requested !== void 0 ? { requested } : {}, named, ...chosenTarget ? { chosenTarget } : {} };
 }
@@ -2468,7 +2832,8 @@ ${url}`)
     if (failure) throw new Error(failure);
     return;
   }
-  if (group !== "auth" && group !== "skills" && group !== "docs" && group !== "nexus")
+  const GROUPS = ["auth", "skills", "docs", "resources", "nexus"];
+  if (group === void 0 || !GROUPS.includes(group))
     throw new Error(`Unknown command.
 
 ${usage(VERSION)}`);
@@ -2478,25 +2843,59 @@ ${usage(VERSION)}`);
     return;
   }
   const { configStore, auth } = createCliServices();
-  if (group === "docs") {
-    if (command !== "list" && command !== "get") {
-      throw new Error(`Unknown docs command.
+  if (group === "docs" || group === "resources") {
+    const allowed = group === "docs" ? ["list", "get", "regions"] : ["list", "download"];
+    if (!allowed.includes(command)) {
+      throw new Error(`Unknown ${group} command.
 
-${usage(VERSION, ["docs"])}`);
+${usage(VERSION, [group])}`);
     }
+    const action = `${group}:${command}`;
     const explicitDocsUrl = option(args, "--docs-url");
-    const path = command === "get" ? args.shift() : void 0;
+    const region = option(args, "--region");
+    const platform3 = option(args, "--platform");
+    const intoDirectory = option(args, "--dir");
+    const force = flag(args, "--force");
+    const path = action === "docs:get" ? args.shift() : void 0;
+    const wantedFile = action === "resources:download" ? args.shift() : void 0;
     if (args.length > 0) throw new Error(`Unknown option: ${args[0]}`);
-    if (command === "get" && !path) throw new Error("pep docs get needs a document path.");
+    if (action === "docs:get" && !path) throw new Error("pep docs get needs a document path.");
+    if (action === "docs:regions" && region !== void 0) {
+      throw new Error("pep docs regions lists every region \u2014 it takes no --region.");
+    }
+    if (action === "resources:download" && !wantedFile) {
+      throw new Error(
+        "pep resources download needs a file name. Run `pep resources list` to see what is there."
+      );
+    }
+    if (platform3 !== void 0 && group !== "resources") {
+      throw new Error(`pep ${group} ${command} takes no --platform.`);
+    }
+    if ((intoDirectory !== void 0 || force) && action !== "resources:download") {
+      throw new Error(`pep ${group} ${command} takes no --dir or --force.`);
+    }
+    const wantedPlatform = platform3 === void 0 ? void 0 : resolvePlatform(platform3);
+    if (platform3 !== void 0 && wantedPlatform === void 0) {
+      throw new Error(`No such platform: ${platform3}. Available: ${PLATFORMS.join(", ")}.`);
+    }
     const saved = await configStore.read();
     const docsUrl = explicitDocsUrl ? normalizeDocsUrl(explicitDocsUrl) : saved?.docsUrl ?? DEFAULT_DOCS_URL;
     if (explicitDocsUrl && saved && saved.docsUrl !== docsUrl) {
       await configStore.write({ ...saved, docsUrl });
     }
+    if (action === "docs:regions") {
+      const known = await fetchRegions({ docsUrl });
+      for (const one of known.regions) {
+        const aliases = one.aliases?.length ? `	${one.aliases.join(",")}` : "	";
+        const mark = one.id === known.defaultRegion ? "	(default)" : "";
+        console.log(`${one.id}${aliases}	${one.defaultLanguage}	${one.name}${mark}`);
+      }
+      return;
+    }
     const authorization = await auth.currentAuthorization();
     const dependencies = { docsUrl, accessToken: authorization.accessToken };
-    if (command === "list") {
-      const entries = await fetchDocsIndex(dependencies);
+    if (action === "docs:list") {
+      const entries = await fetchDocsIndex(dependencies, region);
       if (entries.length === 0) {
         console.error("No documents are readable with this account.");
         return;
@@ -2506,7 +2905,42 @@ ${usage(VERSION, ["docs"])}`);
       }
       return;
     }
-    process.stdout.write(await fetchDocContent(dependencies, path));
+    if (group === "resources") {
+      const known = await fetchRegions({ docsUrl });
+      const picked = region === void 0 ? resolveRegion(known, known.defaultRegion) : resolveRegion(known, region);
+      if (!picked) throw unknownRegion(known, region ?? known.defaultRegion);
+      const all = await fetchResources({ ...dependencies, region: picked }, wantedPlatform);
+      if (action === "resources:list") {
+        if (all.length === 0) {
+          console.error("The developer resources page lists no files.");
+          return;
+        }
+        for (const one of all) {
+          const where = one.external ? "external" : one.platforms.join(",");
+          console.log(`${one.file}	${where}	${one.url}`);
+        }
+        return;
+      }
+      const target = pickResource(all, wantedFile);
+      const result = await downloadResource(dependencies, target, {
+        // 默认落在**执行命令时的当前目录**，不是 CLI 装在哪儿。
+        directory: intoDirectory ?? process.cwd(),
+        force
+      });
+      console.error(
+        result.verified === "blob-sha" ? `  ${result.bytes} bytes, content hash verified` : result.verified === "content-length" ? `  ${result.bytes} bytes, length verified (no content hash in the address)` : `  ${result.bytes} bytes \u2014 the server declared neither length nor content hash`
+      );
+      console.log(result.path);
+      return;
+    }
+    let wanted = path;
+    if (region !== void 0) {
+      const known = await fetchRegions({ docsUrl });
+      const picked = resolveRegion(known, region);
+      if (!picked) throw unknownRegion(known, region);
+      wanted = withRegion(wanted, picked);
+    }
+    process.stdout.write(await fetchDocContent(dependencies, wanted));
     return;
   }
   if (group === "nexus") {

package/package.json

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