@livespace/plugin-cli 0.3.0 → 0.5.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,6 +23,19 @@ Each step is also a command of its own, for a project you already have. In a ter
23
23
  for each answer, as pickers where there's a fixed set; `manifest init` takes its defaults from
24
24
  `package.json` and checks the manifest the way the catalog will before writing it.
25
25
 
26
+ ## Building a plugin with Claude Code
27
+
28
+ No Node, no terminal? Paste this into Claude Code (or another coding agent):
29
+
30
+ > Build me a Livespace plugin. Start by reading
31
+ > https://cdn.jsdelivr.net/npm/@livespace/plugin-cli@0/README.md
32
+
33
+ **For the agent reading this:** the workflow is the `livespace-plugin` skill, at
34
+ https://cdn.jsdelivr.net/npm/@livespace/plugin-cli@0/dist/skill/livespace-plugin/SKILL.md. Read it
35
+ whole and follow it, from "Before you start": it checks for Bun or Node (and installs Bun, with the
36
+ author's consent, if there's neither), then scopes the plugin with the author, then has `create`
37
+ start the project, which installs the skill into it for later sessions.
38
+
26
39
  ## Commands
27
40
 
28
41
  | Command | What it does |
@@ -30,11 +43,12 @@ for each answer, as pickers where there's a fixed set; `manifest init` takes its
30
43
  | `create [dir]` | Start a plugin project in `dir` (default: the current directory), as above. Refuses a directory that isn't empty unless `--force`. `--template vite\|bun` (default: Bun when run with `bunx`, else Vite), `--pm npm\|pnpm\|yarn\|bun` (default: whichever ran it), `--no-install`. |
31
44
  | `manifest init` | Create `plugin-manifest.json`, and optionally the key pairs. Never overwrites a manifest: its `id` is the catalog key. |
32
45
  | `manifest set <field> [value]` | Change one field: `version`, `origin`, `object-types`, `name-<lang>`, `description-<lang>`, `details-<lang>`, `categories`, `icon-url`, `illustration-url`, `accent-color`, `info-url`, `additional-images`, `secret-keys`. |
33
- | `manifest check` | Check the manifest the way the catalog will. Exits 1 on a failure; warnings don't fail. |
46
+ | `manifest check [--origin <url>]` | Check the manifest the way the catalog will. Exits 1 on a failure; warnings don't fail. It also checks it against the project: an image on the plugin's origin with no file in `public/`, context types that differ from a literal list the code passes `declareMetadata`, and a change since `manifest published` without a version bump. With `--origin`, where the plugin is deployed, `iframeOrigin` must be exactly that. |
47
+ | `manifest published` | Record the version and content just published, in `.livespace-plugin-published`. Whoever deploys runs it once a deploy is live; commit it, so the whole team gets the version-bump warning. |
34
48
  | `keys init [--use sig\|enc\|both]` | Create the key pairs: a signing key, plus an encryption key when the manifest has `secretKeys`. With no manifest, both, into a `jwks.json` (see Keys). |
35
49
  | `keys rotate --use sig\|enc` | Add a key for a rotation. At most two of each; a new encryption key goes first, as the browser encrypts with the first. |
36
50
  | `keys retire <kid>` | Remove a key from the manifest. The private half stays on disk until you destroy it. |
37
- | `keys jwks [--out <path>]` | Write `.well-known/livespace/jwks.json` from the manifest's keys, for a catalog plugin that's also added by URL. |
51
+ | `keys jwks [--out <path>]` | Write the `jwks.json` from the manifest's keys, for a catalog plugin that's also added by URL. It goes where a plugin added by URL keeps it (see Keys). |
38
52
  | `client-id` | Print `plugin:<id>`, what your backend checks a plugin token's `aud` against. |
39
53
  | `skill install` | Copy the `livespace-plugin` agent skill into the project: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI and others (Cursor and Copilot read either). `--harness` picks the agents, `--gitignore` keeps the copies out of git. Replaces a copy that's there: run `npx @livespace/plugin-cli@latest skill install` to take the newest skill. The skill reads the SDK's documentation from `node_modules`, so it matches the installed SDK. |
40
54
 
package/dist/cli.js CHANGED
@@ -13,7 +13,7 @@ import { clientId } from "./commands/client-id.js";
13
13
  import { UsageError } from "./commands/context.js";
14
14
  import { DO_YOU_NEED_KEYS, create, spawnExec } from "./commands/create.js";
15
15
  import { keysInit, keysJwks, keysRetire, keysRotate } from "./commands/keys.js";
16
- import { manifestCheck, manifestInit, manifestSet, } from "./commands/manifest.js";
16
+ import { manifestCheck, manifestInit, manifestPublished, manifestSet, } from "./commands/manifest.js";
17
17
  import { skillInstall } from "./commands/skill.js";
18
18
  import { LOCALES } from "./manifest/schema.js";
19
19
  import { Cancelled, clackBackend } from "./ui/clack.js";
@@ -76,8 +76,13 @@ Commands:
76
76
  name-<lang>, description-<lang>, details-<lang>,
77
77
  categories, icon-url, illustration-url, accent-color,
78
78
  info-url, additional-images, secret-keys).
79
- manifest check Check the manifest the way the catalog will. Exit 1 on
80
- a failure.
79
+ manifest check [--origin <url>]
80
+ Check the manifest the way the catalog will, and
81
+ against the project: public/ files, the types the
82
+ code declares, the last publish. With --origin, the
83
+ iframeOrigin must be it. Exit 1 on a failure.
84
+ manifest published Record the version and content just published, so
85
+ check warns about a change without a version bump.
81
86
  keys init [--use sig|enc|both] [--out <path>]
82
87
  Create the key pairs: a signing key, and an encryption
83
88
  key when there are secretKeys. Private halves go to
@@ -88,9 +93,9 @@ Commands:
88
93
  keys rotate --use sig|enc
89
94
  Add a key for a rotation (at most two per use).
90
95
  keys retire <kid> Remove a key from the manifest, or the jwks.json.
91
- keys jwks [--out <path>] Write .well-known/livespace/jwks.json from the
92
- manifest's keys, for a catalog plugin that's also
93
- added by URL.
96
+ keys jwks [--out <path>] Write [public/].well-known/livespace/jwks.json from
97
+ the manifest's keys, for a catalog plugin that's
98
+ also added by URL.
94
99
  client-id Print plugin:<id>, what the backend checks "aud" against.
95
100
  skill install Copy the livespace-plugin agent skill into the project,
96
101
  into .claude/skills and/or .agents/skills, whichever
@@ -122,8 +127,14 @@ Other flags:
122
127
  --yes, -y Take the defaults instead of asking.
123
128
  --json Print only a JSON result.
124
129
  --help, -h This text.
130
+ --version The CLI's version, given alone. With a command, the manifest's.
125
131
  `;
126
132
  async function run(argv) {
133
+ // Alone, --version asks for the CLI's; with a command, it's the manifest's version flag.
134
+ if (argv.length === 1 && argv[0] === "--version") {
135
+ console.log(CLI_VERSION);
136
+ return 0;
137
+ }
127
138
  const { values, positionals } = parseArgs({
128
139
  args: argv,
129
140
  allowPositionals: true,
@@ -182,6 +193,9 @@ async function run(argv) {
182
193
  return 0;
183
194
  case "manifest check":
184
195
  return manifestCheck(ctx);
196
+ case "manifest published":
197
+ await manifestPublished(ctx);
198
+ return 0;
185
199
  case "keys init":
186
200
  await keysInit(ctx);
187
201
  return 0;
@@ -66,8 +66,8 @@ export async function saveKeys(ctx, pairs) {
66
66
  }
67
67
  const exists = (path) => stat(path).then(() => true, () => false);
68
68
  /**
69
- * Without a manifest: `--out`, else whichever jwks.json is already there, else `public/…` when the
70
- * project has a `public/` directory (a created project does), else the project root.
69
+ * Where a jwks.json goes: `--out`, else whichever jwks.json is already there, else `public/…` when
70
+ * the project has a `public/` directory (a created project does), else the project root.
71
71
  */
72
72
  async function jwksPathFor(ctx) {
73
73
  if (typeof ctx.flags.out === "string") {
@@ -260,7 +260,7 @@ export async function keysJwks(ctx) {
260
260
  if (keys.length === 0) {
261
261
  throw new UsageError("the manifest has no keys yet — `keys init` first");
262
262
  }
263
- const out = typeof ctx.flags.out === "string" ? ctx.flags.out : JWKS_PATH;
263
+ const out = await jwksPathFor(ctx);
264
264
  const path = join(ctx.dir, out);
265
265
  await mkdir(dirname(path), { recursive: true });
266
266
  await writeFile(path, `${JSON.stringify({ keys }, null, 2)}\n`);
@@ -1,7 +1,8 @@
1
- /** `manifest init`, `manifest set` and `manifest check`. */
1
+ /** `manifest init`, `manifest set`, `manifest check` and `manifest published`. */
2
2
  import { checkManifest } from "../manifest/check.js";
3
3
  import { readManifestText, readPackageJson, serializeManifest, writeManifest, } from "../manifest/file.js";
4
4
  import { prefillFrom } from "../manifest/package-json.js";
5
+ import { PUBLISHED_FILE, readProjectFacts, recordPublished, } from "../manifest/project.js";
5
6
  import { CATEGORIES, EXPECTED_LOCALES, LOCALES, MANIFEST_FILE, OBJECT_TYPES, REQUIRED_LOCALE, clientIdOf, } from "../manifest/schema.js";
6
7
  import { isHexColor, isHttpsOrigin, isHttpsUrl, isId, isImageUrl, isKeyList, isSemver, splitList, } from "../ui/validators.js";
7
8
  import { UsageError } from "./context.js";
@@ -365,7 +366,15 @@ export async function manifestCheck(ctx) {
365
366
  ctx.out.result({ ok: false, failures: [failure], warnings: [] });
366
367
  return 1;
367
368
  }
368
- const { failures, warnings } = checkManifest(text);
369
+ const origin = ctx.flags.origin;
370
+ if (origin !== undefined) {
371
+ const problem = typeof origin === "string" ? isHttpsOrigin(origin) : "a value";
372
+ if (problem !== undefined) {
373
+ throw new UsageError(`--origin must be ${problem}`);
374
+ }
375
+ }
376
+ const facts = await readProjectFacts(ctx.dir, typeof origin === "string" ? origin : undefined);
377
+ const { failures, warnings } = checkManifest(text, facts);
369
378
  for (const failure of failures) {
370
379
  ctx.out.warn(`✗ ${failure}`);
371
380
  }
@@ -378,3 +387,20 @@ export async function manifestCheck(ctx) {
378
387
  ctx.out.result({ ok: failures.length === 0, failures, warnings });
379
388
  return failures.length === 0 ? 0 : 1;
380
389
  }
390
+ /**
391
+ * Records what was just published: the version and a digest of the rest. A deployer runs it once a
392
+ * deploy is live, so `manifest check` can warn when the manifest changes without a version bump.
393
+ */
394
+ export async function manifestPublished(ctx) {
395
+ const text = await readManifestText(ctx.dir);
396
+ if (text === undefined) {
397
+ throw new UsageError(`no ${MANIFEST_FILE} here — nothing was published`);
398
+ }
399
+ const { manifest } = checkManifest(text);
400
+ if (manifest === null) {
401
+ throw new UsageError(`${MANIFEST_FILE} fails its check, so it can't have been published — see \`manifest check\``);
402
+ }
403
+ const record = await recordPublished(ctx.dir, manifest);
404
+ ctx.out.success(`Recorded version ${record.version} in ${PUBLISHED_FILE}.`);
405
+ ctx.out.result({ published: PUBLISHED_FILE, ...record });
406
+ }
@@ -5,10 +5,10 @@
5
5
  * and running it again is how a project takes a newer skill (docs/adr/0003).
6
6
  */
7
7
  import { access, mkdir, readFile, writeFile } from "node:fs/promises";
8
- import { join } from "node:path";
8
+ import { dirname, join } from "node:path";
9
9
  import { addToGitignore } from "../project/gitignore.js";
10
10
  import { SDK_LLMS_TXT_CDN_URL, SUPPORTED_SDK_RANGE, isSupportedSdkVersion, } from "../sdk/range.js";
11
- import { CLI_VERSION, HARNESSES, SKILL_FILE, SKILL_NAME, readSkillSource, readStamp, renderSkill, targetsFor, } from "../skill/source.js";
11
+ import { CLI_VERSION, HARNESSES, SKILL_FILE, SKILL_NAME, readSkillFiles, readStamp, targetsFor, } from "../skill/source.js";
12
12
  const exists = (path) => access(path).then(() => true, () => false);
13
13
  /** The installed SDK's version, or undefined when it isn't in node_modules. */
14
14
  async function installedSdkVersion(dir) {
@@ -46,14 +46,17 @@ export async function skillInstall(ctx) {
46
46
  else if (!supported) {
47
47
  ctx.out.warn(`The project has @livespace/plugin-sdk ${sdkVersion}, but this CLI's skill is written for ${SUPPORTED_SDK_RANGE}. Its workflow may not match the SDK; llms.txt is still the installed one.`);
48
48
  }
49
- const copy = renderSkill(readSkillSource());
49
+ const files = readSkillFiles();
50
50
  const targets = [];
51
51
  for (const target of targetsFor(harnesses)) {
52
52
  const skillDir = `${target}/${SKILL_NAME}`;
53
53
  const path = join(ctx.dir, skillDir, SKILL_FILE);
54
54
  const before = await readFile(path, "utf8").catch(() => undefined);
55
- await mkdir(join(ctx.dir, skillDir), { recursive: true });
56
- await writeFile(path, copy);
55
+ for (const [name, text] of files) {
56
+ const filePath = join(ctx.dir, skillDir, name);
57
+ await mkdir(dirname(filePath), { recursive: true });
58
+ await writeFile(filePath, text);
59
+ }
57
60
  if (before === undefined) {
58
61
  ctx.out.success(`Wrote ${skillDir}/${SKILL_FILE}`);
59
62
  targets.push({ dir: skillDir, status: "written" });
@@ -2,10 +2,12 @@
2
2
  * Checks a `plugin-manifest.json` the way the catalog will read it.
3
3
  *
4
4
  * Ported from Labs' `checkManifest` (livespace-labs/scripts/plugin-manifest.ts), with its messages,
5
- * minus what only applies to Labs (its 28-character id and its own origin), plus P2-27's keys.
5
+ * minus its 28-character id, plus P2-27's keys. What Labs read from the project (its deploy origin,
6
+ * the asset files, the declared types, the last publish) comes in as `ProjectFacts` (034).
6
7
  * A failure is something the registry would refuse or mis-store; a warning is something a person
7
8
  * should look at. Pure: no file system, no network.
8
9
  */
10
+ import { createHash } from "node:crypto";
9
11
  import { CATEGORIES, EXPECTED_LOCALES, FIELDS, ID_PATTERN, KEY_ALG, KEY_USES, MAX_KEYS_PER_USE, MIN_RSA_BITS, OBJECT_TYPES, REQUIRED_LOCALE, } from "./schema.js";
10
12
  const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
11
13
  const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
@@ -41,7 +43,25 @@ const parseUrl = (v) => {
41
43
  };
42
44
  /** The bit length of a JWK's base64url modulus. */
43
45
  const modulusBits = (n) => Buffer.from(n, "base64url").length * 8;
44
- export function checkManifest(text) {
46
+ /** A digest of the manifest without its version, so only a content change moves it. */
47
+ export function contentDigest(manifest) {
48
+ const { version: _version, ...rest } = manifest;
49
+ return createHash("sha256").update(canonical(rest)).digest("hex");
50
+ }
51
+ /** JSON with keys sorted at every depth, so key order never changes the digest. */
52
+ function canonical(value) {
53
+ if (Array.isArray(value)) {
54
+ return `[${value.map(canonical).join(",")}]`;
55
+ }
56
+ if (isRecord(value)) {
57
+ return `{${Object.keys(value)
58
+ .sort()
59
+ .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
60
+ .join(",")}}`;
61
+ }
62
+ return JSON.stringify(value);
63
+ }
64
+ export function checkManifest(text, facts = {}) {
45
65
  const failures = [];
46
66
  const warnings = [];
47
67
  const done = (manifest) => ({
@@ -105,8 +125,48 @@ export function checkManifest(text) {
105
125
  }
106
126
  }
107
127
  checkKeys(m, failures, warnings);
128
+ checkAgainstProject(m, facts, failures, warnings);
108
129
  return done(m);
109
130
  }
131
+ const typesLabel = (types) => types === null ? "any type" : [...types].sort().join(", ");
132
+ function checkAgainstProject(m, facts, failures, warnings) {
133
+ if (facts.origin !== undefined && m.iframeOrigin !== facts.origin) {
134
+ failures.push(`"iframeOrigin" must be ${facts.origin}, where the plugin is deployed, not ${m.iframeOrigin}`);
135
+ }
136
+ const origin = parseUrl(m.iframeOrigin)?.origin;
137
+ if (facts.publicFiles !== undefined && origin !== undefined) {
138
+ const images = [
139
+ ["iconUrl", m.iconUrl],
140
+ ["illustrationUrl", m.illustrationUrl],
141
+ ...(m.additionalImages ?? []).map((url, i) => [
142
+ `additionalImages[${i}]`,
143
+ url,
144
+ ]),
145
+ ];
146
+ for (const [key, value] of images) {
147
+ const url = value === undefined ? null : parseUrl(value);
148
+ if (url === null || url.origin !== origin) {
149
+ continue;
150
+ }
151
+ const path = decodeURIComponent(url.pathname);
152
+ if (!facts.publicFiles.has(path)) {
153
+ warnings.push(`"${key}" points at ${path}, but there's no public${path} — the catalog would show a broken image`);
154
+ }
155
+ }
156
+ }
157
+ if (facts.declared !== undefined) {
158
+ const inManifest = typesLabel(m.allowedObjectTypes);
159
+ const declared = typesLabel(facts.declared.types);
160
+ if (inManifest !== declared) {
161
+ warnings.push(`"allowedObjectTypes" (${inManifest}) differs from what ${facts.declared.file} declares (${declared}) — added by URL, the plugin would be offered elsewhere than the catalog places it`);
162
+ }
163
+ }
164
+ if (facts.published !== undefined &&
165
+ m.version === facts.published.version &&
166
+ contentDigest(m) !== facts.published.digest) {
167
+ warnings.push(`the manifest changed since the last publish, but "version" is still ${m.version} — bump it`);
168
+ }
169
+ }
110
170
  function checkOrigin(origin, failures) {
111
171
  const url = parseUrl(origin);
112
172
  if (url === null || url.protocol !== "https:") {
@@ -0,0 +1,115 @@
1
+ /**
2
+ * What `manifest check` reads from the project for the checks Labs' checker made (034): the files in
3
+ * `public/`, the context types the code declares, and what the last publish recorded.
4
+ */
5
+ import { readFile, readdir, writeFile } from "node:fs/promises";
6
+ import { join, relative, sep } from "node:path";
7
+ import { contentDigest } from "./check.js";
8
+ /** What `manifest published` records, for the "changed without a version bump" warning. */
9
+ export const PUBLISHED_FILE = ".livespace-plugin-published";
10
+ /** Where a plugin's code may call `declareMetadata`, in the order they're searched. */
11
+ const SOURCE_DIRS = ["src", "public"];
12
+ const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|html)$/;
13
+ const SKIPPED_DIRS = new Set(["node_modules", "dist", ".git"]);
14
+ const CALL = /declareMetadata\(\s*\{([\s\S]*?)\}\s*\)/;
15
+ const TYPES = /(?:supportedContextTypes|allowedObjectTypes)\s*:\s*(null|\[([^\]]*)\])/;
16
+ const QUOTED = /["'`]([a-z]+)["'`]/g;
17
+ /**
18
+ * The context types a source text passes `declareMetadata`, when it's a literal list or null.
19
+ * Anything else (no call, no types, a variable) reads as nothing: this is a text search, so it only
20
+ * reports what it can be sure of.
21
+ */
22
+ export function declaredTypes(source) {
23
+ const body = CALL.exec(source)?.[1];
24
+ const match = body === undefined ? null : TYPES.exec(body);
25
+ if (match === null) {
26
+ return undefined;
27
+ }
28
+ if (match[1] === "null") {
29
+ return { types: null };
30
+ }
31
+ return {
32
+ types: [...(match[2] ?? "").matchAll(QUOTED)].flatMap((m) => m[1] === undefined ? [] : [m[1]]),
33
+ };
34
+ }
35
+ /**
36
+ * Every file under `root`, as `/`-separated paths relative to it, skipping dependencies and build
37
+ * output. Undefined when there's no `root`.
38
+ */
39
+ async function filesUnder(root) {
40
+ let entries;
41
+ try {
42
+ entries = await readdir(root, { recursive: true, withFileTypes: true });
43
+ }
44
+ catch {
45
+ return undefined;
46
+ }
47
+ return entries
48
+ .filter((entry) => entry.isFile())
49
+ .map((entry) => relative(root, join(entry.parentPath, entry.name)).split(sep))
50
+ .filter((parts) => !parts.some((part) => SKIPPED_DIRS.has(part)))
51
+ .map((parts) => parts.join("/"));
52
+ }
53
+ async function findDeclaration(dir) {
54
+ const candidates = ["index.html"];
55
+ for (const sub of SOURCE_DIRS) {
56
+ for (const file of (await filesUnder(join(dir, sub))) ?? []) {
57
+ if (SOURCE_FILE.test(file)) {
58
+ candidates.push(`${sub}/${file}`);
59
+ }
60
+ }
61
+ }
62
+ for (const file of candidates) {
63
+ let source;
64
+ try {
65
+ source = await readFile(join(dir, file), "utf8");
66
+ }
67
+ catch {
68
+ continue;
69
+ }
70
+ const found = declaredTypes(source);
71
+ if (found !== undefined) {
72
+ return { ...found, file };
73
+ }
74
+ }
75
+ return undefined;
76
+ }
77
+ async function readPublished(dir) {
78
+ try {
79
+ const value = JSON.parse(await readFile(join(dir, PUBLISHED_FILE), "utf8"));
80
+ return typeof value?.version === "string" &&
81
+ typeof value?.digest === "string"
82
+ ? { version: value.version, digest: value.digest }
83
+ : undefined;
84
+ }
85
+ catch {
86
+ return undefined;
87
+ }
88
+ }
89
+ /** Everything `checkManifest` can compare with, from the project at `dir`. */
90
+ export async function readProjectFacts(dir, origin) {
91
+ const facts = {};
92
+ if (origin !== undefined) {
93
+ facts.origin = origin;
94
+ }
95
+ const publicDir = join(dir, "public");
96
+ const publicFiles = await filesUnder(publicDir);
97
+ if (publicFiles !== undefined) {
98
+ facts.publicFiles = new Set(publicFiles.map((file) => `/${file}`));
99
+ }
100
+ const declared = await findDeclaration(dir);
101
+ if (declared !== undefined) {
102
+ facts.declared = declared;
103
+ }
104
+ const published = await readPublished(dir);
105
+ if (published !== undefined) {
106
+ facts.published = published;
107
+ }
108
+ return facts;
109
+ }
110
+ /** Records what was just published, so the next check can spot a change without a version bump. */
111
+ export async function recordPublished(dir, manifest) {
112
+ const record = { version: manifest.version, digest: contentDigest(manifest) };
113
+ await writeFile(join(dir, PUBLISHED_FILE), `${JSON.stringify(record, null, 2)}\n`);
114
+ return record;
115
+ }
package/dist/sdk/range.js CHANGED
@@ -26,4 +26,4 @@ export const SDK_LLMS_TXT_CDN_URL = `https://cdn.jsdelivr.net/npm/@livespace/plu
26
26
  * takes the project's SDK as a peer, so it isn't tied to the SDK's major. A test keeps it in step
27
27
  * with `packages/studio`.
28
28
  */
29
- export const STUDIO_RANGE = "^0.1";
29
+ export const STUDIO_RANGE = "^0.2";
@@ -0,0 +1,273 @@
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.1"
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.
51
+ - **No project yet** (you came here from a link): once you've scoped it (step 1), start one with
52
+ `create`, which also installs this skill so later sessions have it. A project without the skill
53
+ gets it with `skill install`.
54
+
55
+ ## 0. Read `llms.txt`
56
+
57
+ Before writing or changing plugin code, read the SDK's documentation as one file:
58
+
59
+ 1. `node_modules/@livespace/plugin-sdk/dist/llms.txt`, which matches the installed SDK;
60
+ 2. if that's missing, `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@1/dist/llms.txt`.
61
+
62
+ Read its opening part (_Livespace plugins_, down to _Rules that will bite you_) whole, then each
63
+ section the task touches. Look API detail up there every time rather than recalling it: it is the
64
+ source of truth, and it wins wherever it and this skill differ. Done when you can name the sections
65
+ the task touches and have read them.
66
+
67
+ ## 1. Scope it
68
+
69
+ Ask the author, a few questions at a time (one at a time in plain language), until you can state
70
+ the plugin in one sentence and name its record types, its data sources, its settings, where each
71
+ secret lives, and where the plugin will live. Ask before writing any code, so nobody builds
72
+ something they can't host or install. Skip what's already settled, by the record or by an earlier
73
+ answer: the list below is what to know, not a script.
74
+
75
+ - **What it shows or does.** Push for one sentence. Livespace gives the plugin the whole record it
76
+ sits on, so check _Objects_ in `llms.txt` for whether the answer is already there. Then pin down
77
+ the edges, which a non-developer won't volunteer: which field means what they said, what shows
78
+ when it's empty or the record is closed, and any threshold (an admin may want to change it: a
79
+ setting).
80
+ - **Which record types**: deal, company, person, space.
81
+ - **Where its data comes from**: Livespace (`LsPlugin.api.call`), a backend of the author's own
82
+ (`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere. In plain language:
83
+ "Does it need anything from outside Livespace, like another app?" A service outside Livespace (a
84
+ third-party API) always means a backend, which holds that service's key: say early that this
85
+ makes hosting harder.
86
+ - **Tenancy**, asked early, because it decides whether the plugin needs keys. In plain language:
87
+ "Is this for your own Livespace account, or for other companies' accounts too?"
88
+ - **Single-tenant**: the backend serves one Livespace account, the author's own. Always added
89
+ by URL.
90
+ - **Multi-tenant**: one backend serves many accounts. Then ask whether it's a **catalog**
91
+ plugin (listed, with a `plugin-manifest.json`) or **added by URL**.
92
+
93
+ With a backend that holds secrets, explain why the answer matters, from _Do you need keys?_ in
94
+ `llms.txt`: an admin's browser
95
+ encrypts a secret field's value with the plugin's public key, so only its backend reads it, and
96
+ how the plugin reaches an account decides where Livespace finds that key. The author decides
97
+ with that in hand.
98
+ - **Secrets**, any credential the backend uses. Each lives in exactly one of two homes:
99
+ - Single-tenant: offer both. **The backend's environment** needs no keys, and changing the
100
+ secret means a redeploy. **A secret field** (`addSecretInput`) lets the account's admins set
101
+ and replace it in Livespace's settings, and needs keys.
102
+ - Multi-tenant with per-account secrets: a secret field, so keys.
103
+
104
+ A secret goes in one of those homes, never in an ordinary config field. If the author wants a
105
+ config field to avoid keys, explain that a config field's value reaches the browser of every
106
+ user who opens the plugin, so every coworker (or every customer's user) can read it, then offer
107
+ the two homes again.
108
+ - **Settings an admin changes**: a config form. Livespace renders, validates and stores it.
109
+ - **Who will add it to Livespace.** An admin of the account adds it, in Account settings →
110
+ Plugins, and asks Livespace support to allow its address. If the author isn't an admin, they'll
111
+ need one for both: say so now.
112
+ - **Where it will live.** It needs an HTTPS address that Livespace allows (_Rules that will bite
113
+ you_ in `llms.txt`); _Hosting your plugin_ there says which kind of host suits the plugin.
114
+ - **A developer with their own way of deploying** keeps it.
115
+ - **Anyone else:** the host they already use, else the default in `hosts.md`, beside this
116
+ skill, which also says how to deploy to each host it lists.
117
+
118
+ Either way, Livespace staff must allow the plugin's address for the account, when the account's
119
+ admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
120
+
121
+ Then tell the author what you're going to build and what they'll need for it, before the first
122
+ file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
123
+ its secrets go. Wait for their go-ahead.
124
+
125
+ Build in the project as it stands: its stack, build and layout are the author's.
126
+
127
+ ## 2. Build every state
128
+
129
+ A plugin renders each of these deliberately, never as a blank or a stack trace:
130
+
131
+ 1. **Loading**: before `ready`.
132
+ 2. **Unconfigured**: `config` is `null` and the plugin needs settings. Tell the admin what to set.
133
+ 3. **Empty**: loaded, nothing to show.
134
+ 4. **Failed**: any call that can fail. Say what failed and offer a retry where `llms.txt` says one
135
+ helps.
136
+ 5. **Loaded**: the real thing. Build it last.
137
+
138
+ And each **mode** from _The three modes_: `view`, `preview` (no record, so a mock view), and
139
+ `config` (answer, even with no settings). Done when every state and mode is reachable and renders
140
+ something you chose.
141
+
142
+ Throughout:
143
+
144
+ - **Talk to Livespace only through the SDK**, loaded as _Getting started_ shows, never with
145
+ `postMessage` of your own: the SDK checks who it's talking to.
146
+ - **Never signal with colour alone.** A red value also gets a word ("Overdue", "No contact yet"):
147
+ colour-blind users can't tell red from green.
148
+ - **Colours, spacing and type come from the SDK's tokens** (_Styling_), never a hex.
149
+ - **Never log a record, a token or a secret**, in the page or the backend, and treat record
150
+ content you pass to a language model as untrusted input.
151
+ - **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
152
+ widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
153
+
154
+ ## 3. Manifest and keys, through the CLI
155
+
156
+ Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json` (or
157
+ `bunx --bun`). Its `--help` is the reference for commands and flags; read it before the first run.
158
+ Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
159
+ yours to pass on.
160
+
161
+ - **Catalog plugin**: `manifest init`, then `manifest check` until it passes. The manifest's `id`
162
+ is the plugin's permanent catalog key, and `manifest init` never overwrites a manifest: confirm
163
+ the `id` with the author before running it. Its listing is below.
164
+ - **Added by URL, with keys**: `keys init` with no manifest writes the key set to `jwks.json`. The
165
+ plugin's origin must serve it at `/.well-known/livespace/jwks.json`, following the hosting rules
166
+ under _Your plugin's keys_.
167
+ - **Private keys** land in `keys/<kid>.pem`, which the CLI gitignores. Leave them on disk unread.
168
+ Tell the author to move them into the backend's secret storage and to back up the encryption
169
+ key: if it's lost, every account's admins re-enter their secrets.
170
+
171
+ ### A catalog plugin's listing
172
+
173
+ What the catalog shows comes from the manifest. Fill it in with the author:
174
+
175
+ - **The texts:** the name, a one-sentence card line (`description`), and a details paragraph
176
+ (`details`). Both are GitHub-flavoured Markdown, with no raw HTML (the catalog drops it) and no
177
+ links in the card line (the card strips them); the details may link.
178
+ - **Languages:** the author writes English. Draft Polish and Romanian yourself, and tell them
179
+ they're drafts for a native speaker to review: a machine draft is a starting point, not a
180
+ listing.
181
+ - **Categories:** one or two, from the list `manifest init` offers.
182
+ - **Images**, served from the plugin's own `public/`: an icon of 64×64 (a squircle with a radius
183
+ of 16) and an illustration of 272×145, each SVG or PNG, plus optional screenshots
184
+ (`additionalImages`). Placeholders do for testing, not for review.
185
+ - **An about page** for `infoUrl`, for example `public/about.html`: what it does, where it
186
+ appears, its settings, and who to ask.
187
+ - **Where it can go:** `allowedObjectTypes`. If the code also calls `declareMetadata` with context
188
+ types, it lists the same ones (`manifest check` warns when they differ).
189
+ - **A new `version` with every change** to the manifest, and `manifest published` once each
190
+ version is deployed, so `manifest check` catches a change shipped without one.
191
+
192
+ ## 4. Check it
193
+
194
+ - Open the page outside Livespace: it shows its loading state and the console is clean.
195
+ - Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
196
+ made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
197
+ - **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
198
+ use the one already running: it's probably the author's, and its saved settings, secrets and
199
+ exchange failures are shared by everyone using it.
200
+ - **With a browser tool, reach every state and mode from step 2**: each record type and no
201
+ record, no viewer, `null` and saved settings, preview and config on its settings page, the
202
+ narrowest and the widest slot (`width=320` and `width=full`), the dialog and fullscreen, and
203
+ the failures it can switch on. Check each renders what you chose,
204
+ with nothing unexpected in its message log.
205
+ - **Set each state up from the address** rather than by clicking: one URL per state, e.g.
206
+ `http://localhost:5190/#?type=none&viewer=&display=dialog&token=forbidden`, or
207
+ `#settings?preferences=en-US` for the settings page. The studio's README
208
+ (`node_modules/@livespace/plugin-studio/README.md`) lists the params, and the log notes what
209
+ it set and what it ignored.
210
+ - **Saved settings go through the settings page**, never the address: fill in its form and
211
+ Save, or Forget for `null`.
212
+ - **Read the log from the browser console**, not the page: each entry is a line prefixed
213
+ `[studio]`. The studio's notes are warnings, so read those first: anything it refused or
214
+ dropped is a mistake to fix. The messages to and from the plugin are `debug` (with the
215
+ Playwright MCP, `browser_console_messages` with `level: "debug"`); read them when something
216
+ looks wrong.
217
+ - Setting up from the address and the console log need `@livespace/plugin-studio` 0.2 or
218
+ later.
219
+ - **Without a browser tool**, ask the author to do the same, and say what to look for.
220
+ - With a backend, point it at your studio with the env values it prints, and check it verifies
221
+ the plugin's token and reads its secrets.
222
+ - For a catalog plugin, `manifest check` passes.
223
+
224
+ ## 5. Host it
225
+
226
+ A developer deploying their own way needs only what any host must give the plugin (_Hosting your
227
+ plugin_ in `llms.txt`): say it, and leave the how to them. Otherwise deploy to the host from step
228
+ 1, as `hosts.md` describes for it, under these rules on any host:
229
+
230
+ - **Nothing that could cost money without a yes.** Before creating an account, a project or a
231
+ service, say in a sentence what you'll create and that it's on the free plan, then wait. Never
232
+ enter payment details. If the host asks for a card, stop and explain why.
233
+ - **The address is permanent.** Confirm the plugin's name in it with the author before the first
234
+ deploy: support allows that exact address, and admins add the plugin by it.
235
+ - **Check what you can before the author signs up for anything:** build, and any dry run the host
236
+ offers.
237
+ - **Whose account.** Suggest the company's account at that host, or a shared company email, so
238
+ the plugin outlives whoever made it. A personal account is the author's call, once they've heard
239
+ that risk.
240
+ - **Secrets go in by hand.** The author types each secret into the host's dashboard; name the page
241
+ and the field. Never ask them to paste one into the chat.
242
+ - **The author does what only a person can** (signing up, logging in through the browser): one
243
+ step at a time, saying what they'll see. Run everything else yourself.
244
+
245
+ Then check the deployed page as in step 4, at its new address (start the studio with
246
+ `--url <address>`), and tell the author:
247
+
248
+ - **The address**, and that Livespace support must allow it for their account before it shows.
249
+ - **Who adds it**: an admin of the account, by its address, in Account settings → Plugins, after
250
+ asking support to allow it. If that isn't the author, write them a short note to forward to the
251
+ admin, with the address and those two steps.
252
+ - **What happens to the keys**, if it has any: where the private halves are, what to do with them,
253
+ and where the public ones must be published.
254
+ - **That config is not secret storage**, if the plugin has any settings.
255
+
256
+ ### A catalog plugin: listing, testing, review
257
+
258
+ Livespace lists a catalog plugin, not this skill: give whoever lists it the deployed address and
259
+ `plugin-manifest.json`, and say so to the author.
260
+
261
+ - **A new entry is hidden from customers.** An internal Livespace instance lists every entry, and
262
+ that's where it's tested. Walk the tester through this there, and fix, bump `version` and
263
+ redeploy for each failure:
264
+ - the card and details show the right name, texts and images, in English, Polish and Romanian;
265
+ - it can only be placed on the types it declares;
266
+ - on a real record it shows the record's data, and updates without a reload when it's edited;
267
+ - its settings form appears (an empty one if it has none), and its preview renders;
268
+ - the narrowest and the widest slot both read well.
269
+ - **Before review:** real images, and the Polish and Romanian texts reviewed by a native speaker.
270
+ - **Publishing it to every account is a reviewer's decision, made in Livespace.** Prepare a review
271
+ note for the author to hand over: what it does and where it appears, the checklist with its
272
+ results, how it uses the Livespace API, its settings, and open issues. Never say it's published
273
+ when it has only been deployed or listed.
@@ -0,0 +1,132 @@
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
+ 1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
56
+
57
+ ```jsonc
58
+ {
59
+ "name": "my-plugin", // the first part of the address
60
+ "compatibility_date": "2026-11-01",
61
+ "assets": { "directory": "./dist" }
62
+ }
63
+ ```
64
+
65
+ 2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
66
+ up.
67
+ 3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time
68
+ (a few minutes). If no browser opens, or they're on another machine, run
69
+ `wrangler login --browser=false` and give them the link it prints. Then `wrangler whoami` to
70
+ confirm.
71
+ 4. `wrangler deploy`. The first deploy creates the Worker, which the author's yes to the account
72
+ covers; later ones update it. Wrangler prints the address.
73
+
74
+ **Don't use `wrangler dev` under Bun:** it answers every request with 503 (a Bun bug that Wrangler
75
+ names). Preview with the project's dev server and Plugin Studio, as step 4 says.
76
+
77
+ ### The key set's headers
78
+
79
+ For a plugin added by URL with secret fields, put `_headers` in `public/`, which the build copies
80
+ into `dist/`:
81
+
82
+ ```
83
+ /.well-known/livespace/jwks.json
84
+ Access-Control-Allow-Origin: *
85
+ ```
86
+
87
+ Cloudflare serves `.well-known/`, and `jwks.json` as `application/json`. `_headers` itself isn't
88
+ served.
89
+
90
+ ### A backend
91
+
92
+ A Worker's backend is one `fetch` handler; the static files are served without running it.
93
+
94
+ ```jsonc
95
+ {
96
+ "name": "my-plugin",
97
+ "main": "src/worker.ts",
98
+ "compatibility_date": "2026-11-01",
99
+ "assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": ["/api/*"] }
100
+ }
101
+ ```
102
+
103
+ ```ts
104
+ export default {
105
+ async fetch(request: Request, env: { ASSETS: Fetcher; API_KEY: string }) {
106
+ const url = new URL(request.url)
107
+ if (url.pathname.startsWith("/api/")) {
108
+ // Verify the plugin's token first: _Your backend_ in llms.txt.
109
+ // env.API_KEY is the secret the author typed in.
110
+ }
111
+ return env.ASSETS.fetch(request)
112
+ },
113
+ }
114
+ ```
115
+
116
+ `_headers` doesn't apply to what the handler returns: set those headers in code.
117
+
118
+ **Secrets:** the author adds each one in the dashboard: **Workers & Pages** → the plugin's
119
+ Worker → **Settings** → **Variables and Secrets** → **Add**, type **Secret**, the name you give
120
+ them (for example `API_KEY`), the value, then **Deploy**. The handler reads it as
121
+ `env.API_KEY`.
122
+ Deploy the Worker once before this, so it exists.
123
+
124
+ ### Not covered
125
+
126
+ No EU-only location for a Worker or its files: requests run wherever is nearest the visitor.
127
+
128
+ ## Other hosts
129
+
130
+ Authors may already use another: Netlify, Vercel, GitHub Pages, or, for a backend, Fly.io or
131
+ Render. Nothing here has been checked for them. Use the host's own docs for each command, and hold
132
+ 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.3.0",
3
+ "version": "0.5.0-beta.1",
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",
@@ -1,6 +1,6 @@
1
1
  ---
2
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 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.
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
4
  metadata:
5
5
  cli-version: "{{cliVersion}}"
6
6
  sdk-range: "{{sdkRange}}"
@@ -11,6 +11,47 @@ metadata:
11
11
  This skill is the workflow: what to ask, what to build, in what order. The SDK's documentation is
12
12
  the reference: every method, event, field, token name and limit.
13
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.
51
+ - **No project yet** (you came here from a link): once you've scoped it (step 1), start one with
52
+ `create`, which also installs this skill so later sessions have it. A project without the skill
53
+ gets it with `skill install`.
54
+
14
55
  ## 0. Read `llms.txt`
15
56
 
16
57
  Before writing or changing plugin code, read the SDK's documentation as one file:
@@ -25,20 +66,32 @@ the task touches and have read them.
25
66
 
26
67
  ## 1. Scope it
27
68
 
28
- Ask the author, a few questions at a time, until you can state the plugin in one sentence and name
29
- its record types, its data sources, its settings, and where each secret lives.
69
+ Ask the author, a few questions at a time (one at a time in plain language), until you can state
70
+ the plugin in one sentence and name its record types, its data sources, its settings, where each
71
+ secret lives, and where the plugin will live. Ask before writing any code, so nobody builds
72
+ something they can't host or install. Skip what's already settled, by the record or by an earlier
73
+ answer: the list below is what to know, not a script.
30
74
 
31
- - **What it shows or does.** Push for one sentence.
75
+ - **What it shows or does.** Push for one sentence. Livespace gives the plugin the whole record it
76
+ sits on, so check _Objects_ in `llms.txt` for whether the answer is already there. Then pin down
77
+ the edges, which a non-developer won't volunteer: which field means what they said, what shows
78
+ when it's empty or the record is closed, and any threshold (an admin may want to change it: a
79
+ setting).
32
80
  - **Which record types**: deal, company, person, space.
33
81
  - **Where its data comes from**: Livespace (`LsPlugin.api.call`), a backend of the author's own
34
- (`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere.
35
- - **Tenancy**, asked early, because it decides whether the plugin needs keys:
82
+ (`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere. In plain language:
83
+ "Does it need anything from outside Livespace, like another app?" A service outside Livespace (a
84
+ third-party API) always means a backend, which holds that service's key: say early that this
85
+ makes hosting harder.
86
+ - **Tenancy**, asked early, because it decides whether the plugin needs keys. In plain language:
87
+ "Is this for your own Livespace account, or for other companies' accounts too?"
36
88
  - **Single-tenant**: the backend serves one Livespace account, the author's own. Always added
37
89
  by URL.
38
90
  - **Multi-tenant**: one backend serves many accounts. Then ask whether it's a **catalog**
39
91
  plugin (listed, with a `plugin-manifest.json`) or **added by URL**.
40
92
 
41
- Explain why the answer matters, from _Do you need keys?_ in `llms.txt`: an admin's browser
93
+ With a backend that holds secrets, explain why the answer matters, from _Do you need keys?_ in
94
+ `llms.txt`: an admin's browser
42
95
  encrypts a secret field's value with the plugin's public key, so only its backend reads it, and
43
96
  how the plugin reaches an account decides where Livespace finds that key. The author decides
44
97
  with that in hand.
@@ -53,6 +106,21 @@ its record types, its data sources, its settings, and where each secret lives.
53
106
  user who opens the plugin, so every coworker (or every customer's user) can read it, then offer
54
107
  the two homes again.
55
108
  - **Settings an admin changes**: a config form. Livespace renders, validates and stores it.
109
+ - **Who will add it to Livespace.** An admin of the account adds it, in Account settings →
110
+ Plugins, and asks Livespace support to allow its address. If the author isn't an admin, they'll
111
+ need one for both: say so now.
112
+ - **Where it will live.** It needs an HTTPS address that Livespace allows (_Rules that will bite
113
+ you_ in `llms.txt`); _Hosting your plugin_ there says which kind of host suits the plugin.
114
+ - **A developer with their own way of deploying** keeps it.
115
+ - **Anyone else:** the host they already use, else the default in `hosts.md`, beside this
116
+ skill, which also says how to deploy to each host it lists.
117
+
118
+ Either way, Livespace staff must allow the plugin's address for the account, when the account's
119
+ admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
120
+
121
+ Then tell the author what you're going to build and what they'll need for it, before the first
122
+ file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
123
+ its secrets go. Wait for their go-ahead.
56
124
 
57
125
  Build in the project as it stands: its stack, build and layout are the author's.
58
126
 
@@ -71,15 +139,28 @@ And each **mode** from _The three modes_: `view`, `preview` (no record, so a moc
71
139
  `config` (answer, even with no settings). Done when every state and mode is reachable and renders
72
140
  something you chose.
73
141
 
142
+ Throughout:
143
+
144
+ - **Talk to Livespace only through the SDK**, loaded as _Getting started_ shows, never with
145
+ `postMessage` of your own: the SDK checks who it's talking to.
146
+ - **Never signal with colour alone.** A red value also gets a word ("Overdue", "No contact yet"):
147
+ colour-blind users can't tell red from green.
148
+ - **Colours, spacing and type come from the SDK's tokens** (_Styling_), never a hex.
149
+ - **Never log a record, a token or a secret**, in the page or the backend, and treat record
150
+ content you pass to a language model as untrusted input.
151
+ - **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
152
+ widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
153
+
74
154
  ## 3. Manifest and keys, through the CLI
75
155
 
76
- Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json`. Its
77
- `--help` is the reference for commands and flags; read it before the first run. Under `--json` the
78
- only output is one JSON result, so the guidance it would print in a terminal is yours to pass on.
156
+ Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json` (or
157
+ `bunx --bun`). Its `--help` is the reference for commands and flags; read it before the first run.
158
+ Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
159
+ yours to pass on.
79
160
 
80
161
  - **Catalog plugin**: `manifest init`, then `manifest check` until it passes. The manifest's `id`
81
162
  is the plugin's permanent catalog key, and `manifest init` never overwrites a manifest: confirm
82
- the `id` with the author before running it.
163
+ the `id` with the author before running it. Its listing is below.
83
164
  - **Added by URL, with keys**: `keys init` with no manifest writes the key set to `jwks.json`. The
84
165
  plugin's origin must serve it at `/.well-known/livespace/jwks.json`, following the hosting rules
85
166
  under _Your plugin's keys_.
@@ -87,23 +168,106 @@ only output is one JSON result, so the guidance it would print in a terminal is
87
168
  Tell the author to move them into the backend's secret storage and to back up the encryption
88
169
  key: if it's lost, every account's admins re-enter their secrets.
89
170
 
90
- ## 4. Check it and hand it over
171
+ ### A catalog plugin's listing
172
+
173
+ What the catalog shows comes from the manifest. Fill it in with the author:
174
+
175
+ - **The texts:** the name, a one-sentence card line (`description`), and a details paragraph
176
+ (`details`). Both are GitHub-flavoured Markdown, with no raw HTML (the catalog drops it) and no
177
+ links in the card line (the card strips them); the details may link.
178
+ - **Languages:** the author writes English. Draft Polish and Romanian yourself, and tell them
179
+ they're drafts for a native speaker to review: a machine draft is a starting point, not a
180
+ listing.
181
+ - **Categories:** one or two, from the list `manifest init` offers.
182
+ - **Images**, served from the plugin's own `public/`: an icon of 64×64 (a squircle with a radius
183
+ of 16) and an illustration of 272×145, each SVG or PNG, plus optional screenshots
184
+ (`additionalImages`). Placeholders do for testing, not for review.
185
+ - **An about page** for `infoUrl`, for example `public/about.html`: what it does, where it
186
+ appears, its settings, and who to ask.
187
+ - **Where it can go:** `allowedObjectTypes`. If the code also calls `declareMetadata` with context
188
+ types, it lists the same ones (`manifest check` warns when they differ).
189
+ - **A new `version` with every change** to the manifest, and `manifest published` once each
190
+ version is deployed, so `manifest check` catches a change shipped without one.
191
+
192
+ ## 4. Check it
91
193
 
92
194
  - Open the page outside Livespace: it shows its loading state and the console is clean.
93
195
  - Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
94
- made, else `npx @livespace/plugin-studio`. It embeds the page as Livespace does. With a browser tool, open it and reach every state and mode from step 2:
95
- each record type and no record, `null` and saved settings, preview and config on its settings
96
- page, the dialog and fullscreen, and the failures it can switch on. Check that each renders what
97
- you chose, with nothing unexpected in its message log. Without a browser tool, ask the author to
98
- do the same, and say what to look for.
99
- - With a backend, point it at the studio with the env values it prints, and check it verifies
196
+ made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
197
+ - **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
198
+ use the one already running: it's probably the author's, and its saved settings, secrets and
199
+ exchange failures are shared by everyone using it.
200
+ - **With a browser tool, reach every state and mode from step 2**: each record type and no
201
+ record, no viewer, `null` and saved settings, preview and config on its settings page, the
202
+ narrowest and the widest slot (`width=320` and `width=full`), the dialog and fullscreen, and
203
+ the failures it can switch on. Check each renders what you chose,
204
+ with nothing unexpected in its message log.
205
+ - **Set each state up from the address** rather than by clicking: one URL per state, e.g.
206
+ `http://localhost:5190/#?type=none&viewer=&display=dialog&token=forbidden`, or
207
+ `#settings?preferences=en-US` for the settings page. The studio's README
208
+ (`node_modules/@livespace/plugin-studio/README.md`) lists the params, and the log notes what
209
+ it set and what it ignored.
210
+ - **Saved settings go through the settings page**, never the address: fill in its form and
211
+ Save, or Forget for `null`.
212
+ - **Read the log from the browser console**, not the page: each entry is a line prefixed
213
+ `[studio]`. The studio's notes are warnings, so read those first: anything it refused or
214
+ dropped is a mistake to fix. The messages to and from the plugin are `debug` (with the
215
+ Playwright MCP, `browser_console_messages` with `level: "debug"`); read them when something
216
+ looks wrong.
217
+ - Setting up from the address and the console log need `@livespace/plugin-studio` 0.2 or
218
+ later.
219
+ - **Without a browser tool**, ask the author to do the same, and say what to look for.
220
+ - With a backend, point it at your studio with the env values it prints, and check it verifies
100
221
  the plugin's token and reads its secrets.
101
222
  - For a catalog plugin, `manifest check` passes.
102
223
 
103
- Then tell the author:
224
+ ## 5. Host it
225
+
226
+ A developer deploying their own way needs only what any host must give the plugin (_Hosting your
227
+ plugin_ in `llms.txt`): say it, and leave the how to them. Otherwise deploy to the host from step
228
+ 1, as `hosts.md` describes for it, under these rules on any host:
104
229
 
105
- - **Where it can be hosted**: the rules in _Rules that will bite you_ (HTTPS, an allowed domain,
106
- never Livespace's own origin).
230
+ - **Nothing that could cost money without a yes.** Before creating an account, a project or a
231
+ service, say in a sentence what you'll create and that it's on the free plan, then wait. Never
232
+ enter payment details. If the host asks for a card, stop and explain why.
233
+ - **The address is permanent.** Confirm the plugin's name in it with the author before the first
234
+ deploy: support allows that exact address, and admins add the plugin by it.
235
+ - **Check what you can before the author signs up for anything:** build, and any dry run the host
236
+ offers.
237
+ - **Whose account.** Suggest the company's account at that host, or a shared company email, so
238
+ the plugin outlives whoever made it. A personal account is the author's call, once they've heard
239
+ that risk.
240
+ - **Secrets go in by hand.** The author types each secret into the host's dashboard; name the page
241
+ and the field. Never ask them to paste one into the chat.
242
+ - **The author does what only a person can** (signing up, logging in through the browser): one
243
+ step at a time, saying what they'll see. Run everything else yourself.
244
+
245
+ Then check the deployed page as in step 4, at its new address (start the studio with
246
+ `--url <address>`), and tell the author:
247
+
248
+ - **The address**, and that Livespace support must allow it for their account before it shows.
249
+ - **Who adds it**: an admin of the account, by its address, in Account settings → Plugins, after
250
+ asking support to allow it. If that isn't the author, write them a short note to forward to the
251
+ admin, with the address and those two steps.
107
252
  - **What happens to the keys**, if it has any: where the private halves are, what to do with them,
108
253
  and where the public ones must be published.
109
254
  - **That config is not secret storage**, if the plugin has any settings.
255
+
256
+ ### A catalog plugin: listing, testing, review
257
+
258
+ Livespace lists a catalog plugin, not this skill: give whoever lists it the deployed address and
259
+ `plugin-manifest.json`, and say so to the author.
260
+
261
+ - **A new entry is hidden from customers.** An internal Livespace instance lists every entry, and
262
+ that's where it's tested. Walk the tester through this there, and fix, bump `version` and
263
+ redeploy for each failure:
264
+ - the card and details show the right name, texts and images, in English, Polish and Romanian;
265
+ - it can only be placed on the types it declares;
266
+ - on a real record it shows the record's data, and updates without a reload when it's edited;
267
+ - its settings form appears (an empty one if it has none), and its preview renders;
268
+ - the narrowest and the widest slot both read well.
269
+ - **Before review:** real images, and the Polish and Romanian texts reviewed by a native speaker.
270
+ - **Publishing it to every account is a reviewer's decision, made in Livespace.** Prepare a review
271
+ note for the author to hand over: what it does and where it appears, the checklist with its
272
+ results, how it uses the Livespace API, its settings, and open issues. Never say it's published
273
+ when it has only been deployed or listed.
@@ -0,0 +1,132 @@
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
+ 1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
56
+
57
+ ```jsonc
58
+ {
59
+ "name": "my-plugin", // the first part of the address
60
+ "compatibility_date": "2026-11-01",
61
+ "assets": { "directory": "./dist" }
62
+ }
63
+ ```
64
+
65
+ 2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
66
+ up.
67
+ 3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time
68
+ (a few minutes). If no browser opens, or they're on another machine, run
69
+ `wrangler login --browser=false` and give them the link it prints. Then `wrangler whoami` to
70
+ confirm.
71
+ 4. `wrangler deploy`. The first deploy creates the Worker, which the author's yes to the account
72
+ covers; later ones update it. Wrangler prints the address.
73
+
74
+ **Don't use `wrangler dev` under Bun:** it answers every request with 503 (a Bun bug that Wrangler
75
+ names). Preview with the project's dev server and Plugin Studio, as step 4 says.
76
+
77
+ ### The key set's headers
78
+
79
+ For a plugin added by URL with secret fields, put `_headers` in `public/`, which the build copies
80
+ into `dist/`:
81
+
82
+ ```
83
+ /.well-known/livespace/jwks.json
84
+ Access-Control-Allow-Origin: *
85
+ ```
86
+
87
+ Cloudflare serves `.well-known/`, and `jwks.json` as `application/json`. `_headers` itself isn't
88
+ served.
89
+
90
+ ### A backend
91
+
92
+ A Worker's backend is one `fetch` handler; the static files are served without running it.
93
+
94
+ ```jsonc
95
+ {
96
+ "name": "my-plugin",
97
+ "main": "src/worker.ts",
98
+ "compatibility_date": "2026-11-01",
99
+ "assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": ["/api/*"] }
100
+ }
101
+ ```
102
+
103
+ ```ts
104
+ export default {
105
+ async fetch(request: Request, env: { ASSETS: Fetcher; API_KEY: string }) {
106
+ const url = new URL(request.url)
107
+ if (url.pathname.startsWith("/api/")) {
108
+ // Verify the plugin's token first: _Your backend_ in llms.txt.
109
+ // env.API_KEY is the secret the author typed in.
110
+ }
111
+ return env.ASSETS.fetch(request)
112
+ },
113
+ }
114
+ ```
115
+
116
+ `_headers` doesn't apply to what the handler returns: set those headers in code.
117
+
118
+ **Secrets:** the author adds each one in the dashboard: **Workers & Pages** → the plugin's
119
+ Worker → **Settings** → **Variables and Secrets** → **Add**, type **Secret**, the name you give
120
+ them (for example `API_KEY`), the value, then **Deploy**. The handler reads it as
121
+ `env.API_KEY`.
122
+ Deploy the Worker once before this, so it exists.
123
+
124
+ ### Not covered
125
+
126
+ No EU-only location for a Worker or its files: requests run wherever is nearest the visitor.
127
+
128
+ ## Other hosts
129
+
130
+ Authors may already use another: Netlify, Vercel, GitHub Pages, or, for a backend, Fly.io or
131
+ Render. Nothing here has been checked for them. Use the host's own docs for each command, and hold
132
+ it to the same rules: what _Hosting your plugin_ requires, and step 5's.