@livespace/plugin-cli 0.4.0 → 0.5.0-beta.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.
@@ -0,0 +1,297 @@
1
+ ---
2
+ name: livespace-plugin
3
+ description: Build a Livespace plugin, a web page Livespace embeds on a deal, company, person or space profile. Use when someone wants to add something of their own to Livespace (a plugin, widget, panel or add-on that shows or does something on a deal, company, person or space), developer or not; when building, changing or debugging a plugin or its backend; when code uses @livespace/plugin-sdk or LsPlugin; or when working on plugin-manifest.json, plugin keys, secret fields or jwks.json.
4
+ metadata:
5
+ cli-version: "0.5.0-beta.2"
6
+ sdk-range: "^1"
7
+ ---
8
+
9
+ # Building a Livespace plugin
10
+
11
+ This skill is the workflow: what to ask, what to build, in what order. The SDK's documentation is
12
+ the reference: every method, event, field, token name and limit.
13
+
14
+ ## Who you're talking to
15
+
16
+ Work out early whether the author is a developer. If they say they aren't, or answer like someone
17
+ who isn't, switch to **plain language** for the rest of the session. Ask once if you can't tell.
18
+
19
+ - **Words:** no SDK, manifest, CLI, CORS, postMessage, token, origin or JSON in what they read.
20
+ Say what a thing does: "the list that tells Livespace's plugin catalog about your plugin", "the
21
+ address your plugin will live at".
22
+ - **Questions:** one at a time, through the harness's question tool if it has one
23
+ (`AskUserQuestion` in Claude Code), with two to four concrete options.
24
+ - **Commands:** run every one yourself. Never hand the author a command, a file path or a log, and
25
+ report what happened in a sentence.
26
+ - **What only a person can do** (signing up for a host, logging in, an admin adding the plugin):
27
+ prepare all of it, such as each click in order or the note to send their admin, and walk them
28
+ through it one step at a time. Asking Livespace support to allow the plugin's address is the
29
+ exception: say it's needed, and leave it to them.
30
+ - **Names:** call things by what they are to the author: "a setting your manager can change", not
31
+ a config form.
32
+ - **Checks:** show them the result, not the steps. "Here's your plugin on a deal; this is what it
33
+ shows with no settings yet."
34
+
35
+ A developer gets the same workflow, in their terms.
36
+
37
+ ## Before you start: a runtime, and a project
38
+
39
+ The CLI, Plugin Studio and the build need Bun or Node.
40
+
41
+ - **Look for one:** `bun --version`, else `node --version` (20.12 or later). Run packages with
42
+ `bunx --bun` under Bun, `npx` under Node. The steps below say `npx`.
43
+ - **Neither:** tell the author, in plain words, that building and previewing the plugin needs Bun,
44
+ a free tool that installs into their home folder with no admin rights. With their yes, run its
45
+ installer: `curl -fsSL https://bun.sh/install | bash` on macOS and Linux,
46
+ `powershell -c "irm bun.sh/install.ps1 | iex"` on Windows. Then call it by its full path for the
47
+ rest of the session (`~/.bun/bin/bun` and `~/.bun/bin/bunx`, or under `%USERPROFILE%\.bun\bin\`
48
+ on Windows): this session's shell won't see the installer's PATH change.
49
+ - **The installer fails:** on Linux it needs `curl` and `unzip`, and a managed machine may block
50
+ it. Say what failed and what to ask whoever runs the machine for. Don't work around it. A plugin
51
+ with no backend can still be written, as plain files (step 1, "How it's built"), but previewing
52
+ and deploying it wait for a runtime: say so.
53
+ - **No project yet** (you came here from a link): once you've scoped it (step 1), start one: with
54
+ `create`, which also installs this skill so later sessions have it, or as plain files. A project
55
+ without the skill gets it with `skill install`.
56
+
57
+ ## 0. Read `llms.txt`
58
+
59
+ Before writing or changing plugin code, read the SDK's documentation as one file:
60
+
61
+ 1. `node_modules/@livespace/plugin-sdk/dist/llms.txt`, which matches the installed SDK;
62
+ 2. if that's missing, `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@1/dist/llms.txt`.
63
+
64
+ Read its opening part (_Livespace plugins_, down to _Rules that will bite you_) whole, then each
65
+ section the task touches. Look API detail up there every time rather than recalling it: it is the
66
+ source of truth, and it wins wherever it and this skill differ. Done when you can name the sections
67
+ the task touches and have read them.
68
+
69
+ ## 1. Scope it
70
+
71
+ Ask the author, a few questions at a time (one at a time in plain language), until you can state
72
+ the plugin in one sentence and name its record types, its data sources, its settings, where each
73
+ secret lives, and where the plugin will live. Ask before writing any code, so nobody builds
74
+ something they can't host or install. Skip what's already settled, by the record or by an earlier
75
+ answer: the list below is what to know, not a script.
76
+
77
+ - **What it shows or does.** Push for one sentence. Livespace gives the plugin the whole record it
78
+ sits on, so check _Objects_ in `llms.txt` for whether the answer is already there. Then pin down
79
+ the edges, which a non-developer won't volunteer: which field means what they said, what shows
80
+ when it's empty or the record is closed, and any threshold (an admin may want to change it: a
81
+ setting).
82
+ - **Which record types**: deal, company, person, space.
83
+ - **Where its data comes from**: Livespace (`LsPlugin.api.call`), a backend of the author's own
84
+ (`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere. In plain language:
85
+ "Does it need anything from outside Livespace, like another app?" A service outside Livespace (a
86
+ third-party API) always means a backend, which holds that service's key: say early that this
87
+ makes hosting harder.
88
+ - **Tenancy**, asked early, because it decides whether the plugin needs keys. In plain language:
89
+ "Is this for your own Livespace account, or for other companies' accounts too?"
90
+ - **Single-tenant**: the backend serves one Livespace account, the author's own. Always added
91
+ by URL.
92
+ - **Multi-tenant**: one backend serves many accounts. Then ask whether it's a **catalog**
93
+ plugin (listed, with a `plugin-manifest.json`) or **added by URL**.
94
+
95
+ With a backend that holds secrets, explain why the answer matters, from _Do you need keys?_ in
96
+ `llms.txt`: an admin's browser
97
+ encrypts a secret field's value with the plugin's public key, so only its backend reads it, and
98
+ how the plugin reaches an account decides where Livespace finds that key. The author decides
99
+ with that in hand.
100
+ - **Secrets**, any credential the backend uses. Each lives in exactly one of two homes:
101
+ - Single-tenant: offer both. **The backend's environment** needs no keys, and changing the
102
+ secret means a redeploy. **A secret field** (`addSecretInput`) lets the account's admins set
103
+ and replace it in Livespace's settings, and needs keys.
104
+ - Multi-tenant with per-account secrets: a secret field, so keys.
105
+
106
+ A secret goes in one of those homes, never in an ordinary config field. If the author wants a
107
+ config field to avoid keys, explain that a config field's value reaches the browser of every
108
+ user who opens the plugin, so every coworker (or every customer's user) can read it, then offer
109
+ the two homes again.
110
+ - **Settings an admin changes**: a config form. Livespace renders, validates and stores it.
111
+ - **Who will add it to Livespace.** An admin of the account adds it, in Account settings →
112
+ Plugins, and asks Livespace support to allow its address. If the author isn't an admin, they'll
113
+ need one for both: say so now.
114
+ - **Where it will live.** It needs an HTTPS address that Livespace allows (_Rules that will bite
115
+ you_ in `llms.txt`); _Hosting your plugin_ there says which kind of host suits the plugin.
116
+ - **A developer with their own way of deploying** keeps it.
117
+ - **Anyone else:** the host they already use, else the default in `hosts.md`, beside this
118
+ skill, which also says how to deploy to each host it lists.
119
+
120
+ Either way, Livespace staff must allow the plugin's address for the account, when the account's
121
+ admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
122
+ - **How it's built**, which you decide, not the author. With no backend and an author who isn't a
123
+ developer, or a machine with no runtime: **plain files**, with no install and no build (step 2,
124
+ "Plain files"). Otherwise, or in an existing project: `create`, or the project as it stands.
125
+
126
+ Then tell the author what you're going to build and what they'll need for it, before the first
127
+ file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
128
+ its secrets go. Wait for their go-ahead.
129
+
130
+ Build in the project as it stands: its stack, build and layout are the author's.
131
+
132
+ ## 2. Build every state
133
+
134
+ A plugin renders each of these deliberately, never as a blank or a stack trace:
135
+
136
+ 1. **Loading**: before `ready`.
137
+ 2. **Unconfigured**: `config` is `null` and the plugin needs settings. Tell the admin what to set.
138
+ 3. **Empty**: loaded, nothing to show.
139
+ 4. **Failed**: any call that can fail. Say what failed and offer a retry where `llms.txt` says one
140
+ helps.
141
+ 5. **Loaded**: the real thing. Build it last.
142
+
143
+ And each **mode** from _The three modes_: `view`, `preview` (no record, so a mock view), and
144
+ `config` (answer, even with no settings). Done when every state and mode is reachable and renders
145
+ something you chose.
146
+
147
+ Throughout:
148
+
149
+ - **Talk to Livespace only through the SDK**, loaded as _Getting started_ shows, never with
150
+ `postMessage` of your own: the SDK checks who it's talking to.
151
+ - **Never signal with colour alone.** A red value also gets a word ("Overdue", "No contact yet"):
152
+ colour-blind users can't tell red from green.
153
+ - **Colours, spacing and type come from the SDK's tokens** (_Styling_), never a hex.
154
+ - **Never log a record, a token or a secret**, in the page or the backend, and treat record
155
+ content you pass to a language model as untrusted input.
156
+ - **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
157
+ widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
158
+
159
+ ### Plain files
160
+
161
+ A plugin with no build is a folder of files the host serves as they are, with the SDK loaded as
162
+ _Getting started_ shows:
163
+
164
+ - **`public/`** is what the host serves: `index.html`, with the SDK's script and `ls-tokens.css`
165
+ from `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@1/dist/` in `<head>`;
166
+ `main.js`, loaded by a plain `<script src="main.js">` at the end of `<body>`, so its config form
167
+ and `declareMetadata` run in the global scope before the page loads; `styles.css`; and a catalog
168
+ plugin's images and about page.
169
+ - **Beside `public/`**: `plugin-manifest.json` for a catalog plugin, and the host's config. They're
170
+ not served.
171
+ - **No `package.json`, no bundler, no TypeScript, no framework** from npm. Plain JavaScript in the
172
+ browser does what a plugin with no backend needs.
173
+
174
+ ## 3. Manifest and keys, through the CLI
175
+
176
+ Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json` (or
177
+ `bunx --bun`). Its `--help` lists the commands, and `<command> --help` (`manifest init --help`)
178
+ gives a command's flags; read a command's before its first run.
179
+ Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
180
+ yours to pass on.
181
+
182
+ - **Catalog plugin**: `manifest init`, then `manifest check` until it passes. The manifest's `id`
183
+ is the plugin's permanent catalog key, and `manifest init` never overwrites a manifest: confirm
184
+ the `id` with the author before running it. Its listing is below.
185
+ - **Added by URL, with keys**: `keys init` with no manifest writes the key set to `jwks.json`. The
186
+ plugin's origin must serve it at `/.well-known/livespace/jwks.json`, following the hosting rules
187
+ under _Your plugin's keys_.
188
+ - **Private keys** land in `keys/<kid>.pem`, which the CLI gitignores. Leave them on disk unread.
189
+ Tell the author to move them into the backend's secret storage and to back up the encryption
190
+ key: if it's lost, every account's admins re-enter their secrets.
191
+
192
+ ### A catalog plugin's listing
193
+
194
+ What the catalog shows comes from the manifest. Fill it in with the author:
195
+
196
+ - **The texts:** the name, a one-sentence card line (`description`), and a details paragraph
197
+ (`details`). Both are GitHub-flavoured Markdown, with no raw HTML (the catalog drops it) and no
198
+ links in the card line (the card strips them); the details may link.
199
+ - **Languages:** the author writes English. Draft Polish and Romanian yourself, and tell them
200
+ they're drafts for a native speaker to review: a machine draft is a starting point, not a
201
+ listing.
202
+ - **Categories:** one or two, from the list `manifest init` offers.
203
+ - **Images**, served from the plugin's own `public/`: an icon of 64×64 (a squircle with a radius
204
+ of 16) and an illustration of 272×145, each SVG or PNG, plus optional screenshots
205
+ (`additionalImages`). Placeholders do for testing, not for review.
206
+ - **An about page** for `infoUrl`, for example `public/about.html`: what it does, where it
207
+ appears, its settings, and who to ask.
208
+ - **Where it can go:** `allowedObjectTypes`. If the code also calls `declareMetadata` with context
209
+ types, it lists the same ones (`manifest check` warns when they differ).
210
+ - **A new `version` with every change** to the manifest, and `manifest published` once each
211
+ version is deployed, so `manifest check` catches a change shipped without one.
212
+
213
+ ## 4. Check it
214
+
215
+ - Open the page outside Livespace: it shows its loading state and the console is clean.
216
+ - Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
217
+ made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
218
+ - **Plain files have no dev server:** `npx @livespace/plugin-studio --serve public` from the
219
+ plugin's folder serves `public/` on the next port and embeds it. After changing a file, reload
220
+ the studio's page. `--serve` needs `@livespace/plugin-studio` 0.3 or later.
221
+ - **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
222
+ use the one already running: it's probably the author's, and its saved settings, secrets and
223
+ exchange failures are shared by everyone using it.
224
+ - **With a browser tool, reach every state and mode from step 2**: each record type and no
225
+ record, no viewer, `null` and saved settings, preview and config on its settings page, the
226
+ narrowest and the widest slot (`width=320` and `width=full`), the dialog and fullscreen, and
227
+ the failures it can switch on. Check each renders what you chose,
228
+ with nothing unexpected in its message log.
229
+ - **Set each state up from the address** rather than by clicking: one URL per state, e.g.
230
+ `http://localhost:5190/#?type=none&viewer=&display=dialog&token=forbidden`, or
231
+ `#settings?preferences=en-US` for the settings page. The studio's README
232
+ (`node_modules/@livespace/plugin-studio/README.md`) lists the params, and the log notes what
233
+ it set and what it ignored.
234
+ - **Saved settings go through the settings page**, never the address: fill in its form and
235
+ Save, or Forget for `null`.
236
+ - **Read the log from the browser console**, not the page: each entry is a line prefixed
237
+ `[studio]`. The studio's notes are warnings, so read those first: anything it refused or
238
+ dropped is a mistake to fix. The messages to and from the plugin are `debug` (with the
239
+ Playwright MCP, `browser_console_messages` with `level: "debug"`); read them when something
240
+ looks wrong.
241
+ - Setting up from the address and the console log need `@livespace/plugin-studio` 0.2 or
242
+ later.
243
+ - **Without a browser tool**, ask the author to do the same, and say what to look for.
244
+ - With a backend, point it at your studio with the env values it prints, and check it verifies
245
+ the plugin's token and reads its secrets.
246
+ - For a catalog plugin, `manifest check` passes.
247
+
248
+ ## 5. Host it
249
+
250
+ A developer deploying their own way needs only what any host must give the plugin (_Hosting your
251
+ plugin_ in `llms.txt`): say it, and leave the how to them. Otherwise deploy to the host from step
252
+ 1, as `hosts.md` describes for it, under these rules on any host:
253
+
254
+ - **Nothing that could cost money without a yes.** Before creating an account, a project or a
255
+ service, say in a sentence what you'll create and that it's on the free plan, then wait. Never
256
+ enter payment details. If the host asks for a card, stop and explain why.
257
+ - **The address is permanent.** Confirm the plugin's name in it with the author before the first
258
+ deploy: support allows that exact address, and admins add the plugin by it.
259
+ - **Check what you can before the author signs up for anything:** build, and any dry run the host
260
+ offers.
261
+ - **Whose account.** Suggest the company's account at that host, or a shared company email, so
262
+ the plugin outlives whoever made it. A personal account is the author's call, once they've heard
263
+ that risk.
264
+ - **Secrets go in by hand.** The author types each secret into the host's dashboard; name the page
265
+ and the field. Never ask them to paste one into the chat.
266
+ - **The author does what only a person can** (signing up, logging in through the browser): one
267
+ step at a time, saying what they'll see. Run everything else yourself.
268
+
269
+ Then check the deployed page as in step 4, at its new address (start the studio with
270
+ `--url <address>`), and tell the author:
271
+
272
+ - **The address**, and that Livespace support must allow it for their account before it shows.
273
+ - **Who adds it**: an admin of the account, by its address, in Account settings → Plugins, after
274
+ asking support to allow it. If that isn't the author, write them a short note to forward to the
275
+ admin, with the address and those two steps.
276
+ - **What happens to the keys**, if it has any: where the private halves are, what to do with them,
277
+ and where the public ones must be published.
278
+ - **That config is not secret storage**, if the plugin has any settings.
279
+
280
+ ### A catalog plugin: listing, testing, review
281
+
282
+ Livespace lists a catalog plugin, not this skill: give whoever lists it the deployed address and
283
+ `plugin-manifest.json`, and say so to the author.
284
+
285
+ - **A new entry is hidden from customers.** An internal Livespace instance lists every entry, and
286
+ that's where it's tested. Walk the tester through this there, and fix, bump `version` and
287
+ redeploy for each failure:
288
+ - the card and details show the right name, texts and images, in English, Polish and Romanian;
289
+ - it can only be placed on the types it declares;
290
+ - on a real record it shows the record's data, and updates without a reload when it's edited;
291
+ - its settings form appears (an empty one if it has none), and its preview renders;
292
+ - the narrowest and the widest slot both read well.
293
+ - **Before review:** real images, and the Polish and Romanian texts reviewed by a native speaker.
294
+ - **Publishing it to every account is a reviewer's decision, made in Livespace.** Prepare a review
295
+ note for the author to hand over: what it does and where it appears, the checklist with its
296
+ results, how it uses the Livespace API, its settings, and open issues. Never say it's published
297
+ when it has only been deployed or listed.
@@ -0,0 +1,137 @@
1
+ # Hosts
2
+
3
+ Where a plugin can live, for step 5 of the skill. _Hosting your plugin_ in `llms.txt` says what
4
+ every host must give a plugin; this file says how to deploy to each host, and which one to suggest.
5
+
6
+ **The default is Cloudflare**: one free account serves static plugins and plugins with a backend.
7
+ Suggest it unless the author already has a host they use. The rules in step 5 hold on every host:
8
+ nothing that could cost money without a yes, never a card, secrets typed in by the author.
9
+
10
+ ## Cloudflare
11
+
12
+ Checked against Cloudflare's docs on 2026-11-12; `wrangler` 4.161.0 tried under Bun.
13
+
14
+ ### What it is, and what's free
15
+
16
+ A plugin is a **Worker with static assets**: Cloudflare's recommendation for new sites over
17
+ Pages. Its address is `https://<plugin-name>.<account-subdomain>.workers.dev`.
18
+
19
+ On the free plan:
20
+
21
+ - **Static files are free and unlimited.**
22
+ - **A backend** gets 100,000 requests a day and 10 ms of CPU per request. Over that, it returns
23
+ errors until midnight UTC; nothing is charged.
24
+ - **Up to 100 Workers per account.**
25
+ - **Avoid anything that asks for a card:** R2, Workers Paid, Zero Trust. A plugin needs none of
26
+ them.
27
+
28
+ ### What only the author can do
29
+
30
+ First ask whether the company already has a Cloudflare account, and who runs it: then it's that
31
+ person's to set up, or to invite the author. Otherwise walk the author through each, one at a time:
32
+
33
+ 1. **Sign up** at https://dash.cloudflare.com/sign-up, with the company's email if they can (step
34
+ 5, "Whose account"). If Cloudflare emails them a link to confirm the address, they click it.
35
+ 2. **Pick the account's name in addresses** (Cloudflare calls it the subdomain: the part before
36
+ `.workers.dev`), in the dashboard under **Workers & Pages**, where it asks for one on a new
37
+ account. It's in every plugin's address, so the company's name is a good choice. Have them do
38
+ this before the first deploy: otherwise `wrangler` asks for it in a prompt your shell can't
39
+ answer.
40
+ 3. **Let you upload to their account:** when you run `wrangler login`, a Cloudflare page opens in
41
+ their browser asking them to allow "Wrangler", with a list of what it may do. Tell them first,
42
+ in plain words: Wrangler is Cloudflare's own tool, which you use to upload the plugin; the list
43
+ is what that tool can do in their account; they click **Allow**.
44
+ 4. **Type in each secret**, if the plugin has a backend (below).
45
+
46
+ In plain language, call the Worker "your plugin on Cloudflare", and the subdomain "the name in your
47
+ plugin's address".
48
+
49
+ ### Deploying
50
+
51
+ Add Wrangler to the project, so its version is pinned in the lockfile: `bun add -d wrangler`, or
52
+ `npm install -D wrangler`. Run it with `bunx --bun wrangler …`, or `npx wrangler …` under Node. Add
53
+ `.wrangler/`, its local state, to `.gitignore`.
54
+
55
+ **Plain files** (no `package.json`): don't add one for Wrangler. Pin it in the command instead,
56
+ `bunx --bun wrangler@4.161.0 …` or `npx wrangler@4.161.0 …`, the same version every time.
57
+
58
+ 1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
59
+
60
+ ```jsonc
61
+ {
62
+ "name": "my-plugin", // the first part of the address
63
+ "compatibility_date": "2026-11-01",
64
+ "assets": { "directory": "./dist" }
65
+ }
66
+ ```
67
+
68
+ For plain files, `"directory": "./public"`, and there's nothing to build.
69
+
70
+ 2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
71
+ up.
72
+ 3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time
73
+ (a few minutes). If no browser opens, or they're on another machine, run
74
+ `wrangler login --browser=false` and give them the link it prints. Then `wrangler whoami` to
75
+ confirm.
76
+ 4. `wrangler deploy`. The first deploy creates the Worker, which the author's yes to the account
77
+ covers; later ones update it. Wrangler prints the address.
78
+
79
+ **Don't use `wrangler dev` under Bun:** it answers every request with 503 (a Bun bug that Wrangler
80
+ names). Preview with the project's dev server and Plugin Studio, as step 4 says.
81
+
82
+ ### The key set's headers
83
+
84
+ For a plugin added by URL with secret fields, put `_headers` in `public/`, which the build copies
85
+ into `dist/`:
86
+
87
+ ```
88
+ /.well-known/livespace/jwks.json
89
+ Access-Control-Allow-Origin: *
90
+ ```
91
+
92
+ Cloudflare serves `.well-known/`, and `jwks.json` as `application/json`. `_headers` itself isn't
93
+ served.
94
+
95
+ ### A backend
96
+
97
+ A Worker's backend is one `fetch` handler; the static files are served without running it.
98
+
99
+ ```jsonc
100
+ {
101
+ "name": "my-plugin",
102
+ "main": "src/worker.ts",
103
+ "compatibility_date": "2026-11-01",
104
+ "assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": ["/api/*"] }
105
+ }
106
+ ```
107
+
108
+ ```ts
109
+ export default {
110
+ async fetch(request: Request, env: { ASSETS: Fetcher; API_KEY: string }) {
111
+ const url = new URL(request.url)
112
+ if (url.pathname.startsWith("/api/")) {
113
+ // Verify the plugin's token first: _Your backend_ in llms.txt.
114
+ // env.API_KEY is the secret the author typed in.
115
+ }
116
+ return env.ASSETS.fetch(request)
117
+ },
118
+ }
119
+ ```
120
+
121
+ `_headers` doesn't apply to what the handler returns: set those headers in code.
122
+
123
+ **Secrets:** the author adds each one in the dashboard: **Workers & Pages** → the plugin's
124
+ Worker → **Settings** → **Variables and Secrets** → **Add**, type **Secret**, the name you give
125
+ them (for example `API_KEY`), the value, then **Deploy**. The handler reads it as
126
+ `env.API_KEY`.
127
+ Deploy the Worker once before this, so it exists.
128
+
129
+ ### Not covered
130
+
131
+ No EU-only location for a Worker or its files: requests run wherever is nearest the visitor.
132
+
133
+ ## Other hosts
134
+
135
+ Authors may already use another: Netlify, Vercel, GitHub Pages, or, for a backend, Fly.io or
136
+ Render. Nothing here has been checked for them. Use the host's own docs for each command, and hold
137
+ it to the same rules: what _Hosting your plugin_ requires, and step 5's.
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Writes the filled-in skill folder to `dist/skill/livespace-plugin/`, as `skill install` would
3
+ * write it, for anyone who reads it from the package rather than installing it: jsDelivr serves it
4
+ * to an agent with nothing installed (docs/backlog/038-readme-starter-and-runtime.md). Run by
5
+ * `yarn build`, after tsc.
6
+ */
7
+ import { mkdirSync, writeFileSync } from "node:fs";
8
+ import { SKILL_NAME, readSkillFiles } from "./source.js";
9
+ const target = new URL(`${SKILL_NAME}/`, import.meta.url);
10
+ for (const [name, text] of readSkillFiles()) {
11
+ const file = new URL(name, target);
12
+ mkdirSync(new URL(".", file), { recursive: true });
13
+ writeFileSync(file, text);
14
+ }
@@ -3,14 +3,32 @@
3
3
  * harnesses read it from, and the stamp filled into each copy
4
4
  * (docs/adr/0002-skill-installs-as-copies-in-two-dirs.md).
5
5
  */
6
- import { readFileSync } from "node:fs";
6
+ import { readFileSync, readdirSync } from "node:fs";
7
+ import { join, relative, sep } from "node:path";
8
+ import { fileURLToPath } from "node:url";
7
9
  import { SUPPORTED_SDK_MAJOR, SUPPORTED_SDK_RANGE } from "../sdk/range.js";
8
10
  export const SKILL_NAME = "livespace-plugin";
9
11
  export const SKILL_FILE = "SKILL.md";
10
12
  /** The same from `src/skill/` and `dist/skill/`. */
11
13
  const PACKAGE_ROOT = new URL("../../", import.meta.url);
12
14
  export const CLI_VERSION = JSON.parse(readFileSync(new URL("package.json", PACKAGE_ROOT), "utf8")).version;
13
- export const readSkillSource = () => readFileSync(new URL(`skill/${SKILL_NAME}/${SKILL_FILE}`, PACKAGE_ROOT), "utf8");
15
+ const SKILL_SOURCE_DIR = new URL(`skill/${SKILL_NAME}/`, PACKAGE_ROOT);
16
+ export const readSkillSource = () => readFileSync(new URL(SKILL_FILE, SKILL_SOURCE_DIR), "utf8");
17
+ /**
18
+ * Every file of the skill, filled in: SKILL.md and the reference files beside it (hosts.md, 040),
19
+ * as `[path inside the skill folder, text]`, SKILL.md first.
20
+ */
21
+ export function readSkillFiles() {
22
+ const root = fileURLToPath(SKILL_SOURCE_DIR);
23
+ const names = readdirSync(root, { recursive: true, withFileTypes: true })
24
+ .filter((entry) => entry.isFile())
25
+ .map((entry) => relative(root, join(entry.parentPath, entry.name)).split(sep).join("/"))
26
+ .sort((a, b) => a === SKILL_FILE ? -1 : b === SKILL_FILE ? 1 : a.localeCompare(b));
27
+ return names.map((name) => [
28
+ name,
29
+ renderSkill(readFileSync(join(root, name), "utf8")),
30
+ ]);
31
+ }
14
32
  /** Every target, in the order the CLI writes and reports them. */
15
33
  export const SKILL_TARGETS = [".claude/skills", ".agents/skills"];
16
34
  export const HARNESSES = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livespace/plugin-cli",
3
- "version": "0.4.0",
3
+ "version": "0.5.0-beta.2",
4
4
  "description": "Starts a Livespace plugin project, and sets up its catalog manifest and keys.",
5
5
  "author": "LS FE team",
6
6
  "license": "MIT",
@@ -32,7 +32,7 @@
32
32
  "access": "public"
33
33
  },
34
34
  "scripts": {
35
- "build": "rm -rf dist && tsc -p tsconfig.build.json",
35
+ "build": "rm -rf dist && tsc -p tsconfig.build.json && node dist/skill/package-copy.js",
36
36
  "lint:types": "tsc --noEmit",
37
37
  "prepublishOnly": "yarn test",
38
38
  "test": "yarn build && vitest run --watch false",