@livespace/plugin-cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -85,6 +85,10 @@ export function createPrompter({ flags, yes = false, backend, }) {
85
85
  if (chosen.length === 0 && q.required !== false) {
86
86
  wrong(q.name, "needs at least one value");
87
87
  }
88
+ const why = q.validate?.(chosen);
89
+ if (why !== undefined) {
90
+ wrong(q.name, why);
91
+ }
88
92
  return chosen;
89
93
  }
90
94
  if (backend) {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@livespace/plugin-cli",
3
- "version": "0.2.0",
4
- "description": "Sets up a Livespace plugin's catalog manifest, its key pairs included.",
3
+ "version": "0.3.0",
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",
7
7
  "type": "module",
@@ -9,7 +9,9 @@
9
9
  "livespace-plugin": "dist/cli.js"
10
10
  },
11
11
  "files": [
12
- "dist"
12
+ "dist",
13
+ "skill",
14
+ "templates"
13
15
  ],
14
16
  "engines": {
15
17
  "node": ">=20.12"
@@ -34,7 +36,8 @@
34
36
  "lint:types": "tsc --noEmit",
35
37
  "prepublishOnly": "yarn test",
36
38
  "test": "yarn build && vitest run --watch false",
37
- "test:watch": "vitest"
39
+ "test:watch": "vitest",
40
+ "test:e2e": "yarn build && yarn workspace @livespace/plugin-sdk build && yarn workspace @livespace/plugin-studio build && vitest run --watch false -c vitest.e2e.config.mts"
38
41
  },
39
42
  "dependencies": {
40
43
  "@clack/prompts": "1.8.1"
@@ -0,0 +1,109 @@
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 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: "{{cliVersion}}"
6
+ sdk-range: "{{sdkRange}}"
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
+ ## 0. Read `llms.txt`
15
+
16
+ Before writing or changing plugin code, read the SDK's documentation as one file:
17
+
18
+ 1. `node_modules/@livespace/plugin-sdk/dist/llms.txt`, which matches the installed SDK;
19
+ 2. if that's missing, `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@{{sdkMajor}}/dist/llms.txt`.
20
+
21
+ Read its opening part (_Livespace plugins_, down to _Rules that will bite you_) whole, then each
22
+ section the task touches. Look API detail up there every time rather than recalling it: it is the
23
+ source of truth, and it wins wherever it and this skill differ. Done when you can name the sections
24
+ the task touches and have read them.
25
+
26
+ ## 1. Scope it
27
+
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.
30
+
31
+ - **What it shows or does.** Push for one sentence.
32
+ - **Which record types**: deal, company, person, space.
33
+ - **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:
36
+ - **Single-tenant**: the backend serves one Livespace account, the author's own. Always added
37
+ by URL.
38
+ - **Multi-tenant**: one backend serves many accounts. Then ask whether it's a **catalog**
39
+ plugin (listed, with a `plugin-manifest.json`) or **added by URL**.
40
+
41
+ Explain why the answer matters, from _Do you need keys?_ in `llms.txt`: an admin's browser
42
+ encrypts a secret field's value with the plugin's public key, so only its backend reads it, and
43
+ how the plugin reaches an account decides where Livespace finds that key. The author decides
44
+ with that in hand.
45
+ - **Secrets**, any credential the backend uses. Each lives in exactly one of two homes:
46
+ - Single-tenant: offer both. **The backend's environment** needs no keys, and changing the
47
+ secret means a redeploy. **A secret field** (`addSecretInput`) lets the account's admins set
48
+ and replace it in Livespace's settings, and needs keys.
49
+ - Multi-tenant with per-account secrets: a secret field, so keys.
50
+
51
+ A secret goes in one of those homes, never in an ordinary config field. If the author wants a
52
+ config field to avoid keys, explain that a config field's value reaches the browser of every
53
+ user who opens the plugin, so every coworker (or every customer's user) can read it, then offer
54
+ the two homes again.
55
+ - **Settings an admin changes**: a config form. Livespace renders, validates and stores it.
56
+
57
+ Build in the project as it stands: its stack, build and layout are the author's.
58
+
59
+ ## 2. Build every state
60
+
61
+ A plugin renders each of these deliberately, never as a blank or a stack trace:
62
+
63
+ 1. **Loading**: before `ready`.
64
+ 2. **Unconfigured**: `config` is `null` and the plugin needs settings. Tell the admin what to set.
65
+ 3. **Empty**: loaded, nothing to show.
66
+ 4. **Failed**: any call that can fail. Say what failed and offer a retry where `llms.txt` says one
67
+ helps.
68
+ 5. **Loaded**: the real thing. Build it last.
69
+
70
+ And each **mode** from _The three modes_: `view`, `preview` (no record, so a mock view), and
71
+ `config` (answer, even with no settings). Done when every state and mode is reachable and renders
72
+ something you chose.
73
+
74
+ ## 3. Manifest and keys, through the CLI
75
+
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.
79
+
80
+ - **Catalog plugin**: `manifest init`, then `manifest check` until it passes. The manifest's `id`
81
+ is the plugin's permanent catalog key, and `manifest init` never overwrites a manifest: confirm
82
+ the `id` with the author before running it.
83
+ - **Added by URL, with keys**: `keys init` with no manifest writes the key set to `jwks.json`. The
84
+ plugin's origin must serve it at `/.well-known/livespace/jwks.json`, following the hosting rules
85
+ under _Your plugin's keys_.
86
+ - **Private keys** land in `keys/<kid>.pem`, which the CLI gitignores. Leave them on disk unread.
87
+ Tell the author to move them into the backend's secret storage and to back up the encryption
88
+ key: if it's lost, every account's admins re-enter their secrets.
89
+
90
+ ## 4. Check it and hand it over
91
+
92
+ - Open the page outside Livespace: it shows its loading state and the console is clean.
93
+ - 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
100
+ the plugin's token and reads its secrets.
101
+ - For a catalog plugin, `manifest check` passes.
102
+
103
+ Then tell the author:
104
+
105
+ - **Where it can be hosted**: the rules in _Rules that will bite you_ (HTTPS, an allowed domain,
106
+ never Livespace's own origin).
107
+ - **What happens to the keys**, if it has any: where the private halves are, what to do with them,
108
+ and where the public ones must be published.
109
+ - **That config is not secret storage**, if the plugin has any settings.
@@ -0,0 +1,20 @@
1
+ // Bundles index.html into dist/, then copies public/ in as it is: Bun's bundler doesn't, and
2
+ // public/.well-known/livespace/jwks.json has to be published at /.well-known/livespace/jwks.json.
3
+ import { cpSync, existsSync, rmSync } from "node:fs"
4
+
5
+ rmSync("dist", { recursive: true, force: true })
6
+ const result = await Bun.build({
7
+ entrypoints: ["./index.html"],
8
+ outdir: "./dist",
9
+ minify: true,
10
+ })
11
+ if (!result.success) {
12
+ for (const log of result.logs) {
13
+ console.error(log)
14
+ }
15
+ process.exit(1)
16
+ }
17
+ if (existsSync("public")) {
18
+ cpSync("public", "dist", { recursive: true })
19
+ }
20
+ console.log(`Built ${result.outputs.length} files into dist/`)
@@ -0,0 +1,23 @@
1
+ // Bun's HTML dev server, plus public/: on its own, Bun answers every unknown path with index.html,
2
+ // so /.well-known/livespace/jwks.json would come back as HTML.
3
+ import { join, normalize } from "node:path"
4
+ import index from "./index.html"
5
+
6
+ const PUBLIC = join(import.meta.dir, "public")
7
+
8
+ const server = Bun.serve({
9
+ port: Number(process.env.PORT ?? 3000),
10
+ development: true,
11
+ routes: { "/": index },
12
+ async fetch(request) {
13
+ const path = normalize(decodeURIComponent(new URL(request.url).pathname))
14
+ const file = Bun.file(join(PUBLIC, path))
15
+ // Livespace reads public/.well-known/livespace/jwks.json from another origin, so like the
16
+ // hosting must, the dev server lets any origin read what's in public/.
17
+ return (await file.exists())
18
+ ? new Response(file, { headers: { "Access-Control-Allow-Origin": "*" } })
19
+ : new Response("Not found", { status: 404 })
20
+ },
21
+ })
22
+
23
+ console.log(`Serving the plugin at ${server.url}`)
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "{{name}}",
3
+ "private": true,
4
+ "version": "0.1.0",
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "bun dev.ts",
8
+ "studio": "livespace-plugin-studio",
9
+ "typecheck": "tsc && tsc -p tsconfig.tools.json",
10
+ "build": "tsc && tsc -p tsconfig.tools.json && bun build.ts"
11
+ },
12
+ "dependencies": {
13
+ "@livespace/plugin-sdk": "{{sdkRange}}"
14
+ },
15
+ "devDependencies": {
16
+ "@livespace/plugin-studio": "{{studioRange}}",
17
+ "@types/bun": "^1.3.0",
18
+ "typescript": "^5.9.0"
19
+ }
20
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": {
4
+ "lib": ["ESNext"],
5
+ "types": ["bun"]
6
+ },
7
+ "include": ["dev.ts", "build.ts"]
8
+ }
@@ -0,0 +1,23 @@
1
+ # {{name}}
2
+
3
+ A [Livespace plugin](https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@{{sdkMajor}}/dist/docs/index.md):
4
+ a web page Livespace embeds on a deal, company, person or space profile.
5
+
6
+ ```sh
7
+ {{run}} dev # serve it locally; opened directly, it shows its loading state
8
+ {{run}} studio # with dev running: Plugin Studio, embedding it as Livespace does
9
+ {{run}} typecheck # dev doesn't check types; this does, for src/ and the build's own files
10
+ {{run}} build # check types, then build into dist/, to host on your own HTTPS origin
11
+ ```
12
+
13
+ - `src/main.ts` renders the plugin. It imports the SDK first, so Livespace hears `ready` early.
14
+ - `src/config.ts` types the plugin's settings.
15
+ - `tsconfig.json` checks `src/`, which runs in the browser: DOM and the SDK only.
16
+ `tsconfig.tools.json` checks the build's own files, which run in the build tool.
17
+ - `public/` is served and built at the site root as it is. A plugin added by URL that needs keys
18
+ publishes them there: `npx @livespace/plugin-cli keys init` writes
19
+ `public/.well-known/livespace/jwks.json`, served at `/.well-known/livespace/jwks.json`.
20
+ - `keys/` holds private keys, if the plugin has any. It's gitignored: keep it that way.
21
+
22
+ The SDK's documentation, as one file for you or your coding agent:
23
+ `node_modules/@livespace/plugin-sdk/dist/llms.txt`.
@@ -0,0 +1,4 @@
1
+ node_modules/
2
+ dist/
3
+ # Private key halves (`livespace-plugin keys init`): never commit them.
4
+ keys/
@@ -0,0 +1,13 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>{{name}}</title>
7
+ <!-- In <head>, so the SDK says `ready` as early as possible: Livespace sends nothing before. -->
8
+ <script type="module" src="./src/main.ts"></script>
9
+ </head>
10
+ <body>
11
+ <main id="app" aria-live="polite"></main>
12
+ </body>
13
+ </html>
@@ -0,0 +1,10 @@
1
+ // The shape of this plugin's settings, for LsPlugin.config and the "ready" and "config" events.
2
+ // Keep every property optional: Livespace delivers the config as it was stored, so a field added
3
+ // since the admin last saved is missing. See "Typing your config" in the SDK's llms.txt.
4
+ declare global {
5
+ interface LsPluginConfig {
6
+ // accountId?: string
7
+ }
8
+ }
9
+
10
+ export {}
@@ -0,0 +1,52 @@
1
+ // The SDK first: importing it sends `ready`, and Livespace sends the plugin nothing until then.
2
+ import LsPlugin from "@livespace/plugin-sdk/ls-plugin.mjs"
3
+ import "./style.css"
4
+
5
+ // Settings an admin gives the plugin: declare them with LsPlugin.createConfigForm() here, at the
6
+ // top level, and type them in config.ts. See "Configuration forms" in the SDK's llms.txt.
7
+
8
+ type Config = NonNullable<typeof LsPlugin.config>
9
+
10
+ /** The settings the plugin can't work without. Until each has a value, it asks for them. */
11
+ const REQUIRED_SETTINGS: (keyof Config)[] = []
12
+
13
+ type State = "loading" | "unconfigured" | "empty" | "loaded" | "failed"
14
+
15
+ const app = document.querySelector<HTMLElement>("#app")
16
+
17
+ function show(state: State, text: string): void {
18
+ if (app) {
19
+ app.dataset.state = state
20
+ app.textContent = text
21
+ }
22
+ }
23
+
24
+ function render(): void {
25
+ const { context, config } = LsPlugin
26
+ // `undefined` is "not delivered yet". Outside Livespace nothing ever is.
27
+ if (context === undefined || config === undefined) {
28
+ return show("loading", "Loading…")
29
+ }
30
+ if (REQUIRED_SETTINGS.some((key) => config?.[key] === undefined)) {
31
+ return show(
32
+ "unconfigured",
33
+ "Ask an admin to finish setting up this plugin.",
34
+ )
35
+ }
36
+ // `null` is preview mode: an admin is configuring the plugin, and there is no record.
37
+ if (context === null) {
38
+ return show("loaded", "Preview: a record's details appear here.")
39
+ }
40
+ // Exactly one of these is present; its key says which kind of record it is.
41
+ const record =
42
+ context.deal ?? context.company ?? context.person ?? context.space
43
+ if (record === undefined) {
44
+ return show("empty", "Nothing to show for this record.")
45
+ }
46
+ show("loaded", record.name)
47
+ }
48
+
49
+ render()
50
+ LsPlugin.on("ready", render)
51
+ LsPlugin.on("context", render)
52
+ LsPlugin.on("config", render)
@@ -0,0 +1,21 @@
1
+ /* Livespace's design tokens, so the plugin looks like part of the product. See "Styling" in the
2
+ SDK's llms.txt for what exists. */
3
+ @import "@livespace/plugin-sdk/ls-tokens.css";
4
+
5
+ body {
6
+ margin: 0;
7
+ padding: var(--spacing-md);
8
+ font-family: var(--font-sans);
9
+ color: var(--color-gray-900);
10
+ background: var(--color-white);
11
+ }
12
+
13
+ #app[data-state="loading"],
14
+ #app[data-state="unconfigured"],
15
+ #app[data-state="empty"] {
16
+ color: var(--color-gray-500);
17
+ }
18
+
19
+ #app[data-state="failed"] {
20
+ color: var(--color-destructive);
21
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "module": "ESNext",
5
+ "moduleResolution": "bundler",
6
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
7
+ "types": [],
8
+ "strict": true,
9
+ "noEmit": true,
10
+ "isolatedModules": true,
11
+ "skipLibCheck": true,
12
+ "noUncheckedIndexedAccess": true
13
+ },
14
+ "include": ["src"]
15
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "{{name}}",
3
+ "private": true,
4
+ "version": "0.1.0",
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "vite",
8
+ "studio": "livespace-plugin-studio",
9
+ "typecheck": "tsc && tsc -p tsconfig.tools.json",
10
+ "build": "tsc && tsc -p tsconfig.tools.json && vite build",
11
+ "preview": "vite preview"
12
+ },
13
+ "dependencies": {
14
+ "@livespace/plugin-sdk": "{{sdkRange}}"
15
+ },
16
+ "devDependencies": {
17
+ "@livespace/plugin-studio": "{{studioRange}}",
18
+ "typescript": "^5.9.0",
19
+ "vite": "^7.1.0"
20
+ }
21
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": {
4
+ "lib": ["ESNext"],
5
+ "types": []
6
+ },
7
+ "include": ["vite.config.ts"]
8
+ }
@@ -0,0 +1,6 @@
1
+ import { defineConfig } from "vite"
2
+
3
+ export default defineConfig({
4
+ // Relative asset URLs, so the built plugin works from any path on its origin.
5
+ base: "./",
6
+ })