@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/commands/share.d.ts

@@ -1,293 +0,0 @@
-import { type Command } from 'commander';
-import { type ShareConfig } from '../lib/share/config.js';
-import { type CloudflareRequester } from '../lib/share/provision.js';
-import { type PublishResult, type ShareVisibility } from '../lib/share/publish.js';
-import { deleteShare, type DeleteShareResult } from '../lib/share/delete.js';
-import type { PhoenixSession } from '../lib/identity/client.js';
-export declare function formatSharePublishResult(result: PublishResult, json?: boolean): string;
-/** 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 declare function shareTemplateStatus(cfg: ShareConfig): 'current' | 'outdated' | 'unknown';
-/** One published object as reported by the Worker's `?format=json` listing route. */
-interface ShareListItem {
-    slug: string;
-    url: string;
-    /** Object size in bytes. */
-    size: number;
-    /** Stored content type, or null if the Worker had none recorded. */
-    contentType: string | null;
-    /** ISO timestamp the object was last written (R2 `uploaded`). */
-    publishedAt: string;
-    /** ISO auto-expire timestamp, or null for a permanent share. */
-    expiresAt: string | null;
-    /** Human display title (explicit `--label` or auto-derived), or null for a
-     * share published before this field existed. */
-    label: string | null;
-    /** Harness/agent name that published this (`AGENTS_AGENT_NAME`), or null. */
-    agent: string | null;
-    /** Session id that published this, or null. */
-    session: string | null;
-    /** Hostname the publish ran from, or null. */
-    host: string | null;
-    /** git repo name at publish time, or null (published outside a git repo, or
-     * before this field existed). */
-    repo: string | null;
-    /** Count of retained prior versions under this slug (see `share revisions`). */
-    revisionCount: number;
-    /** The visibility stamped at publish time: public | unlisted | me | org.
-     * Missing on Workers that predate this field → treated as public. */
-    visibility: ShareVisibility;
-    /** Arbitrary `--meta key=value` entries attached at publish time (RUSH-2683)
-     * — everything that isn't a reserved provenance/label key. `{}` when none
-     * were set, or when the deployed Worker predates this field. */
-    meta: Record<string, string>;
-}
-interface ShareListResult {
-    /** The namespace listed. */
-    user: string;
-    count: number;
-    objects: ShareListItem[];
-}
-/** DI seam for tests — override the real HTTP GET of the JSON listing route.
- * The optional `headers` carry the owner bearer for hidden-visibility listings. */
-type ListingFetchFn = (url: string, headers?: Record<string, string>) => Promise<{
-    status: number;
-    contentType: string;
-    body: string;
-}>;
-interface ShareEditResult {
-    ok: true;
-    url: string;
-    label: string | null;
-    meta: Record<string, string>;
-    /** The visibility the page now carries (present on Workers that support the
-     * visibility edit; absent from an older deployed template). */
-    visibility?: ShareVisibility;
-    /** The visibility the page had before this edit, when the Worker reports it. */
-    previousVisibility?: ShareVisibility;
-}
-export declare function runShareEdit(target: string, opts: {
-    githubUser?: string;
-    config?: ShareConfig;
-    writeToken?: string;
-    byo?: boolean;
-    session?: PhoenixSession | null;
-    label?: string | null;
-    meta?: Record<string, string>;
-    metaMode?: 'merge' | 'replace';
-    removeMeta?: string[];
-    /** Change the page's visibility in place (public | unlisted | me | org).
-     * A metadata-only rewrite like label/meta — the body is untouched, so no
-     * revision is created. me/org require a Phoenix session. `private` is
-     * rejected here — token-gating needs a fresh viewer key only the publish
-     * path mints (PHNX-3654). */
-    visibility?: ShareVisibility;
-    force?: boolean;
-    fetchEdit?: typeof fetch;
-}): Promise<ShareEditResult>;
-/** 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 declare function parseShareListing(user: string, body: string): ShareListResult;
-/** 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. Signed-in users hit the managed
- * endpoint; BYO still uses `readShareConfig()`. */
-export declare function runShareList(opts?: {
-    githubUser?: string;
-    config?: ShareConfig;
-    writeToken?: string;
-    byo?: boolean;
-    /** DI seam — override `readSession()`. Named `phoenixSession` because
-     * `session` is already the listing filter (session id). */
-    phoenixSession?: PhoenixSession | null;
-    fetchListing?: ListingFetchFn;
-    /** Only shares published by this agent/harness (case-insensitive, exact). */
-    agent?: string;
-    /** Only shares published from this session id (exact). */
-    session?: string;
-    /** Only shares whose label contains this text (case-insensitive substring). */
-    label?: string;
-    /** Only shares matching every provided `--meta key=value` entry. */
-    meta?: Record<string, string>;
-    /** Visibility filter. `public` (default) lists only public gallery pages;
-     * `unlisted`/`me`/`org` include that owner's hidden pages; `all` includes
-     * every active page. Hidden scopes send the owner's bearer and `scope=mine`. */
-    scope?: 'public' | 'unlisted' | 'private' | 'me' | 'org' | 'all';
-}): Promise<ShareListResult>;
-/** Client-side filtering over an already-fetched listing (RUSH-2683) — the
- * Worker has no query surface for this, so it narrows the fetched set instead
- * of a second round trip. `count` reflects the FILTERED set, matching what the
- * caller actually sees. */
-export declare function applyShareListFilters(result: ShareListResult, filters: {
-    agent?: string;
-    session?: string;
-    label?: string;
-    meta?: Record<string, string>;
-    scope?: 'public' | 'unlisted' | 'private' | 'me' | 'org' | 'all';
-}): ShareListResult;
-export declare function formatShareList(result: ShareListResult, json?: boolean): string;
-/** One retained prior version of a slug, as reported by the Worker's
- * `?revisions=json` route. */
-interface ShareRevisionItem {
-    /** R2 object key, `<user>/<slug>/rev-<ts>-<rand>`. */
-    key: string;
-    url: string;
-    size: number;
-    contentType: string | null;
-    /** ISO timestamp this version was replaced (when the copy was made). */
-    uploadedAt: string;
-    expiresAt: string | null;
-    label: string | null;
-    agent: string | null;
-    session: string | null;
-    host: string | null;
-    repo: string | null;
-    /** Arbitrary `--meta key=value` entries attached at publish time (RUSH-2683)
-     * — everything that isn't a reserved provenance/label key. `{}` when none
-     * were set, or when the deployed Worker predates this field. */
-    meta: Record<string, string>;
-}
-interface ShareRevisionsResult {
-    /** The canonical `<user>/<slug>` key these are revisions of. */
-    key: string;
-    count: number;
-    revisions: ShareRevisionItem[];
-}
-/** Parse the Worker's `?revisions=json` payload, failing loud (with the same
- * outdated-template hint as {@link parseShareListing}) on an unexpected shape. */
-export declare function parseShareRevisions(key: string, body: string): ShareRevisionsResult;
-/** Fetch and parse the retained prior versions of one published slug. `target`
- * accepts the same three forms as `agents artifacts unshare` (a full URL, `<user>/<slug>`,
- * or a bare slug resolved against the caller's own namespace) — reuses
- * {@link resolveDeleteTarget} rather than re-deriving the key. */
-export declare function runShareRevisions(target: string, opts?: {
-    githubUser?: string;
-    config?: ShareConfig;
-    writeToken?: string;
-    byo?: boolean;
-    session?: PhoenixSession | null;
-    fetchListing?: ListingFetchFn;
-}): Promise<ShareRevisionsResult>;
-/** The resolved page URL plus a signed-in-owner URL that carries a one-time
- * login ticket, so opening it activates the shared page's inline visibility
- * control (PHNX-3370). */
-interface ShareOpenResult {
-    /** `<user>/<slug>` key of the target page. */
-    key: string;
-    /** The plain page URL (no ticket). */
-    url: string;
-    /** The page URL with `?phoenix_ticket=<t>` — open THIS to be the owner. */
-    ownerUrl: string;
-}
-/** Mint a one-time login ticket for the signed-in owner and build the URL that
- * opens their own published page **as the owner**, so the inline visibility
- * control is live in the browser. Managed backend only — the control is gated on
- * the Phoenix identity, and BYO (WRITE_TOKEN) endpoints have no per-viewer login.
- * `target` accepts the same three forms as `visibility`/`unshare` (a full URL,
- * `<user>/<slug>`, or a bare slug in the caller's namespace). */
-export declare function runShareOpen(target: string, opts?: {
-    githubUser?: string;
-    config?: ShareConfig;
-    session?: PhoenixSession | null;
-    /** DI seam — override the ticket-mint POST. */
-    fetchTicket?: (url: string, bearer: string) => Promise<{
-        status: number;
-        body: string;
-    }>;
-}): Promise<ShareOpenResult>;
-export declare function formatShareRevisions(result: ShareRevisionsResult, json?: boolean): string;
-export declare function formatShareDeleteResult(result: DeleteShareResult, json?: boolean): string;
-interface ShareDeleteCliOpts {
-    keepCover?: boolean;
-    keepRevisions?: boolean;
-    ifExists?: boolean;
-    forUser?: string;
-    deleteJson?: boolean;
-}
-/** Shared handler for `agents artifacts share delete <targets...>` and the
- * nested `agents artifacts 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.
- *
- * `deleteFn` is a DI seam for tests (defaults to the real `deleteShare`) — it is
- * never exposed as a CLI flag, only used to inject a fake config/checker/deleter
- * without touching the keychain or a live endpoint. */
-export declare function runShareDelete(targets: string[], opts: ShareDeleteCliOpts, deleteFn?: typeof deleteShare): Promise<void>;
-/**
- * Register the `share` subtree under its parent group — `agents artifacts share`
- * (see commands/artifacts.ts). `agents artifacts unshare` is the nested alias
- * registered via {@link registerUnshareCommand} on the artifacts group.
- * registration on the ROOT program, so it is {@link registerUnshareCommand}, not
- * part of this subtree.
- */
-export declare function registerShareCommands(artifactsCmd: Command): void;
-/**
- * Register `agents artifacts unshare <targets...>` as the nested alias of
- * `agents artifacts share delete`. Top-level `agents unshare` is retired.
- */
-export declare function registerUnshareCommand(artifactsCmd: Command): void;
-/** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
- * endpoint config + write token. Shared by both modes of `agents artifacts setup`
- * (the flag-driven provision and the interactive wizard). */
-export declare function runShareProvision(opts: {
-    bundle: string;
-    worker: string;
-    bucket: string;
-    account?: string;
-    token?: string;
-    domain?: string;
-    analyticsToken?: string;
-    request?: CloudflareRequester;
-    /** Bind PHOENIX_ID_BASE even when the mapped hostname is not the managed domain. */
-    managed?: boolean;
-}): Promise<void>;
-interface ShareUpdateResult {
-    updated: boolean;
-    templateHash: string;
-    baseUrl: string;
-    workerName: string;
-    /** True when this was a `--check` run: nothing was deployed, the fields below
-     * just report whether a deploy WOULD be needed. Used by the release train to
-     * decide during preflight — before it verifies deploy creds — whether this
-     * release even changes the Worker. */
-    checked?: boolean;
-    /** Whether the current `worker-template.ts` render differs from what the
-     * endpoint last deployed (or `--force`/an endpoint with no recorded hash). */
-    deployNeeded?: boolean;
-    /** The template hash the endpoint last deployed, per local config. Undefined
-     * on an endpoint provisioned before the hash field existed. */
-    deployedHash?: string;
-}
-/** 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 — and, on a
- * managed endpoint, `PHOENIX_ID_BASE` — survives the re-upload). Idempotent:
- * no-ops the script upload when the deployed hash already matches unless
- * `force`; a managed endpoint still re-applies `PHOENIX_ID_BASE`. */
-export declare function runShareUpdate(opts?: {
-    bundle?: string;
-    account?: string;
-    token?: string;
-    force?: boolean;
-    /** Report whether a deploy is needed and return without deploying. Needs no
-     * Cloudflare credentials — change detection is a pure local render+hash. */
-    check?: boolean;
-    request?: CloudflareRequester;
-    /** Bind PHOENIX_ID_BASE even when the configured hostname is not the managed domain. */
-    managed?: boolean;
-}): Promise<ShareUpdateResult>;
-/** Join an existing share endpoint (no provisioning): prompt for the endpoint
- * details + write token and persist them. Shared by `agents artifacts share join`
- * and the `agents artifacts setup` wizard. */
-export declare function runShareJoin(baseUrl?: string, opts?: {
-    token?: string;
-}): Promise<void>;
-export {};