@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 +3 -2
- package/dist/cli.js +23 -114
- package/dist/flags.js +104 -0
- package/dist/help.js +277 -0
- package/dist/sdk/range.js +3 -2
- package/dist/skill/livespace-plugin/SKILL.md +30 -6
- package/dist/skill/livespace-plugin/hosts.md +5 -0
- package/package.json +1 -1
- package/skill/livespace-plugin/SKILL.md +29 -5
- package/skill/livespace-plugin/hosts.md +5 -0
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.
|
|
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 {
|
|
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 {
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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`
|
|
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
|
@@ -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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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`
|
|
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
|