@eserstack/noskills-web 0.0.0-stage → 5.0.0

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.
Files changed (41) hide show
  1. package/LICENSE +13 -0
  2. package/README.md +247 -2
  3. package/dist/auth.d.ts +50 -0
  4. package/dist/auth.js +107 -0
  5. package/dist/mod.d.ts +13 -0
  6. package/dist/mod.js +11 -0
  7. package/dist/request-context.d.ts +35 -0
  8. package/dist/request-context.js +19 -0
  9. package/dist/routes/api.d.ts +45 -0
  10. package/dist/routes/api.js +167 -0
  11. package/dist/routes/pages.d.ts +20 -0
  12. package/dist/routes/pages.js +80 -0
  13. package/dist/routes/sse.d.ts +15 -0
  14. package/dist/routes/sse.js +61 -0
  15. package/dist/routes/static.d.ts +10 -0
  16. package/dist/routes/static.js +52 -0
  17. package/dist/server.d.ts +53 -0
  18. package/dist/server.js +228 -0
  19. package/dist/static/client.js +257 -0
  20. package/dist/static/icons/icon.svg +12 -0
  21. package/dist/static/manifest.json +17 -0
  22. package/dist/static/mux-remote.js +192 -0
  23. package/dist/static/mux-render.js +224 -0
  24. package/dist/static/style.css +391 -0
  25. package/dist/static/sw-register.js +31 -0
  26. package/dist/static/sw.js +109 -0
  27. package/dist/templates/components.d.ts +17 -0
  28. package/dist/templates/components.js +89 -0
  29. package/dist/templates/dashboard.d.ts +8 -0
  30. package/dist/templates/dashboard.js +28 -0
  31. package/dist/templates/escape.d.ts +8 -0
  32. package/dist/templates/escape.js +14 -0
  33. package/dist/templates/layout.d.ts +12 -0
  34. package/dist/templates/layout.js +83 -0
  35. package/dist/templates/spec-detail.d.ts +7 -0
  36. package/dist/templates/spec-detail.js +83 -0
  37. package/dist/terminal/mux-host.d.ts +65 -0
  38. package/dist/terminal/mux-host.js +166 -0
  39. package/dist/terminal/ws-bridge.d.ts +9 -0
  40. package/dist/terminal/ws-bridge.js +26 -0
  41. package/package.json +32 -3
@@ -0,0 +1,167 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * JSON API routes — dashboard actions.
4
+ *
5
+ * @module
6
+ */
7
+ import * as dashboard from "@eserstack/noskills/dashboard";
8
+ import { runtime } from "@eserstack/standards/cross-runtime";
9
+ /**
10
+ * Opt-in switch that appends the underlying error text to fault responses.
11
+ *
12
+ * Off unless explicitly set, so a plain `noskills web` never ships internal
13
+ * detail to a caller; a developer chasing a bug has to ask for it by name.
14
+ */
15
+ const debugErrorsEnabled = () => {
16
+ const value = runtime.env.get("NOSKILLS_WEB_DEBUG_ERRORS");
17
+ return value === "1" || value === "true";
18
+ };
19
+ const json = (data, status = 200) => new Response(JSON.stringify(data), {
20
+ status,
21
+ headers: { "content-type": "application/json" },
22
+ });
23
+ /**
24
+ * Serialize a rejection as `{ ok: false, error }`, the shape the dashboard
25
+ * client and the REST callers read. `reason` is the whole story here (a wrong
26
+ * phase, an unknown action), so nothing is logged.
27
+ */
28
+ const jsonError = (reason, status) => json({ ok: false, error: reason }, status);
29
+ /**
30
+ * Log a caught fault under the request id and answer
31
+ * `{ ok: false, error, requestId }`.
32
+ *
33
+ * `reason` is written at the call site; it is never derived from `cause`, and
34
+ * `cause` never reaches the wire. Everything below this layer reports faults
35
+ * as a bare `Error` carrying whatever the runtime threw, such as
36
+ * `NotFound: ... open '/Users/<name>/<repo>/.eser/specs/<spec>/state.json'`, so
37
+ * forwarding its message or stack would map out the host's directory layout
38
+ * and the internal module structure for the caller. The token guard narrows
39
+ * who can ask, but it is a single per-process secret embedded in the dashboard
40
+ * HTML, not a reason to answer with a stack trace. The detail goes to the log
41
+ * instead, and the request id in the response leads to it.
42
+ *
43
+ * @param context - The request the fault happened in
44
+ * @param reason - What failed, in words the user can act on
45
+ * @param status - The HTTP status of the response
46
+ * @param cause - The caught error; logged, never sent
47
+ * @returns The JSON failure response
48
+ */
49
+ export const faultResponse = async (context, reason, status, cause) => {
50
+ await context.log.with({ error: cause }).error(reason);
51
+ const body = {
52
+ ok: false,
53
+ error: reason,
54
+ requestId: context.requestId,
55
+ };
56
+ // The error text only, as the Go dashboard sends: a stack would add the
57
+ // module paths of this process. A thrown value that is not an Error has no
58
+ // error text and adds no detail; the log has both.
59
+ if (debugErrorsEnabled() && cause instanceof Error) {
60
+ body["detail"] = cause.message;
61
+ }
62
+ return json(body, status);
63
+ };
64
+ /** A string field of a JSON request body; "" when it is missing or not a string. */
65
+ const stringField = (body, key) => {
66
+ const value = body[key];
67
+ return typeof value === "string" ? value : "";
68
+ };
69
+ /** The acting user of a JSON request body, when it carries a name and an email. */
70
+ const userField = (body) => {
71
+ const value = body["user"];
72
+ if (!(value instanceof Object)) {
73
+ return undefined;
74
+ }
75
+ const { name, email } = value;
76
+ if (typeof name !== "string" || typeof email !== "string") {
77
+ return undefined;
78
+ }
79
+ return { name, email };
80
+ };
81
+ /** GET /api/state — Full dashboard state. */
82
+ export const handleGetState = async (root) => {
83
+ const state = await dashboard.getState(root);
84
+ return json(state);
85
+ };
86
+ /**
87
+ * GET /api/spec/:name/ledger | summary — read-only decision-ledger data.
88
+ * `ledger` returns the full records + summary; `summary` returns only the
89
+ * maturity summary. Missing files yield empty records / null summary, never 404.
90
+ */
91
+ export const handleSpecRead = async (root, specName, kind) => {
92
+ const summary = await dashboard.readSummary(root, specName);
93
+ if (kind === "summary") {
94
+ return json({ ok: true, spec: specName, summary });
95
+ }
96
+ const records = await dashboard.readLedger(root, specName);
97
+ return json({ ok: true, spec: specName, records, summary });
98
+ };
99
+ /**
100
+ * POST /api/spec/:name/:action: run one dashboard action on a spec.
101
+ *
102
+ * The actions are the ones `@eserstack/noskills/dashboard` implements. The spec
103
+ * page offers only these; a button for any other action would answer 400 on
104
+ * every click (server.test.ts checks the buttons of every phase).
105
+ */
106
+ export const handleAction = async (root, specName, action, body, host, context) => {
107
+ const user = userField(body);
108
+ let result;
109
+ switch (action) {
110
+ case "approve":
111
+ result = await dashboard.approve(root, specName, user);
112
+ break;
113
+ case "note":
114
+ result = await dashboard.addNote(root, specName, stringField(body, "text"), user);
115
+ break;
116
+ case "question":
117
+ result = await dashboard.addQuestion(root, specName, stringField(body, "text"), user);
118
+ break;
119
+ case "signoff":
120
+ result = await dashboard.signoff(root, specName, user);
121
+ break;
122
+ case "reply":
123
+ result = await dashboard.replyMention(root, specName, stringField(body, "mentionId"), stringField(body, "text"), user);
124
+ break;
125
+ case "complete":
126
+ result = await dashboard.complete(root, specName, user);
127
+ break;
128
+ default:
129
+ return jsonError(`Unknown action: ${action}`, 400);
130
+ }
131
+ if (!result.ok) {
132
+ // A rejection the dashboard layer decided on is safe to repeat back and is
133
+ // the only useful thing to say — "Cannot approve in phase: SPEC_PROPOSAL"
134
+ // tells the user what to do, whereas the generic string leaves them
135
+ // guessing. Anything else is a caught fault whose message may carry host
136
+ // paths, so it stays generic and goes to the log instead.
137
+ if (result.error instanceof dashboard.ActionRejectedError) {
138
+ return jsonError(result.error.message, 400);
139
+ }
140
+ return await faultResponse({ ...context, log: context.log.with({ spec: specName, action }) }, "Action could not be completed", 400, result.error);
141
+ }
142
+ // Notify the pane bound to this spec, without stealing focus from the user.
143
+ // The notice is typed into the agent's PTY, so the name from the request body
144
+ // loses its control characters: a "\r" would submit, an ESC start a sequence.
145
+ const userName = (user?.name ?? "someone").replace(/\p{Cc}/gu, "");
146
+ host.notifySpec(specName, `\n[noskills: spec ${specName} ${action} by ${userName}]\n`);
147
+ return json({ ok: true });
148
+ };
149
+ /** POST /api/tab — Create a new tab. */
150
+ export const handleCreateTab = async (host, body) => {
151
+ const spec = body["spec"];
152
+ const tab = await host.createTab(typeof spec === "string" ? spec : undefined);
153
+ return json({ ok: true, tabId: tab.id, specName: tab.specName });
154
+ };
155
+ /** DELETE /api/tab/:id — Close a tab. */
156
+ export const handleCloseTab = (host, tabId) => {
157
+ host.closeTab(tabId);
158
+ return json({ ok: true });
159
+ };
160
+ /** GET /api/tabs — List tabs. */
161
+ export const handleListTabs = (host) => {
162
+ const tabs = host.listTabs().map((t) => ({
163
+ id: t.id,
164
+ specName: t.specName,
165
+ }));
166
+ return json(tabs);
167
+ };
@@ -0,0 +1,20 @@
1
+ import type { MuxHost } from "../terminal/mux-host.ts";
2
+ /** GET / — Dashboard page. */
3
+ export declare const handleDashboard: (root: string, host: MuxHost, token?: string) => Promise<Response>;
4
+ /** The 404 of a spec that has no directory, or a name that cannot be one. */
5
+ export declare const specNotFound: () => Response;
6
+ /**
7
+ * Whether `name` can name one directory under `.eser/specs/` without leaving
8
+ * it: not empty, not `.` or `..`, and without a separator or a NUL.
9
+ */
10
+ export declare const isSpecDirName: (name: string) => boolean;
11
+ /**
12
+ * The spec a `/spec/:name` path segment names: the segment percent-decoded,
13
+ * or `null` when it does not decode or does not name one spec directory.
14
+ */
15
+ export declare const specNameFromPath: (segment: string) => string | null;
16
+ /**
17
+ * GET /spec/:name — Spec detail page. The page carries the token, as the
18
+ * dashboard does, so its buttons can send the actions.
19
+ */
20
+ export declare const handleSpecDetail: (root: string, specName: string, token?: string) => Promise<Response>;
@@ -0,0 +1,80 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * HTML page routes.
4
+ *
5
+ * @module
6
+ */
7
+ import * as dashboard from "@eserstack/noskills/dashboard";
8
+ import { runtime } from "@eserstack/standards/cross-runtime";
9
+ import * as dashboardTemplate from "../templates/dashboard.js";
10
+ import * as specDetail from "../templates/spec-detail.js";
11
+ import * as layout from "../templates/layout.js";
12
+ /** GET / — Dashboard page. */
13
+ export const handleDashboard = async (root, host, token) => {
14
+ const state = await dashboard.getState(root);
15
+ const tabs = host.listTabs().map((t) => ({
16
+ id: t.id,
17
+ specName: t.specName,
18
+ phase: null,
19
+ }));
20
+ const activeTabId = tabs.length > 0 ? tabs[0].id : null;
21
+ const html = dashboardTemplate.renderDashboard(state, tabs, activeTabId, token);
22
+ return new Response(html, {
23
+ headers: layout.htmlHeaders(),
24
+ });
25
+ };
26
+ /** The 404 of a spec that has no directory, or a name that cannot be one. */
27
+ export const specNotFound = () => new Response("Spec not found", { status: 404 });
28
+ /**
29
+ * Whether `name` can name one directory under `.eser/specs/` without leaving
30
+ * it: not empty, not `.` or `..`, and without a separator or a NUL.
31
+ */
32
+ export const isSpecDirName = (name) => name !== "" &&
33
+ name !== "." &&
34
+ name !== ".." &&
35
+ !/[/\\]/.test(name) &&
36
+ !name.includes("\0");
37
+ /**
38
+ * The spec a `/spec/:name` path segment names: the segment percent-decoded,
39
+ * or `null` when it does not decode or does not name one spec directory.
40
+ */
41
+ export const specNameFromPath = (segment) => {
42
+ let name;
43
+ try {
44
+ name = decodeURIComponent(segment);
45
+ }
46
+ catch {
47
+ return null;
48
+ }
49
+ return isSpecDirName(name) ? name : null;
50
+ };
51
+ /**
52
+ * GET /spec/:name — Spec detail page. The page carries the token, as the
53
+ * dashboard does, so its buttons can send the actions.
54
+ */
55
+ export const handleSpecDetail = async (root, specName, token) => {
56
+ if (!isSpecDirName(specName)) {
57
+ return specNotFound();
58
+ }
59
+ try {
60
+ // Check spec directory exists
61
+ await runtime.fs.stat(`${root}/.eser/specs/${specName}`);
62
+ }
63
+ catch {
64
+ return specNotFound();
65
+ }
66
+ const spec = await dashboard.getSpecSummary(root, specName);
67
+ const state = await dashboard.getState(root);
68
+ // Read spec markdown
69
+ let specContent = "";
70
+ try {
71
+ specContent = await runtime.fs.readTextFile(`${root}/.eser/specs/${specName}/spec.md`);
72
+ }
73
+ catch {
74
+ // No spec.md yet
75
+ }
76
+ const html = specDetail.renderSpecDetail(spec, specContent, state.currentUser, token);
77
+ return new Response(html, {
78
+ headers: layout.htmlHeaders(),
79
+ });
80
+ };
@@ -0,0 +1,15 @@
1
+ /**
2
+ * SSE event stream — pushes dashboard events to connected clients.
3
+ *
4
+ * @module
5
+ */
6
+ import * as dashboard from "@eserstack/noskills/dashboard";
7
+ /** Subscribes to dashboard events and returns the function that unsubscribes. */
8
+ export type WatchEvents = typeof dashboard.watchEvents;
9
+ /**
10
+ * GET /events: the Server-Sent Events stream of dashboard events.
11
+ *
12
+ * `watchEvents` defaults to the dashboard's event-file watcher; tests pass a
13
+ * fake to observe the subscription without polling the file system.
14
+ */
15
+ export declare const handleSSE: (root: string, watchEvents?: WatchEvents) => Response;
@@ -0,0 +1,61 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * SSE event stream — pushes dashboard events to connected clients.
4
+ *
5
+ * @module
6
+ */
7
+ import * as dashboard from "@eserstack/noskills/dashboard";
8
+ /** A comment frame every 30 s keeps proxies from closing an idle stream. */
9
+ const KEEPALIVE_INTERVAL_MS = 30_000;
10
+ /**
11
+ * GET /events: the Server-Sent Events stream of dashboard events.
12
+ *
13
+ * `watchEvents` defaults to the dashboard's event-file watcher; tests pass a
14
+ * fake to observe the subscription without polling the file system.
15
+ */
16
+ export const handleSSE = (root, watchEvents = dashboard.watchEvents) => {
17
+ const encoder = new TextEncoder();
18
+ // The watcher and the keepalive timer belong to this stream: start() creates
19
+ // them, and cancel() (the client disconnected) or a failed enqueue releases
20
+ // them, so a closed tab leaves no polling behind.
21
+ let unsubscribe = null;
22
+ let keepalive = null;
23
+ const release = () => {
24
+ if (keepalive !== null) {
25
+ clearInterval(keepalive);
26
+ keepalive = null;
27
+ }
28
+ if (unsubscribe !== null) {
29
+ unsubscribe();
30
+ unsubscribe = null;
31
+ }
32
+ };
33
+ const stream = new ReadableStream({
34
+ start(controller) {
35
+ const send = (chunk) => {
36
+ try {
37
+ controller.enqueue(encoder.encode(chunk));
38
+ }
39
+ catch {
40
+ // The stream is already closed; stop producing for it.
41
+ release();
42
+ }
43
+ };
44
+ send(": connected\n\n");
45
+ unsubscribe = watchEvents(root, (event) => {
46
+ send(`data: ${JSON.stringify(event)}\n\n`);
47
+ });
48
+ keepalive = setInterval(() => send(": keepalive\n\n"), KEEPALIVE_INTERVAL_MS);
49
+ },
50
+ cancel() {
51
+ release();
52
+ },
53
+ });
54
+ return new Response(stream, {
55
+ headers: {
56
+ "content-type": "text/event-stream",
57
+ "cache-control": "no-cache",
58
+ connection: "keep-alive",
59
+ },
60
+ });
61
+ };
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Answer with the file at `path` under `staticDir`, byte for byte, or 404
3
+ * when there is no such file, the path leaves the directory, or there is no
4
+ * directory (`null`: the module was loaded from a remote URL).
5
+ *
6
+ * @param staticDir - The directory the files are served from
7
+ * @param path - The file's path relative to `staticDir`
8
+ * @returns The file, or a 404
9
+ */
10
+ export declare const serveStatic: (staticDir: string | null, path: string) => Promise<Response>;
@@ -0,0 +1,52 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Static file route: the browser scripts, the stylesheet, the icons and the
4
+ * PWA files.
5
+ *
6
+ * @module
7
+ */
8
+ import { runtime } from "@eserstack/standards/cross-runtime";
9
+ const MIME_TYPES = {
10
+ ".css": "text/css",
11
+ ".js": "application/javascript",
12
+ ".html": "text/html",
13
+ ".json": "application/json",
14
+ ".png": "image/png",
15
+ ".svg": "image/svg+xml",
16
+ };
17
+ const notFound = () => new Response("Not found", { status: 404 });
18
+ /**
19
+ * Answer with the file at `path` under `staticDir`, byte for byte, or 404
20
+ * when there is no such file, the path leaves the directory, or there is no
21
+ * directory (`null`: the module was loaded from a remote URL).
22
+ *
23
+ * @param staticDir - The directory the files are served from
24
+ * @param path - The file's path relative to `staticDir`
25
+ * @returns The file, or a 404
26
+ */
27
+ export const serveStatic = async (staticDir, path) => {
28
+ if (staticDir === null) {
29
+ return notFound();
30
+ }
31
+ // Join against the static dir, then guard against path traversal in a
32
+ // separator-agnostic way: the resolved file must stay inside staticDir.
33
+ const filePath = runtime.path.join(staticDir, path);
34
+ const rel = runtime.path.relative(staticDir, filePath);
35
+ if (rel.startsWith("..") || runtime.path.isAbsolute(rel)) {
36
+ return notFound();
37
+ }
38
+ let content;
39
+ try {
40
+ // Bytes, not text: decoding as UTF-8 would corrupt an image.
41
+ content = await runtime.fs.readFile(filePath);
42
+ }
43
+ catch {
44
+ return notFound();
45
+ }
46
+ const contentType = MIME_TYPES[runtime.path.extname(filePath)] ?? "application/octet-stream";
47
+ // readFile's type allows any ArrayBufferLike, a Response body only an
48
+ // ArrayBuffer-backed view: the copy is one.
49
+ return new Response(new Uint8Array(content), {
50
+ headers: { "content-type": contentType },
51
+ });
52
+ };
@@ -0,0 +1,53 @@
1
+ import * as requestContext from "./request-context.ts";
2
+ /** Answers one request within its {@link requestContext.RequestContext}. */
3
+ export type ContextHandler = (request: Request, context: requestContext.RequestContext) => Promise<Response>;
4
+ /**
5
+ * Give every request a context, and turn an error that `handler` throws into a
6
+ * logged fault: the record carries the request id, and the client gets a 500
7
+ * with the same id instead of the error.
8
+ *
9
+ * @param handler - Answers the request
10
+ * @param logger - Receives the error records
11
+ * @returns The handler to serve
12
+ */
13
+ export declare const withFaultBoundary: (handler: ContextHandler, logger: requestContext.RequestLogger) => ((request: Request) => Promise<Response>);
14
+ /** The address the server listens on, as {@link ServerOptions.onListen} gets it. */
15
+ export type ListenAddress = {
16
+ /** Always 127.0.0.1. */
17
+ readonly hostname: string;
18
+ /** The bound port; the one the system picked when `port` was 0. */
19
+ readonly port: number;
20
+ };
21
+ /** Options for {@link startServer}. */
22
+ export type ServerOptions = {
23
+ /** Project root that holds the `.eser/` directory noskills reads. */
24
+ readonly root: string;
25
+ /**
26
+ * Port to listen on, on 127.0.0.1 only. Defaults to 3000; 0 lets the system
27
+ * pick a free port, which `onListen` reports.
28
+ */
29
+ readonly port?: number;
30
+ /** Opens the dashboard in the default browser once the server listens. */
31
+ readonly open?: boolean;
32
+ /**
33
+ * Aborts the listener. Without it the only way to stop the server is the
34
+ * SIGINT handler, which makes it untestable in-process.
35
+ */
36
+ readonly signal?: AbortSignal;
37
+ /** Called once the server listens, with the address it bound. */
38
+ readonly onListen?: (address: ListenAddress) => void;
39
+ /**
40
+ * Receives the error records of failed requests and of a failed shutdown.
41
+ * Defaults to the `noskills-web` logger of `@eserstack/logging`, which
42
+ * writes to stderr when nothing configures it.
43
+ */
44
+ readonly logger?: requestContext.RequestLogger;
45
+ };
46
+ /**
47
+ * Serve the noskills dashboard, its JSON API, the SSE event stream and the
48
+ * `/mux` WebSocket on 127.0.0.1, and resolve once the server stops.
49
+ *
50
+ * The token that guards mutating routes and `/mux` comes from
51
+ * `NOSKILLS_WEB_TOKEN` when it is set, and is minted per process otherwise.
52
+ */
53
+ export declare const startServer: (opts: ServerOptions) => Promise<void>;