@phnx-labs/agents-cli 1.20.72 → 1.20.73

package/dist/lib/share/provision.js

@@ -1,8 +1,12 @@
 // Cloudflare provisioning for `agents share setup` — plain `fetch` against the CF
-// REST API (the repo has no CF wrapper). Creates the R2 bucket, uploads the Worker
-// (with an R2 binding + the WRITE_TOKEN as an inline secret), enables the free
-// `*.workers.dev` subdomain, and — when the token owns the zone — maps a custom domain.
+// REST API (the repo has no CF wrapper). Creates the R2 bucket, configures its
+// lifecycle, uploads the Worker (with an R2 binding), sets the WRITE_TOKEN secret,
+// enables the free `*.workers.dev` subdomain, and — when the token owns the zone —
+// maps a custom domain.
 const CF_API = 'https://api.cloudflare.com/client/v4';
+export const SHARE_LIFECYCLE_RULE_ID = 'agents-share-expire-objects';
+export const SHARE_LIFECYCLE_RETENTION_DAYS = 366;
+const SECONDS_PER_DAY = 86400;
 async function cf(apiToken, method, pathname, body, form) {
     const headers = { authorization: `Bearer ${apiToken}` };
     let payload;
@@ -22,66 +26,137 @@ async function cf(apiToken, method, pathname, body, form) {
     }
     return json.result;
 }
+const defaultCloudflareRequester = (request) => cf(request.apiToken, request.method, request.pathname, request.body, request.form);
 /** True if the CF error looks like "the thing already exists" (idempotent create). */
 function isAlreadyExists(e) {
     return /already exists|duplicate|10004|10014/i.test(String(e));
 }
 /** Create the R2 bucket (idempotent). */
-export async function createBucket(apiToken, accountId, name) {
+export async function createBucket(apiToken, accountId, name, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
     try {
-        await cf(apiToken, 'POST', `/accounts/${accountId}/r2/buckets`, { name });
+        await request({
+            apiToken,
+            method: 'POST',
+            pathname: `/accounts/${accountId}/r2/buckets`,
+            body: { name },
+        });
     }
     catch (e) {
         if (!isAlreadyExists(e))
             throw e;
     }
 }
-/** Upload the module Worker with an R2 binding (`BUCKET`) + inline `WRITE_TOKEN` secret. */
-export async function deployWorker(apiToken, accountId, workerName, script, bucketName, writeToken) {
+export function buildShareLifecycleRule(days = SHARE_LIFECYCLE_RETENTION_DAYS) {
+    return {
+        id: SHARE_LIFECYCLE_RULE_ID,
+        enabled: true,
+        conditions: { prefix: '' },
+        deleteObjectsTransition: {
+            condition: { type: 'Age', maxAge: days * SECONDS_PER_DAY },
+        },
+    };
+}
+export function mergeShareLifecycleRule(existing = [], rule = buildShareLifecycleRule()) {
+    return [...existing.filter((r) => r.id !== SHARE_LIFECYCLE_RULE_ID), rule];
+}
+/** Ensure the share bucket self-cleans old objects. Exact per-link expiry is enforced by the Worker. */
+export async function configureBucketLifecycle(apiToken, accountId, bucketName, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    const lifecycle = await request({
+        apiToken,
+        method: 'GET',
+        pathname: `/accounts/${accountId}/r2/buckets/${bucketName}/lifecycle`,
+    });
+    await request({
+        apiToken,
+        method: 'PUT',
+        pathname: `/accounts/${accountId}/r2/buckets/${bucketName}/lifecycle`,
+        body: { rules: mergeShareLifecycleRule(lifecycle.rules ?? []) },
+    });
+}
+/** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
+export async function deployWorker(apiToken, accountId, workerName, script, bucketName, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
     const metadata = {
         main_module: 'worker.js',
         compatibility_date: '2024-11-06',
         bindings: [
             { type: 'r2_bucket', name: 'BUCKET', bucket_name: bucketName },
-            { type: 'secret_text', name: 'WRITE_TOKEN', text: writeToken },
         ],
     };
     const form = new FormData();
     form.set('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }));
     form.set('worker.js', new Blob([script], { type: 'application/javascript+module' }), 'worker.js');
-    await cf(apiToken, 'PUT', `/accounts/${accountId}/workers/scripts/${workerName}`, undefined, form);
+    await request({
+        apiToken,
+        method: 'PUT',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}`,
+        form,
+    });
+}
+/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
+export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    await request({
+        apiToken,
+        method: 'PUT',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}/secrets`,
+        body: { name: 'WRITE_TOKEN', text: writeToken, type: 'secret_text' },
+    });
 }
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
-export async function enableWorkersDev(apiToken, accountId, workerName) {
-    await cf(apiToken, 'POST', `/accounts/${accountId}/workers/scripts/${workerName}/subdomain`, {
-        enabled: true,
-        previews_enabled: false,
+export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
+    await request({
+        apiToken,
+        method: 'POST',
+        pathname: `/accounts/${accountId}/workers/scripts/${workerName}/subdomain`,
+        body: {
+            enabled: true,
+            previews_enabled: false,
+        },
+    });
+    const sub = await request({
+        apiToken,
+        method: 'GET',
+        pathname: `/accounts/${accountId}/workers/subdomain`,
     });
-    const sub = await cf(apiToken, 'GET', `/accounts/${accountId}/workers/subdomain`);
     if (!sub?.subdomain) {
         throw new Error('No workers.dev subdomain on this account yet — register one at dash.cloudflare.com → Workers → Subdomain, then re-run.');
     }
     return sub.subdomain;
 }
 /** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
-export async function findZoneId(apiToken, domain) {
+export async function findZoneId(apiToken, domain, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
     // Try the exact name, then the registrable parent (share.agents-cli.sh -> agents-cli.sh).
     const candidates = [domain, domain.split('.').slice(-2).join('.')];
     for (const name of candidates) {
-        const zones = await cf(apiToken, 'GET', `/zones?name=${encodeURIComponent(name)}`).catch(() => []);
+        const zones = await request({
+            apiToken,
+            method: 'GET',
+            pathname: `/zones?name=${encodeURIComponent(name)}`,
+        }).catch(() => []);
         if (zones?.length)
             return zones[0].id;
     }
     return null;
 }
 /** Map a custom hostname (e.g. `share.agents-cli.sh`) to the Worker via Workers Custom Domains. */
-export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname) {
+export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname, opts = {}) {
+    const request = opts.request ?? defaultCloudflareRequester;
     try {
-        await cf(apiToken, 'PUT', `/accounts/${accountId}/workers/domains`, {
-            zone_id: zoneId,
-            hostname,
-            service: workerName,
-            environment: 'production',
+        await request({
+            apiToken,
+            method: 'PUT',
+            pathname: `/accounts/${accountId}/workers/domains`,
+            body: {
+                zone_id: zoneId,
+                hostname,
+                service: workerName,
+                environment: 'production',
+            },
         });
     }
     catch (e) {

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

@@ -1,8 +1,13 @@
-type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
+import { type ShareConfig } from './config.js';
+export type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
     ok: boolean;
     status: number;
     url?: string;
 }>;
+export interface PublishEndpoint {
+    baseUrl: string;
+    token: string;
+}
 export interface PublishOptions {
     slug?: string;
     /** e.g. `30d`, `12h`, or an absolute date like `2026-08-01`. */
@@ -10,15 +15,26 @@ export interface PublishOptions {
     contentType?: string;
     /** Generate + attach an OG cover for HTML pages (default true). */
     cover?: boolean;
+    /** Inject the Cloudflare Web Analytics beacon (default true for HTML). */
+    analytics?: boolean;
+    /** Override the analytics token from share config. */
+    analyticsToken?: string;
+    /** Override the GitHub username used for the URL namespace. */
+    githubUser?: string;
+    /** DI seam for tests — override the persisted share endpoint config. */
+    config?: ShareConfig;
+    /** DI seam for tests — override the keychain-backed write token. */
+    writeToken?: string;
     /** DI seam for tests — override the real HTTP PUT. */
-    uploader?: (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
-        ok: boolean;
-        status: number;
-        url?: string;
-    }>;
+    uploader?: PutFn;
     /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
     capturer?: (htmlPath: string) => Promise<Buffer | null>;
 }
+export interface PublishResult {
+    url: string;
+    expiresAt?: string;
+    coverUrl?: string;
+}
 /** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
 export declare function parseExpire(spec: string | undefined): string | undefined;
 /** Derive a URL-safe slug from a filename (or pass one through). */
@@ -26,9 +42,14 @@ 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>-<6hex>`. Project scopes the link
+ * 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).
+ *
+ * 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
+ * §Security for the threat model and `--expire` for sensitive content.)
  */
 export declare function defaultSlug(filePath: string, dir?: string): string;
 /**
@@ -49,9 +70,11 @@ export declare function attachOgCover(filePath: string, body: Buffer, ctx: {
     body: Buffer;
     coverUrl?: string;
 }>;
-export declare function publishFile(filePath: string, opts?: PublishOptions): Promise<{
-    url: string;
-    expiresAt?: string;
-    coverUrl?: string;
-}>;
-export {};
+/** Resolve the publisher's GitHub username, with an explicit override winning first. */
+export declare function resolveShareUsername(opts?: {
+    githubUser?: string;
+}): Promise<string>;
+/** Build the R2 object key from a namespace username and a slug part. */
+export declare function buildShareKey(username: string, slugPart: string): string;
+export declare function publishFile(filePath: string, opts?: PublishOptions): Promise<PublishResult>;
+export declare function publishToEndpoint(filePath: string, endpoint: PublishEndpoint, opts?: PublishOptions): Promise<PublishResult>;

package/dist/lib/share/publish.js

@@ -10,8 +10,10 @@ import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { readShareConfig, readWriteToken } from './config.js';
+import { resolveGitHubUsername } from '../git.js';
 import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
+import { injectAnalyticsBeacon } from './analytics.js';
 const UNIT_MS = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
 /** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
 export function parseExpire(spec) {
@@ -55,13 +57,18 @@ export function detectProject(dir = process.cwd()) {
     return sanitizeSlugPart(basename(dir)) || 'share';
 }
 /**
- * Notion-style default slug: `<project>-<feature>-<6hex>`. Project scopes the link
+ * 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).
+ *
+ * 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
+ * §Security for the threat model and `--expire` for sensitive content.)
  */
 export function defaultSlug(filePath, dir) {
     const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
-    return `${detectProject(dir)}-${feature}-${randomBytes(3).toString('hex')}`;
+    return `${detectProject(dir)}-${feature}-${randomBytes(8).toString('hex')}`;
 }
 function guessContentType(filePath) {
     if (/\.html?$/i.test(filePath))
@@ -103,30 +110,70 @@ export async function attachOgCover(filePath, body, ctx) {
     });
     return { body: Buffer.from(injected, 'utf8'), coverUrl: ctx.pngUrl };
 }
+/** Resolve the publisher's GitHub username, with an explicit override winning first. */
+export async function resolveShareUsername(opts = {}) {
+    if (opts.githubUser) {
+        const sanitized = sanitizeSlugPart(opts.githubUser);
+        if (sanitized)
+            return sanitized;
+    }
+    const resolved = await resolveGitHubUsername();
+    if (resolved)
+        return sanitizeSlugPart(resolved);
+    throw new Error("Could not determine your GitHub username for the share URL namespace. " +
+        "Authenticate with `gh auth login`, set `git config --global github.user <user>`, " +
+        "or pass `--github-user <user>`.");
+}
+/** Build the R2 object key from a namespace username and a slug part. */
+export function buildShareKey(username, slugPart) {
+    const user = sanitizeSlugPart(username);
+    const part = sanitizeSlugPart(slugPart.replace(/\//g, '-'));
+    if (!user)
+        throw new Error('GitHub username is required for the share URL namespace.');
+    if (!part)
+        throw new Error('Share slug is empty.');
+    return `${user}/${part}`;
+}
 export async function publishFile(filePath, opts = {}) {
-    const cfg = readShareConfig();
+    const cfg = opts.config ?? readShareConfig();
     if (!cfg) {
         throw new Error("Not set up yet. Run 'agents share setup' (provision your own endpoint) or 'agents share join' (use an existing one).");
     }
-    const token = readWriteToken();
-    const slug = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
+    const token = opts.writeToken ?? readWriteToken();
+    const username = await resolveShareUsername(opts);
+    const analyticsToken = opts.analyticsToken ?? cfg.analyticsToken;
+    return publishToEndpoint(filePath, { baseUrl: cfg.baseUrl, token }, {
+        ...opts,
+        githubUser: username,
+        analyticsToken,
+    });
+}
+export async function publishToEndpoint(filePath, endpoint, opts = {}) {
+    const username = await resolveShareUsername(opts);
+    const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
+    const key = buildShareKey(username, slugPart);
     const expiresAt = parseExpire(opts.expire);
-    const pageUrl = `${cfg.baseUrl}/${slug}`;
+    const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const put = opts.uploader ??
         (async (u, b, h) => {
             const res = await fetch(u, { method: 'PUT', headers: h, body: new Uint8Array(b) });
             return { ok: res.ok, status: res.status, url: u };
         });
     const authHeaders = (contentType) => {
-        const h = { authorization: `Bearer ${token}`, 'content-type': contentType };
+        const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         return h;
     };
     let body = readFileSync(filePath);
     let coverUrl;
+    const isHtml = /\.html?$/i.test(filePath);
+    // Analytics: cookieless CF Web Analytics beacon, injected for HTML by default.
+    if (isHtml && opts.analytics !== false && opts.analyticsToken) {
+        body = Buffer.from(injectAnalyticsBeacon(body.toString('utf8'), opts.analyticsToken), 'utf8');
+    }
     // Cover: screenshot the page's hero → upload <slug>.png → inject og:image meta.
-    if (/\.html?$/i.test(filePath) && opts.cover !== false) {
+    if (isHtml && opts.cover !== false) {
         const res = await attachOgCover(filePath, body, {
             pngUrl: `${pageUrl}.png`,
             pageUrl,

package/dist/lib/share/worker-template.js

@@ -1,26 +1,30 @@
 // The Cloudflare Worker that fronts the R2 share bucket.
 //
 // One tiny Worker does both sides:
-//   - PUT  /<slug>  — bearer-gated (WRITE_TOKEN secret); writes the body to R2 via
-//                     the BUCKET binding, storing an optional expiry in object metadata.
-//   - GET  /<slug>  — public; streams the object from R2, 410s (and lazily deletes)
-//                     once its expiry has passed. A bucket lifecycle rule is the
-//                     durable sweeper; this is the immediate gate.
+//   - PUT  /<username>/<slug>  — bearer-gated (WRITE_TOKEN secret); writes the body
+//     to R2 via the BUCKET binding, storing an optional expires-at value in
+//     object metadata.
+//   - GET  /<username>/<slug>  — public; streams the object from R2, 410s (and lazily
+//     deletes) once its expiry has passed. A bucket lifecycle rule is the durable
+//     sweeper; this is the immediate gate.
+//   - GET  /<username>         — public gallery of that user's shares.
+//   - GET  /<slug>             — backward-compat flat slug (legacy shares before
+//     per-user namespaces).
 //
 // Emitted as a string (mirrors src/lib/serve/page.ts `renderPage()`), so it compiles
 // into `dist/**` and ships with no package.json#files change. `provision.ts` uploads
 // this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
 /** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
 export function renderWorkerScript() {
-    return `// GENERATED by agents-cli \`agents share setup\` — do not edit here; edit
+    return `// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.
 export default {
   async fetch(request, env) {
     const url = new URL(request.url);
-    const key = decodeURIComponent(url.pathname.replace(/^\\/+/, ''));
+    const path = decodeURIComponent(url.pathname.replace(/^\\/+/, ''));
 
-    if (!key) {
-      return new Response('agents share — POST is not it; PUT /<slug> to publish, GET /<slug> to view.', {
+    if (!path) {
+      return new Response('agents share — POST is not it; PUT /<username>/<slug> to publish, GET /<username>/<slug> to view.', {
         status: 200, headers: { 'content-type': 'text/plain; charset=utf-8' },
       });
     }
@@ -32,19 +36,28 @@ export default {
       }
       const expiresAt = request.headers.get('x-share-expires-at') || '';
       const contentType = request.headers.get('content-type') || 'text/html; charset=utf-8';
-      await env.BUCKET.put(key, request.body, {
+      await env.BUCKET.put(path, request.body, {
         httpMetadata: { contentType },
-        customMetadata: expiresAt ? { expiresAt } : {},
+        customMetadata: expiresAt ? { 'expires-at': expiresAt } : {},
       });
-      return json({ ok: true, url: url.origin + '/' + key, expiresAt: expiresAt || null }, 200);
+      return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null }, 200);
     }
 
     if (request.method === 'GET' || request.method === 'HEAD') {
-      const obj = await env.BUCKET.get(key);
+      // Single-segment path may be a user gallery OR a legacy flat slug.
+      const segments = path.split('/').filter(Boolean);
+      if (segments.length === 1) {
+        const list = await env.BUCKET.list({ prefix: segments[0] + '/', limit: 1 });
+        if (list.objects && list.objects.length > 0) {
+          return renderGallery(env.BUCKET, url.origin, segments[0], request.method);
+        }
+      }
+
+      const obj = await env.BUCKET.get(path);
       if (!obj) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
-      const expiresAt = obj.customMetadata && obj.customMetadata.expiresAt;
+      const expiresAt = obj.customMetadata && obj.customMetadata['expires-at'];
       if (expiresAt && Date.now() > Date.parse(expiresAt)) {
-        await env.BUCKET.delete(key);
+        await env.BUCKET.delete(path);
         return new Response('gone — this link has expired', { status: 410, headers: { 'content-type': 'text/plain' } });
       }
       const headers = new Headers();
@@ -58,14 +71,67 @@ export default {
     if (request.method === 'DELETE') {
       const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
       if (!env.WRITE_TOKEN || !safeEqual(presented, env.WRITE_TOKEN)) return json({ error: 'unauthorized' }, 401);
-      await env.BUCKET.delete(key);
-      return json({ ok: true, deleted: key }, 200);
+      await env.BUCKET.delete(path);
+      return json({ ok: true, deleted: path }, 200);
     }
 
     return new Response('method not allowed', { status: 405 });
   },
 };
 
+async function renderGallery(bucket, origin, user, method) {
+  const objects = [];
+  let cursor;
+  do {
+    const list = await bucket.list({ prefix: user + '/', limit: 1000, cursor, include: ['customMetadata'] });
+    objects.push(...(list.objects || []));
+    cursor = list.truncated ? list.cursor : undefined;
+  } while (cursor);
+
+  const activeObjects = objects.filter(o => {
+    if (o.key.endsWith('.png')) return false;
+    const expiresAt = o.customMetadata && o.customMetadata['expires-at'];
+    return !(expiresAt && Date.now() > Date.parse(expiresAt));
+  });
+  const items = activeObjects.map(o => {
+    const slug = o.key.slice(o.key.indexOf('/') + 1);
+    const url = origin + '/' + o.key;
+    return { slug, url, updated: o.uploaded };
+  });
+
+  if (method === 'HEAD') {
+    return new Response(null, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' } });
+  }
+
+  const html =
+    '<!doctype html><html><head>' +
+    '<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">' +
+    '<title>' + escapeHtml(user) + ' — agents share</title>' +
+    '<style>' +
+    'body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;max-width:720px;margin:48px auto;padding:0 24px;color:#111;background:#fafafa}' +
+    'h1{font-size:28px;margin-bottom:8px}a{color:#0a0a0a;text-decoration:none;border-bottom:1px solid #999}' +
+    'a:hover{border-color:#111}ul{list-style:none;padding:0}li{margin:16px 0}' +
+    '.slug{font-weight:600}.meta{color:#666;font-size:14px}' +
+    '</style></head><body>' +
+    '<h1>@' + escapeHtml(user) + '</h1>' +
+    '<p class="meta">' + items.length + ' shared ' + (items.length === 1 ? 'page' : 'pages') + '</p>' +
+    '<ul>' +
+    items.map(i =>
+      '<li><a class="slug" href="' + escapeHtml(i.url) + '">' + escapeHtml(i.slug) + '</a>' +
+      '<br><span class="meta">' + new Date(i.updated).toISOString().slice(0, 10) + '</span></li>'
+    ).join('') +
+    '</ul></body></html>';
+  return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'public, max-age=60' } });
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
 function json(body, status) {
   return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
 }

package/dist/lib/shims.d.ts

@@ -99,6 +99,14 @@ export declare function shimTargetsFor(platform: NodeJS.Platform): {
  * Create a shim for an agent.
  */
 export declare function createShim(agent: AgentId): string;
+/** The POSIX pass-through shim for a brand. */
+export declare function generateBrandShim(name: string): string;
+/** Write a brand's pass-through shim(s) onto PATH; returns the shim path. */
+export declare function createBrandShim(name: string): string;
+/** True when the file at the given path is an agents-cli brand shim. */
+export declare function isBrandShim(filePath: string): boolean;
+/** Remove a brand's shim companions. Returns true if anything was removed. */
+export declare function removeBrandShim(name: string): boolean;
 /**
  * Remove the shim for an agent.
  */
@@ -500,6 +508,7 @@ export declare function addShimsToPath(overrides?: {
     shimsDir?: string;
 }): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
+export declare function listAgentsWithNonIsolatedInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in
  * the current version but missing from the target.