@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/README.md CHANGED
@@ -23,6 +23,19 @@ Each step is also a command of its own, for a project you already have. In a ter
23
23
  for each answer, as pickers where there's a fixed set; `manifest init` takes its defaults from
24
24
  `package.json` and checks the manifest the way the catalog will before writing it.
25
25
 
26
+ ## Building a plugin with Claude Code
27
+
28
+ No Node, no terminal? Paste this into Claude Code (or another coding agent):
29
+
30
+ > Build me a Livespace plugin. Start by reading
31
+ > https://cdn.jsdelivr.net/npm/@livespace/plugin-cli@0/README.md
32
+
33
+ **For the agent reading this:** the workflow is the `livespace-plugin` skill, at
34
+ https://cdn.jsdelivr.net/npm/@livespace/plugin-cli@0/dist/skill/livespace-plugin/SKILL.md. Read it
35
+ whole and follow it, from "Before you start": it checks for Bun or Node (and installs Bun, with the
36
+ author's consent, if there's neither), then scopes the plugin with the author, then has `create`
37
+ start the project, which installs the skill into it for later sessions.
38
+
26
39
  ## Commands
27
40
 
28
41
  | Command | What it does |
@@ -30,11 +43,12 @@ for each answer, as pickers where there's a fixed set; `manifest init` takes its
30
43
  | `create [dir]` | Start a plugin project in `dir` (default: the current directory), as above. Refuses a directory that isn't empty unless `--force`. `--template vite\|bun` (default: Bun when run with `bunx`, else Vite), `--pm npm\|pnpm\|yarn\|bun` (default: whichever ran it), `--no-install`. |
31
44
  | `manifest init` | Create `plugin-manifest.json`, and optionally the key pairs. Never overwrites a manifest: its `id` is the catalog key. |
32
45
  | `manifest set <field> [value]` | Change one field: `version`, `origin`, `object-types`, `name-<lang>`, `description-<lang>`, `details-<lang>`, `categories`, `icon-url`, `illustration-url`, `accent-color`, `info-url`, `additional-images`, `secret-keys`. |
33
- | `manifest check` | Check the manifest the way the catalog will. Exits 1 on a failure; warnings don't fail. |
46
+ | `manifest check [--origin <url>]` | Check the manifest the way the catalog will. Exits 1 on a failure; warnings don't fail. It also checks it against the project: an image on the plugin's origin with no file in `public/`, context types that differ from a literal list the code passes `declareMetadata`, and a change since `manifest published` without a version bump. With `--origin`, where the plugin is deployed, `iframeOrigin` must be exactly that. |
47
+ | `manifest published` | Record the version and content just published, in `.livespace-plugin-published`. Whoever deploys runs it once a deploy is live; commit it, so the whole team gets the version-bump warning. |
34
48
  | `keys init [--use sig\|enc\|both]` | Create the key pairs: a signing key, plus an encryption key when the manifest has `secretKeys`. With no manifest, both, into a `jwks.json` (see Keys). |
35
49
  | `keys rotate --use sig\|enc` | Add a key for a rotation. At most two of each; a new encryption key goes first, as the browser encrypts with the first. |
36
50
  | `keys retire <kid>` | Remove a key from the manifest. The private half stays on disk until you destroy it. |
37
- | `keys jwks [--out <path>]` | Write `.well-known/livespace/jwks.json` from the manifest's keys, for a catalog plugin that's also added by URL. |
51
+ | `keys jwks [--out <path>]` | Write the `jwks.json` from the manifest's keys, for a catalog plugin that's also added by URL. It goes where a plugin added by URL keeps it (see Keys). |
38
52
  | `client-id` | Print `plugin:<id>`, what your backend checks a plugin token's `aud` against. |
39
53
  | `skill install` | Copy the `livespace-plugin` agent skill into the project: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI and others (Cursor and Copilot read either). `--harness` picks the agents, `--gitignore` keeps the copies out of git. Replaces a copy that's there: run `npx @livespace/plugin-cli@latest skill install` to take the newest skill. The skill reads the SDK's documentation from `node_modules`, so it matches the installed SDK. |
40
54
 
@@ -99,11 +113,12 @@ npx @livespace/plugin-cli manifest init --yes --json \
99
113
  goes alone, never with a type: `any,deal` is refused.
100
114
 
101
115
  Without a terminal, a missing answer is never waited for: the command exits 1 and lists every flag
102
- it still needs. See `--help` for them all.
116
+ it still needs. `--help` lists the commands, and `<command> --help` a command's flags.
103
117
 
104
118
  ## Requirements
105
119
 
106
- 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.
107
122
 
108
123
  ## License
109
124
 
package/dist/cli.js CHANGED
@@ -11,119 +11,22 @@ 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
- import { manifestCheck, manifestInit, manifestSet, } from "./commands/manifest.js";
16
+ import { manifestCheck, manifestInit, manifestPublished, manifestSet, } from "./commands/manifest.js";
17
17
  import { skillInstall } from "./commands/skill.js";
18
- 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 Check the manifest the way the catalog will. Exit 1 on
80
- a failure.
81
- keys init [--use sig|enc|both] [--out <path>]
82
- Create the key pairs: a signing key, and an encryption
83
- key when there are secretKeys. Private halves go to
84
- keys/<kid>.pem (0600, gitignored); never printed.
85
- Public halves go in the manifest; with no manifest (a
86
- plugin added by URL), in [public/].well-known/livespace/
87
- jwks.json, both keys by default.
88
- keys rotate --use sig|enc
89
- Add a key for a rotation (at most two per use).
90
- keys retire <kid> Remove a key from the manifest, or the jwks.json.
91
- keys jwks [--out <path>] Write .well-known/livespace/jwks.json from the
92
- manifest's keys, for a catalog plugin that's also
93
- added by URL.
94
- client-id Print plugin:<id>, what the backend checks "aud" against.
95
- skill install Copy the livespace-plugin agent skill into the project,
96
- into .claude/skills and/or .agents/skills, whichever
97
- the chosen agents read. Replaces a copy that's there:
98
- run it again to take a newer CLI's skill.
99
-
100
- To try a plugin locally, embedded as Livespace embeds it, run Plugin Studio: the studio
101
- script in a project create made, or npx @livespace/plugin-studio.
102
-
103
- Answers as flags (for scripts and agents; without a terminal, a missing one is an error):
104
- create --template vite|bun, --pm npm|pnpm|yarn|bun, --no-install, --force,
105
- --tenancy single|multi, --distribution catalog|url,
106
- --secrets | --no-secrets, --skill | --no-skill,
107
- then manifest init's and skill install's. --tenancy, --distribution
108
- and --secrets have no default: they decide the keys. Why:
109
- ${DO_YOU_NEED_KEYS}
110
- manifest init --id, --version, --origin, --object-types deal,company|any,
111
- --languages en,pl, --name-<lang>, --description-<lang>,
112
- --categories "Deal,Finance", --icon-url, --illustration-url,
113
- --accent-color, --info-url, --secrets | --no-secrets,
114
- --secret-keys apiToken,webhookSecret, --keys | --no-keys
115
- (<lang>: ${LOCALES.join(", ")})
116
- keys --bits 2048
117
- skill install --harness claude-code,codex,cursor,copilot,gemini,other,
118
- --gitignore | --no-gitignore
119
-
120
- Other flags:
121
- --dir <path> The plugin project (default: the current directory).
122
- --yes, -y Take the defaults instead of asking.
123
- --json Print only a JSON result.
124
- --help, -h This text.
125
- `;
126
24
  async function run(argv) {
25
+ // Alone, --version asks for the CLI's; with a command, it's the manifest's version flag.
26
+ if (argv.length === 1 && argv[0] === "--version") {
27
+ console.log(CLI_VERSION);
28
+ return 0;
29
+ }
127
30
  const { values, positionals } = parseArgs({
128
31
  args: argv,
129
32
  allowPositionals: true,
@@ -135,11 +38,28 @@ async function run(argv) {
135
38
  },
136
39
  });
137
40
  const flags = values;
138
- const [group, command, arg, value] = positionals;
139
- if (flags.help || group === undefined || group === "help") {
140
- 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));
141
49
  return 0;
142
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));
143
63
  // `manifest set <field> <value>` is the same as `manifest set <field> --<field> <value>`.
144
64
  if (group === "manifest" &&
145
65
  command === "set" &&
@@ -182,6 +102,9 @@ async function run(argv) {
182
102
  return 0;
183
103
  case "manifest check":
184
104
  return manifestCheck(ctx);
105
+ case "manifest published":
106
+ await manifestPublished(ctx);
107
+ return 0;
185
108
  case "keys init":
186
109
  await keysInit(ctx);
187
110
  return 0;
@@ -66,8 +66,8 @@ export async function saveKeys(ctx, pairs) {
66
66
  }
67
67
  const exists = (path) => stat(path).then(() => true, () => false);
68
68
  /**
69
- * Without a manifest: `--out`, else whichever jwks.json is already there, else `public/…` when the
70
- * project has a `public/` directory (a created project does), else the project root.
69
+ * Where a jwks.json goes: `--out`, else whichever jwks.json is already there, else `public/…` when
70
+ * the project has a `public/` directory (a created project does), else the project root.
71
71
  */
72
72
  async function jwksPathFor(ctx) {
73
73
  if (typeof ctx.flags.out === "string") {
@@ -260,7 +260,7 @@ export async function keysJwks(ctx) {
260
260
  if (keys.length === 0) {
261
261
  throw new UsageError("the manifest has no keys yet — `keys init` first");
262
262
  }
263
- const out = typeof ctx.flags.out === "string" ? ctx.flags.out : JWKS_PATH;
263
+ const out = await jwksPathFor(ctx);
264
264
  const path = join(ctx.dir, out);
265
265
  await mkdir(dirname(path), { recursive: true });
266
266
  await writeFile(path, `${JSON.stringify({ keys }, null, 2)}\n`);
@@ -1,7 +1,8 @@
1
- /** `manifest init`, `manifest set` and `manifest check`. */
1
+ /** `manifest init`, `manifest set`, `manifest check` and `manifest published`. */
2
2
  import { checkManifest } from "../manifest/check.js";
3
3
  import { readManifestText, readPackageJson, serializeManifest, writeManifest, } from "../manifest/file.js";
4
4
  import { prefillFrom } from "../manifest/package-json.js";
5
+ import { PUBLISHED_FILE, readProjectFacts, recordPublished, } from "../manifest/project.js";
5
6
  import { CATEGORIES, EXPECTED_LOCALES, LOCALES, MANIFEST_FILE, OBJECT_TYPES, REQUIRED_LOCALE, clientIdOf, } from "../manifest/schema.js";
6
7
  import { isHexColor, isHttpsOrigin, isHttpsUrl, isId, isImageUrl, isKeyList, isSemver, splitList, } from "../ui/validators.js";
7
8
  import { UsageError } from "./context.js";
@@ -365,7 +366,15 @@ export async function manifestCheck(ctx) {
365
366
  ctx.out.result({ ok: false, failures: [failure], warnings: [] });
366
367
  return 1;
367
368
  }
368
- const { failures, warnings } = checkManifest(text);
369
+ const origin = ctx.flags.origin;
370
+ if (origin !== undefined) {
371
+ const problem = typeof origin === "string" ? isHttpsOrigin(origin) : "a value";
372
+ if (problem !== undefined) {
373
+ throw new UsageError(`--origin must be ${problem}`);
374
+ }
375
+ }
376
+ const facts = await readProjectFacts(ctx.dir, typeof origin === "string" ? origin : undefined);
377
+ const { failures, warnings } = checkManifest(text, facts);
369
378
  for (const failure of failures) {
370
379
  ctx.out.warn(`✗ ${failure}`);
371
380
  }
@@ -378,3 +387,20 @@ export async function manifestCheck(ctx) {
378
387
  ctx.out.result({ ok: failures.length === 0, failures, warnings });
379
388
  return failures.length === 0 ? 0 : 1;
380
389
  }
390
+ /**
391
+ * Records what was just published: the version and a digest of the rest. A deployer runs it once a
392
+ * deploy is live, so `manifest check` can warn when the manifest changes without a version bump.
393
+ */
394
+ export async function manifestPublished(ctx) {
395
+ const text = await readManifestText(ctx.dir);
396
+ if (text === undefined) {
397
+ throw new UsageError(`no ${MANIFEST_FILE} here — nothing was published`);
398
+ }
399
+ const { manifest } = checkManifest(text);
400
+ if (manifest === null) {
401
+ throw new UsageError(`${MANIFEST_FILE} fails its check, so it can't have been published — see \`manifest check\``);
402
+ }
403
+ const record = await recordPublished(ctx.dir, manifest);
404
+ ctx.out.success(`Recorded version ${record.version} in ${PUBLISHED_FILE}.`);
405
+ ctx.out.result({ published: PUBLISHED_FILE, ...record });
406
+ }
@@ -5,10 +5,10 @@
5
5
  * and running it again is how a project takes a newer skill (docs/adr/0003).
6
6
  */
7
7
  import { access, mkdir, readFile, writeFile } from "node:fs/promises";
8
- import { join } from "node:path";
8
+ import { dirname, join } from "node:path";
9
9
  import { addToGitignore } from "../project/gitignore.js";
10
10
  import { SDK_LLMS_TXT_CDN_URL, SUPPORTED_SDK_RANGE, isSupportedSdkVersion, } from "../sdk/range.js";
11
- import { CLI_VERSION, HARNESSES, SKILL_FILE, SKILL_NAME, readSkillSource, readStamp, renderSkill, targetsFor, } from "../skill/source.js";
11
+ import { CLI_VERSION, HARNESSES, SKILL_FILE, SKILL_NAME, readSkillFiles, readStamp, targetsFor, } from "../skill/source.js";
12
12
  const exists = (path) => access(path).then(() => true, () => false);
13
13
  /** The installed SDK's version, or undefined when it isn't in node_modules. */
14
14
  async function installedSdkVersion(dir) {
@@ -46,14 +46,17 @@ export async function skillInstall(ctx) {
46
46
  else if (!supported) {
47
47
  ctx.out.warn(`The project has @livespace/plugin-sdk ${sdkVersion}, but this CLI's skill is written for ${SUPPORTED_SDK_RANGE}. Its workflow may not match the SDK; llms.txt is still the installed one.`);
48
48
  }
49
- const copy = renderSkill(readSkillSource());
49
+ const files = readSkillFiles();
50
50
  const targets = [];
51
51
  for (const target of targetsFor(harnesses)) {
52
52
  const skillDir = `${target}/${SKILL_NAME}`;
53
53
  const path = join(ctx.dir, skillDir, SKILL_FILE);
54
54
  const before = await readFile(path, "utf8").catch(() => undefined);
55
- await mkdir(join(ctx.dir, skillDir), { recursive: true });
56
- await writeFile(path, copy);
55
+ for (const [name, text] of files) {
56
+ const filePath = join(ctx.dir, skillDir, name);
57
+ await mkdir(dirname(filePath), { recursive: true });
58
+ await writeFile(filePath, text);
59
+ }
57
60
  if (before === undefined) {
58
61
  ctx.out.success(`Wrote ${skillDir}/${SKILL_FILE}`);
59
62
  targets.push({ dir: skillDir, status: "written" });
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
+ }