designsource 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +8 -4
  2. package/dist/index.js +61 -12
  3. package/package.json +6 -5
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  The command line for a [DS source](https://designsource.app) design system. Three things it does:
8
8
 
9
9
  - **`integrate`** — add the design system to the app you already have: a `design-system/` folder with your tokens as CSS variables, a prompt that tells your coding agent how to wire them in, and the component kit as reference. Vue, Svelte, Angular or plain CSS.
10
- - **`create`** — start a new Next.js project from it: tokens, all 28 components and your mockup page, running after `pnpm install && pnpm dev`.
10
+ - **`create`** — start a new Next.js project from it: tokens, all 61 components, the block pages (`/blocks`) and your mockup page, running after `pnpm install && pnpm dev`.
11
11
  - **`mcp`** — serve the design system to your coding agent over MCP: tokens, every component's source, your mockup page and a step-by-step integration guide, read on demand instead of pasted. Claude Code, Cursor, Codex — any client that speaks MCP over stdio.
12
12
 
13
13
  ```sh
@@ -52,7 +52,7 @@ Writes `design-system/` into the folder (default: the current one). Refuses when
52
52
  npx designsource create [folder] [--token <project token>] [--api <origin>] [--force]
53
53
  ```
54
54
 
55
- Writes a runnable Next.js app into a new or empty folder (default `my-design-system`): Tailwind v4 with the shadcn theme CSS built from your tokens, 28 UI components under `components/ui`, your mockup page on `/`, a component gallery on `/components`, light and dark via `next-themes`. Next steps print in the dialect of the runner you used (`pnpm`, `npm`, `yarn` or `bun`); a pnpm run pins `packageManager`.
55
+ Writes a runnable Next.js app into a new or empty folder (default `my-design-system`): Tailwind v4 with the shadcn theme CSS built from your tokens, 61 UI components under `components/ui`, your mockup page on `/`, a component gallery on `/components`, light and dark via `next-themes`. Next steps print in the dialect of the runner you used (`pnpm`, `npm`, `yarn` or `bun`); a pnpm run pins `packageManager`.
56
56
 
57
57
  <p align="center">
58
58
  <img src="https://designsource.app/designsource/starter-dark-home.png" alt="Generated Next.js starter, home page, dark" width="49%">
@@ -126,10 +126,14 @@ The workbench's Copy dialog hands out all three. Then ask the agent to integrate
126
126
  | `get_tokens` | Tokens as `{path, $type, $value: {light, dark}, ref}`; filter by `tier`, `category`, `component`. |
127
127
  | `get_css_variables` | Every token as plain CSS custom properties, light and dark — for any stack. |
128
128
  | `get_shadcn_theme` | The shadcn/ui theme stylesheet for Tailwind v4. |
129
- | `list_components` | The 28 components and the CSS variables each reads. |
129
+ | `list_components` | The 61 components and the CSS variables each reads. |
130
130
  | `get_component_source` | One component's React source (`utils` for the `cn` helper): verbatim in React + Tailwind, the spec to port from elsewhere. |
131
131
  | `get_mockup_page` | Your mockup page as a layout spec plus the renderer that paints it. |
132
132
  | `get_integration_guide` | The steps: wire the tokens, bring in the components, migrate existing styles, document. |
133
+ | `list_blocks` | The 34 ready-made page layouts (login, signup, sidebars, a dashboard, chart sets) with the components and files of each. |
134
+ | `get_block_source` | Every file of one block, headed by the path it takes under `components/blocks/`. |
135
+
136
+ New in 0.4.0: `list_blocks` and `get_block_source`, the page layouts built from the components. `create` now also writes them as `/blocks` pages, and `integrate` drops them under `design-system/reference/blocks/`. Against an older server the two tools answer that the server sent no blocks.
133
137
 
134
138
  Read-only: nothing an agent does here changes the design system. The project is fetched on the first tool call and refreshed every 60 seconds, so a Save in the workbench shows on the next call. Like every export, it needs the project's account on Pro; on the free plan every tool answers with one line saying so.
135
139
 
@@ -175,7 +179,7 @@ By the maintainer, through GitHub Actions with npm trusted publishing: no npm to
175
179
  3. Tag the merge commit `designsource@<version>` and push the tag:
176
180
 
177
181
  ```sh
178
- git tag designsource@0.3.0 && git push origin designsource@0.3.0
182
+ git tag designsource@0.4.1 && git push origin designsource@0.4.1
179
183
  ```
180
184
 
181
185
  The workflow (`.github/workflows/release-designsource.yml`) refuses a tag that does not match `package.json`, runs the tests (which build `dist/` first), publishes, then installs the published version from npm and runs `--help` against it.
package/dist/index.js CHANGED
@@ -52,6 +52,7 @@ var ArgsError = class extends Error {
52
52
  super(message);
53
53
  this.usage = usage;
54
54
  }
55
+ usage;
55
56
  };
56
57
  function baseArgs(env) {
57
58
  const args = { api: DEFAULT_API_ORIGIN, force: false };
@@ -133,6 +134,7 @@ function parseVerb(verb, argv, env) {
133
134
  }
134
135
  if (verb === "create") {
135
136
  const { framework: _drop, ...common } = args;
137
+ void _drop;
136
138
  return { kind: "create", args: common };
137
139
  }
138
140
  return { kind: "integrate", args };
@@ -144,6 +146,7 @@ var CliError = class extends Error {
144
146
  super(message);
145
147
  this.exitCode = exitCode;
146
148
  }
149
+ exitCode;
147
150
  };
148
151
  var CANCELLED = "Cancelled.";
149
152
  var TOKEN_MESSAGE = "Project token not recognised. In the workbench open Project settings and copy the project token.";
@@ -323,7 +326,7 @@ function nextStepsText({ runner, framework, folder, created }) {
323
326
 
324
327
  // src/write.ts
325
328
  import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
326
- import { dirname, resolve as resolve2 } from "node:path";
329
+ import { dirname, relative, resolve as resolve2 } from "node:path";
327
330
 
328
331
  // src/paths.ts
329
332
  import { isAbsolute, resolve, sep } from "node:path";
@@ -349,7 +352,7 @@ function planTarget(cwd, folder, framework, force) {
349
352
  }
350
353
  return { root, created: false };
351
354
  }
352
- function writeFiles(root, files, opts) {
355
+ function writeFiles(root, files, opts, writeFile = writeFileSync) {
353
356
  const targets = files.map((f) => ({ file: f, abs: resolveInside(root, f.path) }));
354
357
  if (!opts.force) {
355
358
  const clash = targets.find((t) => existsSync(t.abs));
@@ -357,13 +360,15 @@ function writeFiles(root, files, opts) {
357
360
  }
358
361
  const written = [];
359
362
  const previous = /* @__PURE__ */ new Map();
363
+ const madeDirs = [];
360
364
  let failingPath;
361
365
  try {
362
366
  for (const { file, abs } of targets) {
363
367
  failingPath = file.path;
364
368
  if (!previous.has(file.path)) previous.set(file.path, existsSync(abs) ? readFileSync(abs) : void 0);
369
+ madeDirs.push(...missingDirs(root, dirname(abs)));
365
370
  mkdirSync(dirname(abs), { recursive: true });
366
- writeFileSync(abs, file.path === "package.json" && opts.packageManager ? withPackageManager(file.contents, opts.packageManager) : file.contents);
371
+ writeFile(abs, file.path === "package.json" && opts.packageManager ? withPackageManager(file.contents, opts.packageManager) : file.contents);
367
372
  written.push(file.path);
368
373
  }
369
374
  } catch (e) {
@@ -374,21 +379,32 @@ function writeFiles(root, files, opts) {
374
379
  }
375
380
  let restored = 0;
376
381
  let removed = 0;
377
- for (const p of written) {
382
+ for (const [p, before] of previous) {
378
383
  const abs = resolveInside(root, p);
379
- const before = previous.get(p);
380
384
  if (before === void 0) {
381
- rmSync(abs, { force: true });
382
- removed++;
385
+ if (existsSync(abs) && statSync(abs).isFile()) {
386
+ rmSync(abs, { force: true });
387
+ removed++;
388
+ }
383
389
  } else {
384
390
  writeFileSync(abs, before);
385
391
  restored++;
386
392
  }
387
393
  }
394
+ for (const dir of [...madeDirs].reverse()) rmSync(dir, { recursive: true, force: true });
388
395
  throw new CliError(`Could not write ${failingPath} (${code2}). Restored ${restored} file(s) and removed ${removed} new file(s); the folder is as it was.`);
389
396
  }
390
397
  return { written };
391
398
  }
399
+ function missingDirs(root, dir) {
400
+ const missing = [];
401
+ let d = dir;
402
+ while (relative(root, d) !== "" && !relative(root, d).startsWith("..") && !existsSync(d)) {
403
+ missing.unshift(d);
404
+ d = dirname(d);
405
+ }
406
+ return missing;
407
+ }
392
408
  function withPackageManager(contents, packageManager) {
393
409
  const pkg = JSON.parse(contents);
394
410
  return `${JSON.stringify({ ...pkg, packageManager }, null, 2)}
@@ -504,7 +520,7 @@ async function runIntegrate(args, env, io) {
504
520
  import { createInterface as createInterface2 } from "node:readline";
505
521
 
506
522
  // src/version.ts
507
- var VERSION = true ? "0.3.0" : "0.0.0-dev";
523
+ var VERSION = true ? "0.4.1" : "0.0.0-dev";
508
524
 
509
525
  // src/mcp/jsonrpc.ts
510
526
  var PARSE_ERROR = -32700;
@@ -567,8 +583,16 @@ var TIERS = ["design", "semantic", "component"];
567
583
  var CATEGORIES = ["color", "spacing", "radius", "typography", "shadow", "zIndex", "border"];
568
584
  var NO_INPUT = { type: "object", properties: {}, additionalProperties: false };
569
585
  var pretty = (v) => JSON.stringify(v, null, 2);
586
+ var NO_BLOCKS = "This server sent no blocks. Update designsource and the server.";
570
587
  var SOURCE_HEADER = "// Reference implementation. Use verbatim in React + Tailwind; port to your stack otherwise, keeping every var() chain.";
588
+ var FALLBACK_BLOCK_SOURCE_HEADER = `${SOURCE_HEADER}
589
+ // The block renders inside BlockStage (components/blocks/stage.tsx, below), which supplies the @container/stage its
590
+ // responsive classes query and the frame height its min-h-full fills: render <BlockStage><Block /></BlockStage> as a
591
+ // full-viewport page. components/ui/preview-portal.tsx is the portal context the stage provides; the kit components
592
+ // list_blocks names for this block come from get_component_source.`;
571
593
  var UTILS_HEADER = "// The `cn` helper every component imports from `@/lib/utils`. Save as lib/utils.ts in React; port or drop elsewhere.";
594
+ var PORTAL_HEADER = "// The portal context components import from `./preview-portal`. Save it beside them as components/ui/preview-portal.tsx in React: with no provider it portals to document.body, as stock shadcn does. Port or drop elsewhere.";
595
+ var blockAppPath = (key) => key.startsWith("kit/") ? `components/ui/${key.slice("kit/".length)}` : `components/${key}`;
572
596
  var componentsIn = (snapshot) => [...new Set(snapshot.canonical.tokens.map((t) => t.component).filter((c) => c !== null))].sort();
573
597
  function optionalEnum(args, key, allowed) {
574
598
  const v = args[key];
@@ -635,13 +659,13 @@ var TOOLS = [
635
659
  },
636
660
  {
637
661
  name: "get_component_source",
638
- description: 'The React + Tailwind source of one component (see list_components), or "utils" for the cn helper. Use verbatim in React; port to any other stack keeping every var() chain.',
639
- inputSchema: { type: "object", properties: { name: { type: "string", description: "A name from list_components, or utils." } }, required: ["name"], additionalProperties: false },
662
+ description: 'The React + Tailwind source of one component (see list_components), or a helper: "utils" for the cn helper, "preview-portal" for the portal context components import. Use verbatim in React; port to any other stack keeping every var() chain.',
663
+ inputSchema: { type: "object", properties: { name: { type: "string", description: "A name from list_components, or a helper (utils, preview-portal)." } }, required: ["name"], additionalProperties: false },
640
664
  run: (snapshot, _at, args) => {
641
665
  const names = Object.keys(snapshot.kit.sources).sort();
642
666
  const name = args.name;
643
667
  if (typeof name !== "string" || !names.includes(name)) return errorResult(`"name" must be one of: ${names.join(", ")}.`);
644
- const header = name in snapshot.kit.variables ? SOURCE_HEADER : UTILS_HEADER;
668
+ const header = name in snapshot.kit.variables ? SOURCE_HEADER : name === "preview-portal" ? PORTAL_HEADER : UTILS_HEADER;
645
669
  return textResult(`${header}
646
670
  ${snapshot.kit.sources[name]}`);
647
671
  }
@@ -664,6 +688,27 @@ ${files.join("\n")}`);
664
688
  description: "Step-by-step instructions for integrating this design system into the current repository: wire the tokens, bring in the components, migrate existing styles, document. Read this before changing anything.",
665
689
  inputSchema: NO_INPUT,
666
690
  run: (snapshot) => textResult(snapshot.guide)
691
+ },
692
+ {
693
+ name: "list_blocks",
694
+ description: "Ready-made page layouts built from the kit (login, signup, sidebars, a dashboard, chart sets): id, title, family, components used and files. Follow with get_block_source.",
695
+ inputSchema: NO_INPUT,
696
+ run: (snapshot) => snapshot.blocks ? textResult(pretty(snapshot.blocks.index)) : errorResult(NO_BLOCKS)
697
+ },
698
+ {
699
+ name: "get_block_source",
700
+ description: "Every file of one block (see list_blocks), each headed by the path it takes in the app: the block under components/blocks/, plus BlockStage (components/blocks/stage.tsx), which supplies the @container/stage its responsive classes query and the frame height, and the portal context it provides (components/ui/preview-portal.tsx). Render <BlockStage><Block /></BlockStage> as a full-viewport page. Use verbatim in React + Tailwind; port elsewhere keeping every var() chain.",
701
+ inputSchema: { type: "object", properties: { id: { type: "string", description: "A block id from list_blocks." } }, required: ["id"], additionalProperties: false },
702
+ run: (snapshot, _at, args) => {
703
+ const blocks = snapshot.blocks;
704
+ if (!blocks) return errorResult(NO_BLOCKS);
705
+ const entry = blocks.index.find((b) => b.id === args.id);
706
+ if (!entry) return errorResult(`"id" must be one of: ${blocks.index.map((b) => b.id).join(", ")}.`);
707
+ const files = entry.files.map((f) => `--- file: ${blockAppPath(f)}
708
+ ${blocks.sources[f] ?? ""}`);
709
+ return textResult(`${blocks.header ?? FALLBACK_BLOCK_SOURCE_HEADER}
710
+ ${files.join("\n\n")}`);
711
+ }
667
712
  }
668
713
  ];
669
714
  var TOOL_NAMES = TOOLS.map((t) => t.name);
@@ -734,16 +779,20 @@ var malformed2 = () => new CliError("Unexpected response from the API \u2014 not
734
779
  var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
735
780
  var isStringRecord = (v) => isObject(v) && Object.values(v).every((x) => typeof x === "string");
736
781
  var isStringListRecord = (v) => isObject(v) && Object.values(v).every((x) => Array.isArray(x) && x.every((s) => typeof s === "string"));
782
+ var isBlockEntry = (v) => isObject(v) && typeof v.id === "string" && typeof v.title === "string" && typeof v.family === "string" && Array.isArray(v.components) && v.components.every((c) => typeof c === "string") && Array.isArray(v.files) && v.files.every((f) => typeof f === "string");
737
783
  function validateSnapshot(json) {
738
784
  if (!isObject(json)) throw malformed2();
739
785
  if (typeof json.version !== "number") throw malformed2();
740
786
  if (json.version !== 1) throw new CliError(UPDATE_MESSAGE);
741
- const { project, canonical, cssVars, shadcnTheme, kit, mockup, guide } = json;
787
+ const { project, canonical, cssVars, shadcnTheme, kit, mockup, blocks, guide } = json;
742
788
  if (!isObject(project) || typeof project.name !== "string" || typeof project.radiusStrategy !== "string" || typeof project.tokenCount !== "number" || typeof project.hasMockup !== "boolean" || !isStringRecord(project.fonts)) throw malformed2();
743
789
  if (!isObject(canonical) || !Array.isArray(canonical.tokens) || !canonical.tokens.every(isObject)) throw malformed2();
744
790
  if (typeof cssVars !== "string" || typeof shadcnTheme !== "string" || typeof guide !== "string") throw malformed2();
745
791
  if (!isObject(kit) || !isStringRecord(kit.sources) || !isStringListRecord(kit.variables)) throw malformed2();
746
792
  if (mockup !== null && !(isObject(mockup) && isObject(mockup.spec) && isStringRecord(mockup.renderer))) throw malformed2();
793
+ const validBlocks = isObject(blocks) && Array.isArray(blocks.index) && blocks.index.every(isBlockEntry) && isStringRecord(blocks.sources);
794
+ if (!validBlocks) return { ...json, blocks: void 0 };
795
+ if (blocks.header !== void 0 && typeof blocks.header !== "string") return { ...json, blocks: { ...blocks, header: void 0 } };
747
796
  return json;
748
797
  }
749
798
  var FETCH_TIMEOUT_MS = 3e4;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "designsource",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "The DS source CLI: add a design system to an existing app (integrate), start a new Next.js project from it (create), or serve it to a coding agent over MCP (mcp) — tokens, every component and your mockup page.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -38,12 +38,13 @@
38
38
  "build": "node esbuild.mjs",
39
39
  "prepublishOnly": "node esbuild.mjs",
40
40
  "start": "node dist/index.js",
41
- "test": "node esbuild.mjs && vitest run"
41
+ "test": "node esbuild.mjs && vitest run",
42
+ "typecheck": "tsc --noEmit"
42
43
  },
43
44
  "devDependencies": {
44
- "@types/node": "^26",
45
- "esbuild": "^0.24.0",
45
+ "@types/node": "^26.6.5",
46
+ "esbuild": "^0.28.2",
46
47
  "typescript": "~6.0.3",
47
- "vitest": "^4.1.10"
48
+ "vitest": "^5.0.5"
48
49
  }
49
50
  }