Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor CLI tool descriptions and improve input validation

konstantin-paulusd5a298f004ab
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 5ca06ffa..167c6cf9 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -8,7 +8,7 @@ import { isAbsolute, resolve } from "node:path";
import { Command } from "commander";
import { z } from "zod";
import { version } from "../../../package.json";
-import { ISSUE_LOG_TAIL, toolByName } from "@diffusionstudio/dapi";
+import { toolByName } from "@diffusionstudio/dapi";
import { MCP_URL } from "@diffusionstudio/dapi/socket";
import { APP_NAME, call, isAppDown, launchApp, ping, waitForApp } from "./cli-client";
import { runProxy } from "./mcp-proxy";
@@ -30,16 +30,12 @@ function describe(name: ToolName): string {
return toolByName(name).description;
}
-/**
- * An input field's description, for the option that maps onto it. The
- * fallback is for the shared window fields (`start`, `end`), which the
- * catalog leaves for each wrapper to word.
- */
-function field(name: ToolName, key: string, fallback?: string): string {
+/** An input field's description, verbatim, for the option that maps onto it. */
+function field(name: ToolName, key: string): string {
const tool: GenericTool = toolByName(name);
const schema = tool.input.shape[key];
- if (schema === undefined && fallback === undefined) throw new Error(`tool ${name} has no input field "${key}"`);
- return schema?.description ?? fallback ?? "";
+ if (schema === undefined) throw new Error(`tool ${name} has no input field "${key}"`);
+ return schema.description ?? "";
}
/**
@@ -166,8 +162,8 @@ media
.option("-t, --times <time...>", field("media_grab", "times"))
.option("-c, --count <n>", field("media_grab", "count"), numeric)
.option("-a, --auto", field("media_grab", "auto"))
- .option("-s, --start <time>", field("media_grab", "start", `with --count or --auto, start of the window to sample (seconds, "45f" frames, or "MM:SS"; default: 0)`))
- .option("-e, --end <time>", field("media_grab", "end", `with --count or --auto, end of the window to sample (seconds, "45f" frames, or "MM:SS"; default: asset duration)`))
+ .option("-s, --start <time>", field("media_grab", "start"))
+ .option("-e, --end <time>", field("media_grab", "end"))
.option("-q, --quality <preset>", field("media_grab", "quality"))
.option("-S, --separate", field("media_grab", "separate"))
.option("--per-sheet <n>", field("media_grab", "perSheet"), numeric)
@@ -182,8 +178,8 @@ media
.alias("film")
.description(describe("media_filmstrip"))
.argument("<path>", field("media_filmstrip", "path"))
- .option("-s, --start <time>", field("media_filmstrip", "start", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`))
- .option("-e, --end <time>", field("media_filmstrip", "end", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`))
+ .option("-s, --start <time>", field("media_filmstrip", "start"))
+ .option("-e, --end <time>", field("media_filmstrip", "end"))
.option("-x, --scale <factor>", field("media_filmstrip", "scale"), numeric)
.option("-o, --output <path>", field("media_filmstrip", "output"))
.action((ref: string, opts: Omit<ToolInput<"media_filmstrip">, "path">) =>
@@ -195,8 +191,8 @@ media
.alias("wave")
.description(describe("media_waveform"))
.argument("<path>", field("media_waveform", "path"))
- .option("-s, --start <time>", field("media_waveform", "start", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`))
- .option("-e, --end <time>", field("media_waveform", "end", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`))
+ .option("-s, --start <time>", field("media_waveform", "start"))
+ .option("-e, --end <time>", field("media_waveform", "end"))
.option("-x, --scale <factor>", field("media_waveform", "scale"), numeric)
.option("-o, --output <path>", field("media_waveform", "output"))
.action((ref: string, opts: Omit<ToolInput<"media_waveform">, "path">) =>
@@ -232,7 +228,7 @@ program
.command("logs")
.description(describe("logs"))
.option("-n, --tail <n>", field("logs", "tail"), numeric)
- .option("-l, --level <level>", `${field("logs", "level")}: "debug", "info", "warning", or "error"`)
+ .option("-l, --level <level>", field("logs", "level"))
.action((opts: ToolInput<"logs">) => run("logs", opts));
program
@@ -247,16 +243,16 @@ program
.description(describe("report"))
.argument("<title>", field("report", "title"))
.option("-b, --body <text>", field("report", "body"))
- .option("-c, --commands <cmd...>", `${field("report", "commands")}; repeatable`)
- .option("--logs <n>", field("report", "logs", `trailing app log entries to attach (0 to omit; default: ${ISSUE_LOG_TAIL})`), numeric)
+ .option("-c, --commands <cmd...>", field("report", "commands"))
+ .option("--logs <n>", field("report", "logs"), numeric)
.action((title: string, opts: Omit<ToolInput<"report">, "title">) => run("report", { title, ...opts }));
program
.command("fonts")
.description(describe("fonts"))
.option("-f, --family <pattern>", field("fonts", "family"))
- .option("-w, --weights <weights...>", `${field("fonts", "weights")}, e.g. -w 400 700`)
- .option("-s, --style <style>", `${field("fonts", "style")}: "normal" or "italic"`)
+ .option("-w, --weights <weights...>", field("fonts", "weights"))
+ .option("-s, --style <style>", field("fonts", "style"))
.option("-l, --limit <n>", field("fonts", "limit"), numeric)
.action((opts: ToolInput<"fonts">) => run("fonts", opts));
diff --git a/packages/dapi/src/schemas.ts b/packages/dapi/src/schemas.ts
index ae9e4103..0e52cd3d 100644
--- a/packages/dapi/src/schemas.ts
+++ b/packages/dapi/src/schemas.ts
@@ -6,7 +6,7 @@
// here is a tool on its own.
import { z } from "zod";
-import { NonNegativeTime } from "./time";
+import { NonNegativeTime, TIME_FORMS } from "./time";
export const NodeId = z
.string()
@@ -87,8 +87,8 @@ export function checkSheetOptions(
/** A `[start, end)` window in seconds; both optional, and start must precede end. */
export const windowFields = {
- start: NonNegativeTime.optional(),
- end: NonNegativeTime.optional(),
+ start: NonNegativeTime.optional().describe(`start of the window — ${TIME_FORMS} (default: 0)`),
+ end: NonNegativeTime.optional().describe(`end of the window — ${TIME_FORMS} (default: asset duration)`),
};
export function checkWindow(
diff --git a/packages/dapi/src/tools/fonts.ts b/packages/dapi/src/tools/fonts.ts
index e6bdd994..e725d0f2 100644
--- a/packages/dapi/src/tools/fonts.ts
+++ b/packages/dapi/src/tools/fonts.ts
@@ -26,7 +26,7 @@ export const fonts = defineTool({
input: z.object({
family: z.string().optional().describe("filter to families whose name contains this (case-insensitive)"),
weights: z.array(z.string()).optional().describe('filter to variants with the given CSS weights, e.g. ["400", "700"]'),
- style: FontStyle.optional().describe("filter to variants with the given style"),
+ style: FontStyle.optional().describe("filter to variants with the given style, normal or italic"),
limit: z.int().min(1).optional().describe("return at most this many families"),
}),
output: z.object({ families: z.array(FontFamily) }),
diff --git a/packages/dapi/src/tools/logs.ts b/packages/dapi/src/tools/logs.ts
index 6e63ed8a..a9e02d6e 100644
--- a/packages/dapi/src/tools/logs.ts
+++ b/packages/dapi/src/tools/logs.ts
@@ -13,7 +13,7 @@ export const logs = defineTool({
"Recent console output from the running app (what the devtools console shows: page logs, worker logs, uncaught errors), oldest first. The app buffers the last 2000 entries across reloads and project switches, so this replaces relaunching with ELECTRON_ENABLE_LOGGING=1 when debugging renderer-side behavior.",
input: z.object({
tail: z.int().min(1).optional().describe("return only the last n entries"),
- level: LogLevel.optional().describe("minimum level to include"),
+ level: LogLevel.optional().describe("minimum level to include: debug, info, warning, or error"),
}),
output: z.object({ entries: z.array(LogEntry) }),
runsIn: "main",
diff --git a/packages/dapi/src/tools/media-grab.ts b/packages/dapi/src/tools/media-grab.ts
index 9e9f8eac..8b22144b 100644
--- a/packages/dapi/src/tools/media-grab.ts
+++ b/packages/dapi/src/tools/media-grab.ts
@@ -37,7 +37,8 @@ export const mediaGrab = defineTool({
.describe(
"scan the clip at 2fps and keep a frame each time the footage settles into a new visual state (transitions are waited out, so picks stay sharp); returns at most count frames (default cap: 30), static footage like screen recordings returns far fewer; requires WebGPU",
),
- ...windowFields,
+ start: windowFields.start.describe("with count or auto, start of the window to sample (default: 0)"),
+ end: windowFields.end.describe("with count or auto, end of the window to sample (default: asset duration)"),
quality: FrameQuality.optional().describe(
"frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with separate: true",
),
diff --git a/packages/dapi/src/tools/models.ts b/packages/dapi/src/tools/models.ts
index ca2cc8ce..74958e34 100644
--- a/packages/dapi/src/tools/models.ts
+++ b/packages/dapi/src/tools/models.ts
@@ -22,7 +22,7 @@ export const models = defineTool({
description:
"List available AI generation models and their per-model constraints (durations, aspect ratios, features), for `generate.*` asset declarations in a project module.",
input: z.object({
- type: ModelType.optional().describe("filter to one kind of model (default: all three)"),
+ type: ModelType.optional().describe("filter to one kind of model, image, video, or audio (default: all three)"),
}),
output: z.object({ models: z.array(ModelInfo) }),
runsIn: "renderer",