minutework 0.1.0

package/assets/templates/next-tenant-app/src/lib/theme.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  isThemeMode,
+  SYSTEM_THEME_QUERY,
+  THEME_COOKIE_NAME,
+  THEME_STORAGE_KEY,
+  type ResolvedTheme,
+  type ThemeMode,
+} from "@/lib/theme-config";
+
+type ThemeContextValue = {
+  theme: ThemeMode;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (theme: ThemeMode) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function getSystemTheme(): ResolvedTheme {
+  return window.matchMedia(SYSTEM_THEME_QUERY).matches ? "dark" : "light";
+}
+
+function resolveTheme(theme: ThemeMode, systemTheme: ResolvedTheme): ResolvedTheme {
+  return theme === "system" ? systemTheme : theme;
+}
+
+function applyThemeToDocument(resolvedTheme: ResolvedTheme, attribute: string) {
+  const root = document.documentElement;
+
+  if (attribute === "class") {
+    root.classList.remove("light", "dark");
+    root.classList.add(resolvedTheme);
+  } else {
+    root.setAttribute(attribute, resolvedTheme);
+  }
+
+  root.style.colorScheme = resolvedTheme;
+}
+
+function disableTransitionsTemporarily() {
+  const style = document.createElement("style");
+  style.appendChild(
+    document.createTextNode(
+      "*{-webkit-transition:none !important;transition:none !important}",
+    ),
+  );
+  document.head.appendChild(style);
+
+  return () => {
+    window.getComputedStyle(document.body);
+    window.setTimeout(() => {
+      style.remove();
+    }, 0);
+  };
+}
+
+export function ThemeProvider({
+  children,
+  attribute = "class",
+  defaultTheme = "system",
+  enableSystem = true,
+  disableTransitionOnChange = false,
+}: {
+  children: ReactNode;
+  attribute?: string;
+  defaultTheme?: ThemeMode;
+  enableSystem?: boolean;
+  disableTransitionOnChange?: boolean;
+}) {
+  const [theme, setThemeState] = useState<ThemeMode>(() => {
+    if (typeof window === "undefined") {
+      return defaultTheme;
+    }
+
+    try {
+      const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY);
+      if (isThemeMode(storedTheme)) {
+        return storedTheme;
+      }
+    } catch {}
+
+    return defaultTheme;
+  });
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(() => {
+    if (typeof window === "undefined") {
+      return "light";
+    }
+
+    return getSystemTheme();
+  });
+  const resolvedTheme = resolveTheme(
+    theme,
+    enableSystem ? systemTheme : ("light" as ResolvedTheme),
+  );
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(SYSTEM_THEME_QUERY);
+    const syncSystemTheme = () => {
+      setSystemTheme(mediaQuery.matches ? "dark" : "light");
+    };
+
+    syncSystemTheme();
+    mediaQuery.addEventListener("change", syncSystemTheme);
+
+    return () => {
+      mediaQuery.removeEventListener("change", syncSystemTheme);
+    };
+  }, []);
+
+  useEffect(() => {
+    const restoreTransitions = disableTransitionOnChange
+      ? disableTransitionsTemporarily()
+      : null;
+
+    applyThemeToDocument(resolvedTheme, attribute);
+
+    if (restoreTransitions) {
+      restoreTransitions();
+    }
+  }, [attribute, disableTransitionOnChange, resolvedTheme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      resolvedTheme,
+      setTheme: (nextTheme) => {
+        setThemeState(nextTheme);
+
+        try {
+          window.localStorage.setItem(THEME_STORAGE_KEY, nextTheme);
+          document.cookie = `${THEME_COOKIE_NAME}=${nextTheme}; path=/; max-age=31536000; SameSite=Lax`;
+        } catch {}
+      },
+    }),
+    [resolvedTheme, theme],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+
+  if (!context) {
+    throw new Error("useTheme must be used within ThemeProvider");
+  }
+
+  return context;
+}

package/assets/templates/next-tenant-app/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/assets/templates/next-tenant-app/template.json

@@ -0,0 +1,27 @@
+{
+  "template_id": "next-tenant-app",
+  "template_kind": "sidecar_nextjs_private",
+  "template_profile": "platform_session_bff",
+  "template_bundle_ref": "runtime/builder/templates/next-tenant-app",
+  "template_version": "0.2.0",
+  "materialize": {
+    "destination": "app"
+  },
+  "builder_edit_mode": "workspace_copy_only",
+  "seed_source": "apps/mw-next-client",
+  "required_bootstrap_steps": [
+    "next_typegen",
+    "design_system_tokens"
+  ],
+  "runtime_contract_refs": [
+    "reference/mwv3-dj6-docs/auth_and_credential_contract.md",
+    "reference/mwv3-dj6-docs/published_web_property_contract.md",
+    "reference/mwv3-dj6-docs/runtime_app_pack_contract.md",
+    "reference/mwv3-dj6-docs/runtime_compute_isolation_and_sandboxing_contract.md"
+  ],
+  "example_features": {
+    "runtime_command_demo": {
+      "default_enabled": false
+    }
+  }
+}

package/assets/templates/next-tenant-app/template.schema.json

@@ -0,0 +1,160 @@
+{
+  "$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"
+      ]
+    },
+    "template_profile": {
+      "type": "string",
+      "enum": [
+        "platform_session_bff",
+        "bridge_internal"
+      ]
+    },
+    "template_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "materialize": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "destination"
+      ],
+      "properties": {
+        "destination": {
+          "type": "string",
+          "const": "app"
+        }
+      }
+    },
+    "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/next-tenant-app/test/server-only-stub.ts

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

package/assets/templates/next-tenant-app/tools/design-system/build-token-manifest.mjs

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

package/assets/templates/next-tenant-app/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/next-tenant-app/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/next-tenant-app/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/next-tenant-app/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;
+}