velloo 0.1.0 → 0.3.0

package/pkgs/schema/src/index.ts

@@ -66,6 +66,10 @@ export {
   type ExtensionPropDescriptor,
   ExtensionPropDescriptorSchema,
   ExtensionSchema,
+  type RepoComponentOverride,
+  RepoComponentOverrideSchema,
+  type RepoComponentsManifest,
+  RepoComponentsManifestSchema,
 } from "./extension.ts";
 export {
   type Frame,
@@ -77,9 +81,11 @@ export {
 export { pascalizeIconName } from "./icon-name.ts";
 export { type ResourceId, ResourceIdSchema } from "./ids.ts";
 export {
+  APP_PATH_PREFIX,
   CURRENT_SCHEMA_VERSION,
   FOLDER_MIGRATIONS,
   type FolderMigration,
+  type MigrationContext,
   type MigrationRun,
   planMigration,
   schemaVersionOf,
@@ -88,20 +94,32 @@ export {
   type ComponentNode,
   isComponentNode,
   isParamRef,
+  isRepoNode,
   isSnippetInstance,
   type Node,
   NodeIdSchema,
   NodeSchema,
   nodeId,
   type ParamRef,
+  parseRepoKey,
+  type RepoComponentRef,
+  RepoComponentRefSchema,
+  repoImportIssue,
+  repoKey,
   type SnippetInstance,
 } from "./node.ts";
 export {
+  DesignNameSchema,
+  designNameIssue,
   type FeedbackPrefs,
   FeedbackPrefsSchema,
+  isDesignName,
+  type NormalizedRepoManifest,
+  normalizeRepoManifest,
   REPO_MANIFEST_FILE,
   type RepoManifest,
   RepoManifestSchema,
+  toDesignName,
 } from "./repo.ts";
 export { type Screen, ScreenSchema } from "./screen.ts";
 export { type Snippet, type SnippetParam, SnippetParamSchema, SnippetSchema } from "./snippet.ts";

package/pkgs/schema/src/migrate.ts

@@ -24,9 +24,14 @@
  *       `letterSpacing` records are gone and `typography` parses strictly, so
  *       a v2 theme file is now a hard validation failure rather than dead
  *       weight — hence the version gate.
+ *   4 — designs carry their own `name` (formerly the `velloo.json` project
+ *       key or a local record's `projectName`), and app-relative paths use the
+ *       `app:` prefix instead of `project:`.
  */
 
-export const CURRENT_SCHEMA_VERSION = 3;
+import { isDesignName, toDesignName } from "./repo.ts";
+
+export const CURRENT_SCHEMA_VERSION = 4;
 
 /**
  * Read the format version off a raw (unvalidated) config object. Historical
@@ -41,19 +46,32 @@ export function schemaVersionOf(rawConfig: unknown): number {
 
 type RawObject = Record<string, unknown>;
 
+/**
+ * Facts a pure migration can't read for itself. The CLI's upgrade supplies
+ * them from the files around the folder.
+ */
+export interface MigrationContext {
+  /** The design's name as its registration recorded it. */
+  name?: string | undefined;
+}
+
 export interface FolderMigration {
   /** Migrates from exactly this version to `from + 1`. */
   from: number;
   /** One-line, user-facing description (printed by `velloo upgrade`). */
   summary: string;
   /** Transform the raw config.json object (already shallow-cloned). */
-  config?(raw: RawObject): RawObject;
+  config?(raw: RawObject, context: MigrationContext): RawObject;
   /** Transform one annotation entry from a `screens/<id>.annotations.json` sidecar. */
   annotation?(raw: RawObject): RawObject;
   /** Transform one `theme/<name>.json` document. */
   theme?(raw: RawObject): RawObject;
 }
 
+/** Prefix of a path resolved from the design's application root. */
+export const APP_PATH_PREFIX = "app:";
+const LEGACY_APP_PREFIX = "project:";
+
 /** Library id assigned to a legacy single-library config when it is promoted. */
 const LEGACY_LIBRARY_KEY = "default";
 
@@ -194,6 +212,41 @@ export const FOLDER_MIGRATIONS: FolderMigration[] = [
       return { ...raw, typography: next };
     },
   },
+  {
+    from: 3,
+    summary: "the design's name moves into its config; `project:` paths become `app:`",
+    config(raw, context) {
+      const out: RawObject = { ...raw, schemaVersion: 4 };
+      if (typeof out.name !== "string" || !isDesignName(out.name)) {
+        out.name = (context.name && toDesignName(context.name)) ?? "design";
+      }
+      const toApp = (path: unknown) =>
+        typeof path === "string" && path.startsWith(LEGACY_APP_PREFIX)
+          ? `${APP_PATH_PREFIX}${path.slice(LEGACY_APP_PREFIX.length)}`
+          : path;
+      const hostApp = asObject(out.hostApp);
+      if (hostApp) out.hostApp = { ...hostApp, root: toApp(hostApp.root) };
+      const hostApps = asObject(out.hostApps);
+      if (hostApps) {
+        out.hostApps = Object.fromEntries(
+          Object.entries(hostApps).map(([key, app]) => {
+            const entry = asObject(app);
+            return [key, entry ? { ...entry, root: toApp(entry.root) } : app];
+          }),
+        );
+      }
+      const libraries = asObject(out.libraries);
+      if (libraries) {
+        out.libraries = Object.fromEntries(
+          Object.entries(libraries).map(([key, lib]) => {
+            const entry = asObject(lib);
+            return [key, entry ? { ...entry, componentsPath: toApp(entry.componentsPath) } : lib];
+          }),
+        );
+      }
+      return out;
+    },
+  },
 ];
 
 export interface MigrationRun {
@@ -216,7 +269,7 @@ export interface MigrationRun {
  * (version > current) — the caller should tell the user to upgrade velloo —
  * or when the chain has a gap (a bug in this module).
  */
-export function planMigration(rawConfig: unknown): MigrationRun {
+export function planMigration(rawConfig: unknown, context: MigrationContext = {}): MigrationRun {
   const from = schemaVersionOf(rawConfig);
   if (from > CURRENT_SCHEMA_VERSION) {
     throw new Error(
@@ -231,7 +284,7 @@ export function planMigration(rawConfig: unknown): MigrationRun {
   }
   let config = { ...((rawConfig ?? {}) as RawObject) };
   for (const step of steps) {
-    if (step.config) config = step.config(config);
+    if (step.config) config = step.config(config, context);
   }
   // Even a no-step run normalizes the version field so `upgrade` is idempotent.
   config.schemaVersion = CURRENT_SCHEMA_VERSION;

package/pkgs/schema/src/node.ts

@@ -47,6 +47,37 @@ export type ComponentNode = {
    * capture → design → emit. Absent ⇒ the node emits as itself.
    */
   $emitAs?: { name: string; importPath: string } | undefined;
+  /**
+   * Repository component identity: this node IS a component the host app
+   * imports (a package export such as Mantine's `Tabs`, or the app's own
+   * `StatCard`), not a library component. `$ref` stays the JSX name codegen
+   * prints; the identity decides rendering and imports. Takes precedence over
+   * any provider component or extension of the same name, so shadowing is
+   * explicit on the node rather than a registry-order accident.
+   */
+  $repo?: RepoComponentRef | undefined;
+};
+
+/**
+ * Where a repository component comes from. The import form is kept exactly as
+ * code generation must print it; the resolved file is runtime cache data and
+ * never persisted.
+ */
+export type RepoComponentRef = {
+  /**
+   * Module specifier. Bare (`@mantine/core`) and aliased (`@/components/card`)
+   * specifiers are kept as the app writes them; a `./`-relative one is relative
+   * to the host app root, since the importing file varies per call site.
+   */
+  importPath: string;
+  /** The export binding, or `"default"` for a default export. */
+  exportName: string;
+  /** Static member path of a compound part: `"List"` for `Tabs.List`. */
+  member?: string | undefined;
+  /** `config.hostApps` key in a monorepo; absent ⇒ the default host app. */
+  app?: string | undefined;
+  /** Snippet id drawn in the component's place when it can't render for real. */
+  proxy?: string | undefined;
 };
 
 export type SnippetInstance = {
@@ -126,6 +157,42 @@ const EmitAsSchema = z.object({
   importPath: z.string().min(1),
 });
 
+/**
+ * A specifier codegen may print verbatim inside `import … from "…"` and the
+ * bundler may resolve against the host app. Conservative charset (no quotes,
+ * spaces, semicolons), and no absolute or `..` paths: a design folder is data a
+ * cloned repo supplies, and it must not be able to reach outside the app.
+ */
+export function repoImportIssue(importPath: string): string | null {
+  if (!/^[\w@./~-]+$/.test(importPath)) return "has characters an import specifier can't carry";
+  if (importPath.startsWith("/")) return "must not be an absolute path";
+  if (importPath.split("/").includes("..")) return "must not climb out of the host app with ..";
+  return null;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+export const RepoComponentRefSchema = z.object({
+  importPath: z
+    .string()
+    .min(1)
+    .superRefine((value, ctx) => {
+      const issue = repoImportIssue(value);
+      if (issue) ctx.addIssue({ code: "custom", message: `importPath ${issue}` });
+    }),
+  exportName: z
+    .string()
+    .regex(IDENTIFIER, { message: 'exportName must be an identifier or "default"' }),
+  member: z
+    .string()
+    .regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/, {
+      message: 'member must be a dotted identifier path like "List"',
+    })
+    .optional(),
+  app: z.string().min(1).optional(),
+  proxy: z.string().min(1).optional(),
+});
+
 const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
   z.object({
     $ref: z.string().min(1),
@@ -136,9 +203,41 @@ const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
       .transform((items) => items.map(wrapScalarChild))
       .optional(),
     $emitAs: EmitAsSchema.optional(),
+    $repo: RepoComponentRefSchema.optional(),
   }),
 );
 
+/** True when the node is a repository component (see ComponentNode.$repo). */
+export function isRepoNode(n: Node): n is ComponentNode & { $repo: RepoComponentRef } {
+  return isComponentNode(n) && n.$repo !== undefined;
+}
+
+/**
+ * The runtime key a repository component registers under — identity only, so
+ * two apps' `Button`s (or Mantine's vs the provider's) never collide.
+ */
+export function repoKey(ref: RepoComponentRef): string {
+  const member = ref.member ? `.${ref.member}` : "";
+  return `repo:${encodeURIComponent(ref.app ?? "")}:${ref.importPath}#${ref.exportName}${member}`;
+}
+
+/**
+ * Invert {@link repoKey}. A bundle URL carries only keys, so the runtime can
+ * resolve a screen's components from identity alone — no catalog lookup, which
+ * keeps a design renderable while discovery is cold or the app has moved on.
+ */
+export function parseRepoKey(key: string): RepoComponentRef | null {
+  const match = /^repo:([^:]*):([^#]+)#([A-Za-z_$][\w$]*)(?:\.(.+))?$/.exec(key);
+  if (!match) return null;
+  const parsed = RepoComponentRefSchema.safeParse({
+    importPath: match[2],
+    exportName: match[3],
+    ...(match[4] ? { member: match[4] } : {}),
+    ...(match[1] ? { app: decodeURIComponent(match[1]) } : {}),
+  });
+  return parsed.success ? parsed.data : null;
+}
+
 const SnippetInstanceSchema: z.ZodType<SnippetInstance> = z.object({
   $snippet: z.string().min(1),
   $id: NodeIdSchema.optional(),

package/pkgs/schema/src/repo.ts

@@ -18,35 +18,117 @@ export const FeedbackPrefsSchema = z.object({
 
 export type FeedbackPrefs = z.infer<typeof FeedbackPrefsSchema>;
 
-const PROJECT_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const MAX_DESIGN_NAME = 80;
 
 /**
- * The repo-root `velloo.json`. It names a repo's design folders so a monorepo
- * can hold several, and carries the handful of preferences that belong to the
- * repo rather than to any one design folder — feedback consent is answered
- * once per person, not once per canvas.
- *
- * Design settings still live in each folder's `.design/config.json`; nothing
- * here duplicates that contract.
+ * Why `name` can't name a design, or null when it can. Almost anything goes —
+ * spaces, emoji, any script. The limits are the ones a name typed as a command
+ * argument needs: no path separator (a bare argument with one is read as a
+ * path), no control characters, nothing that is only whitespace or a dot
+ * path, and no padding a shell would silently strip.
+ */
+export function designNameIssue(name: string): string | null {
+  if (name.trim() === "") return "a design name can't be empty";
+  if (name !== name.trim()) return "a design name can't start or end with spaces";
+  if (name === "." || name === "..") return `"${name}" can't be a design name`;
+  if (/[/\\]/.test(name)) return "a design name can't contain / or \\";
+  if (/\p{Cc}/u.test(name)) return "a design name can't contain control characters";
+  if ([...name].length > MAX_DESIGN_NAME)
+    return `a design name can't be longer than ${MAX_DESIGN_NAME} characters`;
+  return null;
+}
+
+export function isDesignName(name: string): boolean {
+  return designNameIssue(name) === null;
+}
+
+/** A Zod string that must be a design name, with the specific reason when it isn't. */
+export const DesignNameSchema = z.string().superRefine((name, ctx) => {
+  const issue = designNameIssue(name);
+  if (issue) ctx.addIssue({ code: "custom", message: issue });
+});
+
+/**
+ * Coerce free text (a directory name, an app name) into a valid design name,
+ * or null when nothing usable is left.
+ */
+export function toDesignName(text: string): string | null {
+  const cleaned = [...text.replace(/[/\\\p{Cc}]+/gu, " ").trim()]
+    .slice(0, MAX_DESIGN_NAME)
+    .join("")
+    .trim();
+  return cleaned && isDesignName(cleaned) ? cleaned : null;
+}
+
+/**
+ * The repo-root `velloo.json`. It lists a repo's designs so a monorepo can
+ * hold several, and carries the handful of preferences that belong to the
+ * repo rather than to any one design — feedback consent is answered once per
+ * person, not once per canvas.
  *
- * Every project is a path to a design folder inside the repository. A design
+ * Only locations live here: each design's name and settings are in its own
+ * `.design/config.json`, so nothing here can drift from the design itself.
+ * Every entry is a path to a design folder inside the repository. A design
  * kept outside it is recorded only on the machine that has it, never here.
  */
 export const RepoManifestSchema = z
   .object({
     $schema: z.string().optional(),
-    projects: z.record(
-      z.string().regex(PROJECT_NAME, "project names are letters/digits plus . _ -"),
-      z.string().min(1),
-    ),
-    defaultProject: z.string().optional(),
+    designs: z.array(z.string().min(1)),
+    /** The name of the design a bare command resolves to when nothing else picks one. */
+    defaultDesign: DesignNameSchema.optional(),
     feedback: FeedbackPrefsSchema.optional(),
   })
-  .refine((m) => !m.defaultProject || m.defaultProject in m.projects, {
-    message: "defaultProject must name an entry in projects",
+  .refine((m) => new Set(m.designs).size === m.designs.length, {
+    message: "designs lists the same path twice",
   });
 
 export type RepoManifest = z.infer<typeof RepoManifestSchema>;
 
 /** Filename of the repo-root manifest, resolved by walking up from a folder. */
 export const REPO_MANIFEST_FILE = "velloo.json";
+
+export interface NormalizedRepoManifest {
+  /** The manifest in the current shape, ready for {@link RepoManifestSchema}. */
+  manifest: unknown;
+  /**
+   * Names the pre-v4 `projects` map gave each path. A folder not yet migrated
+   * has no `name` in its config, so these stand in until `velloo upgrade`
+   * writes them there.
+   */
+  legacyNames: Record<string, string>;
+  /** True when the file was in the pre-v4 shape and should be rewritten. */
+  legacy: boolean;
+}
+
+/**
+ * Read either manifest shape. Before designs carried their own names the file
+ * was `{ projects: { name: path }, defaultProject }`; the schema would silently
+ * drop those keys, so they are converted here, before parsing.
+ */
+export function normalizeRepoManifest(raw: unknown): NormalizedRepoManifest {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { manifest: raw, legacyNames: {}, legacy: false };
+  }
+  const { projects, defaultProject, ...rest } = raw as Record<string, unknown>;
+  if (projects === undefined || "designs" in rest) {
+    return { manifest: raw, legacyNames: {}, legacy: false };
+  }
+  const legacyNames: Record<string, string> = {};
+  const designs: unknown[] = [];
+  if (typeof projects === "object" && projects !== null && !Array.isArray(projects)) {
+    for (const [name, path] of Object.entries(projects)) {
+      designs.push(path);
+      if (typeof path === "string") legacyNames[path] = name;
+    }
+  }
+  return {
+    manifest: {
+      ...rest,
+      designs,
+      ...(defaultProject !== undefined ? { defaultDesign: defaultProject } : {}),
+    },
+    legacyNames,
+    legacy: true,
+  };
+}

package/pkgs/schema/src/screen.ts

@@ -24,6 +24,13 @@ export const ScreenSchema = z.object({
    * components and extensions resolve against this library's registry.
    */
   library: z.string().min(1).optional(),
+  /**
+   * The app route this screen stands for ("/", "/settings/account"). Set by
+   * the route scan `init` runs, and editable per screen. The canvas mount
+   * hands it to the host framework's router contexts, so a repository nav
+   * lights the item the real page would.
+   */
+  route: z.string().min(1).optional(),
   tree: NodeSchema,
 });