@postplus/cli 0.1.33 → 0.1.35

package/README.md

@@ -33,7 +33,10 @@ Requires Node.js and npm.
 ```bash
 npm install -g @postplus/cli@latest
 postplus auth login
-npx -y skills add PostPlusAI/postplus-skills --global --full-depth --skill '*' --agent claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent --yes
+POSTPLUS_AGENT_TARGETS="claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent"
+for agent in $POSTPLUS_AGENT_TARGETS; do
+  npx -y skills add PostPlusAI/postplus-skills --global --full-depth --skill '*' --agent "$agent" --yes
+done
 postplus skills verify
 ```
 
@@ -41,7 +44,10 @@ If you explicitly do not want global skills, run the install from the target
 project directory and omit `--global`:
 
 ```bash
-npx -y skills add PostPlusAI/postplus-skills --full-depth --skill '*' --agent claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent --yes
+POSTPLUS_AGENT_TARGETS="claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent"
+for agent in $POSTPLUS_AGENT_TARGETS; do
+  npx -y skills add PostPlusAI/postplus-skills --full-depth --skill '*' --agent "$agent" --yes
+done
 ```
 
 Useful checks:
@@ -51,6 +57,22 @@ postplus status
 npx -y skills add PostPlusAI/postplus-skills --global --list
 ```
 
+Hosted request schema discovery:
+
+```bash
+postplus research schema --collection-key <collection-key> --json
+postplus media schema --endpoint <endpoint-key> --json
+postplus publish schema --json
+postplus mobile schema --json
+```
+
+Use these schema commands before an agent writes a `--input` or `--request`
+JSON file for a hosted PostPlus command. For media work, run
+`postplus media schema --json` first to list `endpointKeys`, then rerun with
+the selected `--endpoint`. For research work, run
+`postplus research schema --json` first to list `collectionKeys`, then rerun
+with the selected `--collection-key`.
+
 ## Local Studio
 
 For heavier skills that benefit from a visual workspace, use the CLI-managed
@@ -384,7 +406,7 @@ Start from the job, not the file name.
 
 1. Describe the outcome you want in natural language.
 2. If you are unsure which workflow fits, start with a router skill.
-3. Use `skills/INDEX.md` as the detailed map of active skills, boundaries, and handoffs.
+3. Use `skills/catalog.json` for machine-readable released skill metadata.
 4. Read the target `SKILL.md` before execution.
 5. Follow shared rulebooks when the task crosses platforms, products, ads, media, or publishing.
 6. Chain only the minimum skills needed to produce the next useful artifact.
@@ -392,9 +414,9 @@ Start from the job, not the file name.
 Important files:
 
 - `README.md`: this first-time onboarding page
-- `skills/INDEX.md`: detailed agent-facing navigation map
 - `skills/README.md`: short runtime catalog notes
-- `skills/shared-*.md`: shared routing and judgment rules
+- `skills/catalog.json`: released skill metadata for CLI and verification
+- `skills/00-shared/postplus-shared/references/`: shared routing and judgment rules
 - each `SKILL.md`: the workflow contract for one specific capability
 
 ## First Requests To Try

package/build/account-binding-display.js

@@ -0,0 +1,21 @@
+export function formatAccountBindingLines(input) {
+    if (input.accountType === 'team') {
+        return [
+            `Workspace: ${formatAccountBindingName(input)}`,
+            ...(input.accountSlug ? [`Workspace slug: ${input.accountSlug}`] : []),
+            `Account ID: ${input.accountId ?? 'not bound'}`,
+        ];
+    }
+    return [
+        `Account: ${input.accountName ?? 'not bound'}`,
+        `Account ID: ${input.accountId ?? 'not bound'}`,
+    ];
+}
+export function formatAccountBindingName(input) {
+    if (!input.accountName) {
+        return input.accountId ? `Account ${input.accountId}` : 'not bound';
+    }
+    return input.accountType === 'team'
+        ? `${input.accountName} (team)`
+        : input.accountName;
+}

package/build/auth-lifecycle.js

@@ -1,3 +1,4 @@
+import { formatAccountBindingLines } from './account-binding-display.js';
 import { refreshRemoteAuthSession } from './auth-session.js';
 import { clearAuthState, generateAuthStatusReport } from './auth.js';
 import { buildPostPlusClientCompatibilityHeaders, formatPostPlusCompatibilityError, } from './client-compatibility.js';
@@ -8,6 +9,9 @@ export async function refreshRemoteAuth() {
     const refreshed = await refreshRemoteAuthSession();
     return {
         accountId: refreshed.accountId,
+        accountName: refreshed.accountName,
+        accountSlug: refreshed.accountSlug,
+        accountType: refreshed.accountType,
         apiBaseUrl: refreshed.apiBaseUrl,
         ok: true,
         subscriptionStatus: refreshed.subscriptionStatus,
@@ -21,7 +25,7 @@ export function formatAuthRefreshReport(report) {
         '',
         `Remote auth: ${report.ok ? 'OK' : 'FAILED'}`,
         `PostPlus Cloud: ${report.apiBaseUrl}`,
-        `Account: ${report.accountId}`,
+        ...formatAccountBindingLines(report),
         `User: ${report.userEmail ?? report.userId}`,
         `Subscription: ${readSubscriptionStatusField(report).label}`,
     ].join('\n');

package/build/auth-login.js

@@ -34,6 +34,9 @@ export async function loginWithCloudHandoff() {
     });
     await setLocalSession({
         accountId: validated.accountId,
+        accountName: validated.accountName,
+        accountSlug: validated.accountSlug,
+        accountType: validated.accountType,
         apiBaseUrl: baseUrl,
         cliSessionToken: handoffPayload.cliSessionToken,
         sessionExpiresAt: validated.sessionExpiresAt ?? handoffPayload.sessionExpiresAt ?? null,
@@ -43,6 +46,9 @@ export async function loginWithCloudHandoff() {
     await writeCurrentCliVersionToLocalConfig();
     return {
         accountId: validated.accountId,
+        accountName: validated.accountName,
+        accountSlug: validated.accountSlug,
+        accountType: validated.accountType,
         apiBaseUrl: baseUrl,
         ok: true,
         userEmail: validated.userEmail,
@@ -135,6 +141,9 @@ export async function validateCliSession(input) {
     if (!response.ok) {
         throw new Error(formatCliSessionAuthError(payload));
     }
+    if (!isValidatedCliSessionPayload(payload)) {
+        throw new Error('PostPlus CLI auth validation returned incomplete data.');
+    }
     return payload;
 }
 export function formatCliSessionAuthError(payload) {
@@ -168,11 +177,25 @@ function isCliAuthLoginCompletedPayload(payload) {
         payload.status === 'completed' &&
         typeof payload.cliSessionToken === 'string' &&
         typeof payload.accountId === 'string' &&
+        typeof payload.accountName === 'string' &&
+        (payload.accountSlug === null || typeof payload.accountSlug === 'string') &&
+        (payload.accountType === 'personal' || payload.accountType === 'team') &&
         typeof payload.userId === 'string');
 }
 function isCliAuthLoginPendingPayload(payload) {
     return 'status' in payload && payload.status === 'pending';
 }
+function isValidatedCliSessionPayload(payload) {
+    return (typeof payload === 'object' &&
+        payload !== null &&
+        typeof payload.accountId === 'string' &&
+        typeof payload.accountName === 'string' &&
+        (payload.accountSlug === null ||
+            typeof payload.accountSlug === 'string') &&
+        (payload.accountType === 'personal' ||
+            payload.accountType === 'team') &&
+        typeof payload.userId === 'string');
+}
 function formatRemoteAuthLoginError(payload) {
     const compatibilityError = formatPostPlusCompatibilityError(payload);
     if (compatibilityError) {

package/build/auth-session.js

@@ -66,6 +66,9 @@ export async function refreshRemoteAuthSession(input) {
     }
     await setLocalSession({
         accountId: payload.accountId,
+        accountName: payload.accountName,
+        accountSlug: payload.accountSlug,
+        accountType: payload.accountType,
         apiBaseUrl,
         cliSessionToken: payload.cliSessionToken,
         sessionExpiresAt: payload.sessionExpiresAt,
@@ -86,5 +89,10 @@ function isRemoteAuthRefreshSuccessPayload(payload) {
         payload.cliSessionToken.trim().length >
             0 &&
         typeof payload.accountId === 'string' &&
+        typeof payload.accountName === 'string' &&
+        (payload.accountSlug === null ||
+            typeof payload.accountSlug === 'string') &&
+        (payload.accountType === 'personal' ||
+            payload.accountType === 'team') &&
         typeof payload.userId === 'string');
 }

package/build/auth-validate.js

@@ -1,3 +1,4 @@
+import { formatAccountBindingLines } from './account-binding-display.js';
 import { resolveFreshRemoteAuth } from './auth-session.js';
 import { buildPostPlusClientCompatibilityHeaders, formatPostPlusCompatibilityError, } from './client-compatibility.js';
 import { readSubscriptionStatusField } from './subscription-status.js';
@@ -22,10 +23,16 @@ export async function validateRemoteAuth() {
     }
     const hasSubscriptionStatus = Object.prototype.hasOwnProperty.call(payload, 'subscriptionStatus');
     const accountId = readRequiredString(payload, 'accountId');
+    const accountName = readRequiredString(payload, 'accountName');
+    const accountSlug = readNullableString(payload, 'accountSlug');
+    const accountType = readAccountType(payload);
     const userId = readRequiredString(payload, 'userId');
     const userEmail = readNullableString(payload, 'userEmail');
     return {
         accountId,
+        accountName,
+        accountSlug,
+        accountType,
         apiBaseUrl: auth.apiBaseUrl,
         ok: true,
         source: auth.source,
@@ -42,11 +49,18 @@ export function formatAuthValidateReport(report) {
         '',
         `Remote auth: ${report.ok ? 'OK' : 'FAILED'}`,
         `PostPlus Cloud: ${report.apiBaseUrl}`,
-        `Account: ${report.accountId}`,
+        ...formatAccountBindingLines(report),
         `User: ${report.userEmail ?? report.userId}`,
         `Subscription: ${readSubscriptionStatusField(report).label}`,
     ].join('\n');
 }
+function readAccountType(payload) {
+    const value = payload.accountType;
+    if (value !== 'personal' && value !== 'team') {
+        throw new Error('Invalid PostPlus auth response: accountType must be personal or team.');
+    }
+    return value;
+}
 async function fetchWhoami(input) {
     const compatibilityHeaders = await buildPostPlusClientCompatibilityHeaders();
     return fetch(`${input.apiBaseUrl}/api/postplus-cli/auth/whoami`, {

package/build/auth.js

@@ -1,3 +1,4 @@
+import { formatAccountBindingLines } from './account-binding-display.js';
 import { clearLocalAuthState, getPostPlusConfigPath, hasLocalConfigFile, maskSecret, readLocalConfig, resolveApiBaseUrlState, resolveLocalSessionState, setLocalApiBaseUrl, } from './local-state.js';
 export async function generateAuthStatusReport() {
     const [sessionState, apiBaseUrlState, configExists, config] = await Promise.all([
@@ -22,6 +23,15 @@ export async function generateAuthStatusReport() {
             path: getPostPlusConfigPath(),
             exists: configExists,
             accountId: config?.accountId?.trim() || null,
+            accountName: typeof config?.accountName === 'string'
+                ? config.accountName.trim() || null
+                : null,
+            accountSlug: typeof config?.accountSlug === 'string'
+                ? config.accountSlug.trim() || null
+                : null,
+            accountType: config?.accountType === 'personal' || config?.accountType === 'team'
+                ? config.accountType
+                : null,
             sessionExpiresAt: typeof config?.sessionExpiresAt === 'number'
                 ? config.sessionExpiresAt
                 : null,
@@ -47,7 +57,12 @@ export function formatAuthStatusReport(report) {
     lines.push(report.config.exists
         ? `[PASS] local config: ${report.config.path}`
         : `[PASS] local config path: ${report.config.path}`);
-    lines.push(`  Account: ${report.config.accountId ?? 'not bound'}`);
+    lines.push(...formatAccountBindingLines({
+        accountId: report.config.accountId,
+        accountName: report.config.accountName,
+        accountSlug: report.config.accountSlug,
+        accountType: report.config.accountType,
+    }).map((line) => `  ${line}`));
     lines.push(`  User: ${report.config.userEmail ?? report.config.userId ?? 'not bound'}`);
     lines.push(`  Expires: ${report.config.sessionExpiresAt
         ? new Date(report.config.sessionExpiresAt * 1000).toISOString()

package/build/client-compatibility.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { readLocalConfig, updateLocalConfig } from './local-state.js';
-export const POSTPLUS_CLIENT_CONTRACT_VERSION = 1;
+export const POSTPLUS_CLIENT_CONTRACT_VERSION = 2;
 export const POSTPLUS_CLIENT_RUNTIME = 'postplus-cli';
 export const POSTPLUS_CLIENT_COMPATIBILITY_HEADERS = {
     cliVersion: 'x-postplus-cli-version',

package/build/doctor.js

@@ -1,3 +1,4 @@
+import { formatAccountBindingName } from './account-binding-display.js';
 import { resolveFreshRemoteAuth, } from './auth-session.js';
 import { buildPostPlusClientCompatibilityHeaders, formatPostPlusCompatibilityError, } from './client-compatibility.js';
 import { resolveHostedBaseUrl } from './hosted-release.js';
@@ -131,13 +132,21 @@ async function checkRemoteAuth(input) {
             return createFail('remote_auth', 'Remote auth', readErrorMessage(payload, 'PostPlus Cloud rejected the CLI session.'), 'Run `postplus auth login`.');
         }
         const accountId = typeof payload.accountId === 'string' ? payload.accountId : 'unknown';
+        const accountName = typeof payload.accountName === 'string' ? payload.accountName : null;
+        const accountType = payload.accountType === 'personal' || payload.accountType === 'team'
+            ? payload.accountType
+            : null;
         const user = typeof payload.userEmail === 'string'
             ? payload.userEmail
             : typeof payload.userId === 'string'
                 ? payload.userId
                 : 'unknown';
         const subscription = readSubscriptionStatusField(payload).label;
-        return createPass('remote_auth', 'Remote auth', `Account ${accountId}; user ${user}; subscription ${subscription}`);
+        return createPass('remote_auth', 'Remote auth', `${formatAccountBindingName({
+            accountId,
+            accountName,
+            accountType,
+        })}; account ${accountId}; user ${user}; subscription ${subscription}`);
     }
     catch (error) {
         return createFail('remote_auth', 'Remote auth', error instanceof Error
@@ -216,9 +225,7 @@ function readCapabilityFailureLabel(value, skillScope) {
             .map(readReadinessCheckFailureLabel)
             .filter((check) => check !== null)
         : [];
-    const labelWithFailures = failedChecks.length > 0
-        ? `${label} (${failedChecks.join(', ')})`
-        : label;
+    const labelWithFailures = failedChecks.length > 0 ? `${label} (${failedChecks.join(', ')})` : label;
     return skillScope
         ? `${labelWithFailures} for ${skillScope.skill.skillId}`
         : labelWithFailures;

package/build/hosted-domain-commands.js

@@ -0,0 +1,366 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, 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 { readLargeCreditQuoteConfirmationChallenge, } from './quote-confirmation.js';
+class HostedQuoteConfirmationRequiredError extends Error {
+    challenge;
+    constructor(message, challenge) {
+        super(message);
+        this.challenge = challenge;
+        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',
+    ]),
+};
+export async function runHostedDomainCommand(domain, args) {
+    const [subcommand, ...rest] = args;
+    if (domain === 'research') {
+        if (subcommand === 'schema') {
+            return runHostedSchema(domain, rest);
+        }
+        if (subcommand === 'collect') {
+            return runResearchCollect(rest);
+        }
+        if (subcommand === 'capability') {
+            return runHostedCapability(domain, rest);
+        }
+        printResearchHelp();
+        return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
+    }
+    if (subcommand === 'schema') {
+        return runHostedSchema(domain, rest);
+    }
+    if (subcommand === 'capability') {
+        return runHostedCapability(domain, rest);
+    }
+    printCapabilityHelp(domain);
+    return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
+}
+async function runResearchCollect(args) {
+    const flags = parseFlags(args, new Set(['json']));
+    const runHandle = flags.values.get('run-handle');
+    const outputPath = flags.values.get('output') ?? null;
+    if (runHandle) {
+        const payload = await postHostedJson({
+            body: { runHandle },
+            pathName: '/api/postplus-cli/hosted/collection',
+            skillName: null,
+        });
+        await writeResult(payload, outputPath, flags.booleans.has('json'));
+        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 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,
+            skillName,
+        },
+        pathName: '/api/postplus-cli/hosted/collection',
+        skillName,
+    }).catch((error) => buildHostedCommandError(error, {
+        inputPath,
+        outputPath,
+    }));
+    await writeResult(payload, outputPath, flags.booleans.has('json'));
+    return 0;
+}
+async function runHostedSchema(domain, args) {
+    const flags = parseFlags(args, new Set(['json']));
+    const allowedFlags = domain === 'media'
+        ? new Set(['endpoint'])
+        : domain === 'research'
+            ? new Set(['collection-key'])
+            : new Set();
+    for (const key of flags.values.keys()) {
+        if (!allowedFlags.has(key)) {
+            throw new Error(`Unknown option for ${domain} schema: --${key}.`);
+        }
+    }
+    writeJson(buildHostedRequestSchemaReport({
+        collectionKey: flags.values.get('collection-key') ?? null,
+        domain,
+        endpointKey: flags.values.get('endpoint') ?? null,
+    }));
+    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({
+        apiBaseUrl: auth.apiBaseUrl,
+        body: input.body,
+        cliSessionToken: auth.cliSessionToken,
+        pathName: input.pathName,
+        skillName: input.skillName,
+    });
+    if (response.status === 401) {
+        auth = await resolveFreshRemoteAuth({ forceRefresh: true });
+        response = await postJson({
+            apiBaseUrl: auth.apiBaseUrl,
+            body: input.body,
+            cliSessionToken: auth.cliSessionToken,
+            pathName: input.pathName,
+            skillName: input.skillName,
+        });
+    }
+    const payload = await readJsonResponse(response);
+    if (!response.ok) {
+        const challenge = readLargeCreditQuoteConfirmationChallenge(payload);
+        if (challenge) {
+            throw new HostedQuoteConfirmationRequiredError(readProductError(payload), challenge);
+        }
+        const compatibilityError = formatPostPlusCompatibilityError(payload);
+        if (compatibilityError) {
+            throw new Error(compatibilityError);
+        }
+        throw new Error(readProductError(payload));
+    }
+    return payload;
+}
+async function buildHostedCommandError(error, input) {
+    if (!(error instanceof HostedQuoteConfirmationRequiredError)) {
+        throw error;
+    }
+    const challengePath = path.resolve(input.outputPath
+        ? `${input.outputPath}.quote-confirmation.json`
+        : `${input.inputPath}.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'));
+}
+async function postJson(input) {
+    const headers = await buildPostPlusClientCompatibilityHeaders({
+        skillName: input.skillName,
+    });
+    return fetch(`${input.apiBaseUrl}${input.pathName}`, {
+        body: JSON.stringify(input.body),
+        headers: {
+            accept: 'application/json',
+            authorization: `Bearer ${input.cliSessionToken}`,
+            ...headers,
+            'content-type': 'application/json',
+        },
+        method: 'POST',
+        signal: AbortSignal.timeout(120000),
+    });
+}
+async function readJsonResponse(response) {
+    const text = await response.text();
+    if (!text.trim()) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        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.';
+}
+async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? `Failed to read JSON file ${filePath}: ${error.message}`
+            : `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) {
+        process.stdout.write(text);
+    }
+    if (outputPath) {
+        await mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await writeFile(outputPath, text);
+    }
+}
+function parseFlags(args, booleanFlags) {
+    const values = new Map();
+    const booleans = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith('--')) {
+            throw new Error(`Unexpected positional argument: ${arg}`);
+        }
+        const key = arg.slice(2);
+        if (booleanFlags.has(key)) {
+            booleans.add(key);
+            continue;
+        }
+        const value = args[index + 1];
+        if (!value || value.startsWith('--')) {
+            throw new Error(`Missing value for --${key}.`);
+        }
+        values.set(key, value);
+        index += 1;
+    }
+    return { booleans, values };
+}
+function requireFlag(flags, key) {
+    const value = flags.values.get(key);
+    if (!value) {
+        throw new Error(`Missing required option --${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;
+}
+function isHelp(value) {
+    return value === 'help' || value === '--help' || value === '-h';
+}
+function printResearchHelp() {
+    process.stdout.write(`PostPlus CLI - research commands
+
+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 --run-handle <runHandle> [--output <result.json>]
+  postplus research capability --request <hosted-capability-request.json> [--output <result.json>]
+`);
+}
+function printCapabilityHelp(domain) {
+    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>]
+`);
+}
+function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}