@postplus/cli 0.1.45 → 0.1.47

package/build/hosted-domain-commands.js

@@ -3,11 +3,11 @@ 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 { sendAuthedCloudRequest } from './authed-cloud-request.js';
+import { sendAuthedCloudRequest, } from './authed-cloud-request.js';
 import { formatPostPlusCompatibilityError } from './client-compatibility.js';
 import { assertModelledFieldValuesInRange } from './hosted-field-validation.js';
 import { buildVerbTargetIndex, } from './hosted-manifest-index.js';
-import { buildHostedRequestSchemaReport, buildMediaGenerationRequestDimensions, } from './hosted-request-schemas.js';
+import { buildHostedRequestSchemaReport } from './hosted-request-schemas.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,
@@ -27,6 +27,20 @@ function buildPublishVerbIndex() {
     }
     return index;
 }
+// Reads the request-json body for a surface: from the injected object (lib path)
+// or by reading `--request <file>` (bin path). This is the SINGLE place the two
+// paths diverge on input source; the resolved body then flows through the SAME
+// validation + envelope build, so the URL/body/headers stay byte-identical.
+async function resolveRequestBody(context, flags) {
+    if (context) {
+        if (context.requestJson === undefined) {
+            throw new Error('This hosted command requires a requestJson body.');
+        }
+        return { body: context.requestJson, errorInputLabel: 'requestJson' };
+    }
+    const requestPath = requireFlag(flags, 'request');
+    return { body: await readJsonFile(requestPath), errorInputLabel: requestPath };
+}
 class HostedQuoteConfirmationRequiredError extends Error {
     challenge;
     constructor(message, challenge) {
@@ -43,41 +57,45 @@ class HostedProductRequestError extends Error {
         this.name = 'HostedProductRequestError';
     }
 }
-export async function runHostedDomainCommand(domain, args) {
+export async function runHostedDomainCommand(domain, args, 
+// Present only on the in-process hosted-lib path; the bin path never passes it.
+// See HostedRequestContext: it carries the injected auth/releaseId/requestJson
+// and switches every leaf onto the no-disk, no-file, return-payload behavior.
+context) {
     const [subcommand, ...rest] = args;
     if (domain === 'research') {
         if (subcommand === 'schema') {
-            return runHostedSchema(domain, rest);
+            return runHostedSchema(domain, rest, context);
         }
         if (subcommand === 'collect') {
-            return runResearchCollect(rest);
+            return runResearchCollect(rest, context);
         }
         if (subcommand === 'scrape') {
-            return runResearchScrape(rest);
+            return runResearchScrape(rest, context);
         }
         printResearchHelp();
         return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
     }
     if (subcommand === 'schema') {
-        return runHostedSchema(domain, rest);
+        return runHostedSchema(domain, rest, context);
     }
     // Poll a pending async media-generation run by handle. This is a hand-coded
     // branch (not a manifest verb) because a status poll has no endpointKey/field
     // contract to project — exactly like the `research collect --run-handle`
     // polling branch. It must be checked before the manifest verb dispatch.
     if (domain === 'media' && subcommand === 'poll') {
-        return runMediaPoll(rest);
+        return runMediaPoll(rest, context);
     }
     if (domain === 'media' &&
         subcommand &&
         MEDIA_VERB_ENDPOINTS.has(subcommand)) {
-        return runMediaVerb(subcommand, rest);
+        return runMediaVerb(subcommand, rest, context);
     }
     // publish: the OPERATION is the subcommand (no separate target positional).
     if (domain === 'publish' &&
         subcommand &&
         PUBLISH_VERB_OPERATIONS.has(subcommand)) {
-        return runPublishOperation(subcommand, rest);
+        return runPublishOperation(subcommand, rest, context);
     }
     printDomainVerbHelp(domain);
     return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
@@ -87,7 +105,7 @@ export async function runHostedDomainCommand(domain, args) {
 // 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) {
+async function runMediaVerb(verb, args, context) {
     const targets = MEDIA_VERB_ENDPOINTS.get(verb);
     if (!targets) {
         throw new Error(`Unknown media verb ${verb}.`);
@@ -112,6 +130,7 @@ async function runMediaVerb(verb, args) {
             modelKey: targetKey,
             resolved,
             verb,
+            context,
         });
     }
     if (resolved.surface === 'request-json') {
@@ -120,6 +139,7 @@ async function runMediaVerb(verb, args) {
             endpointKey: targetKey,
             resolved,
             verb,
+            context,
         });
     }
     return runMediaVerbFlags({
@@ -127,12 +147,13 @@ async function runMediaVerb(verb, args) {
         endpointKey: targetKey,
         resolved,
         verb,
+        context,
     });
 }
 // 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 { endpointKey, resolved, verb, context } = args;
     const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
     const fields = endpoint.fields;
     const flagToField = new Map();
@@ -193,6 +214,7 @@ async function runMediaVerbFlags(args) {
         outputPath,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
         skillName: flags.values.get('skill') ?? resolved.skill,
+        context,
     });
 }
 // Request-json surface (e.g. seedance-submitter): the nested envelope is supplied
@@ -200,7 +222,7 @@ async function runMediaVerbFlags(args) {
 // 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 { endpointKey, resolved, verb, context } = args;
     const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
     const flags = parseFlags(args.args, new Set(['json']));
     const allowedKeys = new Set([
@@ -216,9 +238,8 @@ async function runMediaVerbRequestJson(args) {
             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);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`media ${verb} ${endpointKey} --request must be a JSON object of media-generation input.`);
     }
@@ -239,7 +260,7 @@ async function runMediaVerbRequestJson(args) {
     return submitMediaGenerationRequest({
         capability: resolved.capability,
         endpointKey,
-        errorInputLabel: requestPath,
+        errorInputLabel,
         input,
         json: flags.booleans.has('json'),
         operationId: flags.values.get('hosted-operation-id') ??
@@ -247,6 +268,7 @@ async function runMediaVerbRequestJson(args) {
         outputPath,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
         skillName: flags.values.get('skill') ?? resolved.skill,
+        context,
     });
 }
 function requireResolvedEndpoint(resolved, verb, endpointKey) {
@@ -264,7 +286,7 @@ function requireResolvedEndpoint(resolved, verb, endpointKey) {
 // `estimatedUsage.videoSeconds` so the Web boundary can route eligible short
 // videos through its preflight/routing path (omit it to use the default route).
 async function runVideoAnalysisVerb(args) {
-    const { modelKey, resolved, verb } = args;
+    const { modelKey, resolved, verb, context } = args;
     const flags = parseFlags(args.args, new Set(['json']));
     const allowedKeys = new Set([
         'hosted-operation-id',
@@ -280,9 +302,8 @@ async function runVideoAnalysisVerb(args) {
             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);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`media ${verb} ${modelKey} --request must be a JSON object of Gemini request payload.`);
     }
@@ -311,16 +332,17 @@ async function runVideoAnalysisVerb(args) {
             `postplus-cli:media:video-analysis:analyze:${randomUUID()}`,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body,
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: flags.values.get('skill') ?? resolved.skill,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // `media-file upload`: the generic local-file -> hosted media verb. Released
 // skills ship no scripts, so a skill that must place a local file behind hosted
@@ -346,15 +368,15 @@ function inferUploadMimeType(filePath) {
     return (MEDIA_FILE_MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] ??
         'application/octet-stream');
 }
-export async function runMediaFileCommand(args) {
+export async function runMediaFileCommand(args, context) {
     const [subcommand, ...rest] = args;
     if (subcommand === 'upload') {
-        return runMediaFileUpload(rest);
+        return runMediaFileUpload(rest, context);
     }
     printMediaFileHelp();
     return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
 }
-async function runMediaFileUpload(args) {
+async function runMediaFileUpload(args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const allowedKeys = new Set([
         'hosted-operation-id',
@@ -391,12 +413,13 @@ async function runMediaFileUpload(args) {
             `postplus-cli:media-file:create-upload-url:${randomUUID()}`,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: async () => {
             const payload = await postHostedJson({
                 body,
                 pathName: '/api/postplus-cli/hosted/capability',
                 skillName: flags.values.get('skill') ?? null,
+                context,
             });
             const output = readHostedUploadOutput(payload);
             const signedUpload = readSignedUpload(output);
@@ -418,12 +441,13 @@ async function runMediaFileUpload(args) {
                 },
                 pathName: '/api/postplus-cli/hosted/capability',
                 skillName: flags.values.get('skill') ?? null,
+                context,
             });
         },
         errorInputLabel: inputFile,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 function readHostedUploadOutput(payload) {
     if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
@@ -492,6 +516,9 @@ Usage:
 // 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) {
+    // Billing dimensions are derived solely at the Web boundary from
+    // (endpointKey, input); the CLI sends only the payload. The Web request schema
+    // rejects any caller-supplied `requestDimensions` (single source of truth).
     const body = {
         capability: params.capability,
         endpointKey: params.endpointKey,
@@ -499,18 +526,18 @@ function submitMediaGenerationRequest(params) {
         operation: 'request',
         operationId: params.operationId,
         quoteConfirmationToken: params.quoteConfirmationToken ?? undefined,
-        requestDimensions: buildMediaGenerationRequestDimensions(params.endpointKey, params.input),
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body,
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: params.skillName,
+            context: params.context,
         }),
         errorInputLabel: params.errorInputLabel,
         json: params.json,
         outputPath: params.outputPath,
-    });
+    }, params.context);
 }
 // Poll a pending media-generation run: `postplus media poll --handle <run-id>`.
 // A media `create`/`transcribe`/`analyze` submit returns an async run handle
@@ -522,11 +549,11 @@ function submitMediaGenerationRequest(params) {
 // The body carries only the status quadruple; submit-only fields (input,
 // requestDimensions, quoteConfirmationToken) are never sent. Mirrors the
 // `research collect --run-handle` polling branch.
-async function runMediaPoll(args) {
+async function runMediaPoll(args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const handle = requireFlag(flags, 'handle');
     const outputPath = flags.values.get('output') ?? null;
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'media-generation',
@@ -536,11 +563,12 @@ async function runMediaPoll(args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: null,
+            context,
         }),
         errorInputLabel: 'media-poll-handle',
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 function buildMediaVerbInput(input) {
     const record = {};
@@ -604,23 +632,24 @@ function buildMediaVerbInput(input) {
 // 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) {
+async function runResearchCollect(args, context) {
     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({
+        return dispatchHostedCommand({
             request: () => postHostedJson({
                 body: { runHandle, runHandleType: 'hosted-collection' },
                 pathName: '/api/postplus-cli/hosted/collection',
                 skillName: null,
+                context,
             }),
             errorInputLabel: 'research-collect-run-handle',
             json: flags.booleans.has('json'),
             outputPath,
-        });
+        }, context);
     }
     const verb = 'collect';
     const collectionKey = first;
@@ -650,9 +679,8 @@ async function runResearchCollect(args) {
             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);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`research ${verb} ${collectionKey} --request must be a JSON object of collection input.`);
     }
@@ -671,7 +699,7 @@ async function runResearchCollect(args) {
         }
         maxTotalChargeUsd = parsed;
     }
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 collectionKey,
@@ -683,11 +711,12 @@ async function runResearchCollect(args) {
             },
             pathName: '/api/postplus-cli/hosted/collection',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // Manifest-driven public-content-collection verb (request-json surface). Resolves
 // the positional `<sourceKey>` against the research verb index for verb `scrape`,
@@ -696,7 +725,7 @@ async function runResearchCollect(args) {
 // 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) {
+async function runResearchScrape(args, context) {
     const [first, ...rest] = args;
     const verb = 'scrape';
     const targets = RESEARCH_VERB_TARGETS.get(verb);
@@ -704,16 +733,17 @@ async function runResearchScrape(args) {
         const flags = parseFlags(args, new Set(['json']));
         const runHandle = requireFlag(flags, 'run-handle');
         const outputPath = flags.values.get('output') ?? null;
-        return runHostedCommand({
+        return dispatchHostedCommand({
             request: () => postHostedJson({
                 body: { runHandle, runHandleType: 'public-content-collection' },
                 pathName: '/api/postplus-cli/hosted/collection',
                 skillName: null,
+                context,
             }),
             errorInputLabel: 'research-scrape-run-handle',
             json: flags.booleans.has('json'),
             outputPath,
-        });
+        }, context);
     }
     const sourceKey = first;
     const resolved = targets?.get(sourceKey);
@@ -741,9 +771,8 @@ async function runResearchScrape(args) {
             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);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     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.`);
     }
@@ -764,7 +793,7 @@ async function runResearchScrape(args) {
     }
     // 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({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'public-content-collection',
@@ -777,11 +806,12 @@ async function runResearchScrape(args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // Manifest-driven publish operation (request-json surface). The OPERATION is the
 // subcommand and the target: `postplus publish <operation> --request <file>`. The
@@ -790,7 +820,7 @@ async function runResearchScrape(args) {
 // 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) {
+async function runPublishOperation(operation, args, context) {
     const resolved = PUBLISH_VERB_OPERATIONS.get(operation);
     if (!resolved) {
         throw new Error(`Unknown publish operation ${operation}. Valid: ${[...PUBLISH_VERB_OPERATIONS.keys()].join(', ')}.`);
@@ -814,9 +844,8 @@ async function runPublishOperation(operation, args) {
             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);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`publish ${operation} --request must be a JSON object of publishing input.`);
     }
@@ -825,7 +854,7 @@ async function runPublishOperation(operation, args) {
     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({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'social-publishing',
@@ -836,13 +865,14 @@ async function runPublishOperation(operation, args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
-async function runHostedSchema(domain, args) {
+async function runHostedSchema(domain, args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const allowedFlags = domain === 'media'
         ? new Set(['endpoint'])
@@ -854,24 +884,40 @@ async function runHostedSchema(domain, args) {
             throw new Error(`Unknown option for ${domain} schema: --${key}.`);
         }
     }
-    writeJson(buildHostedRequestSchemaReport({
+    const report = buildHostedRequestSchemaReport({
         collectionKey: flags.values.get('collection-key') ?? null,
         domain,
         endpointKey: flags.values.get('endpoint') ?? null,
-    }));
+    });
+    // In-process / context path: RETURN the structured catalog so the model
+    // receives it as the call result. The bin path (no context) keeps writeJson +
+    // return 0 for human CLI stdout output. Mirrors the spend-verb dispatch.
+    if (context) {
+        return report;
+    }
+    writeJson(report);
     return 0;
 }
 async function postHostedJson(input) {
-    const auth = await resolveFreshRemoteAuth();
-    const response = await sendAuthedCloudRequest({
-        auth,
-        body: input.body,
-        method: 'POST',
-        pathName: input.pathName,
-        retryOn401: () => resolveFreshRemoteAuth({ forceRefresh: true }),
-        skillName: input.skillName,
-        timeoutMs: 120000,
-    });
+    const response = input.context
+        ? await sendAuthedCloudRequest({
+            auth: input.context.auth,
+            body: input.body,
+            method: 'POST',
+            pathName: input.pathName,
+            skillName: input.skillName,
+            skillsReleaseId: input.context.skillsReleaseId ?? null,
+            timeoutMs: 120000,
+        })
+        : await sendAuthedCloudRequest({
+            auth: await resolveFreshRemoteAuth(),
+            body: input.body,
+            method: 'POST',
+            pathName: input.pathName,
+            retryOn401: () => resolveFreshRemoteAuth({ forceRefresh: true }),
+            skillName: input.skillName,
+            timeoutMs: 120000,
+        });
     const payload = await readJsonResponse(response);
     if (!response.ok) {
         const productError = readHostedProductError(payload);
@@ -887,7 +933,7 @@ async function postHostedJson(input) {
     }
     return payload;
 }
-// Single exit path for every hosted command: success writes the result and
+// Single exit path for the BIN 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.
@@ -919,6 +965,20 @@ async function runHostedCommand(input) {
     await writeResult(payload, input.outputPath, input.json);
     return 0;
 }
+// Single exit path for both BIN and LIB hosted commands. Each dispatch function
+// builds the SAME `request` closure (resolve verb -> build envelope -> POST) and
+// hands it here. The bin path (no `context`) keeps stdout/file/exit-code behavior
+// via runHostedCommand. The lib path (with `context`) returns the parsed payload
+// and rethrows the structured HostedProductRequestError / quote-confirmation error
+// VERBATIM — no stdout, no file writes, no exit code — so the in-process caller
+// surfaces the structured JSON and fails honestly. Because the closure is shared,
+// the wire request (URL + body + headers) is byte-identical across both paths.
+async function dispatchHostedCommand(input, context) {
+    if (!context) {
+        return runHostedCommand(input);
+    }
+    return input.request();
+}
 async function writeQuoteConfirmationChallenge(error, input) {
     const challengePath = path.resolve(input.outputPath
         ? `${input.outputPath}.quote-confirmation.json`