@n6k.io/serve 0.3.0 → 0.3.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
@@ -4,18 +4,18 @@ Serve `.mdx` pages in the browser with live data from
4
4
  [n6kd](https://github.com/n6k-io/n6kd) or pykit `n6k database`.
5
5
 
6
6
  ```sh
7
- n6k-serve page.mdx # no data
8
- n6k-serve page.mdx --data ws://localhost:8080/ws # attached as `db`
9
- n6k-serve page.mdx --data nyc=ws://localhost:8080/ws --data sales=ws://localhost:7823/ws
10
- n6k-serve page.mdx --data nyc=ws://<token>@localhost:8080/ws # token sent to the server
11
- n6k-serve page.mdx --port 3000 # default 3000
7
+ n6k-serve page page.mdx # no data
8
+ n6k-serve page page.mdx --data ws://localhost:8080/ws # attached as `db`
9
+ n6k-serve page page.mdx --data nyc=ws://localhost:8080/ws --data sales=ws://localhost:7823/ws
10
+ n6k-serve page page.mdx --data nyc=ws://<token>@localhost:8080/ws # token sent to the server
11
+ n6k-serve page page.mdx --port 3000 # default 3000
12
12
  ```
13
13
 
14
14
  A token in `--data` is removed from the URL and sent as the connection token.
15
15
  Frontmatter `attach:` URLs may not carry one.
16
16
 
17
17
  ```sh
18
- n6k-serve page.mdx --data nyc=ws://localhost:8080/ws --oidc-login
18
+ n6k-serve page page.mdx --data nyc=ws://localhost:8080/ws --oidc-login
19
19
  ```
20
20
 
21
21
  `--oidc-login` signs in to every source without a token, using the server's
@@ -55,11 +55,11 @@ reloads when the file is saved.
55
55
  ## MCP
56
56
 
57
57
  ```sh
58
- claude mcp add n6k-serve -- bunx @n6k.io/serve --mcp
59
- claude mcp add n6k-serve -- bunx @n6k.io/serve --mcp --port 4000
58
+ claude mcp add n6k-serve -- bunx @n6k.io/serve mcp
59
+ claude mcp add n6k-serve -- bunx @n6k.io/serve mcp --port 4000
60
60
  ```
61
61
 
62
- `--mcp` serves pages at `/<page>/` and is driven over stdio by one MCP client.
62
+ `mcp` serves pages at `/<page>/` and is driven over stdio by one MCP client.
63
63
  It takes only `--port`, `--host` and `--origin`. Data
64
64
  sources and pages are set with MCP tools (see `tools/list`); frontmatter
65
65
  `attach:` is ignored. The process exits when stdin closes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n6k.io/serve",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "private": false,
5
5
  "description": "Serve .mdx pages with live data from n6kd or pykit",
6
6
  "repository": "https://github.com/n6k-io/js-serve",
@@ -34,6 +34,7 @@
34
34
  "@tailwindcss/oxide": "^4.3.5",
35
35
  "@tailwindcss/typography": "^0.5.20",
36
36
  "@tanstack/react-query": "^5.104.1",
37
+ "commander": "^15.1.0",
37
38
  "esbuild": "^0.28.2",
38
39
  "radix-ui": "^1.7.0",
39
40
  "react": "^19.3.0",
package/src/cli.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env bun
2
2
  import path from "node:path";
3
3
  import { existsSync, readFileSync } from "node:fs";
4
- import { parseArgs } from "node:util";
4
+ import { Command } from "commander";
5
5
  import { parseAttachUrls } from "@n6k.io/build/pipeline";
6
6
  import { DataArgError, resolveData, type DataSource } from "./data-args";
7
7
  import { bundlePage } from "./bundle";
@@ -25,94 +25,104 @@ import { LogoutError, logout } from "./logout";
25
25
  import { SRC_DIR } from "./paths";
26
26
  import pkg from "../package.json";
27
27
 
28
- const USAGE = `usage: n6k-serve <page.mdx> [--data [alias=]ws://…]... [--oidc-login] [options]
29
- n6k-serve --pages <pages.yml> [options]
30
- n6k-serve sql [--console] [--data [alias=]ws://…]... [--oidc-login] [options]
31
- n6k-serve --mcp [options]
32
- n6k-serve logout [ws://host[:port] | --all]
33
- options: [--port 3000] [--host 127.0.0.1] [--origin <origin>]...`;
34
-
35
28
  function fail(message: string): never {
36
29
  console.error(message);
37
30
  process.exit(1);
38
31
  }
39
32
 
40
- const { values, positionals } = parseArgs({
41
- args: process.argv.slice(2),
42
- options: {
43
- data: { type: "string", multiple: true, default: [] },
44
- pages: { type: "string" },
45
- mcp: { type: "boolean", default: false },
46
- console: { type: "boolean", default: false },
47
- "oidc-login": { type: "boolean", default: false },
48
- all: { type: "boolean", default: false },
49
- port: { type: "string", default: "3000" },
50
- host: { type: "string", default: "127.0.0.1" },
51
- origin: { type: "string", multiple: true, default: [] },
52
- },
53
- allowPositionals: true,
54
- strict: true,
55
- });
56
-
57
- if (positionals[0] === "logout") {
58
- if (positionals.length > 2 || (values.all && positionals.length === 2))
59
- fail(USAGE);
60
- try {
61
- for (const out of await logout(positionals[1], values.all))
62
- console.error(out);
63
- } catch (err) {
64
- if (err instanceof LogoutError) fail(err.message);
65
- throw err;
66
- }
67
- process.exit(0);
33
+ const collect = (value: string, acc: string[]): string[] => [...acc, value];
34
+
35
+ type ServerFlags = { port: string; host: string; origin: string[] };
36
+ type DataFlags = { data: string[]; oidcLogin: boolean };
37
+
38
+ function withServerFlags(cmd: Command): Command {
39
+ return cmd
40
+ .option("--port <port>", "port to listen on", "3000")
41
+ .option("--host <host>", "host to bind", "127.0.0.1")
42
+ .option("--origin <origin>", "allowed origin (repeatable)", collect, []);
68
43
  }
69
- if (values.all) fail(USAGE);
70
-
71
- const port = Number(values.port);
72
- if (!Number.isInteger(port) || port < 0)
73
- fail(`--port ${values.port}: not a port`);
74
- if (!hasWasmExtensions())
75
- fail("n6k duckdb wasm extensions missing from @n6k.io/db");
76
-
77
- const options: ServeOptions = {
78
- hostname: values.host,
79
- port,
80
- origins: values.origin,
81
- };
82
-
83
- if (values.console && positionals[0] !== "sql") fail(USAGE);
84
- if (values["oidc-login"] && (values.mcp || values.pages !== undefined))
85
- fail(USAGE);
86
-
87
- if (positionals[0] === "sql") {
88
- if (positionals.length !== 1 || values.mcp || values.pages !== undefined)
89
- fail(USAGE);
90
- await servePage(
91
- path.join(SRC_DIR, "sql", values.console ? "console.mdx" : "editor.mdx"),
92
- true,
93
- );
94
- } else if (values.mcp) {
95
- if (
96
- positionals.length > 0 ||
97
- values.pages !== undefined ||
98
- values.data.length > 0
99
- )
100
- fail(USAGE);
101
- serveMcp();
102
- } else if (values.pages === undefined) {
103
- if (positionals.length !== 1) fail(USAGE);
104
- await servePage(positionals[0]);
105
- } else {
106
- if (positionals.length > 0 || values.data.length > 0) fail(USAGE);
107
- servePages(values.pages);
44
+
45
+ function withDataFlags(cmd: Command): Command {
46
+ return cmd
47
+ .option("--data <[alias=]ws://…>", "data source (repeatable)", collect, [])
48
+ .option("--oidc-login", "sign in to data sources with OIDC", false);
49
+ }
50
+
51
+ function serveOptions(flags: ServerFlags): ServeOptions {
52
+ const port = Number(flags.port);
53
+ if (!Number.isInteger(port) || port < 0)
54
+ fail(`--port ${flags.port}: not a port`);
55
+ if (!hasWasmExtensions())
56
+ fail("n6k duckdb wasm extensions missing from @n6k.io/db");
57
+ return { hostname: flags.host, port, origins: flags.origin };
108
58
  }
109
59
 
110
- async function servePage(arg: string, bare = false): Promise<void> {
60
+ const program = new Command("n6k-serve")
61
+ .description(pkg.description)
62
+ .version(pkg.version);
63
+
64
+ withDataFlags(withServerFlags(program.command("page")))
65
+ .description("serve one .mdx page")
66
+ .argument("<page.mdx>")
67
+ .action(async (arg: string, flags: ServerFlags & DataFlags) => {
68
+ await servePage(arg, flags, serveOptions(flags));
69
+ });
70
+
71
+ withServerFlags(program.command("site"))
72
+ .description("serve the pages listed in a pages.yml")
73
+ .argument("<pages.yml>")
74
+ .action((arg: string, flags: ServerFlags) => {
75
+ servePages(arg, serveOptions(flags));
76
+ });
77
+
78
+ withDataFlags(withServerFlags(program.command("sql")))
79
+ .description("serve the SQL editor")
80
+ .option("--console", "serve the SQL console instead of the editor", false)
81
+ .action(async (flags: ServerFlags & DataFlags & { console: boolean }) => {
82
+ await servePage(
83
+ path.join(SRC_DIR, "sql", flags.console ? "console.mdx" : "editor.mdx"),
84
+ flags,
85
+ serveOptions(flags),
86
+ true,
87
+ );
88
+ });
89
+
90
+ withServerFlags(program.command("mcp"))
91
+ .description("serve pages driven by an MCP client over stdio")
92
+ .action((flags: ServerFlags) => {
93
+ serveMcp(serveOptions(flags));
94
+ });
95
+
96
+ program
97
+ .command("logout")
98
+ .description("list saved sign-ins, or sign out")
99
+ .argument("[url]", "ws://host[:port]")
100
+ .option("--all", "sign out of all", false)
101
+ .action(async (url: string | undefined, flags: { all: boolean }) => {
102
+ if (url !== undefined && flags.all)
103
+ fail("logout: give a URL or --all, not both");
104
+ try {
105
+ for (const out of await logout(url, flags.all)) console.error(out);
106
+ } catch (err) {
107
+ if (err instanceof LogoutError) fail(err.message);
108
+ throw err;
109
+ }
110
+ process.exit(0);
111
+ });
112
+
113
+ await program.parseAsync();
114
+
115
+ async function servePage(
116
+ arg: string,
117
+ flags: DataFlags,
118
+ options: ServeOptions,
119
+ bare = false,
120
+ ): Promise<void> {
111
121
  const mdxPath = path.resolve(arg);
112
122
  if (!mdxPath.endsWith(".mdx")) fail(`${arg}: not an .mdx file`);
113
123
  if (!existsSync(mdxPath)) fail(`${arg}: no such file`);
114
- const dataFlags = values.data;
115
- const logins = values["oidc-login"] ? new OidcLogins() : undefined;
124
+ const dataFlags = flags.data;
125
+ const logins = flags.oidcLogin ? new OidcLogins() : undefined;
116
126
 
117
127
  const login = async (
118
128
  sources: Record<string, DataSource>,
@@ -207,7 +217,7 @@ async function servePage(arg: string, bare = false): Promise<void> {
207
217
  });
208
218
  }
209
219
 
210
- function servePages(arg: string): void {
220
+ function servePages(arg: string, options: ServeOptions): void {
211
221
  const file = path.resolve(arg);
212
222
  const load = (): PagesConfig => parsePages(readFileSync(file, "utf8"), file);
213
223
 
@@ -234,7 +244,7 @@ function servePages(arg: string): void {
234
244
  });
235
245
  }
236
246
 
237
- function serveMcp(): void {
247
+ function serveMcp(options: ServeOptions): void {
238
248
  const site = new McpSite((key) => reloadPage(server, key));
239
249
  const server = startServer(site, options);
240
250
  console.error(`n6k-serve ${server.url}`);
package/src/mcp.test.ts CHANGED
@@ -16,7 +16,7 @@ type Reply = {
16
16
  };
17
17
 
18
18
  function spawnMcp(args: string[] = []) {
19
- const proc = Bun.spawn(["bun", CLI, "--mcp", "--port", "0", ...args], {
19
+ const proc = Bun.spawn(["bun", CLI, "mcp", "--port", "0", ...args], {
20
20
  stdin: "pipe",
21
21
  stdout: "pipe",
22
22
  stderr: "pipe",
@@ -75,13 +75,13 @@ test("secret URL sets the cookie the token route requires", async () => {
75
75
  expect(await ok.text()).toBe("tok");
76
76
  });
77
77
 
78
- test("--oidc-login is rejected with --mcp and --pages", async () => {
79
- for (const args of [["--mcp"], ["--pages", "x.yml"]]) {
78
+ test("--oidc-login is rejected by mcp and site", async () => {
79
+ for (const args of [["mcp"], ["site", "x.yml"]]) {
80
80
  const proc = Bun.spawn(
81
81
  ["bun", `${import.meta.dir}/cli.ts`, ...args, "--oidc-login"],
82
82
  { stdin: "ignore", stdout: "pipe", stderr: "pipe" },
83
83
  );
84
84
  expect(await proc.exited).toBe(1);
85
- expect(await new Response(proc.stderr).text()).toContain("usage:");
85
+ expect(await new Response(proc.stderr).text()).toContain("unknown option");
86
86
  }
87
87
  });