@p11-core/cli 0.0.10 → 0.0.12

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;
@@ -3659,37 +3667,79 @@ Examples:
 
 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: minimal or all.").option("--output [file]", "Write the example to a file.").action(async (name, options2) => {
-    await example(name, normalizeExampleOptions(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);
 }
@@ -3699,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,
@@ -4037,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);
 }
@@ -4544,6 +4743,7 @@ function parseUrlVersion(value) {
   }
 }
 export {
+  __testing,
   addSourceLineAttributes,
   appendPublishHistory,
   buildPageModule,

package/docs/components.md

@@ -76,7 +76,7 @@ Supported languages include TypeScript, JavaScript, Python, Rust, HTML/XML, CSS,
 
 ## Validation
 
-`p11 share` validates the document before build and upload.
+Before sharing, `p11 share` validates the document.
 
 Do not import or render app/control components such as:
 

package/docs/index.md

@@ -14,7 +14,7 @@ p11 comments <readUrl|editUrl|readId|editId>
 p11 delete <editUrl|editId>
 ```
 
-Add `--json` when scripting or when exact structured fields are needed.
+For `share`, `history`, `comments`, and `delete`, add `--json` when scripting or when exact structured fields are needed.
 
 ## Docs Topics
 

package/docs/sharing.md

@@ -35,6 +35,6 @@ p11 delete <editUrl|editId>
 Add `--json` when scripting or when exact structured fields are needed.
 
 `P11_API_URL` overrides the default API URL. `--api-url <url>` can override it per command.
-Temporary share builds are created under the OS temp directory by default. Use `P11_BUILD_DIR` or `--build-dir <dir>` only when you need to inspect or redirect the transient build workspace.
+Use `P11_BUILD_DIR` or `--build-dir <dir>` only when you need a custom working directory while sharing.
 
 Edit URLs are bearer credentials for updating or deleting a document. Keep them private.

package/examples/all-components.tsx

@@ -26,7 +26,7 @@ import {
 } from "@p11-core/components";
 
 const figureSrc =
-  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 720 240'%3E%3Crect width='720' height='240' fill='%23f8fafc'/%3E%3Cpath d='M80 172h560' stroke='%23d4d4d8' stroke-width='2'/%3E%3Ccircle cx='160' cy='132' r='42' fill='%2318181b'/%3E%3Crect x='260' y='92' width='120' height='80' rx='8' fill='%2352525b'/%3E%3Cpath d='M460 172 540 72l80 100z' fill='%2371717a'/%3E%3Ctext x='80' y='52' font-family='Inter, Arial' font-size='28' font-weight='700' fill='%2318181b'%3Ep11 document figure%3C/text%3E%3C/svg%3E";
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 720 240'%3E%3Crect width='720' height='240' fill='%23f8fafc'/%3E%3Cpath d='M80 172h560' stroke='%23d4d4d8' stroke-width='2'/%3E%3Ccircle cx='160' cy='132' r='42' fill='%2318181b'/%3E%3Crect x='260' y='92' width='120' height='80' rx='8' fill='%2352525b'/%3E%3Cpath d='M460 172 540 72l80 100z' fill='%2371717a'/%3E%3Ctext x='80' y='52' font-family='Inter, Arial' font-size='28' font-weight='700' fill='%2318181b'%3ESample document figure%3C/text%3E%3C/svg%3E";
 
 export default function All() {
   return (
@@ -35,26 +35,25 @@ export default function All() {
         <Section>
           <Heading level={1}>All Components Showcase</Heading>
           <Text>
-            This example replaces the original decision brief with a compact
-            tour of every document-safe component exported by{" "}
-            <code>@p11-core/components</code>. It also includes safe inline markup
-            such as <strong>strong text</strong>, <em>emphasis</em>,{" "}
+            This example is a compact tour of every available document
+            component. It also includes common inline markup such as{" "}
+            <strong>strong text</strong>, <em>emphasis</em>,{" "}
             <code>inline code</code>,{" "}
             <Strikethrough>obsolete wording</Strikethrough>, and a{" "}
-            <a href="https://example.com">print-safe link</a>.
+            <a href="https://example.com">sample link</a>.
           </Text>
           <Quote>
-            The page is intentionally broad: authors can use it to inspect
-            screen layout, print pagination, source-line anchors, tables,
-            figures, and syntax highlighting in one shared document.
+            The page is intentionally broad: authors can inspect text hierarchy,
+            lists, tables, figures, page breaks, and syntax highlighting in one
+            sample document.
           </Quote>
         </Section>
 
         <Section>
           <Heading>1. Text Hierarchy</Heading>
           <Text>
-            The heading component supports levels one through six while keeping
-            the document printable and commentable.
+            The heading component supports levels one through six for clear
+            document structure.
           </Text>
           <Heading level={2}>Level Two Heading</Heading>
           <Text>
@@ -73,21 +72,21 @@ export default function All() {
         <Section>
           <Heading>2. Lists</Heading>
           <Text>
-            Unordered lists work for parallel facts and short capabilities.
+            Unordered lists work for parallel facts and concise observations.
           </Text>
           <List>
-            <ListItem>Share static React-authored documents.</ListItem>
-            <ListItem>Allow anonymous comments on text selections.</ListItem>
+            <ListItem>Summarize goals and outcomes.</ListItem>
+            <ListItem>Group related facts into scannable entries.</ListItem>
             <ListItem>
-              Export comments with source file and line anchors.
+              Keep supporting details close to the relevant topic.
             </ListItem>
           </List>
           <Text>Ordered lists work for procedural steps.</Text>
           <List ordered>
-            <ListItem>Author a document file.</ListItem>
-            <ListItem>Share it with the CLI.</ListItem>
+            <ListItem>Draft the initial material.</ListItem>
+            <ListItem>Review the structure and supporting evidence.</ListItem>
             <ListItem>
-              Review the screen view and browser print output.
+              Prepare the final version for its audience.
             </ListItem>
           </List>
         </Section>
@@ -102,12 +101,12 @@ export default function All() {
           <DefinitionList>
             <DefinitionTerm>Page</DefinitionTerm>
             <DefinitionDescription>
-              A printable document surface with fixed letter-sized dimensions.
+              A bounded document surface used to organize related sections.
             </DefinitionDescription>
-            <DefinitionTerm>Comment anchor</DefinitionTerm>
+            <DefinitionTerm>Margin note</DefinitionTerm>
             <DefinitionDescription>
-              Source metadata attached to document text so reviewer feedback can
-              point back to authored content.
+              A short observation that adds context without interrupting the
+              main flow.
             </DefinitionDescription>
           </DefinitionList>
         </Section>
@@ -118,27 +117,27 @@ export default function All() {
             <TableHeader>
               <TableRow>
                 <TableHead>Component</TableHead>
-                <TableHead>Rendered Tag</TableHead>
+                <TableHead>Example Use</TableHead>
                 <TableHead>Purpose</TableHead>
               </TableRow>
             </TableHeader>
             <TableBody>
               <TableRow>
                 <TableCell>TableHeader</TableCell>
-                <TableCell>thead</TableCell>
+                <TableCell>Column labels</TableCell>
                 <TableCell>
-                  Groups the header rows for print-safe tables.
+                  Groups the header rows for structured data.
                 </TableCell>
               </TableRow>
               <TableRow>
                 <TableCell>TableBody</TableCell>
-                <TableCell>tbody</TableCell>
+                <TableCell>Table content</TableCell>
                 <TableCell>Groups the body rows and cells.</TableCell>
               </TableRow>
               <TableRow>
                 <TableCell>TableHead and TableCell</TableCell>
-                <TableCell>th and td</TableCell>
-                <TableCell>Provide commentable table content.</TableCell>
+                <TableCell>Labels and values</TableCell>
+                <TableCell>Present comparable table content.</TableCell>
               </TableRow>
             </TableBody>
           </Table>
@@ -149,11 +148,11 @@ export default function All() {
           <Figure>
             <img
               src={figureSrc}
-              alt="Abstract p11 document figure with simple geometric marks"
+              alt="Abstract sample document figure with simple geometric marks"
             />
             <Caption>
-              Figure 1. Figure and Caption components keep visual evidence with
-              its explanatory text.
+              Figure 1. Figure and Caption components keep visual material with
+              its explanation.
             </Caption>
           </Figure>
         </Section>
@@ -166,18 +165,18 @@ export default function All() {
           <Heading>6. TypeScript</Heading>
           <CodeBlock language="typescript">
             {code`
-              type ShareOptions = {
-                input: string;
-                comments?: boolean;
+              type BriefOptions = {
+                title: string;
+                includeSummary?: boolean;
               };
 
-              export async function share(options: ShareOptions) {
-                const response = await fetch("/api/pages", {
+              export async function createBrief(options: BriefOptions) {
+                const response = await fetch("/api/briefs", {
                   method: "POST",
                   body: JSON.stringify(options)
                 });
 
-                return response.json() as Promise<{ docId: string; readUrl: string; editUrl: string; version: number }>;
+                return response.json() as Promise<{ id: string; title: string; updatedAt: string }>;
               }
             `}
           </CodeBlock>
@@ -187,11 +186,11 @@ export default function All() {
           <Heading>7. JavaScript</Heading>
           <CodeBlock language="javascript">
             {code`
-              const pages = new Map();
+              const notes = new Map();
 
-              export function rememberPage(page) {
-                pages.set(page.id, {
-                  ...page,
+              export function rememberNote(note) {
+                notes.set(note.id, {
+                  ...note,
                   updatedAt: new Date().toISOString()
                 });
               }
@@ -206,12 +205,12 @@ export default function All() {
               from dataclasses import dataclass
 
               @dataclass
-              class Comment:
-                  author: str
-                  body: str
+              class Task:
+                  owner: str
+                  title: str
 
-              def preview(comment: Comment) -> str:
-                  return f"{comment.author}: {comment.body[:48]}"
+              def preview(task: Task) -> str:
+                  return f"{task.owner}: {task.title[:48]}"
             `}
           </CodeBlock>
         </Section>
@@ -221,13 +220,13 @@ export default function All() {
           <CodeBlock language="rust">
             {code`
               #[derive(Debug)]
-              struct Page<'a> {
+              struct Milestone<'a> {
                   id: &'a str,
-                  comments_enabled: bool,
+                  complete: bool,
               }
 
-              fn describe(page: &Page) -> String {
-                  format!("{} comments={}", page.id, page.comments_enabled)
+              fn describe(milestone: &Milestone) -> String {
+                  format!("{} complete={}", milestone.id, milestone.complete)
               }
             `}
           </CodeBlock>
@@ -237,9 +236,9 @@ export default function All() {
           <Heading>10. HTML And XML</Heading>
           <CodeBlock language="html">
             {code`
-              <article class="p11-page">
+              <article class="sample-page">
                 <h1>All Components Showcase</h1>
-                <p data-p11-block>Reviewers can comment on document text.</p>
+                <p>Each section demonstrates a different document pattern.</p>
               </article>
             `}
           </CodeBlock>
@@ -253,13 +252,13 @@ export default function All() {
           <Heading>11. CSS</Heading>
           <CodeBlock language="css">
             {code`
-              .p11-page {
+              .sample-page {
                 color: #27272a;
-                font-family: var(--p11-font-body);
+                font-family: ui-serif, Georgia, serif;
                 line-height: 1.62;
               }
 
-              .p11-code-block code.hljs {
+              .sample-code-block code {
                 background: transparent;
               }
             `}
@@ -271,9 +270,8 @@ export default function All() {
           <CodeBlock language="json">
             {code`
               {
-                "docId": "all",
+                "title": "All Components Showcase",
                 "version": 2,
-                "comments": true,
                 "languages": ["typescript", "javascript", "python", "rust", "html", "css", "json", "yaml", "bash"]
               }
             `}
@@ -285,10 +283,8 @@ export default function All() {
           <CodeBlock language="yaml">
             {code`
               document:
-                id: all
+                title: All Components Showcase
                 version: 2
-                comments: true
-                retentionDays: 7
               languages:
                 - typescript
                 - javascript
@@ -307,8 +303,8 @@ export default function All() {
           <Heading>14. Bash</Heading>
           <CodeBlock language="bash">
             {code`
-              p11 share ./all.tsx
-              p11 comments <readUrl> --version 1
+              mkdir -p notes
+              printf "Summary ready\n" > notes/summary.txt
             `}
           </CodeBlock>
         </Section>

package/package.json

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