fastdraw 0.2.1 → 0.3.0
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 +41 -17
- package/agents/AGENTS-snippet.md +3 -1
- package/agents/README.md +9 -5
- package/dist/cli.js +591 -588
- package/dist-embed/embed/draw-u9ucGBP1.js +41 -0
- package/dist-embed/embed.js +560 -2
- package/guide/guide.md +38 -12
- package/guide/look.md +99 -9
- package/package.json +7 -2
- package/plugins/fastdraw/.claude-plugin/plugin.json +18 -0
- package/plugins/fastdraw/skills/fastdraw/SKILL.md +22 -0
- package/agents/claude-skill/fastdraw/SKILL.md +0 -19
- package/dist-embed/embed/draw-CFzc4XD7.js +0 -1070
package/README.md
CHANGED
|
@@ -43,34 +43,52 @@ 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:
|
|
47
50
|
|
|
48
51
|
```
|
|
49
|
-
|
|
50
|
-
npx fastdraw check docs/example.fdraw # report problems, with line numbers
|
|
51
|
-
npx fastdraw render docs/example.fdraw # write example.png next to the file
|
|
52
|
-
npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
|
|
52
|
+
/plugin install fastdraw --marketplace coccor/fastdraw
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
|
|
56
|
-
|
|
55
|
+
On Claude Code older than 2.1.275, run `/plugin marketplace add coccor/fastdraw`, then
|
|
56
|
+
`/plugin install fastdraw@fastdraw`.
|
|
57
57
|
|
|
58
|
-
|
|
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.
|
|
59
66
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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.
|
|
63
70
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
agent to tell you. To update them, run this in the repository; it rewrites the skill and replaces only
|
|
67
|
-
FastDraw's own section of `AGENTS.md` or Copilot's instructions:
|
|
71
|
+
Then ask your agent for a diagram. It runs the command-line tool through `npx`, so there is nothing
|
|
72
|
+
else to install:
|
|
68
73
|
|
|
69
74
|
```
|
|
70
|
-
npx fastdraw
|
|
71
|
-
npx fastdraw
|
|
75
|
+
npx fastdraw check docs/example.fdraw # report problems, with line numbers
|
|
76
|
+
npx fastdraw render docs/example.fdraw # write example.png next to the file
|
|
77
|
+
npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
|
|
72
78
|
```
|
|
73
79
|
|
|
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
|
+
|
|
74
92
|
If fastdraw is installed on the PATH (`npm install -g fastdraw`), agents use that copy instead of `npx`.
|
|
75
93
|
`fastdraw guide` checks npm for a newer release at most once a day and says so when there is one; update
|
|
76
94
|
with `npm install -g fastdraw@latest`. Set `FASTDRAW_NO_UPDATE_CHECK=1` to turn the check off; it is off on CI.
|
|
@@ -108,6 +126,12 @@ Written by agents from the guides alone and drawn in the built-in look; sources
|
|
|
108
126
|
|
|
109
127
|
FastDraw is at version 0.x, and details of the language may still change.
|
|
110
128
|
|
|
129
|
+
## Rust
|
|
130
|
+
|
|
131
|
+
[`fastdraw-render`](crates/fastdraw-render) is the renderer as a Rust crate, for applications that draw
|
|
132
|
+
diagrams without Node. It draws the same SVG as the npm package of the same version, character for character;
|
|
133
|
+
CI checks that on Linux and Windows. See its [README](crates/fastdraw-render/README.md).
|
|
134
|
+
|
|
111
135
|
## Contributing
|
|
112
136
|
|
|
113
137
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source, running the tests and the
|
package/agents/AGENTS-snippet.md
CHANGED
|
@@ -6,10 +6,12 @@ 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.
|
|
13
14
|
- On a docs site (a web page, not a GitHub README), show a diagram with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js and keep the rendered PNG inside it as the fallback image; see "Embedding a diagram" in FastDraw's README.
|
|
15
|
+
- When a diagram needs vendor icons (Azure, AWS, Google Cloud, Kubernetes, product logos) or a font that does not ship with FastDraw, add them to the look by their https:// address from the recommended sources in `fastdraw guide look`, with a fixed version in the address, rather than downloading files into the repo.
|
|
14
16
|
- When changing an existing diagram, leave the position, size and styling of existing elements alone unless asked.
|
|
15
17
|
- If `fastdraw` is not on the PATH, run it as `npx fastdraw`.
|
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,
|