{"protocol":"clank-doc/1","frameworkVersion":"0.19.5","slug":"workbench","title":"App Studio and the developer workbench","description":"Clank's AI first workflow has two deliberate halves. App Studio turns application intent into an exact approval bound generated plan. The workbench inspects and tests that app without hidden services or package hooks.","group":{"id":"agents","title":"Agents and generation"},"url":"https://docs.clank.run/docs/workbench","source":"docs/workbench.md","headings":["Conversational App Studio","Production parity and database evolution","Contract generated tests and agent playground","Visual regression","Upgrade assistant","Provider conformance kit","Shared control plane design system"],"tableOfContents":[{"id":"conversational-app-studio","title":"Conversational App Studio","level":2},{"id":"production-parity-and-database-evolution","title":"Production parity and database evolution","level":2},{"id":"contract-generated-tests-and-agent-playground","title":"Contract-generated tests and agent playground","level":2},{"id":"visual-regression","title":"Visual regression","level":2},{"id":"upgrade-assistant","title":"Upgrade assistant","level":2},{"id":"provider-conformance-kit","title":"Provider conformance kit","level":2},{"id":"shared-control-plane-design-system","title":"Shared control-plane design system","level":2}],"markdown":"# App Studio and the developer workbench\n\nClank's AI-first workflow has two deliberate halves. App Studio turns application intent into an\nexact approval-bound generated plan. The workbench inspects and tests that app without hidden\nservices or package hooks.\n\n## Conversational App Studio\n\n`clank compose` is the interactive Studio: an agent proposes a data-only blueprint, Clank validates\nit, and a person approves the exact generated-file digest. `createStudioReview()` exposes the same\ncontract to browser tools.\n\n```ts\nimport { createStudioReview } from \"@clank.run/framework/tooling\";\n\nconst review = await createStudioReview({\n  intent: \"Build a private realtime Todoist-style app\",\n  blueprint: proposedBlueprint,\n  questions: [\"Should completed work be retained forever?\"],\n});\n```\n\nThe review does not execute code, install, authenticate, or deploy. Its `approvalDigest` is the\nordinary `clank-plan/1` digest, so browser Studio and CLI composition cannot disagree.\n\n## Production parity and database evolution\n\n```sh\nclank workbench parity local-runtime.json production-runtime.json --json\nclank workbench schema schema-current.json schema-target.json \\\n  --output=0004_todo_labels.sql --json\n```\n\nParity compares Node, database, isolation, region, environment names, migrations, and service\ncapabilities without secret values. Node, database, and migration differences are errors.\n\nThe schema workbench labels every table, column, type, nullability, default, and index change as\nsafe, review, or destructive. A required column without a default needs review; dropping data is\ndestructive; type changes produce an explicit rebuild placeholder. Output migrations are created\nexclusively and owner-readable.\n\n## Contract-generated tests and agent playground\n\n`testActionContract()` generates valid, null, and missing-required-field cases from an action's\nreal JSON schema and executes its normal parser and handler.\n\n```ts\nconst report = await testActionContract(todos.add, { user });\n\nconst playground = createAgentPlayground([todos.list, todos.add], {\n  authorize: (call, action) => policyAllows(call.principal, action.manifest.name),\n});\n\nconst transcript = await playground.call({\n  action: \"todos.add\",\n  input: { title: \"Ship\" },\n  principal: \"agent_codex\",\n  scopes: [\"agent:write\"],\n});\n```\n\nPlayground transcripts are bounded and redact password, token, secret, authorization, and cookie\nkeys. Production MCP still uses resource-bound OAuth and server authorization.\n\n## Visual regression\n\n`compareVisuals()` compares decoded RGBA screenshots with channel tolerance, a changed-pixel ratio,\nand explicit ignored rectangles. Pair it with semantic `clank journey`: journeys prove behavior\nand accessibility state; pixels catch layout, spacing, color, radius, and typography changes. The\ndependency-free CLI accepts bounded, checksummed 8-bit RGB or RGBA PNG screenshots directly:\n\n```sh\nclank workbench visual test/baselines/home.png artifacts/home.png \\\n  --tolerance=4 --ratio=0.001 --json\n```\n\nA mismatch exits nonzero for CI. Decoding rejects malformed chunks, unsupported image modes,\ncompressed payloads over 16 MiB, and images over 16,777,216 pixels.\n\n## Upgrade assistant\n\n```sh\nclank workbench upgrade clank-upgrade.json \\\n  --node=22 --exports=oldRouter,legacyApi --json\n```\n\nUpgrade manifests declare versions, minimum Node, removed/renamed exports, config edits, and\nmigration notes. Renames are mechanical edits; an old runtime or an in-use removed export without\na replacement is a blocker.\n\n## Provider conformance kit\n\n```sh\nclank workbench provider ./my-provider.mjs --json\n```\n\nThe kit validates provider shape, frozen credential-free stopped requests, exact-operation\nidempotency, and abortable deadlines. Missing optional capabilities are skipped. Rollback and\ndelete are also skipped unless you explicitly use a disposable provider project:\n\n```sh\nclank workbench provider ./my-provider.mjs \\\n  --project=disposable-conformance-project --destructive=true --json\n```\n\nThat opt-in exercises advertised rollback/delete capabilities with canonical confirmations and\ncan destroy the named provider project. Provider-specific crash and isolation tests remain\nrequired.\n\n## Shared control-plane design system\n\nThe hosted control plane consumes the same `clank` theme preset exposed by Design Studio. Its\ncanvas, surfaces, text, borders, accent, danger, radius, and shadow map from stable `--clank-*`\ntokens during SSR. Applications can use any of ten presets or define a validated custom theme.\n"}