@wavespeed/cli 0.4.3 → 0.4.5

package/README.md

@@ -195,3 +195,8 @@ Stack: TypeScript, Commander, Inquirer, Chalk, Ora, the official `wavespeed` SDK
 ## License
 
 MIT — see [LICENSE](LICENSE).
+
+---
+
+**[WaveSpeed AI](https://wavespeed.ai/)** — AI image & video generation platform.
+Try it in the browser: **[Image generator](https://wavespeed.ai/image-generator)** · **[Video generator](https://wavespeed.ai/video-generator)**

package/dist/commands/run.js

@@ -3,9 +3,10 @@ import ora from 'ora';
 import path from 'node:path';
 import fs from 'node:fs';
 import { requireClient } from '../lib/client.js';
-import { parseInputs } from '../lib/inputs.js';
+import { parseInputs, withInputSyntaxHint } from '../lib/inputs.js';
 import { resolveLocalFiles } from '../lib/local-files.js';
-import { submitPrediction, waitForPrediction } from '../lib/api.js';
+import { fetchModels, submitPrediction, waitForPrediction } from '../lib/api.js';
+import { findUnknownInputs } from '../lib/validate-inputs.js';
 import { uploadWithCache } from '../lib/upload-cache.js';
 import { downloadOutputs, printOutputs } from '../lib/output.js';
 import { emitJson, emitJsonError, isJsonMode, log, setJsonMode } from '../lib/log.js';
@@ -74,6 +75,7 @@ export function registerRun(program) {
         .option('--input-file <path>', 'JSON file with full input object')
         .option('--download [path]', 'Save outputs locally (optional path template, e.g. "./out/{index}.{ext}")')
         .option('--sync', 'Attempt sync mode; timed-out tasks can still be queried later')
+        .option('--no-validate', 'Skip pre-submit input validation against the model schema')
         .option('--json', 'Emit a single JSON object on stdout (progress goes to stderr)')
         .option('--output-dir <dir>', 'Directory for --download when no path is given')
         .action(async (modelArg, opts) => {
@@ -97,6 +99,50 @@ export function registerRun(program) {
         Object.assign(input, parseInputs(opts.input ?? []));
         if (opts.prompt)
             input.prompt = opts.prompt;
+        // Reject inputs the model's schema does not declare BEFORE anything
+        // costs money. The API's entry whitelist silently drops unknown keys,
+        // so a typo doesn't fail — it bills a generation that ignored the
+        // parameter. Validation fails open (no schema → no check) and, to
+        // avoid stale-cache false positives, re-fetches the catalog once
+        // before rejecting.
+        if (opts.validate !== false) {
+            try {
+                let { models } = await fetchModels();
+                let found = models.find((m) => m.model_id === model);
+                let report = findUnknownInputs(input, found);
+                if (report) {
+                    ({ models } = await fetchModels({ refresh: true }));
+                    found = models.find((m) => m.model_id === model);
+                    report = findUnknownInputs(input, found);
+                }
+                if (report) {
+                    const lines = report.unknown.map((k) => {
+                        const hint = report.suggestions.get(k);
+                        return `  ${k}` + (hint ? `  (did you mean \`${hint}\`?)` : '');
+                    });
+                    const msg = `Model ${model} does not accept: ${report.unknown.join(', ')}. ` +
+                        `The API silently drops unknown inputs, so this would bill a run that ignores them.`;
+                    if (isJsonMode()) {
+                        emitJsonError(msg, { unknown_inputs: report.unknown, accepted_inputs: report.known });
+                    }
+                    else {
+                        console.error(chalk.red('Error: ') + `unknown input${report.unknown.length > 1 ? 's' : ''} for ` + chalk.cyan(model) + ':');
+                        for (const l of lines)
+                            console.error(chalk.yellow(l));
+                        console.error(chalk.gray('  The API silently drops unknown inputs — the run would be billed with them ignored.'));
+                        console.error(chalk.gray('  Accepted inputs: ') + report.known.join(', '));
+                        console.error(chalk.gray('  Full schema:     ') + chalk.cyan(`wavespeed schema ${model}`));
+                        console.error(chalk.gray('  Bypass check:    ') + chalk.cyan('--no-validate'));
+                    }
+                    process.exit(1);
+                }
+            }
+            catch {
+                // Catalog unreachable — validation is best-effort, never a blocker.
+                // (The unknown-input rejection above exits the process directly and
+                // is not routed through here.)
+            }
+        }
         // `@path` inputs become hosted URLs before submission. Only the
         // explicit @ marker uploads — the CLI never guesses that a bare value
         // was meant to be a file.
@@ -137,7 +183,7 @@ export function registerRun(program) {
             submitted = await submitPrediction(model, input, { sync: !!opts.sync });
         }
         catch (err) {
-            const message = err.message ?? String(err);
+            const message = withInputSyntaxHint(err.message ?? String(err), opts.input);
             spinner.fail(message);
             if (isJsonMode())
                 emitJsonError(message);

package/dist/lib/inputs.js

@@ -2,8 +2,9 @@
 // - bare strings stay strings
 // - "123" / "1.5" parsed as number
 // - "true" / "false" parsed as boolean
-// - "[a,b,c]" parsed as array of strings
-// - JSON values (starting with { or [) parsed as JSON
+// - values starting with { or [ are parsed as JSON, and stay strings if that
+//   fails — so an array has to be written as valid JSON: '["a","b"]'.
+//   A bare "[a,b,c]" is not JSON and reaches the API as a string.
 // - keys with dots like "size.width" become nested
 function coerce(raw) {
     if (raw === 'true')
@@ -50,3 +51,16 @@ function setPath(obj, dotted, value) {
     }
     cur[parts[parts.length - 1]] = value;
 }
+/**
+ * The API rejects a scalar sent to an array field. The message says what is
+ * wrong but not how to write it, and `-i key=value` gives no hint that an
+ * array needs JSON — so point at the fix rather than mutating the input.
+ */
+export function withInputSyntaxHint(message, pairs = []) {
+    const field = /field "([^"]+)" must be an array/.exec(message)?.[1];
+    if (!field)
+        return message;
+    const given = pairs.find((p) => p.slice(0, p.indexOf('=')).trim() === field);
+    const sample = given ? given.slice(given.indexOf('=') + 1) : 'value';
+    return `${message}\nWrite arrays as JSON: -i '${field}=["${sample}"]'`;
+}

package/dist/lib/validate-inputs.js

@@ -0,0 +1,62 @@
+// Pre-submit input validation against a model's published request schema.
+//
+// The API's entry whitelist silently DROPS any input key that is not in the
+// model's schema — a typo like `size=2560*1440` against a model whose real
+// knobs are `aspect_ratio`/`resolution` doesn't fail, it just quietly bills a
+// generation with defaults. Catching that before submission is the only
+// moment the mistake is still free.
+//
+// Validation fails OPEN: no schema (brand-new model, catalog lag, offline
+// cache miss) means no check. It must never block a submission the API would
+// have accepted.
+export function requestSchemaProps(model) {
+    const props = model?.api_schema?.api_schemas?.[0]?.request_schema?.properties;
+    if (!props)
+        return null;
+    const keys = Object.keys(props);
+    return keys.length > 0 ? keys : null;
+}
+// Small edit distance for typo hints — inputs are short snake_case tokens, so
+// a full Levenshtein over ≤40 keys is nothing.
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return dp[a.length][b.length];
+}
+function closest(key, known) {
+    let best;
+    let bestD = Infinity;
+    for (const k of known) {
+        const d = editDistance(key.toLowerCase(), k.toLowerCase());
+        if (d < bestD) {
+            bestD = d;
+            best = k;
+        }
+    }
+    // A hint is only a hint when it's plausibly the same word.
+    return bestD <= Math.max(2, Math.floor(key.length / 3)) ? best : undefined;
+}
+/**
+ * Compare top-level input keys with the schema's properties.
+ * Returns null when everything checks out or no schema is available.
+ */
+export function findUnknownInputs(input, model) {
+    const known = requestSchemaProps(model);
+    if (!known)
+        return null;
+    const knownSet = new Set(known);
+    const unknown = Object.keys(input).filter((k) => !knownSet.has(k));
+    if (unknown.length === 0)
+        return null;
+    const suggestions = new Map();
+    for (const k of unknown) {
+        const hit = closest(k, known);
+        if (hit)
+            suggestions.set(k, hit);
+    }
+    return { unknown, known, suggestions };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "WaveSpeed CLI \u2014 one command to run any WaveSpeed AI model from your terminal.",
   "publishConfig": {
     "access": "public"