@postplus/cli 0.1.38 → 0.1.40

package/build/hosted-domain-commands.js

@@ -1,10 +1,30 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveFreshRemoteAuth } from './auth-session.js';
 import { buildPostPlusClientCompatibilityHeaders, formatPostPlusCompatibilityError, } from './client-compatibility.js';
 import { buildHostedRequestSchemaReport, buildMediaGenerationRequestDimensions, } from './hosted-request-schemas.js';
+import { buildVerbTargetIndex, } from './hosted-manifest-index.js';
 import { readLargeCreditQuoteConfirmationChallenge, } from './quote-confirmation.js';
+// Manifest-driven verb grammar indexes (SSOT projected from apps/web +
+// public-skill-metadata via the generated manifest). The verb/flag grammar,
+// runner-managed set, and enum sets all come from the manifest so the CLI never
+// hand-maintains a mirror of the Web hosted catalog.
+const MEDIA_VERB_ENDPOINTS = buildVerbTargetIndex('media');
+const RESEARCH_VERB_TARGETS = buildVerbTargetIndex('research');
+const PUBLISH_VERB_OPERATIONS = buildPublishVerbIndex();
+// Publish flattens to operation -> resolved target: the publish OPERATION is both
+// the subcommand and the target (no separate positional), unlike media/research.
+function buildPublishVerbIndex() {
+    const index = new Map();
+    for (const targets of buildVerbTargetIndex('publish').values()) {
+        for (const [operation, resolved] of targets) {
+            index.set(operation, resolved);
+        }
+    }
+    return index;
+}
 class HostedQuoteConfirmationRequiredError extends Error {
     challenge;
     constructor(message, challenge) {
@@ -13,15 +33,14 @@ class HostedQuoteConfirmationRequiredError extends Error {
         this.name = 'HostedQuoteConfirmationRequiredError';
     }
 }
-const HOSTED_DOMAIN_CAPABILITIES = {
-    media: new Set(['media-file', 'media-generation', 'video-analysis']),
-    mobile: new Set(['mobile-automation']),
-    publish: new Set(['social-publishing']),
-    research: new Set([
-        'public-content-collection',
-        'public-content-discovery',
-    ]),
-};
+class HostedProductRequestError extends Error {
+    productError;
+    constructor(productError) {
+        super(formatHostedProductErrorMessage(productError));
+        this.productError = productError;
+        this.name = 'HostedProductRequestError';
+    }
+}
 export async function runHostedDomainCommand(domain, args) {
     const [subcommand, ...rest] = args;
     if (domain === 'research') {
@@ -31,8 +50,8 @@ export async function runHostedDomainCommand(domain, args) {
         if (subcommand === 'collect') {
             return runResearchCollect(rest);
         }
-        if (subcommand === 'capability') {
-            return runHostedCapability(domain, rest);
+        if (subcommand === 'scrape') {
+            return runResearchScrape(rest);
         }
         printResearchHelp();
         return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
@@ -40,51 +59,689 @@ export async function runHostedDomainCommand(domain, args) {
     if (subcommand === 'schema') {
         return runHostedSchema(domain, rest);
     }
-    if (subcommand === 'capability') {
-        return runHostedCapability(domain, rest);
+    if (domain === 'media' && subcommand && MEDIA_VERB_ENDPOINTS.has(subcommand)) {
+        return runMediaVerb(subcommand, rest);
+    }
+    // publish: the OPERATION is the subcommand (no separate target positional).
+    if (domain === 'publish' &&
+        subcommand &&
+        PUBLISH_VERB_OPERATIONS.has(subcommand)) {
+        return runPublishOperation(subcommand, rest);
     }
-    printCapabilityHelp(domain);
+    printDomainVerbHelp(domain);
     return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
 }
-async function runResearchCollect(args) {
+// Manifest-driven verb grammar: `postplus media <verb> <endpointKey> ...`. The
+// endpoint's executionSurface decides the input shape — a flags surface maps
+// scalar intent/default fields to flags, a request-json surface reads the nested
+// envelope from `--request <file>`. Either way runner-managed fields (billing
+// dimensions, ids, tokens) are derived/minted by the runner, never agent-supplied.
+async function runMediaVerb(verb, args) {
+    const targets = MEDIA_VERB_ENDPOINTS.get(verb);
+    if (!targets) {
+        throw new Error(`Unknown media verb ${verb}.`);
+    }
+    const [targetKey, ...rest] = args;
+    if (!targetKey || targetKey.startsWith('--')) {
+        throw new Error(`postplus media ${verb} requires a target key. Run \`postplus media schema --json\` to list targets.`);
+    }
+    const resolved = targets.get(targetKey);
+    if (!resolved) {
+        throw new Error(`Unknown ${verb} target ${targetKey}. Valid: ${[...targets.keys()].join(', ')}.`);
+    }
+    // `postplus media <verb> <endpoint> --help`: render the endpoint's field-level
+    // contract (intent / default / runner-managed) instead of dispatching a request.
+    if (rest.some(isHelp)) {
+        printMediaEndpointHelp('media', verb, targetKey, resolved);
+        return 0;
+    }
+    if (resolved.capability === 'video-analysis') {
+        return runVideoAnalysisVerb({
+            args: rest,
+            modelKey: targetKey,
+            resolved,
+            verb,
+        });
+    }
+    if (resolved.surface === 'request-json') {
+        return runMediaVerbRequestJson({
+            args: rest,
+            endpointKey: targetKey,
+            resolved,
+            verb,
+        });
+    }
+    return runMediaVerbFlags({
+        args: rest,
+        endpointKey: targetKey,
+        resolved,
+        verb,
+    });
+}
+// Flags surface (e.g. audio-transcription): scalar intent/default fields map to
+// flags; runner-managed fields have no flag so the agent cannot pass them.
+async function runMediaVerbFlags(args) {
+    const { endpointKey, resolved, verb } = args;
+    const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
+    const fields = endpoint.fields;
+    const flagToField = new Map();
+    const booleanKeys = new Set(['json']);
+    const arrayKeys = new Set();
+    for (const field of fields) {
+        if (!field.flag) {
+            continue;
+        }
+        const key = field.flag.replace(/^--/u, '');
+        flagToField.set(key, field);
+        if (field.type === 'boolean') {
+            booleanKeys.add(key);
+        }
+        if (field.repeatable) {
+            arrayKeys.add(key);
+        }
+    }
+    const flags = parseFlags(args.args, booleanKeys, arrayKeys);
+    const outputPath = flags.values.get('output') ?? null;
+    const controlKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'output',
+        'quote-confirmation-token',
+        'skill',
+    ]);
+    // Reject unknown flags. This is how runner-managed fields (no flag) and typos
+    // are caught locally before any hosted call.
+    for (const key of [
+        ...flags.values.keys(),
+        ...flags.booleans,
+        ...flags.arrays.keys(),
+    ]) {
+        if (!flagToField.has(key) && !controlKeys.has(key)) {
+            throw new Error(`Unknown option for media ${verb}: --${key}.`);
+        }
+    }
+    const input = buildMediaVerbInput({
+        endpointKey,
+        fields,
+        flags,
+        verb,
+    });
+    return submitMediaGenerationRequest({
+        capability: resolved.capability,
+        endpointKey,
+        errorInputLabel: `media-${verb}-${endpointKey}`,
+        input,
+        json: flags.booleans.has('json'),
+        operationId: flags.values.get('hosted-operation-id') ??
+            `postplus-cli:media:${resolved.capability}:request:${randomUUID()}`,
+        outputPath,
+        quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
+        skillName: flags.values.get('skill') ?? resolved.skill,
+    });
+}
+// Request-json surface (e.g. seedance-submitter): the nested envelope is supplied
+// via `--request <file>`. capability/endpointKey come from the verb + positional,
+// so the body carries only the media-generation input. Runner-managed fields have
+// no flag and must not appear in the body — the CLI fast-fails if they do.
+async function runMediaVerbRequestJson(args) {
+    const { endpointKey, resolved, verb } = args;
+    const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
+    const flags = parseFlags(args.args, new Set(['json']));
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'output',
+        'quote-confirmation-token',
+        'request',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for media ${verb}: --${key}.`);
+        }
+    }
+    const requestPath = requireFlag(flags, 'request');
+    const outputPath = flags.values.get('output') ?? null;
+    const raw = await readJsonFile(requestPath);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`media ${verb} ${endpointKey} --request must be a JSON object of media-generation input.`);
+    }
+    const input = raw;
+    // Runner-managed fields are minted/derived by the CLI; reject them in the body so
+    // the agent cannot smuggle in ids, tokens, or billing dimensions.
+    for (const field of endpoint.fields) {
+        if (field.class === 'runner-managed' &&
+            Object.hasOwn(input, field.name)) {
+            throw new Error(`media ${verb} ${endpointKey} input must not include runner-managed field "${field.name}"; the CLI mints or derives it.`);
+        }
+    }
+    return submitMediaGenerationRequest({
+        capability: resolved.capability,
+        endpointKey,
+        errorInputLabel: requestPath,
+        input,
+        json: flags.booleans.has('json'),
+        operationId: flags.values.get('hosted-operation-id') ??
+            `postplus-cli:media:${resolved.capability}:request:${randomUUID()}`,
+        outputPath,
+        quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
+        skillName: flags.values.get('skill') ?? resolved.skill,
+    });
+}
+function requireResolvedEndpoint(resolved, verb, endpointKey) {
+    if (!resolved.endpoint) {
+        throw new Error(`media ${verb} ${endpointKey} resolved to a non-endpoint target; this verb requires a media-generation endpoint.`);
+    }
+    return resolved.endpoint;
+}
+// video-analysis verb (request-json surface). The agent authors an opaque Gemini
+// request object (contents + generationConfig) in `--request <file>`; capability,
+// operation, and modelKey come from the verb + positional, so the body posts
+// EXACTLY the locked Web contract. There is no field classification and no
+// estimatedUsage — the payload is forwarded verbatim as the Gemini request.
+async function runVideoAnalysisVerb(args) {
+    const { modelKey, resolved, verb } = args;
+    const flags = parseFlags(args.args, new Set(['json']));
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'output',
+        'quote-confirmation-token',
+        'request',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for media ${verb}: --${key}.`);
+        }
+    }
+    const requestPath = requireFlag(flags, 'request');
+    const outputPath = flags.values.get('output') ?? null;
+    const raw = await readJsonFile(requestPath);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`media ${verb} ${modelKey} --request must be a JSON object of Gemini request payload.`);
+    }
+    const payload = raw;
+    const body = {
+        capability: 'video-analysis',
+        operation: 'analyze',
+        modelKey,
+        payload,
+        operationId: flags.values.get('hosted-operation-id') ??
+            `postplus-cli:media:video-analysis:analyze:${randomUUID()}`,
+        quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
+    };
+    return runHostedCommand({
+        request: () => postHostedJson({
+            body,
+            pathName: '/api/postplus-cli/hosted/capability',
+            skillName: flags.values.get('skill') ?? resolved.skill,
+        }),
+        errorInputLabel: requestPath,
+        json: flags.booleans.has('json'),
+        outputPath,
+    });
+}
+// `media-file upload`: the generic local-file -> hosted storageReference verb.
+// Released skills ship no scripts, so any skill that must place a local file
+// behind a hosted reference before a hosted request (e.g. video-analysis before
+// `media analyze`) drives it through this verb. It is capability-generic: it has
+// no knowledge of any one skill's request payload, it only mints an opaque
+// storageReference the agent then embeds in its own hosted request. The runner
+// holds no provider keys — it asks the Web boundary for a signed upload target,
+// PUTs the bytes, and returns the storageReference the Web boundary issued.
+const MEDIA_FILE_MIME_BY_EXTENSION = {
+    '.gif': 'image/gif',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.m4a': 'audio/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.png': 'image/png',
+    '.wav': 'audio/wav',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+};
+function inferUploadMimeType(filePath) {
+    return (MEDIA_FILE_MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] ??
+        'application/octet-stream');
+}
+export async function runMediaFileCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === 'upload') {
+        return runMediaFileUpload(rest);
+    }
+    printMediaFileHelp();
+    return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
+}
+async function runMediaFileUpload(args) {
     const flags = parseFlags(args, new Set(['json']));
-    const runHandle = flags.values.get('run-handle');
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'input-file',
+        'json',
+        'mime',
+        'output',
+        'quote-confirmation-token',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for media-file upload: --${key}.`);
+        }
+    }
+    const inputFile = requireFlag(flags, 'input-file');
+    const absolutePath = path.resolve(inputFile);
+    const fileStat = await stat(absolutePath);
+    if (!fileStat.isFile()) {
+        throw new Error(`media-file upload source is not a file: ${absolutePath}`);
+    }
+    const mimeType = flags.values.get('mime') ?? inferUploadMimeType(absolutePath);
     const outputPath = flags.values.get('output') ?? null;
-    if (runHandle) {
-        const payload = await postHostedJson({
-            body: { runHandle },
-            pathName: '/api/postplus-cli/hosted/collection',
-            skillName: null,
+    const body = {
+        capability: 'media-file',
+        operation: 'create-upload-url',
+        file: {
+            mimeType,
+            name: path.basename(absolutePath),
+            sizeBytes: fileStat.size,
+        },
+        operationId: flags.values.get('hosted-operation-id') ??
+            `postplus-cli:media-file:create-upload-url:${randomUUID()}`,
+        quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
+    };
+    return runHostedCommand({
+        request: async () => {
+            const payload = await postHostedJson({
+                body,
+                pathName: '/api/postplus-cli/hosted/capability',
+                skillName: flags.values.get('skill') ?? null,
+            });
+            const output = readHostedUploadOutput(payload);
+            const signedUpload = readSignedUpload(output);
+            await putHostedMediaBytes(signedUpload, absolutePath);
+            return { storageReference: readStorageReferenceValue(output) };
+        },
+        errorInputLabel: inputFile,
+        json: flags.booleans.has('json'),
+        outputPath,
+    });
+}
+function readHostedUploadOutput(payload) {
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        const output = payload.output;
+        if (output && typeof output === 'object' && !Array.isArray(output)) {
+            return output;
+        }
+    }
+    throw new Error('Hosted media upload response is missing output.');
+}
+function readSignedUpload(output) {
+    const signedUpload = output.signedUpload;
+    if (!signedUpload ||
+        typeof signedUpload !== 'object' ||
+        Array.isArray(signedUpload)) {
+        throw new Error('Hosted media upload response is missing signedUpload.');
+    }
+    const record = signedUpload;
+    if (typeof record.url !== 'string' || !record.url.trim()) {
+        throw new Error('Hosted media upload signedUpload.url must be a string.');
+    }
+    if (record.method !== 'PUT') {
+        throw new Error(`Unsupported hosted media signed upload method: ${String(record.method)}.`);
+    }
+    const requiredHeaders = {};
+    if (record.requiredHeaders &&
+        typeof record.requiredHeaders === 'object' &&
+        !Array.isArray(record.requiredHeaders)) {
+        for (const [key, value] of Object.entries(record.requiredHeaders)) {
+            if (typeof value !== 'string') {
+                throw new Error(`Hosted media upload signedUpload.requiredHeaders.${key} must be a string.`);
+            }
+            requiredHeaders[key] = value;
+        }
+    }
+    return { method: record.method, requiredHeaders, url: record.url.trim() };
+}
+function readStorageReferenceValue(output) {
+    const storageReference = output.storageReference;
+    if (!storageReference ||
+        typeof storageReference !== 'object' ||
+        Array.isArray(storageReference)) {
+        throw new Error('Hosted media upload response is missing storageReference.');
+    }
+    return storageReference;
+}
+async function putHostedMediaBytes(signedUpload, absolutePath) {
+    const response = await fetch(signedUpload.url, {
+        body: createReadStream(absolutePath),
+        duplex: 'half',
+        headers: signedUpload.requiredHeaders,
+        method: 'PUT',
+        signal: AbortSignal.timeout(120000),
+    });
+    if (!response.ok) {
+        throw new Error(`Hosted media signed upload failed with status ${response.status}.`);
+    }
+}
+function printMediaFileHelp() {
+    process.stdout.write(`PostPlus CLI - media-file commands
+
+Usage:
+  postplus media-file upload --input-file <path> [--mime <type>] [--skill <skill-id>] [--json] [--output <result.json>]
+`);
+}
+// Shared submit path for both surfaces: wrap the media input, derive billing
+// dimensions from endpointKey + input, and POST to the Web boundary.
+function submitMediaGenerationRequest(params) {
+    const body = {
+        capability: params.capability,
+        endpointKey: params.endpointKey,
+        input: params.input,
+        operation: 'request',
+        operationId: params.operationId,
+        quoteConfirmationToken: params.quoteConfirmationToken ?? undefined,
+        requestDimensions: buildMediaGenerationRequestDimensions(params.endpointKey, params.input),
+    };
+    return runHostedCommand({
+        request: () => postHostedJson({
+            body,
+            pathName: '/api/postplus-cli/hosted/capability',
+            skillName: params.skillName,
+        }),
+        errorInputLabel: params.errorInputLabel,
+        json: params.json,
+        outputPath: params.outputPath,
+    });
+}
+function buildMediaVerbInput(input) {
+    const record = {};
+    for (const field of input.fields) {
+        if (field.class === 'runner-managed' || !field.flag) {
+            continue;
+        }
+        const key = field.flag.replace(/^--/u, '');
+        if (field.repeatable) {
+            const list = input.flags.arrays.get(key) ?? [];
+            if (list.length === 0) {
+                if (field.required) {
+                    throw new Error(`Missing required option --${key} for media ${input.verb} ${input.endpointKey}.`);
+                }
+                continue;
+            }
+            record[field.name] = list;
+            continue;
+        }
+        if (field.type === 'boolean') {
+            if (input.flags.booleans.has(key)) {
+                record[field.name] = true;
+            }
+            else if (typeof field.default === 'boolean') {
+                record[field.name] = field.default;
+            }
+            continue;
+        }
+        const raw = input.flags.values.get(key);
+        if (raw === undefined) {
+            if (field.class === 'default' && field.default !== undefined) {
+                record[field.name] = field.default;
+            }
+            else if (field.required) {
+                throw new Error(`Missing required option --${key} for media ${input.verb} ${input.endpointKey}.`);
+            }
+            continue;
+        }
+        if (field.enumValues && !field.enumValues.includes(raw)) {
+            throw new Error(`--${key} must be one of ${field.enumValues.join(', ')}.`);
+        }
+        if (field.type === 'number') {
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`--${key} must be a positive number.`);
+            }
+            record[field.name] = parsed;
+        }
+        else {
+            record[field.name] = raw;
+        }
+    }
+    return record;
+}
+// Manifest-driven hosted-collection verb (request-json surface). The polling path
+// (`--run-handle`) resumes a pending run unchanged. The launch path resolves the
+// positional `<collectionKey>` against the research verb index for verb `collect`,
+// reads the collection input object directly from `--request <file>` (NOT a
+// schemaVersion envelope), and posts to /hosted/collection. The resolved entry
+// gives the default skillName (overridable by `--skill`); the actorId stays
+// internal and is never placed on the public body.
+async function runResearchCollect(args) {
+    const [first, ...rest] = args;
+    // Polling path: `research collect --run-handle <h>`. No positional collectionKey.
+    if (!first || first.startsWith('--')) {
+        const flags = parseFlags(args, new Set(['json']));
+        const runHandle = requireFlag(flags, 'run-handle');
+        const outputPath = flags.values.get('output') ?? null;
+        return runHostedCommand({
+            request: () => postHostedJson({
+                body: { runHandle },
+                pathName: '/api/postplus-cli/hosted/collection',
+                skillName: null,
+            }),
+            errorInputLabel: 'research-collect-run-handle',
+            json: flags.booleans.has('json'),
+            outputPath,
         });
-        await writeResult(payload, outputPath, flags.booleans.has('json'));
+    }
+    const verb = 'collect';
+    const collectionKey = first;
+    const targets = RESEARCH_VERB_TARGETS.get(verb);
+    const resolved = targets?.get(collectionKey);
+    if (!resolved) {
+        const valid = targets ? [...targets.keys()].join(', ') : '';
+        throw new Error(`Unknown research collect collection ${collectionKey}. Valid: ${valid}.`);
+    }
+    // `postplus research collect <collection-key> --help`: opaque-input contract.
+    if (rest.some(isHelp)) {
+        printOpaqueTargetHelp('research', verb, collectionKey, resolved);
         return 0;
     }
-    const skillName = requireFlag(flags, 'skill');
-    const collectionKey = requireFlag(flags, 'collection-key');
-    const inputPath = requireFlag(flags, 'input');
-    const envelope = readHostedEnvelope(await readJsonFile(inputPath), inputPath);
+    const flags = parseFlags(rest, new Set(['json']));
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'max-charge-usd',
+        'output',
+        'quote-confirmation-token',
+        'request',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for research ${verb}: --${key}.`);
+        }
+    }
+    const requestPath = requireFlag(flags, 'request');
+    const outputPath = flags.values.get('output') ?? null;
+    const raw = await readJsonFile(requestPath);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`research ${verb} ${collectionKey} --request must be a JSON object of collection input.`);
+    }
+    const input = raw;
+    const skillName = flags.values.get('skill') ?? resolved.skill;
     const operationId = flags.values.get('hosted-operation-id') ??
-        normalizeString(envelope.hostedOperationId) ??
-        normalizeString(envelope.operationId) ??
-        `postplus-cli:research:${collectionKey}:${randomUUID()}`;
-    const quoteConfirmationToken = flags.values.get('quote-confirmation-token') ??
-        normalizeString(envelope.quoteConfirmationToken);
-    const payload = await postHostedJson({
-        body: {
-            collectionKey,
-            input: envelope.input,
-            operationId,
-            quoteConfirmationToken: quoteConfirmationToken ?? undefined,
+        `postplus-cli:research:collect:${collectionKey}:${randomUUID()}`;
+    const quoteConfirmationToken = flags.values.get('quote-confirmation-token');
+    // Optional per-request cost ceiling (USD) overriding the hosted default.
+    const maxChargeFlag = flags.values.get('max-charge-usd');
+    let maxTotalChargeUsd;
+    if (maxChargeFlag !== undefined) {
+        const parsed = Number(maxChargeFlag);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new Error('--max-charge-usd must be a positive number of USD.');
+        }
+        maxTotalChargeUsd = parsed;
+    }
+    return runHostedCommand({
+        request: () => postHostedJson({
+            body: {
+                collectionKey,
+                input,
+                operationId,
+                quoteConfirmationToken: quoteConfirmationToken ?? undefined,
+                skillName,
+                maxTotalChargeUsd,
+            },
+            pathName: '/api/postplus-cli/hosted/collection',
             skillName,
-        },
-        pathName: '/api/postplus-cli/hosted/collection',
-        skillName,
-    }).catch((error) => buildHostedCommandError(error, {
-        inputPath,
+        }),
+        errorInputLabel: requestPath,
+        json: flags.booleans.has('json'),
         outputPath,
-    }));
-    await writeResult(payload, outputPath, flags.booleans.has('json'));
-    return 0;
+    });
+}
+// Manifest-driven public-content-collection verb (request-json surface). Resolves
+// the positional `<sourceKey>` against the research verb index for verb `scrape`,
+// reads the scrape input directly from `--request <file>` as a JSON ARRAY of input
+// records (one per public URL/query), and posts to /hosted/capability with
+// capability `public-content-collection` / operation `scrape`. The resolved entry
+// gives the default skillName (overridable by `--skill`); the datasetId stays
+// internal and is never placed on the public body.
+async function runResearchScrape(args) {
+    const [first, ...rest] = args;
+    const verb = 'scrape';
+    const targets = RESEARCH_VERB_TARGETS.get(verb);
+    if (!first || first.startsWith('--')) {
+        const valid = targets ? [...targets.keys()].join(', ') : '';
+        throw new Error(`postplus research ${verb} requires a source key. Valid: ${valid}.`);
+    }
+    const sourceKey = first;
+    const resolved = targets?.get(sourceKey);
+    if (!resolved) {
+        const valid = targets ? [...targets.keys()].join(', ') : '';
+        throw new Error(`Unknown research scrape source ${sourceKey}. Valid: ${valid}.`);
+    }
+    // `postplus research scrape <source-key> --help`: opaque-array-input contract.
+    if (rest.some(isHelp)) {
+        printOpaqueTargetHelp('research', verb, sourceKey, resolved);
+        return 0;
+    }
+    const flags = parseFlags(rest, new Set(['json']));
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'max-charge-usd',
+        'output',
+        'quote-confirmation-token',
+        'request',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for research ${verb}: --${key}.`);
+        }
+    }
+    const requestPath = requireFlag(flags, 'request');
+    const outputPath = flags.values.get('output') ?? null;
+    const raw = await readJsonFile(requestPath);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error(`research ${verb} ${sourceKey} --request must be a non-empty JSON array of scrape input records.`);
+    }
+    const input = raw;
+    const skillName = flags.values.get('skill') ?? resolved.skill;
+    const operationId = flags.values.get('hosted-operation-id') ??
+        `postplus-cli:research:scrape:${sourceKey}:${randomUUID()}`;
+    const quoteConfirmationToken = flags.values.get('quote-confirmation-token');
+    // Optional per-request cost ceiling (USD) overriding the hosted default.
+    const maxChargeFlag = flags.values.get('max-charge-usd');
+    let maxTotalChargeUsd;
+    if (maxChargeFlag !== undefined) {
+        const parsed = Number(maxChargeFlag);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new Error('--max-charge-usd must be a positive number of USD.');
+        }
+        maxTotalChargeUsd = parsed;
+    }
+    // The Web /hosted/capability scrape contract is a strict object: skillName is
+    // carried as the compatibility header (postHostedJson), never on the public body.
+    return runHostedCommand({
+        request: () => postHostedJson({
+            body: {
+                capability: 'public-content-collection',
+                operation: 'scrape',
+                sourceKey,
+                input,
+                operationId,
+                quoteConfirmationToken: quoteConfirmationToken ?? undefined,
+                maxTotalChargeUsd,
+            },
+            pathName: '/api/postplus-cli/hosted/capability',
+            skillName,
+        }),
+        errorInputLabel: requestPath,
+        json: flags.booleans.has('json'),
+        outputPath,
+    });
+}
+// Manifest-driven publish operation (request-json surface). The OPERATION is the
+// subcommand and the target: `postplus publish <operation> --request <file>`. The
+// publishing input object is read directly from `--request <file>` and posted to
+// /hosted/capability with capability `social-publishing` / the resolved operation.
+// Side-effecting operations surface the Web quote-confirmation challenge; the
+// shared runHostedCommand handles the challenge -> retry-with-token path. There is
+// no requestDimensions/approval/execute — those were private-runtime concepts.
+async function runPublishOperation(operation, args) {
+    const resolved = PUBLISH_VERB_OPERATIONS.get(operation);
+    if (!resolved) {
+        throw new Error(`Unknown publish operation ${operation}. Valid: ${[...PUBLISH_VERB_OPERATIONS.keys()].join(', ')}.`);
+    }
+    // `postplus publish <operation> --help`: opaque-input contract.
+    if (args.some(isHelp)) {
+        printOpaqueTargetHelp('publish', operation, operation, resolved);
+        return 0;
+    }
+    const flags = parseFlags(args, new Set(['json']));
+    const allowedKeys = new Set([
+        'hosted-operation-id',
+        'json',
+        'output',
+        'quote-confirmation-token',
+        'request',
+        'skill',
+    ]);
+    for (const key of [...flags.values.keys(), ...flags.booleans]) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`Unknown option for publish ${operation}: --${key}.`);
+        }
+    }
+    const requestPath = requireFlag(flags, 'request');
+    const outputPath = flags.values.get('output') ?? null;
+    const raw = await readJsonFile(requestPath);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`publish ${operation} --request must be a JSON object of publishing input.`);
+    }
+    const input = raw;
+    const skillName = flags.values.get('skill') ?? resolved.skill;
+    const operationId = flags.values.get('hosted-operation-id') ??
+        `postplus-cli:publish:social-publishing:request:${randomUUID()}`;
+    const quoteConfirmationToken = flags.values.get('quote-confirmation-token');
+    return runHostedCommand({
+        request: () => postHostedJson({
+            body: {
+                capability: 'social-publishing',
+                operation,
+                input,
+                operationId,
+                quoteConfirmationToken: quoteConfirmationToken ?? undefined,
+            },
+            pathName: '/api/postplus-cli/hosted/capability',
+            skillName,
+        }),
+        errorInputLabel: requestPath,
+        json: flags.booleans.has('json'),
+        outputPath,
+    });
 }
 async function runHostedSchema(domain, args) {
     const flags = parseFlags(args, new Set(['json']));
@@ -105,65 +762,6 @@ async function runHostedSchema(domain, args) {
     }));
     return 0;
 }
-async function runHostedCapability(domain, args) {
-    const flags = parseFlags(args, new Set(['json']));
-    const requestPath = requireFlag(flags, 'request');
-    const outputPath = flags.values.get('output') ?? null;
-    const request = await readJsonFile(requestPath);
-    if (!request || typeof request !== 'object' || Array.isArray(request)) {
-        throw new Error(`Hosted ${domain} capability request must be a JSON object.`);
-    }
-    const record = request;
-    const capability = requireDomainCapability(record, domain);
-    const operation = requireRecordString(record, 'operation');
-    const operationId = flags.values.get('hosted-operation-id') ??
-        normalizeString(record.operationId) ??
-        `postplus-cli:${domain}:${capability}:${operation}:${randomUUID()}`;
-    const quoteConfirmationToken = flags.values.get('quote-confirmation-token') ??
-        normalizeString(record.quoteConfirmationToken);
-    const publicRecord = { ...record };
-    delete publicRecord.skillName;
-    const derivedFields = buildDerivedHostedCapabilityFields({
-        capability,
-        domain,
-        operation,
-        record,
-    });
-    const body = {
-        ...publicRecord,
-        ...derivedFields,
-        capability,
-        operation,
-        operationId,
-        quoteConfirmationToken: quoteConfirmationToken ?? undefined,
-    };
-    const skillName = flags.values.get('skill') ?? normalizeString(record.skillName);
-    const payload = await postHostedJson({
-        body,
-        pathName: '/api/postplus-cli/hosted/capability',
-        skillName,
-    }).catch((error) => buildHostedCommandError(error, {
-        inputPath: requestPath,
-        outputPath,
-    }));
-    await writeResult(payload, outputPath, flags.booleans.has('json'));
-    return 0;
-}
-function buildDerivedHostedCapabilityFields(input) {
-    if (input.domain !== 'media' ||
-        input.capability !== 'media-generation' ||
-        input.operation !== 'request') {
-        return {};
-    }
-    if (Object.hasOwn(input.record, 'requestDimensions')) {
-        throw new Error('Hosted media-generation request must not include requestDimensions. The CLI derives billing dimensions from endpointKey and input.');
-    }
-    const endpointKey = requireRecordString(input.record, 'endpointKey');
-    const mediaInput = requireRecordObject(input.record, 'input');
-    return {
-        requestDimensions: buildMediaGenerationRequestDimensions(endpointKey, mediaInput),
-    };
-}
 async function postHostedJson(input) {
     let auth = await resolveFreshRemoteAuth();
     let response = await postJson({
@@ -185,36 +783,61 @@ async function postHostedJson(input) {
     }
     const payload = await readJsonResponse(response);
     if (!response.ok) {
+        const productError = readHostedProductError(payload);
         const challenge = readLargeCreditQuoteConfirmationChallenge(payload);
         if (challenge) {
-            throw new HostedQuoteConfirmationRequiredError(readProductError(payload), challenge);
+            throw new HostedQuoteConfirmationRequiredError(productError.message, challenge);
         }
         const compatibilityError = formatPostPlusCompatibilityError(payload);
         if (compatibilityError) {
             throw new Error(compatibilityError);
         }
-        throw new Error(readProductError(payload));
+        throw new HostedProductRequestError(productError);
     }
     return payload;
 }
-async function buildHostedCommandError(error, input) {
-    if (!(error instanceof HostedQuoteConfirmationRequiredError)) {
+// Single exit path for every hosted command: success writes the result and
+// returns 0; a quote challenge writes the challenge file and rethrows actionable
+// guidance; a structured product error writes the full error envelope to the
+// result JSON and surfaces code/layer/operationId on the terminal, exiting 1.
+async function runHostedCommand(input) {
+    let payload;
+    try {
+        payload = await input.request();
+    }
+    catch (error) {
+        if (error instanceof HostedQuoteConfirmationRequiredError) {
+            const challengePath = await writeQuoteConfirmationChallenge(error, {
+                errorInputLabel: input.errorInputLabel,
+                outputPath: input.outputPath,
+            });
+            throw new Error([
+                error.message,
+                `Quote confirmation challenge: ${challengePath}`,
+                `Confirm: postplus quote confirm --json --challenge-file "${challengePath}"`,
+                'Then rerun the hosted command with --quote-confirmation-token <token>.',
+            ].join('\n'));
+        }
+        if (error instanceof HostedProductRequestError) {
+            await writeResult({ error: error.productError }, input.outputPath, input.json);
+            process.stderr.write(`${error.message}\n`);
+            return 1;
+        }
         throw error;
     }
+    await writeResult(payload, input.outputPath, input.json);
+    return 0;
+}
+async function writeQuoteConfirmationChallenge(error, input) {
     const challengePath = path.resolve(input.outputPath
         ? `${input.outputPath}.quote-confirmation.json`
-        : `${input.inputPath}.quote-confirmation.json`);
+        : `${input.errorInputLabel}.quote-confirmation.json`);
     await mkdir(path.dirname(challengePath), { recursive: true });
     await writeFile(challengePath, `${JSON.stringify(error.challenge, null, 2)}\n`, {
         encoding: 'utf8',
         mode: 0o600,
     });
-    throw new Error([
-        error.message,
-        `Quote confirmation challenge: ${challengePath}`,
-        `Confirm: postplus quote confirm --json --challenge-file "${challengePath}"`,
-        'Then rerun the hosted command with --quote-confirmation-token <token>.',
-    ].join('\n'));
+    return challengePath;
 }
 async function postJson(input) {
     const headers = await buildPostPlusClientCompatibilityHeaders({
@@ -244,17 +867,31 @@ async function readJsonResponse(response) {
         throw new Error('PostPlus Cloud returned invalid JSON.');
     }
 }
-function readProductError(payload) {
-    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
-        const record = payload;
-        if (typeof record.error === 'string' && record.error.trim()) {
-            return record.error.trim();
-        }
-        if (typeof record.message === 'string' && record.message.trim()) {
-            return record.message.trim();
-        }
-    }
-    return 'PostPlus hosted capability request failed.';
+function readHostedProductError(payload) {
+    const record = payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? payload
+        : {};
+    return {
+        message: normalizeString(record.error) ??
+            normalizeString(record.message) ??
+            'PostPlus hosted capability request failed.',
+        code: normalizeString(record.code) ?? normalizeString(record.productErrorCode),
+        layer: normalizeString(record.layer),
+        operationId: normalizeString(record.operationId),
+        userMessageRule: normalizeString(record.userMessageRule),
+    };
+}
+// Terminal message that keeps the stable code, owning layer, and operation id
+// visible next to the human-readable message so a failed run is locatable.
+function formatHostedProductErrorMessage(productError) {
+    const locator = [
+        productError.code ? `code=${productError.code}` : null,
+        productError.layer ? `layer=${productError.layer}` : null,
+        productError.operationId ? `operationId=${productError.operationId}` : null,
+    ].filter((part) => part !== null);
+    return locator.length > 0
+        ? `${productError.message} (${locator.join(' ')})`
+        : productError.message;
 }
 async function readJsonFile(filePath) {
     try {
@@ -266,16 +903,6 @@ async function readJsonFile(filePath) {
             : `Failed to read JSON file ${filePath}.`);
     }
 }
-function readHostedEnvelope(value, filePath) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error(`${filePath} must be a schemaVersion 1 hosted envelope.`);
-    }
-    const envelope = value;
-    if (envelope.schemaVersion !== 1 || !Object.hasOwn(envelope, 'input')) {
-        throw new Error(`${filePath} must be a schemaVersion 1 hosted envelope.`);
-    }
-    return envelope;
-}
 async function writeResult(payload, outputPath, forceStdout) {
     const text = `${JSON.stringify(payload, null, 2)}\n`;
     if (!outputPath || forceStdout) {
@@ -286,9 +913,10 @@ async function writeResult(payload, outputPath, forceStdout) {
         await writeFile(outputPath, text);
     }
 }
-function parseFlags(args, booleanFlags) {
+function parseFlags(args, booleanFlags, arrayFlags = new Set()) {
     const values = new Map();
     const booleans = new Set();
+    const arrays = new Map();
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg.startsWith('--')) {
@@ -303,10 +931,17 @@ function parseFlags(args, booleanFlags) {
         if (!value || value.startsWith('--')) {
             throw new Error(`Missing value for --${key}.`);
         }
-        values.set(key, value);
+        if (arrayFlags.has(key)) {
+            const list = arrays.get(key) ?? [];
+            list.push(value);
+            arrays.set(key, list);
+        }
+        else {
+            values.set(key, value);
+        }
         index += 1;
     }
-    return { booleans, values };
+    return { arrays, booleans, values };
 }
 function requireFlag(flags, key) {
     const value = flags.values.get(key);
@@ -315,28 +950,6 @@ function requireFlag(flags, key) {
     }
     return value;
 }
-function requireDomainCapability(record, domain) {
-    const capability = requireRecordString(record, 'capability');
-    const allowed = HOSTED_DOMAIN_CAPABILITIES[domain];
-    if (!allowed.has(capability)) {
-        throw new Error(`Hosted ${domain} capability request uses unsupported capability ${capability}.`);
-    }
-    return capability;
-}
-function requireRecordString(record, key) {
-    const value = normalizeString(record[key]);
-    if (!value) {
-        throw new Error(`Hosted capability request must include string ${key}.`);
-    }
-    return value;
-}
-function requireRecordObject(record, key) {
-    const value = record[key];
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error(`Hosted capability request must include object ${key}.`);
-    }
-    return value;
-}
 function normalizeString(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
@@ -348,17 +961,136 @@ function printResearchHelp() {
 
 Usage:
   postplus research schema [--collection-key <key>] [--json]
-  postplus research collect --skill <skill-id> --collection-key <key> --input <hosted-envelope.json> [--output <result.json>]
+  postplus research collect <collection-key> --request <input.json> [--skill <skill-id>] [--max-charge-usd <usd>] [--output <result.json>]
   postplus research collect --run-handle <runHandle> [--output <result.json>]
-  postplus research capability --request <hosted-capability-request.json> [--output <result.json>]
+  postplus research scrape <source-key> --request <input-array.json> [--skill <skill-id>] [--max-charge-usd <usd>] [--output <result.json>]
 `);
 }
-function printCapabilityHelp(domain) {
+function printDomainVerbHelp(domain) {
+    const verbUsage = domain === 'media'
+        ? [...MEDIA_VERB_ENDPOINTS.keys()]
+            .map((verb) => `  postplus media ${verb} <endpoint-key> --<intent/default flags> [--json] [--output <result.json>]\n`)
+            .join('')
+        : '  postplus publish <operation> --request <input.json> [--json] [--output <result.json>]\n';
     process.stdout.write(`PostPlus CLI - ${domain} commands
 
 Usage:
-  postplus ${domain} schema${domain === 'media' ? ' [--endpoint <endpoint-key>]' : ''} [--json]
-  postplus ${domain} capability --request <hosted-capability-request.json> [--output <result.json>]
+${verbUsage}  postplus ${domain} schema${domain === 'media' ? ' [--endpoint <endpoint-key>]' : ''} [--json]
+`);
+}
+// Per-endpoint `--help` for a media-generation endpoint (and the video-analysis
+// model). Renders the endpoint's field-level contract grouped into the envelope's
+// three classes — intent (you write it), default (manifest-defaulted; write only
+// to deviate), runner-managed (minted by the CLI; never an input) — using the
+// manifest as the SSOT for flags, enum sets, ranges, and defaults.
+function printMediaEndpointHelp(domain, verb, targetKey, resolved) {
+    // video-analysis: opaque Gemini payload, no field classification to render.
+    if (resolved.capability === 'video-analysis') {
+        process.stdout.write(`PostPlus CLI - ${domain} ${verb} ${targetKey}
+
+  Surface: request-json (opaque Gemini request payload)
+  Usage:
+    postplus ${domain} ${verb} ${targetKey} --request <input.json> [--json] [--output <result.json>]
+
+  --request <file>  A JSON object authored verbatim as the Gemini request
+                    (contents + optional generationConfig) under "payload".
+  Runner-managed (minted by the CLI; never in the body): operationId, quoteConfirmationToken
+`);
+        return;
+    }
+    if (!resolved.endpoint) {
+        throw new Error(`media ${verb} ${targetKey} resolved to a non-endpoint target.`);
+    }
+    const fields = resolved.endpoint.fields;
+    const isFlagsSurface = resolved.surface === 'flags';
+    const intent = fields.filter((field) => field.class === 'intent');
+    const defaulted = fields.filter((field) => field.class === 'default');
+    const managed = fields.filter((field) => field.class === 'runner-managed');
+    const lines = [
+        `PostPlus CLI - ${domain} ${verb} ${targetKey}`,
+        '',
+        `  Surface: ${resolved.surface}`,
+        '  Usage:',
+        isFlagsSurface
+            ? `    postplus ${domain} ${verb} ${targetKey} ${formatFlagsUsage(fields)} [--json] [--output <result.json>]`
+            : `    postplus ${domain} ${verb} ${targetKey} --request <input.json> [--json] [--output <result.json>]`,
+        '',
+    ];
+    appendFieldGroup(lines, 'Intent (you must / may write):', intent, isFlagsSurface);
+    appendFieldGroup(lines, 'Default (manifest-defaulted; write only to deviate):', defaulted, isFlagsSurface);
+    if (managed.length > 0) {
+        lines.push('  Runner-managed (minted by the CLI; never an input):');
+        for (const field of managed) {
+            const derived = field.derivedFrom
+                ? ` (derived from ${field.derivedFrom})`
+                : '';
+            lines.push(`    ${field.name}${derived}`);
+        }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+}
+function formatFlagsUsage(fields) {
+    const parts = [];
+    for (const field of fields) {
+        if (field.class === 'runner-managed' || !field.flag) {
+            continue;
+        }
+        const token = `${field.flag} <${field.name}>`;
+        parts.push(field.required ? token : `[${token}]`);
+    }
+    return parts.join(' ');
+}
+function appendFieldGroup(lines, title, fields, isFlagsSurface) {
+    if (fields.length === 0) {
+        return;
+    }
+    lines.push(`  ${title}`);
+    for (const field of fields) {
+        const label = isFlagsSurface && field.flag ? field.flag : `(json) ${field.name}`;
+        lines.push(`    ${label}${formatFieldDetail(field)}`);
+    }
+    lines.push('');
+}
+// Field detail: type, required/optional, enum set or numeric range, default, and
+// repeatable arity — all read from the manifest contract.
+function formatFieldDetail(field) {
+    const detail = [
+        field.repeatable ? `${field.type}[]` : field.type,
+        field.required ? 'required' : 'optional',
+    ];
+    if (field.enumValues && field.enumValues.length > 0) {
+        detail.push(`one of {${field.enumValues.join(', ')}}`);
+    }
+    else if (field.min !== undefined || field.max !== undefined) {
+        detail.push(`range ${field.min ?? '-'}..${field.max ?? '-'}`);
+    }
+    if (field.default !== undefined) {
+        detail.push(`default ${String(field.default)}`);
+    }
+    return `  [${detail.join('; ')}]`;
+}
+// Per-target `--help` for capabilities whose request body is an opaque JSON object
+// (research collect/scrape, publish): there is no field classification to render,
+// so the help states the input shape and the runner-managed protocol fields.
+function printOpaqueTargetHelp(domain, verb, targetKey, resolved) {
+    const inputShape = resolved.capability === 'public-content-collection'
+        ? 'a non-empty JSON array of provider-shaped scrape records'
+        : 'a provider-shaped JSON object of input';
+    // publish's operation is both the verb and the target, so the header/usage show
+    // it once; research shows `<verb> <target>`.
+    const header = domain === 'publish' ? `publish ${targetKey}` : `research ${verb} ${targetKey}`;
+    const usage = domain === 'publish'
+        ? `    postplus publish ${targetKey} --request <input.json> [--json] [--output <result.json>]`
+        : `    postplus research ${verb} ${targetKey} --request <input.json> [--skill <skill-id>] [--max-charge-usd <usd>] [--json] [--output <result.json>]`;
+    process.stdout.write(`PostPlus CLI - ${header}
+
+  Surface: request-json (opaque input authored by the agent)
+  Capability: ${resolved.capability}
+  Usage:
+${usage}
+
+  --request <file>  ${inputShape}.
+  Runner-managed (minted by the CLI; never in the body): operationId, quoteConfirmationToken
 `);
 }
 function writeJson(value) {