@aisa-one/cli 0.2.1 → 0.2.3

package/dist/commands/video.js

@@ -1,94 +1,311 @@
+import { writeFile } from "node:fs/promises";
 import ora from "ora";
 import chalk from "chalk";
 import { requireApiKey } from "../config.js";
 import { apiRequest } from "../api.js";
-import { error, formatJson, success } from "../utils/display.js";
+import { error, formatJson, hint, success } from "../utils/display.js";
+import { DEFAULT_VIDEO_MODEL, MEDIA_TYPES, VIDEO_MODELS, videoModelSpec, } from "../constants.js";
+/** Statuses after which the task will never change again. */
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const POLL_INTERVAL_MS = 5000;
+const MAX_WAIT_MS = 15 * 60 * 1000;
+const VIDEO_KEY = /video.*url|url.*video/i;
+const URL_KEY = /url$/i;
+/** Keys that carry a still image rather than the clip — thumbnails end in "url" too. */
+const NOT_VIDEO_KEY = /thumb|cover|preview|poster|image|img|icon|logo|snapshot|avatar|first_frame|last_frame/i;
+function searchUrl(value, keyMatches, depth = 0) {
+    if (depth > 8 || value == null)
+        return undefined;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = searchUrl(item, keyMatches, depth + 1);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (typeof value !== "object")
+        return undefined;
+    const entries = Object.entries(value);
+    for (const [key, val] of entries) {
+        if (typeof val === "string" && keyMatches(key) && /^https?:\/\//.test(val))
+            return val;
+    }
+    for (const [, val] of entries) {
+        const found = searchUrl(val, keyMatches, depth + 1);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Each upstream nests the finished video somewhere different (DashScope puts it
+ * at result.output.video_url, Seedance under result.data[].content[].url), so
+ * search rather than hardcode a path.
+ *
+ * Every pass covers the whole tree before the next one starts, and each is
+ * narrower than a plain "ends in url" match would be. Responses ship thumbnails
+ * and cover images beside the clip, and `thumbnail_url` both ends in "url" and
+ * tends to sit closer to the root than the video does — matching it would make
+ * `--output` download a still image.
+ */
+export function findVideoUrl(value) {
+    // The still-image exclusion applies to every pass: `video_thumbnail_url`
+    // matches the video-named pattern too, and saving it via --output would hand
+    // the user a JPEG with an .mp4 name.
+    return (
+    // 1. Explicitly video-named: output.video_url
+    searchUrl(value, (k) => VIDEO_KEY.test(k) && !NOT_VIDEO_KEY.test(k)) ??
+        // 2. A bare `url`, which is what a media-item object uses: content[].url
+        searchUrl(value, (k) => k.toLowerCase() === "url") ??
+        // 3. Any other *_url, minus the ones that name a still image
+        searchUrl(value, (k) => URL_KEY.test(k) && !NOT_VIDEO_KEY.test(k)));
+}
+function printTask(task, fallbackId) {
+    const url = task.result ? findVideoUrl(task.result) : undefined;
+    console.log(`  Task:   ${task.id || fallbackId}`);
+    console.log(`  Status: ${task.status || "unknown"}`);
+    if (task.model)
+        console.log(`  Model:  ${task.model}`);
+    if (task.progress && !TERMINAL_STATUSES.has(task.status || "")) {
+        console.log(`  Progress: ${task.progress}`);
+    }
+    if (url)
+        console.log(`  URL:    ${chalk.cyan(url)}`);
+    if (task.error?.message)
+        console.log(`  Error:  ${chalk.red(task.error.message)}`);
+}
+async function downloadVideo(url, outputPath) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed: ${res.status}`);
+    const buffer = Buffer.from(await res.arrayBuffer());
+    await writeFile(outputPath, buffer);
+}
+/** Parse `--media first_frame=https://…`, and bare URLs from `--image`. */
+export function parseMedia(specs = [], images = []) {
+    const media = images.map((url) => ({ type: "first_frame", url }));
+    for (const spec of specs) {
+        const eq = spec.indexOf("=");
+        if (eq < 0) {
+            throw new Error(`Invalid --media "${spec}". Use type=url, e.g. first_frame=https://…`);
+        }
+        const type = spec.slice(0, eq);
+        const url = spec.slice(eq + 1);
+        if (!MEDIA_TYPES.includes(type)) {
+            throw new Error(`Unknown media type "${type}". Valid: ${MEDIA_TYPES.join(", ")}`);
+        }
+        if (!url)
+            throw new Error(`Missing URL in --media "${spec}"`);
+        media.push({ type, url });
+    }
+    return media;
+}
+/**
+ * Build the request body for a model's vendor. The gateway rewrites only the
+ * top-level `model` and forwards the rest verbatim, so a Bailian body sent to a
+ * Seedance model is rejected with a 400.
+ */
+export function buildVideoBody(model, prompt, media, options) {
+    const spec = videoModelSpec(model);
+    if (spec.family === "seedance") {
+        // BytePlus takes a multimodal content array rather than input/parameters.
+        return {
+            model,
+            content: [
+                { type: "text", text: prompt },
+                ...media.map((m) => ({ type: "image_url", image_url: { url: m.url } })),
+            ],
+        };
+    }
+    return {
+        model,
+        input: { prompt, ...(media.length > 0 ? { media } : {}) },
+        parameters: {
+            resolution: options.resolution || "720P",
+            duration: options.duration ? parseInt(options.duration) : 5,
+        },
+    };
+}
+/**
+ * Parse a `--body` payload. The option means "send this verbatim", so the model
+ * it names wins over the CLI's default — only an explicit `--model` overrides
+ * it. Anything else would silently redirect a valid request to another model.
+ */
+export function parseBodyOverride(raw, explicitModel) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("--body must be valid JSON");
+    }
+    // JSON.parse accepts null, arrays and numbers; none of them are request bodies.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("--body must be a JSON object");
+    }
+    const body = { ...parsed };
+    if (explicitModel)
+        body.model = explicitModel;
+    else if (!body.model)
+        body.model = DEFAULT_VIDEO_MODEL;
+    return body;
+}
 export async function videoCreateAction(prompt, options) {
     const key = requireApiKey();
+    let body;
+    if (options.body) {
+        // Escape hatch for shapes the CLI does not model; the gateway is a pass-through.
+        try {
+            body = parseBodyOverride(options.body, options.model);
+        }
+        catch (err) {
+            error(err.message);
+            return;
+        }
+    }
+    else {
+        const model = options.model || DEFAULT_VIDEO_MODEL;
+        const spec = videoModelSpec(model);
+        let media;
+        try {
+            media = parseMedia(options.media, options.image);
+        }
+        catch (err) {
+            error(err.message);
+            return;
+        }
+        // Image- and clip-driven models are accepted at submission time and only
+        // fail a minute later, after billing. Refuse before spending anything —
+        // and check for the type the model actually wants, since supplying a
+        // first_clip to an i2v model fails exactly the same way as supplying none.
+        if (spec.requiresMedia && !media.some((m) => m.type === spec.requiresMedia)) {
+            const shorthand = spec.requiresMedia === "first_frame" ? " (or --image <url>)" : "";
+            error(media.length === 0
+                ? `${model} needs source media.`
+                : `${model} needs ${spec.requiresMedia} media, got ${media.map((m) => m.type).join(", ")}.`);
+            hint(`Pass --media ${spec.requiresMedia}=<url>${shorthand}`);
+            return;
+        }
+        if (spec.family === "seedance" && media.length > 0) {
+            hint("Seedance media handling is unverified — use --body if the request is rejected");
+        }
+        body = buildVideoBody(model, prompt, media, options);
+    }
     const spinner = ora("Creating video generation task...").start();
-    const body = {
-        model: options.model || "wan2.6-t2v",
-        input: { prompt },
-        parameters: { resolution: "720P", duration: 5 },
-    };
-    const res = await apiRequest(key, "services/aigc/video-generation/video-synthesis", {
+    const res = await apiRequest(key, "video/generations", {
         method: "POST",
         body,
-        headers: { "X-DashScope-Async": "enable" },
-        domain: true,
     });
     if (!res.success || !res.data) {
         spinner.fail("Failed to create video task");
         error(res.error || "Unknown error");
+        if ((res.error || "").includes("model not found")) {
+            hint(`Available video models: ${Object.keys(VIDEO_MODELS).join(", ")}`);
+        }
         return;
     }
     spinner.stop();
-    const taskId = res.data.output?.task_id || res.data.taskId;
-    if (!taskId) {
-        console.log(formatJson(res.data));
-        return;
-    }
-    success(`Task created: ${taskId}`);
-    if (!options.wait) {
-        console.log(chalk.gray(`  Check status: aisa video status ${taskId}`));
+    const taskId = res.data.id;
+    // --raw changes the output format; it must not cancel work the user asked
+    // for. Only skip polling when nothing was requested beyond submission.
+    if (!options.wait || !taskId) {
+        if (options.raw) {
+            console.log(JSON.stringify(res.data));
+            return;
+        }
+        if (!taskId) {
+            console.log(formatJson(res.data));
+            return;
+        }
+        success(`Task created: ${taskId}`);
+        hint(`Check status: aisa video status ${taskId}`);
         return;
     }
-    // Poll for completion
-    const pollSpinner = ora("Generating video...").start();
-    let status = "PENDING";
-    let lastPollData;
-    while (status === "PENDING" || status === "RUNNING") {
-        await new Promise((r) => setTimeout(r, 5000));
-        const pollRes = await apiRequest(key, "services/aigc/tasks", {
-            query: { task_id: taskId },
-            domain: true,
-        });
+    if (!options.raw)
+        success(`Task created: ${taskId}`);
+    const pollSpinner = options.raw ? undefined : ora("Generating video...").start();
+    const deadline = Date.now() + MAX_WAIT_MS;
+    let task = res.data;
+    while (!TERMINAL_STATUSES.has(task.status || "")) {
+        if (Date.now() > deadline) {
+            pollSpinner?.warn(`Still ${task.status || "pending"} after 15 minutes — giving up on waiting`);
+            if (options.raw)
+                console.log(JSON.stringify(task));
+            else
+                hint(`Check later: aisa video status ${taskId}`);
+            return;
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        const pollRes = await apiRequest(key, `video/generations/${taskId}`);
         if (!pollRes.success || !pollRes.data) {
-            pollSpinner.fail("Failed to check status");
+            pollSpinner?.fail("Failed to check status");
             error(pollRes.error || "Unknown error");
             return;
         }
-        lastPollData = pollRes.data;
-        status = lastPollData.output?.task_status || lastPollData.status || "UNKNOWN";
-        pollSpinner.text = `Generating video... (${status})`;
-    }
-    if (status === "SUCCEEDED" || status === "completed") {
-        pollSpinner.succeed("Video generated!");
-        const videoUrl = lastPollData?.output?.video_url || lastPollData?.resultUrl;
-        if (videoUrl) {
-            console.log(`  URL: ${chalk.cyan(videoUrl)}`);
+        task = pollRes.data;
+        if (pollSpinner) {
+            pollSpinner.text = `Generating video... (${task.status}${task.progress ? ` ${task.progress}` : ""})`;
         }
     }
-    else {
-        pollSpinner.fail(`Video generation failed: ${status}`);
+    const videoUrl = findVideoUrl(task.result);
+    if (task.status !== "completed") {
+        pollSpinner?.fail(`Video generation ${task.status}`);
+        if (options.raw)
+            console.log(JSON.stringify(task));
+        else if (task.error?.message)
+            error(task.error.message);
+        return;
+    }
+    pollSpinner?.succeed("Video generated!");
+    if (options.output) {
+        await download(videoUrl, options.output, options.raw);
+    }
+    if (options.raw) {
+        console.log(JSON.stringify(task));
+        return;
+    }
+    if (videoUrl)
+        console.log(`  URL: ${chalk.cyan(videoUrl)}`);
+    else
+        console.log(formatJson(task.result));
+}
+/** Download to `output`, reporting through a spinner unless output is raw JSON. */
+async function download(videoUrl, output, raw) {
+    if (!videoUrl) {
+        error("No video URL available to download");
+        return;
+    }
+    const spinner = raw ? undefined : ora(`Downloading to ${output}...`).start();
+    try {
+        await downloadVideo(videoUrl, output);
+        spinner?.succeed(`Saved to ${output}`);
+    }
+    catch (err) {
+        const message = `Download failed: ${err.message}`;
+        if (spinner)
+            spinner.fail(message);
+        else
+            error(message);
     }
 }
 export async function videoStatusAction(taskId, options) {
     const key = requireApiKey();
     const spinner = ora("Checking status...").start();
-    const res = await apiRequest(key, "services/aigc/tasks", {
-        query: { task_id: taskId },
-        domain: true,
-    });
+    const res = await apiRequest(key, `video/generations/${taskId}`);
     if (!res.success || !res.data) {
         spinner.fail("Failed to check status");
         error(res.error || "Unknown error");
         return;
     }
     spinner.stop();
+    // --raw selects the output format; it must not skip a requested download.
+    if (options.output) {
+        await download(findVideoUrl(res.data.result), options.output, options.raw);
+    }
     if (options.raw) {
         console.log(JSON.stringify(res.data));
+        return;
     }
-    else {
-        const d = res.data;
-        const status = d.output?.task_status || d.status || "unknown";
-        const id = d.output?.task_id || d.taskId || taskId;
-        const videoUrl = d.output?.video_url || d.resultUrl;
-        console.log(`  Task:   ${id}`);
-        console.log(`  Status: ${status}`);
-        if (videoUrl)
-            console.log(`  URL:    ${chalk.cyan(videoUrl)}`);
-        if (d.request_id)
-            console.log(`  Request: ${chalk.gray(d.request_id)}`);
-    }
+    printTask(res.data, taskId);
 }

package/dist/completion.d.ts

@@ -0,0 +1,26 @@
+import type { Command } from "commander";
+/**
+ * Shell completion.
+ *
+ * The shell scripts are thin: they hand the words typed so far to a hidden
+ * `__complete` subcommand and let the CLI decide. That keeps the command tree in
+ * one place instead of duplicating it into three shell dialects.
+ *
+ * Everything dynamic (provider slugs, skill names, model ids) is read from the
+ * on-disk cache only. A completion that made a network call would hang the
+ * terminal on every Tab press, so a cold cache simply completes nothing.
+ */
+export interface Candidate {
+    value: string;
+    description?: string;
+}
+declare const SHELLS: readonly ["bash", "zsh", "fish"];
+export type Shell = (typeof SHELLS)[number];
+export declare function isShell(value: string): value is Shell;
+/**
+ * Candidates for the position after `words` (which excludes the partial word
+ * currently being typed — the shell filters by prefix itself).
+ */
+export declare function complete(program: Command, words: string[]): Candidate[];
+export declare function completionScript(shell: Shell, binary?: string): string;
+export {};

package/dist/completion.js

@@ -0,0 +1,293 @@
+import { readCache } from "./cache.js";
+import { cacheScope } from "./api.js";
+import { AGENT_DIRS, API_CATEGORIES, COINGECKO_IDS, MCP_CONFIGS, MEDIA_TYPES, VIDEO_MODELS, } from "./constants.js";
+const SHELLS = ["bash", "zsh", "fish"];
+export function isShell(value) {
+    return SHELLS.includes(value);
+}
+// ── Dynamic candidates, all cache-only ───────────────────────────────────────
+function cachedProviders() {
+    return readCache(`catalog/${cacheScope()}/category.json`)?.data.apis || [];
+}
+/**
+ * Slugs usable with `aisa run`. A provider's id is not always its URL slug
+ * (`brave-search` serves `/apis/v1/brave/...`), so prefer the real slug from any
+ * cached detail and fall back to the id.
+ */
+function runSlugs() {
+    const out = new Map();
+    for (const provider of cachedProviders()) {
+        const detail = readCache(`catalog/${cacheScope()}/${provider.id.replace(/[^\w.-]/g, "_")}.json`)?.data.api;
+        const first = detail?.endpoint_groups?.flatMap((g) => g.endpoints || [])[0];
+        const slug = first
+            ? first.path.replace(/^\/apis\/v1\//, "").split("/")[0]
+            : provider.id;
+        out.set(slug, `${provider.endpoint_count} endpoints`);
+    }
+    return [...out].map(([value, description]) => ({ value, description }));
+}
+function providerIds() {
+    return cachedProviders().map((p) => ({
+        value: p.id,
+        description: `${p.endpoint_count} endpoints`,
+    }));
+}
+/** Endpoint paths within one provider, for `aisa run <slug> <TAB>`. */
+function endpointPaths(slug) {
+    for (const provider of cachedProviders()) {
+        const detail = readCache(`catalog/${cacheScope()}/${provider.id.replace(/[^\w.-]/g, "_")}.json`)?.data.api;
+        if (!detail)
+            continue;
+        const endpoints = (detail.endpoint_groups || []).flatMap((g) => g.endpoints || []);
+        const matching = endpoints.filter((e) => e.path.replace(/^\/apis\/v1\//, "").startsWith(`${slug}/`));
+        if (matching.length > 0) {
+            return matching.map((e) => ({
+                value: `/${e.path.replace(/^\/apis\/v1\//, "").split("/").slice(1).join("/")}`,
+                description: e.name,
+            }));
+        }
+    }
+    return [];
+}
+function skillSlugs() {
+    const index = readCache("skills/tree.json")?.data;
+    if (!index)
+        return [];
+    // Leaf names are what install/remove operate on; the canonical slug is the hint.
+    return index.slugs.map((slug) => ({
+        value: slug.split("/").pop(),
+        description: slug,
+    }));
+}
+function skillCategories() {
+    const index = readCache("skills/tree.json")?.data;
+    if (!index)
+        return [];
+    return [...new Set(index.slugs.map((s) => s.split("/")[0]))].map((value) => ({ value }));
+}
+function modelIds() {
+    const models = readCache(`models/${cacheScope()}.json`)?.data;
+    return (models || []).map((m) => ({ value: m.id, description: m.owned_by }));
+}
+// ── Static candidate sets ────────────────────────────────────────────────────
+const STATIC = {
+    agent: Object.keys(AGENT_DIRS).concat("all").map((value) => ({ value })),
+    mcpAgent: Object.keys(MCP_CONFIGS).concat("all").map((value) => ({ value })),
+    lang: ["curl", "python", "node", "typescript"].map((value) => ({ value })),
+    searchType: [
+        { value: "tavily" },
+        { value: "youtube" },
+        { value: "scholar" },
+        { value: "smart", description: "currently degraded" },
+        { value: "full", description: "currently degraded" },
+    ],
+    stockField: [
+        "info",
+        "estimates",
+        "financials",
+        "filings",
+        "insider",
+        "institutional",
+        "news",
+    ].map((value) => ({ value })),
+    configKey: ["defaultModel", "baseUrl", "outputFormat", "twitterCookies", "twitterProxy"].map((value) => ({ value })),
+    template: ["default", "llm", "search", "finance", "twitter", "video"].map((value) => ({ value })),
+    videoModel: Object.entries(VIDEO_MODELS).map(([value, spec]) => ({
+        value,
+        description: spec.requiresMedia ? `needs --media ${spec.requiresMedia}` : undefined,
+    })),
+    mediaType: MEDIA_TYPES.map((value) => ({ value: `${value}=` })),
+    apiCategory: API_CATEGORIES.map((value) => ({ value })),
+    period: ["current", "1d", "7d", "30d", "90d", "1y"].map((value) => ({ value })),
+    cryptoSource: ["coingecko", "financial"].map((value) => ({ value })),
+    shell: SHELLS.map((value) => ({ value })),
+    crypto: Object.keys(COINGECKO_IDS).map((value) => ({
+        value: value.toUpperCase(),
+        description: COINGECKO_IDS[value],
+    })),
+};
+/**
+ * Values for an option that takes an argument, keyed by "command path --option".
+ * Matched longest-prefix-first so `skills install --agent` and `mcp setup
+ * --agent` can differ.
+ */
+const OPTION_VALUES = [
+    ["mcp setup --agent", () => STATIC.mcpAgent],
+    ["skills --agent", () => STATIC.agent],
+    ["skills list --category", () => skillCategories()],
+    ["skills init --template", () => STATIC.template],
+    ["api list --category", () => STATIC.apiCategory],
+    ["api search --provider", () => providerIds()],
+    ["api code --lang", () => STATIC.lang],
+    ["code --lang", () => STATIC.lang],
+    ["video create --model", () => STATIC.videoModel],
+    ["video create --media", () => STATIC.mediaType],
+    ["chat --model", () => modelIds()],
+    ["web-search --type", () => STATIC.searchType],
+    ["stock --field", () => STATIC.stockField],
+    ["crypto --period", () => STATIC.period],
+    ["crypto --source", () => STATIC.cryptoSource],
+    ["models --provider", () => [...new Set(modelIds().map((m) => m.description))].filter(Boolean).map((value) => ({ value: value }))],
+];
+/**
+ * Positional-argument candidates, keyed by command path and argument index.
+ * Callbacks receive the positionals parsed so far — never the raw word list,
+ * whose last entry may be an option or an option's value
+ * (`run financial --raw <TAB>`).
+ */
+const POSITIONAL = [
+    ["run", 0, () => runSlugs()],
+    ["run", 1, (positionals) => endpointPaths(positionals[0])],
+    ["api show", 0, () => providerIds()],
+    ["api code", 0, () => runSlugs()],
+    ["api code", 1, (positionals) => endpointPaths(positionals[0])],
+    ["code", 0, () => runSlugs()],
+    ["models show", 0, () => modelIds()],
+    ["skills show", 0, () => skillSlugs()],
+    ["skills install", 0, () => skillSlugs()],
+    ["skills remove", 0, () => skillSlugs()],
+    ["crypto", 0, () => STATIC.crypto],
+    ["config set", 0, () => STATIC.configKey],
+    ["config get", 0, () => STATIC.configKey],
+    ["completion", 0, () => STATIC.shell],
+];
+// ── Command tree walking ─────────────────────────────────────────────────────
+function visibleSubcommands(cmd) {
+    return cmd.commands.filter((c) => !c._hidden && !c.name().startsWith("__"));
+}
+/**
+ * The subcommand commander runs when none is named — `aisa models --provider x`
+ * is really `aisa models list --provider x`, so its options belong to the parent
+ * position too.
+ */
+function defaultSubcommand(cmd) {
+    const name = cmd._defaultCommandName;
+    return name ? visibleSubcommands(cmd).find((c) => c.name() === name) : undefined;
+}
+/** The commands whose options apply at this position: the command, plus its default child. */
+function optionScope(cmd) {
+    const fallback = defaultSubcommand(cmd);
+    return fallback ? [cmd, fallback] : [cmd];
+}
+function optionCandidates(cmd) {
+    const out = [];
+    const seen = new Set();
+    for (const scoped of optionScope(cmd)) {
+        for (const option of scoped.options) {
+            if (option.hidden || !option.long || seen.has(option.long))
+                continue;
+            seen.add(option.long);
+            out.push({ value: option.long, description: option.description });
+        }
+    }
+    out.push({ value: "--help", description: "display help" });
+    return out;
+}
+function findOption(cmd, flag) {
+    for (const scoped of optionScope(cmd)) {
+        const option = scoped.options.find((o) => o.long === flag || o.short === flag);
+        if (option)
+            return option;
+    }
+    return undefined;
+}
+function takesValue(cmd, flag) {
+    const option = findOption(cmd, flag);
+    return Boolean(option && (option.required || option.optional));
+}
+/**
+ * Candidates for the position after `words` (which excludes the partial word
+ * currently being typed — the shell filters by prefix itself).
+ */
+export function complete(program, words) {
+    let cmd = program;
+    const path = [];
+    const positionals = [];
+    let i = 0;
+    // Walk down the command tree, collecting positional args along the way.
+    for (; i < words.length; i++) {
+        const word = words[i];
+        if (word.startsWith("-"))
+            break;
+        const child = visibleSubcommands(cmd).find((c) => c.name() === word || c.aliases().includes(word));
+        if (!child)
+            break;
+        cmd = child;
+        path.push(child.name());
+    }
+    // Remaining words are options and positional arguments.
+    for (; i < words.length; i++) {
+        const word = words[i];
+        if (word.startsWith("-")) {
+            if (takesValue(cmd, word)) {
+                // The word being typed is this option's value.
+                if (i === words.length - 1) {
+                    const key = `${path.join(" ")} ${word}`;
+                    const match = OPTION_VALUES.filter(([prefix]) => {
+                        const [prefixPath, prefixFlag] = [
+                            prefix.slice(0, prefix.lastIndexOf(" ")),
+                            prefix.slice(prefix.lastIndexOf(" ") + 1),
+                        ];
+                        return prefixFlag === word && key.startsWith(prefixPath);
+                    }).sort((a, b) => b[0].length - a[0].length)[0];
+                    return match ? match[1]() : [];
+                }
+                i++; // skip the value
+            }
+            continue;
+        }
+        positionals.push(word);
+    }
+    const commandPath = path.join(" ");
+    const subcommands = visibleSubcommands(cmd).map((c) => ({
+        value: c.name(),
+        description: c.description(),
+    }));
+    const positional = POSITIONAL.filter(([prefix, index]) => prefix === commandPath && index === positionals.length)
+        .flatMap(([, , produce]) => produce(positionals))
+        .filter(Boolean);
+    return [...subcommands, ...positional, ...optionCandidates(cmd)];
+}
+// ── Shell scripts ────────────────────────────────────────────────────────────
+export function completionScript(shell, binary = "aisa") {
+    switch (shell) {
+        case "bash":
+            return `# aisa bash completion
+# Install:  aisa completion bash > /usr/local/etc/bash_completion.d/aisa
+#      or:  eval "$(aisa completion bash)"
+_${binary}_complete() {
+  local cur words
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  words=("\${COMP_WORDS[@]:1:COMP_CWORD-1}")
+  local candidates
+  candidates=$(${binary} __complete -- "\${words[@]}" 2>/dev/null | cut -f1)
+  COMPREPLY=($(compgen -W "\${candidates}" -- "\${cur}"))
+}
+complete -o default -F _${binary}_complete ${binary}
+`;
+        case "zsh":
+            return `#compdef ${binary}
+# aisa zsh completion
+# Install:  aisa completion zsh > "\${fpath[1]}/_aisa"
+#      or:  eval "$(aisa completion zsh)"
+_${binary}() {
+  local -a candidates
+  local -a prior
+  prior=(\${words[2,CURRENT-1]})
+  # Output is "value<TAB>description"; _describe wants "value:description".
+  candidates=(\${(f)"$(${binary} __complete -- \${prior} 2>/dev/null | sed 's/\\t/:/')"})
+  _describe -t commands '${binary}' candidates
+}
+compdef _${binary} ${binary}
+`;
+        case "fish":
+            return `# aisa fish completion
+# Install:  aisa completion fish > ~/.config/fish/completions/aisa.fish
+function __${binary}_complete
+  set -l tokens (commandline -opc)
+  ${binary} __complete -- $tokens[2..-1] 2>/dev/null
+end
+complete -c ${binary} -f -a '(__${binary}_complete)'
+`;
+    }
+}