velloo 0.0.0 → 0.2.0

package/pkgs/schema/src/config.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { BoardGroupSchema } from "./board.ts";
+import { ExtensionSchema } from "./extension.ts";
+import { CURRENT_SCHEMA_VERSION } from "./migrate.ts";
+import { DesignNameSchema, FeedbackPrefsSchema } from "./repo.ts";
+
+export const ViewportPresetSchema = z.object({
+  name: z.string().min(1),
+  w: z.number().int().positive(),
+  h: z.number().int().positive(),
+});
+
+export type ViewportPreset = z.infer<typeof ViewportPresetSchema>;
+
+/**
+ * Library declaration. The `id` selects which component provider the
+ * design folder is built against (see `@velloo/provider`). `source`
+ * tells the loader where the components live for that provider:
+ *
+ *   "binary"   — components ship with the velloo binary.
+ *   "cache"    — components live under `~/.velloo/…`.
+ *   "in-repo"  — components live inside the user's app folder.
+ *                `componentsPath` is the resolved location; the shadcn
+ *                canvas imports supported files from here directly.
+ */
+export const LibrarySchema = z.object({
+  /**
+   * Component provider id. The server's provider loader maps ids to
+   * factories; `"shadcn-upstream"` is the default for new folders.
+   */
+  id: z.enum(["shadcn-upstream", "none", "mui", "antd", "chakra"]),
+  version: z.string().min(1),
+  source: z.enum(["binary", "cache", "in-repo"]),
+  /** Where the components live, relative to the design folder root. */
+  componentsPath: z.string().min(1),
+});
+
+export type Library = z.infer<typeof LibrarySchema>;
+
+const CodegenConfigSchema = z.object({
+  /** Import prefix for emitted shadcn imports. Defaults to "@/components/ui". */
+  componentsAlias: z.string().min(1).optional(),
+  /**
+   * Where the app's UI components live, relative to the app root — what
+   * `init` asked (or detected). Recorded so a *second* design folder in the
+   * same repo inherits the answer instead of asking again.
+   */
+  componentsDir: z.string().min(1).optional(),
+});
+
+export type CodegenConfig = z.infer<typeof CodegenConfigSchema>;
+
+/**
+ * Where the host app lives, used by the live-island bundler to resolve
+ * a `render:"live"` extension's `importPath` (and its dependencies, e.g.
+ * the app's own recharts) into a browser bundle. `root` is absolute or
+ * resolved from the design folder root; `project:` paths resolve from the
+ * locally bound application root for managed designs. Absent ⇒ the bundler defaults to
+ * the design folder's parent (the `<appRoot>/velloo` layout `init`
+ * produces). `aliases` mirrors the host tsconfig path map (e.g.
+ * `{ "@/*": "src/*" }`); absent ⇒ `{ "@/*": "*" }`. Reading the host
+ * tsconfig per build is fragile (JSON5, `extends` chains), so it's
+ * persisted once at registration time.
+ */
+export const HostAppSchema = z.object({
+  root: z.string().min(1),
+  aliases: z.record(z.string().min(1), z.string().min(1)).optional(),
+});
+
+export type HostApp = z.infer<typeof HostAppSchema>;
+
+/**
+ * Folder config. Multi-library: a folder registers N libraries by id
+ * and pins one as the default; each screen optionally declares which
+ * library it uses (`screen.library`), falling back to `defaultLibrary`.
+ *
+ * `schemaVersion` gates loading: the server refuses folders on any
+ * other version (older ⇒ `velloo upgrade` migrates them on disk — see
+ * `migrate.ts`; newer ⇒ the binary is too old).
+ */
+export const ConfigSchema = z
+  .object({
+    schemaVersion: z.literal(CURRENT_SCHEMA_VERSION),
+    toolVersion: z.string().min(1),
+    /**
+     * The design's name — what commands, `velloo.json`'s `defaultDesign`, the
+     * canvas title and agents call it. Lives here, not in the manifest, so a
+     * design carries its identity wherever it is stored. Unique among the
+     * designs of one checkout.
+     */
+    name: DesignNameSchema,
+    /**
+     * Stable folder identity for velloo-cloud (a UUID). Published share links
+     * carry it server-side, so every clone of the folder finds its links (and
+     * their comments) by id — no committed link records. `init` generates it;
+     * pre-existing folders get one lazily on their first `velloo publish`.
+     * Optional because it's meaningless until the folder touches the cloud.
+     */
+    folderId: z
+      .string()
+      .regex(/^[A-Za-z0-9_-]{8,64}$/)
+      .optional(),
+    /**
+     * Map of `libraryId → Library`. Library ids are free-form strings
+     * the user picks (e.g. "shadcn", "marketing", "internal"); the
+     * `Library.id` field inside each entry still names the provider
+     * implementation.
+     */
+    libraries: z.record(z.string().min(1), LibrarySchema),
+    /** Library id used when a screen doesn't declare one. */
+    defaultLibrary: z.string().min(1),
+    /**
+     * User-declared custom components. The agent adds these via the
+     * `add_extension` MCP tool when a screen needs a component the
+     * active library doesn't have. Keyed by component id; ids
+     * shadow library components of the same name.
+     */
+    extensions: z.record(z.string().min(1), ExtensionSchema).optional(),
+    viewportPresets: z.array(ViewportPresetSchema).min(1),
+    /** Screen id the canvas should focus on first load. Falls back to the first screen. */
+    defaultScreen: z.string().min(1).optional(),
+    /** Board id the canvas should open on first load. Falls back to the first board. */
+    defaultBoard: z.string().min(1).optional(),
+    /**
+     * Left-sidebar display order of boards, as board ids. The canvas
+     * writes this when the user drags boards to reorder them. Boards not
+     * listed fall to the end in filename (alphabetical) order; ids that
+     * no longer resolve are ignored. Absent ⇒ filename order — the
+     * historical default, so existing folders are unaffected.
+     */
+    boardOrder: z.array(z.string().min(1)).optional(),
+    /**
+     * Sidebar groups of boards, in display order — an area of work ("Side
+     * pane", "Account page") holding a set of boards. A board points at one
+     * via `Board.group`; boards pointing at nothing render under Ungrouped.
+     * `boardOrder` still orders boards *within* a group. Absent ⇒ today's
+     * flat list, so existing folders are unaffected.
+     */
+    boardGroups: z.array(BoardGroupSchema).optional(),
+    codegen: CodegenConfigSchema.optional(),
+    /**
+     * The folder's CSS framework — the styling axis, independent of the
+     * component library (`library`). `init` detects it from the host app.
+     * `"tailwind"` ⇒ Tailwind utility classes on `className`; `"none"` ⇒ inline
+     * `style` objects (themed via the CSS vars `themeToCss` injects, no build
+     * step). Absent ⇒ the active library's default channel (Tailwind for
+     * shadcn/none, `sx` for MUI). Honored per screen only when that screen's
+     * library supports it — a shadcn screen stays Tailwind even here. The
+     * server rejects a folder whose CSS framework no registered library
+     * supports (e.g. shadcn + none).
+     */
+    styling: z.object({ framework: z.enum(["tailwind", "none"]) }).optional(),
+    /** Host app location for the live-island bundler. See `HostAppSchema`. */
+    hostApp: HostAppSchema.optional(),
+    /**
+     * Named host apps for monorepos — the multi-app twin of `hostApp`, keyed
+     * by a short app name (`"web"`, `"admin"`; `init`'s multi-app scan uses
+     * the same prefixes as the screen ids it generates). An extension can
+     * pick its app via `extension.app`, so its live island bundles against
+     * that app's root/aliases/node_modules (and its React copy). `hostApp`
+     * stays the default for extensions that don't name one. Absent ⇒
+     * single-app folder, everything resolves through `hostApp`.
+     */
+    hostApps: z.record(z.string().min(1), HostAppSchema).optional(),
+    /**
+     * Opt-in product feedback. Set during interactive `init` (after the user
+     * signs in). When `enabled`, the server exposes the `send_feedback` MCP
+     * tool, which posts free-text feedback about Velloo to velloo-cloud.
+     * `contactOk` records consent to be contacted about that feedback. Absent
+     * ⇒ disabled (the default; the local tool stays account-free + offline).
+     */
+    /**
+     * @deprecated Feedback consent is a repo-level preference now, stored in
+     * `velloo.json` — it's about the person, not the design folder, and a
+     * repo with several folders shouldn't ask (or answer) it twice. Still
+     * read as the fallback for folders written before the move; never
+     * written.
+     */
+    feedback: FeedbackPrefsSchema.optional(),
+  })
+  .refine((c) => c.defaultLibrary in c.libraries, {
+    message: "`defaultLibrary` must name an entry in `libraries`.",
+  });
+
+export type Config = z.infer<typeof ConfigSchema>;

package/pkgs/schema/src/css-sanitize.ts

@@ -0,0 +1,56 @@
+/**
+ * CSS-injection hardening for untrusted design-folder strings that reach an
+ * inline `<style>` (the renderer's canvas + Playwright document) or an emitted
+ * stylesheet (codegen's globals.css). Theme values, palette entries, custom.css,
+ * and Google-font specs are authored by whoever wrote the design JSON, so a
+ * value like `#fff</style><script>…</script>` must not break out of the style
+ * element or the declaration. This is the single home for that logic — the
+ * renderer's `theme-to-css.ts`/`document.ts` and codegen's `emit-theme` both
+ * route through it (mirrors how `svg-sanitize.ts` centralizes SVG safety).
+ */
+
+/** A CSS custom-property / token name: letters, digits, dash, underscore only. */
+const CSS_IDENT_RE = /^[A-Za-z0-9_-]+$/;
+
+/** True when `name` is safe to interpolate as a `--<name>` token identifier. */
+export function isCssIdent(name: string): boolean {
+  return CSS_IDENT_RE.test(name);
+}
+
+/**
+ * Make an untrusted theme *token value* safe to interpolate into a CSS
+ * declaration. Theme values (colors, spacing, shadows, radius, font stacks,
+ * animation shorthands) never legitimately contain declaration/element/comment
+ * delimiters, so strip the characters that could break out — `<> {} ;`,
+ * backslash, the comment-close `*​/`, and newlines — while preserving everything
+ * a real value needs (parens, commas, quotes, %, #, dots, spaces).
+ */
+export function sanitizeCssTokenValue(value: string): string {
+  return value
+    .replace(/\*\//g, "")
+    .replace(/[<>{};\\]/g, "")
+    .replace(/[\r\n]+/g, " ")
+    .trim();
+}
+
+/**
+ * Neutralize an untrusted *raw CSS block* (folder custom.css, adapter emotion
+ * CSS) for inlining into an HTML `<style>` element. The only breakout from a
+ * raw-text element is the end-tag sequence `</`, so escape it: `<\/` is inert to
+ * the HTML tokenizer and reads as `/` to the CSS parser (a valid escape,
+ * preserved even inside `url()`/string values). Structural CSS (`;{}`) is left
+ * intact because the block IS structural CSS.
+ */
+export function neutralizeCssText(css: string): string {
+  return css.replace(/<\//g, "<\\/");
+}
+
+/**
+ * Restrict a Google Fonts css2 `family=` spec to the characters the syntax
+ * actually uses (family name + `ital,wght@…;…` axis tuples), folding spaces to
+ * `+`. Drops anything that could break out of the `<link href>` attribute or the
+ * `@import url("…")` string (quotes, angle brackets, parens, backslash).
+ */
+export function sanitizeGoogleFontSpec(spec: string): string {
+  return spec.replace(/[^A-Za-z0-9 +:,.;@_-]/g, "").replace(/ /g, "+");
+}

package/pkgs/schema/src/extension.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+/**
+ * A user-declared component the agent can place in a screen tree but
+ * which isn't part of any library's registry. The canvas renders an
+ * extension node as a labelled placeholder (Tier 1); codegen emits a
+ * real import to `importPath` so the user's app mounts the actual
+ * component — one tier of the three-tier customization story.
+ *
+ * The prop schema mirrors `@velloo/provider`'s `PropDescriptor` — kept
+ * here as a Zod schema so `.design/config.json` validation works
+ * without `@velloo/schema` depending on `@velloo/provider` (which
+ * would invert the package graph). The type produced is structurally
+ * compatible: extension props feed into the same inspector affordances
+ * the manifest-derived ones use.
+ */
+const PropControlSchema = z.enum(["boolean", "number", "string", "color", "enum", "icon"]);
+
+export const ExtensionPropDescriptorSchema = z
+  .object({
+    name: z.string().min(1),
+    /** Raw TS type string (e.g. "boolean | undefined"). Free-form; just used for display. */
+    type: z.string().min(1),
+    optional: z.boolean(),
+    defaultValue: z.string().optional(),
+    control: PropControlSchema,
+    /** Allowed values when `control === "enum"`. */
+    enumValues: z.array(z.union([z.string(), z.number()])).optional(),
+  })
+  .superRefine((prop, ctx) => {
+    // An enum control with no values would render an empty select in the
+    // inspector — reject it at parse time instead.
+    if (prop.control === "enum" && (!prop.enumValues || prop.enumValues.length === 0)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["enumValues"],
+        message: `prop "${prop.name}": control "enum" requires a non-empty \`enumValues\` array`,
+      });
+    }
+  });
+
+export type ExtensionPropDescriptor = z.infer<typeof ExtensionPropDescriptorSchema>;
+
+export const ExtensionSchema = z.object({
+  /**
+   * Bare import specifier emitted by codegen. Examples:
+   *   "@/components/data-table"     — alias-based relative path
+   *   "../components/PriceChart"    — relative path
+   *   "@acme/charts"                — npm package
+   */
+  importPath: z.string().min(1),
+  /**
+   * UI vs typography. Drives the Library tab grouping; defaults to
+   * "ui" when omitted.
+   */
+  category: z.enum(["ui", "typography"]).optional(),
+  /** Free-form description shown in the Library detail page. */
+  description: z.string().optional(),
+  /** Schema of props the canvas inspector + agent both consume. */
+  props: z.array(ExtensionPropDescriptorSchema),
+  /**
+   * Marks how the agent registered this extension. "agent" is the
+   * common case (via `add_extension` MCP tool); "manual" indicates the
+   * user edited config.json directly. Today purely informational —
+   * affects nothing in code.
+   */
+  origin: z.enum(["agent", "manual"]).optional(),
+  /**
+   * How the canvas previews this extension node.
+   *   "static" (default) — labelled placeholder card (Tier 1).
+   *   "live"             — the real component is bundled from the host
+   *                        app and client-mounted into a SSR marker
+   *                        ("live island"). Used for charts and other
+   *                        components whose visual fidelity needs the
+   *                        actual implementation. Falls back to the
+   *                        placeholder if the bundle/render fails.
+   * Optional, absent ⇒ "static". Never written when static so existing
+   * `config.json` files round-trip unchanged.
+   */
+  render: z.enum(["static", "live"]).optional(),
+  /**
+   * Which host app this component lives in — a key into `config.hostApps`
+   * (monorepos only). A `render:"live"` island bundles its `importPath`
+   * against that app's root/aliases and mounts with that app's React copy.
+   * Absent ⇒ the folder default (`config.hostApp`), which is every
+   * single-app folder.
+   */
+  app: z.string().min(1).optional(),
+  /**
+   * How a `render:"live"` island is sized on the canvas.
+   *   "aspect-video" (default) — wrapper locks a 16:9 box (`aspect-video
+   *                              w-full`); right for charts that fill their
+   *                              container via a responsive container.
+   *   "content"                — wrapper imposes no ratio (`w-full` only) and
+   *                              grows to the component's intrinsic height. Use
+   *                              for a fixed-height chart (a recharts
+   *                              `ResponsiveContainer height={300}`) or an
+   *                              `absolute inset-0` overlay that the 16:9 box
+   *                              would misalign.
+   * Optional, absent ⇒ "aspect-video". Only meaningful when render:"live".
+   */
+  fit: z.enum(["aspect-video", "content"]).optional(),
+});
+
+export type Extension = z.infer<typeof ExtensionSchema>;