@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
package/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ Copyright 2023-present Eser Ozvataf and other contributors.
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License.
5
+ You may obtain a copy of the License at
6
+
7
+ http://www.apache.org/licenses/LICENSE-2.0
8
+
9
+ Unless required by applicable law or agreed to in writing, software
10
+ distributed under the License is distributed on an "AS IS" BASIS,
11
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ See the License for the specific language governing permissions and
13
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,248 @@
1
- # Temporary Holding Version
1
+ # ๐Ÿ–ฅ๏ธ [@eserstack/noskills-web](./)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/noskills-web` is
4
+ > published on npm under the same name (`pnpm add @eserstack/noskills-web`); the
5
+ > JSR versions stay available but get no updates.
6
+
7
+ > **eserstack Product** ยท [eser/stack on GitHub](https://github.com/eser/stack)
8
+ > ยท **Install:** `pnpm add @eserstack/noskills-web`
9
+
10
+ `@eserstack/noskills-web` is the browser dashboard that `noskills web` starts.
11
+ One local server on 127.0.0.1 shows the specs of a noskills project, a spec page
12
+ with its tasks, open questions and phase actions, and coding-agent tabs rendered
13
+ with xterm.js. The pages are HTML rendered from TypeScript templates, with plain
14
+ browser scripts and no build step. The server listens, accepts the `/mux`
15
+ WebSocket and handles Ctrl+C through `runtime.http` and `runtime.process` from
16
+ `@eserstack/standards/cross-runtime`, so it calls no runtime-specific API
17
+ itself.
18
+
19
+ ## Quick Start
20
+
21
+ In a project where you have run `noskills init`, start the dashboard from the
22
+ noskills command line:
23
+
24
+ ```bash
25
+ noskills web # serves http://localhost:3000
26
+ noskills web --port=4000 --open # another port, and open the browser
27
+ ```
28
+
29
+ To start the same server from your own code, pass the project root:
30
+
31
+ ```typescript
32
+ import * as noskillsWeb from "@eserstack/noskills-web";
33
+
34
+ await noskillsWeb.startServer({ root: ".", port: 3000 });
35
+ ```
36
+
37
+ `startServer` prints the dashboard URL and resolves once the server stops, which
38
+ happens when its `signal` aborts. Ctrl+C closes every tab, kills the agent
39
+ processes, removes their session files and exits the process.
40
+
41
+ ## Server
42
+
43
+ ### `startServer(options)`
44
+
45
+ | Option | Type | Default | Description |
46
+ | ---------- | ------------------- | ------------------------- | --------------------------------------------------------------------------- |
47
+ | `root` | `string` | | Project root that holds the `.eser/` directory |
48
+ | `port` | `number` | `3000` | Port to listen on; the server binds to 127.0.0.1 only. `0` picks a free one |
49
+ | `open` | `boolean` | `false` | Opens the dashboard in the default browser after the server listens |
50
+ | `signal` | `AbortSignal` | | Stops the server when aborted, for tests and embedding |
51
+ | `onListen` | `(address) => void` | | Called once the server listens, with `{ hostname, port }` |
52
+ | `logger` | `RequestLogger` | the `noskills-web` logger | Receives the error records, see [Logging](#logging) |
53
+
54
+ Stop a server you started from code with an `AbortController`. With `port: 0`,
55
+ `onListen` tells you the port the system picked:
56
+
57
+ ```typescript
58
+ import * as noskillsWeb from "@eserstack/noskills-web";
59
+
60
+ const controller = new AbortController();
61
+ const server = noskillsWeb.startServer({
62
+ root: ".",
63
+ port: 0,
64
+ signal: controller.signal,
65
+ onListen: ({ port }) => {
66
+ console.log(`listening on ${port}`);
67
+ },
68
+ });
69
+
70
+ // When you are done with it:
71
+ controller.abort();
72
+ await server;
73
+ ```
74
+
75
+ ### Routes
76
+
77
+ | Method | Path | Purpose |
78
+ | ------------- | --------------------------------------------------- | ------------------------------------------------------------- |
79
+ | `GET` | `/` | Dashboard: spec list, pending mentions, agent tabs |
80
+ | `GET` | `/spec/:name` | Spec page with tasks, questions and the phase actions |
81
+ | `GET` | `/events` | Server-Sent Events stream of dashboard events |
82
+ | `GET` | `/api/state` | Dashboard state as JSON |
83
+ | `GET` | `/api/tabs` | Open tabs as JSON |
84
+ | `GET` | `/api/spec/:name/ledger`, `/api/spec/:name/summary` | Decision ledger records, or only the maturity summary |
85
+ | `POST` | `/api/spec/:name/:action` | `approve`, `note`, `question`, `signoff`, `reply`, `complete` |
86
+ | `POST` | `/api/tab` | Open an agent tab, bound to a spec with `{ "spec": "name" }` |
87
+ | `DELETE` | `/api/tab/:id` | Close a tab |
88
+ | `GET` upgrade | `/mux?token=...` | WebSocket that carries the whole multiplexer |
89
+ | `GET` | `/static/*`, `/sw.js`, `/manifest.json` | Browser scripts, styles and the PWA files |
90
+
91
+ `note`, `question` and `reply` read `text` from the JSON body, and `reply` also
92
+ reads `mentionId`. An action the dashboard refuses, such as approving a spec in
93
+ the wrong phase or an unknown action name, answers status 400 with
94
+ `{ "ok": false, "error": "..." }`. The error message names the problem.
95
+
96
+ An approved spec has no web action that starts execution. Start it from the
97
+ coding agent with `noskills spec your_spec_name next`, for example in an agent
98
+ tab bound to the spec.
99
+
100
+ A fault answers with a fixed message and the request id:
101
+ `{ "ok": false, "error": "Action could not be completed", "requestId": "..." }`
102
+ for a failed action (status 400), and `"Request could not be completed"` with
103
+ status 500 when a route throws. The cause stays out of the response and goes to
104
+ the log under the same request id.
105
+
106
+ ### Logging
107
+
108
+ The server logs each fault through `@eserstack/logging`, under the
109
+ `noskills-web` category, as one error record. The record carries `requestId`,
110
+ `method`, `path` (never the query string, which holds the `/mux` token) and the
111
+ caught `error` with its stack and causes. A failed action also adds `spec` and
112
+ `action`. Names and emails from the request body are not logged.
113
+
114
+ `noskills web` configures nothing, and `@eserstack/logging` then writes its
115
+ records to stderr, so the detail appears in the terminal that runs the server.
116
+ To send the records elsewhere, pass a `logger`: any object with `with(fields)`
117
+ and `error(message)`, such as a `Logger` from `@eserstack/logging`:
118
+
119
+ ```typescript
120
+ import * as logging from "@eserstack/logging";
121
+ import * as noskillsWeb from "@eserstack/noskills-web";
122
+
123
+ await noskillsWeb.startServer({
124
+ root: ".",
125
+ logger: logging.logger.getLogger(["your_app", "dashboard"]),
126
+ });
127
+ ```
128
+
129
+ ### Access Control
130
+
131
+ Binding to 127.0.0.1 keeps other machines out, but any page open in your browser
132
+ can still send requests to localhost and open WebSockets to it. The server
133
+ therefore checks two things before it changes state:
134
+
135
+ - The `Origin` header, when present, must be `http://localhost:<port>`,
136
+ `http://127.0.0.1:<port>` or `http://[::1]:<port>`. This applies to every
137
+ `POST`, `PUT`, `PATCH`, `DELETE` and to `/mux`.
138
+ - A per-process token must match: in the `x-noskills-token` header on mutating
139
+ requests, and in the `token` query parameter on `/mux`. Mutating requests
140
+ other than `DELETE` must also send `content-type: application/json`, which an
141
+ HTML form cannot post across origins.
142
+
143
+ The dashboard page carries the token in a `<meta name="noskills-token">` tag,
144
+ and `static/client.js` sends it with every mutating call. Every HTML page sends
145
+ a Content-Security-Policy that allows scripts only from the server itself and
146
+ from `cdn.jsdelivr.net/npm/`, and the xterm.js files from jsDelivr load with
147
+ Subresource Integrity digests.
148
+
149
+ ### Environment Variables
150
+
151
+ | Name | Required | Default | Purpose |
152
+ | --------------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------- |
153
+ | `NOSKILLS_WEB_TOKEN` | No | A fresh token per process | Fixes the access token, so a trusted tool can call the API without reading the dashboard HTML |
154
+ | `NOSKILLS_WEB_DEBUG_ERRORS` | No | Off | `1` or `true` adds the underlying error text to fault responses as `detail` |
155
+
156
+ For example, `NOSKILLS_WEB_TOKEN=your_access_token noskills web` lets a script
157
+ send `x-noskills-token: your_access_token`. Leave `NOSKILLS_WEB_DEBUG_ERRORS`
158
+ unset outside debugging: the detail can contain file paths of your machine.
159
+
160
+ ## Agent Tabs
161
+
162
+ ### `MuxHost`
163
+
164
+ `MuxHost` owns the multiplexer behind the dashboard: one `@eserstack/mux` server
165
+ for every tab, pane and PTY, plus the noskills session bound to each tab.
166
+ `startServer` creates one for you. Use it directly to drive tabs from your own
167
+ code:
168
+
169
+ ```typescript
170
+ import * as noskillsWeb from "@eserstack/noskills-web";
171
+
172
+ const host = new noskillsWeb.MuxHost(".");
173
+
174
+ // Starts the coding agent (Claude Code by default) in a new tab bound to a spec.
175
+ const tab = await host.createTab("your_spec_name");
176
+ host.notifySpec("your_spec_name", "\n[noskills: review requested]\n");
177
+
178
+ console.log(host.listTabs()); // [{ id, specName, sessionId }]
179
+ host.closeTab(tab.id);
180
+ await host.killAll();
181
+ ```
182
+
183
+ | Member | Description |
184
+ | ---------------------------- | --------------------------------------------------------------------- |
185
+ | `createTab(specName?)` | Starts the agent in a new tab and records a noskills session for it |
186
+ | `closeTab(tabId)` | Closes one tab without moving the active tab |
187
+ | `findTabBySpec(specName)` | The tab bound to a spec, or `undefined` |
188
+ | `notifySpec(specName, text)` | Types `text` into the PTY of the spec's focused pane; `false` if none |
189
+ | `listTabs()` | Open tabs as `WebTab` values: `id`, `specName`, `sessionId` |
190
+ | `killAll()` | Closes every pane and PTY and deletes the tabs' session files |
191
+ | `attachSocket(socket)` | Connects a browser WebSocket to the multiplexer (see below) |
192
+
193
+ The `/mux` route calls `attachSocket` after it checks the Origin and the token;
194
+ authenticate a socket the same way before you attach it. Every frame from the
195
+ socket passes the `@eserstack/mux` remote sanitizer, so a frame cannot choose
196
+ the command, arguments or directory of a new pane. One socket is connected at a
197
+ time: attaching a new one closes the old one, and the panes keep running while
198
+ no socket is connected.
199
+
200
+ ## Browser Scripts
201
+
202
+ The files in `static/` load as plain `<script>` tags:
203
+
204
+ - `mux-render.js` draws a mux scene with one xterm.js terminal per pane and
205
+ exposes `globalThis.MuxRender`. It does not know the transport.
206
+ - `client.js` connects `MuxRender` to `/mux` over a WebSocket, follows
207
+ `/events`, and sends the tab and spec actions.
208
+ - `mux-remote.js` exposes `globalThis.startRemoteMux(...)`, which renders the
209
+ same scene from a `noskills-server` daemon over WebTransport. Its header marks
210
+ it as not yet tested against a live daemon.
211
+ - `sw.js` and `sw-register.js` register the service worker that shows push
212
+ notifications. On a page served over HTTPS, which is the `noskills-server`
213
+ daemon, `sw-register.js` also hands the worker the daemon's certificate
214
+ fingerprint from `/api/cert-fingerprint`. The plain-HTTP dashboard has no
215
+ certificate, so it skips that request.
216
+
217
+ ## Upgrading from 4.x
218
+
219
+ These changes since 4.5.2 need a change in code, commands or files that use this
220
+ package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
221
+ lists the changes in every package.
222
+
223
+ - `MuxHost` no longer has a public `server` field. Connect a browser WebSocket,
224
+ after authenticating it, with `host.attachSocket(socket)`. Code that drove the
225
+ mux server directly (`dispatch`, `getState`, `dispose`) creates its own with
226
+ `mux.createServer` from `@eserstack/mux`.
227
+ - A route that throws answers 500 JSON
228
+ `{ ok: false, error: "Request could not be completed", requestId }` instead of
229
+ the runtime's default 500, and an `Action could not be completed` fault
230
+ carries `requestId`. Use `requestId` to find the server log record.
231
+ - Server errors are written as `@eserstack/logging` records (JSON lines on
232
+ stderr, category `noskills-web`) instead of `[noskills-web] reason: <error>`
233
+ console lines. Read the JSON records, or pass your own `logger` to
234
+ `startServer`.
235
+ - Ctrl+C runs the graceful shutdown on Node too, and the SIGINT listener
236
+ is removed once the server stops. An embedder that relied on Node's default
237
+ Ctrl+C exit while the server runs gets the shutdown instead.
238
+
239
+ ## ๐Ÿ”— Links
240
+
241
+ - [eser/stack on GitHub](https://github.com/eser/stack)
242
+ - [`@eserstack/noskills`](../noskills/README.md): the `noskills` command and the
243
+ dashboard state this package renders
244
+ - [`@eserstack/mux`](../mux/): the terminal multiplexer behind the agent tabs
245
+ - [`@eserstack/logging`](../logging/README.md): the logger behind the server's
246
+ error records
247
+ - [`noskills-server`](../../../cmd/noskills-server/README.md): the daemon that
248
+ `mux-remote.js` attaches to
package/dist/auth.d.ts ADDED
@@ -0,0 +1,50 @@
1
+ /** Query-string parameter carrying the token on the WebSocket upgrade. */
2
+ export declare const TOKEN_QUERY_PARAM = "token";
3
+ /** Header carrying the token on mutating REST calls. */
4
+ export declare const TOKEN_HEADER = "x-noskills-token";
5
+ /**
6
+ * Mint a per-process token.
7
+ *
8
+ * 32 bytes from the CSPRNG, hex-encoded. Regenerated on every start, so a
9
+ * token leaked from one session is useless against the next.
10
+ */
11
+ export declare const createToken: () => string;
12
+ /**
13
+ * Build the set of origins the server answers to.
14
+ *
15
+ * Only loopback on the port we are actually listening on. `localhost` and the
16
+ * two loopback literals are distinct origins to a browser, so all three are
17
+ * listed; anything else -- including a LAN address for the same server -- is
18
+ * rejected.
19
+ */
20
+ export declare const allowedOrigins: (port: number) => ReadonlySet<string>;
21
+ /**
22
+ * Check a request's Origin.
23
+ *
24
+ * A missing Origin is allowed: non-browser clients (curl, the CLI's own
25
+ * fetches) omit it, and they are not the threat this guard addresses -- the
26
+ * token is. Every browser-issued cross-origin request *does* carry one, which
27
+ * is what makes the check effective where it matters.
28
+ */
29
+ export declare const isOriginAllowed: (request: Request, port: number) => boolean;
30
+ /** Check the token supplied as a query parameter (WebSocket upgrade). */
31
+ export declare const hasValidQueryToken: (request: Request, expected: string) => boolean;
32
+ /** Check the token supplied as a header (mutating REST). */
33
+ export declare const hasValidHeaderToken: (request: Request, expected: string) => boolean;
34
+ /**
35
+ * Reject a request whose body is a CSRF-simple content type.
36
+ *
37
+ * `application/x-www-form-urlencoded`, `multipart/form-data` and `text/plain`
38
+ * are the three types an HTML form can post cross-origin without a preflight.
39
+ * Requiring JSON forces a preflight, which the Origin check then fails.
40
+ */
41
+ export declare const hasJsonContentType: (request: Request) => boolean;
42
+ /** 403 with a short reason; the body is deliberately uninformative. */
43
+ export declare const forbidden: (reason: string) => Response;
44
+ /**
45
+ * Read a token supplied by the environment, if any.
46
+ *
47
+ * Lets a trusted external tool drive the server without scraping the dashboard
48
+ * HTML. Absent, a fresh token is minted per process.
49
+ */
50
+ export declare const tokenFromEnv: () => string | null;
package/dist/auth.js ADDED
@@ -0,0 +1,107 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Origin and token guards for the noskills web server.
4
+ *
5
+ * Binding to 127.0.0.1 is not an authorization boundary. WebSockets are exempt
6
+ * from the same-origin policy: any page the developer visits while `noskills
7
+ * web` is running can open `ws://localhost:<port>/mux` and drive the
8
+ * multiplexer. Form posts are likewise cross-origin-reachable. Both therefore
9
+ * need an explicit check.
10
+ *
11
+ * Two independent guards, because each covers the other's gap:
12
+ *
13
+ * - **Origin allowlist** stops a browser page on another origin. It cannot
14
+ * stop a non-browser client, which sets any Origin it likes.
15
+ * - **Per-process token** stops any client that has not read the dashboard
16
+ * HTML. It is minted per run and never persisted.
17
+ *
18
+ * @module
19
+ */
20
+ import { runtime } from "@eserstack/standards/cross-runtime";
21
+ /** Query-string parameter carrying the token on the WebSocket upgrade. */
22
+ export const TOKEN_QUERY_PARAM = "token";
23
+ /** Header carrying the token on mutating REST calls. */
24
+ export const TOKEN_HEADER = "x-noskills-token";
25
+ /**
26
+ * Mint a per-process token.
27
+ *
28
+ * 32 bytes from the CSPRNG, hex-encoded. Regenerated on every start, so a
29
+ * token leaked from one session is useless against the next.
30
+ */
31
+ export const createToken = () => {
32
+ const bytes = new Uint8Array(32);
33
+ crypto.getRandomValues(bytes);
34
+ return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
35
+ };
36
+ /** Constant-time string comparison, to keep the token off a timing side channel. */
37
+ const timingSafeEqual = (a, b) => {
38
+ if (a.length !== b.length) {
39
+ return false;
40
+ }
41
+ let diff = 0;
42
+ for (let i = 0; i < a.length; i++) {
43
+ diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
44
+ }
45
+ return diff === 0;
46
+ };
47
+ /**
48
+ * Build the set of origins the server answers to.
49
+ *
50
+ * Only loopback on the port we are actually listening on. `localhost` and the
51
+ * two loopback literals are distinct origins to a browser, so all three are
52
+ * listed; anything else -- including a LAN address for the same server -- is
53
+ * rejected.
54
+ */
55
+ export const allowedOrigins = (port) => new Set([
56
+ `http://localhost:${port}`,
57
+ `http://127.0.0.1:${port}`,
58
+ `http://[::1]:${port}`,
59
+ ]);
60
+ /**
61
+ * Check a request's Origin.
62
+ *
63
+ * A missing Origin is allowed: non-browser clients (curl, the CLI's own
64
+ * fetches) omit it, and they are not the threat this guard addresses -- the
65
+ * token is. Every browser-issued cross-origin request *does* carry one, which
66
+ * is what makes the check effective where it matters.
67
+ */
68
+ export const isOriginAllowed = (request, port) => {
69
+ const origin = request.headers.get("origin");
70
+ if (origin === null || origin === "") {
71
+ return true;
72
+ }
73
+ return allowedOrigins(port).has(origin);
74
+ };
75
+ /** Check the token supplied as a query parameter (WebSocket upgrade). */
76
+ export const hasValidQueryToken = (request, expected) => {
77
+ const supplied = new URL(request.url).searchParams.get(TOKEN_QUERY_PARAM);
78
+ return supplied !== null && timingSafeEqual(supplied, expected);
79
+ };
80
+ /** Check the token supplied as a header (mutating REST). */
81
+ export const hasValidHeaderToken = (request, expected) => {
82
+ const supplied = request.headers.get(TOKEN_HEADER);
83
+ return supplied !== null && timingSafeEqual(supplied, expected);
84
+ };
85
+ /**
86
+ * Reject a request whose body is a CSRF-simple content type.
87
+ *
88
+ * `application/x-www-form-urlencoded`, `multipart/form-data` and `text/plain`
89
+ * are the three types an HTML form can post cross-origin without a preflight.
90
+ * Requiring JSON forces a preflight, which the Origin check then fails.
91
+ */
92
+ export const hasJsonContentType = (request) => {
93
+ const contentType = request.headers.get("content-type") ?? "";
94
+ return contentType.split(";")[0]?.trim().toLowerCase() === "application/json";
95
+ };
96
+ /** 403 with a short reason; the body is deliberately uninformative. */
97
+ export const forbidden = (reason) => new Response(`Forbidden: ${reason}`, { status: 403 });
98
+ /**
99
+ * Read a token supplied by the environment, if any.
100
+ *
101
+ * Lets a trusted external tool drive the server without scraping the dashboard
102
+ * HTML. Absent, a fresh token is minted per process.
103
+ */
104
+ export const tokenFromEnv = () => {
105
+ const value = runtime.env.get("NOSKILLS_WEB_TOKEN");
106
+ return value === undefined || value === "" ? null : value;
107
+ };
package/dist/mod.d.ts ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * noskills web โ€” browser interface for noskills dashboard.
3
+ *
4
+ * Provides the same experience as the TUI manager:
5
+ * tabs, spec reading, inline CTAs, terminal interaction.
6
+ *
7
+ * @module
8
+ */
9
+ export { startServer } from "./server.ts";
10
+ export type { ListenAddress, ServerOptions } from "./server.ts";
11
+ export type { RequestLogger } from "./request-context.ts";
12
+ export { MuxHost } from "./terminal/mux-host.ts";
13
+ export type { WebTab } from "./terminal/mux-host.ts";
package/dist/mod.js ADDED
@@ -0,0 +1,11 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * noskills web โ€” browser interface for noskills dashboard.
4
+ *
5
+ * Provides the same experience as the TUI manager:
6
+ * tabs, spec reading, inline CTAs, terminal interaction.
7
+ *
8
+ * @module
9
+ */
10
+ export { startServer } from "./server.js";
11
+ export { MuxHost } from "./terminal/mux-host.js";
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The ids and the logger of one HTTP request.
3
+ *
4
+ * The server creates a context for every request it answers. Its request id
5
+ * goes into each log record of that request and into the failure response, so a
6
+ * user who reports a failed action can be matched to the record that has the
7
+ * detail.
8
+ *
9
+ * @module
10
+ */
11
+ /**
12
+ * The logger calls the request handlers make. A `Logger` from
13
+ * `@eserstack/logging` satisfies it; tests pass a fake that keeps the records.
14
+ */
15
+ export type RequestLogger = {
16
+ /** A logger that adds `properties` to every record it writes. */
17
+ with(properties: Record<string, unknown>): RequestLogger;
18
+ /** Writes an error record. */
19
+ error(message: string): Promise<unknown>;
20
+ };
21
+ /** The ids and the logger of one request. */
22
+ export type RequestContext = {
23
+ /** A random id that the log records and the failure response share. */
24
+ readonly requestId: string;
25
+ /** Writes records with `requestId`, `method` and `path` attached. */
26
+ readonly log: RequestLogger;
27
+ };
28
+ /**
29
+ * Create the context of `request`: a fresh request id, and a logger that
30
+ * attaches it with the method and the path.
31
+ *
32
+ * Only the path is logged. The query string stays out of the log because the
33
+ * `/mux` upgrade carries the access token in it.
34
+ */
35
+ export declare const createRequestContext: (request: Request, logger: RequestLogger) => RequestContext;
@@ -0,0 +1,19 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Create the context of `request`: a fresh request id, and a logger that
4
+ * attaches it with the method and the path.
5
+ *
6
+ * Only the path is logged. The query string stays out of the log because the
7
+ * `/mux` upgrade carries the access token in it.
8
+ */
9
+ export const createRequestContext = (request, logger) => {
10
+ const requestId = crypto.randomUUID();
11
+ return {
12
+ requestId,
13
+ log: logger.with({
14
+ requestId,
15
+ method: request.method,
16
+ path: new URL(request.url).pathname,
17
+ }),
18
+ };
19
+ };
@@ -0,0 +1,45 @@
1
+ import type * as requestContext from "../request-context.ts";
2
+ import type { MuxHost } from "../terminal/mux-host.ts";
3
+ /**
4
+ * Log a caught fault under the request id and answer
5
+ * `{ ok: false, error, requestId }`.
6
+ *
7
+ * `reason` is written at the call site; it is never derived from `cause`, and
8
+ * `cause` never reaches the wire. Everything below this layer reports faults
9
+ * as a bare `Error` carrying whatever the runtime threw, such as
10
+ * `NotFound: ... open '/Users/<name>/<repo>/.eser/specs/<spec>/state.json'`, so
11
+ * forwarding its message or stack would map out the host's directory layout
12
+ * and the internal module structure for the caller. The token guard narrows
13
+ * who can ask, but it is a single per-process secret embedded in the dashboard
14
+ * HTML, not a reason to answer with a stack trace. The detail goes to the log
15
+ * instead, and the request id in the response leads to it.
16
+ *
17
+ * @param context - The request the fault happened in
18
+ * @param reason - What failed, in words the user can act on
19
+ * @param status - The HTTP status of the response
20
+ * @param cause - The caught error; logged, never sent
21
+ * @returns The JSON failure response
22
+ */
23
+ export declare const faultResponse: (context: requestContext.RequestContext, reason: string, status: number, cause: unknown) => Promise<Response>;
24
+ /** GET /api/state โ€” Full dashboard state. */
25
+ export declare const handleGetState: (root: string) => Promise<Response>;
26
+ /**
27
+ * GET /api/spec/:name/ledger | summary โ€” read-only decision-ledger data.
28
+ * `ledger` returns the full records + summary; `summary` returns only the
29
+ * maturity summary. Missing files yield empty records / null summary, never 404.
30
+ */
31
+ export declare const handleSpecRead: (root: string, specName: string, kind: "ledger" | "summary") => Promise<Response>;
32
+ /**
33
+ * POST /api/spec/:name/:action: run one dashboard action on a spec.
34
+ *
35
+ * The actions are the ones `@eserstack/noskills/dashboard` implements. The spec
36
+ * page offers only these; a button for any other action would answer 400 on
37
+ * every click (server.test.ts checks the buttons of every phase).
38
+ */
39
+ export declare const handleAction: (root: string, specName: string, action: string, body: Readonly<Record<string, unknown>>, host: MuxHost, context: requestContext.RequestContext) => Promise<Response>;
40
+ /** POST /api/tab โ€” Create a new tab. */
41
+ export declare const handleCreateTab: (host: MuxHost, body: Readonly<Record<string, unknown>>) => Promise<Response>;
42
+ /** DELETE /api/tab/:id โ€” Close a tab. */
43
+ export declare const handleCloseTab: (host: MuxHost, tabId: string) => Response;
44
+ /** GET /api/tabs โ€” List tabs. */
45
+ export declare const handleListTabs: (host: MuxHost) => Response;