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.
- package/README.md +8 -4
- package/dist/index.js +61 -12
- 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
|
|
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,
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
382
|
-
|
|
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.
|
|
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
|
+
"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.
|
|
45
|
+
"@types/node": "^26.6.5",
|
|
46
|
+
"esbuild": "^0.28.2",
|
|
46
47
|
"typescript": "~6.0.3",
|
|
47
|
-
"vitest": "^
|
|
48
|
+
"vitest": "^5.0.5"
|
|
48
49
|
}
|
|
49
50
|
}
|