firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/simple/library-sharing.js

@@ -0,0 +1,414 @@
+// `firedrill library recipients | grants | share | share-request | revoke |
+// dependents | bind`: reusing a library version across workspaces of one
+// organization and fixing a parameterized version's values.
+//
+// - Sharing grants one exact immutable version to another workspace, read
+//   only or read and use. Only an administrator of the owner workspace shares
+//   or revokes, and only after the human approves. A grant never lets the
+//   recipient edit the source and never carries credentials. Revoking stops
+//   new reads and uses; copies the recipient already made stay its own.
+// - The request key is printed before a grant is sent. The same key returns
+//   the original grant; a lost answer is read back, never sent under a new key.
+// - Binding creates a new private immutable version of this workspace with the
+//   exact parameter values. A world uses that bound version in place of the
+//   parameterized one. Nothing here provisions, runs or spends anything.
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { getLibraryRevision, sharedHere } from '../native/cloud-resources.js';
+import { errorCode, retryTransient } from '../native/control-plane.js';
+import { bindLibraryVersion, boundFrom, checkBindingValues, checkBoundVersion, DEPENDENT_KINDS, libraryId, listLibraryDependents, listLibraryGrants, listLibraryRecipients, recoverLibraryGrant, revokeLibraryGrant, shareLibraryVersion, } from '../native/library-sharing.js';
+import { answerLost, recoverLostWrite, recoverMetadataRequest } from '../native/metadata-requests.js';
+import { answeredRefusal } from '../native/world-reuse.js';
+import { readJsonObject } from './plan-apply.js';
+/** The verbs this module owns under `firedrill library`. */
+export const LIBRARY_SHARING_VERBS = new Set(['recipients', 'grants', 'share', 'share-request', 'revoke', 'dependents', 'bind']);
+const RECOVER_MS = 15_000;
+const VALUES_BYTES = 256 * 1024;
+const VALUE_PREVIEW = 120;
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: tty(options), openBrowser: options.openBrowser && !options.json });
+function pageNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]{0,6}$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --page with a number of 1 or more.', 2);
+    return Number(value);
+}
+/**
+ * Who owns a version and what this workspace may do with it. root's can_use
+ * is false for a shared version without a use grant, and for any version whose
+ * resource is archived (its owner's too) until the resource is restored.
+ */
+export function libraryAccess(scope, row) {
+    if (sharedHere(scope, row)) {
+        return `shared from workspace ${row.owner_workspace_id}: `
+            + `${row.can_use ? 'read and use' : 'read only here (shared read only, or its owner archived the resource)'}; never editable here`;
+    }
+    const parts = ['owned by this workspace'];
+    if (!row.can_edit)
+        parts.push('read only for your account');
+    if (row.state === 'archived')
+        parts.push('archived');
+    else if (!row.can_use)
+        parts.push('its resource is archived, so it cannot be used until the resource is restored');
+    return parts.join('; ');
+}
+/** Why a version cannot be bound or used here, with the one step that changes that. */
+function unusableText(scope, row) {
+    if (sharedHere(scope, row)) {
+        return `Workspace ${row.owner_workspace_id} shared this version read only, or has since archived its resource, so it cannot be bound here. `
+            + 'Ask its owner for read-and-use access.';
+    }
+    if (row.state === 'archived')
+        return 'This version records that its resource was archived, so it cannot be bound. Restore the resource and bind its new version.';
+    return `Its resource ${row.resource_id} is archived. Restore it first (firedrill library history ${row.resource_id} shows the revision to restore from).`;
+}
+/** A bound value, shortened for the terminal. */
+const preview = (value) => typeof value === 'number' ? String(value)
+    : JSON.stringify(value.length > VALUE_PREVIEW ? `${value.slice(0, VALUE_PREVIEW)}...` : value);
+/** Parameter declaration and binding lines for one version's detail. */
+export function parameterLines(row) {
+    const lines = [];
+    if (row.parameter_schema) {
+        lines.push(`Parameters (bind them before a world can use this version: firedrill library bind ${row.id} --file <values.json>):`);
+        for (const item of row.parameter_schema.parameters) {
+            const bounds = item.type === 'string' ? `string, at most ${item.maximum} characters` : `integer ${item.minimum}-${item.maximum}`;
+            lines.push(`  ${terminalText(item.name)}  ${bounds}  at ${terminalText(item.path.join('.'))}  `
+                + (item.required ? 'required' : `default ${terminalText(preview(item.default))}`));
+        }
+    }
+    if (row.parameter_binding) {
+        lines.push(`Bound from version ${row.parameter_binding.source_revision_id} with:`);
+        for (const [name, value] of Object.entries(row.parameter_binding.values))
+            lines.push(`  ${terminalText(name)} = ${terminalText(preview(value))}`);
+    }
+    return lines;
+}
+function grantLine(grant) {
+    return `  ${grant.id}  workspace ${grant.recipient_workspace_id}  ${grant.allow_use ? 'read and use' : 'read only'}  `
+        + `shared ${terminalText(grant.created_at)}${grant.revoked_at ? `  revoked ${terminalText(grant.revoked_at)}` : ''}`;
+}
+/** Root answers 404 for a page past the last one; that is not a missing version. */
+const pastEnd = (page, otherwise) => (error) => {
+    if ((page ?? 1) > 1 && error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('page_not_found', `There is no page ${page}. Start again from --page 1.`, 2);
+    }
+    return otherwise(error);
+};
+/** Only an organization administrator shares, revokes or lists recipients; root says so with admin_required. */
+const adminOnly = (error) => {
+    if (errorCode(error) === 'admin_required') {
+        throw new CliError('native_library_admin_required', 'Only an administrator of this organization can share library versions, revoke sharing or '
+            + 'list recipient workspaces. Nothing was shared or changed.', 3, error instanceof CliError ? error.httpStatus : null);
+    }
+    throw error;
+};
+const notOwned = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_library_version_not_found', 'That is not a library version this workspace can read. Find versions with firedrill library.', 2);
+    }
+    throw error;
+};
+/** Grants are listed and revoked only through the workspace that owns the version; any other gets 404. */
+const ownerOnly = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_library_version_not_found', 'That is not a library version this workspace owns. Only the owner workspace lists '
+            + 'or revokes its sharing grants; find this workspace\'s versions with firedrill library.', 2);
+    }
+    throw error;
+};
+/**
+ * Root's original-grant read is administrator-only, so reading a fresh key
+ * confirms that before the human is asked. It changes nothing.
+ */
+const confirmAdministrator = (scope, revisionId, signal) => recoverLibraryGrant(scope, { revisionId, requestKey: randomUUID(), signal }).catch(adminOnly);
+/** Each verb's arguments and flags, checked before anything is read or sent. */
+export function checkSharingArguments(args, options) {
+    const [verb, first, second, third] = args;
+    const takes = {
+        recipients: ['search', 'page'], grants: ['page'], share: ['request', 'approve'], 'share-request': [], revoke: ['approve'],
+        dependents: ['kind', 'page'], bind: ['file', 'request'],
+    };
+    const flags = { kind: '--kind', file: '--file', search: '--search', archived: '--archived',
+        page: '--page', expectedRevision: '--expected-revision', request: '--request', approve: '--approve-change', parameters: '--parameters',
+        removeParameters: '--remove-parameters' };
+    const extra = Object.keys(flags)
+        .filter((flag) => options[flag] !== undefined && options[flag] !== false && !takes[verb]?.includes(flag));
+    if (extra.length)
+        throw new CliError('arguments_invalid', `firedrill library ${verb} does not take ${extra.map((flag) => flags[flag]).join(', ')}.`, 2);
+    const counts = { recipients: 1, grants: 2, share: 4, 'share-request': 3, revoke: 3, dependents: 2, bind: 2 };
+    if (args.length !== counts[verb] || (verb === 'share' && third !== 'read' && third !== 'use')) {
+        throw new CliError('arguments_invalid', 'Use firedrill library recipients [--search <prefix>], library grants <version-id>, '
+            + 'library share <version-id> <workspace-id> read|use, library share-request <version-id> <request-key>, library revoke <version-id> <grant-id>, '
+            + 'library dependents <version-id> [--kind world|scenario] or library bind <version-id> [--file <values.json|->].', 2);
+    }
+    if (first !== undefined)
+        libraryId(first, 'library version id');
+    if (second !== undefined)
+        libraryId(second, verb === 'share' ? 'workspace id' : verb === 'revoke' ? 'grant id' : 'request key');
+    if (options.request !== undefined)
+        libraryId(options.request, 'request key');
+    if (verb === 'dependents' && options.kind !== undefined && !DEPENDENT_KINDS.includes(options.kind)) {
+        throw new CliError('arguments_invalid', `Use --kind ${DEPENDENT_KINDS.join('|')} with library dependents.`, 2);
+    }
+    pageNumber(options.page);
+}
+/** `share <version-id> <workspace-id> read|use [--request <key>] [--approve-change]`. */
+async function share(scope, args, options, emit) {
+    const [, version, recipientArg, mode] = args;
+    const signal = options.signal;
+    const recipient = libraryId(recipientArg, 'workspace id');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the version. Nothing was sent.', 2);
+    }
+    const allowUse = mode === 'use';
+    const access = allowUse ? 'read and use' : 'read only';
+    const requestKey = options.request === undefined ? randomUUID() : libraryId(options.request, 'request key');
+    const rerun = `firedrill library share ${version.toLowerCase()} ${recipient} ${mode} --request ${requestKey}`;
+    const read = `firedrill library share-request ${version.toLowerCase()} ${requestKey}`;
+    const row = await getLibraryRevision(scope, { revisionId: version, signal }).catch(notOwned);
+    if (sharedHere(scope, row)) {
+        throw new CliError('native_library_share_owner_only', `Only workspace ${row.owner_workspace_id}, which owns this version, can share it. Nothing was sent.`, 2);
+    }
+    // A grant already made under this key is shown, never made again. The read
+    // is administrator-only, so a fresh key also confirms that before the human is asked.
+    const original = await recoverLibraryGrant(scope, { revisionId: row.id, requestKey, signal }).catch(adminOnly);
+    if (original) {
+        if (original.recipient_workspace_id !== recipient || original.allow_use !== allowUse) {
+            throw new CliError('idempotency_conflict', `Request ${requestKey} shared this version with workspace ${original.recipient_workspace_id} `
+                + `(${original.allow_use ? 'read and use' : 'read only'}). Nothing was changed; share differently under a new request.`, 2);
+        }
+        emit('library_grant', original, `Already shared under request ${requestKey}:\n${grantLine(original)}`
+            + (original.revoked_at ? '\nThis grant was revoked. A request key is never renewed: to share again, start without --request.' : ''));
+        return;
+    }
+    if (row.state !== 'draft') {
+        throw new CliError('native_library_share_archived', 'This version records that its resource was archived, so it cannot be shared. Share an earlier '
+            + `version (firedrill library history ${row.resource_id}), or restore the resource and share its new version. Nothing was sent.`, 2);
+    }
+    emit('library_share_review', { version: row, recipient_workspace_id: recipient, allow_use: allowUse, request_key: requestKey }, [
+        `Share ${row.kind} ${terminalText(row.name)} v${row.revision} (version ${row.id}) with workspace ${recipient}: ${access}.`,
+        allowUse ? 'It can read this exact version and use it in its worlds, forks and parameter bindings.'
+            : 'It can read this exact version, but not use it in worlds, forks or bindings.',
+        'It can never edit this version or see other versions of it. Revoking later stops new reads and uses; copies it already made stay its own.',
+        allowUse && !row.can_use ? 'Its resource is archived now, so that workspace can read this version but cannot use it until the resource is restored.' : null,
+    ].filter((line) => line !== null).join('\n'));
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Share this version with workspace ${recipient} (${access})?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is shared.' },
+            { value: true, label: 'Share it', detail: `Grants ${access} access to this exact version only.` },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('library_share_consent_required', `Nothing was shared. After the human approves: ${rerun} --approve-change`, 2);
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (if interrupted, rerun ${rerun} --approve-change; ${read} reads it back)\n`);
+    let grant;
+    try {
+        // The same key and body replay the original grant, so a retry never shares twice.
+        grant = await retryTransient(() => shareLibraryVersion(scope, { revisionId: row.id, recipientWorkspaceId: recipient, allowUse, requestKey, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (errorCode(error) === 'admin_required')
+            adminOnly(error);
+        // A refusal with the service's own code wrote nothing; only an answer that never arrived is recovered by its key.
+        if (signal.aborted || !answerLost(error) || answeredRefusal(error)) {
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('native_library_recipient_unavailable', 'That workspace is not another active workspace of this organization, or this '
+                    + 'version is no longer shareable. Find recipients with firedrill library recipients. Nothing was shared.', 2);
+            }
+            throw error;
+        }
+        const recovered = await recoverLibraryGrant(scope, { revisionId: row.id, requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!recovered) {
+            throw new CliError('native_library_share_unconfirmed', `The share was not confirmed and may still land. Read it with ${read}, or rerun ${rerun} `
+                + '--approve-change, which returns the original instead of sharing twice. Never share it again under a new key.');
+        }
+        if (recovered.recipient_workspace_id !== recipient || recovered.allow_use !== allowUse) {
+            throw new CliError('native_response_unconfirmed', `Request ${requestKey} recorded a different grant, not this share. Nothing else was sent. `
+                + `Read it with ${read}.`, 2);
+        }
+        grant = recovered;
+    }
+    emit('library_grant', grant, `Shared ${row.kind} ${terminalText(row.name)} v${row.revision} with workspace ${grant.recipient_workspace_id}: `
+        + `${grant.allow_use ? 'read and use' : 'read only'}.\n${grantLine(grant)}\nRevoke it with firedrill library revoke ${row.id} ${grant.id}`);
+}
+/** `revoke <version-id> <grant-id> [--approve-change]`. */
+async function revoke(scope, args, options, emit) {
+    const [, version, grantArg] = args;
+    const signal = options.signal;
+    const revisionId = libraryId(version, 'library version id');
+    const grantId = libraryId(grantArg, 'grant id');
+    // Revoked by its exact id: root's revoke needs no listing, and grant history
+    // is never searched (an old grant may sit beyond any page bound). The
+    // administrator-only original-request read confirms access before the
+    // human is asked; it changes nothing.
+    const command = `firedrill library revoke ${revisionId} ${grantId}`;
+    await confirmAdministrator(scope, revisionId, signal);
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Revoke sharing grant ${grantId} of library version ${revisionId}?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is changed.' },
+            { value: true, label: 'Revoke', detail: 'Stops that workspace\'s new reads and uses. Copies it already made, and work already accepted, are not undone.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('library_share_consent_required', `Nothing was changed. After the human approves: ${command} --approve-change`, 2);
+    // Idempotent: a grant revoked earlier is returned as it is, with its original revocation time.
+    const revoked = await retryTransient(() => revokeLibraryGrant(scope, { revisionId, grantId, signal }), { signal, attempts: 3 })
+        .catch((error) => {
+        if (errorCode(error) !== 'admin_required' && error instanceof CliError && error.httpStatus === 404) {
+            throw new CliError('native_library_grant_not_found', 'That is not a sharing grant of a library version this workspace owns. Nothing was changed. '
+                + `List them with firedrill library grants ${revisionId}.`, 2);
+        }
+        return adminOnly(error);
+    });
+    emit('library_grant', revoked, `Grant ${revoked.id} is revoked (since ${terminalText(revoked.revoked_at)}).\n${grantLine(revoked)}\n`
+        + `Workspace ${revoked.recipient_workspace_id} can no longer read or newly use this version. Forks and bound copies it already made stay its own, `
+        + 'and work it already started is reconciled, not rolled back.');
+}
+/** The bound version's lines. */
+function boundText(bound, sourceId, lead) {
+    return [
+        `${lead} ${bound.kind} ${terminalText(bound.name)} into a new private resource ${bound.resource_id}, version ${bound.id} (v${bound.revision}).`,
+        ...parameterLines(bound),
+        `Use version ${bound.id} in a world in place of the parameterized version ${sourceId}. Nothing was provisioned or spent.`,
+        `Request key (rerun with --request to replay): ${bound.request_key}`,
+    ].join('\n');
+}
+/** `bind <version-id> [--file <values.json|->] [--request <key>]`. */
+async function bind(scope, args, options, emit) {
+    const [, version] = args;
+    const signal = options.signal;
+    const sourceId = libraryId(version, 'library version id');
+    const values = options.file === undefined ? {} : await readJsonObject(options.file, 'the parameter values', signal, VALUES_BYTES);
+    const requestKey = options.request === undefined ? randomUUID() : libraryId(options.request, 'request key');
+    // Root returns the original under a used key before it checks current
+    // access, so a replay reads that original first: it still answers after
+    // the source was revoked or its resource archived.
+    if (options.request !== undefined) {
+        const original = await recoverMetadataRequest(scope, { kind: 'library', requestKey }, signal);
+        if (original.state === 'withdrawn') {
+            throw new CliError('native_metadata_request_withdrawn', `Request ${requestKey} was withdrawn, so it will not land. Bind again without --request `
+                + 'only if the human still wants it.', 2);
+        }
+        if (original.state === 'removed')
+            throw new CliError('native_metadata_removed', `The version bound under request ${requestKey} has since been removed.`, 2);
+        if (original.state === 'committed') {
+            const receipt = original.receipt;
+            if (!boundFrom(receipt, sourceId)) {
+                throw new CliError('idempotency_conflict', `Request ${requestKey} recorded a different library change, not a binding of version ${sourceId}. `
+                    + 'Nothing was sent; bind without --request.', 2);
+            }
+            const recorded = receipt.parameter_binding.values;
+            const differ = Object.keys(values).filter((name) => recorded[name] !== values[name]);
+            if (differ.length) {
+                throw new CliError('idempotency_conflict', `Request ${requestKey} bound other values for ${differ.join(', ')}. Nothing was sent; `
+                    + 'bind these values without --request.', 2);
+            }
+            const bound = { ...checkBoundVersion(scope, receipt, { id: sourceId }), request_key: requestKey };
+            emit('library_binding', bound, boundText(bound, sourceId, 'Already bound under this request key:'));
+            return;
+        }
+    }
+    const source = await getLibraryRevision(scope, { revisionId: sourceId, signal }).catch(notOwned);
+    if (!source.parameter_schema) {
+        throw new CliError('native_library_not_parameterized', 'This version declares no parameters, so there is nothing to bind. Use it directly. Nothing was sent.', 2);
+    }
+    if (!source.can_use)
+        throw new CliError('native_library_use_not_granted', `${unusableText(scope, source)} Nothing was sent.`, 2);
+    const checked = checkBindingValues(source.parameter_schema, values);
+    const replay = `firedrill library bind ${source.id}${options.file === undefined ? '' : ' --file <the same values>'} --request ${requestKey}`;
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (rerun with --request ${requestKey} to replay this exact binding; firedrill library request ${requestKey} reads it back)\n`);
+    let bound;
+    try {
+        bound = await bindLibraryVersion(scope, { source, values: checked, requestKey, signal });
+    }
+    catch (error) {
+        // No answer: read the original back by its key. Never sent again here, never under a new key.
+        // A refusal with the service's own code (for example a 503 before any write) wrote nothing.
+        if (!answerLost(error) || answeredRefusal(error) || signal.aborted)
+            throw error;
+        const recovered = await recoverLostWrite(scope, { kind: 'library', requestKey }, { replay, withdraw: `firedrill library withdraw-request ${requestKey}` });
+        if (!boundFrom(recovered, source.id)) {
+            throw new CliError('native_response_unconfirmed', `Request ${requestKey} recorded a different library change, not this binding. Nothing else was sent.`, 2);
+        }
+        bound = { ...checkBoundVersion(scope, recovered, source), request_key: requestKey };
+    }
+    emit('library_binding', bound, boundText(bound, source.id, 'Bound'));
+}
+/**
+ * `library recipients [--search <prefix>] [--page <n>] | grants <version-id> [--page <n>]
+ *  | share <version-id> <workspace-id> read|use [--request <key>] [--approve-change] | share-request <version-id> <key>
+ *  | revoke <version-id> <grant-id> [--approve-change] | dependents <version-id> [--kind world|scenario] [--page <n>]
+ *  | bind <version-id> [--file <values.json|->] [--request <key>]`.
+ */
+export async function librarySharingCommand(args, options, emit) {
+    checkSharingArguments(args, options);
+    const [verb, first, second] = args;
+    const signal = options.signal;
+    const scope = await scopeOf(options);
+    if (verb === 'share')
+        return share(scope, args, options, emit);
+    if (verb === 'revoke')
+        return revoke(scope, args, options, emit);
+    if (verb === 'bind')
+        return bind(scope, args, options, emit);
+    if (verb === 'recipients') {
+        const number = pageNumber(options.page);
+        const page = await listLibraryRecipients(scope, { search: options.search, page: number, signal }).catch(pastEnd(number, adminOnly));
+        emit('library_recipients', page, [
+            `Workspaces of this organization a version can be shared with, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((one) => `  ${one.id}  ${terminalText(one.name)}`),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            'Share a version: firedrill library share <version-id> <workspace-id> read|use',
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'grants') {
+        const revisionId = libraryId(first, 'library version id');
+        const number = pageNumber(options.page);
+        const page = await listLibraryGrants(scope, { revisionId, page: number, signal }).catch(pastEnd(number, ownerOnly));
+        emit('library_grants', { revision_id: revisionId, ...page }, [
+            `Sharing grants of version ${revisionId}, page ${page.page} (${page.count} in all, revoked ones included):`,
+            ...page.results.map(grantLine),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            `Share it: firedrill library share ${revisionId} <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'share-request') {
+        const revisionId = libraryId(first, 'library version id');
+        const requestKey = libraryId(second, 'request key');
+        const grant = await recoverLibraryGrant(scope, { revisionId, requestKey, signal }).catch(adminOnly);
+        emit('library_grant', grant ?? { revision_id: revisionId, request_key: requestKey, state: 'not_found' }, grant ? grantLine(grant).trim()
+            : `None of your sharing requests for this version is recorded under ${requestKey}. An unanswered request may still arrive. `
+                + 'Rerun the original share with the same --request key (it returns the original instead of sharing twice); never share it under a new key.');
+        return;
+    }
+    const revisionId = libraryId(first, 'library version id');
+    const kind = (options.kind ?? 'world');
+    const number = pageNumber(options.page);
+    const page = await listLibraryDependents(scope, { revisionId, kind, page: number, signal }).catch(pastEnd(number, notOwned));
+    emit('library_dependents', { revision_id: revisionId, kind, ...page }, [
+        `${kind === 'world' ? 'World' : 'Scenario'} versions in this workspace that reference version ${revisionId}, page ${page.page} (${page.count} in all):`,
+        ...page.results.map((one) => one.kind === 'world'
+            ? `  world ${one.world_id} revision ${one.revision} (${one.id})  ${terminalText(one.name)}  ${terminalText(one.created_at)}`
+            : `  scenario ${terminalText(one.name)} v${one.revision} (version ${one.id})  ${terminalText(one.created_at)}`),
+        page.results.length ? null : '  none',
+        page.next ? `More: --page ${page.page + 1}` : null,
+        'Each is an exact version. Other workspaces\' uses are never shown here.',
+        kind === 'world' ? `Scenario versions: firedrill library dependents ${revisionId} --kind scenario` : null,
+    ].filter((line) => line !== null).join('\n'));
+}

package/dist/cli/src/simple/metadata-requests.js

@@ -0,0 +1,46 @@
+// `library|world|register|descriptors request <key>` and `... withdraw-request <key>`:
+// read an original native metadata write back by its request key, or withdraw
+// it while it was never committed (see native/metadata-requests.ts). Neither
+// ever sends the change again.
+import { CliError } from '../http.js';
+import { selectOne } from '../prompts.js';
+import { metadataNoun, recoverMetadataRequest, withdrawMetadataRequest } from '../native/metadata-requests.js';
+/** What to say about one original, by its state. */
+function stateText(kind, key, state) {
+    const noun = metadataNoun(kind);
+    if (state === 'withdrawn')
+        return `The ${noun} with request key ${key} was withdrawn. It will not land.`;
+    if (state === 'removed')
+        return `The ${noun} with request key ${key} was saved and has since been removed.`;
+    return `No ${noun} with request key ${key} is saved yet. It may still land: replay the same command with --request ${key}, or withdraw it before making a different change.`;
+}
+export async function metadataRequestCommand(action, target, scope, options, emit, describe, withdrawCommand) {
+    const key = target.requestKey.toLowerCase();
+    const original = await recoverMetadataRequest(scope, target, options.signal);
+    if (action === 'request' || original.state !== 'not_found') {
+        // Committed, withdrawn or removed: there is nothing to withdraw, so this only reports it.
+        if (original.state === 'committed') {
+            emit('native_request', { kind: target.kind, request_key: key, state: 'committed', receipt: original.receipt }, `${describe(original.receipt)}\nRequest key: ${key}${action === 'withdraw-request' ? '\nIt was already saved, so there is nothing to withdraw.' : ''}`);
+            return;
+        }
+        emit('native_request', { kind: target.kind, request_key: key, state: original.state }, original.state === 'not_found' ? `${stateText(target.kind, key, original.state)} Withdraw it with: ${withdrawCommand}` : stateText(target.kind, key, original.state));
+        return;
+    }
+    if (!options.json && process.stdin.isTTY) {
+        const yes = await selectOne(`Withdraw this ${metadataNoun(target.kind)} (request ${key})?`, [
+            { value: true, label: 'Withdraw it', detail: 'It can never land after this. Nothing saved is deleted.' },
+            { value: false, label: 'Keep it', detail: 'It may still land.' }
+        ], options.signal);
+        if (!yes)
+            throw new CliError('canceled', 'The request was kept.', 130);
+    }
+    else if (!options.approve) {
+        throw new CliError('change_consent_required', `Withdrawing needs the human's approval. Nothing was withdrawn. After they approve: ${withdrawCommand} --approve-change`, 2);
+    }
+    const result = await withdrawMetadataRequest(scope, target, options.signal);
+    if (result.state === 'committed') {
+        emit('native_request', { kind: target.kind, request_key: key, state: 'committed', receipt: result.receipt }, `${describe(result.receipt)}\nRequest key: ${key}\nIt had already been saved, so nothing was withdrawn.`);
+        return;
+    }
+    emit('native_request', { kind: target.kind, request_key: key, state: 'withdrawn' }, `Withdrawn. The ${metadataNoun(target.kind)} with request key ${key} can no longer land; make a new change only if the human still wants it.`);
+}