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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -113,11 +113,12 @@ npx @livespace/plugin-cli manifest init --yes --json \
113
113
  goes alone, never with a type: `any,deal` is refused.
114
114
 
115
115
  Without a terminal, a missing answer is never waited for: the command exits 1 and lists every flag
116
- it still needs. See `--help` for them all.
116
+ it still needs. `--help` lists the commands, and `<command> --help` a command's flags.
117
117
 
118
118
  ## Requirements
119
119
 
120
- Node 20.12 or later.
120
+ Node 20.12 or later, or Bun. Under Bun, run it with `bunx --bun @livespace/plugin-cli`: `--bun`
121
+ keeps it on Bun when an older Node is also installed. `create` run that way picks the Bun template.
121
122
 
122
123
  ## License
123
124
 
package/dist/cli.js CHANGED
@@ -11,124 +11,16 @@ import { resolve } from "node:path";
11
11
  import { parseArgs } from "node:util";
12
12
  import { clientId } from "./commands/client-id.js";
13
13
  import { UsageError } from "./commands/context.js";
14
- import { DO_YOU_NEED_KEYS, create, spawnExec } from "./commands/create.js";
14
+ import { create, spawnExec } from "./commands/create.js";
15
15
  import { keysInit, keysJwks, keysRetire, keysRotate } from "./commands/keys.js";
16
16
  import { manifestCheck, manifestInit, manifestPublished, manifestSet, } from "./commands/manifest.js";
17
17
  import { skillInstall } from "./commands/skill.js";
18
- import { LOCALES } from "./manifest/schema.js";
18
+ import { BOOLEAN_FLAGS, STRING_FLAGS, refuseForeignFlags } from "./flags.js";
19
+ import { commandHelp, groupHelp, overview } from "./help.js";
19
20
  import { Cancelled, clackBackend } from "./ui/clack.js";
20
21
  import { clackOutput, jsonOutput, plainOutput } from "./ui/output.js";
21
22
  import { MissingAnswers, createPrompter } from "./ui/prompter.js";
22
23
  const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
23
- const TEXT_FLAGS = LOCALES.flatMap((lang) => ["name", "description", "details"].map((field) => `${field}-${lang}`));
24
- const STRING_FLAGS = [
25
- "dir",
26
- "id",
27
- "version",
28
- "origin",
29
- "object-types",
30
- "languages",
31
- "categories",
32
- "other-categories",
33
- "icon-url",
34
- "illustration-url",
35
- "accent-color",
36
- "info-url",
37
- "additional-images",
38
- "secret-keys",
39
- "use",
40
- "bits",
41
- "out",
42
- "harness",
43
- "template",
44
- "pm",
45
- "tenancy",
46
- "distribution",
47
- ...TEXT_FLAGS,
48
- ];
49
- const BOOLEAN_FLAGS = [
50
- "yes",
51
- "json",
52
- "help",
53
- "secrets",
54
- "no-secrets",
55
- "keys",
56
- "no-keys",
57
- "gitignore",
58
- "no-gitignore",
59
- "force",
60
- "no-install",
61
- "skill",
62
- "no-skill",
63
- ];
64
- const HELP = `livespace-plugin ${CLI_VERSION} — start a Livespace plugin, and set up its manifest and keys
65
-
66
- Usage: npx @livespace/plugin-cli <command> [flags]
67
-
68
- Commands:
69
- create [dir] Start a plugin project: a Vite or Bun template, git init,
70
- the install, then the manifest or keys it needs, and
71
- the agent skill. Refuses a non-empty dir unless --force.
72
- manifest init Create plugin-manifest.json, asking for each field.
73
- Defaults come from package.json when there is one.
74
- manifest set <field> [value]
75
- Change one field (version, origin, object-types,
76
- name-<lang>, description-<lang>, details-<lang>,
77
- categories, icon-url, illustration-url, accent-color,
78
- info-url, additional-images, secret-keys).
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.
86
- keys init [--use sig|enc|both] [--out <path>]
87
- Create the key pairs: a signing key, and an encryption
88
- key when there are secretKeys. Private halves go to
89
- keys/<kid>.pem (0600, gitignored); never printed.
90
- Public halves go in the manifest; with no manifest (a
91
- plugin added by URL), in [public/].well-known/livespace/
92
- jwks.json, both keys by default.
93
- keys rotate --use sig|enc
94
- Add a key for a rotation (at most two per use).
95
- keys retire <kid> Remove a key from the manifest, or the jwks.json.
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.
99
- client-id Print plugin:<id>, what the backend checks "aud" against.
100
- skill install Copy the livespace-plugin agent skill into the project,
101
- into .claude/skills and/or .agents/skills, whichever
102
- the chosen agents read. Replaces a copy that's there:
103
- run it again to take a newer CLI's skill.
104
-
105
- To try a plugin locally, embedded as Livespace embeds it, run Plugin Studio: the studio
106
- script in a project create made, or npx @livespace/plugin-studio.
107
-
108
- Answers as flags (for scripts and agents; without a terminal, a missing one is an error):
109
- create --template vite|bun, --pm npm|pnpm|yarn|bun, --no-install, --force,
110
- --tenancy single|multi, --distribution catalog|url,
111
- --secrets | --no-secrets, --skill | --no-skill,
112
- then manifest init's and skill install's. --tenancy, --distribution
113
- and --secrets have no default: they decide the keys. Why:
114
- ${DO_YOU_NEED_KEYS}
115
- manifest init --id, --version, --origin, --object-types deal,company|any,
116
- --languages en,pl, --name-<lang>, --description-<lang>,
117
- --categories "Deal,Finance", --icon-url, --illustration-url,
118
- --accent-color, --info-url, --secrets | --no-secrets,
119
- --secret-keys apiToken,webhookSecret, --keys | --no-keys
120
- (<lang>: ${LOCALES.join(", ")})
121
- keys --bits 2048
122
- skill install --harness claude-code,codex,cursor,copilot,gemini,other,
123
- --gitignore | --no-gitignore
124
-
125
- Other flags:
126
- --dir <path> The plugin project (default: the current directory).
127
- --yes, -y Take the defaults instead of asking.
128
- --json Print only a JSON result.
129
- --help, -h This text.
130
- --version The CLI's version, given alone. With a command, the manifest's.
131
- `;
132
24
  async function run(argv) {
133
25
  // Alone, --version asks for the CLI's; with a command, it's the manifest's version flag.
134
26
  if (argv.length === 1 && argv[0] === "--version") {
@@ -146,11 +38,28 @@ async function run(argv) {
146
38
  },
147
39
  });
148
40
  const flags = values;
149
- const [group, command, arg, value] = positionals;
150
- if (flags.help || group === undefined || group === "help") {
151
- console.log(HELP);
41
+ // `help <command>` is `<command> --help`.
42
+ const asked = positionals[0] === "help" || flags.help === true;
43
+ const [group, command, arg, value] = positionals[0] === "help" ? positionals.slice(1) : positionals;
44
+ const name = group === "create" || group === "client-id"
45
+ ? group
46
+ : `${group} ${command ?? ""}`.trim();
47
+ if (group === undefined) {
48
+ console.log(overview(CLI_VERSION));
152
49
  return 0;
153
50
  }
51
+ if (asked) {
52
+ const help = commandHelp(name) ??
53
+ (command === undefined ? groupHelp(group) : undefined);
54
+ if (help === undefined) {
55
+ throw new UsageError(`unknown command "${name}" — see --help`);
56
+ }
57
+ console.log(help);
58
+ return 0;
59
+ }
60
+ // A flag another command takes is refused, not ignored (044). An unknown command is refused
61
+ // below.
62
+ refuseForeignFlags(name, Object.keys(values));
154
63
  // `manifest set <field> <value>` is the same as `manifest set <field> --<field> <value>`.
155
64
  if (group === "manifest" &&
156
65
  command === "set" &&
package/dist/flags.js ADDED
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Which flags each command takes (044). The CLI parses against all of them, so a typo is still an
3
+ * unknown flag, then refuses one the command doesn't take: an agent guessing at flags hears that
4
+ * it guessed wrong, instead of a flag being ignored without a word.
5
+ */
6
+ import { UsageError } from "./commands/context.js";
7
+ import { LOCALES } from "./manifest/schema.js";
8
+ /** Taken by every command. */
9
+ export const GLOBAL_FLAGS = ["dir", "yes", "json", "help"];
10
+ const TEXT_FLAGS = LOCALES.flatMap((lang) => ["name", "description", "details"].map((field) => `${field}-${lang}`));
11
+ /** The manifest's fields that `manifest set` changes and `manifest init` asks for. */
12
+ const MANIFEST_FIELDS = [
13
+ "version",
14
+ "origin",
15
+ "object-types",
16
+ "categories",
17
+ "other-categories",
18
+ "icon-url",
19
+ "illustration-url",
20
+ "accent-color",
21
+ "info-url",
22
+ "additional-images",
23
+ "secret-keys",
24
+ ...TEXT_FLAGS,
25
+ ];
26
+ const MANIFEST_INIT = [
27
+ "id",
28
+ "languages",
29
+ ...MANIFEST_FIELDS,
30
+ "secrets",
31
+ "no-secrets",
32
+ "keys",
33
+ "no-keys",
34
+ "bits",
35
+ ];
36
+ const KEYS_INIT = ["use", "out", "bits"];
37
+ const SKILL_INSTALL = ["harness", "gitignore", "no-gitignore"];
38
+ /** Each command's own flags, besides the global ones. */
39
+ export const COMMAND_FLAGS = {
40
+ // create runs manifest init, keys init and skill install, so it takes theirs.
41
+ create: Array.from(new Set([
42
+ "template",
43
+ "pm",
44
+ "no-install",
45
+ "force",
46
+ "tenancy",
47
+ "distribution",
48
+ "skill",
49
+ "no-skill",
50
+ ...MANIFEST_INIT,
51
+ ...KEYS_INIT,
52
+ ...SKILL_INSTALL,
53
+ ])),
54
+ "manifest init": MANIFEST_INIT,
55
+ "manifest set": MANIFEST_FIELDS,
56
+ "manifest check": ["origin"],
57
+ "manifest published": [],
58
+ "keys init": KEYS_INIT,
59
+ "keys rotate": ["use", "bits"],
60
+ "keys retire": [],
61
+ "keys jwks": ["out"],
62
+ "client-id": [],
63
+ "skill install": SKILL_INSTALL,
64
+ };
65
+ /** Every flag any command takes, typed as the parser needs them. */
66
+ export const BOOLEAN_FLAGS = [
67
+ ...GLOBAL_FLAGS.filter((flag) => flag !== "dir"),
68
+ "secrets",
69
+ "no-secrets",
70
+ "keys",
71
+ "no-keys",
72
+ "gitignore",
73
+ "no-gitignore",
74
+ "force",
75
+ "no-install",
76
+ "skill",
77
+ "no-skill",
78
+ ];
79
+ export const STRING_FLAGS = Array.from(new Set([GLOBAL_FLAGS, ...Object.values(COMMAND_FLAGS)]
80
+ .flat()
81
+ .filter((flag) => !BOOLEAN_FLAGS.includes(flag))));
82
+ const listed = (flags) => flags.length === 1
83
+ ? flags[0]
84
+ : `${flags.slice(0, -1).join(", ")} and ${flags.at(-1)}`;
85
+ /**
86
+ * Throws when a flag given isn't one `command` takes, naming the ones it does. An unknown command
87
+ * passes: the caller says it's unknown, which is the more useful error.
88
+ */
89
+ export function refuseForeignFlags(command, given) {
90
+ const own = COMMAND_FLAGS[command];
91
+ if (own === undefined) {
92
+ return;
93
+ }
94
+ const foreign = given.filter((flag) => !own.includes(flag) && !GLOBAL_FLAGS.includes(flag));
95
+ if (foreign.length === 0) {
96
+ return;
97
+ }
98
+ const named = listed(foreign.map((flag) => `--${flag}`));
99
+ const globals = listed(GLOBAL_FLAGS.map((flag) => `--${flag}`));
100
+ const takes = own.length === 0
101
+ ? `It takes only ${globals}.`
102
+ : `It takes ${own.map((flag) => `--${flag}`).join(", ")}, plus ${globals}.`;
103
+ throw new UsageError(`${named} ${foreign.length === 1 ? "isn't a flag" : "aren't flags"} of ${command}. ${takes}`);
104
+ }
package/dist/help.js ADDED
@@ -0,0 +1,277 @@
1
+ /**
2
+ * The CLI's help (044): `--help` lists the commands, `<group> --help` a group's, and
3
+ * `<command> --help` one command with each of its flags. One table feeds all three, and a test
4
+ * checks that each command's entry names every flag `flags.ts` gives it.
5
+ */
6
+ import { DO_YOU_NEED_KEYS } from "./commands/create.js";
7
+ import { LOCALES } from "./manifest/schema.js";
8
+ const RUN = "npx @livespace/plugin-cli";
9
+ const LANG = `<lang>: ${LOCALES.join(", ")}`;
10
+ /** The manifest's fields, as `manifest init` asks for them and `manifest set` changes them. */
11
+ const MANIFEST_FIELDS = [
12
+ ["--version <x.y.z>", "Its version. Bump it on every change you publish."],
13
+ ["--origin <url>", "The https origin it's served from: its iframeOrigin."],
14
+ [
15
+ "--object-types <types>",
16
+ "Where it may go: deal,company,person,space, or any alone (every type, and the apps menu with no record).",
17
+ ],
18
+ ["--name-<lang> <text>", `Its name in the catalog (${LANG}).`],
19
+ ["--description-<lang> <text>", "Its card line in the catalog."],
20
+ ["--details-<lang> <text>", "Its about page, in Markdown."],
21
+ [
22
+ "--categories <list>",
23
+ 'Catalog categories, comma-separated: "Deal,Finance".',
24
+ ],
25
+ ["--other-categories <list>", "Categories not on the list, in English."],
26
+ ["--icon-url <url>", "Its icon, .svg or .png (64×64)."],
27
+ [
28
+ "--illustration-url <url>",
29
+ "Its card illustration, .svg or .png (272×145).",
30
+ ],
31
+ ["--accent-color <colour>", "Its accent colour."],
32
+ ["--info-url <url>", "A page about it."],
33
+ ["--additional-images <urls>", "Screenshot URLs, comma-separated."],
34
+ [
35
+ "--secret-keys <list>",
36
+ "The keys of its config form's Secret Fields: apiToken,webhookSecret.",
37
+ ],
38
+ ];
39
+ const OWN_KEYS = [
40
+ [
41
+ "--use sig|enc|both",
42
+ "Which key pairs: by default a signing key, plus an encryption key when there are secretKeys; both with no manifest.",
43
+ ],
44
+ ["--out <path>", "Where the jwks.json goes, with no manifest."],
45
+ ["--bits <n>", "The RSA key size (default and minimum 2048)."],
46
+ ];
47
+ const SKILL_INSTALL = [
48
+ [
49
+ "--harness <list>",
50
+ "The coding agents that should see it: claude-code, codex, cursor, copilot, gemini, other (default: claude-code).",
51
+ ],
52
+ [
53
+ "--gitignore | --no-gitignore",
54
+ "Keep it out of git, or commit it so everyone on the project gets it (the default).",
55
+ ],
56
+ ];
57
+ export const COMMAND_HELP = {
58
+ create: {
59
+ usage: "[dir]",
60
+ summary: "Start a plugin project: a Vite or Bun template, git init, the install, then the manifest or keys it needs, and the agent skill. Refuses a non-empty dir unless --force.",
61
+ flags: [
62
+ ["--template vite|bun", "The build tool."],
63
+ [
64
+ "--pm npm|pnpm|yarn|bun",
65
+ "The package manager (default: the one running it).",
66
+ ],
67
+ ["--no-install", "Skip the install."],
68
+ ["--force", "Write the template into a directory that isn't empty."],
69
+ [
70
+ "--tenancy single|multi",
71
+ "Whether its backend serves one Livespace account or many.",
72
+ ],
73
+ [
74
+ "--distribution catalog|url",
75
+ "How accounts add it: from the catalog, or by URL.",
76
+ ],
77
+ [
78
+ "--secrets | --no-secrets",
79
+ "Whether admins enter secrets (API tokens and the like) in its settings.",
80
+ ],
81
+ [
82
+ "--skill | --no-skill",
83
+ "Whether to add the livespace-plugin agent skill.",
84
+ ],
85
+ ],
86
+ notes: [
87
+ "--tenancy, --distribution and --secrets have no default: they decide the keys. Why:",
88
+ DO_YOU_NEED_KEYS,
89
+ "",
90
+ "It also takes the flags of the commands it runs: manifest init's, keys init's",
91
+ `and skill install's. See ${RUN} manifest init --help, and the others.`,
92
+ ],
93
+ },
94
+ "manifest init": {
95
+ usage: "",
96
+ summary: "Create plugin-manifest.json, asking for each field. Defaults come from package.json when there is one. Never overwrites a manifest.",
97
+ flags: [
98
+ ["--id <id>", "The plugin's permanent catalog key."],
99
+ [
100
+ "--languages <list>",
101
+ "The languages its texts are in: en,pl (en is required).",
102
+ ],
103
+ ...MANIFEST_FIELDS,
104
+ [
105
+ "--secrets | --no-secrets",
106
+ "Whether its config form has Secret Fields.",
107
+ ],
108
+ [
109
+ "--keys | --no-keys",
110
+ "Whether to create its key pairs now, as keys init does.",
111
+ ],
112
+ [
113
+ "--bits <n>",
114
+ "The RSA key size, with --keys (default and minimum 2048).",
115
+ ],
116
+ ],
117
+ },
118
+ "manifest set": {
119
+ usage: "<field> [value]",
120
+ summary: "Change one field. `manifest set origin <url>` is `manifest set origin --origin <url>`.",
121
+ flags: MANIFEST_FIELDS,
122
+ },
123
+ "manifest check": {
124
+ usage: "[--origin <url>]",
125
+ summary: "Check the manifest the way the catalog will, and against the project: public/ files, the types the code declares, the last publish. Exit 1 on a failure.",
126
+ flags: [
127
+ [
128
+ "--origin <url>",
129
+ "The iframeOrigin must be this: the address it's deployed to.",
130
+ ],
131
+ ],
132
+ },
133
+ "manifest published": {
134
+ usage: "",
135
+ summary: "Record the version and content just published, so check warns about a change without a version bump.",
136
+ flags: [],
137
+ },
138
+ "keys init": {
139
+ usage: "[--use sig|enc|both] [--out <path>]",
140
+ summary: "Create the key pairs: a signing key, and an encryption key when there are secretKeys. Private halves go to keys/<kid>.pem (0600, gitignored); never printed. Public halves go in the manifest; with no manifest (a plugin added by URL), in [public/].well-known/livespace/jwks.json.",
141
+ flags: OWN_KEYS,
142
+ },
143
+ "keys rotate": {
144
+ usage: "--use sig|enc",
145
+ summary: "Add a key for a rotation (at most two per use).",
146
+ flags: [
147
+ ["--use sig|enc", "Which key to rotate."],
148
+ ["--bits <n>", "The RSA key size (default and minimum 2048)."],
149
+ ],
150
+ },
151
+ "keys retire": {
152
+ usage: "<kid>",
153
+ summary: "Remove a key from the manifest, or the jwks.json.",
154
+ flags: [],
155
+ },
156
+ "keys jwks": {
157
+ usage: "[--out <path>]",
158
+ summary: "Write [public/].well-known/livespace/jwks.json from the manifest's keys, for a catalog plugin that's also added by URL.",
159
+ flags: [
160
+ [
161
+ "--out <path>",
162
+ "Where to write it (default: the jwks.json that's there, else public/.well-known/… when there's a public/ directory).",
163
+ ],
164
+ ],
165
+ },
166
+ "client-id": {
167
+ usage: "",
168
+ summary: 'Print plugin:<id>, what the backend checks "aud" against.',
169
+ flags: [],
170
+ },
171
+ "skill install": {
172
+ usage: "",
173
+ summary: "Copy the livespace-plugin agent skill into the project, into .claude/skills and/or .agents/skills, whichever the chosen agents read. Replaces a copy that's there: run it again to take a newer CLI's skill.",
174
+ flags: SKILL_INSTALL,
175
+ },
176
+ };
177
+ const GLOBAL = [
178
+ ["--dir <path>", "The plugin project (default: the current directory)."],
179
+ ["--yes, -y", "Take the defaults instead of asking."],
180
+ ["--json", "Print only a JSON result."],
181
+ ["--help, -h", "This text."],
182
+ ];
183
+ /** The width help is wrapped to. */
184
+ const WIDTH = 90;
185
+ /** `text` in lines of at most `width` characters, broken at spaces. */
186
+ function wrap(text, width) {
187
+ const lines = [];
188
+ let line = "";
189
+ for (const word of text.split(" ")) {
190
+ if (line !== "" && line.length + 1 + word.length > width) {
191
+ lines.push(line);
192
+ line = word;
193
+ }
194
+ else {
195
+ line = line === "" ? word : `${line} ${word}`;
196
+ }
197
+ }
198
+ return [...lines, line];
199
+ }
200
+ /**
201
+ * A two-column table, indented two: the left column padded to `width`, the right wrapped beside
202
+ * it. A left entry too long for the column takes a line of its own.
203
+ */
204
+ function table(rows, width) {
205
+ const pad = " ".repeat(width);
206
+ return rows
207
+ .flatMap(([left, right]) => {
208
+ const lines = wrap(right, WIDTH - 2 - width).map((line) => ` ${pad}${line}`);
209
+ if (left.length < width - 1) {
210
+ lines[0] = ` ${left.padEnd(width)}${lines[0].trimStart()}`;
211
+ return lines;
212
+ }
213
+ return [` ${left}`, ...lines];
214
+ })
215
+ .join("\n");
216
+ }
217
+ const commandRows = (names) => names.map((name) => {
218
+ const { usage, summary } = COMMAND_HELP[name];
219
+ return [`${name} ${usage}`.trim(), summary];
220
+ });
221
+ /** The overview, for `--help` alone. */
222
+ export function overview(version) {
223
+ return `livespace-plugin ${version} — start a Livespace plugin, and set up its manifest and keys
224
+
225
+ Usage: ${RUN} <command> [flags]
226
+
227
+ Commands:
228
+ ${table(commandRows(Object.keys(COMMAND_HELP)), 27)}
229
+
230
+ A command's flags, and what each one does: ${RUN} <command> --help
231
+ (for example, ${RUN} manifest init --help).
232
+ Without a terminal, every answer comes from a flag, and a missing one is an error that
233
+ lists them.
234
+
235
+ To try a plugin locally, embedded as Livespace embeds it, run Plugin Studio: the studio
236
+ script in a project create made, or npx @livespace/plugin-studio.
237
+
238
+ Flags every command takes:
239
+ ${table(GLOBAL, 15)}
240
+ --version The CLI's version, given alone. With a command, the manifest's.
241
+ `;
242
+ }
243
+ /** The commands of `group` (`manifest`, `keys`, `skill`), or undefined when there are none. */
244
+ export function groupHelp(group) {
245
+ const names = Object.keys(COMMAND_HELP).filter((name) => name.startsWith(`${group} `));
246
+ if (names.length === 0) {
247
+ return undefined;
248
+ }
249
+ return `Usage: ${RUN} ${group} <command> [flags]
250
+
251
+ Commands:
252
+ ${table(commandRows(names), 27)}
253
+
254
+ A command's flags: ${RUN} ${group} <command> --help
255
+ `;
256
+ }
257
+ /** One command's help, with each of its flags, or undefined for an unknown command. */
258
+ export function commandHelp(name) {
259
+ const help = COMMAND_HELP[name];
260
+ if (help === undefined) {
261
+ return undefined;
262
+ }
263
+ const width = Math.min(30, Math.max(15, ...help.flags.map(([flag]) => flag.length + 2)));
264
+ const own = help.flags.length === 0
265
+ ? "It takes no flags of its own.\n"
266
+ : `Flags:\n${table(help.flags, width)}\n`;
267
+ const notes = help.notes === undefined ? "" : `\n${help.notes.join("\n")}\n`;
268
+ return (`Usage: ${RUN} ${name} ${help.usage}`.trimEnd() +
269
+ `
270
+
271
+ ${wrap(help.summary, WIDTH).join("\n")}
272
+
273
+ ${own}${notes}
274
+ Flags every command takes:
275
+ ${table(GLOBAL, 15)}
276
+ `);
277
+ }
package/dist/sdk/range.js CHANGED
@@ -24,6 +24,7 @@ export const SDK_LLMS_TXT_CDN_URL = `https://cdn.jsdelivr.net/npm/@livespace/plu
24
24
  /**
25
25
  * The `@livespace/plugin-studio` range `create`'s templates list as a dev dependency. The studio
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
- * with `packages/studio`.
27
+ * with `packages/studio`. While the studio is a pre-release, the range starts at it: a caret range
28
+ * takes later pre-releases of that version, and every release after.
28
29
  */
29
- export const STUDIO_RANGE = "^0.2";
30
+ export const STUDIO_RANGE = "^0.3.0-beta.1";
@@ -2,7 +2,7 @@
2
2
  name: livespace-plugin
3
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
- cli-version: "0.5.0-beta.1"
5
+ cli-version: "0.5.0-beta.2"
6
6
  sdk-range: "^1"
7
7
  ---
8
8
 
@@ -47,10 +47,12 @@ The CLI, Plugin Studio and the build need Bun or Node.
47
47
  rest of the session (`~/.bun/bin/bun` and `~/.bun/bin/bunx`, or under `%USERPROFILE%\.bun\bin\`
48
48
  on Windows): this session's shell won't see the installer's PATH change.
49
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`.
50
+ it. Say what failed and what to ask whoever runs the machine for. Don't work around it. A plugin
51
+ with no backend can still be written, as plain files (step 1, "How it's built"), but previewing
52
+ and deploying it wait for a runtime: say so.
53
+ - **No project yet** (you came here from a link): once you've scoped it (step 1), start one: with
54
+ `create`, which also installs this skill so later sessions have it, or as plain files. A project
55
+ without the skill gets it with `skill install`.
54
56
 
55
57
  ## 0. Read `llms.txt`
56
58
 
@@ -117,6 +119,9 @@ answer: the list below is what to know, not a script.
117
119
 
118
120
  Either way, Livespace staff must allow the plugin's address for the account, when the account's
119
121
  admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
122
+ - **How it's built**, which you decide, not the author. With no backend and an author who isn't a
123
+ developer, or a machine with no runtime: **plain files**, with no install and no build (step 2,
124
+ "Plain files"). Otherwise, or in an existing project: `create`, or the project as it stands.
120
125
 
121
126
  Then tell the author what you're going to build and what they'll need for it, before the first
122
127
  file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
@@ -151,10 +156,26 @@ Throughout:
151
156
  - **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
152
157
  widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
153
158
 
159
+ ### Plain files
160
+
161
+ A plugin with no build is a folder of files the host serves as they are, with the SDK loaded as
162
+ _Getting started_ shows:
163
+
164
+ - **`public/`** is what the host serves: `index.html`, with the SDK's script and `ls-tokens.css`
165
+ from `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@1/dist/` in `<head>`;
166
+ `main.js`, loaded by a plain `<script src="main.js">` at the end of `<body>`, so its config form
167
+ and `declareMetadata` run in the global scope before the page loads; `styles.css`; and a catalog
168
+ plugin's images and about page.
169
+ - **Beside `public/`**: `plugin-manifest.json` for a catalog plugin, and the host's config. They're
170
+ not served.
171
+ - **No `package.json`, no bundler, no TypeScript, no framework** from npm. Plain JavaScript in the
172
+ browser does what a plugin with no backend needs.
173
+
154
174
  ## 3. Manifest and keys, through the CLI
155
175
 
156
176
  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.
177
+ `bunx --bun`). Its `--help` lists the commands, and `<command> --help` (`manifest init --help`)
178
+ gives a command's flags; read a command's before its first run.
158
179
  Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
159
180
  yours to pass on.
160
181
 
@@ -194,6 +215,9 @@ What the catalog shows comes from the manifest. Fill it in with the author:
194
215
  - Open the page outside Livespace: it shows its loading state and the console is clean.
195
216
  - Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
196
217
  made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
218
+ - **Plain files have no dev server:** `npx @livespace/plugin-studio --serve public` from the
219
+ plugin's folder serves `public/` on the next port and embeds it. After changing a file, reload
220
+ the studio's page. `--serve` needs `@livespace/plugin-studio` 0.3 or later.
197
221
  - **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
198
222
  use the one already running: it's probably the author's, and its saved settings, secrets and
199
223
  exchange failures are shared by everyone using it.
@@ -52,6 +52,9 @@ Add Wrangler to the project, so its version is pinned in the lockfile: `bun add
52
52
  `npm install -D wrangler`. Run it with `bunx --bun wrangler …`, or `npx wrangler …` under Node. Add
53
53
  `.wrangler/`, its local state, to `.gitignore`.
54
54
 
55
+ **Plain files** (no `package.json`): don't add one for Wrangler. Pin it in the command instead,
56
+ `bunx --bun wrangler@4.161.0 …` or `npx wrangler@4.161.0 …`, the same version every time.
57
+
55
58
  1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
56
59
 
57
60
  ```jsonc
@@ -62,6 +65,8 @@ Add Wrangler to the project, so its version is pinned in the lockfile: `bun add
62
65
  }
63
66
  ```
64
67
 
68
+ For plain files, `"directory": "./public"`, and there's nothing to build.
69
+
65
70
  2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
66
71
  up.
67
72
  3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livespace/plugin-cli",
3
- "version": "0.5.0-beta.1",
3
+ "version": "0.5.0-beta.2",
4
4
  "description": "Starts a Livespace plugin project, and sets up its catalog manifest and keys.",
5
5
  "author": "LS FE team",
6
6
  "license": "MIT",
@@ -47,10 +47,12 @@ The CLI, Plugin Studio and the build need Bun or Node.
47
47
  rest of the session (`~/.bun/bin/bun` and `~/.bun/bin/bunx`, or under `%USERPROFILE%\.bun\bin\`
48
48
  on Windows): this session's shell won't see the installer's PATH change.
49
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`.
50
+ it. Say what failed and what to ask whoever runs the machine for. Don't work around it. A plugin
51
+ with no backend can still be written, as plain files (step 1, "How it's built"), but previewing
52
+ and deploying it wait for a runtime: say so.
53
+ - **No project yet** (you came here from a link): once you've scoped it (step 1), start one: with
54
+ `create`, which also installs this skill so later sessions have it, or as plain files. A project
55
+ without the skill gets it with `skill install`.
54
56
 
55
57
  ## 0. Read `llms.txt`
56
58
 
@@ -117,6 +119,9 @@ answer: the list below is what to know, not a script.
117
119
 
118
120
  Either way, Livespace staff must allow the plugin's address for the account, when the account's
119
121
  admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
122
+ - **How it's built**, which you decide, not the author. With no backend and an author who isn't a
123
+ developer, or a machine with no runtime: **plain files**, with no install and no build (step 2,
124
+ "Plain files"). Otherwise, or in an existing project: `create`, or the project as it stands.
120
125
 
121
126
  Then tell the author what you're going to build and what they'll need for it, before the first
122
127
  file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
@@ -151,10 +156,26 @@ Throughout:
151
156
  - **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
152
157
  widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
153
158
 
159
+ ### Plain files
160
+
161
+ A plugin with no build is a folder of files the host serves as they are, with the SDK loaded as
162
+ _Getting started_ shows:
163
+
164
+ - **`public/`** is what the host serves: `index.html`, with the SDK's script and `ls-tokens.css`
165
+ from `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@{{sdkMajor}}/dist/` in `<head>`;
166
+ `main.js`, loaded by a plain `<script src="main.js">` at the end of `<body>`, so its config form
167
+ and `declareMetadata` run in the global scope before the page loads; `styles.css`; and a catalog
168
+ plugin's images and about page.
169
+ - **Beside `public/`**: `plugin-manifest.json` for a catalog plugin, and the host's config. They're
170
+ not served.
171
+ - **No `package.json`, no bundler, no TypeScript, no framework** from npm. Plain JavaScript in the
172
+ browser does what a plugin with no backend needs.
173
+
154
174
  ## 3. Manifest and keys, through the CLI
155
175
 
156
176
  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.
177
+ `bunx --bun`). Its `--help` lists the commands, and `<command> --help` (`manifest init --help`)
178
+ gives a command's flags; read a command's before its first run.
158
179
  Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
159
180
  yours to pass on.
160
181
 
@@ -194,6 +215,9 @@ What the catalog shows comes from the manifest. Fill it in with the author:
194
215
  - Open the page outside Livespace: it shows its loading state and the console is clean.
195
216
  - Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
196
217
  made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
218
+ - **Plain files have no dev server:** `npx @livespace/plugin-studio --serve public` from the
219
+ plugin's folder serves `public/` on the next port and embeds it. After changing a file, reload
220
+ the studio's page. `--serve` needs `@livespace/plugin-studio` 0.3 or later.
197
221
  - **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
198
222
  use the one already running: it's probably the author's, and its saved settings, secrets and
199
223
  exchange failures are shared by everyone using it.
@@ -52,6 +52,9 @@ Add Wrangler to the project, so its version is pinned in the lockfile: `bun add
52
52
  `npm install -D wrangler`. Run it with `bunx --bun wrangler …`, or `npx wrangler …` under Node. Add
53
53
  `.wrangler/`, its local state, to `.gitignore`.
54
54
 
55
+ **Plain files** (no `package.json`): don't add one for Wrangler. Pin it in the command instead,
56
+ `bunx --bun wrangler@4.161.0 …` or `npx wrangler@4.161.0 …`, the same version every time.
57
+
55
58
  1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
56
59
 
57
60
  ```jsonc
@@ -62,6 +65,8 @@ Add Wrangler to the project, so its version is pinned in the lockfile: `bun add
62
65
  }
63
66
  ```
64
67
 
68
+ For plain files, `"directory": "./public"`, and there's nothing to build.
69
+
65
70
  2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
66
71
  up.
67
72
  3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time