@p11-core/cli 0.0.8 → 0.0.10

package/dist/index.js

@@ -3521,7 +3521,12 @@ var docsTopics = /* @__PURE__ */ new Map([
   ["components", "docs/components.md"],
   ["sharing", "docs/sharing.md"]
 ]);
-var exampleFiles = /* @__PURE__ */ new Map([["all-components", "examples/all-components.tsx"]]);
+var exampleFiles = /* @__PURE__ */ new Map([
+  ["minimal", "examples/minimal.tsx"],
+  ["all", "examples/all-components.tsx"],
+  ["all-components", "examples/all-components.tsx"]
+]);
+var publicExampleNames = ["minimal", "all"];
 var allowedDocumentComponents = /* @__PURE__ */ new Set([
   "Document",
   "Page",
@@ -3625,6 +3630,11 @@ async function main() {
     return;
   }
   const command = process.argv[2];
+  if (isVersionFlag(command)) {
+    await warnIfUpdateAvailable({ force: true });
+    console.log(packageJson.version);
+    return;
+  }
   if (!isKnownTopLevelCommand(program2, command)) throw new Error(`Unknown command: ${command}`);
   await program2.parseAsync(process.argv);
 }
@@ -3632,13 +3642,21 @@ function createCliProgram(options = {}) {
   const program2 = new Command();
   const warnBeforeAction = options.warnIfUpdateAvailable ?? warnIfUpdateAvailable;
   program2.name("p11").description("Share and inspect p11 document pages.");
-  program2.hook("preAction", async () => {
+  program2.version(packageJson.version);
+  program2.hook("preAction", async (_thisCommand, actionCommand) => {
+    if (actionCommand.name() === "version") return;
     await warnBeforeAction();
   });
   program2.addHelpText(
     "after",
     `
 
+Examples:
+  p11 example minimal --output ./page.tsx
+  p11 example all
+  p11 share ./page.tsx
+  p11 docs components
+
 Environment:
   P11_API_URL    Defaults to ${builtDefaultApiUrl}
   P11_BUILD_DIR  Directory for temporary share build files. Defaults to the OS temp directory.`
@@ -3655,6 +3673,10 @@ Environment:
     await deleteDocument(target, normalizeDeleteOptions(options2));
   });
   allowLegacyParserBehavior(deleteCommand);
+  program2.command("version").description("Print the p11 CLI version.").action(async () => {
+    await warnBeforeAction({ force: true });
+    console.log(packageJson.version);
+  });
   program2.command("history").description("List saved read/edit links.").option("--json", "Print saved history as JSON.").action(async (options2) => {
     await history(normalizeHistoryOptions(options2));
   });
@@ -3662,14 +3684,17 @@ Environment:
     await docs(topic);
   });
   allowLegacyParserBehavior(docsCommand);
-  const exampleCommand = program2.command("example").description("Print or write a p11 example document.").argument("[name]", "Example name: all-components.").option("--output [file]", "Write the example to a file.").action(async (name, options2) => {
+  const exampleCommand = program2.command("example").description("Print or write a p11 example document.").argument("[name]", "Example name: minimal or all.").option("--output [file]", "Write the example to a file.").action(async (name, options2) => {
     await example(name, normalizeExampleOptions(options2));
   });
   allowLegacyParserBehavior(exampleCommand);
   return program2;
 }
 function isKnownTopLevelCommand(program2, command) {
-  return command === "--help" || command === "-h" || command === "help" || program2.commands.some((subcommand) => subcommand.name() === command);
+  return command === "--help" || command === "-h" || isVersionFlag(command) || command === "help" || program2.commands.some((subcommand) => subcommand.name() === command);
+}
+function isVersionFlag(command) {
+  return command === "--version" || command === "-V";
 }
 function allowLegacyParserBehavior(command) {
   return command.allowUnknownOption().allowExcessArguments();
@@ -3735,7 +3760,7 @@ async function publish(input, options) {
     const url = editTarget ? new URL(`/api/edit/${encodeURIComponent(editTarget.editId)}/page`, apiUrl) : new URL("/api/pages", apiUrl);
     const uploadBody = new ArrayBuffer(zipBytes.byteLength);
     new Uint8Array(uploadBody).set(zipBytes);
-    const response = await fetch(url, {
+    const response = await fetchForOperation("Share", url, {
       method: "POST",
       headers: {
         "content-type": "application/zip"
@@ -3756,19 +3781,26 @@ async function publish(input, options) {
     if (options.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
-      console.log(data.readUrl ?? data.url);
-      if (data.editUrl) console.log(`editUrl: ${data.editUrl}`);
-      if (data.docId) console.log(`docId: ${data.docId}`);
-      if (data.readId) console.log(`readId: ${data.readId}`);
-      if (data.editId) console.log(`editId: ${data.editId}`);
-      if (data.version) console.log(`version: ${data.version}`);
-      if (data.latestVersion) console.log(`latestVersion: ${data.latestVersion}`);
-      if (data.createdAt) console.log(`createdAt: ${data.createdAt}`);
+      for (const line of publishOutputLines(data)) console.log(line);
     }
   } finally {
     if (cleanupDir) await rm(cleanupDir, { recursive: true, force: true });
   }
 }
+function publishOutputLines(data) {
+  const lines = [];
+  const readUrl = data.readUrl ?? data.url;
+  if (readUrl) lines.push(`readUrl: ${readUrl}`);
+  if (data.editUrl) lines.push(`editUrl: ${data.editUrl}`);
+  if (readUrl && data.editUrl) lines.push("Note: share readUrl for comments; keep editUrl private for updates and deletion.");
+  if (data.docId) lines.push(`docId: ${data.docId}`);
+  if (data.readId) lines.push(`readId: ${data.readId}`);
+  if (data.editId) lines.push(`editId: ${data.editId}`);
+  if (data.version) lines.push(`version: ${data.version}`);
+  if (data.latestVersion) lines.push(`latestVersion: ${data.latestVersion}`);
+  if (data.createdAt) lines.push(`createdAt: ${data.createdAt}`);
+  return lines;
+}
 async function history(options) {
   const entries = await readHistoryEntries();
   if (options.json) {
@@ -3788,14 +3820,15 @@ async function docs(topic) {
 async function example(name, options) {
   if (!name) {
     console.log("Available examples:");
-    for (const exampleName of exampleFiles.keys()) console.log(`  ${exampleName}`);
+    for (const exampleName of publicExampleNames) console.log(`  ${exampleName}`);
     console.log("");
-    console.log("Usage: p11 example all-components [--output FILE]");
+    console.log("Usage: p11 example minimal [--output FILE]");
+    console.log("       p11 example all [--output FILE]");
     return;
   }
   const relativePath = exampleFiles.get(name);
   if (!relativePath) {
-    throw new Error(`Unknown example: ${name}. Available examples: ${Array.from(exampleFiles.keys()).join(", ")}`);
+    throw new Error(`Unknown example: ${name}. Available examples: ${publicExampleNames.join(", ")}`);
   }
   const contents = await readCliAsset(relativePath);
   if (options.output) {
@@ -3813,7 +3846,7 @@ async function comments(target, options) {
     apiUrl: options.apiUrl,
     version
   });
-  const response = await fetch(url);
+  const response = await fetchForOperation("Fetch comments", url);
   const text = await response.text();
   if (!response.ok) {
     throw new Error(`Fetch comments failed (${response.status}): ${text}`);
@@ -3836,7 +3869,7 @@ async function deleteDocument(target, options) {
   const url = deleteApiUrlForTarget(target, {
     apiUrl: options.apiUrl
   });
-  const response = await fetch(url, {
+  const response = await fetchForOperation("Delete", url, {
     method: "DELETE"
   });
   const text = await response.text();
@@ -4053,9 +4086,34 @@ function responseErrorMessage(text) {
   }
   return text;
 }
+async function fetchForOperation(operation, url, init) {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    throw new Error(formatNetworkError(operation, url, error));
+  }
+}
+function formatNetworkError(operation, url, error) {
+  return `${operation} request failed before receiving a response: ${fetchFailureDetails(error)}. API URL: ${url.origin}. ${networkErrorHint()}`;
+}
+function fetchFailureDetails(error) {
+  const message = errorMessage(error);
+  const cause = errorCause(error);
+  if (!cause) return message;
+  const causeCode = errorCode(cause);
+  const causeMessage = errorMessage(cause);
+  const causeDetails = causeCode && !causeMessage.includes(causeCode) ? `${causeCode} ${causeMessage}` : causeMessage;
+  return `${message} (cause: ${causeDetails})`;
+}
+function networkErrorHint() {
+  return "If running in an agent sandbox, retry with network access outside the sandbox or with escalated network permissions.";
+}
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function errorCause(error) {
+  return typeof error === "object" && error !== null && "cause" in error ? error.cause : null;
+}
 async function readCliAsset(relativePath) {
   return readFile(path.join(cliPackageRoot, relativePath), "utf8");
 }
@@ -4417,12 +4475,12 @@ function validateAccessTarget(target, expected) {
 function normalizeApiUrl(value) {
   return value.endsWith("/") ? value.slice(0, -1) : value;
 }
-async function warnIfUpdateAvailable() {
+async function warnIfUpdateAvailable(options = {}) {
   if (process.env.P11_DISABLE_UPDATE_CHECK) return;
   try {
     const cachePath = updateCheckCachePath();
     const checkedAt = await readUpdateCheckTime(cachePath);
-    if (checkedAt && Date.now() - checkedAt.getTime() < updateCheckIntervalMs) return;
+    if (!options.force && checkedAt && Date.now() - checkedAt.getTime() < updateCheckIntervalMs) return;
     await writeUpdateCheckTime(cachePath);
     const latestVersion = await fetchLatestVersion();
     if (!latestVersion || !isNewerVersion(latestVersion, packageJson.version)) return;
@@ -4493,10 +4551,12 @@ export {
   commentsExportJson,
   createCliProgram,
   deleteApiUrlForTarget,
+  formatNetworkError,
   isNewerVersion,
   parseCommentsTarget,
   parseEditId,
   parseReadId,
+  publishOutputLines,
   readHistoryEntries,
   resolveBuildParentDir,
   validatePageSource

package/docs/index.md

@@ -5,6 +5,8 @@ p11 shares reviewable, public-but-unlisted document pages from React files.
 ## Common Commands
 
 ```bash
+p11 example minimal --output ./page.tsx
+p11 example all
 p11 share <page.tsx>
 p11 share <page.tsx> --edit-url <editUrl>
 p11 history
@@ -25,8 +27,9 @@ p11 docs sharing
 
 ```bash
 p11 example
-p11 example all-components
-p11 example all-components --output ./all-components.tsx
+p11 example minimal --output ./page.tsx
+p11 example all
+p11 example all --output ./all.tsx
 ```
 
 Use `p11 share --help`, `p11 comments --help`, `p11 delete --help`, and `p11 history --help` for command-specific flags.

package/examples/all-components.tsx

@@ -271,7 +271,7 @@ export default function All() {
           <CodeBlock language="json">
             {code`
               {
-                "docId": "all-components",
+                "docId": "all",
                 "version": 2,
                 "comments": true,
                 "languages": ["typescript", "javascript", "python", "rust", "html", "css", "json", "yaml", "bash"]
@@ -285,7 +285,7 @@ export default function All() {
           <CodeBlock language="yaml">
             {code`
               document:
-                id: all-components
+                id: all
                 version: 2
                 comments: true
                 retentionDays: 7
@@ -307,7 +307,7 @@ export default function All() {
           <Heading>14. Bash</Heading>
           <CodeBlock language="bash">
             {code`
-              p11 share ./all-components.tsx
+              p11 share ./all.tsx
               p11 comments <readUrl> --version 1
             `}
           </CodeBlock>

package/examples/minimal.tsx

@@ -0,0 +1,21 @@
+import { Document, Heading, Page, Section, Text } from "@p11-core/components";
+
+// For the full component set, run:
+//   p11 docs components
+//   p11 example all
+
+export default function Minimal() {
+  return (
+    <Document mode="page">
+      <Page>
+        <Section>
+          <Heading level={1}>Review Brief</Heading>
+          <Text>
+            This is a minimal p11 document. Replace this text with the content
+            you want reviewers to read and comment on.
+          </Text>
+        </Section>
+      </Page>
+    </Document>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p11-core/cli",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {