@postplus/cli 0.1.34 → 0.1.36

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
@@ -209,6 +231,7 @@ Example requests:
 "Generate a storyboard for a 15-second hook."
 "Transcribe this video, create subtitles, and suggest B-roll placements."
 "Prepare provider-ready image or video generation requests."
+"Turn this product into a UGC-style video workflow with image, voice, clip, montage, and QA handoffs."
 ```
 
 Typical outputs:
@@ -218,6 +241,7 @@ Typical outputs:
 - hook and pattern breakdowns
 - storyboards and prompt requests
 - B-roll plans and edit-ready packages
+- image, video, audio, and UGC workflow controller handoffs
 - generated media candidates and manifests
 
 ### Strategy, Copy, SEO, and Growth
@@ -384,7 +408,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 +416,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/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`);
+}