@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/share.js

@@ -1,10 +1,14 @@
-// `agents share` — publish an HTML file to your own Cloudflare R2 behind a tiny
-// Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+// `agents artifacts share` — publish an HTML file to your own Cloudflare R2
+// behind a tiny Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+//
+// Registered under the `artifacts` group by commands/artifacts.ts; the
+// provisioning door lives beside it at `agents artifacts setup`
+// (commands/artifacts-setup.ts), which calls `runShareProvision` below.
 import { existsSync } from 'node:fs';
 import chalk from 'chalk';
-import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
-import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile } from '../lib/share/publish.js';
+import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
+import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, updateWorker, setWorkerSecret, } from '../lib/share/provision.js';
+import { publishFile, resolveShareUsername } from '../lib/share/publish.js';
 import { deleteShare } from '../lib/share/delete.js';
 import { renderWorkerScript } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
@@ -18,8 +22,132 @@ export function formatSharePublishResult(result, json = false) {
         lines.push(chalk.dim(`  cover ${result.coverUrl}`));
     if (result.expiresAt)
         lines.push(chalk.dim(`  expires ${new Date(result.expiresAt).toLocaleString()}`));
+    else
+        lines.push(chalk.dim('  expires never'));
+    if (result.unlisted)
+        lines.push(chalk.dim('  unlisted (hidden from gallery / share list)'));
     return lines.join('\n');
 }
+/** Compare the configured endpoint's last-deployed template hash against the
+ * hash of the CURRENT `worker-template.ts` render. A config with no recorded
+ * hash (every endpoint provisioned before this field existed) is "unknown" —
+ * never "current" or "outdated", since there is nothing to compare against. */
+export function shareTemplateStatus(cfg) {
+    if (!cfg.templateHash)
+        return 'unknown';
+    return cfg.templateHash === hashWorkerScript(renderWorkerScript()) ? 'current' : 'outdated';
+}
+/** Shown whenever the deployed Worker has no `?format=json` listing route — an
+ * endpoint provisioned before this feature. Points at the RUSH-2449 update path
+ * (`agents artifacts share update`) instead of letting the caller hit a 404 or an
+ * HTML body and get a confusing parse error. */
+const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents artifacts share list`. ' +
+    'Run `agents artifacts share update` to deploy the current Worker template, then retry (`agents artifacts share status` shows whether an update is due).';
+async function defaultListingFetch(url) {
+    const res = await fetch(url, { headers: { accept: 'application/json' } });
+    return { status: res.status, contentType: res.headers.get('content-type') ?? '', body: await res.text() };
+}
+/** Parse the Worker's listing JSON into a validated result, failing loud (with the
+ * outdated-template hint) on any body that isn't the expected shape — an old Worker
+ * serves the HTML gallery for a non-empty namespace, which must not be silently
+ * accepted as "you have published nothing". */
+export function parseShareListing(user, body) {
+    let data;
+    try {
+        data = JSON.parse(body);
+    }
+    catch {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const objectsRaw = data?.objects;
+    if (!data || typeof data !== 'object' || !Array.isArray(objectsRaw)) {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const objects = objectsRaw.map((o) => {
+        const item = o;
+        return {
+            slug: String(item.slug ?? ''),
+            url: String(item.url ?? ''),
+            size: typeof item.size === 'number' ? item.size : 0,
+            contentType: item.contentType == null ? null : String(item.contentType),
+            publishedAt: String(item.publishedAt ?? ''),
+            expiresAt: item.expiresAt == null ? null : String(item.expiresAt),
+        };
+    });
+    return { user, count: objects.length, objects };
+}
+/** Fetch and parse the machine-readable listing of the caller's namespace from the
+ * Worker's `?format=json` route. Fails loud when share was never configured, when
+ * the deployed template is known-outdated (RUSH-2449 templateHash), or when the
+ * live response proves the route is absent (404 or a non-JSON 200 = the old HTML
+ * gallery) — never a silent empty/wrong result. */
+export async function runShareList(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).");
+    }
+    // A known-stale template can't have the listing route — say so before any network
+    // call. 'unknown' (provisioned before templateHash tracking) is attempted, then
+    // caught by the response checks below if the route turns out to be absent.
+    const templateStatus = shareTemplateStatus(cfg);
+    if (templateStatus === 'outdated') {
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    const user = await resolveShareUsername({ githubUser: opts.githubUser });
+    const listUrl = `${cfg.baseUrl.replace(/\/+$/, '')}/${encodeURIComponent(user)}?format=json`;
+    const fetchListing = opts.fetchListing ?? defaultListingFetch;
+    const res = await fetchListing(listUrl);
+    if (res.status === 404) {
+        // A single-segment path 404s either because the namespace is genuinely empty
+        // (current template — the listing route gates on the namespace holding objects,
+        // so a namespace with nothing falls through to an object GET) OR because the
+        // endpoint predates the listing route entirely. The recorded templateHash
+        // disambiguates: a 'current' template HAS the route, so its 404 means an empty
+        // namespace ("nothing published"); otherwise the route may be absent, so point
+        // at `agents artifacts share update`.
+        if (templateStatus === 'current') {
+            return { user, count: 0, objects: [] };
+        }
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    if (res.status !== 200) {
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' completed.`);
+    }
+    if (!/application\/json/i.test(res.contentType)) {
+        // A 200 that isn't JSON means the old Worker ignored ?format=json and served
+        // the HTML gallery — the deployed template is outdated.
+        throw new Error(OUTDATED_TEMPLATE_HINT);
+    }
+    return parseShareListing(user, res.body);
+}
+/** Human-readable bytes, e.g. `1.2 KB`, `640 B`. */
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = n / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+export function formatShareList(result, json = false) {
+    if (json)
+        return JSON.stringify(result, null, 2);
+    if (result.count === 0) {
+        return chalk.dim(`No active pages published under @${result.user}.`);
+    }
+    const header = chalk.bold(`@${result.user}`) +
+        chalk.dim(`  ${result.count} published ${result.count === 1 ? 'page' : 'pages'}`);
+    const rows = result.objects.map((o) => {
+        const when = o.publishedAt ? o.publishedAt.slice(0, 10) : 'unknown';
+        const meta = `${when} · ${formatBytes(o.size)}${o.expiresAt ? ` · expires ${o.expiresAt.slice(0, 10)}` : ''}`;
+        return `${chalk.cyan(o.slug)}  ${chalk.dim(meta)}\n  ${chalk.green(o.url)}`;
+    });
+    return [header, ...rows].join('\n');
+}
 export function formatShareDeleteResult(result, json = false) {
     if (json)
         return JSON.stringify(result, null, 2);
@@ -33,8 +161,8 @@ export function formatShareDeleteResult(result, json = false) {
     }
     return lines.join('\n');
 }
-/** Shared handler for `agents share delete <targets...>` and the top-level
- * `agents unshare <targets...>` alias. Deletes each target independently and
+/** Shared handler for `agents artifacts share delete <targets...>` and the
+ * top-level `agents unshare <targets...>` alias. Deletes each target independently and
  * continues past a failed one (rm-style), reporting all results and exiting
  * non-zero if any target failed to verify as gone.
  *
@@ -76,10 +204,10 @@ function registerShareDeleteOptions(cmd) {
 }
 const SHARE_DELETE_EXAMPLES = `
       # Delete by full URL — also takes down the sibling OG cover
-      agents share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
+      agents artifacts share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
 
       # Delete by <user>/<slug>, or a bare slug in your own namespace
-      agents share delete octocat/my-plan-a1b2
+      agents artifacts share delete octocat/my-plan-a1b2
       agents unshare my-plan-a1b2
 
       # Several at once
@@ -96,16 +224,25 @@ const SHARE_DELETE_NOTES = `
   Worker's DELETE is idempotent and returns {"ok":true} even for a key that was
   never there, so that response alone is never proof of a takedown.
 
-  agents share delete === agents unshare (same command, different name).
+  agents artifacts share delete === agents unshare (same command, different name).
 `;
-export function registerShareCommands(program) {
-    const shareCmd = program
+/**
+ * Register the `share` subtree under its parent group — `agents artifacts share`
+ * (see commands/artifacts.ts). The top-level `agents unshare` alias is a sibling
+ * registration on the ROOT program, so it is {@link registerUnshareCommand}, not
+ * part of this subtree.
+ */
+export function registerShareCommands(artifactsCmd) {
+    const shareCmd = artifactsCmd
         .command('share')
         .description('Publish an HTML file to your own Cloudflare R2 and get a shareable link (~$0).')
         .argument('[file]', 'file to publish (HTML or any static asset)')
         .option('--slug <slug>', 'custom URL slug under your namespace (default: <project>-<feature>-<hash>)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config)')
-        .option('--expire <spec>', 'auto-expire, e.g. 30d, 12h, or 2026-08-01')
+        .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
+        .option('--unlisted', 'hide from the public gallery and `agents artifacts share list` (direct URL still works)')
+        .option('--private', 'alias of --unlisted')
+        .option('--force', 'publish even when the file contains emails or credential-shaped strings')
         .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
         .option('--no-analytics', 'skip injecting the Cloudflare Web Analytics beacon')
         .option('--json', 'emit machine-readable publish result for plan-render hooks and scripts')
@@ -120,14 +257,16 @@ export function registerShareCommands(program) {
             return;
         }
         try {
-            const { url, expiresAt, coverUrl } = await publishFile(file, {
+            const result = await publishFile(file, {
                 slug: opts.slug,
                 githubUser: opts.githubUser,
                 expire: opts.expire,
+                unlisted: opts.unlisted === true || opts.private === true,
+                force: opts.force,
                 cover: opts.cover,
                 analytics: opts.analytics,
             });
-            console.log(formatSharePublishResult({ url, expiresAt, coverUrl }, Boolean(opts.json)));
+            console.log(formatSharePublishResult(result, Boolean(opts.json)));
         }
         catch (e) {
             console.error(chalk.red(e.message));
@@ -136,17 +275,33 @@ export function registerShareCommands(program) {
     });
     setHelpSections(shareCmd, {
         examples: `
-      # Publish an HTML file — gets an auto OG cover + a shareable link
-      agents share ./out/plan.html
+      # Publish an HTML file — auto OG cover, default 30d expiry, shareable link
+      agents artifacts share ./out/plan.html
+
+      # Hide from the public gallery (direct URL still works) and expire sooner
+      agents artifacts share ./out/report.html --unlisted --expire 12h
+
+      # Permanent public page (opt out of the default 30d expiry)
+      agents artifacts share ./out/landing.html --slug landing --expire never
 
-      # Custom slug, expiring in 30 days
-      agents share ./out/report.html --slug q3-report --expire 30d
+      # Custom slug, expiring in 7 days
+      agents artifacts share ./out/report.html --slug q3-report --expire 7d
 ${SHARE_DELETE_EXAMPLES}
       # One-time setup (or join an existing endpoint)
-      agents share setup
-      agents share join https://share.agents-cli.sh
+      agents artifacts setup
+      agents artifacts share join https://share.agents-cli.sh
+
+      # Push a worker-template.ts change out to an already-provisioned endpoint
+      agents artifacts share update
+    `,
+        notes: `
+  Default expiry is 30d so an accidental publish decays. Pass --expire never for
+  a permanent link. --unlisted / --private hides the page from the public gallery
+  and agents artifacts share list; the direct URL is still world-readable
+  (unlisted, not secret). A pre-publish scan refuses emails and credential-shaped
+  strings unless --force is passed.
+${SHARE_DELETE_NOTES}
     `,
-        notes: SHARE_DELETE_NOTES,
     });
     const shareDeleteCmd = registerShareDeleteOptions(shareCmd
         .command('delete <targets...>')
@@ -155,53 +310,68 @@ ${SHARE_DELETE_EXAMPLES}
     shareDeleteCmd.action(async (targets, opts) => {
         await runShareDelete(targets, opts);
     });
-    const unshareCmd = registerShareDeleteOptions(program
-        .command('unshare <targets...>')
-        .description('Alias of `agents share delete` — take down a published page (and by default its OG cover).'));
-    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
-    unshareCmd.action(async (targets, opts) => {
-        await runShareDelete(targets, opts);
-    });
     shareCmd
-        .command('setup')
-        .description('One-time: provision an R2 bucket + Worker on your Cloudflare and save the config.')
-        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
-        .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
-        .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)
-        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
-        .option('--token <t>', 'Cloudflare API token (else read from the --bundle)')
-        .option('--domain <host>', `custom domain to map (default: ${DEFAULT_SHARE_DOMAIN}; workers.dev if zone is not visible)`)
-        .option('--analytics-token <token>', 'Cloudflare Web Analytics token to inject into published HTML pages')
-        .action(async (opts) => {
+        .command('join')
+        .description('Use an existing synced share endpoint and write token (no provisioning).')
+        .argument('[baseUrl]', 'base URL of the endpoint, e.g. https://share.agents-cli.sh')
+        .option('--token <token>', 'write token (else SHARE_WRITE_TOKEN env, existing bundle, or prompt)')
+        .action(async (baseUrl, opts) => {
         try {
-            await runShareProvision(opts);
+            await runShareJoin(baseUrl, opts);
         }
         catch (e) {
             console.error(chalk.red(e.message));
             process.exitCode = 1;
         }
     });
-    shareCmd
-        .command('join')
-        .description('Use an existing synced share endpoint and write token (no provisioning).')
-        .argument('[baseUrl]', 'base URL of the endpoint, e.g. https://share.agents-cli.sh')
-        .option('--token <token>', 'write token (else SHARE_WRITE_TOKEN env, existing bundle, or prompt)')
-        .action(async (baseUrl, opts) => {
+    const shareUpdateCmd = shareCmd
+        .command('update')
+        .description('Re-deploy the Worker script to the current template on an already-provisioned endpoint (idempotent).')
+        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
+        .option('--account <id>', 'Cloudflare account id override (default: the configured endpoint\'s account)')
+        .option('--token <t>', 'Cloudflare API token (else read from --bundle)')
+        .option('--force', 're-deploy even if the deployed template already matches')
+        .option('--json', 'emit a machine-readable result')
+        .action(async (opts) => {
         try {
-            await runShareJoin(baseUrl, opts);
+            const result = await runShareUpdate(opts);
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            if (result.updated) {
+                console.log(chalk.green(`Worker '${result.workerName}' updated → template ${result.templateHash.slice(0, 12)}…`));
+            }
+            else {
+                console.log(chalk.dim(`Worker '${result.workerName}' already matches the current template — no-op.`));
+            }
         }
         catch (e) {
             console.error(chalk.red(e.message));
             process.exitCode = 1;
         }
     });
+    setHelpSections(shareUpdateCmd, {
+        examples: `
+      # Push a worker-template.ts change out to your already-provisioned endpoint
+      agents artifacts share update
+
+      # Force a re-deploy even though the template hash already matches
+      agents artifacts share update --force
+    `,
+        notes: `
+  Reuses the existing account/worker/bucket from 'agents artifacts share status' and the
+  existing write token — it never re-provisions a bucket, touches routes, or
+  regenerates the token. See 'agents artifacts share status' for whether an update is due.
+    `,
+    });
     shareCmd
         .command('status')
         .description('Show the configured share endpoint and namespace.')
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         console.log(`${chalk.bold('endpoint')}  ${chalk.green(cfg.baseUrl)}`);
@@ -209,6 +379,48 @@ ${SHARE_DELETE_EXAMPLES}
         const user = await resolveGitHubUsername();
         console.log(`${chalk.bold('namespace')} ${user ? chalk.cyan(`${cfg.baseUrl}/${user}`) : chalk.yellow('unknown — set gh auth or github.user')}`);
         console.log(`${chalk.bold('analytics')} ${analyticsEnabled(cfg) ? chalk.green('enabled') : chalk.dim('not configured')}`);
+        const templateStatus = shareTemplateStatus(cfg);
+        const templateLabel = templateStatus === 'current'
+            ? chalk.green('current')
+            : templateStatus === 'outdated'
+                ? chalk.yellow('outdated — run `agents artifacts share update`')
+                : chalk.dim("unknown — provisioned before version tracking; run `agents artifacts share update` to adopt it");
+        console.log(`${chalk.bold('template')}  ${templateLabel}`);
+    });
+    const shareListCmd = shareCmd
+        .command('list')
+        .description("List the pages you've published to your share namespace (human table; --json for scripts).")
+        .option('--github-user <user>', 'GitHub username whose namespace to list (default: resolved from gh/git config)')
+        .option('--json', 'emit the machine-readable listing (slug, url, size, contentType, publishedAt, expiresAt)')
+        .action(async (opts) => {
+        try {
+            const result = await runShareList({ githubUser: opts.githubUser });
+            console.log(formatShareList(result, Boolean(opts.json)));
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(shareListCmd, {
+        examples: `
+      # Everything you've published, newest first
+      agents artifacts share list
+
+      # Machine-readable — e.g. pull every still-public URL with jq
+      agents artifacts share list --json | jq -r '.objects[].url'
+
+      # List another namespace
+      agents artifacts share list --github-user octocat
+    `,
+        notes: `
+  Lists the ACTIVE pages in your namespace — expired links and the sibling .png OG
+  covers are omitted (it mirrors the public gallery). It reads the endpoint's JSON
+  listing route, which ships with the current Worker template. If your deployed
+  Worker predates this feature the command says so and points you at 'agents
+  artifacts share update' (RUSH-2449) rather than returning a wrong or empty result
+  — see 'agents artifacts share status' for whether an update is due.
+    `,
     });
     shareCmd
         .command('analytics')
@@ -216,7 +428,7 @@ ${SHARE_DELETE_EXAMPLES}
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         if (!analyticsEnabled(cfg)) {
@@ -236,9 +448,24 @@ ${SHARE_DELETE_EXAMPLES}
         }
     });
 }
+/**
+ * Register the top-level `agents unshare <targets...>` alias of
+ * `agents artifacts share delete`. It takes the ROOT program (not the artifacts
+ * group) because it is deliberately a top-level convenience verb — taking a page
+ * down is the one artifact action typed often enough to keep at the root.
+ */
+export function registerUnshareCommand(program) {
+    const unshareCmd = registerShareDeleteOptions(program
+        .command('unshare <targets...>')
+        .description('Alias of `agents artifacts share delete` — take down a published page (and by default its OG cover).'));
+    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
+    unshareCmd.action(async (targets, opts) => {
+        await runShareDelete(targets, opts);
+    });
+}
 /** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
- * endpoint config + write token. Shared by `agents share setup` and the unified
- * `agents setup share` wizard. */
+ * endpoint config + write token. Shared by both modes of `agents artifacts setup`
+ * (the flag-driven provision and the interactive wizard). */
 export async function runShareProvision(opts) {
     const { default: ora } = await import('ora');
     const { input } = await import('@inquirer/prompts');
@@ -253,6 +480,7 @@ export async function runShareProvision(opts) {
     const bucketName = opts.bucket;
     const token = generateWriteToken();
     const requestedDomain = cleanHostname(opts.domain) ?? DEFAULT_SHARE_DOMAIN;
+    const script = renderWorkerScript();
     const spin = ora('Provisioning on Cloudflare…').start();
     try {
         const provisionOpts = opts.request ? { request: opts.request } : {};
@@ -260,7 +488,7 @@ export async function runShareProvision(opts) {
         spin.text = `R2 bucket '${bucketName}' ready`;
         await configureBucketLifecycle(apiToken, accountId, bucketName, provisionOpts);
         spin.text = `R2 bucket '${bucketName}' lifecycle ready`;
-        await deployWorker(apiToken, accountId, workerName, renderWorkerScript(), bucketName, provisionOpts);
+        await deployWorker(apiToken, accountId, workerName, script, bucketName, provisionOpts);
         spin.text = `Worker '${workerName}' deployed`;
         await setWorkerSecret(apiToken, accountId, workerName, token, provisionOpts);
         spin.text = `Worker '${workerName}' write token set`;
@@ -280,11 +508,19 @@ export async function runShareProvision(opts) {
             }
         }
         spin.succeed('Provisioned');
-        const cfg = { baseUrl, accountId, workerName, bucketName, domain, analyticsToken: opts.analyticsToken };
+        const cfg = {
+            baseUrl,
+            accountId,
+            workerName,
+            bucketName,
+            domain,
+            analyticsToken: opts.analyticsToken,
+            templateHash: hashWorkerScript(script),
+        };
         writeShareConfig(cfg);
         storeWriteToken(token);
         console.log(chalk.green(`\nShare endpoint ready → ${chalk.bold(baseUrl)}`));
-        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents share <file>'));
+        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents artifacts share <file>'));
         console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --host <box>' and pull config with 'agents repo pull'.`));
     }
     catch (e) {
@@ -292,6 +528,32 @@ export async function runShareProvision(opts) {
         throw e;
     }
 }
+/** Re-deploy the Worker script on an ALREADY-provisioned endpoint to match the
+ * current `worker-template.ts`. Reuses the existing account/worker/bucket and
+ * write token from `readShareConfig()`/the `share` bundle — never creates a
+ * bucket, touches routes/domains, or regenerates the token (see
+ * `updateWorker` in `lib/share/provision.ts` for how the token survives the
+ * re-upload). Idempotent: no-ops when the deployed hash already matches
+ * unless `force`. */
+export async function runShareUpdate(opts = {}) {
+    const cfg = readShareConfig();
+    if (!cfg) {
+        throw new Error("Not configured. Run 'agents artifacts setup' (to provision) or 'agents artifacts share join' first.");
+    }
+    const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle ?? DEFAULT_CF_BUNDLE, {
+        apiToken: opts.token,
+        accountId: opts.account,
+    });
+    const accountId = opts.account || acctFromBundle || cfg.accountId;
+    const writeToken = readWriteToken();
+    const script = renderWorkerScript();
+    const provisionOpts = { ...(opts.request ? { request: opts.request } : {}), force: opts.force };
+    const result = await updateWorker(apiToken, accountId, cfg.workerName, cfg.bucketName, script, writeToken, cfg.templateHash, provisionOpts);
+    if (!result.skipped) {
+        writeShareConfig({ ...cfg, templateHash: result.templateHash });
+    }
+    return { updated: !result.skipped, templateHash: result.templateHash, baseUrl: cfg.baseUrl, workerName: cfg.workerName };
+}
 function cleanHostname(domain) {
     const raw = domain?.trim().replace(/\/+$/, '');
     if (!raw)
@@ -305,14 +567,14 @@ function cleanHostname(domain) {
     }
 }
 /** Join an existing share endpoint (no provisioning): prompt for the endpoint
- * details + write token and persist them. Shared by `agents share join` and the
- * unified `agents setup share` wizard. */
+ * details + write token and persist them. Shared by `agents artifacts share join`
+ * and the `agents artifacts setup` wizard. */
 export async function runShareJoin(baseUrl, opts = {}) {
     const { password, input } = await import('@inquirer/prompts');
     const existing = readShareConfig();
     const clean = baseUrl?.replace(/\/+$/, '');
     if (!clean && !existing) {
-        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents share join <baseUrl>.");
+        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents artifacts share join <baseUrl>.");
     }
     let cfg;
     if (existing && (!clean || clean === existing.baseUrl)) {
@@ -345,5 +607,5 @@ export async function runShareJoin(baseUrl, opts = {}) {
         throw new Error('A write token is required to join.');
     writeShareConfig(cfg);
     storeWriteToken(token);
-    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents share <file>'));
+    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents artifacts share <file>'));
 }

package/dist/commands/skills.js

@@ -406,17 +406,6 @@ Examples:
             console.log(chalk.gray('Central source unchanged. Skills will re-sync on next agent launch.'));
         }
     });
-    // `skills sync` is gone — sync runs automatically when the agent launches.
-    skillsCmd
-        .command('sync', { hidden: true })
-        .allowUnknownOption()
-        .allowExcessArguments()
-        .action(() => {
-        console.error(chalk.red('"agents skills sync" is gone.'));
-        console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup skills'));
-        process.exit(1);
-    });
     // `skills prune` moved to the top-level `agents prune cleanup` command.
     skillsCmd
         .command('prune', { hidden: true })

package/dist/commands/snapshot.js

@@ -82,7 +82,7 @@ export function registerSnapshotCommand(program) {
       # Fleet-wide active sessions (matches sessions --active scope)
       agents snapshot --json --all-hosts
 
-      # Inventory for one harness only (Factory-style usage poll)
+      # Inventory for one harness only (an AGI EXT-style usage poll)
       agents snapshot --json --agent claude
 
       # Run the whole snapshot on another device

package/dist/commands/ssh.d.ts

@@ -11,6 +11,8 @@
  */
 import type { Command } from 'commander';
 import { type FanOutDeviceTarget } from '../lib/devices/fleet.js';
+import type { AgentId } from '../lib/types.js';
+import { type HostHarnessResult } from '../lib/devices/harness-inventory.js';
 import { type CrabboxBox } from '../lib/crabbox/cli.js';
 /**
  * Live "Leased boxes" section for `agents devices` (F4, RUSH-1923), computed
@@ -43,5 +45,21 @@ export declare function showLeasedBoxesSection(opts: {
  * instead of reimplementing the logic.
  */
 export declare function raceFleetPingDeadline<T, Target extends FanOutDeviceTarget>(fanOut: Promise<import('../lib/devices/fleet.js').FanOutDeviceResult<T>[]>, remoteTargets: Target[], overallTimeoutMs: number): Promise<import('../lib/devices/fleet.js').FanOutDeviceResult<T>[]>;
+export interface HarnessInventoryOpts {
+    agents?: AgentId[];
+    devices?: string[];
+    refresh?: boolean;
+    json?: boolean;
+    local?: boolean;
+}
+/**
+ * Gather harness rows across the fleet: THIS host in process, every reachable
+ * peer over SSH. Shared by both `harnesses` and `accounts` (they differ only in
+ * how the rows are rendered). Honors an optional `--device` allowlist on both
+ * the local and remote rows. Bounded by the same per-device + overall deadlines
+ * as `fleet ping`, so one unreachable box can never stall the glance.
+ */
+export declare function collectFleetHarnesses(opts: HarnessInventoryOpts): Promise<HostHarnessResult[]>;
+export declare function runDevicesAccounts(opts: HarnessInventoryOpts): Promise<void>;
 /** Register both `agents ssh` and `agents devices`. */
 export declare function registerSshCommands(program: Command): void;