@kazzle/app 0.1.693

package/README.md

@@ -0,0 +1,63 @@
+# @kazzle/app
+
+The one versioned package for building Kazzle apps. It owns the app-facing
+TypeScript contracts, tool helpers, the Vite preview helper, the app templates,
+and the app migration codemods.
+
+This file is the ownership doc referenced by the code comments in this package
+and in the server. Read it before changing exports, templates, or the
+compatibility policy.
+
+## Why this package exists
+
+App contracts used to be copied into every generated app repo as vendored files
+(`kazzle.types.ts`, `kazzle.vite.ts`). Copies drift, can't be versioned, and give
+the AI stale types. This package replaces the copies with real imports:
+
+```ts
+import { defineConfig } from '@kazzle/app';
+import { defineTools } from '@kazzle/app/tools';
+import { kazzleAppVite } from '@kazzle/app/vite';
+```
+
+## Subpath exports — keep them separate
+
+One npm package, one version, many subpaths. The split is a hard contract, not a
+convenience: process apps that only need tools must not pull in Vite/plugin code,
+and the root export must stay tiny and dependency-free.
+
+| Subpath | Owns | Runtime deps |
+|---|---|---|
+| `@kazzle/app` | `defineConfig`, `KazzleConfig` + component/trigger/env types | none |
+| `@kazzle/app/tools` | `defineTools`, `KazzleTool` types, Zod input helper types | `zod` (peer, type-only) |
+| `@kazzle/app/client` | install-scoped client: per-install secrets, sibling component URLs | none |
+| `@kazzle/app/vite` | `kazzleAppVite` preview/runtime Vite helper | `vite` (peer, type-only) |
+| `@kazzle/app/templates` | programmatic template manifest + asset readers (server/generator only) | none |
+| `@kazzle/app/migrations` | app migration metadata + codemods (server/CLI only) | none |
+
+To add an export: add the `src/*.ts` file, add it to BOTH `exports` and
+`publishConfig.exports` in `package.json`, and document it in the table above.
+
+## Build model — source in dev, dist on npm
+
+- Workspace consumers (server, tests, typecheck) resolve `exports` → raw `.ts`
+  source. Bun and `tsc` read TS directly, so there is no build step for the
+  monorepo. This mirrors `@kazzle/framework`.
+- The published package resolves `publishConfig.exports` → compiled `dist/*.js`
+  + `dist/*.d.ts`, because apps installed from npm need JS + types.
+- `bun run build` (`scripts/build.ts`) emits `dist/` and copies `templates/`.
+- Templates ship as package assets (`files: ["dist", "templates"]`) so the
+  server generator reads the exact versioned template for every app it creates.
+
+## Versioning
+
+`@kazzle/app` shares the root Kazzle version during pre-launch (`package.json`
+`version` mirrors the repo root). CI's version-bump job syncs it before pack +
+publish. Splitting into independent semver waits until there is a real
+post-launch reason. See `documents/cicd.md`.
+
+## Compatibility
+
+Publish/check enforcement lives on the server in
+`server/apps/apps.sdk-compat.ts` (supported / deprecated / blocked ranges +
+migration command). Docs are not the enforcement layer.

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+/** Read the injected base URL of the Kazzle API for install-secret calls. */
+export declare function kazzleApiUrl(): string;
+/** Env var name Kazzle injects for a sibling component's internal URL. */
+export declare function componentUrlEnvName(componentName: string): string;
+/**
+ * Resolve a sibling component's internal URL. Throws if the platform has not
+ * injected it (start the named component first) — there is no fallback, because
+ * a wrong/empty address makes cross-component calls fail silently.
+ */
+export declare function componentUrl(componentName: string): string;
+/** Extract the install identity Authorization header from an incoming tool request. */
+export declare function installAuthHeader(req: Request): string;
+/**
+ * Client scoped to one install, built from the identity header on an incoming
+ * tool request. Use it to persist and read per-install runtime secrets.
+ */
+export declare class KazzleInstallClient {
+    private readonly auth;
+    private readonly apiUrl;
+    constructor(reqOrAuthHeader: Request | string);
+    /** Read a per-install secret by fixed name. Returns null when not set yet (404). */
+    getSecret(name: string): Promise<string | null>;
+    /** Write a per-install secret by fixed name. */
+    setSecret(name: string, value: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,83 @@
+// @kazzle/app/client — install-scoped helpers for app process/server code.
+//
+// Two things app backends repeatedly need and used to hand-roll from copy-paste
+// comments in the templates:
+//
+//   1. Per-install secrets. When the AI calls an app tool, Kazzle POSTs the
+//      request with `Authorization: Bearer <install identity>`. The app reads
+//      or writes runtime secrets by calling Kazzle back with that SAME header;
+//      Kazzle scopes the secret to this install. Use a fixed secret name — never
+//      key by user yourself.
+//   2. Sibling component URLs. A component reaches another component in the same
+//      app via the injected `KAZZLE_APP_COMPONENT_<NAME>_URL` env var. That URL
+//      is server-to-server only — never expose it to the browser.
+//
+// Dependency-free on purpose (uses global fetch). Do not add zod/vite here.
+/** Read the injected base URL of the Kazzle API for install-secret calls. */
+export function kazzleApiUrl() {
+    const url = process.env['KAZZLE_API_URL'];
+    if (!url) {
+        throw new Error('KAZZLE_API_URL is not set — this code must run as a deployed Kazzle app component.');
+    }
+    return url;
+}
+/** Env var name Kazzle injects for a sibling component's internal URL. */
+export function componentUrlEnvName(componentName) {
+    const normalized = componentName.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '');
+    return `KAZZLE_APP_COMPONENT_${normalized}_URL`;
+}
+/**
+ * Resolve a sibling component's internal URL. Throws if the platform has not
+ * injected it (start the named component first) — there is no fallback, because
+ * a wrong/empty address makes cross-component calls fail silently.
+ */
+export function componentUrl(componentName) {
+    const envName = componentUrlEnvName(componentName);
+    const url = process.env[envName];
+    if (!url) {
+        throw new Error(`${envName} is not set. Start the "${componentName}" component so Kazzle can resolve its address.`);
+    }
+    return url;
+}
+/** Extract the install identity Authorization header from an incoming tool request. */
+export function installAuthHeader(req) {
+    const auth = req.headers.get('authorization');
+    if (!auth) {
+        throw new Error('Missing Authorization header — expected the install identity from a Kazzle tool call.');
+    }
+    return auth;
+}
+/**
+ * Client scoped to one install, built from the identity header on an incoming
+ * tool request. Use it to persist and read per-install runtime secrets.
+ */
+export class KazzleInstallClient {
+    auth;
+    apiUrl;
+    constructor(reqOrAuthHeader) {
+        this.auth = typeof reqOrAuthHeader === 'string' ? reqOrAuthHeader : installAuthHeader(reqOrAuthHeader);
+        this.apiUrl = kazzleApiUrl();
+    }
+    /** Read a per-install secret by fixed name. Returns null when not set yet (404). */
+    async getSecret(name) {
+        const res = await fetch(`${this.apiUrl}/apps/secrets/${encodeURIComponent(name)}`, {
+            headers: { authorization: this.auth },
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Failed to read install secret "${name}": ${res.status}`);
+        const body = (await res.json());
+        return body.value ?? null;
+    }
+    /** Write a per-install secret by fixed name. */
+    async setSecret(name, value) {
+        const res = await fetch(`${this.apiUrl}/apps/secrets/${encodeURIComponent(name)}`, {
+            method: 'PUT',
+            headers: { authorization: this.auth, 'content-type': 'application/json' },
+            body: JSON.stringify({ value }),
+        });
+        if (!res.ok)
+            throw new Error(`Failed to write install secret "${name}": ${res.status}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+export interface KazzleComponentRuntime {
+    /** Command to start the dev server (e.g. "bun run dev", "vite") */
+    dev?: string;
+    /** Command to build for production (e.g. "bun run build", "vite build") */
+    build?: string;
+    /** Command to start in production (e.g. "bun run start") */
+    run?: string;
+}
+export interface KazzleComponentEnv {
+    /** Secret collection slug */
+    collection: string;
+    /** Environment slug for secret injection */
+    environment: string;
+    /** Only inject these env var names. If omitted, inject all from collection+environment. */
+    include?: string[];
+}
+/**
+ * A single trigger entry on a process component. One component can declare
+ * many triggers — for example, a daily cron AND a webhook handler that both
+ * route into the same code.
+ *
+ *   - `kind: 'schedule'` → fires on the cron expression in `schedule`.
+ *     `schedule` is a 5-field cron expression with minute resolution.
+ *
+ *   - `kind: 'webhook'`  → fires when the platform receives
+ *     `POST /webhooks/{spaceId}/{appId}/{componentName}/{name}`.
+ *
+ * `path` is the HTTP route on the running server that handles this trigger.
+ * Required when `processMode: 'persistent'` (the platform POSTs the trigger
+ * into the long-running server at this path with `Authorization: Bearer
+ * ${KAZZLE_TRIGGER_SECRET}`). Ignored for `processMode: 'triggered'` — those
+ * components run as one-off ephemeral processes that read `TRIGGER_NAME`
+ * from the environment instead.
+ */
+export interface KazzleTrigger {
+    /** Stable identifier, unique within the component (kebab-case, e.g. "daily-digest"). */
+    name: string;
+    /** Trigger kind — schedule (cron) or webhook (HTTP POST). */
+    kind: 'schedule' | 'webhook';
+    /** Cron expression (5-field, minute resolution). Required for kind="schedule". */
+    schedule?: string;
+    /** HTTP path on the running server. Required when processMode="persistent". */
+    path?: string;
+}
+export interface KazzleComponent {
+    /** Unique component name within the app */
+    name: string;
+    /** Component type — ui (max 1) or process */
+    type: 'ui' | 'process';
+    /** Entry path within the app directory */
+    path: string;
+    /** Commands for dev, build, and run phases */
+    runtime?: KazzleComponentRuntime;
+    /**
+     * Execution lifecycle for process components.
+     *
+     *   - 'persistent' — long-running server. Triggers are POSTed into the
+     *     server at the declared `path`. This is the default.
+     *   - 'triggered'  — ephemeral one-off run per trigger. The platform
+     *     spawns the entry script with `TRIGGER_NAME`, `RUN_ID`, and an
+     *     optional `WEBHOOK_PAYLOAD` env var, then waits for exit.
+     */
+    processMode?: 'persistent' | 'triggered';
+    /** Schedule and webhook triggers. One component may declare many. */
+    triggers?: KazzleTrigger[];
+    /** Secret collection + environment for env var injection. */
+    env?: KazzleComponentEnv;
+}
+export interface KazzleSkill {
+    /** Skill name */
+    name: string;
+    /** Path to the SKILL.md file relative to the app root */
+    path: string;
+}
+export interface KazzleConfig {
+    /** Where the published app runs — remote (Fly.io) or local (user computer). Defaults to remote. */
+    target?: 'local' | 'remote';
+    /** Path to the app icon file (png, jpg, svg, webp, ico) */
+    icon?: string;
+    /** Executable components — UI frontends or background processes */
+    components?: KazzleComponent[];
+    /** AI skill definitions — markdown files the AI reads for domain knowledge */
+    skills?: KazzleSkill[];
+}
+/** Type-safe config helper. Use: export default defineConfig({ ... }) */
+export declare function defineConfig(config: KazzleConfig): KazzleConfig;

package/dist/index.js

@@ -0,0 +1,15 @@
+// @kazzle/app — root export. App config contract + `defineConfig`.
+//
+// SOURCE OF TRUTH for the app config types that generated apps author in
+// kazzle.config.ts. The server validates the runtime shape with the Zod
+// `ManifestSchema` in server/apps/apps.manifest.ts; these interfaces are the
+// hand-authored TypeScript mirror app code imports. Keep the two in sync — if
+// you add a config field here, add it to ManifestSchema in the same change.
+//
+// This module must stay dependency-free. Tools live in `@kazzle/app/tools`,
+// the Vite helper in `@kazzle/app/vite` — do not re-export them here or the
+// root import pulls in zod/vite for every consumer. See README.md.
+/** Type-safe config helper. Use: export default defineConfig({ ... }) */
+export function defineConfig(config) {
+    return config;
+}

package/dist/migrations.d.ts

@@ -0,0 +1,19 @@
+/** A file map: relative path -> file contents. */
+export type AppFileMap = Record<string, string>;
+export interface AppMigration {
+    /** Unique migration id, e.g. "app-api-v0.2". Referenced by compat policy. */
+    id: string;
+    /** Human range this migration upgrades FROM, e.g. "<0.2". Display + matching. */
+    appliesTo: string;
+    /** What the migration does. */
+    description: string;
+    /** Globs the migration may edit (for the dry-run summary). */
+    files: string[];
+    /** Pure transform: returns only the files it changed (or added). */
+    run(files: AppFileMap): AppFileMap;
+}
+export declare const APP_MIGRATIONS: AppMigration[];
+/** Look up a migration by id. */
+export declare function getAppMigration(id: string): AppMigration | undefined;
+/** Add the `@kazzle/app` dependency to an app package.json string (idempotent). */
+export declare function addPackageDependency(pkgJson: string, version: string): string;

package/dist/migrations.js

@@ -0,0 +1,74 @@
+// @kazzle/app/migrations — versioned app migration metadata + codemods.
+//
+// SERVER/CLI ONLY. A machine-readable registry of upgrade instructions for
+// existing generated app repos — the same idea as Next codemods / Expo upgrade
+// tooling. It is NOT product data: it tells `kazzle migrate` how to rewrite an
+// app checkout when the app contract changes between package versions.
+//
+// Codemods are PURE: they take an in-memory `{ path -> contents }` map and
+// return the changed files. The server/CLI owns reading and writing the actual
+// checkout (see the thin-CLI rule in the plan). This keeps migrations testable
+// without a filesystem and keeps fs/permission policy server-side.
+//
+// To add a migration:
+//   1. Append an `AppMigration` to `APP_MIGRATIONS` with a unique `id`.
+//   2. Set `appliesTo` (semver-ish range string, matched by the server compat
+//      policy) and `files` (globs it may touch, for the dry-run summary).
+//   3. Implement `run` as a pure file-map transform.
+//   4. Point the server compat blocker/deprecation `migrationCommand` at the id.
+/** Rewrite a vendored `./kazzle.types` / `./kazzle.vite` import to the package. */
+function rewriteImports(contents) {
+    return contents
+        // `from './kazzle.types'`, `from '../../kazzle.types'`, etc → '@kazzle/app'
+        .replace(/(from\s*['"])((?:\.\.?\/)+)kazzle\.types(['"])/g, '$1@kazzle/app$3')
+        // vite helper → '@kazzle/app/vite'
+        .replace(/(from\s*['"])((?:\.\.?\/)+)kazzle\.vite(['"])/g, '$1@kazzle/app/vite$3');
+}
+/** Ensure `@kazzle/app` is a dependency of the app root package.json. */
+function ensurePackageDependency(pkgJson, version) {
+    const parsed = JSON.parse(pkgJson);
+    parsed.dependencies = parsed.dependencies ?? {};
+    if (parsed.dependencies['@kazzle/app'])
+        return pkgJson;
+    parsed.dependencies['@kazzle/app'] = `^${version}`;
+    return JSON.stringify(parsed, null, 2) + '\n';
+}
+/**
+ * v0.2: apps stop vendoring kazzle.types.ts / kazzle.vite.ts and import the
+ * contracts from `@kazzle/app`. Rewrites imports, adds the dependency, and
+ * deletes the vendored files (represented by an empty-string body, which the
+ * server/CLI turns into a delete).
+ */
+function migrateToPackageImports(files) {
+    const changed = {};
+    for (const [path, contents] of Object.entries(files)) {
+        const base = path.split('/').pop() ?? path;
+        if (base === 'kazzle.types.ts' || base === 'kazzle.vite.ts') {
+            changed[path] = ''; // empty body = delete (vendored file replaced by import)
+            continue;
+        }
+        if (path === 'package.json')
+            continue; // handled below with the version
+        const rewritten = rewriteImports(contents);
+        if (rewritten !== contents)
+            changed[path] = rewritten;
+    }
+    return changed;
+}
+export const APP_MIGRATIONS = [
+    {
+        id: 'app-api-v0.2',
+        appliesTo: '<0.2',
+        description: 'Import Kazzle app contracts from @kazzle/app instead of vendored kazzle.types.ts / kazzle.vite.ts.',
+        files: ['**/*.ts', '**/*.tsx', 'package.json'],
+        run: migrateToPackageImports,
+    },
+];
+/** Look up a migration by id. */
+export function getAppMigration(id) {
+    return APP_MIGRATIONS.find(m => m.id === id);
+}
+/** Add the `@kazzle/app` dependency to an app package.json string (idempotent). */
+export function addPackageDependency(pkgJson, version) {
+    return ensurePackageDependency(pkgJson, version);
+}

package/dist/templates.d.ts

@@ -0,0 +1,33 @@
+/** One entry in the package template manifest (metadata only, no file bodies). */
+export interface TemplateManifestEntry {
+    /** Template id, e.g. "ui-db". The scaffold dir is `${id}-app`. */
+    id: string;
+    /** Short human label. */
+    label: string;
+    /** One-line description for listing. */
+    description: string;
+    /** Optional discovery tags. */
+    tags?: string[];
+}
+/**
+ * Absolute path to the package `templates/` root. The server's gitignore-aware
+ * file reader (`server/apps/apps.template-files.ts`) points its scan root here
+ * so there is exactly one on-disk source for scaffold files.
+ */
+export declare function templatesRoot(): string;
+/** Read the template manifest (metadata for listing). */
+export declare function templateManifest(): TemplateManifestEntry[];
+/** Absolute path to a template's scaffold dir. */
+export declare function templateDir(id: string): string;
+/** Absolute path to the shared scaffold dir merged into every app. */
+export declare function sharedTemplateDir(): string;
+/** Whether a template id has a scaffold dir in this package. */
+export declare function templateExists(id: string): boolean;
+/** Relative file paths in a template's scaffold dir. */
+export declare function listTemplateFiles(id: string): string[];
+/** Relative file paths in the shared scaffold dir. */
+export declare function listSharedFiles(): string[];
+/** Read one scaffold file's raw contents. Throws if missing. */
+export declare function readTemplateFile(id: string, relPath: string): string;
+/** Read one shared scaffold file's raw contents. Throws if missing. */
+export declare function readSharedFile(relPath: string): string;

package/dist/templates.js

@@ -0,0 +1,89 @@
+// @kazzle/app/templates — programmatic template asset reader.
+//
+// SERVER/GENERATOR ONLY. This is the single source for the app scaffold files
+// shipped with the package (under `packages/kazzle-app/templates/`). The server
+// reads through these functions instead of hardcoding `server/templates` fs
+// paths, so app generation and the AI `tpl_*` browse tools always see the exact
+// versioned template that ships with this package version.
+//
+// What lives where:
+//   - Scaffold file assets + `manifest.json` → this package's `templates/` dir.
+//   - Template setup hooks + params (server-side, needs DB/checkout context) →
+//     `server/apps/templates/*.template.ts` (cannot move here; would create a
+//     package → server dependency).
+//
+// Resolution: `templates/` sits next to `src/` in dev and next to `dist/` when
+// published, so `../templates` off this module resolves in both.
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative } from 'node:path';
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/', import.meta.url));
+const ALWAYS_SKIP = new Set(['.git', '.DS_Store']);
+function manifestPath() {
+    return join(TEMPLATES_DIR, 'manifest.json');
+}
+/**
+ * Absolute path to the package `templates/` root. The server's gitignore-aware
+ * file reader (`server/apps/apps.template-files.ts`) points its scan root here
+ * so there is exactly one on-disk source for scaffold files.
+ */
+export function templatesRoot() {
+    return TEMPLATES_DIR;
+}
+/** Read the template manifest (metadata for listing). */
+export function templateManifest() {
+    const path = manifestPath();
+    if (!existsSync(path))
+        return [];
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed.entries;
+}
+/** Scaffold directory name for a template id. */
+function templateDirName(id) {
+    return `${id}-app`;
+}
+/** Absolute path to a template's scaffold dir. */
+export function templateDir(id) {
+    return join(TEMPLATES_DIR, templateDirName(id));
+}
+/** Absolute path to the shared scaffold dir merged into every app. */
+export function sharedTemplateDir() {
+    return join(TEMPLATES_DIR, 'shared');
+}
+/** Whether a template id has a scaffold dir in this package. */
+export function templateExists(id) {
+    const dir = templateDir(id);
+    return existsSync(dir) && statSync(dir).isDirectory();
+}
+function walk(dir, baseDir) {
+    const files = [];
+    if (!existsSync(dir))
+        return files;
+    for (const entry of readdirSync(dir)) {
+        if (ALWAYS_SKIP.has(entry))
+            continue;
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            files.push(...walk(full, baseDir));
+        else
+            files.push(relative(baseDir, full));
+    }
+    return files;
+}
+/** Relative file paths in a template's scaffold dir. */
+export function listTemplateFiles(id) {
+    return walk(templateDir(id), templateDir(id));
+}
+/** Relative file paths in the shared scaffold dir. */
+export function listSharedFiles() {
+    const dir = sharedTemplateDir();
+    return walk(dir, dir);
+}
+/** Read one scaffold file's raw contents. Throws if missing. */
+export function readTemplateFile(id, relPath) {
+    return readFileSync(join(templateDir(id), relPath), 'utf-8');
+}
+/** Read one shared scaffold file's raw contents. Throws if missing. */
+export function readSharedFile(relPath) {
+    return readFileSync(join(sharedTemplateDir(), relPath), 'utf-8');
+}

package/dist/tools.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+/** Zod schema for a tool's input object. Use .default(), .optional(), .transform(), etc. */
+export type KazzleToolInputSchema = z.ZodType<Record<string, unknown>>;
+interface KazzleToolBase {
+    /** Provider-safe identifier: letters, numbers, underscores, or hyphens. */
+    name: string;
+    /** Friendly title shown in chat cards, e.g. "Save bookmark". */
+    displayName: string;
+    /** AI-facing description for when to call this tool. */
+    description: string;
+}
+/** A tool served by one of this app's own components. */
+export interface KazzleAppTool extends KazzleToolBase {
+    type: 'app';
+    /** Zod schema for tool input. Use .default(), .optional(), .transform(), etc. here. */
+    input: KazzleToolInputSchema;
+    /** Component name from kazzle.config.ts that serves this tool. */
+    component: string;
+    /** POST route on that component. */
+    path: string;
+}
+/** A tool served by an external publisher-hosted HTTP endpoint. */
+export interface KazzleUrlTool extends KazzleToolBase {
+    type: 'url';
+    input: KazzleToolInputSchema;
+    /** Literal absolute URL, used verbatim. */
+    url: string;
+}
+/** A name-only reference to a platform/native tool resolved from the code registry. */
+export interface KazzleNativeTool extends KazzleToolBase {
+    type: 'kazzle';
+}
+export type KazzleTool = KazzleAppTool | KazzleUrlTool | KazzleNativeTool;
+/** Type-safe tools helper. Use: export const tools = defineTools([...]) */
+export declare function defineTools<T extends readonly KazzleTool[]>(tools: T): T;
+export {};

package/dist/tools.js

@@ -0,0 +1,22 @@
+// @kazzle/app/tools — app tool contract + `defineTools`.
+//
+// An app declares its AI tools in skills/tools/tools.ts as
+// `export const tools = defineTools([...])`. Each tool's `input` is a Zod
+// schema, which is the whole point of this file existing:
+//
+//   - Zod gives real optional/`.default()`/`.transform()` semantics, so a
+//     tool with `maxResults: z.number().default(20)` does NOT mark maxResults
+//     as required in the model-facing schema. Plain JSON tool schemas treated
+//     every field as required, which caused wrong-param tool calls.
+//   - `displayName` is the friendly title shown in chat cards ("List Gmail
+//     messages"); `name` is the provider-safe id ([a-zA-Z0-9_-]{1,64}).
+//
+// Publish-time, the server compiles these Zod schemas into provider JSON schema
+// for model exposure AND server-side repair validation. That compiler is
+// server/apps/apps.skills.tools.ts — it reads the SAME shape defined here
+// (`type`, `name`, `displayName`, `description`, `input`, `component`/`path`/`url`).
+// If you change this contract, update that compiler and its tests together.
+/** Type-safe tools helper. Use: export const tools = defineTools([...]) */
+export function defineTools(tools) {
+    return tools;
+}

package/dist/vite.d.ts

@@ -0,0 +1,29 @@
+import type { UserConfig } from 'vite';
+export interface KazzleAppViteOptions {
+    /**
+     * Name of the sibling process component that owns this app's backend/API
+     * routes. Omit for a pure static UI with no backend component.
+     *
+     * When set, the dev server refuses to start until Kazzle injects that
+     * component's URL (KAZZLE_APP_COMPONENT_<NAME>_URL), and the routes in
+     * `proxyPaths` are forwarded to it. That internal URL is for this proxy
+     * only — never expose it to the browser via import.meta.env / VITE_*.
+     */
+    apiComponent?: string;
+    /**
+     * Relative root route names the browser calls (e.g. ['/todos', '/chat'])
+     * that must be proxied to `apiComponent`. Ignored when `apiComponent` is
+     * omitted. The browser always uses relative paths; the proxy hides the
+     * backend address.
+     */
+    proxyPaths?: string[];
+}
+/**
+ * Kazzle preview/runtime Vite config. Spread the result into your Vite config:
+ *
+ *   export default defineConfig(({ command }) => ({
+ *     plugins: [react(), tailwindcss()],
+ *     ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/todos'] }),
+ *   }));
+ */
+export declare function kazzleAppVite(command: string, options?: KazzleAppViteOptions): UserConfig;

package/dist/vite.js

@@ -0,0 +1,77 @@
+// @kazzle/app/vite — Kazzle preview/runtime Vite helper.
+//
+// BUILD-TIME ONLY. This module imports vite types and is meant for a UI
+// component's vite.config.ts. Never import it from process/runtime code — the
+// subpath split exists so process apps don't pull vite into their dependency
+// graph. See README.md.
+//
+// READ THIS BEFORE TOUCHING vite.config.ts (human or AI):
+// Kazzle assigns every UI component a specific HOST and PORT at preview/run
+// time and injects them through `kazzle run`. The preview tunnel forwards
+// traffic to THAT exact port. If Vite binds any other port (e.g. its default
+// 5173) the tunnel gets ECONNREFUSED and the preview looks broken. This helper
+// is the ONE place that reads HOST/PORT and pins Vite to them (strictPort).
+//
+// Every UI component's vite.config.ts MUST spread `...kazzleAppVite(command)`
+// into its config instead of hand-writing server.host / server.port.
+function componentUrlEnvName(componentName) {
+    const normalized = componentName.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '');
+    return `KAZZLE_APP_COMPONENT_${normalized}_URL`;
+}
+/**
+ * Kazzle preview/runtime Vite config. Spread the result into your Vite config:
+ *
+ *   export default defineConfig(({ command }) => ({
+ *     plugins: [react(), tailwindcss()],
+ *     ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/todos'] }),
+ *   }));
+ */
+export function kazzleAppVite(command, options = {}) {
+    const isServe = command === 'serve';
+    // DO NOT ADD FALLBACKS. HOST/PORT are injected by `kazzle run`. Missing
+    // values must throw when a server actually needs to bind (dev/preview) — but
+    // production `vite build` emits static files and never binds, so we only
+    // enforce in serve mode. Throwing during build would break the deploy pipeline.
+    if (isServe && (!process.env['PORT'] || !process.env['HOST'])) {
+        throw new Error('PORT and HOST must be set by "kazzle run" — never hardcode them.');
+    }
+    const host = process.env['HOST'];
+    const port = process.env['PORT'] ? Number(process.env['PORT']) : undefined;
+    let proxy;
+    if (options.apiComponent) {
+        const envName = componentUrlEnvName(options.apiComponent);
+        const apiTarget = process.env[envName];
+        if (isServe && !apiTarget) {
+            // This app declares a backend component. The UI proxy MUST know the
+            // backend address before serving — there is no fallback. Start the
+            // named component first; Kazzle injects its URL from the sibling's
+            // sticky component_port.
+            throw new Error(`${envName} is required. Start the \`${options.apiComponent}\` component first ` +
+                'so Kazzle can resolve its address.');
+        }
+        if (apiTarget && options.proxyPaths?.length) {
+            proxy = Object.fromEntries(options.proxyPaths.map(path => [path, { target: apiTarget, changeOrigin: true }]));
+        }
+    }
+    return {
+        server: {
+            host,
+            port,
+            // DO NOT REMOVE. Fail loudly (EADDRINUSE) if PORT is taken instead of
+            // silently binding the next free port. The Kazzle preview proxy only
+            // knows the assigned PORT — if Vite drifted the preview would
+            // 404/ECONNREFUSED and look "broken". Kazzle frees this port first.
+            strictPort: true,
+            // The Kazzle preview tunnel forwards requests with a *.kazzle.app Host
+            // header, not localhost. Vite rejects unknown hosts unless enabled.
+            allowedHosts: true,
+            proxy,
+        },
+        preview: {
+            host,
+            port,
+            strictPort: true, // DO NOT REMOVE — see server.strictPort above.
+            allowedHosts: true,
+        },
+    };
+}