@livespace/plugin-studio 0.1.0 → 0.3.0-beta.1

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
@@ -11,6 +11,9 @@ Projects that [`@livespace/plugin-cli create`](https://www.npmjs.com/package/@li
11
11
  makes already have it, with a `studio` script. Outside a project, `npx @livespace/plugin-studio`
12
12
  runs it for any plugin page, a deployed one included.
13
13
 
14
+ It runs on Node 20.12 or later, or on Bun: `bunx --bun @livespace/plugin-studio`, where `--bun`
15
+ keeps it on Bun when an older Node is also installed.
16
+
14
17
  The studio uses the project's own `@livespace/plugin-sdk` (a peer dependency, `^1`), so it speaks
15
18
  the same protocol version as the plugin.
16
19
 
@@ -69,6 +72,11 @@ top, so any plugin page works, a deployed one included.
69
72
  Livespace can.
70
73
  - **Messages**: every message, both ways, in a pane on the right. Its button in the top bar hides
71
74
  it, and its edge resizes it.
75
+ - **The browser console** gets the same log, one line per entry, prefixed `[studio]`, for the
76
+ browser tools coding agents use. The studio's notes (what it refused or dropped as Livespace
77
+ would, timeouts, what the address set) are warnings. The plugin's messages are `debug`, hidden
78
+ unless asked for: Chrome's "Verbose" level, or `level: "debug"` in the Playwright MCP's
79
+ `browser_console_messages`. Payloads over 4000 characters are cut.
72
80
 
73
81
  `--url` fills in the address (default: Vite's `http://localhost:5173` or Bun's
74
82
  `http://localhost:3000`, from the project; outside one, the page asks). `--port` moves the
@@ -76,11 +84,56 @@ studio, and `--client-id` sets the starting client id (default: the manifest's `
76
84
  `plugin:dev`). The sidebar, the address and the layout are kept in your browser; what you save on
77
85
  the settings page lives in the studio's memory, so a restart starts that afresh.
78
86
 
87
+ ## A plugin that's plain files
88
+
89
+ A plugin with no build has no dev server. `--serve` serves its folder instead, usually `public/`:
90
+
91
+ ```sh
92
+ npx @livespace/plugin-studio --serve public
93
+ ```
94
+
95
+ The folder gets the port after the studio's (5191 by default), so the plugin has an origin of its
96
+ own, as in Livespace. Every file is sent with `Access-Control-Allow-Origin: *` and no caching, so
97
+ a published `jwks.json` is read as Livespace reads it. There's no live reload: after changing a
98
+ file, reload the studio's page. The manifest is read from `--dir` (default: the current
99
+ directory), so run it from the plugin's folder.
100
+
101
+ ## Setting up a state from the address
102
+
103
+ The address can set up a state in one go, which is quicker for a coding agent than clicking
104
+ through the sidebar. Params go after the page in the hash, `#?…` for the profile page and
105
+ `#settings?…` for the settings page:
106
+
107
+ ```
108
+ http://localhost:5190/#?type=none&viewer=&display=fullscreen&token=forbidden
109
+ http://localhost:5190/#settings?preferences=en-US&width=320
110
+ ```
111
+
112
+ | Param | Values | Sets |
113
+ |---|---|---|
114
+ | `type` | `deal`, `company`, `person`, `space`, `none` (the apps menu) | Where it's installed. A type the plugin can't be installed on gives way, as in the sidebar. |
115
+ | `viewer` | A user id; empty for no user | The viewer. |
116
+ | `preferences` | `pl`, `en-US`, `none` (an older Livespace) | The preferences preset. |
117
+ | `width` | `320`, `420`, `640`, `full` | The slot's column width. |
118
+ | `height` | Pixels, 40–2000 | The plugin's inline height. |
119
+ | `display` | `inline`, `dialog`, `fullscreen` | The profile page's display, for its next embed if none is open. |
120
+ | `credentials` | `bad_request`, `unauthenticated`, `forbidden`, `not_found`, `conflict`, `server_error`, `no-answer` | How `api.call`'s credentials are refused. |
121
+ | `token` | `token`, `every-other-expired`, a refusal code above or `not_purchased`, `no-answer` | How plugin tokens are answered. |
122
+
123
+ - **Set once, then dropped.** What's set is kept as if chosen in the sidebar, and the params
124
+ leave the address, so a reload or Back never sets them again. The message log notes what was
125
+ set, and what was ignored and why.
126
+ - **This browser's state only.** The saved settings, the stored secrets and the exchange's
127
+ refusal live in the studio's memory, so everyone using that studio shares them: a plugin's
128
+ backend reads them without a browser. The address never sets them. Use the settings form and
129
+ the Switches section instead.
130
+
79
131
  ## Flags
80
132
 
81
133
  | Flag | What it does |
82
134
  |---|---|
83
135
  | `--url <page>` | The plugin's page to start with. The page can change it. |
136
+ | `--serve <folder>` | A plugin that's plain files: the studio serves the folder and embeds its `index.html` ([below](#a-plugin-thats-plain-files)). Not with `--url`. |
84
137
  | `--port <n>` | Where the studio listens (default: 5190). |
85
138
  | `--client-id <id>` | The starting client id. The page can change it. |
86
139
  | `--dir <path>` | The plugin project, for its manifest and template (default: the current directory). |
package/dist/cli.js CHANGED
@@ -6,24 +6,29 @@
6
6
  import { readFileSync } from "node:fs";
7
7
  import { resolve } from "node:path";
8
8
  import { parseArgs } from "node:util";
9
+ import { serveStatic } from "./serve.js";
9
10
  import { startStudio } from "./server.js";
10
11
  import { STUDIO_PORT, UsageError, start, untilSignal } from "./start.js";
11
12
  const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
12
13
  const HELP = `livespace-plugin-studio ${version}: try a Livespace plugin locally
13
14
 
14
- Usage: livespace-plugin-studio [--url <plugin page>] [--port <n>] [--client-id <id>]
15
- [--dir <path>]
15
+ Usage: livespace-plugin-studio [--url <plugin page> | --serve <folder>] [--port <n>]
16
+ [--client-id <id>] [--dir <path>]
16
17
 
17
18
  Serves Plugin Studio at http://localhost:${STUDIO_PORT}. It embeds your plugin's page the way
18
19
  Livespace does, renders its settings form, logs every message, and acts as the account your
19
20
  backend calls (it prints the env values). Start your dev server first; the studio doesn't start it.
21
+ A plugin that's plain files needs none: --serve its folder.
20
22
 
21
23
  --url <page> The plugin's page (default: Vite's or Bun's dev server, from the
22
24
  project's template; otherwise the page asks). The page can change it.
25
+ --serve <folder> A plugin that's plain files, with no build (its public/): the studio
26
+ serves the folder on the next port, its own origin, and embeds its
27
+ index.html. After a change, reload the studio's page.
23
28
  --port <n> Where the studio listens (default: ${STUDIO_PORT}).
24
29
  --client-id <id> The plugin's client id (default: plugin:<id> from the project's
25
30
  plugin-manifest.json, else plugin:dev). The page can change it.
26
- --dir <path> The plugin project (default: the current directory).
31
+ --dir <path> The plugin project, for its manifest (default: the current directory).
27
32
  --help, -h This text.
28
33
  --version, -v The version.
29
34
  `;
@@ -35,6 +40,7 @@ async function main(argv) {
35
40
  port: { type: "string" },
36
41
  "client-id": { type: "string" },
37
42
  dir: { type: "string" },
43
+ serve: { type: "string" },
38
44
  help: { type: "boolean", short: "h" },
39
45
  version: { type: "boolean", short: "v" },
40
46
  },
@@ -50,9 +56,15 @@ async function main(argv) {
50
56
  await start({
51
57
  dir: resolve(values.dir ?? process.cwd()),
52
58
  url: values.url,
59
+ serve: values.serve === undefined ? undefined : resolve(values.serve),
53
60
  port: values.port,
54
61
  clientId: values["client-id"],
55
- }, { start: startStudio, untilStopped: untilSignal, print: console.log });
62
+ }, {
63
+ start: startStudio,
64
+ serve: serveStatic,
65
+ untilStopped: untilSignal,
66
+ print: console.log,
67
+ });
56
68
  return 0;
57
69
  }
58
70
  main(process.argv.slice(2)).then((code) => {
@@ -0,0 +1,79 @@
1
+ /**
2
+ * The studio's address: the page, and a one-off instruction to set up a state, so a coding agent
3
+ * opens one URL per state instead of clicking through the sidebar. E.g.
4
+ * `#settings?type=company&preferences=en-US`, or `#?type=deal&display=dialog` for the profile.
5
+ * Only what this browser keeps: the saved settings, secrets and the exchange's refusal are the
6
+ * server's, shared by everyone on the studio. No DOM here.
7
+ */
8
+ import { COLUMN_WIDTHS } from "./display.js";
9
+ import { CREDENTIALS_CHOICES, TOKEN_CHOICES } from "./failures.js";
10
+ import { MAX_HEIGHT_PX, MIN_HEIGHT_PX } from "./slot-store.js";
11
+ import { PREFERENCE_PRESETS, RECORD_CHOICES, } from "./view-data.js";
12
+ const DISPLAYS = ["inline", "dialog", "fullscreen"];
13
+ const widthText = (width) => width === null ? "full" : String(width);
14
+ const oneOf = (values, set) => (value) => values.includes(value)
15
+ ? { ok: true, set: set(value) }
16
+ : { ok: false, reason: `one of ${values.join(", ")}` };
17
+ const READERS = {
18
+ type: oneOf(RECORD_CHOICES.map((c) => c.value), (type) => ({ type })),
19
+ viewer: (viewer) => ({ ok: true, set: { viewer: viewer.trim() } }),
20
+ preferences: oneOf(PREFERENCE_PRESETS.map((p) => p.value), (preferences) => ({ preferences })),
21
+ width: (value) => {
22
+ const width = COLUMN_WIDTHS.find((w) => widthText(w.value) === value);
23
+ return width === undefined
24
+ ? {
25
+ ok: false,
26
+ reason: `one of ${COLUMN_WIDTHS.map((w) => widthText(w.value)).join(", ")}`,
27
+ }
28
+ : { ok: true, set: { width: width.value } };
29
+ },
30
+ height: (value) => {
31
+ const height = Number(value);
32
+ return /^\d+$/.test(value) &&
33
+ height >= MIN_HEIGHT_PX &&
34
+ height <= MAX_HEIGHT_PX
35
+ ? { ok: true, set: { height } }
36
+ : { ok: false, reason: `pixels, ${MIN_HEIGHT_PX}–${MAX_HEIGHT_PX}` };
37
+ },
38
+ display: oneOf(DISPLAYS, (display) => ({ display })),
39
+ credentials: oneOf(CREDENTIALS_CHOICES.map((c) => c.value), (credentials) => ({ credentials })),
40
+ token: oneOf(TOKEN_CHOICES.map((c) => c.value), (token) => ({ token })),
41
+ };
42
+ /** Kept on the server, so never set from an address: say why, rather than "unknown". */
43
+ const SERVER_SIDE = {
44
+ config: "the saved settings are the studio server's: use the settings form",
45
+ exchange: "the exchange's refusal is the studio server's: use the Switches section",
46
+ };
47
+ export function readAddress(hash) {
48
+ const text = hash.startsWith("#") ? hash.slice(1) : hash;
49
+ const at = text.indexOf("?");
50
+ const path = at === -1 ? text : text.slice(0, at);
51
+ const page = path === "settings" ? "settings" : "profile";
52
+ const address = {
53
+ page,
54
+ changes: {},
55
+ applied: [],
56
+ ignored: [],
57
+ clean: page === "settings" ? "#settings" : "",
58
+ };
59
+ if (at === -1) {
60
+ return address;
61
+ }
62
+ new URLSearchParams(text.slice(at + 1)).forEach((value, name) => {
63
+ const read = READERS[name];
64
+ if (read === undefined) {
65
+ address.ignored.push(`${name} (${SERVER_SIDE[name] ?? "unknown"})`);
66
+ return;
67
+ }
68
+ const result = name === "display" && page === "settings"
69
+ ? { ok: false, reason: "the profile page's alone" }
70
+ : read(value);
71
+ if (!result.ok) {
72
+ address.ignored.push(`${name}=${value} (${result.reason})`);
73
+ return;
74
+ }
75
+ Object.assign(address.changes, result.set);
76
+ address.applied.push(`${name}=${value}`);
77
+ });
78
+ return address;
79
+ }
@@ -1,6 +1,7 @@
1
1
  /** Which page is shown: the profile, or the settings screen. It follows the address's hash. */
2
2
  import { signal } from "@preact/signals";
3
- export const pageFor = (hash) => hash === "#settings" ? "settings" : "profile";
3
+ /** The page a hash names; what follows a `?` is the address's params (address.ts). */
4
+ export const pageFor = (hash) => hash.split("?")[0] === "#settings" ? "settings" : "profile";
4
5
  export class NavigationStore {
5
6
  #page;
6
7
  constructor(hash) {
@@ -8,6 +8,10 @@ import { SurfaceStore } from "./surface-store.js";
8
8
  export class ProfileStore {
9
9
  deps;
10
10
  surface;
11
+ /** Embeds open now: none while the settings page shows, or before the first. */
12
+ #live = 0;
13
+ /** Asked for with no embed to show it: the next one starts there. */
14
+ #pending = null;
11
15
  constructor(deps) {
12
16
  this.deps = deps;
13
17
  this.surface = new SurfaceStore({ log: deps.log.append }, deps.slot.size);
@@ -16,6 +20,32 @@ export class ProfileStore {
16
20
  connect = (post) => {
17
21
  this.surface.reset();
18
22
  this.deps.toasts.reset();
19
- return new ProfileSession({ ...this.deps, surface: this.surface, post });
23
+ if (this.#pending !== null) {
24
+ this.surface.show(this.#pending);
25
+ this.#pending = null;
26
+ }
27
+ const session = new ProfileSession({
28
+ ...this.deps,
29
+ surface: this.surface,
30
+ post,
31
+ });
32
+ this.#live++;
33
+ return {
34
+ receive: session.receive,
35
+ loaded: session.loaded,
36
+ dispose: () => {
37
+ this.#live--;
38
+ session.dispose();
39
+ },
40
+ };
41
+ };
42
+ /** Shows the plugin inline, in its dialog or fullscreen: now, or as the next embed starts. */
43
+ show = (display) => {
44
+ if (this.#live > 0) {
45
+ this.surface.show(display);
46
+ }
47
+ else {
48
+ this.#pending = display;
49
+ }
20
50
  };
21
51
  }
@@ -3,6 +3,7 @@
3
3
  * transport it needs. Components reach it through `StudioContext` (ui/context.ts).
4
4
  */
5
5
  import { BrowserStorage } from "../transport/browser-storage.js";
6
+ import { readAddress } from "./address.js";
6
7
  import { timers } from "./draft.js";
7
8
  import { FailuresStore } from "./failures-store.js";
8
9
  import { LayoutStore } from "./layout-store.js";
@@ -83,6 +84,46 @@ export class Studio {
83
84
  failures: this.failures,
84
85
  });
85
86
  }
87
+ /**
88
+ * The address changed, or the page opened on it: the page follows its hash, and what its params
89
+ * ask for is set as if chosen in the sidebar, with a note in the log. Returns the hash to leave
90
+ * in the address, without the params, so a reload never sets them again.
91
+ */
92
+ followAddress = (hash) => {
93
+ const { page, changes, applied, ignored, clean } = readAddress(hash);
94
+ this.navigation.follow(page === "settings" ? "#settings" : "");
95
+ if (changes.type !== undefined) {
96
+ this.view.choose(changes.type);
97
+ }
98
+ if (changes.viewer !== undefined) {
99
+ this.view.viewer.set(changes.viewer);
100
+ }
101
+ if (changes.preferences !== undefined) {
102
+ this.view.choosePreset(changes.preferences);
103
+ }
104
+ if (changes.width !== undefined) {
105
+ this.slot.setWidth(changes.width);
106
+ }
107
+ if (changes.height !== undefined) {
108
+ this.slot.setHeight(changes.height);
109
+ }
110
+ if (changes.display !== undefined) {
111
+ this.profile.show(changes.display);
112
+ }
113
+ if (changes.credentials !== undefined) {
114
+ void this.failures.set("credentials", changes.credentials);
115
+ }
116
+ if (changes.token !== undefined) {
117
+ void this.failures.set("token", changes.token);
118
+ }
119
+ if (applied.length > 0) {
120
+ this.log.append("note", `From the address: ${applied.join(", ")}`);
121
+ }
122
+ if (ignored.length > 0) {
123
+ this.log.append("note", `From the address, ignored: ${ignored.join("; ")}`);
124
+ }
125
+ return clean;
126
+ };
86
127
  /** Reads what the server holds: the plugin, its saved settings, and the switched failures. */
87
128
  async start() {
88
129
  await Promise.all([
package/dist/page/main.js CHANGED
@@ -6,6 +6,7 @@ import { jsx as _jsx } from "preact/jsx-runtime";
6
6
  import { signal } from "@preact/signals";
7
7
  import { render } from "preact";
8
8
  import { Studio } from "./domain/studio.js";
9
+ import { mirrorToConsole } from "./transport/console-mirror.js";
9
10
  import { StudioApi } from "./transport/studio-api.js";
10
11
  import { boot } from "./ui/boot.js";
11
12
  import { StudioContext } from "./ui/context.js";
@@ -26,6 +27,17 @@ const studio = new Studio({
26
27
  hash: window.location.hash,
27
28
  viewportWidth,
28
29
  });
29
- window.addEventListener("hashchange", () => studio.navigation.follow(window.location.hash));
30
+ // Before anything is logged, so the console has it all.
31
+ mirrorToConsole(studio.log);
32
+ // The address's params are set once, then dropped, so a reload never sets them again.
33
+ const followAddress = () => {
34
+ const clean = studio.followAddress(window.location.hash);
35
+ if (clean !== window.location.hash) {
36
+ const { pathname, search } = window.location;
37
+ history.replaceState(history.state, "", `${pathname}${search}${clean}`);
38
+ }
39
+ };
40
+ followAddress();
41
+ window.addEventListener("hashchange", followAddress);
30
42
  window.addEventListener("pagehide", studio.flush);
31
43
  render(_jsx(StudioContext.Provider, { value: studio, children: _jsx(Root, { phase: boot(studio, root) }) }), root);
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The message log, mirrored to the browser console, where the browser tools coding agents use
3
+ * read it. One line per entry, prefixed `[studio]`. The plugin's messages are `debug`, which
4
+ * consoles hide unless asked (Chrome's "Verbose"; the Playwright MCP's `level: "debug"`); the
5
+ * studio's notes are warnings, since that's where a plugin's mistakes show.
6
+ */
7
+ import { effect } from "@preact/signals";
8
+ /** Past this, a payload is cut: a record can be long, and one line should stay readable. */
9
+ export const MAX_PAYLOAD_CHARS = 4000;
10
+ const ARROWS = { in: "←", out: "→", note: "·" };
11
+ /** An entry as one console line. */
12
+ export function consoleLine(entry) {
13
+ const parts = ["[studio]", ARROWS[entry.direction], entry.type];
14
+ if (entry.source !== undefined) {
15
+ parts.push(`(${entry.source})`);
16
+ }
17
+ if (entry.payload !== undefined) {
18
+ let json;
19
+ try {
20
+ json = JSON.stringify(entry.payload) ?? String(entry.payload);
21
+ }
22
+ catch {
23
+ json = String(entry.payload);
24
+ }
25
+ parts.push(json.length > MAX_PAYLOAD_CHARS
26
+ ? `${json.slice(0, MAX_PAYLOAD_CHARS)}… (${json.length - MAX_PAYLOAD_CHARS} more characters)`
27
+ : json);
28
+ }
29
+ return parts.join(" ");
30
+ }
31
+ /** Mirrors each entry as it's logged, those already logged first. Returns a stop. */
32
+ export function mirrorToConsole(log, out = console) {
33
+ let lastId = 0;
34
+ return effect(() => {
35
+ for (const entry of log.entries.value) {
36
+ if (entry.id > lastId) {
37
+ lastId = entry.id;
38
+ const line = consoleLine(entry);
39
+ if (entry.direction === "note") {
40
+ out.warn(line);
41
+ }
42
+ else {
43
+ out.debug(line);
44
+ }
45
+ }
46
+ }
47
+ });
48
+ }
package/dist/serve.js ADDED
@@ -0,0 +1,112 @@
1
+ /**
2
+ * `--serve <dir>`: a plugin that's plain files, served as a host would, so the studio can embed it
3
+ * with no dev server (backlog 039). It listens on a port of its own, so the plugin has an origin
4
+ * of its own, as Livespace requires. Every response allows any origin, as a host serving
5
+ * `jwks.json` must: Livespace reads it from another origin, and so does the studio's page.
6
+ */
7
+ import { readFile, stat } from "node:fs/promises";
8
+ import { createServer } from "node:http";
9
+ import { extname, join, resolve, sep } from "node:path";
10
+ import { PortInUse } from "./server.js";
11
+ const TYPES = {
12
+ ".html": "text/html; charset=utf-8",
13
+ ".css": "text/css; charset=utf-8",
14
+ ".js": "text/javascript; charset=utf-8",
15
+ ".mjs": "text/javascript; charset=utf-8",
16
+ ".json": "application/json; charset=utf-8",
17
+ ".svg": "image/svg+xml",
18
+ ".png": "image/png",
19
+ ".jpg": "image/jpeg",
20
+ ".jpeg": "image/jpeg",
21
+ ".gif": "image/gif",
22
+ ".webp": "image/webp",
23
+ ".ico": "image/x-icon",
24
+ ".woff2": "font/woff2",
25
+ ".txt": "text/plain; charset=utf-8",
26
+ ".md": "text/markdown; charset=utf-8",
27
+ };
28
+ const isFile = (path) => stat(path).then((s) => s.isFile(), () => false);
29
+ /**
30
+ * The file a request path names under `root`, or undefined when there's none or it would leave
31
+ * `root`. A directory gives its `index.html`.
32
+ */
33
+ export async function fileUnder(root, pathname) {
34
+ let decoded;
35
+ try {
36
+ decoded = decodeURIComponent(pathname);
37
+ }
38
+ catch {
39
+ return undefined;
40
+ }
41
+ if (decoded.includes("\0")) {
42
+ return undefined;
43
+ }
44
+ const base = resolve(root);
45
+ const path = resolve(join(base, decoded));
46
+ if (path !== base && !path.startsWith(base + sep)) {
47
+ return undefined;
48
+ }
49
+ if (await isFile(path)) {
50
+ return path;
51
+ }
52
+ const index = join(path, "index.html");
53
+ return (await isFile(index)) ? index : undefined;
54
+ }
55
+ /** Serves `dir` at http://localhost:<port>, until closed. */
56
+ export async function serveStatic(options) {
57
+ const server = createServer(async (request, response) => {
58
+ const headers = {
59
+ "Access-Control-Allow-Origin": "*",
60
+ "Cache-Control": "no-store",
61
+ };
62
+ if (request.method === "OPTIONS") {
63
+ response
64
+ .writeHead(204, {
65
+ ...headers,
66
+ "Access-Control-Allow-Headers": "*",
67
+ "Access-Control-Allow-Methods": "GET, HEAD",
68
+ })
69
+ .end();
70
+ return;
71
+ }
72
+ if (request.method !== "GET" && request.method !== "HEAD") {
73
+ response.writeHead(405, headers).end();
74
+ return;
75
+ }
76
+ const { pathname } = new URL(request.url ?? "/", "http://localhost");
77
+ const file = await fileUnder(options.dir, pathname);
78
+ if (file === undefined) {
79
+ response.writeHead(404, headers).end();
80
+ return;
81
+ }
82
+ try {
83
+ const body = await readFile(file);
84
+ response
85
+ .writeHead(200, {
86
+ ...headers,
87
+ "Content-Type": TYPES[extname(file).toLowerCase()] ?? "application/octet-stream",
88
+ })
89
+ .end(request.method === "HEAD" ? undefined : body);
90
+ }
91
+ catch {
92
+ response.writeHead(404, headers).end();
93
+ }
94
+ });
95
+ await new Promise((resolve, reject) => {
96
+ server.once("error", (error) => {
97
+ reject(error.code === "EADDRINUSE" ? new PortInUse(options.port) : error);
98
+ });
99
+ server.listen(options.port, "localhost", () => resolve());
100
+ });
101
+ const address = server.address();
102
+ const port = typeof address === "object" && address !== null
103
+ ? address.port
104
+ : options.port;
105
+ return {
106
+ url: `http://localhost:${port}/`,
107
+ close: () => new Promise((resolve) => {
108
+ server.closeAllConnections();
109
+ server.close(() => resolve());
110
+ }),
111
+ };
112
+ }
package/dist/start.js CHANGED
@@ -1,10 +1,11 @@
1
1
  /**
2
2
  * Starting the studio, a local stand-in for Livespace that embeds the plugin's page
3
3
  * (docs/adr/0007-studio-is-its-own-package.md). It embeds a page the author's own dev server
4
- * serves, and never starts one.
4
+ * serves, and never starts one. With `--serve`, a plugin that's plain files has no dev server, so
5
+ * the studio serves it, on the next port (docs/adr/0009-a-no-build-lane.md).
5
6
  */
6
- import { access } from "node:fs/promises";
7
- import { join } from "node:path";
7
+ import { access, stat } from "node:fs/promises";
8
+ import { join, relative } from "node:path";
8
9
  import { clientIdOf } from "./keys.js";
9
10
  import { readManifestText } from "./manifest.js";
10
11
  import { PortInUse } from "./server.js";
@@ -73,15 +74,44 @@ async function clientIdFor(options) {
73
74
  }
74
75
  return DEFAULT_CLIENT_ID;
75
76
  }
77
+ /** Serves `--serve`'s folder on the port after the studio's, or undefined without the flag. */
78
+ async function siteFor(options, port, deps) {
79
+ const folder = options.serve;
80
+ if (folder === undefined) {
81
+ return undefined;
82
+ }
83
+ if (options.url !== undefined) {
84
+ throw new UsageError("--serve and --url both say what to embed: give one of them.");
85
+ }
86
+ const isDir = await stat(folder).then((s) => s.isDirectory(), () => false);
87
+ if (!isDir) {
88
+ throw new UsageError(`--serve takes a folder, and ${folder} isn't one.`);
89
+ }
90
+ if (!(await exists(join(folder, "index.html")))) {
91
+ throw new UsageError(`--serve's folder has no index.html, the plugin's page: ${folder}`);
92
+ }
93
+ const sitePort = port === 65535 ? port - 1 : port + 1;
94
+ try {
95
+ return await deps.serve({ dir: folder, port: sitePort });
96
+ }
97
+ catch (error) {
98
+ if (error instanceof PortInUse) {
99
+ throw new UsageError(`Port ${sitePort}, where --serve serves the plugin, is in use. Move the studio with --port (the plugin takes the next port), or stop what's using it.`);
100
+ }
101
+ throw error;
102
+ }
103
+ }
76
104
  export async function start(options, deps) {
77
- const pluginUrl = await pluginUrlFor(options);
78
105
  const port = portFor(options);
106
+ const site = await siteFor(options, port, deps);
107
+ const pluginUrl = site?.url ?? (await pluginUrlFor(options));
79
108
  const clientId = await clientIdFor(options);
80
109
  let studio;
81
110
  try {
82
111
  studio = await deps.start({ port, pluginUrl, clientId, dir: options.dir });
83
112
  }
84
113
  catch (error) {
114
+ await site?.close();
85
115
  if (error instanceof PortInUse) {
86
116
  throw new UsageError(`Port ${port} is in use. Pick another with --port, or stop what's using it.`);
87
117
  }
@@ -89,9 +119,15 @@ export async function start(options, deps) {
89
119
  }
90
120
  const { print } = deps;
91
121
  print(`Plugin Studio: open ${studio.url}`);
92
- print(pluginUrl === null
93
- ? "Enter your plugin's address at the top of the page: any http or https page, a deployed one included."
94
- : `It embeds ${pluginUrl}; change the address at the top of the page. Start your dev server first, if it isn't running.`);
122
+ if (site !== undefined) {
123
+ const shown = relative(process.cwd(), options.serve ?? "") || ".";
124
+ print(`It serves ${shown} at ${site.url} and embeds it. After you change a file, reload the studio's page.`);
125
+ }
126
+ else {
127
+ print(pluginUrl === null
128
+ ? "Enter your plugin's address at the top of the page: any http or https page, a deployed one included."
129
+ : `It embeds ${pluginUrl}; change the address at the top of the page. Start your dev server first, if it isn't running.`);
130
+ }
95
131
  const env = {
96
132
  LIVESPACE_KEYS_URL: studio.keysUrl,
97
133
  LIVESPACE_AUTH_URL: studio.authUrl,
@@ -104,5 +140,6 @@ export async function start(options, deps) {
104
140
  print("Ctrl-C to stop.");
105
141
  await deps.untilStopped();
106
142
  await studio.close();
143
+ await site?.close();
107
144
  print("Stopped.");
108
145
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livespace/plugin-studio",
3
- "version": "0.1.0",
3
+ "version": "0.3.0-beta.1",
4
4
  "description": "Plugin Studio: try and debug a Livespace plugin locally, embedded as Livespace embeds it.",
5
5
  "author": "LS FE team",
6
6
  "license": "MIT",