minutework 0.1.0

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

package/assets/templates/next-tenant-app/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/next-tenant-app/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/next-tenant-app/tools/template/validate-route-contract.mjs

@@ -0,0 +1,39 @@
+import { existsSync } 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/page.tsx",
+  "src/app/pricing/page.tsx",
+  "src/app/docs/page.tsx",
+  "src/app/docs/[...slug]/page.tsx",
+  "src/app/blog/page.tsx",
+  "src/app/blog/[slug]/page.tsx",
+  "src/app/login/page.tsx",
+  "src/app/app/layout.tsx",
+  "src/app/app/page.tsx",
+  "src/app/app/examples/runtime-commands/page.tsx",
+  "src/app/robots.ts",
+  "src/app/sitemap.ts",
+  "src/lib/content/contracts.ts",
+  "src/lib/content/custom-adapter.ts",
+  "src/lib/content/empty-state.ts",
+  "src/lib/content/adapter.server.ts",
+];
+
+const missingPaths = requiredPaths.filter(
+  (relativePath) => !existsSync(path.join(templateRoot, relativePath)),
+);
+
+if (missingPaths.length > 0) {
+  throw new Error(
+    `Combined route contract is incomplete.\n${missingPaths
+      .map((relativePath) => `- ${relativePath}`)
+      .join("\n")}`,
+  );
+}
+
+console.log("combined route contract is valid");

package/assets/templates/next-tenant-app/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/next-tenant-app/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "es2022"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "baseUrl": ".",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/assets/templates/next-tenant-app/vitest.config.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "src"),
+      "server-only": path.resolve(__dirname, "test/server-only-stub.ts"),
+    },
+  },
+  test: {
+    env: {
+      MW_PLATFORM_BASE_URL: "http://127.0.0.1:8000",
+      MW_CONTENT_API_TOKEN: "test-content-token",
+      MW_PUBLIC_BASE_URL: "http://127.0.0.1:3000",
+      MW_PUBLIC_SITE_PROPERTY_KEY: "main-site",
+      MW_PUBLIC_SITE_ENV: "preview",
+    },
+    environment: "node",
+    globals: true,
+    include: ["src/**/*.test.ts"],
+    restoreMocks: true,
+  },
+});

package/bin/minutework.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { createJiti } from "jiti";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const srcLauncherPath = path.join(packageRoot, "src", "launcher.ts");
+const distLauncherPath = path.join(packageRoot, "dist", "launcher.js");
+
+const runCliFromPackageRoot = existsSync(srcLauncherPath)
+  ? await loadSourceLauncher(srcLauncherPath)
+  : await loadDistLauncher(distLauncherPath);
+
+const exitCode = await runCliFromPackageRoot(import.meta.url, process.argv.slice(2));
+process.exit(exitCode);
+
+async function loadSourceLauncher(srcLauncherPath) {
+  const jiti = createJiti(import.meta.url, {
+    fsCache: false,
+    interopDefault: false,
+    moduleCache: false,
+  });
+  const loaded = await jiti.import(srcLauncherPath);
+  return pickRunCliFromPackageRoot(loaded, srcLauncherPath);
+}
+
+async function loadDistLauncher(distLauncherPath) {
+  const loaded = await import(pathToFileURL(distLauncherPath).href);
+  return pickRunCliFromPackageRoot(loaded, distLauncherPath);
+}
+
+function pickRunCliFromPackageRoot(loaded, sourcePath) {
+  if (typeof loaded?.runCliFromPackageRoot !== "function") {
+    throw new Error(`MinuteWork CLI launcher did not export runCliFromPackageRoot: ${sourcePath}`);
+  }
+  return loaded.runCliFromPackageRoot;
+}

package/dist/auth.d.ts

@@ -0,0 +1,59 @@
+import type { CliIo } from "./index.js";
+import type { CliStatePaths, PlatformName } from "./paths.js";
+import { type DeveloperClientDependencies } from "./developer-client.js";
+import { type StoredAuthProfile } from "./state.js";
+export type TokenExchangeResponse = {
+    plaintext_token: string;
+    token: {
+        environment: string;
+        expires_at: string;
+        id: string;
+        issued_for_user: {
+            email: string;
+            id: string;
+            username: string;
+        };
+        kind: string;
+        scope_template: string;
+        scopes: string[];
+        tenant_id: string;
+        tenant_name: string;
+        tenant_slug: string;
+    };
+};
+export type LoopbackReceiver = {
+    close: () => Promise<void>;
+    redirectUri: string;
+    waitForCode: (expectedState: string) => Promise<string>;
+};
+export type LoginDependencies = {
+    createLoopbackReceiver?: () => Promise<LoopbackReceiver>;
+    fetchImpl?: typeof fetch;
+    openExternalUrl?: (url: string, platform?: PlatformName) => Promise<void>;
+};
+export type LinkDependencies = DeveloperClientDependencies;
+export declare function runLoginCommand(options: {
+    args: string[];
+    cwd: string;
+    dependencies?: LoginDependencies;
+    env: NodeJS.ProcessEnv;
+    io: CliIo;
+    paths: CliStatePaths;
+    platform: PlatformName;
+}): Promise<number>;
+export declare function requireCurrentAuthProfile(paths: CliStatePaths): Promise<StoredAuthProfile>;
+export declare function runLinkCommand(options: {
+    args: string[];
+    cwd: string;
+    dependencies?: LinkDependencies;
+    env: NodeJS.ProcessEnv;
+    io: CliIo;
+    paths: CliStatePaths;
+    platform: PlatformName;
+}): Promise<number>;
+export declare function runEnvUseCommand(options: {
+    args: string[];
+    cwd: string;
+    io: CliIo;
+    platform: PlatformName;
+}): Promise<number>;