@newlandnpt/pep-cli 0.9.1 → 0.9.3

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");
@@ -684,8 +684,9 @@ public static class PepCredential {
 function encodedPowerShell(script) {
   return Buffer.from(script, "utf16le").toString("base64");
 }
+var CREDENTIAL_TOOL_TIMEOUT_MS = 6e4;
 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",
       [
@@ -699,7 +700,11 @@ async function runPowerShell(script, input) {
     );
     let stdout = "";
     let stderr = "";
-    const timeout = setTimeout(() => child.kill(), 1e4);
+    let killed = false;
+    const timeout = setTimeout(() => {
+      killed = true;
+      child.kill();
+    }, CREDENTIAL_TOOL_TIMEOUT_MS);
     child.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
     child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
     child.once(
@@ -708,7 +713,15 @@ async function runPowerShell(script, input) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      if (code === 0) resolve4(stdout.trim());
+      if (killed) {
+        reject(
+          new Error(
+            `Windows Credential Manager did not answer within ${CREDENTIAL_TOOL_TIMEOUT_MS / 1e3}s. The machine may be heavily loaded \u2014 try again.`
+          )
+        );
+        return;
+      }
+      if (code === 0) resolve5(stdout.trim());
       else
         reject(
           new Error(
@@ -762,13 +775,17 @@ $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"]
     });
     let stdout = "";
     let stderr = "";
-    const timeout = setTimeout(() => child.kill(), 1e4);
+    let killed = false;
+    const timeout = setTimeout(() => {
+      killed = true;
+      child.kill();
+    }, CREDENTIAL_TOOL_TIMEOUT_MS);
     child.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
     child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
     child.once(
@@ -777,7 +794,15 @@ async function runSecurity(args) {
     );
     child.once("close", (code) => {
       clearTimeout(timeout);
-      resolve4({ code: code ?? -1, stdout, stderr });
+      if (killed) {
+        reject(
+          new Error(
+            `macOS Keychain did not answer within ${CREDENTIAL_TOOL_TIMEOUT_MS / 1e3}s. The machine may be heavily loaded \u2014 try again.`
+          )
+        );
+        return;
+      }
+      resolve5({ code: code ?? -1, stdout, stderr });
     });
   });
 }
@@ -874,6 +899,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 +927,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 +981,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 +998,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 +1021,251 @@ 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");
+}
+function humanBytes(n) {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB"];
+  let value = n / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+function formatProgress(progress, width = 24) {
+  if (progress.phase === "verifying") return "  verifying\u2026";
+  const { bytes, total, elapsedMs } = progress;
+  const speed = elapsedMs > 0 && bytes > 0 ? `  \xB7  ${humanBytes(bytes / elapsedMs * 1e3)}/s` : "";
+  if (total === void 0 || total <= 0) {
+    return `  ${humanBytes(bytes)}${speed}`;
+  }
+  const ratio = Math.min(1, bytes / total);
+  const filled = Math.round(ratio * width);
+  const bar = `${"\u2588".repeat(filled)}${"\u2591".repeat(width - filled)}`;
+  const pct = `${Math.floor(ratio * 100)}`.padStart(3);
+  return `  ${bar} ${pct}%  ${humanBytes(bytes)} / ${humanBytes(total)}${speed}`;
+}
+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 {
+    const report = options.onProgress;
+    const startedAt = Date.now();
+    let seen = 0;
+    await (0, import_promises4.pipeline)(
+      import_node_stream.Readable.fromWeb(response.body),
+      // ⚠ 这一层**无条件**插着，没有回调时它只是加一个数。本来想「没人听就不插」，
+      //   但那要往 `pipeline(...)` 里展开一个数组，TS 的重载当场推不出来；为省一层
+      //   generator 去跟类型较劲不划算。
+      async function* (source) {
+        for await (const chunk of source) {
+          seen += chunk.length;
+          report?.({
+            phase: "downloading",
+            bytes: seen,
+            ...Number.isFinite(declared) && declared > 0 ? { total: declared } : {},
+            elapsedMs: Date.now() - startedAt
+          });
+          yield chunk;
+        }
+      },
+      (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) {
+      options.onProgress?.({ phase: "verifying" });
+      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 +1276,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 +1344,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 +1356,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 +1365,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 +1376,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 +1501,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 +1680,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 +1691,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 +1701,7 @@ FLAGS
 EXAMPLES
   pep setup
   pep docs list
+  pep resources list
   pep nexus setup --help
 
 LEARN MORE
@@ -1341,7 +1724,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 +1813,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
@@ -1592,8 +1975,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}`);
   }
 }
@@ -1696,32 +2079,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");
@@ -1758,9 +2141,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);
   }
@@ -1777,15 +2160,15 @@ async function outsidersAt(directory, skills, ours) {
   const blocked = [];
   for (const skill of skills) {
     if (ours.has(skill)) continue;
-    const path = (0, import_node_path4.join)(directory, skill);
-    if (await (0, import_promises4.stat)(path).catch(() => null)) blocked.push({ skill, path });
+    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;
 }
@@ -1899,14 +2282,14 @@ 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,
@@ -1915,17 +2298,17 @@ async function updateSkills(dependencies) {
   ]);
   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;
     }
@@ -2169,8 +2552,29 @@ async function planSetup(dependencies) {
 }
 
 // src/cli.ts
-var VERSION = false ? "0.0.0-dev" : "0.9.1";
+var VERSION = false ? "0.0.0-dev" : "0.9.3";
 var SKILLS_ADD_DEPRECATION = "\u26A0 `pep skills add` will be removed in a future release.";
+function createProgressReporter(stream = process.stderr) {
+  if (!stream.isTTY) return void 0;
+  const INTERVAL_MS = 100;
+  let lastAt = 0;
+  let painted = false;
+  const paint = (line) => {
+    stream.write(`\r${" ".repeat(78)}\r${line}`);
+    painted = true;
+  };
+  return {
+    report(progress) {
+      const now = Date.now();
+      if (progress.phase === "downloading" && now - lastAt < INTERVAL_MS) return;
+      lastAt = now;
+      paint(formatProgress(progress));
+    },
+    done() {
+      if (painted) stream.write(`\r${" ".repeat(78)}\r`);
+    }
+  };
+}
 function reportUpdate(result) {
   const conflicts = () => {
     for (const { skill, owner } of result.conflicts) {
@@ -2302,7 +2706,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 } : {} };
 }
@@ -2517,7 +2921,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)}`);
@@ -2527,25 +2932,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;
@@ -2555,7 +2994,45 @@ ${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 progress = createProgressReporter();
+      const result = await downloadResource(dependencies, target, {
+        // 默认落在**执行命令时的当前目录**，不是 CLI 装在哪儿。
+        directory: intoDirectory ?? process.cwd(),
+        force,
+        ...progress ? { onProgress: progress.report } : {}
+      });
+      progress?.done();
+      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.1",
+  "version": "0.9.3",
   "description": "PEP CLI —— 凭 PEP 身份读取 Newland 开发者文档与 agent skills",
   "license": "UNLICENSED",
   "type": "module",