minutework 0.1.40 → 0.1.41

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

@@ -0,0 +1,166 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+
+const SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".css",
+  ".mdx",
+]);
+
+const DEFAULT_ROOTS = ["src", "tools/design-system", ".storybook"];
+
+export const rawColorPattern = /#(?:[\da-fA-F]{3,8})\b|(?:rgb|hsl|oklch)a?\([^)]*\)/g;
+export const arbitraryVisualUtilityPattern =
+  /\b(?:bg|text|border|ring|shadow|from|to|via|fill|stroke)-\[[^\]]+\]/g;
+export const literalStyleVisualPattern =
+  /style=\{\{[^}]*\b(?:color|background(?:Color)?|border(?:Color)?|boxShadow|fill|stroke)\s*:\s*['"`](?!var\(--)[^'"`]+['"`]/gs;
+
+function toPosix(filePath) {
+  return filePath.split(sep).join("/");
+}
+
+export function normalizePath(filePath) {
+  return toPosix(relative(repoRoot, resolve(repoRoot, filePath)));
+}
+
+export function absolutePath(filePath) {
+  return resolve(repoRoot, filePath);
+}
+
+function walkDirectory(directoryPath) {
+  const entries = readdirSync(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absoluteEntryPath = join(directoryPath, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...walkDirectory(absoluteEntryPath));
+      continue;
+    }
+
+    if (SOURCE_EXTENSIONS.has(extname(entry.name))) {
+      files.push(normalizePath(absoluteEntryPath));
+    }
+  }
+
+  return files;
+}
+
+export function getSourceFiles() {
+  const files = new Set();
+
+  for (const root of DEFAULT_ROOTS) {
+    const absoluteRoot = absolutePath(root);
+    if (!existsSync(absoluteRoot) || !statSync(absoluteRoot).isDirectory()) {
+      continue;
+    }
+
+    for (const filePath of walkDirectory(absoluteRoot)) {
+      files.add(filePath);
+    }
+  }
+
+  return [...files].sort();
+}
+
+export function getStagedFiles() {
+  try {
+    const output = execFileSync(
+      "git",
+      ["diff", "--name-only", "--cached", "--diff-filter=ACMR"],
+      { cwd: repoRoot, encoding: "utf8" },
+    );
+
+    return output
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map(normalizePath);
+  } catch {
+    return [];
+  }
+}
+
+export function parseCliArgs(argv = process.argv.slice(2)) {
+  const options = {
+    staged: false,
+    files: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--staged") {
+      options.staged = true;
+      continue;
+    }
+
+    if (arg === "--files") {
+      options.files.push(...argv.slice(index + 1));
+      break;
+    }
+
+    options.files.push(arg);
+  }
+
+  return options;
+}
+
+export function resolveTargetFiles({ staged = false, files = [] } = {}) {
+  const candidates =
+    files.length > 0 ? files : staged ? getStagedFiles() : getSourceFiles();
+  const normalizedCandidates = candidates
+    .map(normalizePath)
+    .filter((candidate) => SOURCE_EXTENSIONS.has(extname(candidate)));
+
+  if (normalizedCandidates.length > 0) {
+    return [...new Set(normalizedCandidates)].sort();
+  }
+
+  return getSourceFiles();
+}
+
+export function isTokenFile(filePath) {
+  const normalizedPath = normalizePath(filePath);
+  return (
+    normalizedPath.startsWith("src/design-system/tokens/") &&
+    (normalizedPath.endsWith(".css") ||
+      normalizedPath.endsWith("/manifest.ts") ||
+      normalizedPath.endsWith("/manifest.json"))
+  );
+}
+
+export function isFeatureSurfaceFile(filePath) {
+  const normalizedPath = normalizePath(filePath);
+  return (
+    normalizedPath.startsWith("src/app/") ||
+    normalizedPath.startsWith("src/features/")
+  );
+}
+
+export function isGovernedVisualFile(filePath) {
+  const normalizedPath = normalizePath(filePath);
+  return (
+    normalizedPath.startsWith("src/app/") ||
+    normalizedPath.startsWith("src/features/") ||
+    normalizedPath.startsWith("src/design-system/")
+  );
+}
+
+export function isLegacyUiImport(specifier) {
+  return specifier.startsWith("@/components/ui/");
+}
+
+export function matchesPattern(pattern, value) {
+  pattern.lastIndex = 0;
+  return pattern.test(value);
+}

package/assets/templates/vuilder-shell/tools/design-system/visual.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+
+const storyCases = [
+  {
+    id: "design-system-primitives-button--primary",
+    name: "button-primary.png",
+    viewport: { width: 480, height: 220 },
+  },
+  {
+    id: "design-system-primitives-input--default",
+    name: "input-default.png",
+    viewport: { width: 520, height: 220 },
+  },
+  {
+    id: "design-system-patterns-panel-frame--raised",
+    name: "panel-frame-raised.png",
+    viewport: { width: 560, height: 340 },
+  },
+  {
+    id: "design-system-patterns-status-badge--all-tones",
+    name: "status-badge-tones.png",
+    viewport: { width: 520, height: 220 },
+  },
+  {
+    id: "design-system-patterns-theme-mode-toggle--default",
+    name: "theme-mode-toggle-default.png",
+    viewport: { width: 420, height: 260 },
+  },
+];
+
+for (const storyCase of storyCases) {
+  test(storyCase.id, async ({ page }) => {
+    await page.setViewportSize(storyCase.viewport);
+    await page.goto(`/iframe.html?id=${storyCase.id}&viewMode=story`);
+    await page.addStyleTag({
+      content:
+        "*{animation:none !important;transition:none !important;caret-color:transparent !important;}",
+    });
+    await expect(page.locator("#storybook-root")).toHaveScreenshot(storyCase.name);
+  });
+}

package/assets/templates/vuilder-shell/tools/template/validate-route-contract.mjs

@@ -0,0 +1,373 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templateRoot = path.resolve(__dirname, "..", "..");
+
+const requiredPaths = [
+  "src/app/w/[workspace_slug]/page.tsx",
+  "src/app/w/[workspace_slug]/connect/page.tsx",
+  "src/app/app/page.tsx",
+  "src/app/api/auth/accept-shell-session/route.ts",
+  "src/app/api/auth/session/route.ts",
+  "src/app/api/auth/logout/route.ts",
+  "src/app/login/route.ts",
+  "src/features/vuilder-shell/components/vuilder-workspace-screen.tsx",
+  "src/features/vuilder-shell/components/vuilder-connect-screen.tsx",
+  "src/lib/auth-routes.server.ts",
+  "src/lib/app-routes.ts",
+  "src/lib/platform/client.server.ts",
+  "src/lib/platform/contracts.ts",
+  "src/lib/platform/session.server.ts",
+];
+
+const forbiddenPaths = [
+  "src/app/api/auth/login/route.ts",
+  "src/features/auth/components/login-screen.tsx",
+];
+
+const missingPaths = requiredPaths.filter(
+  (relativePath) => !existsSync(path.join(templateRoot, relativePath)),
+);
+
+if (missingPaths.length > 0) {
+  throw new Error(
+    `Vuilder shell route contract is incomplete.\n${missingPaths
+      .map((relativePath) => `- ${relativePath}`)
+      .join("\n")}`,
+  );
+}
+
+const presentForbiddenPaths = forbiddenPaths.filter((relativePath) =>
+  existsSync(path.join(templateRoot, relativePath)),
+);
+
+if (presentForbiddenPaths.length > 0) {
+  throw new Error(
+    `vuilder-shell must hand credential auth to central SSO, not local password routes.\n${presentForbiddenPaths
+      .map((relativePath) => `- ${relativePath}`)
+      .join("\n")}`,
+  );
+}
+
+const sourcePaths = collectNamedFiles(
+  path.join(templateRoot, "src"),
+  new Set(["ts", "tsx"]),
+).filter((absolutePath) => !absolutePath.includes(".test."));
+const webAuthReferences = sourcePaths.filter((absolutePath) =>
+  readFileSync(absolutePath, "utf8").includes("@minutework/web-auth"),
+);
+
+if (webAuthReferences.length > 0) {
+  throw new Error(
+    `vuilder-shell must use platform member SSO, not tenant customer web-auth.\n${webAuthReferences
+      .map((absolutePath) => `- ${path.relative(templateRoot, absolutePath)}`)
+      .join("\n")}`,
+  );
+}
+
+const credentialAuthReferences = sourcePaths.filter((absolutePath) => {
+  const source = readFileSync(absolutePath, "utf8");
+  return (
+    source.includes("loginWithPassword") ||
+    source.includes("loginRequestSchema") ||
+    source.includes("platformAuthEndpoints.login") ||
+    source.includes("/api/auth/login")
+  );
+});
+
+if (credentialAuthReferences.length > 0) {
+  throw new Error(
+    `vuilder-shell must redirect credential auth through central SSO.\n${credentialAuthReferences
+      .map((absolutePath) => `- ${path.relative(templateRoot, absolutePath)}`)
+      .join("\n")}`,
+  );
+}
+
+const rawPlatformCredentialReferences = sourcePaths.filter((absolutePath) => {
+  const relativePath = path.relative(templateRoot, absolutePath);
+  const source = readFileSync(absolutePath, "utf8");
+  if (relativePath === path.join("src", "lib", "platform", "session.server.ts")) {
+    return false;
+  }
+  return [
+    "mw_platform_session",
+    "mw_platform_csrf",
+    "sessionid=",
+    "csrftoken",
+    "X-CSRFToken",
+    "platformAuthEndpoints.currentSession",
+    "platformAuthEndpoints.logout",
+    "logoutPlatformSession",
+    "ensureCsrfToken",
+  ].some((pattern) => source.includes(pattern));
+});
+
+if (rawPlatformCredentialReferences.length > 0) {
+  throw new Error(
+    `vuilder-shell must consume the tenant-bound shell token, not raw platform session credentials.\n${rawPlatformCredentialReferences
+      .map((absolutePath) => `- ${path.relative(templateRoot, absolutePath)}`)
+      .join("\n")}`,
+  );
+}
+
+const sharedShellCookieDomainReferences = sourcePaths.filter((absolutePath) => {
+  const source = readFileSync(absolutePath, "utf8");
+  return source.includes("MW_VUILDER_SHELL_COOKIE_DOMAIN");
+});
+
+if (sharedShellCookieDomainReferences.length > 0) {
+  throw new Error(
+    `vuilder-shell must set shell sessions as host-only cookies on the branded shell origin.\n${sharedShellCookieDomainReferences
+      .map((absolutePath) => `- ${path.relative(templateRoot, absolutePath)}`)
+      .join("\n")}`,
+  );
+}
+
+const platformClientSource = readFileSync(
+  path.join(templateRoot, "src", "lib", "platform", "client.server.ts"),
+  "utf8",
+);
+for (const requiredSnippet of [
+  "platformAuthEndpoints.shellTokenExchange",
+  "platformAuthEndpoints.shellTokenContext",
+  "platformAuthEndpoints.shellTokenRevoke",
+  "exchangeVuilderShellSessionHandoffCode",
+  "revokeVuilderShellSession",
+  "X-Vuilder-Shell-Session",
+  "loadWorkspaceShellSession",
+  "shellContextCanViewWorkspace",
+  "shellContextCanOpenWorkspace",
+]) {
+  if (!platformClientSource.includes(requiredSnippet)) {
+    throw new Error(
+      `src/lib/platform/client.server.ts must resolve server-authored shell token context (${requiredSnippet}).`,
+    );
+  }
+}
+
+const workspaceRoutesRoot = path.join(templateRoot, "src", "app", "w");
+const workspaceRouteHandlerPaths = collectNamedFiles(
+  workspaceRoutesRoot,
+  new Set(["route.ts", "route.tsx"]),
+);
+if (workspaceRouteHandlerPaths.length > 0) {
+  throw new Error(
+    `Route handlers under /w bypass the platform shell/session contract.\n${workspaceRouteHandlerPaths
+      .map((absolutePath) => `- ${path.relative(templateRoot, absolutePath)}`)
+      .join("\n")}`,
+  );
+}
+
+const routesSource = readFileSync(path.join(templateRoot, "src", "lib", "app-routes.ts"), "utf8");
+for (const requiredExport of [
+  "workspaceShell",
+  "workspaceConnect",
+  "loginForWorkspace",
+  "loginForWorkspaceConnect",
+]) {
+  if (!routesSource.includes(requiredExport)) {
+    throw new Error(`src/lib/app-routes.ts must expose ${requiredExport}.`);
+  }
+}
+
+const loginRouteSource = readFileSync(
+  path.join(templateRoot, "src", "app", "login", "route.ts"),
+  "utf8",
+);
+if (
+  !loginRouteSource.includes("buildCentralSsoLoginUrl") ||
+  !loginRouteSource.includes("createVuilderShellHandoffState") ||
+  !loginRouteSource.includes("applyVuilderShellHandoffStateToResponse") ||
+  !loginRouteSource.includes("NextResponse.redirect")
+) {
+  throw new Error("/login must set shell handoff state before central SSO redirect.");
+}
+
+const workspacePageSource = readFileSync(
+  path.join(templateRoot, "src", "app", "w", "[workspace_slug]", "page.tsx"),
+  "utf8",
+);
+if (!workspacePageSource.includes("VuilderWorkspaceScreen")) {
+  throw new Error("/w/[workspace_slug] must render VuilderWorkspaceScreen.");
+}
+for (const requiredSnippet of [
+  "loadWorkspaceShellSession",
+  "workspaceCanView",
+  "workspaceCanOpen",
+  "appRoutes.loginForWorkspace(workspaceSlug)",
+  "appRoutes.workspaceConnect(workspaceSlug)",
+]) {
+  if (!workspacePageSource.includes(requiredSnippet)) {
+    throw new Error(
+      `/w/[workspace_slug] must preserve the platform-authored shell context and requested workspace (${requiredSnippet}).`,
+    );
+  }
+}
+
+const connectPageSource = readFileSync(
+  path.join(templateRoot, "src", "app", "w", "[workspace_slug]", "connect", "page.tsx"),
+  "utf8",
+);
+if (!connectPageSource.includes("VuilderConnectScreen")) {
+  throw new Error("/w/[workspace_slug]/connect must render VuilderConnectScreen.");
+}
+for (const requiredSnippet of [
+  "loadWorkspaceShellSession",
+  "workspaceCanView",
+  "notFound()",
+]) {
+  if (!connectPageSource.includes(requiredSnippet)) {
+    throw new Error(
+      `/w/[workspace_slug]/connect must fail closed for authenticated shell-context mismatch (${requiredSnippet}).`,
+    );
+  }
+}
+
+const appPageSource = readFileSync(
+  path.join(templateRoot, "src", "app", "app", "page.tsx"),
+  "utf8",
+);
+for (const requiredSnippet of [
+  "loadCurrentWorkspaceShellSession",
+  "workspaceCanView",
+  "workspaceCanOpen",
+  "notFound()",
+  "appRoutes.workspaceConnect(membership.workspace_slug)",
+  "redirect(appRoutes.workspaceShell(membership.workspace_slug))",
+]) {
+  if (!appPageSource.includes(requiredSnippet)) {
+    throw new Error(
+      `/app must apply the same platform-authored shell context gate before redirecting (${requiredSnippet}).`,
+    );
+  }
+}
+if (appPageSource.includes("PrivateAppShell") || appPageSource.includes("TenantDashboard")) {
+  throw new Error("/app must not render private workspace UI outside the /w gate.");
+}
+
+const acceptShellSessionRouteSource = readFileSync(
+  path.join(
+    templateRoot,
+    "src",
+    "app",
+    "api",
+    "auth",
+    "accept-shell-session",
+    "route.ts",
+  ),
+  "utf8",
+);
+for (const requiredSnippet of [
+  "exchangeVuilderShellSessionHandoffCode",
+  "applyVuilderShellSessionToResponse",
+  "readVuilderShellHandoffState",
+  "clearVuilderShellHandoffStateFromResponse",
+  "code",
+  "state",
+  "return_to",
+  "NextResponse.redirect",
+]) {
+  if (!acceptShellSessionRouteSource.includes(requiredSnippet)) {
+    throw new Error(
+      `/api/auth/accept-shell-session must consume SSO handoff on the shell origin (${requiredSnippet}).`,
+    );
+  }
+}
+if (acceptShellSessionRouteSource.includes("clearPlatformSessionFromResponse")) {
+  throw new Error(
+    "/api/auth/accept-shell-session must not clear an existing shell session when a forged handoff fails.",
+  );
+}
+
+const sessionRouteSource = readFileSync(
+  path.join(templateRoot, "src", "app", "api", "auth", "session", "route.ts"),
+  "utf8",
+);
+const sessionNoStoreHeaderCount = Array.from(
+  sessionRouteSource.matchAll(/Cache-Control["'],\s*["']no-store/g),
+).length;
+if (sessionNoStoreHeaderCount < 2) {
+  throw new Error(
+    "/api/auth/session must set Cache-Control: no-store on success and error responses.",
+  );
+}
+
+const logoutRouteSource = readFileSync(
+  path.join(templateRoot, "src", "app", "api", "auth", "logout", "route.ts"),
+  "utf8",
+);
+for (const requiredSnippet of [
+  "hasTrustedBrowserOrigin",
+  "readPlatformAuthState",
+  "revokeVuilderShellSession",
+  "clearPlatformSessionFromResponse",
+]) {
+  if (!logoutRouteSource.includes(requiredSnippet)) {
+    throw new Error(
+      `/api/auth/logout must preserve the shell-token logout contract (${requiredSnippet}).`,
+    );
+  }
+}
+const logoutPostHandlerIndex = logoutRouteSource.indexOf("export async function POST");
+const logoutPostHandlerSource =
+  logoutPostHandlerIndex >= 0 ? logoutRouteSource.slice(logoutPostHandlerIndex) : "";
+const originGuardIndex = logoutPostHandlerSource.indexOf("hasTrustedBrowserOrigin");
+const revokeIndex = logoutPostHandlerSource.indexOf("revokeVuilderShellSession");
+const clearCookieIndex = logoutPostHandlerSource.indexOf("clearPlatformSessionFromResponse");
+if (
+  originGuardIndex < 0 ||
+  revokeIndex < 0 ||
+  clearCookieIndex < 0 ||
+  originGuardIndex > revokeIndex ||
+  revokeIndex > clearCookieIndex
+) {
+  throw new Error(
+    "/api/auth/logout must check the browser origin, revoke the shell token, then clear shell cookies.",
+  );
+}
+
+const connectScreenSource = readFileSync(
+  path.join(
+    templateRoot,
+    "src",
+    "features",
+    "vuilder-shell",
+    "components",
+    "vuilder-connect-screen.tsx",
+  ),
+  "utf8",
+);
+if (!connectScreenSource.includes("appRoutes.loginForWorkspaceConnect(workspaceSlug)")) {
+  throw new Error(
+    "VuilderConnectScreen must preserve workspace context when linking to login.",
+  );
+}
+
+console.log("vuilder shell route contract is valid");
+
+function collectNamedFiles(directory, names) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectNamedFiles(absolutePath, names));
+      continue;
+    }
+    if (
+      !entry.isFile() ||
+      (!names.has(entry.name) && !names.has(path.extname(entry.name).slice(1)))
+    ) {
+      continue;
+    }
+    if (!statSync(absolutePath).isFile()) {
+      continue;
+    }
+    files.push(absolutePath);
+  }
+
+  return files;
+}

package/assets/templates/vuilder-shell/tools/template/validate-template.mjs

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import Ajv2020 from "ajv/dist/2020.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templateRoot = path.resolve(__dirname, "..", "..");
+const bundledSchemaPath = path.join(templateRoot, "template.schema.json");
+const sharedSchemaPath = path.resolve(templateRoot, "..", "template.schema.json");
+const manifestPath = path.join(templateRoot, "template.json");
+
+const bundledSchemaSource = readFileSync(bundledSchemaPath, "utf8");
+const sharedSchemaSource = existsSync(sharedSchemaPath)
+  ? readFileSync(sharedSchemaPath, "utf8")
+  : null;
+
+function normalizeJson(source) {
+  return JSON.stringify(JSON.parse(source));
+}
+
+if (
+  sharedSchemaSource &&
+  normalizeJson(sharedSchemaSource) !== normalizeJson(bundledSchemaSource)
+) {
+  throw new Error(
+    `Bundled template schema is out of sync with the shared schema at ${sharedSchemaPath}`,
+  );
+}
+
+const schema = JSON.parse(sharedSchemaSource ?? bundledSchemaSource);
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const validate = ajv.compile(schema);
+
+if (!validate(manifest)) {
+  const details = (validate.errors ?? [])
+    .map((error) => `${error.instancePath || "/"} ${error.message ?? "invalid"}`)
+    .join("\n");
+
+  throw new Error(`Template manifest validation failed.\n${details}`);
+}
+
+console.log("template.json is valid");

package/assets/templates/vuilder-shell/tools/template/with-public-site-fixture.mjs

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+
+const [command, ...args] = process.argv.slice(2);
+const storybookHeapMb = process.env.MW_STORYBOOK_NODE_HEAP_MB ?? "768";
+
+if (!command) {
+  console.error("Usage: node tools/template/with-public-site-fixture.mjs <command> [args...]");
+  process.exit(1);
+}
+
+const childEnv = {
+  ...process.env,
+  NEXT_PUBLIC_MW_APP_ID: process.env.NEXT_PUBLIC_MW_APP_ID ?? "vuilder.vertical",
+  MW_TEMPLATE_APP_NAME: process.env.MW_TEMPLATE_APP_NAME ?? "Vuilder Shell",
+  MW_PUBLIC_BASE_URL: process.env.MW_PUBLIC_BASE_URL ?? "https://shell.example.com",
+};
+
+if (
+  command === "storybook" &&
+  !/\bmax-old-space-size=/.test(childEnv.NODE_OPTIONS ?? "")
+) {
+  childEnv.NODE_OPTIONS = [childEnv.NODE_OPTIONS, `--max-old-space-size=${storybookHeapMb}`]
+    .filter(Boolean)
+    .join(" ");
+}
+
+const child = spawn(command, args, {
+  env: childEnv,
+  stdio: "inherit",
+});
+
+child.once("error", (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
+
+child.once("exit", (code, signal) => {
+  if (signal) {
+    console.error(`Validation fixture command exited via signal ${signal}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.exitCode = code ?? 1;
+});