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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
+ }
@@ -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
@@ -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";