fastdraw 0.2.0 → 0.2.2
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 +42 -4
- package/agents/AGENTS-snippet.md +2 -1
- package/agents/README.md +9 -5
- package/dist/cli.js +122 -24
- package/guide/guide.md +28 -9
- package/package.json +4 -2
- package/plugins/fastdraw/.claude-plugin/plugin.json +18 -0
- package/plugins/fastdraw/skills/fastdraw/SKILL.md +21 -0
- package/agents/claude-skill/fastdraw/SKILL.md +0 -19
package/README.md
CHANGED
|
@@ -43,17 +43,55 @@ line number, so an agent can fix its own layout before anyone looks at it.
|
|
|
43
43
|
|
|
44
44
|
## Getting started
|
|
45
45
|
|
|
46
|
-
FastDraw needs Node 20 or later.
|
|
46
|
+
FastDraw needs Node 20 or later. Install the skill for your coding agent once; it then works in every
|
|
47
|
+
repository.
|
|
48
|
+
|
|
49
|
+
**Claude Code**, typed in a session:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
/plugin install fastdraw --marketplace coccor/fastdraw
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
On Claude Code older than 2.1.275, run `/plugin marketplace add coccor/fastdraw`, then
|
|
56
|
+
`/plugin install fastdraw@fastdraw`.
|
|
57
|
+
|
|
58
|
+
**Codex, OpenCode, Cursor and other agents**, in a terminal:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
npx skills add coccor/fastdraw -g
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
It asks which of your agents to install for. Without `-g` the skill goes into the current repository
|
|
65
|
+
instead, for a team to commit.
|
|
66
|
+
|
|
67
|
+
**GitHub Copilot** reads only its instructions file, so run this in the repository:
|
|
68
|
+
`npx fastdraw setup copilot`. Chat assistants without a shell can read the language from
|
|
69
|
+
https://fastdraw.dev/llms.txt.
|
|
70
|
+
|
|
71
|
+
Then ask your agent for a diagram. It runs the command-line tool through `npx`, so there is nothing
|
|
72
|
+
else to install:
|
|
47
73
|
|
|
48
74
|
```
|
|
49
|
-
npx fastdraw setup # add FastDraw instructions for this repo's coding agents
|
|
50
75
|
npx fastdraw check docs/example.fdraw # report problems, with line numbers
|
|
51
76
|
npx fastdraw render docs/example.fdraw # write example.png next to the file
|
|
52
77
|
npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
|
|
53
78
|
```
|
|
54
79
|
|
|
55
|
-
|
|
56
|
-
|
|
80
|
+
### Updating
|
|
81
|
+
|
|
82
|
+
The skill is short: it tells the agent to run `fastdraw guide`, and the guide, the kinds of diagram, the
|
|
83
|
+
looks, `check` and `render` all come from the fastdraw that runs. Through `npx fastdraw` that is the
|
|
84
|
+
newest release, so most of an update arrives by itself. The skill itself updates with
|
|
85
|
+
`/plugin marketplace update fastdraw` in Claude Code (or turn on auto-update for the fastdraw marketplace
|
|
86
|
+
under `/plugin`), and with `npx skills update` elsewhere.
|
|
87
|
+
|
|
88
|
+
Files written by `npx fastdraw setup` (an older way to install, still used for Copilot) carry the version
|
|
89
|
+
that wrote them. When they are older than the fastdraw running, `fastdraw guide` starts with a note asking
|
|
90
|
+
the agent to tell you; run `npx fastdraw@latest setup` in the repository to update them.
|
|
91
|
+
|
|
92
|
+
If fastdraw is installed on the PATH (`npm install -g fastdraw`), agents use that copy instead of `npx`.
|
|
93
|
+
`fastdraw guide` checks npm for a newer release at most once a day and says so when there is one; update
|
|
94
|
+
with `npm install -g fastdraw@latest`. Set `FASTDRAW_NO_UPDATE_CHECK=1` to turn the check off; it is off on CI.
|
|
57
95
|
|
|
58
96
|
## Features
|
|
59
97
|
|
package/agents/AGENTS-snippet.md
CHANGED
|
@@ -6,7 +6,8 @@ Diagrams in this repo are FastDraw files (`.fdraw`), drawn with the look in `.lo
|
|
|
6
6
|
|
|
7
7
|
- Save a new diagram in `docs/diagrams/` unless the person names another place or the repo already keeps its `.fdraw` files somewhere; never at the top of the repo.
|
|
8
8
|
- Before writing or changing one, run `fastdraw guide` and follow it; it is the only reference for the language.
|
|
9
|
-
-
|
|
9
|
+
- For a diagram of the code, learn the system first: every project or service, how each talks to the others (HTTP clients, queues, shared stores, config), and the paths a request or event takes. Read every project, not only the first. Do not shrink a big system into a few vague boxes; propose an overview plus one diagram per main path, or the one path the person cares about.
|
|
10
|
+
- Choose the kind of diagram by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart; "architecture diagram" is said of any system picture); `fastdraw guide list` says what each kind shows. Unless the request names exactly one kind and nothing in it pulls toward another, ask before drawing: the kind you would draw and the closest other kind, which path when there are several, and the split when the system is too big for one picture.
|
|
10
11
|
- Finish with `fastdraw check <file>` clean, then run `fastdraw render <file>` and look at the PNG.
|
|
11
12
|
- `fastdraw check <folder>` and `fastdraw render <folder>` work on every `.fdraw` file under a folder. `fastdraw render <file> --dark` also writes `<file>-dark.png` with the look's dark version, for sites with a dark theme; `--look <name|file.look>` draws with another look without changing the file.
|
|
12
13
|
- When the diagram is done, always ask the person what to do next: open it in fastdraw.dev (run `fastdraw open <file>` in the background, then give them the link it prints in case no browser window appeared; edits save back to the file), preview the PNG (open it in their image viewer), or nothing. Do not open anything before they choose.
|
package/agents/README.md
CHANGED
|
@@ -1,15 +1,19 @@
|
|
|
1
1
|
# Telling agents about FastDraw
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
There is one skill, in [`../plugins/fastdraw/skills/fastdraw/SKILL.md`](../plugins/fastdraw/skills/fastdraw/SKILL.md).
|
|
4
|
+
It is a thin pointer to `fastdraw guide`, so there is one place to maintain. It reaches agents three ways:
|
|
5
5
|
|
|
6
|
-
| Agent |
|
|
6
|
+
| Agent | How | What it installs |
|
|
7
7
|
|---|---|---|
|
|
8
|
-
| Claude Code |
|
|
9
|
-
| Codex, OpenCode | `npx fastdraw
|
|
8
|
+
| Claude Code | `/plugin install fastdraw --marketplace coccor/fastdraw` | the `fastdraw` plugin from [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json), for the user |
|
|
9
|
+
| Codex, OpenCode, Cursor and others | `npx skills add coccor/fastdraw -g` | the skill in `~/.agents/skills/fastdraw/` and each chosen agent's folder ([skills.sh](https://skills.sh) finds it through the plugin manifest) |
|
|
10
10
|
| GitHub Copilot | `npx fastdraw setup copilot` | `AGENTS-snippet.md` as a section of `.github/copilot-instructions.md` |
|
|
11
|
+
| A repository that commits its instructions | `npx fastdraw setup claude` or `setup agents` | the skill as `.claude/skills/fastdraw/`, or `AGENTS-snippet.md` as a section of `AGENTS.md` |
|
|
11
12
|
| Chat assistants | none | Ask it to read https://fastdraw.dev/llms.txt first (or paste that file in), then paste the reply into the editor with "Paste diagram text" |
|
|
12
13
|
|
|
14
|
+
The plugin has no `version`, so Claude Code users follow the commits on `main` when they update.
|
|
15
|
+
`claude plugin validate .` checks the marketplace and the plugin.
|
|
16
|
+
|
|
13
17
|
## Diagrams on a docs site
|
|
14
18
|
|
|
15
19
|
A README on GitHub can only show the PNG from `fastdraw render`. A docs site (Starlight, Docusaurus,
|
package/dist/cli.js
CHANGED
|
@@ -10307,8 +10307,8 @@ var init_iconSetAll = __esm({
|
|
|
10307
10307
|
});
|
|
10308
10308
|
|
|
10309
10309
|
// src/cli.ts
|
|
10310
|
-
import { readFileSync as
|
|
10311
|
-
import { dirname as
|
|
10310
|
+
import { readFileSync as readFileSync5, writeFileSync as writeFileSync5, readdirSync as readdirSync2, existsSync as existsSync4, statSync as statSync2 } from "node:fs";
|
|
10311
|
+
import { dirname as dirname5, join as join5, resolve as resolve4, basename as basename2 } from "node:path";
|
|
10312
10312
|
import { fileURLToPath as fileURLToPath2 } from "node:url";
|
|
10313
10313
|
|
|
10314
10314
|
// src/node.ts
|
|
@@ -15300,11 +15300,14 @@ function about(md, name2) {
|
|
|
15300
15300
|
|
|
15301
15301
|
// src/setup.ts
|
|
15302
15302
|
import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync3, mkdirSync, realpathSync as realpathSync3, lstatSync as lstatSync3 } from "node:fs";
|
|
15303
|
-
import { join as join3, relative as relative2, sep as sep3 } from "node:path";
|
|
15303
|
+
import { dirname as dirname3, join as join3, relative as relative2, resolve as resolve3, sep as sep3 } from "node:path";
|
|
15304
15304
|
import { homedir } from "node:os";
|
|
15305
15305
|
var TARGETS = ["claude", "agents", "copilot"];
|
|
15306
15306
|
var START = "<!-- fastdraw:start -->";
|
|
15307
15307
|
var END = "<!-- fastdraw:end -->";
|
|
15308
|
+
var STAMP = /<!-- fastdraw-version: ([\d.]+) -->/;
|
|
15309
|
+
var stamp = (version) => `<!-- fastdraw-version: ${version} -->`;
|
|
15310
|
+
var packageVersion = (root2) => JSON.parse(readFileSync3(join3(root2, "package.json"), "utf8")).version;
|
|
15308
15311
|
function snippet(root2) {
|
|
15309
15312
|
return readFileSync3(join3(root2, "agents", "AGENTS-snippet.md"), "utf8").replace(/^<!--.*?-->\s*/s, "").trim();
|
|
15310
15313
|
}
|
|
@@ -15332,8 +15335,9 @@ function prepare(base, file) {
|
|
|
15332
15335
|
if (!st && i < parts.length - 1) mkdirSync(at);
|
|
15333
15336
|
}
|
|
15334
15337
|
}
|
|
15335
|
-
function upsert(base, file, body) {
|
|
15338
|
+
function upsert(base, file, body, version) {
|
|
15336
15339
|
const block = `${START}
|
|
15340
|
+
${stamp(version)}
|
|
15337
15341
|
${body}
|
|
15338
15342
|
${END}`;
|
|
15339
15343
|
prepare(base, file);
|
|
@@ -15358,7 +15362,7 @@ function detect(dir) {
|
|
|
15358
15362
|
return found.length ? found : ["claude", "agents"];
|
|
15359
15363
|
}
|
|
15360
15364
|
function setup(root2, dir, targets, global = false) {
|
|
15361
|
-
const lines = [];
|
|
15365
|
+
const lines = [], version = packageVersion(root2);
|
|
15362
15366
|
const show = (f) => f.startsWith(dir) ? relative2(dir, f) : f.replace(homedir(), "~");
|
|
15363
15367
|
for (const t of targets) {
|
|
15364
15368
|
if (t === "claude") {
|
|
@@ -15367,23 +15371,108 @@ function setup(root2, dir, targets, global = false) {
|
|
|
15367
15371
|
const was = existsSync3(file);
|
|
15368
15372
|
if (global) mkdirSync(base, { recursive: true });
|
|
15369
15373
|
prepare(base, file);
|
|
15370
|
-
|
|
15374
|
+
const skill = readFileSync3(join3(root2, "plugins", "fastdraw", "skills", "fastdraw", "SKILL.md"), "utf8");
|
|
15375
|
+
writeFileSync3(file, skill.replace(/^(---\r?\n[\s\S]*?\r?\n---\r?\n)/, `$1${stamp(version)}
|
|
15376
|
+
`));
|
|
15371
15377
|
lines.push(`${was ? "updated" : "wrote"} ${show(file)} (Claude Code skill)`);
|
|
15372
15378
|
} else {
|
|
15373
15379
|
const file = t === "agents" ? join3(dir, "AGENTS.md") : join3(dir, ".github", "copilot-instructions.md");
|
|
15374
|
-
lines.push(`${upsert(dir, file, snippet(root2))} ${show(file)} (${t === "agents" ? "Codex, OpenCode and other agents that read AGENTS.md" : "GitHub Copilot"})`);
|
|
15380
|
+
lines.push(`${upsert(dir, file, snippet(root2), version)} ${show(file)} (${t === "agents" ? "Codex, OpenCode and other agents that read AGENTS.md" : "GitHub Copilot"})`);
|
|
15375
15381
|
}
|
|
15376
15382
|
}
|
|
15377
15383
|
return lines;
|
|
15378
15384
|
}
|
|
15385
|
+
function compareVersions(a, b) {
|
|
15386
|
+
const x = a.split(".").map(Number), y = b.split(".").map(Number);
|
|
15387
|
+
for (let i = 0; i < Math.max(x.length, y.length); i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
|
|
15388
|
+
return 0;
|
|
15389
|
+
}
|
|
15390
|
+
function installedSkills(dir, home = homedir()) {
|
|
15391
|
+
const out = [];
|
|
15392
|
+
const look = (target, file, global = false, section = false) => {
|
|
15393
|
+
let text;
|
|
15394
|
+
try {
|
|
15395
|
+
text = readFileSync3(file, "utf8");
|
|
15396
|
+
} catch {
|
|
15397
|
+
return;
|
|
15398
|
+
}
|
|
15399
|
+
if (section && !text.includes(START)) return;
|
|
15400
|
+
out.push({ target, file, version: STAMP.exec(text)?.[1] ?? "", global });
|
|
15401
|
+
};
|
|
15402
|
+
for (let at = resolve3(dir); ; at = dirname3(at)) {
|
|
15403
|
+
look("claude", join3(at, ".claude", "skills", "fastdraw", "SKILL.md"));
|
|
15404
|
+
look("agents", join3(at, "AGENTS.md"), false, true);
|
|
15405
|
+
look("copilot", join3(at, ".github", "copilot-instructions.md"), false, true);
|
|
15406
|
+
if (out.length || existsSync3(join3(at, ".git")) || dirname3(at) === at) break;
|
|
15407
|
+
}
|
|
15408
|
+
if (resolve3(home) !== resolve3(dir)) look("claude", join3(home, ".claude", "skills", "fastdraw", "SKILL.md"), true);
|
|
15409
|
+
return out;
|
|
15410
|
+
}
|
|
15411
|
+
function skillNotes(root2, dir, home = homedir()) {
|
|
15412
|
+
const version = packageVersion(root2), found = installedSkills(dir, home), notes = [];
|
|
15413
|
+
const from = (fs) => [...new Set(fs.map((f) => f.version || "0.2.0 or earlier"))].join(", ");
|
|
15414
|
+
const old = found.filter((f) => !f.version || compareVersions(f.version, version) < 0);
|
|
15415
|
+
const local = old.filter((f) => !f.global), global = old.filter((f) => f.global);
|
|
15416
|
+
if (local.length) {
|
|
15417
|
+
const files = local.map((f) => relative2(resolve3(dir), f.file) || f.file).join(", ");
|
|
15418
|
+
notes.push(`Note: this repository's FastDraw instructions (${files}) are from version ${from(local)}; this fastdraw is ${version}. Tell the person, and to update them run in the repository: npx fastdraw@latest setup ${[...new Set(local.map((f) => f.target))].join(" ")}`);
|
|
15419
|
+
}
|
|
15420
|
+
if (global.length) {
|
|
15421
|
+
notes.push(`Note: the FastDraw skill in ${global[0].file.replace(home, "~")} is from version ${from(global)}; this fastdraw is ${version}. Tell the person, and to update it run: npx fastdraw@latest setup claude --global`);
|
|
15422
|
+
}
|
|
15423
|
+
const newer = found.filter((f) => f.version && compareVersions(f.version, version) > 0);
|
|
15424
|
+
if (newer.length) {
|
|
15425
|
+
notes.push(`Note: this fastdraw is ${version}, older than the FastDraw instructions here (${newer[0].version}). Run it as npx fastdraw@latest instead, or update the installed one: npm install -g fastdraw@latest`);
|
|
15426
|
+
}
|
|
15427
|
+
return notes;
|
|
15428
|
+
}
|
|
15429
|
+
|
|
15430
|
+
// src/update.ts
|
|
15431
|
+
import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
|
|
15432
|
+
import { dirname as dirname4, join as join4 } from "node:path";
|
|
15433
|
+
import { homedir as homedir2 } from "node:os";
|
|
15434
|
+
var DAY = 24 * 60 * 60 * 1e3;
|
|
15435
|
+
var URL2 = "https://registry.npmjs.org/fastdraw/latest";
|
|
15436
|
+
function cacheFile(env = process.env, home = homedir2(), platform = process.platform) {
|
|
15437
|
+
const base = platform === "win32" ? env.LOCALAPPDATA ?? join4(home, "AppData", "Local") : platform === "darwin" ? join4(home, "Library", "Caches") : env.XDG_CACHE_HOME ?? join4(home, ".cache");
|
|
15438
|
+
return join4(base, "fastdraw", "latest.json");
|
|
15439
|
+
}
|
|
15440
|
+
async function fromRegistry() {
|
|
15441
|
+
const r = await fetch(URL2, { signal: AbortSignal.timeout(1500), headers: { accept: "application/json" } });
|
|
15442
|
+
if (!r.ok) throw new Error(`npm answered ${r.status}`);
|
|
15443
|
+
return (await r.json()).version;
|
|
15444
|
+
}
|
|
15445
|
+
async function newerVersion(current, o = {}) {
|
|
15446
|
+
const env = o.env ?? process.env, now = o.now ?? Date.now(), file = o.file ?? cacheFile(env);
|
|
15447
|
+
if (env.FASTDRAW_NO_UPDATE_CHECK || env.CI) return null;
|
|
15448
|
+
let cached = null;
|
|
15449
|
+
try {
|
|
15450
|
+
cached = JSON.parse(readFileSync4(file, "utf8"));
|
|
15451
|
+
} catch {
|
|
15452
|
+
}
|
|
15453
|
+
let latest = cached?.latest ?? null;
|
|
15454
|
+
if (!cached || !(now - cached.checked < DAY)) {
|
|
15455
|
+
try {
|
|
15456
|
+
latest = await (o.fetchLatest ?? fromRegistry)();
|
|
15457
|
+
} catch {
|
|
15458
|
+
latest = null;
|
|
15459
|
+
}
|
|
15460
|
+
try {
|
|
15461
|
+
mkdirSync2(dirname4(file), { recursive: true });
|
|
15462
|
+
writeFileSync4(file, JSON.stringify({ checked: now, latest }));
|
|
15463
|
+
} catch {
|
|
15464
|
+
}
|
|
15465
|
+
}
|
|
15466
|
+
return latest && compareVersions(latest, current) > 0 ? latest : null;
|
|
15467
|
+
}
|
|
15379
15468
|
|
|
15380
15469
|
// src/cli.ts
|
|
15381
|
-
var root =
|
|
15470
|
+
var root = resolve4(dirname5(fileURLToPath2(import.meta.url)), "..");
|
|
15382
15471
|
function isWsl() {
|
|
15383
15472
|
if (process.platform !== "linux") return false;
|
|
15384
15473
|
if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
|
|
15385
15474
|
try {
|
|
15386
|
-
return /microsoft/i.test(
|
|
15475
|
+
return /microsoft/i.test(readFileSync5("/proc/sys/kernel/osrelease", "utf8"));
|
|
15387
15476
|
} catch {
|
|
15388
15477
|
return false;
|
|
15389
15478
|
}
|
|
@@ -15431,7 +15520,9 @@ function usage() {
|
|
|
15431
15520
|
tell this repo's coding agents about FastDraw: a Claude Code
|
|
15432
15521
|
skill, a section in AGENTS.md, or in Copilot's instructions.
|
|
15433
15522
|
With no name, sets up the agents the repo already uses.
|
|
15434
|
-
--global puts the Claude Code skill in ~/.claude for every repo
|
|
15523
|
+
--global puts the Claude Code skill in ~/.claude for every repo.
|
|
15524
|
+
Most people install the skill instead: npx skills add coccor/fastdraw,
|
|
15525
|
+
or /plugin install fastdraw --marketplace coccor/fastdraw in Claude Code`);
|
|
15435
15526
|
process.exit(2);
|
|
15436
15527
|
}
|
|
15437
15528
|
function report(file) {
|
|
@@ -15448,7 +15539,7 @@ ${errors} error(s), ${warns} warning(s), ${hints} hint(s)` : "ok: no problems fo
|
|
|
15448
15539
|
function diagramFiles(paths) {
|
|
15449
15540
|
const files = [];
|
|
15450
15541
|
let folder = false;
|
|
15451
|
-
const walk = (dir) => readdirSync2(dir, { withFileTypes: true }).filter((e) => !e.name.startsWith(".") && e.name !== "node_modules").flatMap((e) => e.isDirectory() ? walk(
|
|
15542
|
+
const walk = (dir) => readdirSync2(dir, { withFileTypes: true }).filter((e) => !e.name.startsWith(".") && e.name !== "node_modules").flatMap((e) => e.isDirectory() ? walk(join5(dir, e.name)) : e.isFile() && e.name.endsWith(".fdraw") ? [join5(dir, e.name)] : []);
|
|
15452
15543
|
for (const p of paths) {
|
|
15453
15544
|
if (existsSync4(p) && statSync2(p).isDirectory()) {
|
|
15454
15545
|
folder = true;
|
|
@@ -15508,7 +15599,7 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15508
15599
|
if (ref) {
|
|
15509
15600
|
look = lookRefText(ref, file);
|
|
15510
15601
|
try {
|
|
15511
|
-
src = withLook(
|
|
15602
|
+
src = withLook(readFileSync5(file, "utf8"), look);
|
|
15512
15603
|
} catch {
|
|
15513
15604
|
}
|
|
15514
15605
|
}
|
|
@@ -15527,7 +15618,7 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15527
15618
|
if (!dark) continue;
|
|
15528
15619
|
let base = lookOver;
|
|
15529
15620
|
if (!base) try {
|
|
15530
|
-
base = lookOfDiagram(file,
|
|
15621
|
+
base = lookOfDiagram(file, readFileSync5(file, "utf8"));
|
|
15531
15622
|
} catch {
|
|
15532
15623
|
continue;
|
|
15533
15624
|
}
|
|
@@ -15554,11 +15645,11 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15554
15645
|
for (const { file, out, src, sc, look } of jobs) {
|
|
15555
15646
|
const svg = renderSvg(sc, void 0, { background: !transparent });
|
|
15556
15647
|
const payload = { v: 1, ...readSources(file, sc, src) };
|
|
15557
|
-
if (out.endsWith(".svg"))
|
|
15648
|
+
if (out.endsWith(".svg")) writeFileSync5(out, embed ? embedSvg(svg, payload) : svg);
|
|
15558
15649
|
else {
|
|
15559
15650
|
const fontFiles = withoutLigatureFonts([...bundledFonts(), ...sc.fontFiles ?? []]);
|
|
15560
15651
|
const png = new Uint8Array(new Resvg(svg, { font: { fontFiles, loadSystemFonts: true, defaultFontFamily: "Geist" }, fitTo: { mode: "zoom", value: scale } }).render().asPng());
|
|
15561
|
-
|
|
15652
|
+
writeFileSync5(out, embed ? embedPng(png, payload) : png);
|
|
15562
15653
|
}
|
|
15563
15654
|
const notes = [out.endsWith(".svg") ? "" : `at ${scale}x`, look ? `look ${look}` : "", transparent ? "no background" : "", embed ? "" : "no diagram inside"].filter(Boolean);
|
|
15564
15655
|
console.log(`wrote ${out} (${sc.w}x${sc.h}${notes.length ? ", " + notes.join(", ") : ""})`);
|
|
@@ -15573,7 +15664,7 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15573
15664
|
console.log(`${out} already exists; choose another path or remove it first`);
|
|
15574
15665
|
process.exit(1);
|
|
15575
15666
|
}
|
|
15576
|
-
|
|
15667
|
+
writeFileSync5(out, DEFAULT_LOOK);
|
|
15577
15668
|
console.log(`wrote ${out}. Point a diagram at it with: look "./${basename2(out)}"`);
|
|
15578
15669
|
} else if (cmd === "preview-look") {
|
|
15579
15670
|
const file = args.find((a, i) => !a.startsWith("-") && args[i - 1] !== "-o");
|
|
@@ -15668,13 +15759,13 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15668
15759
|
process.exit(1);
|
|
15669
15760
|
}
|
|
15670
15761
|
const svg = renderSvg(sc);
|
|
15671
|
-
if (out.endsWith(".svg"))
|
|
15762
|
+
if (out.endsWith(".svg")) writeFileSync5(out, svg);
|
|
15672
15763
|
else {
|
|
15673
15764
|
const { Resvg } = await import("@resvg/resvg-js");
|
|
15674
15765
|
const lf = lookFonts(file, look);
|
|
15675
15766
|
for (const fam2 of lf.missing) console.log(`warning: no font file found for "${fam2}"; it will be drawn in a fallback font`);
|
|
15676
15767
|
const fontFiles = withoutLigatureFonts([...bundledFonts(), ...lf.files]);
|
|
15677
|
-
|
|
15768
|
+
writeFileSync5(out, new Resvg(svg, { font: { fontFiles, loadSystemFonts: true, defaultFontFamily: "Geist" }, fitTo: { mode: "zoom", value: 2 } }).render().asPng());
|
|
15678
15769
|
}
|
|
15679
15770
|
console.log(`wrote ${out}: ${all.length} styles`);
|
|
15680
15771
|
} else if (cmd === "icons") {
|
|
@@ -15684,25 +15775,32 @@ ${files.length} files: ${errors} error(s), ${warns} warning(s), ${hints} hint(s)
|
|
|
15684
15775
|
console.log(names.length ? names.join("\n") : `no icon${word ? ` for "${word}"` : ""}`);
|
|
15685
15776
|
} else if (cmd === "guide") {
|
|
15686
15777
|
const topic = args[0];
|
|
15687
|
-
const file =
|
|
15688
|
-
const topics = readdirSync2(
|
|
15778
|
+
const file = join5(root, "guide", topic ? `${topic}.md` : "guide.md");
|
|
15779
|
+
const topics = readdirSync2(join5(root, "guide")).filter((f) => f.endsWith(".md") && f !== "guide.md").map((f) => f.slice(0, -3)).sort();
|
|
15689
15780
|
if (topic === "list") {
|
|
15690
15781
|
const width = Math.max(...topics.map((t) => t.length)) + 2;
|
|
15691
|
-
for (const t of topics) console.log(t.padEnd(width) + about(
|
|
15782
|
+
for (const t of topics) console.log(t.padEnd(width) + about(readFileSync5(join5(root, "guide", `${t}.md`), "utf8"), t).line);
|
|
15692
15783
|
process.exit(0);
|
|
15693
15784
|
}
|
|
15694
15785
|
if (!existsSync4(file) || /[\\/]/.test(topic ?? "")) {
|
|
15695
15786
|
console.log(`no guide called "${topic}". Topics: ${topics.join(", ")}`);
|
|
15696
15787
|
process.exit(1);
|
|
15697
15788
|
}
|
|
15698
|
-
|
|
15789
|
+
if (!topic) {
|
|
15790
|
+
const version = packageVersion(root);
|
|
15791
|
+
const notes = skillNotes(root, process.cwd());
|
|
15792
|
+
const newer = await newerVersion(version);
|
|
15793
|
+
if (newer) notes.push(`Note: fastdraw ${newer} is out; this is ${version}. Run it as npx fastdraw@latest, or update the installed one: npm install -g fastdraw@latest`);
|
|
15794
|
+
if (notes.length) console.log(notes.join("\n") + "\n");
|
|
15795
|
+
}
|
|
15796
|
+
console.log(readFileSync5(file, "utf8"));
|
|
15699
15797
|
} else if (cmd === "open") {
|
|
15700
15798
|
const file = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--editor");
|
|
15701
15799
|
if (!file || !file.endsWith(".fdraw") || !existsSync4(file)) usage();
|
|
15702
15800
|
const ei = args.indexOf("--editor");
|
|
15703
15801
|
const editor = ei >= 0 ? args[ei + 1] : process.env.FASTDRAW_EDITOR ?? DEFAULT_EDITOR;
|
|
15704
|
-
const s = await serveFolder(
|
|
15705
|
-
console.log(`serving ${
|
|
15802
|
+
const s = await serveFolder(dirname5(resolve4(file)), { editor, open: basename2(file) });
|
|
15803
|
+
console.log(`serving ${dirname5(resolve4(file))} to the editor until this stops (Ctrl-C)
|
|
15706
15804
|
If no browser window opens, open this link:
|
|
15707
15805
|
${s.url}`);
|
|
15708
15806
|
if (!args.includes("--no-browser")) openBrowser(s.url);
|
package/guide/guide.md
CHANGED
|
@@ -5,13 +5,14 @@ FastDraw draws diagrams from a small text file (`.fdraw`). You place every eleme
|
|
|
5
5
|
## How to work
|
|
6
6
|
|
|
7
7
|
1. To create or change a look (how styles are drawn), run `fastdraw guide look` instead of the steps below.
|
|
8
|
-
2.
|
|
9
|
-
3.
|
|
10
|
-
4.
|
|
11
|
-
5.
|
|
12
|
-
6.
|
|
13
|
-
7. Run `fastdraw
|
|
14
|
-
8.
|
|
8
|
+
2. When the diagram is of something in the code (a system, a request, a pipeline), first learn it as described in "Know the system first" below. Do not pick a kind from the request's wording alone.
|
|
9
|
+
3. Choose the kind of diagram and its scope as described in "Choosing the kind" below (`fastdraw guide list` says what each kind shows), and agree them with the person before drawing. If the kind has its own guide, run `fastdraw guide <kind>` and follow it; where it differs from the general rules in this guide, the kind's guide wins.
|
|
10
|
+
4. Run `fastdraw sizes <look file>` to see the styles you can use, their default sizes, and the look's own guidance. Follow that guidance. A diagram with no `look` line uses the built-in look: run `fastdraw sizes` with no file to see it.
|
|
11
|
+
5. Plan the composition on paper first: rows and columns, where the main thing sits.
|
|
12
|
+
6. Write the file. A new diagram goes in `docs/diagrams/` (create the folder) unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never put it at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
|
|
13
|
+
7. Run `fastdraw check <file>`. Fix every error and warning. Read the hints and fix the ones that are real.
|
|
14
|
+
8. Run `fastdraw render <file>` and **look at the PNG**. Fix what looks wrong: cramped labels, uneven gaps, lopsided composition, a label sitting on a border. Repeat from 7 until it is clean and looks good.
|
|
15
|
+
9. When the diagram is done, tell the person where the file is and **ask what they want to do next**, with these three choices (use your tool for asking a question if you have one). Always ask; do not stop without it.
|
|
15
16
|
- **Open in fastdraw.dev**: run `fastdraw open <file>` in the background. It opens the web editor at the diagram, with its look, and saves their edits into the same file. Read its output and give the person the link it prints, in case no browser window appeared. Read the file again before you change it after that.
|
|
16
17
|
- **Preview as PNG**: open the PNG from `fastdraw render` in their image viewer (`xdg-open <file.png>` on Linux, `wslview` or `explorer.exe` under WSL, `open` on macOS, `start ""` on Windows).
|
|
17
18
|
- **Nothing**: stop there.
|
|
@@ -20,9 +21,21 @@ FastDraw draws diagrams from a small text file (`.fdraw`). You place every eleme
|
|
|
20
21
|
|
|
21
22
|
When you change an existing diagram: do not move, resize or restyle anything that is already there unless asked. Place only what you add, in free space.
|
|
22
23
|
|
|
24
|
+
## Know the system first
|
|
25
|
+
|
|
26
|
+
A diagram of a real system is only as good as your knowledge of it. Before choosing a kind, read enough of the code to list:
|
|
27
|
+
|
|
28
|
+
- **The parts.** Every project, service, app, worker, job and store involved, and what each is for. A repo with several projects (a `src/` per service, a solution with many projects, a monorepo's `apps/` and `packages/`) means several parts: open each one, not only the first.
|
|
29
|
+
- **How they talk.** For each connection: who calls whom, and how (HTTP or gRPC client, queue or topic, shared database, file, webhook, SDK of an outside service). Find it in the code that sends: HTTP clients and their base URLs, message publishers and subscribers, connection strings, configuration and deployment files.
|
|
30
|
+
- **The paths through it.** Where a request or event enters, which parts it passes in which order, and where it ends. A system usually has several (a user request, a background job, an incoming webhook); note each one.
|
|
31
|
+
|
|
32
|
+
If you can hand work to helpers that read code, give each project to one. Keep the list in your notes; the diagram is drawn from it.
|
|
33
|
+
|
|
34
|
+
Then judge the size. When the list has more parts or paths than one readable picture holds (about a dozen boxes), do not shrink it to a few vague boxes such as "Backend" and "Services". Propose either an overview that names every part plus one diagram per main path, or one diagram of the path the person cares about.
|
|
35
|
+
|
|
23
36
|
## Choosing the kind
|
|
24
37
|
|
|
25
|
-
Choose by what the reader has to understand, not by a word in the request: a "request flow" or a "user flow" is not a flowchart. `fastdraw guide list` says what every kind shows. The usual choices:
|
|
38
|
+
Choose by what the reader has to understand, not by a word in the request: a "request flow" or a "user flow" is not a flowchart, and "architecture diagram" is often said of any picture of a system. `fastdraw guide list` says what every kind shows. The usual choices:
|
|
26
39
|
|
|
27
40
|
| The reader has to see | Kind |
|
|
28
41
|
|---|---|
|
|
@@ -42,7 +55,13 @@ Choose by what the reader has to understand, not by a word in the request: a "re
|
|
|
42
55
|
- Draw a flowchart only when there are real yes/no questions. Steps in a row with no decision are a swimlane, or a process.
|
|
43
56
|
- If a three-column table would say the same thing, write the table instead.
|
|
44
57
|
|
|
45
|
-
**Agree the kind before drawing.**
|
|
58
|
+
**Agree the kind and the scope before drawing.** Skip this only when the request names exactly one kind and nothing in it pulls toward another ("a sequence diagram of the login"). A request that mixes words of two kinds ("request flow architecture diagram": the order of a request, or the parts and their links?) names neither; ask. In one short message, using what you learned about the system:
|
|
59
|
+
|
|
60
|
+
- the kind you would draw and the closest other kind, with a line on what each would show of *this* system;
|
|
61
|
+
- when the system has several paths, which one to draw (name them);
|
|
62
|
+
- when it is too big for one picture, the split you propose (an overview plus one per path).
|
|
63
|
+
|
|
64
|
+
Use your tool for asking a question if you have one, your pick first. If you cannot ask, draw your pick and say which other kind, path or split would also have worked.
|
|
46
65
|
|
|
47
66
|
## The file
|
|
48
67
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fastdraw",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"description": "Diagrams that an AI agent writes as text and a person edits on a canvas",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"diagram",
|
|
@@ -32,6 +32,7 @@
|
|
|
32
32
|
"guide",
|
|
33
33
|
"fonts",
|
|
34
34
|
"agents",
|
|
35
|
+
"plugins",
|
|
35
36
|
"README.md",
|
|
36
37
|
"LICENSE",
|
|
37
38
|
"licenses"
|
|
@@ -47,7 +48,8 @@
|
|
|
47
48
|
"test:e2e": "playwright test",
|
|
48
49
|
"build:cli": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:@resvg/resvg-js --banner:js=\"#!/usr/bin/env node\" --outfile=dist/cli.js",
|
|
49
50
|
"prepack": "npm run build:cli && npm run build:embed",
|
|
50
|
-
"build:embed": "vite build -c vite.embed.config.ts"
|
|
51
|
+
"build:embed": "vite build -c vite.embed.config.ts",
|
|
52
|
+
"version": "node tools/syncPluginVersion.ts && git add plugins/fastdraw/.claude-plugin/plugin.json"
|
|
51
53
|
},
|
|
52
54
|
"dependencies": {
|
|
53
55
|
"@resvg/resvg-js": "^2.6.2"
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "fastdraw",
|
|
3
|
+
"description": "Draw diagrams as small .fdraw text files that people can edit visually afterwards. The skill runs the fastdraw CLI through npx to check and render each diagram.",
|
|
4
|
+
"author": {
|
|
5
|
+
"name": "coccor"
|
|
6
|
+
},
|
|
7
|
+
"homepage": "https://fastdraw.dev",
|
|
8
|
+
"repository": "https://github.com/coccor/fastdraw",
|
|
9
|
+
"license": "MIT",
|
|
10
|
+
"keywords": [
|
|
11
|
+
"diagram",
|
|
12
|
+
"architecture",
|
|
13
|
+
"flowchart",
|
|
14
|
+
"sequence",
|
|
15
|
+
"fdraw"
|
|
16
|
+
],
|
|
17
|
+
"version": "0.2.2"
|
|
18
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fastdraw
|
|
3
|
+
description: Draw or change a diagram (architecture, request flow, sequence, flowchart, swimlane, data model, chart, or any boxes-and-arrows picture) as a FastDraw .fdraw file that people can later edit visually. Use when asked to draw, create, update or fix a diagram, or when a .fdraw or .look file is involved.
|
|
4
|
+
allowed-tools: Bash(npx -y fastdraw *) Bash(npx fastdraw *) Bash(fastdraw *)
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# FastDraw
|
|
8
|
+
|
|
9
|
+
FastDraw diagrams are small text files (`.fdraw`). You place every element yourself; a look file (`.look`) decides how styles are drawn. People edit the same file in a browser editor afterwards.
|
|
10
|
+
|
|
11
|
+
Run FastDraw's commands as `npx -y fastdraw <command>` (for example `npx -y fastdraw guide`), or as `fastdraw <command>` when it is on the PATH. Below and in the guide they are written `fastdraw <command>`.
|
|
12
|
+
|
|
13
|
+
1. Save a new diagram in `docs/diagrams/` (create the folder), unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
|
|
14
|
+
2. Run `fastdraw guide` and follow it. It is the single source for the language and the way of working, and it points to `fastdraw guide list` (what each kind of diagram shows), `fastdraw guide <kind>` and `fastdraw sizes`.
|
|
15
|
+
For a diagram of the code, learn the system before choosing anything: every project or service, how each talks to the others (HTTP clients, queues, shared stores, config), and the paths a request or event takes. With several projects, read all of them; if you can hand work to subagents (Explore agents in Claude Code), give each project to one. Do not shrink a big system into a few vague boxes: propose an overview plus one diagram per main path, or the one path the person cares about.
|
|
16
|
+
Choose the kind by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart; "architecture diagram" is said of any system picture). Unless the request names exactly one kind and nothing in it pulls toward another, ask before drawing with your tool for asking a question (AskUserQuestion in Claude Code), your pick first: the kind you would draw and the closest other kind, which path when there are several, and the split when the system is too big for one picture. A request like "request flow architecture diagram" names two and must be asked. If you cannot ask, draw your pick and say what else would have worked.
|
|
17
|
+
3. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
|
|
18
|
+
4. When the diagram is done, always ask the person what to do next, with your tool for asking a question; do not end your turn without asking. The choices: **Open in fastdraw.dev** (run `fastdraw open <file>` in the background, then read its output and give the person the link it prints, in case no browser window appeared; it saves their edits back to the file), **Preview as PNG** (open the rendered PNG in their image viewer) or **Nothing**. Do not open anything before they choose.
|
|
19
|
+
5. For a site with light and dark themes, `fastdraw render <file or folder> --dark` writes `x.png` and `x-dark.png` (the look's dark version, Night for the built-in look). Do not copy the file to swap its look line; `--look <name|file.look>` draws with another look. A folder means every `.fdraw` file under it, for `check` too.
|
|
20
|
+
6. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
|
|
21
|
+
7. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.
|
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: fastdraw
|
|
3
|
-
description: Draw or change a diagram (architecture, flowchart, sequence, or any boxes-and-arrows picture) as a FastDraw .fdraw file that people can later edit visually. Use when asked to create, update or fix a diagram in a repo that uses FastDraw, or when a .fdraw or .look file is involved.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# FastDraw
|
|
7
|
-
|
|
8
|
-
FastDraw diagrams are small text files (`.fdraw`). You place every element yourself; a look file (`.look`) decides how styles are drawn. People edit the same file in a browser editor afterwards.
|
|
9
|
-
|
|
10
|
-
1. Save a new diagram in `docs/diagrams/` (create the folder), unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
|
|
11
|
-
2. Run `fastdraw guide` and follow it. It is the single source for the language and the way of working, and it points to `fastdraw guide list` (what each kind of diagram shows), `fastdraw guide <kind>` and `fastdraw sizes`.
|
|
12
|
-
Choose the kind by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart). Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask with AskUserQuestion (your pick first) before drawing. If you cannot ask, draw your pick and say which other kind would also have worked.
|
|
13
|
-
3. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
|
|
14
|
-
4. When the diagram is done, always ask the person what to do next with AskUserQuestion; do not end your turn without asking. The choices: **Open in fastdraw.dev** (run `fastdraw open <file>` with `run_in_background`, then read its output and give the person the link it prints, in case no browser window appeared; it saves their edits back to the file), **Preview as PNG** (open the rendered PNG in their image viewer) or **Nothing**. Do not open anything before they choose.
|
|
15
|
-
5. For a site with light and dark themes, `fastdraw render <file or folder> --dark` writes `x.png` and `x-dark.png` (the look's dark version, Night for the built-in look). Do not copy the file to swap its look line; `--look <name|file.look>` draws with another look. A folder means every `.fdraw` file under it, for `check` too.
|
|
16
|
-
6. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
|
|
17
|
-
7. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.
|
|
18
|
-
|
|
19
|
-
If the `fastdraw` command is not on the PATH, run it as `npx fastdraw` (for example `npx fastdraw guide`).
|