@codepress/design-kit 0.1.0 → 0.1.2

package/README.md

@@ -19,6 +19,47 @@ It runs on Node 20 or later. Playwright is a peer dependency, so the capture
 drives the Playwright and Chromium your project already has. The `kit`
 commands need neither.
 
+## Set up in your repository
+
+`design-kit init` sets a kit up as one reviewable change. Run it in the
+repository's root, or in a monorepo with `--root <package>` (the config goes
+there; the workflow, skill and instructions line go at the repository root):
+
+```bash
+npx @codepress/design-kit init --dry-run   # what it found and would write
+npx @codepress/design-kit init
+```
+
+It looks for Storybook (a `storybook` or `@storybook/*` dependency, or a
+`.storybook` folder, in the project or its workspace packages) and its
+version, the framework (Next.js, Vite, Remix, Create React App, Astro or
+other), the package manager and lockfile, the dev or start script and the
+app's local URL, an existing Playwright, and whether the app switches to dark
+with a class or a `data-theme` attribute. Then it writes:
+
+- `design-kit.config.json`: the `stories` section when Storybook is found, a
+  `pages` section with `TODO` selectors to fill in, and the `theme`.
+- `.github/workflows/design-kit.yml`: a daily build (and `workflow_dispatch`)
+  on `ubuntu-latest`. It skips when there are no commits since the newest
+  `design-kit` artifact's commit; otherwise it installs dependencies, this
+  package at a pinned version and Chromium, builds Storybook and captures the
+  stories, captures the pages once no `TODO` is left in the config, and
+  uploads the `design-kit` artifact for 30 days. A run with nothing to
+  capture yet (no stories, pages still `TODO`) ends with a warning and
+  uploads nothing. The page capture gets
+  `DESIGN_KIT_USERNAME` and `DESIGN_KIT_PASSWORD` from repository secrets for
+  a sign-in module (`pages.auth.setup`).
+- `.claude/skills/design-kit/SKILL.md`: how agents fetch the newest kit,
+  compose mockups from it and caption them, and `.agents/skills/design-kit` as
+  a symlink to it (a copy when the repository keeps real folders there).
+- One line in `AGENTS.md`, or `CLAUDE.md` when only that exists (a new
+  `AGENTS.md` when neither does), pointing at the skill.
+
+It prints what it found and what is still to decide: the page selectors, the
+start command, sign-in, a missing Storybook. It never overwrites an existing
+file without `--force` (a repository with a `design-kit.config.json` exits 1,
+"already set up") and never writes a secret.
+
 ## Configuration
 
 The commands read `design-kit.config.json` from the working directory or the
@@ -109,8 +150,9 @@ export returns (`async ({ browser, baseUrl, config }) => state`).
   for apps that render a different frame at phone width; `layoutSlots[<that
 value>]` then replaces `slots`.
 - `forbidStrings`: values that must never reach the kit, such as a test
-  account's token. A page whose output contains one, as written, escaped for
-  HTML or JSON, or (for a token) any long segment of it, is not written.
+  account's token. When any page's output contains one, as written, escaped
+  for HTML or JSON, or (for a token) any long segment of it, the capture
+  fails (exit 1) and writes no page, so a CI job uploads nothing.
 - `fontsPath`, `copyFonts`: the fonts the pages load are copied into the
   kit's `fonts/` folder (`copyFonts: false` keeps them out); `fontsPath` says
   which URL path holds them when not every font file is one.
@@ -122,6 +164,7 @@ value>]` then replaces `slots`.
 ## Commands
 
 ```bash
+design-kit init            [--root dir] [--dry-run] [--force]
 design-kit capture stories [--config f] [--out dir] [--storybook-dir dir]
                            [--only id,... | --only-file f] [--base previous-kit]
 design-kit capture pages   [--config f] [--out dir] [--base-url url] [--only name,...]
@@ -136,7 +179,8 @@ byte. The two captures share one kit folder and keep each other's files: run
 both with the same `--out`.
 
 Exit codes: 0 done, 1 a capture could not run (no Storybook build, the app
-did not start), 2 a config or usage error. A story or page that fails is a
+did not start, a forbidden string) or `init` found the repository already set
+up, 2 a config or usage error. A story or page that fails is a
 `gaps.json` row and does not fail the run.
 
 Operational knobs: `DESIGN_KIT_CONCURRENCY` (browser pages at once, default

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {
-    "design-kit": "./bin/design-kit.mjs"
+    "design-kit": "bin/design-kit.mjs"
   },
   "main": "./src/index.mjs",
   "types": "./src/index.d.ts",
@@ -13,7 +13,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.mjs"
     },
-    "./kit": "./src/kit.mjs",
+    "./kit": {
+      "types": "./src/kit.d.ts",
+      "default": "./src/kit.mjs"
+    },
     "./schema.json": "./schema/design-kit.config.schema.json",
     "./package.json": "./package.json"
   },

package/src/capture-pages.mjs

@@ -376,8 +376,16 @@ function themeClassesOf(theme) {
  * browser}: set `interrupted` to stop between pages; `browser` is set once
  * launched so a signal handler can close it).
  *
- * Returns 0, or 130 when interrupted (nothing is written then).
+ * Returns 0, or 130 when interrupted (nothing is written then). Throws,
+ * writing nothing, when any page's markup carries a forbidStrings value.
  */
+/** A page's markup carries a forbidStrings value. */
+class ForbiddenStringError extends Error {
+  constructor() {
+    super("the page's markup carries a forbidStrings value");
+  }
+}
+
 export async function capturePages(config, options = {}) {
   const settings = config.pages;
   if (!settings) {
@@ -442,6 +450,7 @@ export async function capturePages(config, options = {}) {
     );
   const timings = {};
   const gaps = [];
+  const leaks = [];
   const rows = [];
   const files = new Map();
   const fontUrls = new Map();
@@ -547,10 +556,7 @@ export async function capturePages(config, options = {}) {
             ].join("\n"),
             needles,
           );
-          if (found)
-            throw new Error(
-              "the page's markup carries a forbidStrings value; not written",
-            );
+          if (found) throw new ForbiddenStringError();
 
           // CSS assets on the app origin (other than fonts) are inlined.
           const inlined = new Map();
@@ -610,6 +616,11 @@ export async function capturePages(config, options = {}) {
             `captured ${id} (${capture.layout}, slots ${capture.slots.join(",")}, ${Math.round(Buffer.byteLength(html) / 1024)} KB, ${((performance.now() - pageStart) / 1000).toFixed(1)}s)`,
           );
         } catch (error) {
+          if (error instanceof ForbiddenStringError) {
+            leaks.push(id);
+            log(`${id}: ${error.message}`);
+            continue;
+          }
           const reason = String(error?.message ?? error)
             .split("\n")
             .slice(0, 3)
@@ -630,6 +641,12 @@ export async function capturePages(config, options = {}) {
       fs.rmSync(shotsDir, { recursive: true, force: true });
   }
 
+  // A leaked value fails the whole capture: no page of this run is written,
+  // so a CI job stops before it uploads anything.
+  if (leaks.length)
+    throw new Error(
+      `${leaks.join(", ")} carried a forbidStrings value; nothing was written`,
+    );
   writePagesKit(out, {
     rows,
     files,

package/src/cli.mjs

@@ -13,6 +13,9 @@ const VERSION = JSON.parse(
 
 const USAGE = `usage: design-kit <command> [options]
 
+  init              set a kit up in this repository: the config, a daily
+                    GitHub Actions build, and a skill for its agents
+      [--root <dir>] [--dry-run] [--force]
   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>]
@@ -27,7 +30,8 @@ const USAGE = `usage: design-kit <command> [options]
 
 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.`;
+not run (or init found the repository already set up), 2 a config or usage
+error.`;
 
 function parse(argv, spec) {
   const options = {};
@@ -153,6 +157,19 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
       return 0;
     }
     if (command === "kit") return await kitCommand(argv.slice(1), env);
+    if (command === "init") {
+      const options = parse(argv.slice(1), {
+        root: "value",
+        "dry-run": "flag",
+        force: "flag",
+      });
+      const { init } = await import("./init.mjs");
+      return init({
+        root: options.root ?? ".",
+        dryRun: Boolean(options["dry-run"]),
+        force: Boolean(options.force),
+      });
+    }
     if (command === "validate") {
       const options = parse(argv.slice(1), { config: "value" });
       const config = loadConfig(options.config);