minutework 0.1.40 → 0.1.41

package/assets/templates/vuilder-shell/template.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://minutework.dev/schemas/runtime/builder/template.schema.json",
+  "title": "Runtime Builder Template Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "template_id",
+    "template_kind",
+    "template_profile",
+    "template_version",
+    "materialize",
+    "builder_edit_mode",
+    "seed_source",
+    "required_bootstrap_steps",
+    "example_features"
+  ],
+  "properties": {
+    "template_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "template_kind": {
+      "type": "string",
+      "enum": [
+        "sidecar_nextjs_private",
+        "sidecar_fastapi_internal",
+        "combined_web",
+        "public_site",
+        "vuilder_shell"
+      ]
+    },
+    "template_profile": {
+      "type": "string",
+      "enum": [
+        "platform_session_bff",
+        "vuilder_shell_token",
+        "tenant_web_auth_sdk",
+        "bridge_internal",
+        "public_dj_cms"
+      ]
+    },
+    "template_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "materialize": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "destination"
+      ],
+      "properties": {
+        "destination": {
+          "type": "string",
+          "enum": [
+            "app",
+            "sidecar",
+            "vuilder-app",
+            "vuilder-shell"
+          ]
+        }
+      }
+    },
+    "builder_edit_mode": {
+      "type": "string",
+      "const": "workspace_copy_only"
+    },
+    "seed_source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "template_bundle_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "required_bootstrap_steps": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "next_typegen",
+          "design_system_tokens",
+          "python_env_sync",
+          "python_import_smoke"
+        ]
+      }
+    },
+    "runtime_contract_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "sidecar_processes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/sidecarProcess"
+      }
+    },
+    "example_features": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/exampleFeature"
+      }
+    }
+  },
+  "$defs": {
+    "exampleFeature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "default_enabled"
+      ],
+      "properties": {
+        "default_enabled": {
+          "type": "boolean"
+        }
+      }
+    },
+    "sidecarProcess": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "process_type",
+        "entrypoint",
+        "composition_profiles"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "process_type": {
+          "type": "string",
+          "enum": [
+            "fastapi",
+            "worker",
+            "cron"
+          ]
+        },
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1
+        },
+        "health_check_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "composition_profiles": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "worker_only",
+              "internal_api_only",
+              "worker_plus_internal_api"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/assets/templates/vuilder-shell/test/server-only-stub.ts

@@ -0,0 +1 @@
+export {};

package/assets/templates/vuilder-shell/tools/design-system/build-token-manifest.mjs

@@ -0,0 +1,3 @@
+import { buildTokenManifest } from "./checks.mjs";
+
+buildTokenManifest();

package/assets/templates/vuilder-shell/tools/design-system/check-imports.mjs

@@ -0,0 +1,9 @@
+import { checkImports } from "./checks.mjs";
+import { parseCliArgs, resolveTargetFiles } from "./shared.mjs";
+
+const options = parseCliArgs();
+const violations = checkImports(resolveTargetFiles(options));
+
+if (violations.length > 0) {
+  process.exit(1);
+}

package/assets/templates/vuilder-shell/tools/design-system/check-stories.mjs

@@ -0,0 +1,9 @@
+import { checkStories } from "./checks.mjs";
+import { parseCliArgs, resolveTargetFiles } from "./shared.mjs";
+
+const options = parseCliArgs();
+const violations = checkStories(resolveTargetFiles(options), options);
+
+if (violations.length > 0) {
+  process.exit(1);
+}

package/assets/templates/vuilder-shell/tools/design-system/check-values.mjs

@@ -0,0 +1,9 @@
+import { checkValues } from "./checks.mjs";
+import { parseCliArgs, resolveTargetFiles } from "./shared.mjs";
+
+const options = parseCliArgs();
+const violations = checkValues(resolveTargetFiles(options));
+
+if (violations.length > 0) {
+  process.exit(1);
+}

package/assets/templates/vuilder-shell/tools/design-system/checks.mjs

@@ -0,0 +1,238 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+
+import {
+  absolutePath,
+  arbitraryVisualUtilityPattern,
+  isFeatureSurfaceFile,
+  isGovernedVisualFile,
+  isLegacyUiImport,
+  isTokenFile,
+  literalStyleVisualPattern,
+  matchesPattern,
+  normalizePath,
+  rawColorPattern,
+} from "./shared.mjs";
+
+function readFile(filePath) {
+  return readFileSync(absolutePath(filePath), "utf8");
+}
+
+function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+function reportViolations(title, violations) {
+  if (violations.length === 0) {
+    return;
+  }
+
+  console.error(`\n${title}`);
+  for (const violation of violations) {
+    console.error(`- ${violation}`);
+  }
+}
+
+function parseCssVariables(filePath) {
+  const content = readFile(filePath);
+  const matches = [...content.matchAll(/--([\w-]+):\s*([^;]+);/g)];
+
+  return Object.fromEntries(matches.map((match) => [match[1], match[2].trim()]));
+}
+
+function fileExists(filePath) {
+  try {
+    readFileSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function buildTokenManifest() {
+  const manifest = {
+    foundation: parseCssVariables("src/design-system/tokens/foundation.css"),
+    semantic: parseCssVariables("src/design-system/tokens/semantic.css"),
+  };
+
+  const jsonOutputPath = absolutePath("src/design-system/tokens/manifest.json");
+  const tsOutputPath = absolutePath("src/design-system/tokens/manifest.ts");
+  const serializedManifest = JSON.stringify(manifest, null, 2);
+
+  writeFileSync(jsonOutputPath, ensureTrailingNewline(serializedManifest));
+  writeFileSync(
+    tsOutputPath,
+    ensureTrailingNewline(
+      `export const tokenManifest = ${serializedManifest} as const\n\nexport default tokenManifest`,
+    ),
+  );
+
+  return manifest;
+}
+
+export function checkImports(targetFiles) {
+  const violations = [];
+  const importPattern =
+    /(?:import|export)\s[\s\S]*?from\s+['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+  for (const filePath of targetFiles) {
+    if (!isFeatureSurfaceFile(filePath)) {
+      continue;
+    }
+
+    const content = readFile(filePath);
+    const matches = [...content.matchAll(importPattern)];
+
+    for (const match of matches) {
+      const specifier = match[1] ?? match[2];
+      if (!specifier) {
+        continue;
+      }
+
+      if (isLegacyUiImport(specifier)) {
+        violations.push(
+          `${normalizePath(filePath)} imports ${specifier}; use @/design-system/primitives/* instead.`,
+        );
+      }
+
+      if (specifier.startsWith("@radix-ui/")) {
+        violations.push(
+          `${normalizePath(filePath)} imports ${specifier}; Radix primitives are only allowed inside src/design-system.`,
+        );
+      }
+
+      if (specifier === "class-variance-authority") {
+        violations.push(
+          `${normalizePath(filePath)} imports class-variance-authority; recipes belong in src/design-system/recipes.`,
+        );
+      }
+
+      if (
+        specifier === "@/design-system/tokens" ||
+        (specifier.startsWith("@/design-system/tokens/") &&
+          specifier !== "@/design-system/tokens/manifest")
+      ) {
+        violations.push(
+          `${normalizePath(filePath)} imports ${specifier}; feature code must consume semantic classes or @/design-system/tokens/manifest only.`,
+        );
+      }
+    }
+  }
+
+  reportViolations("Design-system import violations:", violations);
+  return violations;
+}
+
+export function checkValues(targetFiles) {
+  const violations = [];
+
+  for (const filePath of targetFiles) {
+    if (!isGovernedVisualFile(filePath) || isTokenFile(filePath)) {
+      continue;
+    }
+
+    const content = readFile(filePath);
+
+    if (matchesPattern(rawColorPattern, content)) {
+      violations.push(
+        `${normalizePath(filePath)} contains raw color literals; move those values into src/design-system/tokens.`,
+      );
+    }
+
+    if (matchesPattern(arbitraryVisualUtilityPattern, content)) {
+      violations.push(
+        `${normalizePath(filePath)} contains arbitrary visual utilities such as bg-[...] or text-[...]; use tokens or recipes instead.`,
+      );
+    }
+
+    if (matchesPattern(literalStyleVisualPattern, content)) {
+      violations.push(
+        `${normalizePath(filePath)} contains inline style color values; use CSS variables or semantic classes instead.`,
+      );
+    }
+  }
+
+  reportViolations("Design-system value violations:", violations);
+  return violations;
+}
+
+export function checkStories(targetFiles, { staged = false } = {}) {
+  const publicDirectories = [
+    "src/design-system/primitives",
+    "src/design-system/patterns",
+  ];
+  const storySensitivePaths = new Set(
+    targetFiles.filter((filePath) =>
+      publicDirectories.some((directory) => filePath.startsWith(directory)),
+    ),
+  );
+
+  if (staged && storySensitivePaths.size === 0) {
+    return [];
+  }
+
+  const violations = [];
+  const componentFiles = [];
+  const storyFiles = [];
+
+  for (const directory of publicDirectories) {
+    const stack = [absolutePath(directory)];
+
+    while (stack.length > 0) {
+      const currentDirectory = stack.pop();
+      if (!currentDirectory) {
+        continue;
+      }
+
+      const directoryEntries = readdirSync(currentDirectory, {
+        withFileTypes: true,
+      });
+
+      for (const entry of directoryEntries) {
+        const absoluteEntryPath = `${currentDirectory}/${entry.name}`;
+        if (entry.isDirectory()) {
+          stack.push(absoluteEntryPath);
+          continue;
+        }
+
+        const normalizedPath = normalizePath(absoluteEntryPath);
+        if (!normalizedPath.endsWith(".ts") && !normalizedPath.endsWith(".tsx")) {
+          continue;
+        }
+
+        if (normalizedPath.includes(".stories.")) {
+          storyFiles.push(normalizedPath);
+          continue;
+        }
+
+        componentFiles.push(normalizedPath);
+      }
+    }
+  }
+
+  for (const componentFile of componentFiles) {
+    const tsxStoryPath = absolutePath(componentFile.replace(/\.(ts|tsx)$/, ".stories.tsx"));
+    const mdxStoryPath = absolutePath(componentFile.replace(/\.(ts|tsx)$/, ".stories.mdx"));
+
+    if (!fileExists(tsxStoryPath) && !fileExists(mdxStoryPath)) {
+      violations.push(
+        `${componentFile} is missing a colocated .stories.tsx or .stories.mdx file.`,
+      );
+    }
+  }
+
+  for (const storyFile of storyFiles) {
+    const componentTsPath = absolutePath(storyFile.replace(/\.stories\.(tsx|mdx)$/, ".ts"));
+    const componentTsxPath = absolutePath(
+      storyFile.replace(/\.stories\.(tsx|mdx)$/, ".tsx"),
+    );
+
+    if (!fileExists(componentTsPath) && !fileExists(componentTsxPath)) {
+      violations.push(
+        `${storyFile} is orphaned; add the matching component file or remove the story.`,
+      );
+    }
+  }
+
+  reportViolations("Design-system story coverage violations:", violations);
+  return violations;
+}

package/assets/templates/vuilder-shell/tools/design-system/eslint-plugin-design-system.mjs

@@ -0,0 +1,184 @@
+import {
+  arbitraryVisualUtilityPattern,
+  isFeatureSurfaceFile,
+  matchesPattern,
+  rawColorPattern,
+} from "./shared.mjs";
+
+function filenameOf(context) {
+  return context.filename ?? context.getFilename();
+}
+
+function stringValueFromNode(node) {
+  if (!node) {
+    return null;
+  }
+
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
+  }
+
+  if (node.type === "TemplateElement") {
+    return node.value.raw;
+  }
+
+  return null;
+}
+
+function reportIfPatternMatches(context, node, pattern, message) {
+  const value = stringValueFromNode(node);
+  if (!value || !matchesPattern(pattern, value)) {
+    return;
+  }
+
+  context.report({
+    node,
+    message,
+  });
+}
+
+const noDesignSystemBypassImports = {
+  meta: {
+    type: "problem",
+    schema: [],
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (!isFeatureSurfaceFile(filenameOf(context))) {
+          return;
+        }
+
+        const source = node.source.value;
+        if (typeof source !== "string") {
+          return;
+        }
+
+        if (source.startsWith("@/components/ui/")) {
+          context.report({
+            node,
+            message:
+              "Use @/design-system/primitives/* instead of importing from @/components/ui/* in feature code.",
+          });
+        }
+
+        if (source.startsWith("@radix-ui/")) {
+          context.report({
+            node,
+            message:
+              "Radix imports are only allowed inside src/design-system; feature code must import public design-system primitives.",
+          });
+        }
+
+        if (
+          source === "@/design-system/tokens" ||
+          (source.startsWith("@/design-system/tokens/") &&
+            source !== "@/design-system/tokens/manifest")
+        ) {
+          context.report({
+            node,
+            message:
+              "Feature code cannot import raw token modules directly; use semantic classes or @/design-system/tokens/manifest.",
+          });
+        }
+      },
+    };
+  },
+};
+
+const noCvaOutsideDesignSystem = {
+  meta: {
+    type: "problem",
+    schema: [],
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (!isFeatureSurfaceFile(filenameOf(context))) {
+          return;
+        }
+
+        if (node.source.value === "class-variance-authority") {
+          context.report({
+            node,
+            message:
+              "Feature code cannot import class-variance-authority directly; use recipes from src/design-system/recipes.",
+          });
+        }
+      },
+    };
+  },
+};
+
+const noRawDesignValues = {
+  meta: {
+    type: "problem",
+    schema: [],
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        reportIfPatternMatches(
+          context,
+          node,
+          rawColorPattern,
+          "Raw color literals are forbidden outside src/design-system/tokens.",
+        );
+      },
+      TemplateElement(node) {
+        reportIfPatternMatches(
+          context,
+          node,
+          rawColorPattern,
+          "Raw color literals are forbidden outside src/design-system/tokens.",
+        );
+      },
+    };
+  },
+};
+
+const noBespokeVisualStacksInFeatures = {
+  meta: {
+    type: "problem",
+    schema: [],
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (!isFeatureSurfaceFile(filenameOf(context))) {
+          return;
+        }
+
+        reportIfPatternMatches(
+          context,
+          node,
+          arbitraryVisualUtilityPattern,
+          "Feature code cannot use arbitrary visual Tailwind utilities; use tokens or design-system recipes instead.",
+        );
+      },
+      TemplateElement(node) {
+        if (!isFeatureSurfaceFile(filenameOf(context))) {
+          return;
+        }
+
+        reportIfPatternMatches(
+          context,
+          node,
+          arbitraryVisualUtilityPattern,
+          "Feature code cannot use arbitrary visual Tailwind utilities; use tokens or design-system recipes instead.",
+        );
+      },
+    };
+  },
+};
+
+const designSystemPlugin = {
+  rules: {
+    "no-design-system-bypass-imports": noDesignSystemBypassImports,
+    "no-cva-outside-design-system": noCvaOutsideDesignSystem,
+    "no-raw-design-values": noRawDesignValues,
+    "no-bespoke-visual-stacks-in-features": noBespokeVisualStacksInFeatures,
+  },
+};
+
+export default designSystemPlugin;

package/assets/templates/vuilder-shell/tools/design-system/playwright.config.mjs

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { defineConfig, devices } from "@playwright/test";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "../..");
+
+export default defineConfig({
+  testDir: __dirname,
+  testMatch: "visual.spec.ts",
+  fullyParallel: true,
+  retries: 0,
+  reporter: "line",
+  snapshotPathTemplate: "{testDir}/__screenshots__/{testFilePath}/{arg}{ext}",
+  use: {
+    baseURL: "http://127.0.0.1:6007",
+    trace: "on-first-retry",
+  },
+  webServer: {
+    command: "pnpm exec http-server ./storybook-static -p 6007 -s",
+    cwd: repoRoot,
+    url: "http://127.0.0.1:6007",
+    reuseExistingServer: !process.env.CI,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: {
+        ...devices["Desktop Chrome"],
+      },
+    },
+  ],
+});

package/assets/templates/vuilder-shell/tools/design-system/run-checks.mjs

@@ -0,0 +1,22 @@
+import {
+  buildTokenManifest,
+  checkImports,
+  checkStories,
+  checkValues,
+} from "./checks.mjs";
+import { parseCliArgs, resolveTargetFiles } from "./shared.mjs";
+
+const options = parseCliArgs();
+const targetFiles = resolveTargetFiles(options);
+
+buildTokenManifest();
+
+const violations = [
+  ...checkImports(targetFiles),
+  ...checkValues(targetFiles),
+  ...checkStories(targetFiles, options),
+];
+
+if (violations.length > 0) {
+  process.exit(1);
+}