@n6k.io/serve 0.1.1 → 0.2.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 +21 -3
- package/package.json +7 -4
- package/src/assets.ts +0 -1
- package/src/bundle.ts +7 -2
- package/src/cli.ts +134 -35
- package/src/component-docs.ts +63 -0
- package/src/css.ts +3 -2
- package/src/data-args.test.ts +27 -5
- package/src/data-args.ts +29 -6
- package/src/mcp-instructions.ts +22 -0
- package/src/mcp.test.ts +227 -0
- package/src/mcp.ts +268 -0
- package/src/mdx-components.tsx +14 -5
- package/src/pages-site.ts +113 -0
- package/src/pages.test.ts +91 -0
- package/src/pages.ts +128 -0
- package/src/root.tsx +14 -16
- package/src/server.ts +96 -91
- package/src/sql/console.mdx +1 -0
- package/src/sql/editor.mdx +1 -0
- package/src/virtual-modules.d.ts +2 -2
- package/src/watch.ts +10 -2
package/README.md
CHANGED
|
@@ -1,15 +1,19 @@
|
|
|
1
1
|
# @n6k.io/serve
|
|
2
2
|
|
|
3
|
-
Serve
|
|
3
|
+
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
7
|
n6k-serve page.mdx # no data
|
|
8
8
|
n6k-serve page.mdx --data ws://localhost:8080/ws # attached as `db`
|
|
9
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
|
|
10
11
|
n6k-serve page.mdx --port 3000 # default 3000
|
|
11
12
|
```
|
|
12
13
|
|
|
14
|
+
A token in `--data` is removed from the URL and sent as the connection token.
|
|
15
|
+
Frontmatter `attach:` URLs may not carry one.
|
|
16
|
+
|
|
13
17
|
Or in the page's frontmatter (`--data` wins for the same alias):
|
|
14
18
|
|
|
15
19
|
```yaml
|
|
@@ -23,5 +27,19 @@ attach:
|
|
|
23
27
|
The alias is the catalog name on the server: `nyc=ws://…` attaches the
|
|
24
28
|
server's `nyc` catalog as `nyc`. A bare URL attaches the server's `db` catalog.
|
|
25
29
|
|
|
26
|
-
Every `@n6k.io/ui` component is available in the page without an
|
|
27
|
-
|
|
30
|
+
Every `@n6k.io/ui` component and control is available in the page without an
|
|
31
|
+
import. Controls are declared with directives, e.g.
|
|
32
|
+
`::Slider[n]{label="N" min=1 max=10 default=5}`, and read as `{n}`. The page
|
|
33
|
+
reloads when the file is saved.
|
|
34
|
+
|
|
35
|
+
## MCP
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
claude mcp add n6k-serve -- bunx @n6k.io/serve --mcp
|
|
39
|
+
claude mcp add n6k-serve -- bunx @n6k.io/serve --mcp --port 4000
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`--mcp` serves pages at `/<page>/` and is driven over stdio by one MCP client.
|
|
43
|
+
It takes `--port`, `--host` and `--origin`, not `--data` or `--pages`. Data
|
|
44
|
+
sources and pages are set with MCP tools (see `tools/list`); frontmatter
|
|
45
|
+
`attach:` is ignored. The process exits when stdin closes.
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@n6k.io/serve",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"private": false,
|
|
5
|
-
"description": "Serve
|
|
5
|
+
"description": "Serve .mdx pages with live data from n6kd or pykit",
|
|
6
6
|
"repository": "https://github.com/n6k-io/js-serve",
|
|
7
7
|
"license": "MIT",
|
|
8
8
|
"type": "module",
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
},
|
|
15
15
|
"scripts": {
|
|
16
16
|
"test": "bun test",
|
|
17
|
+
"tags": "bun scripts/tag-release.ts",
|
|
17
18
|
"typecheck": "tsc --noEmit",
|
|
18
19
|
"lint": "eslint .",
|
|
19
20
|
"fmt": "prettier --write --log-level=warn .",
|
|
@@ -23,10 +24,11 @@
|
|
|
23
24
|
},
|
|
24
25
|
"dependencies": {
|
|
25
26
|
"@duckdb/duckdb-wasm": "1.33.1-dev114.0",
|
|
27
|
+
"@modelcontextprotocol/server": "^2.4.0",
|
|
26
28
|
"@n6k.io/build": "^0.5.1",
|
|
27
29
|
"@n6k.io/db": "^0.13.1",
|
|
28
30
|
"@n6k.io/runtime": "^0.1.2",
|
|
29
|
-
"@n6k.io/ui": "^0.10.
|
|
31
|
+
"@n6k.io/ui": "^0.10.6",
|
|
30
32
|
"@tailwindcss/cli": "^4.3.3",
|
|
31
33
|
"@tailwindcss/typography": "^0.5.20",
|
|
32
34
|
"@tanstack/react-query": "^5.104.1",
|
|
@@ -36,7 +38,8 @@
|
|
|
36
38
|
"react-dom": "^19.3.0",
|
|
37
39
|
"shadcn": "^4.21.4",
|
|
38
40
|
"tailwindcss": "^4.3.3",
|
|
39
|
-
"tw-animate-css": "^1.4.0"
|
|
41
|
+
"tw-animate-css": "^1.4.0",
|
|
42
|
+
"zod": "^4"
|
|
40
43
|
},
|
|
41
44
|
"devDependencies": {
|
|
42
45
|
"@eslint/js": "^10.0.1",
|
package/src/assets.ts
CHANGED
|
@@ -30,7 +30,6 @@ function mime(file: string): string {
|
|
|
30
30
|
return N6K_WASM_MIME[path.extname(file)] ?? "application/octet-stream";
|
|
31
31
|
}
|
|
32
32
|
|
|
33
|
-
// duckdb runtime, n6k driver workers, n6k duckdb extensions and fontsource fonts; undefined if `pathname` is none of them.
|
|
34
33
|
export async function serveAsset(
|
|
35
34
|
pathname: string,
|
|
36
35
|
): Promise<Response | undefined> {
|
package/src/bundle.ts
CHANGED
|
@@ -15,16 +15,21 @@ import {
|
|
|
15
15
|
|
|
16
16
|
export type Bundle = Map<string, string>;
|
|
17
17
|
|
|
18
|
+
export type RootProps = {
|
|
19
|
+
data: Record<string, string>;
|
|
20
|
+
tokens: Record<string, string>;
|
|
21
|
+
};
|
|
22
|
+
|
|
18
23
|
export async function bundlePage(
|
|
19
24
|
mdxPath: string,
|
|
20
|
-
|
|
25
|
+
rootProps: RootProps,
|
|
21
26
|
): Promise<Bundle> {
|
|
22
27
|
const mdxDir = path.dirname(mdxPath);
|
|
23
28
|
const { entries, modules } = await preprocess(
|
|
24
29
|
{ index: mdxPath },
|
|
25
30
|
{
|
|
26
31
|
rootComponent: path.join(SRC_DIR, "root.tsx"),
|
|
27
|
-
rootProps
|
|
32
|
+
rootProps,
|
|
28
33
|
mdxComponents: path.join(SRC_DIR, "mdx-components.tsx"),
|
|
29
34
|
},
|
|
30
35
|
);
|
package/src/cli.ts
CHANGED
|
@@ -3,15 +3,30 @@ import path from "node:path";
|
|
|
3
3
|
import { existsSync, readFileSync } from "node:fs";
|
|
4
4
|
import { parseArgs } from "node:util";
|
|
5
5
|
import { parseAttachUrls } from "@n6k.io/build/pipeline";
|
|
6
|
-
import { DataArgError, resolveData } from "./data-args";
|
|
6
|
+
import { DataArgError, resolveData, type DataSource } from "./data-args";
|
|
7
7
|
import { bundlePage } from "./bundle";
|
|
8
8
|
import { buildCss } from "./css";
|
|
9
9
|
import { hasWasmExtensions } from "./assets";
|
|
10
|
-
import {
|
|
10
|
+
import { parsePages, type PagesConfig } from "./pages";
|
|
11
|
+
import { PagesSite } from "./pages-site";
|
|
12
|
+
import {
|
|
13
|
+
reloadPage,
|
|
14
|
+
startServer,
|
|
15
|
+
type PageState,
|
|
16
|
+
type ServeOptions,
|
|
17
|
+
type ServedPage,
|
|
18
|
+
type Site,
|
|
19
|
+
} from "./server";
|
|
11
20
|
import { watchFile } from "./watch";
|
|
21
|
+
import { McpSite, startMcp } from "./mcp";
|
|
22
|
+
import { SRC_DIR } from "./paths";
|
|
23
|
+
import pkg from "../package.json";
|
|
12
24
|
|
|
13
|
-
const USAGE =
|
|
14
|
-
|
|
25
|
+
const USAGE = `usage: n6k-serve <page.mdx> [--data [alias=]ws://…]... [options]
|
|
26
|
+
n6k-serve --pages <pages.yml> [options]
|
|
27
|
+
n6k-serve sql [--console] [--data [alias=]ws://…]... [options]
|
|
28
|
+
n6k-serve --mcp [options]
|
|
29
|
+
options: [--port 3000] [--host 127.0.0.1] [--origin <origin>]...`;
|
|
15
30
|
|
|
16
31
|
function fail(message: string): never {
|
|
17
32
|
console.error(message);
|
|
@@ -22,59 +37,143 @@ const { values, positionals } = parseArgs({
|
|
|
22
37
|
args: process.argv.slice(2),
|
|
23
38
|
options: {
|
|
24
39
|
data: { type: "string", multiple: true, default: [] },
|
|
40
|
+
pages: { type: "string" },
|
|
41
|
+
mcp: { type: "boolean", default: false },
|
|
42
|
+
console: { type: "boolean", default: false },
|
|
25
43
|
port: { type: "string", default: "3000" },
|
|
44
|
+
host: { type: "string", default: "127.0.0.1" },
|
|
45
|
+
origin: { type: "string", multiple: true, default: [] },
|
|
26
46
|
},
|
|
27
47
|
allowPositionals: true,
|
|
28
48
|
strict: true,
|
|
29
49
|
});
|
|
30
50
|
|
|
31
|
-
if (positionals.length !== 1) fail(USAGE);
|
|
32
|
-
const mdxPath = path.resolve(positionals[0]);
|
|
33
|
-
if (!mdxPath.endsWith(".mdx")) fail(`${positionals[0]}: not an .mdx file`);
|
|
34
|
-
if (!existsSync(mdxPath)) fail(`${positionals[0]}: no such file`);
|
|
35
51
|
const port = Number(values.port);
|
|
36
52
|
if (!Number.isInteger(port) || port < 0)
|
|
37
53
|
fail(`--port ${values.port}: not a port`);
|
|
38
54
|
if (!hasWasmExtensions())
|
|
39
55
|
fail("n6k duckdb wasm extensions missing from @n6k.io/db");
|
|
40
56
|
|
|
41
|
-
const
|
|
57
|
+
const options: ServeOptions = {
|
|
58
|
+
hostname: values.host,
|
|
59
|
+
port,
|
|
60
|
+
origins: values.origin,
|
|
61
|
+
};
|
|
42
62
|
|
|
43
|
-
|
|
63
|
+
if (values.console && positionals[0] !== "sql") fail(USAGE);
|
|
64
|
+
|
|
65
|
+
if (positionals[0] === "sql") {
|
|
66
|
+
if (positionals.length !== 1 || values.mcp || values.pages !== undefined)
|
|
67
|
+
fail(USAGE);
|
|
68
|
+
await servePage(
|
|
69
|
+
path.join(SRC_DIR, "sql", values.console ? "console.mdx" : "editor.mdx"),
|
|
70
|
+
);
|
|
71
|
+
} else if (values.mcp) {
|
|
72
|
+
if (
|
|
73
|
+
positionals.length > 0 ||
|
|
74
|
+
values.pages !== undefined ||
|
|
75
|
+
values.data.length > 0
|
|
76
|
+
)
|
|
77
|
+
fail(USAGE);
|
|
78
|
+
serveMcp();
|
|
79
|
+
} else if (values.pages === undefined) {
|
|
80
|
+
if (positionals.length !== 1) fail(USAGE);
|
|
81
|
+
await servePage(positionals[0]);
|
|
82
|
+
} else {
|
|
83
|
+
if (positionals.length > 0 || values.data.length > 0) fail(USAGE);
|
|
84
|
+
servePages(values.pages);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
async function servePage(arg: string): Promise<void> {
|
|
88
|
+
const mdxPath = path.resolve(arg);
|
|
89
|
+
if (!mdxPath.endsWith(".mdx")) fail(`${arg}: not an .mdx file`);
|
|
90
|
+
if (!existsSync(mdxPath)) fail(`${arg}: no such file`);
|
|
91
|
+
const dataFlags = values.data;
|
|
92
|
+
|
|
93
|
+
const resolveDataFor = (): Record<string, DataSource> =>
|
|
94
|
+
resolveData(parseAttachUrls(readFileSync(mdxPath, "utf8")), dataFlags);
|
|
95
|
+
|
|
96
|
+
const build = async (
|
|
97
|
+
sources: Record<string, DataSource>,
|
|
98
|
+
): Promise<PageState> => {
|
|
99
|
+
const entries = Object.entries(sources);
|
|
100
|
+
const [bundle, css] = await Promise.all([
|
|
101
|
+
bundlePage(mdxPath, {
|
|
102
|
+
data: Object.fromEntries(entries.map(([a, s]) => [a, s.url])),
|
|
103
|
+
tokens: Object.fromEntries(entries.map(([a, s]) => [a, s.token])),
|
|
104
|
+
}),
|
|
105
|
+
buildCss(mdxPath),
|
|
106
|
+
]);
|
|
107
|
+
return { bundle, css };
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
let data: Record<string, DataSource>;
|
|
44
111
|
try {
|
|
45
|
-
|
|
112
|
+
data = resolveDataFor();
|
|
46
113
|
} catch (err) {
|
|
47
114
|
if (err instanceof DataArgError) fail(err.message);
|
|
48
115
|
throw err;
|
|
49
116
|
}
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
117
|
+
let state = await build(data);
|
|
118
|
+
const page: ServedPage = {
|
|
119
|
+
title: path.basename(mdxPath),
|
|
120
|
+
key: "",
|
|
121
|
+
state: () => Promise.resolve(state),
|
|
122
|
+
};
|
|
123
|
+
const site: Site = {
|
|
124
|
+
resolve: (pathname) => ({ kind: "page", page, rest: pathname }),
|
|
125
|
+
page: (key) => (key === "" ? page : undefined),
|
|
126
|
+
};
|
|
127
|
+
const server = startServer(site, options);
|
|
59
128
|
|
|
60
|
-
|
|
61
|
-
const
|
|
129
|
+
console.error(`n6k-serve ${server.url}`);
|
|
130
|
+
for (const [alias, { url }] of Object.entries(data)) {
|
|
131
|
+
console.error(` ${alias} → ${url}`);
|
|
132
|
+
}
|
|
62
133
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
134
|
+
watchFile(mdxPath, async () => {
|
|
135
|
+
try {
|
|
136
|
+
const nextData = resolveDataFor();
|
|
137
|
+
state = await build(nextData);
|
|
138
|
+
data = nextData;
|
|
139
|
+
reloadPage(server, "");
|
|
140
|
+
console.error(`rebuilt ${path.basename(mdxPath)}`);
|
|
141
|
+
} catch (err) {
|
|
142
|
+
console.error(err instanceof Error ? err.message : String(err));
|
|
143
|
+
}
|
|
144
|
+
});
|
|
66
145
|
}
|
|
67
146
|
|
|
68
|
-
|
|
147
|
+
function servePages(arg: string): void {
|
|
148
|
+
const file = path.resolve(arg);
|
|
149
|
+
const load = (): PagesConfig => parsePages(readFileSync(file, "utf8"), file);
|
|
150
|
+
|
|
151
|
+
let config: PagesConfig;
|
|
69
152
|
try {
|
|
70
|
-
|
|
71
|
-
parseAttachUrls(readFileSync(mdxPath, "utf8")),
|
|
72
|
-
dataFlags,
|
|
73
|
-
);
|
|
74
|
-
Object.assign(state, await build(data));
|
|
75
|
-
reloadClients(server);
|
|
76
|
-
console.log(`rebuilt ${path.basename(mdxPath)}`);
|
|
153
|
+
config = load();
|
|
77
154
|
} catch (err) {
|
|
78
|
-
|
|
155
|
+
if (err instanceof Error) fail(err.message);
|
|
156
|
+
throw err;
|
|
79
157
|
}
|
|
80
|
-
|
|
158
|
+
|
|
159
|
+
const site = new PagesSite((key) => reloadPage(server, key));
|
|
160
|
+
site.update(config);
|
|
161
|
+
const server = startServer(site, options);
|
|
162
|
+
console.error(`n6k-serve ${server.url}`);
|
|
163
|
+
|
|
164
|
+
watchFile(file, () => {
|
|
165
|
+
try {
|
|
166
|
+
site.update(load());
|
|
167
|
+
console.error(`reloaded ${path.basename(file)}`);
|
|
168
|
+
} catch (err) {
|
|
169
|
+
console.error(err instanceof Error ? err.message : String(err));
|
|
170
|
+
}
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function serveMcp(): void {
|
|
175
|
+
const site = new McpSite((key) => reloadPage(server, key));
|
|
176
|
+
const server = startServer(site, options);
|
|
177
|
+
console.error(`n6k-serve ${server.url}`);
|
|
178
|
+
startMcp(site, server, pkg.version, () => process.exit(0));
|
|
179
|
+
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import docs from "@n6k.io/ui/docs.json";
|
|
2
|
+
|
|
3
|
+
type Prop = { type: string; required: boolean; description: string };
|
|
4
|
+
type Doc = { description: string; file: string; props: Record<string, Prop> };
|
|
5
|
+
|
|
6
|
+
export type ComponentDoc = {
|
|
7
|
+
name: string;
|
|
8
|
+
kind: "component" | "control";
|
|
9
|
+
description: string;
|
|
10
|
+
props: Record<string, Prop>;
|
|
11
|
+
usage?: string;
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
export type ComponentSummary = Pick<ComponentDoc, "name" | "kind"> & {
|
|
15
|
+
summary: string;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
function entries(
|
|
19
|
+
kind: ComponentDoc["kind"],
|
|
20
|
+
group: Record<string, Doc>,
|
|
21
|
+
): ComponentDoc[] {
|
|
22
|
+
return Object.entries(group).map(([name, { description, props }]) => ({
|
|
23
|
+
name,
|
|
24
|
+
kind,
|
|
25
|
+
description,
|
|
26
|
+
props,
|
|
27
|
+
...(kind === "control" && {
|
|
28
|
+
usage: `::${name}[var]{…props}, or :::${name}[var]{…props} children ::: to supply children; declares state \`var\`, read as {var}`,
|
|
29
|
+
}),
|
|
30
|
+
}));
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const ALL: ComponentDoc[] = [
|
|
34
|
+
...entries("component", docs.components),
|
|
35
|
+
...entries("control", docs.controls),
|
|
36
|
+
];
|
|
37
|
+
|
|
38
|
+
export function searchComponents(query = ""): ComponentSummary[] {
|
|
39
|
+
const q = query.toLowerCase();
|
|
40
|
+
return ALL.filter(
|
|
41
|
+
(d) =>
|
|
42
|
+
d.name.toLowerCase().includes(q) ||
|
|
43
|
+
d.description.toLowerCase().includes(q),
|
|
44
|
+
).map(({ name, kind, description }) => ({
|
|
45
|
+
name,
|
|
46
|
+
kind,
|
|
47
|
+
summary: description.split("\n", 1)[0],
|
|
48
|
+
}));
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export class UnknownComponentError extends Error {}
|
|
52
|
+
|
|
53
|
+
export function describeComponent(name: string): ComponentDoc {
|
|
54
|
+
const found = ALL.find((d) => d.name === name);
|
|
55
|
+
if (found) return found;
|
|
56
|
+
const q = name.toLowerCase();
|
|
57
|
+
const near = ALL.filter(
|
|
58
|
+
(d) => d.name.toLowerCase().includes(q) || q.includes(d.name.toLowerCase()),
|
|
59
|
+
).map((d) => d.name);
|
|
60
|
+
throw new UnknownComponentError(
|
|
61
|
+
`no component ${name}${near.length > 0 ? `; did you mean ${near.join(", ")}` : ""}`,
|
|
62
|
+
);
|
|
63
|
+
}
|
package/src/css.ts
CHANGED
|
@@ -8,8 +8,9 @@ const TAILWIND = path.join(SERVE_NODE_MODULES, ".bin", "tailwindcss");
|
|
|
8
8
|
|
|
9
9
|
export async function buildCss(mdxPath: string): Promise<string> {
|
|
10
10
|
mkdirSync(CACHE_DIR, { recursive: true });
|
|
11
|
-
const
|
|
12
|
-
const
|
|
11
|
+
const stem = `${process.pid}.${Bun.hash(mdxPath).toString(36)}`;
|
|
12
|
+
const input = path.join(CACHE_DIR, `${stem}.in.css`);
|
|
13
|
+
const output = path.join(CACHE_DIR, `${stem}.out.css`);
|
|
13
14
|
const base = readFileSync(path.join(SRC_DIR, "globals.css"), "utf8");
|
|
14
15
|
await Bun.write(
|
|
15
16
|
input,
|
package/src/data-args.test.ts
CHANGED
|
@@ -4,27 +4,30 @@ import { DataArgError, resolveData } from "./data-args";
|
|
|
4
4
|
describe("resolveData", () => {
|
|
5
5
|
test("bare URL attaches as db", () => {
|
|
6
6
|
expect(resolveData({}, ["ws://h:7823/ws"])).toEqual({
|
|
7
|
-
db: "ws://h:7823/ws",
|
|
7
|
+
db: { url: "ws://h:7823/ws", token: "" },
|
|
8
8
|
});
|
|
9
9
|
});
|
|
10
10
|
|
|
11
11
|
test("name=URL attaches as name", () => {
|
|
12
12
|
expect(resolveData({}, ["nyc=wss://h/ws", "sales=ws://h2/ws"])).toEqual({
|
|
13
|
-
nyc: "wss://h/ws",
|
|
14
|
-
sales: "ws://h2/ws",
|
|
13
|
+
nyc: { url: "wss://h/ws", token: "" },
|
|
14
|
+
sales: { url: "ws://h2/ws", token: "" },
|
|
15
15
|
});
|
|
16
16
|
});
|
|
17
17
|
|
|
18
18
|
test("a URL whose query contains = is still a bare URL", () => {
|
|
19
19
|
expect(resolveData({}, ["ws://h/ws?a=b"])).toEqual({
|
|
20
|
-
db: "ws://h/ws?a=b",
|
|
20
|
+
db: { url: "ws://h/ws?a=b", token: "" },
|
|
21
21
|
});
|
|
22
22
|
});
|
|
23
23
|
|
|
24
24
|
test("--data overrides frontmatter for the same alias", () => {
|
|
25
25
|
expect(
|
|
26
26
|
resolveData({ nyc: "ws://a/ws", other: "ws://o/ws" }, ["nyc=ws://b/ws"]),
|
|
27
|
-
).toEqual({
|
|
27
|
+
).toEqual({
|
|
28
|
+
nyc: { url: "ws://b/ws", token: "" },
|
|
29
|
+
other: { url: "ws://o/ws", token: "" },
|
|
30
|
+
});
|
|
28
31
|
});
|
|
29
32
|
|
|
30
33
|
test("bad alias is rejected", () => {
|
|
@@ -36,4 +39,23 @@ describe("resolveData", () => {
|
|
|
36
39
|
expect(() => resolveData({}, ["http://h/ws"])).toThrow(DataArgError);
|
|
37
40
|
expect(() => resolveData({}, ["db=localhost:7823"])).toThrow(DataArgError);
|
|
38
41
|
});
|
|
42
|
+
|
|
43
|
+
test("--data token rides userinfo and is stripped from the URL", () => {
|
|
44
|
+
expect(resolveData({}, ["nyc=ws://s%40cret@h:1/ws"])).toEqual({
|
|
45
|
+
nyc: { url: "ws://h:1/ws", token: "s@cret" },
|
|
46
|
+
});
|
|
47
|
+
expect(resolveData({}, ["ws://tok@h/ws"])).toEqual({
|
|
48
|
+
db: { url: "ws://h/ws", token: "tok" },
|
|
49
|
+
});
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
test("user:password is rejected", () => {
|
|
53
|
+
expect(() => resolveData({}, ["ws://u:p@h/ws"])).toThrow(DataArgError);
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
test("frontmatter credentials are rejected", () => {
|
|
57
|
+
expect(() => resolveData({ nyc: "ws://tok@h/ws" }, [])).toThrow(
|
|
58
|
+
DataArgError,
|
|
59
|
+
);
|
|
60
|
+
});
|
|
39
61
|
});
|
package/src/data-args.ts
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
const ALIAS = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
1
|
+
export const ALIAS = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
2
2
|
const DEFAULT_ALIAS = "db";
|
|
3
3
|
|
|
4
4
|
export class DataArgError extends Error {}
|
|
5
5
|
|
|
6
|
+
export type DataSource = { url: string; token: string };
|
|
7
|
+
|
|
6
8
|
function checked(alias: string, url: string, source: string): [string, string] {
|
|
7
9
|
if (!ALIAS.test(alias)) {
|
|
8
10
|
throw new DataArgError(
|
|
@@ -26,19 +28,40 @@ function parseFlag(flag: string): [string, string] {
|
|
|
26
28
|
return checked(flag.slice(0, eq), flag.slice(eq + 1), "--data");
|
|
27
29
|
}
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
function splitToken(raw: string, source: string): DataSource {
|
|
32
|
+
if (!URL.canParse(raw)) {
|
|
33
|
+
throw new DataArgError(`${source}: ${JSON.stringify(raw)} is not a URL`);
|
|
34
|
+
}
|
|
35
|
+
const url = new URL(raw);
|
|
36
|
+
if (!url.username && !url.password) return { url: raw, token: "" };
|
|
37
|
+
if (source !== "--data") {
|
|
38
|
+
throw new DataArgError(
|
|
39
|
+
`${source}: credentials in ${JSON.stringify(url.host)} are only accepted from --data`,
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
if (url.password) {
|
|
43
|
+
throw new DataArgError(
|
|
44
|
+
`${source}: use ws://<token>@host, not user:password`,
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
const token = decodeURIComponent(url.username);
|
|
48
|
+
url.username = "";
|
|
49
|
+
return { url: url.href, token };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
// Alias → source. The alias is also the server catalog name the client attaches.
|
|
30
53
|
export function resolveData(
|
|
31
54
|
frontmatterUrls: Record<string, string>,
|
|
32
55
|
dataFlags: string[],
|
|
33
|
-
): Record<string,
|
|
34
|
-
const out: Record<string,
|
|
56
|
+
): Record<string, DataSource> {
|
|
57
|
+
const out: Record<string, DataSource> = {};
|
|
35
58
|
for (const [alias, url] of Object.entries(frontmatterUrls)) {
|
|
36
59
|
const [a, u] = checked(alias, url, "attach:");
|
|
37
|
-
out[a] = u;
|
|
60
|
+
out[a] = splitToken(u, "attach:");
|
|
38
61
|
}
|
|
39
62
|
for (const flag of dataFlags) {
|
|
40
63
|
const [a, u] = parseFlag(flag);
|
|
41
|
-
out[a] = u;
|
|
64
|
+
out[a] = splitToken(u, "--data");
|
|
42
65
|
}
|
|
43
66
|
return out;
|
|
44
67
|
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export const INSTRUCTIONS = `n6k-serve renders MDX pages in the browser with live data.
|
|
2
|
+
|
|
3
|
+
Pages
|
|
4
|
+
- set_page takes an absolute .mdx path or inline mdx and returns the page URL, or the build error.
|
|
5
|
+
- Every @n6k.io/ui component and control is in scope without imports. Find them with search_components and read props with describe_component.
|
|
6
|
+
|
|
7
|
+
Data
|
|
8
|
+
- set_data(alias, url, token) attaches the gateway's catalog named \`alias\`. Queries run in DuckDB (wasm) in the browser; reference tables as \`alias.table\`.
|
|
9
|
+
- Components read data via props such as \`data\` (a relation), \`value\` (a measure expression, e.g. \`sum(amount)\`) or \`query\` (full SQL).
|
|
10
|
+
- set_data and remove_data rebuild and reload every page.
|
|
11
|
+
|
|
12
|
+
Controls
|
|
13
|
+
- Leaf form declares state and renders the control:
|
|
14
|
+
::Slider[sims]{label="Simulations" min=1000 max=500000 default=100000}
|
|
15
|
+
::Select[category]{label="Category" options="Hardware,Software,Services" empty="All"}
|
|
16
|
+
- Container form supplies its own markup:
|
|
17
|
+
:::Select[month]{default="2020-09"}
|
|
18
|
+
<SelectTrigger><SelectValue /></SelectTrigger>
|
|
19
|
+
<SelectContent><SelectItem value="2020-09">Sep 2020</SelectItem></SelectContent>
|
|
20
|
+
:::
|
|
21
|
+
- The bracketed name is a variable usable in expressions, e.g. filters={{ category }} or query={\`SELECT … LIMIT \${sims}\`}.
|
|
22
|
+
- Attributes are strings coerced to numbers/booleans; \`options\` and \`default\` split on commas; an option "value:label" sets a separate label.`;
|