@p11-core/cli 0.0.9 → 0.0.11

package/dist/index.js

@@ -3466,8 +3466,11 @@ var require_commander = __commonJS({
 });
 
 // src/index.ts
+import { randomUUID } from "crypto";
 import { realpathSync } from "fs";
 import { chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "fs/promises";
+import http from "http";
+import https from "https";
 import { createRequire } from "module";
 import { homedir, tmpdir } from "os";
 import path from "path";
@@ -3503,11 +3506,16 @@ var nodeRequire = createRequire(import.meta.url);
 var packageJson = nodeRequire("../package.json");
 var builtDefaultApiUrl = "https://p11.rarexlabs.com";
 var defaultApiUrl = process.env.P11_API_URL || builtDefaultApiUrl;
+var builtPostHogKey = "phc_CftZMyBB3bMZQRj3CmJovHB3kvzwJmQhXSwUBgzUTUi6";
+var builtPostHogHost = "https://us.i.posthog.com";
+var builtAppEnv = "production";
 var generate = nodeRequire("@babel/generator").default;
 var traverse = nodeRequire("@babel/traverse").default;
 var updateCheckIntervalMs = 30 * 60 * 1e3;
 var updateCheckTimeoutMs = 800;
+var telemetryTimeoutMs = 300;
 var P11_HISTORY_FILE = "history.json";
+var P11_TELEMETRY_FILE = "telemetry.json";
 var P11_HISTORY_DIR_MODE = 448;
 var P11_HISTORY_FILE_MODE = 384;
 var P11_HISTORY_LOCK_STALE_MS = 3e4;
@@ -3521,7 +3529,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",
@@ -3646,39 +3659,87 @@ function createCliProgram(options = {}) {
     "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.`
+  P11_BUILD_DIR  Directory for temporary share build files. Defaults to the OS temp directory.
+  P11_TELEMETRY_DISABLED=1 disables anonymous usage analytics.`
   );
   const shareCommand = program2.command("share").description("Share a review link for a page.").argument("[page.tsx]").option("--json", "Print the API response as JSON.").option("--edit-url [url]", "Share a new version using an edit URL or edit id.").option("--api-url [url]", "Override the p11 API URL.").option("--build-dir [dir]", "Directory for temporary build files.").action(async (input, options2) => {
-    await publish(input, normalizePublishOptions(options2));
+    await runCliAction(
+      "share",
+      {
+        has_input: Boolean(input),
+        json: Boolean(options2.json),
+        edit_url: typeof options2.editUrl === "string",
+        api_url_override: typeof options2.apiUrl === "string",
+        build_dir_override: typeof options2.buildDir === "string"
+      },
+      () => publish(input, normalizePublishOptions(options2))
+    );
   });
   allowLegacyParserBehavior(shareCommand);
   const commentsCommand = program2.command("comments").description("Fetch exported comments for a read/edit URL or id.").argument("[readUrl|editUrl|readId|editId]").option("--json", "Print comments as JSON.").option("--output [file]", "Write comments JSON to a file.").option("--version [n]", "Fetch comments for a specific page version.").option("--api-url [url]", "Override the p11 API URL.").action(async (target, options2) => {
-    await comments(target, normalizeCommentsOptions(options2));
+    await runCliAction(
+      "comments",
+      {
+        has_target: Boolean(target),
+        json: Boolean(options2.json),
+        output: typeof options2.output === "string",
+        version: typeof options2.version === "string",
+        api_url_override: typeof options2.apiUrl === "string"
+      },
+      () => comments(target, normalizeCommentsOptions(options2))
+    );
   });
   allowLegacyParserBehavior(commentsCommand);
   const deleteCommand = program2.command("delete").description("Delete a document and all of its versions and comments.").argument("[editUrl|editId]").option("--json", "Print the API response as JSON.").option("--api-url [url]", "Override the p11 API URL.").action(async (target, options2) => {
-    await deleteDocument(target, normalizeDeleteOptions(options2));
+    await runCliAction(
+      "delete",
+      {
+        has_target: Boolean(target),
+        json: Boolean(options2.json),
+        api_url_override: typeof options2.apiUrl === "string"
+      },
+      () => 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);
+    await runCliAction("version", {}, 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));
+    await runCliAction("history", { json: Boolean(options2.json) }, () => history(normalizeHistoryOptions(options2)));
   });
   const docsCommand = program2.command("docs").description("Print p11 authoring docs.").argument("[topic]", "Docs topic: components or sharing.").action(async (topic) => {
-    await docs(topic);
+    await runCliAction("docs", { has_topic: Boolean(topic), known_topic: isKnownDocsTopic(topic) }, () => 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) => {
-    await example(name, normalizeExampleOptions(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 runCliAction(
+      "example",
+      {
+        has_example: Boolean(name),
+        known_example: isKnownExampleName(name),
+        output: typeof options2.output === "string"
+      },
+      () => example(name, normalizeExampleOptions(options2))
+    );
   });
   allowLegacyParserBehavior(exampleCommand);
   return program2;
 }
+var __testing = {
+  captureCliTelemetry: captureCliTelemetryNow
+};
 function isKnownTopLevelCommand(program2, command) {
   return command === "--help" || command === "-h" || isVersionFlag(command) || command === "help" || program2.commands.some((subcommand) => subcommand.name() === command);
 }
@@ -3688,6 +3749,31 @@ function isVersionFlag(command) {
 function allowLegacyParserBehavior(command) {
   return command.allowUnknownOption().allowExcessArguments();
 }
+function isKnownDocsTopic(topic) {
+  return docsTopics.has(topic ?? "index");
+}
+function isKnownExampleName(name) {
+  return name === void 0 || exampleFiles.has(name);
+}
+async function runCliAction(command, properties, action) {
+  const startedAt = Date.now();
+  try {
+    await action();
+    captureCliTelemetry("p11_cli_command_succeeded", {
+      command,
+      duration_ms: Date.now() - startedAt,
+      ...properties
+    });
+  } catch (error) {
+    await captureCliTelemetryNow("p11_cli_command_failed", {
+      command,
+      duration_ms: Date.now() - startedAt,
+      error_name: error instanceof Error ? error.name : "Error",
+      ...properties
+    });
+    throw error;
+  }
+}
 function normalizePublishOptions(options) {
   return {
     json: options.json,
@@ -3749,7 +3835,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"
@@ -3770,19 +3856,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) {
@@ -3802,14 +3895,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) {
@@ -3827,7 +3921,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}`);
@@ -3850,7 +3944,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();
@@ -4018,6 +4112,130 @@ function delay(ms) {
 function historyFilePath() {
   return path.join(homedir(), ".p11", P11_HISTORY_FILE);
 }
+function captureCliTelemetry(event, properties = {}) {
+  scheduleTelemetry(() => captureCliTelemetryNow(event, properties, { keepAlive: false }));
+}
+async function captureCliTelemetryNow(event, properties = {}, options = {}) {
+  const key = postHogKey();
+  if (!key) return;
+  try {
+    const host = postHogHost();
+    const { anonymousId, isNew } = await telemetryIdentity();
+    const baseProperties = cliTelemetryBaseProperties();
+    const events = [];
+    if (isNew && event !== "p11_cli_activated") {
+      events.push(sendPostHogEvent(host, key, "p11_cli_activated", anonymousId, baseProperties, options));
+    }
+    events.push(sendPostHogEvent(host, key, event, anonymousId, { ...baseProperties, ...properties }, options));
+    await Promise.all(events);
+  } catch {
+  }
+}
+function scheduleTelemetry(task) {
+  const run = () => {
+    task().catch(() => {
+    });
+  };
+  if (typeof setImmediate === "function") {
+    setImmediate(run);
+    return;
+  }
+  setTimeout(run, 0);
+}
+async function sendPostHogEvent(host, key, event, distinctId, properties, options = {}) {
+  const payload = JSON.stringify({
+    api_key: key,
+    event,
+    distinct_id: distinctId,
+    properties: compactObject(properties)
+  });
+  const endpoint = new URL("/capture/", host);
+  const client = endpoint.protocol === "http:" ? http : https;
+  await new Promise((resolve, reject) => {
+    const request = client.request(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(payload)
+        }
+      },
+      (response) => {
+        response.resume();
+        response.on("end", resolve);
+      }
+    );
+    const timeout = setTimeout(() => {
+      request.destroy(new Error("Telemetry request timed out."));
+    }, telemetryTimeoutMs);
+    if (options.keepAlive === false) timeout.unref?.();
+    request.on("socket", (socket) => {
+      if (options.keepAlive === false) socket.unref();
+    });
+    request.on("error", reject);
+    request.on("close", () => clearTimeout(timeout));
+    request.end(payload);
+  });
+}
+function cliTelemetryBaseProperties() {
+  return {
+    product: "p11",
+    surface: "cli",
+    app_env: analyticsEnv(),
+    cli_version: packageJson.version,
+    node_version: process.versions.node,
+    platform: process.platform,
+    arch: process.arch
+  };
+}
+function postHogKey() {
+  if (isTruthyEnv(process.env.P11_TELEMETRY_DISABLED) || isTruthyEnv(process.env.DO_NOT_TRACK)) return "";
+  return (process.env.P11_POSTHOG_KEY || builtPostHogKey || "").trim();
+}
+function postHogHost() {
+  const rawHost = (process.env.P11_POSTHOG_HOST || builtPostHogHost || "https://us.i.posthog.com").trim();
+  try {
+    return new URL(rawHost.endsWith("/") ? rawHost : `${rawHost}/`);
+  } catch {
+    return new URL("https://us.i.posthog.com/");
+  }
+}
+function isTruthyEnv(value) {
+  return value === "1" || value === "true" || value === "yes";
+}
+function analyticsEnv() {
+  return (process.env.APP_ENV || builtAppEnv || "production").trim() || "production";
+}
+async function telemetryIdentity() {
+  const filePath = telemetryFilePath();
+  const raw = await readFile(filePath, "utf8").catch(() => null);
+  if (raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.anonymousId === "string" && /^anon_[A-Za-z0-9-]{12,80}$/.test(parsed.anonymousId)) {
+      return {
+        anonymousId: parsed.anonymousId,
+        isNew: false
+      };
+    }
+  }
+  const data = {
+    anonymousId: `anon_${randomUUID()}`,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const telemetryDir = path.dirname(filePath);
+  await ensurePrivateHistoryDir(telemetryDir);
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}
+`, { mode: P11_HISTORY_FILE_MODE });
+  await chmod(filePath, P11_HISTORY_FILE_MODE);
+  return {
+    anonymousId: data.anonymousId,
+    isNew: true
+  };
+}
+function telemetryFilePath() {
+  return path.join(homedir(), ".p11", P11_TELEMETRY_FILE);
+}
 function commentsExportJson(data) {
   return JSON.stringify(commentExportData(data), null, 2);
 }
@@ -4067,9 +4285,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");
 }
@@ -4500,6 +4743,7 @@ function parseUrlVersion(value) {
   }
 }
 export {
+  __testing,
   addSourceLineAttributes,
   appendPublishHistory,
   buildPageModule,
@@ -4507,10 +4751,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.9",
+  "version": "0.0.11",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {