@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/node_modules/@engenty-wizards/shared/dist/translation.js

@@ -0,0 +1,154 @@
+/**
+ * A wizard translated for its viewer, on request: what the person reads is written in their
+ * language, what the wizard runs on stays as the author wrote it. Never translated: ids,
+ * branches and their statements, the instructions of AI steps, `{{…}}` placeholders, and the
+ * values of choices — a choice shows a translated label and keeps its value.
+ */
+/** Fields whose `options` are choices the person reads (a slot's are dates, written by the runner). */
+function choiceField(field) {
+    return field.kind === "select" || field.kind === "multiselect";
+}
+/** Every text of a definition the person reads, with the way to write it back. */
+function visitTexts(def, visit, choices) {
+    visit(def.title, (t) => {
+        def.title = t;
+    });
+    visit(def.description, (t) => {
+        def.description = t;
+    });
+    visit(def.intro, (t) => {
+        def.intro = t;
+    });
+    for (const list of def.lists ?? []) {
+        visit(list.title, (t) => {
+            list.title = t;
+        });
+        visit(list.description, (t) => {
+            list.description = t;
+        });
+        for (const column of list.columns ?? []) {
+            visit(column.name, (t) => {
+                column.name = t;
+            });
+            const options = ("format" in column
+                ? column.format
+                : undefined)?.options;
+            for (const option of options ?? []) {
+                visit(option.label, (t) => {
+                    option.label = t;
+                });
+            }
+        }
+    }
+    for (const connection of def.connections ?? []) {
+        visit(connection.title, (t) => {
+            connection.title = t;
+        });
+        visit(connection.description, (t) => {
+            connection.description = t;
+        });
+    }
+    for (const step of def.steps) {
+        visit(step.title, (t) => {
+            step.title = t;
+        });
+        visit(step.description, (t) => {
+            step.description = t;
+        });
+        if ("working" in step) {
+            visit(step.working, (t) => {
+                step.working = t;
+            });
+        }
+        // What an AI step's output fields hold: the headings a review and the result show them under.
+        if (step.type === "agent") {
+            for (const field of step.output?.fields ?? []) {
+                visit(field.description, (t) => {
+                    field.description = t;
+                });
+            }
+        }
+        if (step.type === "page") {
+            visit(step.cta, (t) => {
+                step.cta = t;
+            });
+            for (const field of step.fields) {
+                visit(field.label, (t) => {
+                    field.label = t;
+                });
+                visit(field.help, (t) => {
+                    field.help = t;
+                });
+                visit(field.placeholder, (t) => {
+                    field.placeholder = t;
+                });
+                for (const column of field.columns ?? []) {
+                    visit(column.label, (t) => {
+                        column.label = t;
+                    });
+                }
+                if (choiceField(field)) {
+                    for (const option of field.options ?? []) {
+                        choices(option, () => undefined);
+                    }
+                }
+            }
+        }
+        if (step.type === "result") {
+            visit(step.message, (t) => {
+                step.message = t;
+            });
+            for (const deliverable of step.deliverables) {
+                visit(deliverable.label, (t) => {
+                    deliverable.label = t;
+                });
+            }
+        }
+    }
+}
+/** The texts of a definition the person reads, each once, in the order they appear. */
+export function wizardTexts(def) {
+    const seen = new Set();
+    const add = (text) => {
+        if (text?.trim()) {
+            seen.add(text);
+        }
+    };
+    visitTexts(structuredClone(def), add, add);
+    return [...seen];
+}
+/** `{{…}}` placeholders and `{name}` gaps: what a translation keeps exactly. */
+const KEPT = /\{\{[^}]*\}\}|\{\w+\}/g;
+/** Whether a translated text keeps every placeholder and gap of its original, no more, no fewer. */
+export function keepsPlaceholders(original, translated) {
+    const of = (text) => (text.match(KEPT) ?? []).sort().join("\u0000");
+    return of(original) === of(translated);
+}
+/** The texts of a definition a translation does not have yet. */
+export function missingTexts(def, memory) {
+    return wizardTexts(def).filter((text) => !memory[text]);
+}
+/**
+ * The definition in the viewer's language: a copy with every text the memory has written in,
+ * and the labels of the choices beside it (`labels[value]`), the values untouched.
+ */
+export function translateDefinition(def, memory) {
+    const copy = structuredClone(def);
+    const labels = {};
+    visitTexts(copy, (text, write) => {
+        const entry = text ? memory[text] : undefined;
+        if (entry) {
+            write(entry.text);
+        }
+    }, (value) => {
+        const entry = value ? memory[value] : undefined;
+        if (value && entry) {
+            labels[value] = entry.text;
+        }
+    });
+    return { def: copy, labels };
+}
+/** Whether every text of the memory came from the author, or some from a model. */
+export function machineTranslated(memory, def) {
+    return wizardTexts(def).some((text) => memory[text]?.by !== "author");
+}

package/node_modules/@engenty-wizards/shared/dist/wizard-package.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+/**
+ * A wizard as a file, `<title>.wizard`: a zip with `wizard.json` — the definition and what it
+ * needs from its project — and the workspace under `files/`. What belongs to people (runs, lists, connected
+ * accounts) and to the project (brand, credentials) stays where it is.
+ */
+export declare const PACKAGE_FORMAT = "engenty-wizard";
+export declare const PACKAGE_MANIFEST = "wizard.json";
+export declare const PACKAGE_FILES = "files/";
+export declare const PACKAGE_EXTENSION = ".wizard";
+/** A type of its own: under `application/zip` a browser may save the file as `.zip`. */
+export declare const PACKAGE_MIME = "application/vnd.engenty.wizard+zip";
+/** The workspace's 25 MB, with room for the manifest and the zip's own overhead. */
+export declare const PACKAGE_MAX_BYTES = 30000000;
+/**
+ * Where the JSON Schemas of both are published (the docs site's public folder, written by
+ * `pnpm schema`, answered at engenty.ai/schema/…). One folder per definition version: a breaking
+ * change adds the next and keeps the old. The package's schema holds the definition's, so it sits
+ * beside it.
+ */
+export declare const SCHEMA_BASE_URL: string;
+export declare const WIZARD_SCHEMA_URL: string;
+export declare const PACKAGE_SCHEMA_URL: string;
+export declare const manifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    format: z.ZodLiteral<"engenty-wizard">;
+    version: z.ZodLiteral<1>;
+    exportedAt: z.ZodOptional<z.ZodString>;
+    definition: z.ZodUnknown;
+    connectors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodOptional<z.ZodString>;
+        sourceKind: z.ZodOptional<z.ZodEnum<{
+            mcp: "mcp";
+            openapi: "openapi";
+        }>>;
+    }, z.core.$strip>>>;
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        pages: z.ZodNumber;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Manifest = z.infer<typeof manifestSchema>;

package/node_modules/@engenty-wizards/shared/dist/wizard-package.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { DEFINITION_VERSION } from "./definition.js";
+/**
+ * A wizard as a file, `<title>.wizard`: a zip with `wizard.json` — the definition and what it
+ * needs from its project — and the workspace under `files/`. What belongs to people (runs, lists, connected
+ * accounts) and to the project (brand, credentials) stays where it is.
+ */
+export const PACKAGE_FORMAT = "engenty-wizard";
+export const PACKAGE_MANIFEST = "wizard.json";
+export const PACKAGE_FILES = "files/";
+export const PACKAGE_EXTENSION = ".wizard";
+/** A type of its own: under `application/zip` a browser may save the file as `.zip`. */
+export const PACKAGE_MIME = "application/vnd.engenty.wizard+zip";
+/** The workspace's 25 MB, with room for the manifest and the zip's own overhead. */
+export const PACKAGE_MAX_BYTES = 30_000_000;
+/**
+ * Where the JSON Schemas of both are published (the docs site's public folder, written by
+ * `pnpm schema`, answered at engenty.ai/schema/…). One folder per definition version: a breaking
+ * change adds the next and keeps the old. The package's schema holds the definition's, so it sits
+ * beside it.
+ */
+export const SCHEMA_BASE_URL = `https://engenty.ai/schema/v${DEFINITION_VERSION}`;
+export const WIZARD_SCHEMA_URL = `${SCHEMA_BASE_URL}/wizard.json`;
+export const PACKAGE_SCHEMA_URL = `${SCHEMA_BASE_URL}/wizard-package.json`;
+export const manifestSchema = z.object({
+    /** The JSON Schema an editor checks the file against; the app does not read it. */
+    $schema: z.string().optional(),
+    format: z.literal(PACKAGE_FORMAT),
+    version: z.literal(1),
+    exportedAt: z.string().optional(),
+    definition: z.unknown(),
+    /** Imported connectors the wizard's connections name. No address: one pasted by hand can hold a secret. */
+    connectors: z
+        .array(z.object({
+        id: z.string().max(60),
+        name: z.string().max(120),
+        domain: z.string().max(253).optional(),
+        sourceKind: z.enum(["openapi", "mcp"]).optional(),
+    }))
+        .max(50)
+        .default([]),
+    /** Project MCP servers the wizard's steps name — by name only, their address and headers are credentials. */
+    mcpServers: z
+        .array(z.object({ id: z.string().max(31), name: z.string().max(60) }))
+        .max(10)
+        .default([]),
+    /** The project's pages under `files/knowledge/`, when they were asked for: how many, and whether the cap cut some. */
+    knowledge: z.object({ pages: z.number().int(), truncated: z.boolean() }).optional(),
+});

package/node_modules/@engenty-wizards/shared/dist/workspace.d.ts

@@ -0,0 +1,16 @@
+/** A file in a wizard's workspace. The content lives in the blob store under its hash. */
+export interface WorkspaceFile {
+    path: string;
+    hash: string;
+    mime: string;
+    size: number;
+}
+export declare const WORKSPACE_LIMITS: {
+    fileBytes: number;
+    totalBytes: number;
+    files: number;
+};
+/** Relative, forward slashes, no `..`, no hidden files. Returns the normalised path or null. */
+export declare function cleanPath(raw: string): string | null;
+export declare function mimeForPath(path: string): string;
+export declare function isTextMime(mime: string): boolean;

package/node_modules/@engenty-wizards/shared/dist/workspace.js

@@ -0,0 +1,51 @@
+export const WORKSPACE_LIMITS = {
+    fileBytes: 5_000_000,
+    totalBytes: 25_000_000,
+    files: 200,
+};
+const PATH_RE = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/;
+/** Relative, forward slashes, no `..`, no hidden files. Returns the normalised path or null. */
+export function cleanPath(raw) {
+    const path = raw.trim().replace(/^\.?\/+/, "");
+    if (path.length > 200 || !PATH_RE.test(path) || path.split("/").some((p) => p === "..")) {
+        return null;
+    }
+    return path;
+}
+const MIME_BY_EXT = {
+    html: "text/html",
+    htm: "text/html",
+    js: "text/javascript",
+    mjs: "text/javascript",
+    css: "text/css",
+    json: "application/json",
+    geojson: "application/geo+json",
+    csv: "text/csv",
+    txt: "text/plain",
+    md: "text/markdown",
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    pdf: "application/pdf",
+};
+export function mimeForPath(path) {
+    const ext = path.split(".").pop()?.toLowerCase() ?? "";
+    return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+export function isTextMime(mime) {
+    return (mime.startsWith("text/") ||
+        mime === "application/json" ||
+        mime === "application/geo+json" ||
+        mime === "image/svg+xml");
+}

package/node_modules/@engenty-wizards/shared/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@engenty-wizards/shared",
+  "version": "0.1.0",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "exports": {
+    "./engenty/data-tables": "./dist/engenty/data-tables/index.js",
+    "./*": "./dist/*.js"
+  }
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@engenty/wizards-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.5",
+  "description": "Make a wish. Get your wizard. It guides you step by step. Let AI do the work. Runs on your machine, on the AI subscription you already have. The runtime, which `npx wizards` installs.",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://engenty.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/engenty/wizards.git"
+  },
+  "type": "module",
+  "bin": {
+    "wizards": "bin/wizards.mjs"
+  },
+  "engines": {
+    "node": ">=24.11"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "apps",
+    "bin",
+    "modules",
+    "plugin"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "4.0.54",
+    "@ai-sdk/elevenlabs": "3.0.42",
+    "@ai-sdk/fal": "3.0.42",
+    "@ai-sdk/gateway": "4.0.82",
+    "@ai-sdk/google": "4.0.72",
+    "@ai-sdk/openai": "4.0.67",
+    "@ai-sdk/replicate": "3.0.42",
+    "@clack/prompts": "1.8.1",
+    "@engenty-wizards/shared": "0.1.0",
+    "@engenty/wizards": "0.1.0",
+    "@executor-js/plugin-openapi": "1.6.10",
+    "@hono/node-server": "2.1.3",
+    "@libsql/client": "0.18.0",
+    "@mastra/core": "1.77.0",
+    "@mastra/docker": "0.8.0",
+    "@mastra/mcp": "2.4.0",
+    "@modelcontextprotocol/client": "2.2.0",
+    "@modelcontextprotocol/ext-apps": "2.0.3",
+    "@modelcontextprotocol/server": "2.2.0",
+    "@napi-rs/canvas": "0.1.80",
+    "@turbodocx/html-to-docx": "1.23.1",
+    "ai": "7.0.102",
+    "aws4fetch": "1.0.20",
+    "drizzle-orm": "0.45.3",
+    "effect": "4.0.0-beta.59",
+    "exceljs": "4.4.0",
+    "fast-xml-parser": "5.11.2",
+    "fflate": "0.8.3",
+    "hono": "4.13.12",
+    "imapflow": "2.2.1",
+    "jiti": "2.7.0",
+    "jose": "6.2.12",
+    "mammoth": "1.13.0",
+    "marked": "18.0.14",
+    "nanoid": "5.1.16",
+    "pdf-parse": "2.4.5",
+    "playwright-core": "1.63.0",
+    "postal-mime": "4.0.2",
+    "rfc6902": "5.3.0",
+    "turndown": "7.2.4",
+    "undici": "7.30.0",
+    "zod": "4.6.5"
+  },
+  "optionalDependencies": {
+    "node-pty": "1.1.0"
+  },
+  "bundleDependencies": [
+    "@engenty/wizards",
+    "@engenty-wizards/shared"
+  ]
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "engenty-wizards",
+  "displayName": "engenty wizards",
+  "version": "{{VERSION}}",
+  "description": "Build page-by-page AI wizards that people open on a shared link — designed, tested and published from Claude Code — and run your published ones right in the chat.",
+  "author": { "name": "engenty" },
+  "homepage": "{{APP_URL}}",
+  "keywords": ["wizards", "forms", "ai-workflows", "mcp"]
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "engenty-wizards": {
+      "type": "http",
+      "url": "{{APP_URL}}/api/mcp"
+    }
+  }
+}

package/plugin/commands/wizard.md

@@ -0,0 +1,8 @@
+---
+description: Build an engenty wizard from a description
+argument-hint: <what the wizard should do>
+---
+
+Build an engenty wizard for this: $ARGUMENTS
+
+Use the build-wizard skill: read the authoring guide, start from the closest starter, create the wizard, fix every issue, run one test with realistic answers, and give me the studio link. Do not publish unless I ask.

package/plugin/skills/build-wizard/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: build-wizard
+description: Build or change an engenty wizard — a page-by-page AI flow that people open on a shared link (questions, research, texts, images, video, documents, dashboards, writes into other systems). Use when the user wants such a wizard, a guided form with AI steps, or wants to change, test or publish one.
+---
+
+# Build an engenty wizard
+
+You work with the `engenty-wizards` MCP tools. The person you talk to is the ADMIN; the people who later open the wizard's link are END USERS.
+
+1. **Read the guide first.** Call `get_authoring_guide` once per conversation. It holds the JSON schema, the design rules and the project's connected systems. Follow it.
+2. **Start from an example.** `list_starters`, then `get_starter` for the closest one. For an existing wizard, use `list_wizards` and `get_wizard`.
+3. **Write it.**
+   - Use `create_wizard` with the full definition and a short `note` in the admin's language. The admin sees that note in the studio.
+   - Change it with `edit_wizard` ops (`set_meta`, `upsert_step`, `remove_step`, `move_step`). Pass the `revision` you last read as `baseRevision`.
+   - Keep going until `issues` is empty. On `revision_conflict`, call `get_wizard` again and redo your change on top. The admin may be editing in the studio at the same time.
+4. **Test it.**
+   - `start_test_run` takes realistic `answers`: field id → value, for every page. Then call `get_test_run` with `waitSeconds: 45` until the status is no longer `running`.
+   - Read the outputs and open the download links. Fix what is weak, then test again.
+   - Test runs spend the admin's credits: short copy with an image costs about 15, research about 150, an 8-second video about 250. Ask before running video or heavy research more than once.
+5. **Hand over.** Give the admin the `studioUrl`; the studio shows the wizard as a diagram and updates live while you edit. Publish with `publish_wizard` only when the admin asks. Then share the `shareUrl`.
+
+Design rules the guide expands on:
+- Few pages with 1–5 questions each, phrased in plain words.
+- Put a review step before anything expensive and before the result.
+- Totals come from an `items` field with VAT, never from a model.
+- Facts come from `web_search` and `web_fetch` before anything is written.
+- Write every text in the admin's language.

package/plugin/skills/use-wizard/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: use-wizard
+description: Run one of the person's published engenty wizards here in the chat — a social post with an image, a research briefing, an offer, a video ad … page by page, with its review and its downloads. Use when the person wants something one of their wizards makes, names a wizard, or asks what their wizards can do.
+---
+
+# Use an engenty wizard
+
+You work with the `engenty-wizards` MCP tools. The person you talk to runs the wizard; their answers fill its pages.
+
+1. **Find it.** `list_wizards` lists the person's wizards; only `published` ones run. `show_wizard` only when the person wants to see a wizard before running it: apps that show MCP Apps show it as it greets a person, with its flow one click away.
+2. **Start it.** `run_wizard` straight away; apps that show MCP Apps show the wizard itself, page by page, and the person may answer there. What the person already said for the first page goes in with `answer_page`, using the field ids in `waitingFor`. Runs spend credits like any run of the wizard.
+3. **Follow `waitingFor`.**
+   - `page`: ask for the fields with `inChat: true`, in the person's words, then `answer_page`. Fields with `inChat: false` (files, recordings, signatures, line items) need the run page: hand over `browserUrl`.
+   - `review`: show the outputs (texts, image links), then `review_step`: accept, or regenerate one with the person's note.
+   - `ask`: a step wants to change something in a connected account. Ask the person, then `answer_ask` with `allow` or `skip`. A sign-in happens on the run page (`browserUrl`).
+   - Nothing, status `running`: `get_run` with `waitSeconds: 45`, again until it changes.
+4. **In a widget.** When the app shows the run as a widget, the person may answer there instead of in the chat. Call `get_run` before you ask again, so you never ask for a page that is already answered.
+5. **Hand over.** When the status is `done`, give the outputs and their download links (valid one hour). `failed`: say what went wrong; `control_run` with `retry` tries the step again.