create-linkdesk-plugin 0.1.3 → 0.1.4
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 +62 -55
- package/package.json +1 -1
- package/template/AGENTS.md +52 -0
- package/template/README.md +56 -58
package/README.md
CHANGED
|
@@ -1,55 +1,62 @@
|
|
|
1
|
-
# create-linkdesk-plugin
|
|
2
|
-
|
|
3
|
-
LinkDesk
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm create linkdesk-plugin my-cool-plugin
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
npm create linkdesk-plugin
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
my-cool-plugin/
|
|
21
|
-
├── plugin.json #
|
|
22
|
-
├── package.json # scripts: dev / dev:real / build / publish / validate / lint
|
|
23
|
-
├── tsconfig.json # jsx: react-jsx + window.linkdesk.*
|
|
24
|
-
├── .
|
|
25
|
-
├──
|
|
26
|
-
├──
|
|
27
|
-
├── .
|
|
28
|
-
├──
|
|
29
|
-
|
|
30
|
-
├──
|
|
31
|
-
|
|
32
|
-
│ └──
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
npm
|
|
47
|
-
|
|
48
|
-
npm run
|
|
49
|
-
npm run
|
|
50
|
-
npm run
|
|
51
|
-
npm run
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
1
|
+
# create-linkdesk-plugin
|
|
2
|
+
|
|
3
|
+
The LinkDesk plugin scaffold — one command generates your first plugin project (the `yo code` equivalent).
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm create linkdesk-plugin my-cool-plugin
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Run it without a name and it asks interactively:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm create linkdesk-plugin
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## What you get
|
|
16
|
+
|
|
17
|
+
The generated project has **the same shape as an official plugin** — README / CHANGELOG / resources / i18n, nothing missing:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
my-cool-plugin/
|
|
21
|
+
├── plugin.json # plugin manifest (JSONC: comments + trailing commas allowed, sectioned example fields, VS Code $schema validation)
|
|
22
|
+
├── package.json # scripts: dev / dev:real / build / publish / validate / lint / verify / test
|
|
23
|
+
├── tsconfig.json # jsx: react-jsx + window.linkdesk.* types (@linkdesk/plugin-sdk)
|
|
24
|
+
├── AGENTS.md # what this project is + the iron rules + where the docs are (for your AI assistant)
|
|
25
|
+
├── .gitignore # node_modules / dist / *.linkdesk-plugin
|
|
26
|
+
├── README.md # description — data source for the marketplace "Details" tab + the directory contract table
|
|
27
|
+
├── CHANGELOG.md # release notes — data source for the marketplace "Changelog" tab
|
|
28
|
+
├── .github/workflows/ci.yml # CI that runs `npm run verify` on every push
|
|
29
|
+
├── scripts/ci-verify.mjs # the strict tier CI runs (lint + tests + declaration self-checks)
|
|
30
|
+
├── .vscode/settings.json # plugin.json is treated as jsonc (comments do not light up red)
|
|
31
|
+
├── resources/
|
|
32
|
+
│ └── icon.svg # placeholder icon — replace it with your own
|
|
33
|
+
├── src/
|
|
34
|
+
│ ├── index.tsx # view component, default export — the shell renders it with { isActive, tabId?, sourceId? }
|
|
35
|
+
│ └── index.css # styling example — colors/font sizes via var(--xxx), spacing on a 4px grid
|
|
36
|
+
└── i18n/
|
|
37
|
+
└── en.json # English translations (key = the source string)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
> **No empty folders are pre-created** (git does not track them anyway) — "where does this go" is spelled out in the generated `README.md`'s directory contract table. Prose is clearer than a folder-shaped hint.
|
|
41
|
+
|
|
42
|
+
## Commands
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
cd my-cool-plugin
|
|
46
|
+
npm install
|
|
47
|
+
|
|
48
|
+
npm run dev # browser preview with hot reload (changes apply instantly)
|
|
49
|
+
npm run dev:real # real-device loop — writes into {userData}/plugins/<id> + CDP reload (for plugins needing real IPC / serial / LSP)
|
|
50
|
+
npm run validate # validate plugin.json / theme recipes
|
|
51
|
+
npm run lint # SDK rule tier (hard-coded colors / font sizes / spacing grid / eslint rules)
|
|
52
|
+
npm run test # unit tests (vitest)
|
|
53
|
+
npm run verify # full pre-delivery tier — what CI runs
|
|
54
|
+
npm run build # produce <pluginId>.linkdesk-plugin — installable in LinkDesk / publishable
|
|
55
|
+
npm run publish # one-shot publish (creates the GitHub Release + uploads + updates the catalog)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
> The full author documentation (dev preview / build / the whole publishing chain) lives in the LinkDesk repo:
|
|
59
|
+
> the **English tree** at <https://github.com/Encaron/linkdesk/tree/electron/docs/03-plugin-authoring> (start at `00-readme.md`),
|
|
60
|
+
> with the Chinese original at `docs/03-插件制造/`.
|
|
61
|
+
|
|
62
|
+
> 🔴 The generated `AGENTS.md` also carries this pointer, plus the iron rules inline — so the AI working in your project knows where to look without being told.
|
package/package.json
CHANGED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# {{displayName}} — a LinkDesk plugin
|
|
2
|
+
|
|
3
|
+
> **This file is for the AI working in this repository** (Claude Code / Codex / Cursor / …). Humans will prefer `README.md`.
|
|
4
|
+
> Generated by `create-linkdesk-plugin`. Plugin identity = the top-level `pluginId` in `plugin.json` (currently: `{{pluginName}}`).
|
|
5
|
+
|
|
6
|
+
## 1. What this is
|
|
7
|
+
|
|
8
|
+
A **LinkDesk plugin** project. LinkDesk is a "everything is a plugin" desktop container — **the core is only tabs + split view + a data pipeline + registries, and the core does not know what your plugin does.**
|
|
9
|
+
|
|
10
|
+
Your code runs in a renderer process: use any JS library and any Web API (Canvas / WebGL / wasm / WebRTC / Web Audio / fetch are all open — **there is no API allowlist**). Only **system-level capabilities** (serial ports, files, configuration, dialogs, notifications) must go through `window.linkdesk.*`; do not reach for raw Node.js APIs.
|
|
11
|
+
|
|
12
|
+
## 2. Iron rules (breaking these breaks the plugin — or the shell)
|
|
13
|
+
|
|
14
|
+
1. **Colors always via `var(--xxx)`** — never hard-code hex, or your UI will not follow the user's theme.
|
|
15
|
+
2. **UI text always via `t()`** (key = the source string; English translations go in `i18n/en.json`) — never hard-code display strings.
|
|
16
|
+
3. **System capabilities only via `window.linkdesk.*`** — never `import` shell internals (`@src/core/...`); the SDK lint fails this at error level.
|
|
17
|
+
4. **Plugin identity comes only from declarations in `plugin.json`** — never let anyone infer what your plugin is from a directory name or file location.
|
|
18
|
+
5. **Context menus are declarative** (`contributes.menus` + `<ContextMenu>`); **dialogs portal into `document.body`**; **persistence goes through `window.linkdesk.configuration`** (never `localStorage`).
|
|
19
|
+
6. **keep-alive architecture: every tab stays mounted** — do not blank content with `isActive`; it is only for gating "run this only while focused" side effects.
|
|
20
|
+
|
|
21
|
+
## 3. Where to find the rules
|
|
22
|
+
|
|
23
|
+
- **Online (full author documentation, organized by "what I want to do")**: <https://github.com/Encaron/linkdesk/tree/electron/docs/03-plugin-authoring> — start at its `00-readme.md`.
|
|
24
|
+
- **Offline (always available, no network)**: `node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json` — the **field-level authority**; `theme.schema.json` next to it does the same for themes.
|
|
25
|
+
- **Editor completion**: `plugin.json`'s `$schema` points at it, so you get completion and diagnostics as you type.
|
|
26
|
+
- **Self-check after editing**: `npm run validate` (manifest/format validity) + `npm run lint` (SDK rule tier).
|
|
27
|
+
- 中文版作者文档（Chinese docs, maintainer-facing original）：<https://github.com/Encaron/linkdesk/tree/electron/docs/03-插件制造>
|
|
28
|
+
|
|
29
|
+
## 4. What to do next (this project's commands, verbatim)
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install # dependencies (first run)
|
|
33
|
+
npm run dev # ① see it in the browser dev host — HMR on save
|
|
34
|
+
npm run dev:real # ② debug inside an installed LinkDesk (real IPC / serial / filesystem)
|
|
35
|
+
npm run validate # ③ validate plugin.json / theme recipes
|
|
36
|
+
npm run lint # ④ SDK rule tier (the mechanical backstop for the iron rules)
|
|
37
|
+
npm run test # ⑤ unit tests (vitest)
|
|
38
|
+
npm run verify # ⑥ full pre-delivery tier — this is what CI runs
|
|
39
|
+
npm run build # ⑦ produce <pluginId>.linkdesk-plugin (single-file zip)
|
|
40
|
+
npm run publish # ⑧ publish to your own GitHub repo (first step of listing)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**🔴 Listing is two steps**: `publish` only completes **step one** (visible to people who manually added your repo as a marketplace source). **Step two is submitting to the official catalog** — only then can every user with default settings find it.
|
|
44
|
+
|
|
45
|
+
## 5. Two toolchain boundaries
|
|
46
|
+
|
|
47
|
+
- **This project is its own git repo** (the scaffold ran `git init -b main` plus one initial commit). `publish` uses `origin` to create the Release ⇒ pushing to GitHub is just two commands: `git remote add origin <your repo>` + `git push -u origin main`.
|
|
48
|
+
- **Keep the version numbers in step**: `plugin.json`'s `version` and `package.json`'s `version` **must match**; and every bump needs a matching `## v<new version>（YYYY-MM-DD）` section in `CHANGELOG.md`, or the plugin's detail page will show "no changelog provided for this version".
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
> Author: {{author}} ｜ Generated: {{date}}
|
package/template/README.md
CHANGED
|
@@ -1,58 +1,56 @@
|
|
|
1
|
-
# {{displayName}}
|
|
2
|
-
|
|
3
|
-
>
|
|
4
|
-
|
|
5
|
-
<!--
|
|
6
|
-
 -->
|
|
7
|
+
|
|
8
|
+
## How to use
|
|
9
|
+
|
|
10
|
+
How to open it in LinkDesk, where to click, what you should see. Spell out the path a first-time user walks.
|
|
11
|
+
|
|
12
|
+
## Directory layout — where things go
|
|
13
|
+
|
|
14
|
+
You do not need to pre-create empty folders (git does not track them). **Create them when you need them; the table below says where.**
|
|
15
|
+
|
|
16
|
+
| Path | What goes here | When it exists |
|
|
17
|
+
|:--|:--|:--|
|
|
18
|
+
| `plugin.json` | The plugin manifest | **Always** |
|
|
19
|
+
| `README.md` | Description — the data source for the marketplace **Details** tab | Strongly recommended |
|
|
20
|
+
| `CHANGELOG.md` | Release notes — the data source for the marketplace **Changelog** tab | Strongly recommended |
|
|
21
|
+
| `resources/` | Assets: `icon.svg` / `cover.svg` / images referenced from the README | Once you have images |
|
|
22
|
+
| `i18n/` | `en.json` (key = the source string; **do not create `zh.json`**) | Once you have UI text |
|
|
23
|
+
| `themes/` · `languages/` · `snippets/` | Payloads for data-only plugins | Data-only plugins |
|
|
24
|
+
| `src/index.tsx` | Entry (the `entry` in `plugin.json`) | Always for view plugins |
|
|
25
|
+
| `src/views/` | Sidebar / panel view components (the files `contributes.views` points at) | Once you have views |
|
|
26
|
+
| `src/components/` | Components reused inside this plugin | When needed |
|
|
27
|
+
| `src/services/` | Domain logic / IPC wrappers / data layer | When needed |
|
|
28
|
+
| `src/styles/` | **Multiple** CSS files — keep them together here (a single file next to the entry is fine too) | When needed |
|
|
29
|
+
| `src/__tests__/` | Unit tests (run `npm i -D vitest` yourself if you want them — the scaffold does not preinstall test tooling) | When needed |
|
|
30
|
+
|
|
31
|
+
> 🔴 **Shared things do not belong here** — components/hooks reused across plugins come from `@linkdesk/ui` (the public package the shell provides). **Do not write a second copy inside your plugin.** Only logic that belongs to this plugin stays local.
|
|
32
|
+
> 🔴 **Assets always live in `resources/` — no loose images in the plugin root.** What gets into the install package is what is **referenced by the README** or **declared by `icon` / `marketIcon`**; the directory name itself has no magic.
|
|
33
|
+
|
|
34
|
+
## Three rules for this plugin
|
|
35
|
+
|
|
36
|
+
1. **Colors come from theme variables** — always `var(--xxx)` in CSS, **never a hard-coded hex**. Reason: LinkDesk supports full theme replacement, so a fixed color means your plugin does not follow the theme.
|
|
37
|
+
2. **UI text goes through `t()`** — `t("source string")`, with English in `i18n/en.json` and **no `zh.json`** (the source string is the key and is its own fallback). **Only add keys you actually read with `t()`** — an unread key is a dead key. Code identifiers (`src/index.tsx` and friends) are not copy — do not wrap them in `t()`.
|
|
38
|
+
3. **Plugin identity comes only from declared fields in `plugin.json`** — declare whatever capability you need (`contributes` / `tabBehavior` / `icon` …). **Never make other people guess what your plugin is from a directory name or file location.**
|
|
39
|
+
|
|
40
|
+
## Publishing
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm run publish # create the GitHub Release + upload the .linkdesk-plugin + update the catalog
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The first publish needs a GitHub token (the command walks you through it once and stores it locally). To see what it would do without doing it: `npm run publish -- --dry-run`.
|
|
47
|
+
|
|
48
|
+
Publishing also requires this project to be **pushed to GitHub** (`publish` uses your project's `origin` to create the Release):
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
git remote add origin git@github.com:<you>/<repo>.git
|
|
52
|
+
git push -u origin main
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
> The scaffold already created this repository for you (`main` branch + one initial commit), so this step is only about wiring the remote.
|
|
56
|
+
> If you generated with `--no-git`, run `git init -b main` and commit first.
|