@codepress/design-kit 0.0.0-stage → 0.1.0

package/src/cli.mjs

@@ -0,0 +1,175 @@
+/**
+ * The `design-kit` command line: capture a design kit from a Storybook build
+ * and a running app, and compose mockups from it. Run `design-kit --help`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { ConfigError, loadConfig } from "./config.mjs";
+
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+const USAGE = `usage: design-kit <command> [options]
+
+  capture stories   capture every story of a Storybook 7/8 static build
+      [--config <file>] [--out <dir>] [--storybook-dir <dir>]
+      [--only <id,...> | --only-file <file>] [--base <previous kit>]
+  capture pages     capture the configured pages of a running app
+      [--config <file>] [--out <dir>] [--base-url <url>] [--only <name,...>]
+      [--ready <name>=<selector>] [--screenshots <dir>] [--timeout <ms>]
+  kit <info|find|show|compose> ...
+                    look up and compose from a kit (\`design-kit kit --help\`)
+      [--kit <dir>]   default: DESIGN_KIT_DIR, the config's "out", ./design-kit
+  validate          check design-kit.config.json against the v1 schema
+      [--config <file>]
+
+The config is the nearest design-kit.config.json at or above the working
+directory unless --config names one. Exit codes: 0 done, 1 a capture could
+not run, 2 a config or usage error.`;
+
+function parse(argv, spec) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") continue;
+    const name = arg.replace(/^--/, "");
+    if (!arg.startsWith("--") || !(name in spec)) {
+      throw new ConfigError(`unknown option ${arg}\n\n${USAGE}`);
+    }
+    if (spec[name] === "flag") {
+      options[name] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined) throw new ConfigError(`${arg} needs a value`);
+    i += 1;
+    if (spec[name] === "list") (options[name] ??= []).push(value);
+    else options[name] = value;
+  }
+  return options;
+}
+
+async function captureStories(argv) {
+  const options = parse(argv, {
+    config: "value",
+    out: "value",
+    "storybook-dir": "value",
+    only: "value",
+    "only-file": "value",
+    base: "value",
+  });
+  const config = loadConfig(options.config);
+  const { captureStories: run, parseOnly } =
+    await import("./capture-stories.mjs");
+  const only =
+    options.only !== undefined
+      ? parseOnly(options.only)
+      : options["only-file"] !== undefined
+        ? parseOnly(readFileSync(options["only-file"], "utf8"))
+        : undefined;
+  await run(config, {
+    out: options.out,
+    storybookDir: options["storybook-dir"],
+    only,
+    base: options.base ? resolve(options.base) : undefined,
+  });
+  return 0;
+}
+
+async function capturePagesCommand(argv) {
+  const options = parse(argv, {
+    config: "value",
+    out: "value",
+    "base-url": "value",
+    only: "value",
+    ready: "list",
+    screenshots: "value",
+    timeout: "value",
+  });
+  const config = loadConfig(options.config);
+  const ready = {};
+  for (const raw of options.ready ?? []) {
+    const at = raw.indexOf("=");
+    if (at < 1)
+      throw new ConfigError(`--ready takes <page>=<selector>, got ${raw}`);
+    ready[raw.slice(0, at)] = raw.slice(at + 1);
+  }
+  const timeoutMs =
+    options.timeout === undefined ? undefined : Number(options.timeout);
+  if (timeoutMs !== undefined && !(Number.isFinite(timeoutMs) && timeoutMs > 0))
+    throw new ConfigError("--timeout takes a positive number of milliseconds");
+  const { capturePages } = await import("./capture-pages.mjs");
+  const session = { interrupted: false, browser: null };
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => {
+      session.interrupted = true;
+    });
+  }
+  return capturePages(config, {
+    out: options.out,
+    baseUrl: options["base-url"],
+    only: options.only?.split(",").filter(Boolean),
+    ready,
+    screenshots: options.screenshots ? resolve(options.screenshots) : undefined,
+    timeoutMs,
+    session,
+  });
+}
+
+async function kitCommand(argv, env) {
+  const { run } = await import("./kit.mjs");
+  let defaultDir = resolve("design-kit");
+  if (!argv.includes("--kit") && !env.DESIGN_KIT_DIR) {
+    try {
+      const config = loadConfig();
+      if (config.out) defaultDir = config.out;
+    } catch {
+      // No usable config: the kit folder comes from --kit or ./design-kit.
+    }
+    if (!existsSync(defaultDir)) defaultDir = process.cwd();
+  }
+  return run(argv, undefined, env, defaultDir);
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const [command, sub, ...rest] = argv;
+  try {
+    if (!command) {
+      console.log(USAGE);
+      return 2;
+    }
+    // `kit --help` is the kit tool's own usage; anywhere else, this one.
+    if (
+      command !== "kit" &&
+      argv.some((arg) => arg === "--help" || arg === "-h")
+    ) {
+      console.log(USAGE);
+      return 0;
+    }
+    if (command === "--version") {
+      console.log(VERSION);
+      return 0;
+    }
+    if (command === "kit") return await kitCommand(argv.slice(1), env);
+    if (command === "validate") {
+      const options = parse(argv.slice(1), { config: "value" });
+      const config = loadConfig(options.config);
+      console.log(`${config.file}: valid (version 1)`);
+      return 0;
+    }
+    if (command === "capture" && sub === "stories")
+      return await captureStories(rest);
+    if (command === "capture" && sub === "pages")
+      return await capturePagesCommand(rest);
+    throw new ConfigError(`unknown command "${argv.join(" ")}"\n\n${USAGE}`);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`design-kit: ${error.message}`);
+      return 2;
+    }
+    console.error(`design-kit: ${error?.message ?? error}`);
+    return 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,276 @@
+/**
+ * design-kit.config.json: finding it, validating it against the v1 schema
+ * shipped in this package (schema/design-kit.config.schema.json), and
+ * resolving it into the shape the captures use. A config error names the
+ * field and exits 2.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CONFIG_NAME = "design-kit.config.json";
+export const SCHEMA_PATH = fileURLToPath(
+  new URL("../schema/design-kit.config.schema.json", import.meta.url),
+);
+export const DEFAULT_FIXED_TIME = "2026-01-01T12:00:00.000Z";
+export const DEFAULT_PAGE_WIDTHS = [
+  { width: 1280, height: 800 },
+  { width: 390, height: 844 },
+];
+
+/** A problem with the config or the command line: exit 2. */
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.exitCode = 2;
+  }
+}
+
+let schemaCache = null;
+export function configSchema() {
+  schemaCache ??= JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+  return schemaCache;
+}
+
+// ── validation (the subset of JSON Schema the shipped schema uses) ──────────
+
+function typeOf(value) {
+  if (Array.isArray(value)) return "array";
+  if (value === null) return "null";
+  if (typeof value === "number")
+    return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+
+function fieldName(path) {
+  return path.length ? path.join("").replace(/^\./, "") : "(the config)";
+}
+
+/**
+ * Every place `value` breaks `schema`, as "<field>: <problem>" strings, in
+ * document order.
+ */
+export function validate(value, schema = configSchema(), root = schema) {
+  const errors = [];
+  const walk = (node, rule, path) => {
+    if (rule.$ref) {
+      const name = rule.$ref.replace(/^#\/\$defs\//, "");
+      walk(node, { ...root.$defs[name], ...rule, $ref: undefined }, path);
+      return;
+    }
+    const field = fieldName(path);
+    const actual = typeOf(node);
+    if (rule.type) {
+      const ok =
+        actual === rule.type ||
+        (rule.type === "number" && actual === "integer");
+      if (!ok) {
+        errors.push(`${field}: must be ${an(rule.type)}, not ${an(actual)}`);
+        return;
+      }
+    }
+    if (rule.enum && !rule.enum.includes(node)) {
+      errors.push(
+        `${field}: must be ${rule.enum.map((v) => JSON.stringify(v)).join(" or ")}`,
+      );
+    }
+    if (actual === "string") {
+      if (rule.minLength && node.length < rule.minLength)
+        errors.push(`${field}: must not be empty`);
+      if (rule.pattern && !new RegExp(rule.pattern).test(node))
+        errors.push(`${field}: must match ${rule.pattern}`);
+    }
+    if (
+      (actual === "integer" || actual === "number") &&
+      rule.minimum !== undefined
+    ) {
+      if (node < rule.minimum)
+        errors.push(`${field}: must be at least ${rule.minimum}`);
+    }
+    if (actual === "array") {
+      if (rule.minItems && node.length < rule.minItems)
+        errors.push(
+          `${field}: needs at least ${rule.minItems} item${rule.minItems === 1 ? "" : "s"}`,
+        );
+      if (rule.items)
+        node.forEach((item, index) =>
+          walk(item, rule.items, [...path, `[${index}]`]),
+        );
+    }
+    if (actual === "object") {
+      for (const key of rule.required ?? []) {
+        if (!(key in node))
+          errors.push(`${fieldName([...path, `.${key}`])}: is required`);
+      }
+      for (const [key, child] of Object.entries(node)) {
+        const childPath = [...path, `.${key}`];
+        if (rule.properties && key in rule.properties) {
+          walk(child, rule.properties[key], childPath);
+        } else if (rule.additionalProperties === false) {
+          errors.push(`${fieldName(childPath)}: unknown key`);
+        } else if (
+          rule.additionalProperties &&
+          typeof rule.additionalProperties === "object"
+        ) {
+          walk(child, rule.additionalProperties, childPath);
+        }
+      }
+    }
+  };
+  walk(value, schema, []);
+  return errors;
+}
+
+function an(type) {
+  return /^[aeiou]/.test(type) ? `an ${type}` : `a ${type}`;
+}
+
+// ── loading ─────────────────────────────────────────────────────────────────
+
+/** The nearest design-kit.config.json at or above `from`, or null. */
+export function findConfig(from = process.cwd()) {
+  let dir = resolve(from);
+  for (;;) {
+    const candidate = join(dir, CONFIG_NAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Reads, validates and resolves a config. `file` defaults to the nearest
+ * design-kit.config.json above the working directory.
+ */
+export function loadConfig(file) {
+  const path = file ? resolve(file) : findConfig();
+  if (!path) {
+    throw new ConfigError(
+      `no ${CONFIG_NAME} here or in any folder above; pass --config <file>`,
+    );
+  }
+  if (!existsSync(path)) throw new ConfigError(`${path}: no such file`);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new ConfigError(`${path}: not valid JSON (${error.message})`);
+  }
+  return resolveConfig(raw, path);
+}
+
+/** Validates a parsed config and resolves its paths against `path`'s folder. */
+export function resolveConfig(raw, path) {
+  const errors = validate(raw);
+  if (!errors.length && !raw.stories && !raw.pages) {
+    errors.push("(the config): needs a stories or a pages section");
+  }
+  raw.stories?.widths?.forEach((width, index) => {
+    try {
+      new RegExp(width.titles);
+    } catch (error) {
+      errors.push(
+        `stories.widths[${index}].titles: not a regular expression (${error.message})`,
+      );
+    }
+  });
+  for (const [key, section] of [
+    ["stories", raw.stories],
+    ["pages", raw.pages],
+  ]) {
+    if (section?.fixedTime && Number.isNaN(Date.parse(section.fixedTime)))
+      errors.push(`${key}.fixedTime: not an ISO 8601 date`);
+  }
+  if (raw.pages?.auth?.storageState && raw.pages?.auth?.setup) {
+    errors.push("pages.auth: give storageState or setup, not both");
+  }
+  if (raw.pages?.startCommand && !raw.pages?.waitUrl) {
+    errors.push("pages.waitUrl: is required with pages.startCommand");
+  }
+  const names = new Set();
+  raw.pages?.pages?.forEach((page, index) => {
+    if (names.has(page?.name))
+      errors.push(`pages.pages[${index}].name: "${page.name}" is used twice`);
+    names.add(page?.name);
+  });
+  if (errors.length) {
+    throw new ConfigError(
+      `${path}:\n${errors.map((error) => `  ${error}`).join("\n")}`,
+    );
+  }
+
+  const configDir = dirname(path);
+  const at = (value) =>
+    value === undefined ? undefined : resolve(configDir, value);
+  const config = {
+    file: path,
+    configDir,
+    raw,
+    out: at(raw.out),
+    theme: raw.theme ? normalizeTheme(raw.theme) : undefined,
+  };
+  if (raw.stories) {
+    const s = raw.stories;
+    const root = at(s.root ?? ".");
+    config.stories = {
+      root,
+      storybookDir: at(s.storybookDir),
+      buildCommand: s.buildCommand,
+      staticDir: s.staticDir ? resolve(root, s.staticDir) : undefined,
+      viewport: s.viewport ?? { width: 1280, height: 800 },
+      widths: (s.widths ?? []).map((w) => ({
+        titles: new RegExp(w.titles),
+        width: w.width,
+        height: w.height,
+      })),
+      fonts: s.fonts ? { dir: at(s.fonts.dir), faces: s.fonts.faces } : null,
+      fixedTime: s.fixedTime ?? DEFAULT_FIXED_TIME,
+      gaps: s.gaps
+        ? {
+            sourceRoot: s.gaps.sourceRoot ? at(s.gaps.sourceRoot) : root,
+            componentGlob: s.gaps.componentGlob,
+          }
+        : null,
+    };
+  }
+  if (raw.pages) {
+    const p = raw.pages;
+    config.pages = {
+      baseUrl: p.baseUrl,
+      startCommand: p.startCommand,
+      waitUrl: p.waitUrl,
+      cwd: at(p.cwd) ?? configDir,
+      startTimeoutMs: p.startTimeoutMs ?? 120_000,
+      auth: {
+        storageState: at(p.auth?.storageState),
+        setup: at(p.auth?.setup),
+      },
+      hooks: at(p.hooks),
+      widths: p.widths ?? DEFAULT_PAGE_WIDTHS,
+      fixedTime: p.fixedTime ?? DEFAULT_FIXED_TIME,
+      shellReady: p.shellReady,
+      layout: p.layout
+        ? { ...p.layout, default: p.layout.default ?? "default" }
+        : null,
+      fontsPath: p.fontsPath ?? null,
+      copyFonts: p.copyFonts ?? true,
+      timeoutMs: p.timeoutMs ?? 30_000,
+      forbidStrings: p.forbidStrings ?? [],
+      pages: p.pages,
+    };
+  }
+  return config;
+}
+
+/** The theme as the manifest records it, with its defaults filled in. */
+export function normalizeTheme(theme) {
+  const attribute = theme.attribute ?? "class";
+  return {
+    attribute,
+    dark: theme.dark ?? "dark",
+    ...(theme.light ? { light: theme.light } : {}),
+    targets:
+      theme.targets ?? (attribute === "class" ? ["html", "body"] : ["html"]),
+  };
+}

package/src/glob.mjs

@@ -0,0 +1,46 @@
+/**
+ * A small glob matcher for config paths: `**` (any number of folders), `*`
+ * and `?` (within one name), `[A-Z]` classes and `{a,b}` alternatives.
+ * Paths use `/`.
+ */
+
+/** @param {string} glob */
+export function globToRegExp(glob) {
+  let out = "";
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        const slash = glob[i + 2] === "/";
+        out += slash ? "(?:[^/]*/)*" : ".*";
+        i += slash ? 2 : 1;
+      } else out += "[^/]*";
+    } else if (ch === "?") out += "[^/]";
+    else if (ch === "[") {
+      const close = glob.indexOf("]", i + 1);
+      if (close < 0) out += "\\[";
+      else {
+        const body = glob.slice(i + 1, close).replace(/\\/g, "\\\\");
+        out += `[${body.startsWith("!") ? `^${body.slice(1)}` : body}]`;
+        i = close;
+      }
+    } else if (ch === "{") {
+      const close = glob.indexOf("}", i + 1);
+      if (close < 0) out += "\\{";
+      else {
+        out += `(?:${glob
+          .slice(i + 1, close)
+          .split(",")
+          .map((part) => globToRegExp(part).source.slice(1, -1))
+          .join("|")})`;
+        i = close;
+      }
+    } else out += ch.replace(/[.+^${}()|\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** @param {RegExp} pattern @param {string} path */
+export function matchFile(pattern, path) {
+  return pattern.test(path.replace(/\\/g, "/"));
+}

package/src/index.d.ts

@@ -0,0 +1,137 @@
+/** Types for @codepress/design-kit's programmatic API. */
+
+export const CONFIG_NAME: "design-kit.config.json";
+export const SCHEMA_PATH: string;
+
+export class ConfigError extends Error {
+  exitCode: 2;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface PageConfig {
+  name: string;
+  title?: string;
+  path: string;
+  ready: string;
+  sourceFile?: string;
+  slots: { main: string[]; [slot: string]: string[] };
+  layoutSlots?: Record<string, { main: string[]; [slot: string]: string[] }>;
+}
+
+/** A loaded, validated config with its paths resolved. */
+export interface DesignKitConfig {
+  file: string;
+  configDir: string;
+  raw: Record<string, unknown>;
+  out?: string;
+  theme?: {
+    attribute: string;
+    dark: string;
+    light?: string;
+    targets: ("html" | "body")[];
+  };
+  stories?: Record<string, unknown>;
+  pages?: {
+    baseUrl?: string;
+    fixedTime: string;
+    widths: Size[];
+    pages: PageConfig[];
+    [key: string]: unknown;
+  };
+}
+
+export function findConfig(from?: string): string | null;
+export function loadConfig(file?: string): DesignKitConfig;
+export function resolveConfig(raw: unknown, path: string): DesignKitConfig;
+/** "<field>: <problem>" for every place `value` breaks the v1 schema. */
+export function validate(value: unknown): string[];
+
+export function playwrightVersion(from?: string): string;
+
+export function captureStories(
+  config: DesignKitConfig,
+  options?: {
+    out?: string;
+    storybookDir?: string;
+    only?: string[];
+    base?: string;
+    log?: (message: string) => void;
+  },
+): Promise<{ out: string; rows: number; failed: number }>;
+
+/** Returned by a `page` hook; both run inside the capture of one page. */
+export interface PageHookResult {
+  /** The ready selector never appeared; may throw a clearer error. */
+  readyFailed?(): void | Promise<void>;
+  /** Runs just before serialization, in place of the optional screenshot. */
+  beforeSerialize?(info: { shotPath: string }): void | Promise<void>;
+}
+
+export interface CaptureHookInfo {
+  page: PageConfig;
+  viewport: Size;
+}
+
+export interface CapturePagesOptions {
+  out?: string;
+  only?: string[];
+  ready?: Record<string, string>;
+  screenshots?: string;
+  timeoutMs?: number;
+  baseUrl?: string;
+  /** A storageState file path or a Playwright storage state object. */
+  storageState?: string | object;
+  forbidStrings?: string[];
+  stripOrigins?: string[];
+  hooks?: {
+    /** Runs on each fresh context; may return a cleanup. */
+    context?(
+      context: unknown,
+      info: CaptureHookInfo,
+    ): void | (() => Promise<void>) | Promise<void | (() => Promise<void>)>;
+    /** Runs on each page before it navigates. */
+    page?(
+      page: unknown,
+      info: CaptureHookInfo,
+    ): void | PageHookResult | Promise<void | PageHookResult>;
+  };
+  /** The Playwright to drive; default the project's own. */
+  playwright?: { chromium: unknown };
+  log?: (message: string) => void;
+  /** Set `interrupted` to stop between pages; `browser` is set once launched. */
+  session?: { interrupted: boolean; browser: unknown };
+}
+
+/** 0, or 130 when `session.interrupted` stopped the run (nothing written). */
+export function capturePages(
+  config: DesignKitConfig,
+  options?: CapturePagesOptions,
+): Promise<number>;
+
+/** What to look for per forbidden value: as written, a token's long segments, and escaped. */
+export function forbiddenNeedles(values: string[]): string[];
+/** The first needle `text` contains, or null. */
+export function findForbidden(text: string, needles: string[]): string | null;
+
+export function loadKit(dir: string): unknown;
+export function find(kit: unknown, query: string): unknown[];
+export function compose(
+  kit: unknown,
+  options: {
+    frame: string;
+    slots?: { name: string; content: string }[];
+    theme?: "light" | "dark";
+    showNew?: boolean;
+  },
+): string;
+/** Runs one `kit` command; returns its exit code. */
+export function runKit(
+  argv: string[],
+  io?: { out(text: string): void; err(text: string): void },
+  env?: Record<string, string | undefined>,
+  defaultDir?: string,
+): number;

package/src/index.mjs

@@ -0,0 +1,17 @@
+/**
+ * @codepress/design-kit's programmatic API. The command line (`design-kit`)
+ * is a thin layer over these.
+ */
+export {
+  CONFIG_NAME,
+  ConfigError,
+  SCHEMA_PATH,
+  findConfig,
+  loadConfig,
+  resolveConfig,
+  validate,
+} from "./config.mjs";
+export { captureStories, playwrightVersion } from "./capture-stories.mjs";
+export { capturePages } from "./capture-pages.mjs";
+export { findForbidden, forbiddenNeedles } from "./pages.mjs";
+export { compose, find, loadKit, run as runKit } from "./kit.mjs";