@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/lib/share/publish.d.ts

@@ -18,10 +18,20 @@ export interface PublishOptions {
      */
     expire?: string;
     contentType?: string;
+    /**
+     * Server-enforced visibility (RUSH-3135). `public` (default) is listed in
+     * the gallery; `unlisted` is a capability URL (GET still 200, X-Robots-Tag:
+     * noindex, hidden from gallery/list). `me` requires a Phoenix session and is
+     * visible only to the signed-in owner; `org` requires the same and is visible
+     * to members of the same Phoenix organization.
+     */
+    visibility?: ShareVisibility;
     /**
      * Hide this page from the public `/<user>` gallery and `agents artifacts share list`
      * (metadata `visibility=unlisted`). The direct URL is still world-readable —
-     * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
+     * unlisted, not secret (RUSH-2443). Alias of `--visibility unlisted` /
+     * `--private` on the CLI. Kept so `sessions share` and existing callers do
+     * not break.
      */
     unlisted?: boolean;
     /**
@@ -39,8 +49,12 @@ export interface PublishOptions {
     githubUser?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
-    /** DI seam for tests — override the keychain-backed write token. */
+    /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
     writeToken?: string;
+    /** DI seam for tests — override `readSession()`. `null` means signed out. */
+    session?: import('../identity/client.js').PhoenixSession | null;
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
     /** DI seam for tests — override the real HTTP PUT. */
     uploader?: PutFn;
     /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
@@ -55,22 +69,26 @@ export interface PublishOptions {
     /**
      * Structured metadata (`--meta key=value`, repeatable). Keys are validated by
      * {@link parseMetaEntries} — lowercase `[a-z0-9-]`, and may not collide with
-     * {@link RESERVED_META_KEYS}, which the CLI sets automatically.
+     * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at,
+     * plus provenance the CLI sets automatically).
      */
     meta?: Record<string, string>;
     /**
      * Skip revision retention on this publish — overwrite an existing slug's
      * object in place with no `<slug>/rev-<ts>` backup of the version it replaces
-     * (default: keep it; see docs/share.md §Revisions).
+     * (default: keep it; see docs/distribution.md).
      */
     noRevision?: boolean;
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
+export type ShareVisibility = 'public' | 'unlisted' | 'me' | 'org';
 export interface PublishResult {
     url: string;
     expiresAt?: string;
     coverUrl?: string;
+    /** Server-enforced visibility stamped on the object. */
+    visibility?: ShareVisibility;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
     /** The label stored with this share — explicit (`--label`) or derived. */
@@ -78,6 +96,14 @@ export interface PublishResult {
     /** Whether `label` came from `--label` or was auto-derived. */
     labelSource?: 'explicit' | 'derived';
 }
+/**
+ * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
+ * passes through; otherwise `visibility` (default public).
+ */
+export declare function resolveShareVisibility(opts?: {
+    visibility?: ShareVisibility;
+    unlisted?: boolean;
+}): ShareVisibility;
 export interface ShareProvenance {
     /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
     agent?: string;
@@ -91,11 +117,12 @@ export interface ShareProvenance {
     date?: string;
 }
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["agent", "session", "host", "repo", "date", "label", "label-source"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "visibility", "owner", "agent", "session", "host", "repo", "date", "label", "label-source"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a
@@ -113,8 +140,9 @@ export declare function resolveShareProvenance(opts?: {
 /**
  * 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
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export declare function parseMetaEntries(pairs: string[]): Record<string, string>;
 /** Throws when the combined `customMetadata` payload would exceed {@link MAX_METADATA_BYTES}. */
@@ -201,16 +229,17 @@ export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */
 export declare function detectProject(dir?: string): string;
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export declare function defaultSlug(filePath: string, dir?: string): string;
+export declare function defaultSlug(filePath: string, _dir?: string): string;
 /**
  * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
  * the page body with og:image meta injected (+ the cover URL). All IO is injected

package/dist/lib/share/publish.js

@@ -10,17 +10,42 @@ import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { hostname as osHostname } from 'node:os';
-import { readShareConfig, readWriteToken } from './config.js';
+import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
+import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
 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';
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
+ * passes through; otherwise `visibility` (default public).
  */
-export const RESERVED_META_KEYS = ['agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+export function resolveShareVisibility(opts = {}) {
+    if (opts.unlisted === true)
+        return 'unlisted';
+    if (opts.visibility === 'unlisted' || opts.visibility === 'me' || opts.visibility === 'org')
+        return opts.visibility;
+    return 'public';
+}
+/**
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
+ */
+export const RESERVED_META_KEYS = [
+    'expires-at',
+    'visibility',
+    'owner',
+    'agent',
+    'session',
+    'host',
+    'repo',
+    'date',
+    'label',
+    'label-source',
+];
 const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
@@ -43,8 +68,9 @@ export function resolveShareProvenance(opts = {}) {
 /**
  * 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
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export function parseMetaEntries(pairs) {
     const meta = {};
@@ -59,7 +85,7 @@ export function parseMetaEntries(pairs) {
             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 (set automatically from your session/git) — pass a different key.`);
+            throw new Error(`--meta ${key}=… is reserved (Worker-stamped, or set automatically from your session/git) — pass a different key.`);
         }
         meta[key] = value;
     }
@@ -293,7 +319,7 @@ export function slugify(name) {
         .slice(0, 60) || 'page');
 }
 function sanitizeSlugPart(s) {
-    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return sanitizeShareNamespace(s);
 }
 /** The current repo's name, or undefined outside a git checkout — never a
  * fallback guess, since callers that want one (detectProject) supply it themselves. */
@@ -317,18 +343,19 @@ export function detectProject(dir = process.cwd()) {
     return gitRepoName(dir) ?? (sanitizeSlugPart(basename(dir)) || 'share');
 }
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export function defaultSlug(filePath, dir) {
+export function defaultSlug(filePath, _dir) {
     const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
-    return `${detectProject(dir)}-${feature}-${randomBytes(8).toString('hex')}`;
+    return `${feature}-${randomBytes(8).toString('hex')}`;
 }
 function guessContentType(filePath) {
     if (/\.html?$/i.test(filePath))
@@ -419,14 +446,12 @@ export function buildShareKey(username, slugPart) {
     return `${user}/${part}`;
 }
 export async function publishFile(filePath, opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    const token = opts.writeToken ?? readWriteToken();
-    const username = await resolveShareUsername(opts);
-    const analyticsToken = opts.analyticsToken ?? cfg.analyticsToken;
-    return publishToEndpoint(filePath, { baseUrl: cfg.baseUrl, token }, {
+    const backend = resolveShareBackend(opts);
+    const username = backend.kind === 'managed'
+        ? backend.namespace
+        : await resolveShareUsername({ githubUser: opts.githubUser || backend.namespace || undefined });
+    const analyticsToken = opts.analyticsToken ?? (backend.kind === 'byo' ? (opts.config ?? readShareConfig())?.analyticsToken : undefined);
+    return publishToEndpoint(filePath, { baseUrl: backend.baseUrl, token: backend.token }, {
         ...opts,
         githubUser: username,
         analyticsToken,
@@ -437,7 +462,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
     const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
-    const unlisted = opts.unlisted === true;
+    const visibility = resolveShareVisibility(opts);
+    const unlisted = visibility === 'unlisted';
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
     const meta = opts.meta ?? {};
@@ -449,6 +475,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     let body = readFileSync(filePath);
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
+    if (isHtml) {
+        body = Buffer.from(prepareShareHtml(body.toString('utf8'), filePath), 'utf8');
+    }
     const explicitLabel = opts.label?.trim();
     // sanitizeLabel here (not just inside deriveLabel) covers an explicit
     // --label/--title the caller typed with an embedded newline — deriveLabel
@@ -492,8 +521,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
-        if (unlisted)
-            h['x-share-visibility'] = 'unlisted';
+        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.
@@ -541,6 +569,9 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
+        if (r.status === 409) {
+            throw new Error(`Handle '${username}' is already claimed by another account. The public URL namespace is the email local-part; two Phoenix users cannot share it.`);
+        }
         throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     return {
@@ -549,6 +580,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         coverUrl,
         label,
         labelSource,
+        visibility,
         ...(unlisted ? { unlisted: true } : {}),
     };
 }