@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/lib/share/publish.js

@@ -9,6 +9,8 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { hostname as osHostname } from 'node:os';
+import { createHash } from 'node:crypto';
+import { readSession } from '../identity/client.js';
 import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
 import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
@@ -16,6 +18,9 @@ import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
 import { injectAnalyticsBeacon } from './analytics.js';
 import { prepareShareHtml } from './html.js';
+/** The visibility levels a share may carry — the Worker's own set, used to
+ * validate `--visibility` and `share visibility <target> <level>`. */
+export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
 /**
  * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
  * passes through; otherwise `visibility` (default public).
@@ -35,13 +40,16 @@ export function resolveShareVisibility(opts = {}) {
  */
 export const RESERVED_META_KEYS = [
     'expires-at',
+    'published-at',
     'visibility',
     'owner',
+    'org_domain',
     'agent',
     'session',
     'host',
     'repo',
     'date',
+    'avatar',
     'label',
     'label-source',
 ];
@@ -64,6 +72,26 @@ export function resolveShareProvenance(opts = {}) {
         date: (opts.now ?? new Date()).toISOString().slice(0, 10),
     };
 }
+/**
+ * The sharer's avatar URL, stamped so the share bar can show a real profile
+ * picture instead of only the initials circle. We key a Gravatar on the SHA-256
+ * of the signed-in user's lowercased email (Gravatar resolves either MD5 or
+ * SHA-256), with `d=404` so Gravatar returns 404 for a user who has none — the
+ * bar's `<img>` onerror then falls back to the initials circle. Only the hash
+ * lands in public metadata, never the raw email. Returns '' when signed out
+ * (BYO without a Phoenix session), leaving the bar on the initials circle.
+ *
+ * `opts.session === null` means "explicitly signed out" (a test seam / BYO) and
+ * yields ''; `undefined` reads the real persisted session.
+ */
+export function resolveShareAvatar(opts = {}) {
+    const session = opts.session !== undefined ? opts.session : readSession();
+    const email = session?.email?.trim().toLowerCase();
+    if (!email)
+        return '';
+    const hash = createHash('sha256').update(email).digest('hex');
+    return `https://www.gravatar.com/avatar/${hash}?d=404&s=52`;
+}
 /**
  * Parse repeated `--meta key=value` CLI args into a validated metadata record.
  * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
@@ -80,12 +108,12 @@ export function parseMetaEntries(pairs) {
         }
         const key = pair.slice(0, eq).trim();
         const value = pair.slice(eq + 1);
-        if (!META_KEY_RE.test(key)) {
-            throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
-        }
         if (RESERVED_META_KEYS.includes(key)) {
             throw new Error(`--meta ${key}=… is reserved (Worker-stamped, or set automatically from your session/git) — pass a different key.`);
         }
+        if (!META_KEY_RE.test(key)) {
+            throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
+        }
         meta[key] = value;
     }
     return meta;
@@ -142,10 +170,13 @@ const HEADER_TRANSLITERATIONS = [
  * The transliterations above cover what actually shows up; anything else outside
  * latin1 is dropped, and a value that transliterates to nothing at all (a title
  * written entirely in a non-latin script) degrades to a marker rather than an
- * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
- * here AND a matching decode in the Worker, which every already-deployed Worker
- * would render as `%E2%80%A6` until its operator ran `agents artifacts share
- * update` — tracked as RUSH-2786.
+ * empty header. This value is the **latin1-safe floor** every Worker can read: a
+ * pre-Unicode Worker only ever sees `x-share-<field>`, so it MUST stay folded.
+ * Full Unicode rides ALONGSIDE it in a percent-encoded companion header
+ * (`toPercentHeaderValue` / {@link needsUnicodeCompanion}), which a new Worker
+ * opts into via `x-share-encoding: percent` and an old one ignores — so a
+ * Japanese/emoji title renders in full on an updated Worker and still folds
+ * gracefully everywhere else (PHNX-2786).
  */
 export function toHeaderValue(text) {
     let safe = text;
@@ -159,6 +190,31 @@ export function toHeaderValue(text) {
         return safe;
     return text.trim() ? '(unnamed)' : '';
 }
+/**
+ * Whether text carries a code point above latin1 (U+00FF) — the meaningful
+ * display content `fetch`'s ByteString cannot hold, which {@link toHeaderValue}
+ * therefore transliterates or drops. This is the range worth carrying in the
+ * percent-encoded companion: an em dash, a curly quote, an emoji, or any
+ * CJK/Arabic/Hindi text. A plain accented latin1 name (`José`, é = U+00E9) is
+ * NOT lossy and needs no companion.
+ *
+ * `toHeaderValue` ALSO strips C0/C1 control characters (below U+0020, and
+ * U+007F–U+009F), which this deliberately does not flag: a raw ANSI/control
+ * sequence is not display text and must not be reconstructed into a page's
+ * rendered metadata, so it stays dropped on both the old and new Worker paths.
+ */
+export function needsUnicodeCompanion(text) {
+    return /[^\u0000-\u00ff]/.test(text);
+}
+/**
+ * Percent-encode a single-line free-text value for the `x-share-<field>-u`
+ * companion header. Whitespace is collapsed first (matching the folded value's
+ * single-line shape), then `encodeURIComponent` makes it pure-ASCII and
+ * header-safe. The Worker recovers the original with `decodeURIComponent`.
+ */
+export function toPercentHeaderValue(text) {
+    return encodeURIComponent(text.replace(/\s+/g, ' ').trim());
+}
 /**
  * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
  * Markdown frontmatter `title:`, else the filename. Always returns something —
@@ -462,6 +518,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const unlisted = visibility === 'unlisted';
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
+    const avatarUrl = opts.avatar ?? resolveShareAvatar({ session: opts.session });
     const meta = opts.meta ?? {};
     const put = opts.uploader ??
         (async (u, b, h) => {
@@ -511,35 +568,60 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         metadataPreview.repo = provenance.repo;
     if (provenance.date)
         metadataPreview.date = provenance.date;
+    if (avatarUrl)
+        metadataPreview.avatar = avatarUrl;
     assertMetadataSize(metadataPreview);
     const authHeaders = (contentType) => {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         h['x-share-visibility'] = visibility;
-        // Every free-text header goes through toHeaderValue: a non-latin1 code point
-        // anywhere in a label, a repo name, or a --meta value throws inside fetch and
-        // crashes the publish outright.
+        // Two headers per free-text field, backward-compatible by construction
+        // (PHNX-2786): `x-share-<field>` always carries the latin1-safe folded value
+        // an already-deployed Worker reads verbatim, and — only when the fold is lossy
+        // (a curly quote, em dash, emoji, CJK/Arabic/Hindi) — a percent-encoded
+        // `x-share-<field>-u` companion carries the full Unicode. A new Worker opts
+        // into the companions via `x-share-encoding: percent`; an old one ignores the
+        // unknown headers and keeps folding gracefully. The floor also keeps the
+        // ByteString crash fixed: a non-latin1 code point never reaches a raw header.
+        let unicodeCompanion = false;
+        const setText = (name, value) => {
+            h[name] = toHeaderValue(value);
+            if (needsUnicodeCompanion(value)) {
+                h[`${name}-u`] = toPercentHeaderValue(value);
+                unicodeCompanion = true;
+            }
+        };
         if (provenance.agent)
-            h['x-share-agent'] = toHeaderValue(provenance.agent);
+            setText('x-share-agent', provenance.agent);
         if (provenance.session)
-            h['x-share-session'] = toHeaderValue(provenance.session);
+            setText('x-share-session', provenance.session);
         if (provenance.host)
-            h['x-share-host'] = toHeaderValue(provenance.host);
+            setText('x-share-host', provenance.host);
         if (provenance.repo)
-            h['x-share-repo'] = toHeaderValue(provenance.repo);
+            setText('x-share-repo', provenance.repo);
         if (provenance.date)
-            h['x-share-date'] = toHeaderValue(provenance.date);
-        h['x-share-label'] = toHeaderValue(label);
+            setText('x-share-date', provenance.date);
+        if (avatarUrl)
+            setText('x-share-avatar', avatarUrl);
+        setText('x-share-label', label);
         h['x-share-label-source'] = labelSource;
         // Per VALUE, before JSON.stringify — folding the serialized form would rewrite
         // a curly quote inside a value into a bare `"`, which is structural in JSON and
         // makes the Worker's JSON.parse throw. It swallows that error, so every --meta
-        // key would silently vanish on a 200.
+        // key would silently vanish on a 200. The companion carries the whole raw meta
+        // object percent-encoded once, so a new Worker recovers full-Unicode keys AND
+        // values in one JSON.parse rather than per-field.
         if (Object.keys(meta).length > 0) {
             const headerMeta = Object.fromEntries(Object.entries(meta).map(([k, v]) => [toHeaderValue(k), toHeaderValue(v)]));
             h['x-share-meta'] = JSON.stringify(headerMeta);
+            if (Object.entries(meta).some(([k, v]) => needsUnicodeCompanion(k) || needsUnicodeCompanion(v))) {
+                h['x-share-meta-u'] = encodeURIComponent(JSON.stringify(meta));
+                unicodeCompanion = true;
+            }
         }
+        if (unicodeCompanion)
+            h['x-share-encoding'] = 'percent';
         if (opts.noRevision)
             h['x-share-no-revision'] = '1';
         return h;