@scenerok/cli 2.4.0 → 2.5.0

package/dist/commands/plugin.js

@@ -0,0 +1,651 @@
+/**
+ * `scenerok plugin` — marketplace authoring commands (#122).
+ *
+ *   init     scaffold an RFC §4.1 package
+ *   validate run the *server's* static checks locally (no network, no auth)
+ *   publish  validate, build the canonical tarball, upload, queue a build
+ *   status   show one build's stage, checks and resulting version
+ *
+ * `validate` and `publish` share `src/lib/plugins/cli-checks-entry.ts` with the
+ * server and the `plugin-builder` service, bundled into the CLI at build time
+ * (`scripts/build-cli-plugin-checks.mjs`). A local pass is therefore the same
+ * result the builder will produce — not an approximation.
+ *
+ * Exit codes: `0` success, `1` checks failed / build failed, `2` usage error.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { getPlugin, getPluginBuild, runPlugin, searchPlugins, publishPluginPackage, } from '../lib/api.js';
+import { getBaseUrl, isAuthenticated } from '../lib/config.js';
+import { formatApiErrorMessage } from '../lib/format-api-error.js';
+import { logError } from '../lib/logger.js';
+import { checkPluginDirectory, formatBytes, loadPluginChecks, printStaticCheckReport, } from '../lib/plugin-checks.js';
+import { buildScaffold } from '../lib/plugin-scaffold.js';
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+function fail(write, message) {
+    write(chalk.red(`Error: ${message}`));
+    return EXIT_USAGE;
+}
+function plural(count, word) {
+    return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+function shortSha(sha) {
+    return `${sha.slice(0, 12)}…`;
+}
+/** `My Plugin` → `my-plugin`, for a helpful "did you mean" on a bad slug. */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 49);
+}
+export async function runPluginInit(options = {}) {
+    const write = options.write ?? ((line) => console.log(line));
+    const target = resolve(options.dir ?? '.');
+    const checks = await loadPluginChecks();
+    const kind = (options.kind ?? 'vertical').trim();
+    if (!checks.PLUGIN_KINDS.includes(kind)) {
+        return fail(write, `unknown --kind "${kind}". Choose one of: ${checks.PLUGIN_KINDS.join(', ')}`);
+    }
+    const rawNamespace = (options.namespace ?? '').trim().replace(/^@/, '');
+    if (!rawNamespace) {
+        return fail(write, 'missing --namespace. Use the handle you publish under, e.g. --namespace acme');
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(rawNamespace)) {
+        return fail(write, `invalid --namespace "${options.namespace}". Use lowercase letters, digits and dashes, starting with a letter.`);
+    }
+    const folderName = target.split(/[\\/]/).filter(Boolean).pop() ?? '';
+    const slug = (options.slug ?? folderName).trim();
+    if (!checks.SLUG_PATTERN.test(slug)) {
+        const suggestion = slugify(options.slug ?? folderName);
+        return fail(write, `invalid --slug "${slug}" (lowercase, 2–49 chars, starts with a letter).` +
+            (checks.SLUG_PATTERN.test(suggestion) ? ` Try: --slug ${suggestion}` : ''));
+    }
+    if (existsSync(target) && !statSync(target).isDirectory()) {
+        return fail(write, `${target} exists and is not a directory.`);
+    }
+    const existing = existsSync(target) ? readdirSync(target) : [];
+    if (existing.length > 0 && !options.force) {
+        return fail(write, `${target} is not empty (${plural(existing.length, 'entry')}: ${existing
+            .slice(0, 3)
+            .join(', ')}${existing.length > 3 ? ', …' : ''}).\n` +
+            'Choose an empty directory or pass --force to add the missing scaffold files.');
+    }
+    const scaffold = buildScaffold({
+        kind,
+        slug,
+        namespace: rawNamespace,
+        title: options.title,
+        summary: options.summary,
+    });
+    const created = [];
+    const kept = [];
+    for (const [path, contents] of scaffold.files) {
+        const absolute = join(target, path);
+        if (existsSync(absolute)) {
+            kept.push(path);
+            continue;
+        }
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, contents, 'utf-8');
+        created.push(path);
+    }
+    const manifest = scaffold.manifest;
+    write('');
+    write(chalk.green(`✔ Created ${manifest.id}`) + chalk.dim(` (${manifest.kind})`));
+    write(chalk.dim(`  ${target}`));
+    write('');
+    for (const path of created)
+        write(`  ${chalk.green('+')} ${path}`);
+    for (const path of kept)
+        write(`  ${chalk.dim('=')} ${path} ${chalk.dim('(kept)')}`);
+    write('');
+    write(chalk.cyan('  Next:'));
+    if (options.dir && resolve(options.dir) !== process.cwd()) {
+        write(`    cd ${options.dir}`);
+    }
+    write('    scenerok plugin validate');
+    write('    scenerok plugin publish');
+    write('');
+    write(chalk.dim('  Manifest reference: docs/reference-plugin-manifest.md'));
+    write('');
+    return EXIT_OK;
+}
+export async function runPluginValidate(options = {}) {
+    const write = options.write ?? ((line) => console.log(line));
+    const dir = resolve(options.dir ?? '.');
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        return fail(write, `${dir} is not a directory.`);
+    }
+    const started = Date.now();
+    const { read, report } = await checkPluginDirectory(dir);
+    const elapsedMs = Date.now() - started;
+    const manifest = readManifestIdentity(read.files);
+    if (options.json) {
+        write(JSON.stringify({
+            ok: report.ok,
+            needsReview: report.needsReview,
+            directory: dir,
+            package: manifest,
+            files: read.files.size,
+            bytes: read.bytes,
+            skipped: read.skipped,
+            checks: report.checks,
+        }, null, 2));
+        return report.ok ? EXIT_OK : EXIT_FAILED;
+    }
+    const printOptions = {
+        title: manifest?.id ?? 'plugin package',
+        directory: dir,
+        files: read.files.size,
+        bytes: read.bytes,
+        verbose: options.verbose,
+        quiet: options.quiet,
+        write,
+    };
+    printStaticCheckReport(report, printOptions);
+    if (read.skipped.length > 0) {
+        write(chalk.dim(`  Not packaged: ${read.skipped.slice(0, 6).join(', ')}${read.skipped.length > 6 ? ', …' : ''} (dotfiles and node_modules are never uploaded)`));
+        write('');
+    }
+    write(chalk.dim(`  ${read.files.size} files · ${formatBytes(read.bytes)} · ${elapsedMs} ms · local checks`));
+    write('');
+    return report.ok ? EXIT_OK : EXIT_FAILED;
+}
+/** Best-effort identity from the manifest bytes (the checks already reported errors). */
+function readManifestIdentity(files) {
+    const bytes = files.get('scenerok-plugin.json');
+    if (!bytes)
+        return null;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        return {
+            ...(typeof parsed.id === 'string' ? { id: parsed.id } : {}),
+            ...(typeof parsed.kind === 'string' ? { kind: parsed.kind } : {}),
+            ...(typeof parsed.title === 'string' ? { title: parsed.title } : {}),
+            ...(typeof parsed.versionLabel === 'string' ? { versionLabel: parsed.versionLabel } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const TERMINAL_BUILD_STATUSES = new Set(['passed', 'failed']);
+export async function runPluginPublish(options = {}) {
+    const write = options.write ?? ((line) => console.log(line));
+    const dir = resolve(options.dir ?? '.');
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        return fail(write, `${dir} is not a directory.`);
+    }
+    write('');
+    write(chalk.dim(`  API: ${getBaseUrl()}`));
+    // 1. The same checks the builder will run — fail before uploading anything.
+    const validateStarted = Date.now();
+    const { read, report } = await checkPluginDirectory(dir);
+    const identity = readManifestIdentity(read.files);
+    if (!options.json) {
+        printStaticCheckReport(report, {
+            title: identity?.id ?? 'plugin package',
+            directory: dir,
+            files: read.files.size,
+            bytes: read.bytes,
+            write,
+        });
+    }
+    if (!report.ok) {
+        logError('plugin publish blocked by local checks', { dir });
+        write(chalk.red('  Nothing was uploaded. Fix the errors above and run publish again.'));
+        write('');
+        return EXIT_FAILED;
+    }
+    write(chalk.green(`  ✔ Local checks passed`) +
+        chalk.dim(` (${Date.now() - validateStarted} ms · ${read.files.size} files · ${formatBytes(read.bytes)})`));
+    // 2. Canonical tarball + content hash (the server recomputes it).
+    const checks = await loadPluginChecks();
+    const tarball = checks.buildCanonicalTarGz(read.files);
+    const sha256 = checks.computeSourceSha256(read.files);
+    write(chalk.dim(`  Tarball ${formatBytes(tarball.byteLength)} · sha256 ${shortSha(sha256)}`));
+    const spinner = options.json ? null : ora('Uploading…').start();
+    try {
+        const form = new FormData();
+        form.set('tarball', new Blob([new Uint8Array(tarball)], { type: 'application/gzip' }), 'plugin.tgz');
+        form.set('sourceSha256', sha256);
+        const result = await publishPluginPackage(form);
+        spinner?.succeed('Uploaded');
+        if (options.json) {
+            write(JSON.stringify(result, null, 2));
+        }
+        else {
+            write('');
+            write(chalk.green(`  ✔ Build ${result.buildId}`) + (result.created ? '' : chalk.dim(' (reused — same source)')));
+            write(`  ${chalk.bold(result.package.id)}` +
+                chalk.dim(` · ${result.package.kind}${result.package.versionLabel ? ` · v${result.package.versionLabel}` : ''}`));
+            write('');
+            write(chalk.cyan('  Next:'));
+            write(`    scenerok plugin status ${result.buildId}`);
+            write(`    scenerok plugin status ${result.buildId} --watch`);
+            write('');
+            write(chalk.dim('  The build runs the same checks you just ran, then creates the version for review.'));
+            write('');
+        }
+        if (options.watch) {
+            return await watchPluginBuild(result.buildId, {
+                write,
+                json: options.json,
+                verbose: false,
+                pollIntervalMs: options.pollIntervalMs,
+                watchTimeoutMs: options.watchTimeoutMs,
+            });
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        spinner?.fail('Upload failed');
+        logError('plugin publish failed', { dir, error: formatApiErrorMessage(error) });
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return error && typeof error === 'object' && 'status' in error && error.status === 401
+            ? EXIT_USAGE
+            : EXIT_FAILED;
+    }
+}
+function printBuild(view, write, verbose) {
+    const tone = view.status === 'passed' ? chalk.green : view.status === 'failed' ? chalk.red : chalk.cyan;
+    write('');
+    write(`  Build ${chalk.bold(view.id)}`);
+    write(`  Status   ${tone(view.status)}${view.stage !== view.status ? chalk.dim(` · stage ${view.stage}`) : ''}`);
+    if (view.plugin) {
+        write(`  Package  ${chalk.bold(`@${view.plugin.namespace}/${view.plugin.slug}`)}`);
+    }
+    if (view.version) {
+        const label = view.version.versionLabel ? chalk.dim(` · ${view.version.versionLabel}`) : '';
+        write(`  Version  ${view.version.version} ${chalk.dim(`(${view.version.status})`)}${label}`);
+    }
+    if (view.needsReview !== null) {
+        write(`  Review   ${view.needsReview ? chalk.yellow('human review required') : chalk.dim('no extra review')}`);
+    }
+    write(`  Source   ${chalk.dim(shortSha(view.sourceSha256))}`);
+    write(`  Created  ${chalk.dim(view.createdAt)}`);
+    if (view.reason) {
+        write('');
+        write(chalk.red(`  Reason: ${view.reason}`));
+    }
+    if (view.checks.length > 0) {
+        printStaticCheckReport({
+            ok: view.status !== 'failed',
+            needsReview: view.needsReview ?? false,
+            checks: view.checks,
+        }, { verbose, quiet: false, write });
+    }
+    else {
+        write('');
+        write(chalk.dim(`  ${view.status === 'queued' ? 'Queued — checks have not run yet.' : 'No check report yet.'}`));
+        write('');
+    }
+    if (verbose && view.log) {
+        write(chalk.dim('  Build log:'));
+        for (const line of view.log.split('\n'))
+            write(chalk.dim(`    ${line}`));
+        write('');
+    }
+}
+async function watchPluginBuild(buildId, options) {
+    const { write } = options;
+    const interval = options.pollIntervalMs ?? 2000;
+    const timeout = options.watchTimeoutMs ?? 10 * 60 * 1000;
+    const started = Date.now();
+    let lastStage = '';
+    if (!options.json) {
+        write(chalk.dim(`  Watching ${buildId} (Ctrl-C to stop)…`));
+    }
+    while (true) {
+        const view = await getPluginBuild(buildId);
+        if (view.stage !== lastStage && !options.json) {
+            lastStage = view.stage;
+            write(chalk.dim(`  · ${view.status} (${view.stage})`));
+        }
+        if (TERMINAL_BUILD_STATUSES.has(view.status)) {
+            if (options.json)
+                write(JSON.stringify(view, null, 2));
+            else
+                printBuild(view, write, options.verbose);
+            if (view.status === 'failed') {
+                write(chalk.red('  Build failed — nothing was published. Fix the errors and re-run publish.'));
+                write('');
+                return EXIT_FAILED;
+            }
+            write(chalk.green(`  Build passed — version ${view.version?.version ?? '?'} is awaiting review.`));
+            write('');
+            return EXIT_OK;
+        }
+        if (Date.now() - started > timeout) {
+            write(chalk.yellow(`  Still ${view.status} after ${Math.round(timeout / 60000)} min. Check again with: scenerok plugin status ${buildId}`));
+            write('');
+            return EXIT_OK;
+        }
+        await new Promise((resolveWait) => setTimeout(resolveWait, interval));
+    }
+}
+export async function runPluginStatus(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    if (!options.buildId || options.buildId.trim().length === 0) {
+        return fail(write, 'missing build id. Usage: scenerok plugin status <buildId>');
+    }
+    try {
+        if (options.watch) {
+            return await watchPluginBuild(options.buildId, {
+                write,
+                json: options.json,
+                verbose: options.verbose === true,
+                pollIntervalMs: options.pollIntervalMs,
+                watchTimeoutMs: options.watchTimeoutMs,
+            });
+        }
+        const view = await getPluginBuild(options.buildId);
+        if (options.json) {
+            write(JSON.stringify(view, null, 2));
+        }
+        else {
+            printBuild(view, write, options.verbose === true);
+        }
+        return view.status === 'failed' ? EXIT_FAILED : EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+function parsePluginLookupRef(raw) {
+    let value = raw.trim();
+    if (value.startsWith('scenerok://plugin/'))
+        value = value.slice('scenerok://plugin/'.length);
+    if (value.startsWith('@')) {
+        const slash = value.indexOf('/');
+        if (slash > 0)
+            value = value.slice(slash + 1);
+    }
+    const at = value.lastIndexOf('@');
+    const slug = at > 0 ? value.slice(0, at) : value;
+    const version = at > 0 ? value.slice(at + 1) : undefined;
+    if (!/^[a-z][a-z0-9-]{1,48}$/.test(slug)) {
+        throw new Error(`invalid plugin ref "${raw}"`);
+    }
+    return { slug, version };
+}
+function parseJsonValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return '';
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return raw;
+    }
+}
+function assignPath(target, path, value) {
+    const parts = path.split('.').filter(Boolean);
+    if (parts.length === 0)
+        throw new Error('empty --set key');
+    let cursor = target;
+    for (const part of parts.slice(0, -1)) {
+        const existing = cursor[part];
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    }
+    cursor[parts[parts.length - 1]] = value;
+}
+function parseSetOverride(raw) {
+    const equals = raw.indexOf('=');
+    if (equals <= 0)
+        throw new Error(`invalid --set "${raw}" (expected key=value)`);
+    return {
+        key: raw.slice(0, equals).trim(),
+        value: parseJsonValue(raw.slice(equals + 1)),
+    };
+}
+function loadRunInputs(options) {
+    let inputs = {};
+    if (options.input) {
+        const parsed = JSON.parse(readFileSync(resolve(options.input), 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('--input must point to a JSON object');
+        }
+        inputs = { ...parsed };
+    }
+    for (const raw of options.set ?? []) {
+        const override = parseSetOverride(raw);
+        assignPath(inputs, override.key, override.value);
+    }
+    return inputs;
+}
+function parseMaxTokens(value) {
+    const parsed = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error('missing or invalid --max-tokens N (positive integer required)');
+    }
+    return parsed;
+}
+function costLine(estimate, worstCase) {
+    if (!estimate)
+        return `worst case ${worstCase.totalTokens} tokens`;
+    return `estimate ${estimate.totalTokens} tokens · worst case ${worstCase.totalTokens} tokens`;
+}
+function printPluginSummary(plugin, write) {
+    const label = plugin.latestVersion.versionLabel ? ` (${plugin.latestVersion.versionLabel})` : '';
+    write(`${chalk.bold(plugin.title)} ${chalk.dim(plugin.ref)}${label}`);
+    if (plugin.summary)
+        write(`  ${plugin.summary}`);
+    write(`  ${plugin.kind}${plugin.category ? ` · ${plugin.category}` : ''} · ${costLine(plugin.typicalCost?.estimate ?? null, plugin.worstCase)}`);
+    const permissions = [
+        plugin.permissions.providers.length ? `providers: ${plugin.permissions.providers.join(', ')}` : null,
+        plugin.permissions.connectors.length ? `connectors: ${plugin.permissions.connectors.join(', ')}` : null,
+        plugin.permissions.network.length ? `network: ${plugin.permissions.network.join(', ')}` : null,
+    ].filter(Boolean);
+    if (permissions.length)
+        write(chalk.dim(`  ${permissions.join(' · ')}`));
+    if (plugin.badges.length)
+        write(chalk.dim(`  badges: ${plugin.badges.join(', ')}`));
+}
+function printPluginDetail(plugin, write) {
+    printPluginSummary(plugin, write);
+    write('');
+    write(chalk.cyan('Input schema:'));
+    write(JSON.stringify(plugin.inputSchema, null, 2));
+    if (plugin.typicalCost) {
+        write('');
+        write(chalk.cyan(`Typical cost (${plugin.typicalCost.examplePath}):`));
+        write(JSON.stringify(plugin.typicalCost.estimate, null, 2));
+    }
+    if (plugin.readmeExcerpt) {
+        write('');
+        write(chalk.cyan('README excerpt:'));
+        write(plugin.readmeExcerpt);
+    }
+    if (plugin.untrusted_text_notice) {
+        write('');
+        write(chalk.yellow(plugin.untrusted_text_notice));
+    }
+}
+function printPluginRunResult(result, write) {
+    write(`${chalk.green('Estimate')} ${result.estimate.totalTokens} tokens · ${chalk.yellow('worst case')} ${result.worstCaseTokens} tokens`);
+    if (result.dryRun) {
+        write(chalk.dim('Dry run only; no render was created.'));
+        return;
+    }
+    if (result.render) {
+        write(`${chalk.green('Render')} ${result.render.renderId} · ${result.render.status}`);
+        if (result.render.renderUrl)
+            write(`Page: ${result.render.renderUrl}`);
+        if (result.render.downloadUrl)
+            write(`Download: ${result.render.downloadUrl}`);
+        write(chalk.dim(`Next: scenerok status ${result.render.renderId}`));
+    }
+}
+export async function runPluginSearch(options = {}) {
+    const write = options.write ?? ((line) => console.log(line));
+    try {
+        const result = await searchPlugins({
+            q: options.q,
+            category: options.category,
+            kind: options.kind,
+            limit: options.limit,
+        });
+        if (options.json) {
+            write(JSON.stringify(result, null, 2));
+            return EXIT_OK;
+        }
+        if (result.plugins.length === 0) {
+            write('No plugins found.');
+            return EXIT_OK;
+        }
+        for (const plugin of result.plugins) {
+            printPluginSummary(plugin, write);
+            write('');
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+export async function runPluginShow(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    try {
+        const ref = parsePluginLookupRef(options.ref);
+        const result = await getPlugin(ref.slug, ref.version);
+        if (options.json)
+            write(JSON.stringify(result.plugin, null, 2));
+        else
+            printPluginDetail(result.plugin, write);
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+export async function runPluginRunCommand(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    try {
+        const inputs = loadRunInputs(options);
+        const maxTokens = parseMaxTokens(options.maxTokens);
+        const result = await runPlugin({
+            ref: options.ref,
+            inputs,
+            maxTokens,
+            dryRun: options.dryRun,
+        });
+        if (options.json)
+            write(JSON.stringify(result, null, 2));
+        else
+            printPluginRunResult(result, write);
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+// ---------------------------------------------------------------------------
+// command wiring
+// ---------------------------------------------------------------------------
+export const pluginCommand = new Command('plugin')
+    .description('Create, validate, publish and run marketplace plugins')
+    .addCommand(new Command('init')
+    .description('Scaffold a new plugin package')
+    .argument('[dir]', 'Directory to create the package in', '.')
+    .option('-k, --kind <kind>', 'Plugin kind (vertical, template-pack, code, …)', 'vertical')
+    .option('-s, --slug <slug>', 'Plugin slug (defaults to the directory name)')
+    .option('-n, --namespace <namespace>', 'Your publisher namespace, e.g. acme')
+    .option('-t, --title <title>', 'Human-readable title')
+    .option('--summary <summary>', 'One-line listing summary')
+    .option('--force', 'Add missing scaffold files to a non-empty directory')
+    .action(async (dir, options) => {
+    process.exitCode = await runPluginInit({ ...options, dir });
+}))
+    .addCommand(new Command('validate')
+    .description('Run the publish checks locally (no network, no credentials)')
+    .argument('[dir]', 'Plugin package directory', '.')
+    .option('--json', 'Machine-readable report')
+    .option('--verbose', 'List every passing check')
+    .option('--quiet', 'Only show failures')
+    .action(async (dir, options) => {
+    process.exitCode = await runPluginValidate({ ...options, dir });
+}))
+    .addCommand(new Command('publish')
+    .description('Validate, upload and queue a build for review')
+    .argument('[dir]', 'Plugin package directory', '.')
+    .option('--watch', 'Follow the build until it passes or fails')
+    .option('--json', 'Machine-readable output')
+    .action(async (dir, options) => {
+    process.exitCode = await runPluginPublish({ ...options, dir });
+}))
+    .addCommand(new Command('status')
+    .description('Show a build’s stage, checks and resulting version')
+    .argument('<buildId>', 'Build id printed by `scenerok plugin publish`')
+    .option('--watch', 'Follow the build until it passes or fails')
+    .option('--json', 'Machine-readable output')
+    .option('-v, --verbose', 'Include the timestamped build log')
+    .action(async (buildId, options) => {
+    process.exitCode = await runPluginStatus({ ...options, buildId });
+}))
+    .addCommand(new Command('search')
+    .description('Search published marketplace plugins')
+    .argument('[q]', 'Search text')
+    .option('--category <category>', 'Filter by category')
+    .option('--kind <kind>', 'Filter by manifest kind')
+    .option('--limit <n>', 'Maximum results', (value) => Number.parseInt(value, 10))
+    .option('--json', 'Machine-readable output')
+    .action(async (q, options) => {
+    process.exitCode = await runPluginSearch({ ...options, q });
+}))
+    .addCommand(new Command('show')
+    .description('Show a published plugin schema, costs and permissions')
+    .argument('<ref>', 'Plugin slug or ref')
+    .option('--json', 'Machine-readable output')
+    .action(async (ref, options) => {
+    process.exitCode = await runPluginShow({ ...options, ref });
+}))
+    .addCommand(new Command('run')
+    .description('Run a published plugin')
+    .argument('<ref>', 'Pinned plugin ref')
+    .option('--input <file>', 'JSON input object')
+    .option('--set <key=value>', 'Set or override an input value (repeatable)', (value, previous = []) => [
+    ...previous,
+    value,
+])
+    .requiredOption('--max-tokens <n>', 'Hard token cap; refused before debit if worst-case is higher')
+    .option('--dry-run', 'Return estimate and bound without creating a render')
+    .option('--json', 'Machine-readable output')
+    .action(async (ref, options) => {
+    process.exitCode = await runPluginRunCommand({ ...options, ref });
+}));

package/dist/index.js

@@ -11,6 +11,7 @@ import { validateCommand } from './commands/validate.js';
 import { lintVideoCommand } from './commands/lint-video.js';
 import { projectCommand } from './commands/project.js';
 import { cacheCommand } from './commands/cache.js';
+import { pluginCommand } from './commands/plugin.js';
 const program = new Command();
 const packageJson = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
 program
@@ -23,6 +24,7 @@ program.addCommand(skillsCommand);
 program.addCommand(renderCommand);
 program.addCommand(projectCommand);
 program.addCommand(cacheCommand);
+program.addCommand(pluginCommand);
 program.addCommand(validateCommand);
 program.addCommand(lintVideoCommand);
 program.addCommand(statusCommand);
@@ -43,6 +45,11 @@ program.on('--help', () => {
     console.log('  $ scenerok lint-video 42 --cost low --json');
     console.log('  $ scenerok project upload video.vidscript --assets ./assets --render --watch --download');
     console.log('  $ scenerok cache pull');
+    console.log('  $ scenerok plugin init my-plugin --namespace acme --kind vertical');
+    console.log('  $ scenerok plugin validate');
+    console.log('  $ scenerok plugin publish --watch');
+    console.log('  $ scenerok plugin search "product promo"');
+    console.log('  $ scenerok plugin run scenerok://plugin/listing-promo@1 --input run.json --max-tokens 1000');
     console.log('  $ scenerok status 42');
     console.log('');
     console.log(chalk.cyan('Get started:'));