asljs-rq-srv 0.1.1 → 0.1.2

package/README.md

@@ -5,33 +5,50 @@
 
 ## Overview
 
-`asljs-rq-srv` is the `rq view` web server: an editor with the requirements
-graph as a diagram, the documents rendered, and an editor that saves them. `rq
-view` of `asljs-rq-cli` runs it.
+`asljs-rq-srv` is the `rq-srv` web server: an editor with the requirements graph
+as a diagram and the documents, rendered and edited in the browser from the data
+the server sends.
 
 ## Installation
 
 ```bash
-npm install asljs-rq-srv
+npm install --global asljs-rq-srv
 ```
 
 ## Usage
 
+```bash
+rq-srv
+```
+
+serves every project of the current folder, each folder with an `rq.json`, in
+one editor with a list box to switch between them, until stopped with Ctrl+C.
+
+```bash
+rq-srv --working-dir ~/work --port 8080
+```
+
+serves the projects of `~/work` on port 8080. Each project's folders come from
+its own `rq.json`; `rq-srv` takes no folder option of `rq`.
+
 ```ts
-import { execView } from 'asljs-rq-srv';
+import { createApp } from 'asljs-rq-srv';
 ```
 
-`execView(io, options)` takes the `Io` of `asljs-rq` and the view options, among
-them the graph's path and the port, starts the server and returns it once it
-listens.
+`createApp(context, options?)` takes an `EditorAppContext` of `asljs-appbase`,
+`{ cwd, base, env, loggerProvider, files? }`, whose `cwd` the projects are
+looked for in, and `{ stderr }`, where a failed post-processing is reported, and
+returns the `EditorApp` whose `handler` serves the editor below `base`, for a
+server of its own or one that serves several applications.
 
 ## Further reading
 
-- [rq view][DOC] - what the server serves, and editing.
+- [rq-srv][DOC] - the command, what the server serves, and editing.
 
 ## Related packages
 
 - [asljs-rq-cli][CLI] - the `rq` command line.
+- [asljs-rq-mcp][MCP] - the `rq-mcp` MCP server.
 - [asljs-rq][RQL] - the requirements model and the commands as functions.
 
 ## License
@@ -40,6 +57,7 @@ See [LICENSE][LIC] for details.
 
 [#1]: https://github.com/AlexandriteSoftware/asljs
 [CLI]: ../rq-cli/README.md
-[DOC]: <docs/rq view.md>
+[DOC]: docs/rq-srv.md
 [LIC]: LICENSE.md
+[MCP]: ../rq-mcp/README.md
 [RQL]: ../rq/README.md

package/bin/rq-srv.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { main }
+  from '../dist/main.js';
+
+process.exitCode =
+  await main(
+    process.argv.slice(2),
+    { cwd: process.cwd(),
+      env: process.env,
+      stdout: process.stdout,
+      stderr: process.stderr });

package/dist/browser/data.d.ts

@@ -0,0 +1,54 @@
+import { type GraphDiagram, type ImplementationRow } from 'asljs-rq';
+/**
+ * What `_/data.json` of a project answers: the title of the graph, its
+ * structure errors, and the diagram, whose nodes link to their documents by
+ * paths relative to the project's base.
+ */
+export interface GraphReply {
+    title: string;
+    problems: string[];
+    diagram: GraphDiagram;
+}
+/**
+ * What the editor of a requirement or test edits: the id, which stays, the
+ * title after it, and the text without the sections the commands own; a save
+ * sends `version` back.
+ */
+export interface EditableReply {
+    id: string;
+    title: string;
+    body: string;
+    version: string;
+}
+/**
+ * A requirement's `## Implementation` list: the rows of the documents it
+ * links to, shown as a table where the paragraph `placeholder` stands in the
+ * text.
+ */
+export interface ImplementationReply {
+    placeholder: string;
+    rows: ImplementationRow[];
+}
+/**
+ * What `_/document.json?path=<path>` answers for a markdown document of the
+ * served folder: its path as asked, its full path, and its text. A
+ * requirement or test also has `editable`; a requirement with an
+ * `## Implementation` list has `implementation`, its list replaced in `text`
+ * by the placeholder.
+ */
+export interface DocumentReply {
+    path: string;
+    file: string;
+    text: string;
+    editable?: EditableReply;
+    implementation?: ImplementationReply;
+}
+/**
+ * What a `POST` of `{ path, version, title, body }` to `_/document.json`
+ * answers when it saved the document: a warning when the post-processing
+ * failed.
+ */
+export interface SaveReply {
+    saved: true;
+    warning?: string;
+}

package/dist/browser/data.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/document.d.ts

@@ -0,0 +1,20 @@
+import { type ImplementationRow } from 'asljs-rq';
+import { type DocumentReply } from './data.js';
+/**
+ * The rendered text of a document of `_/document.json`: its markdown, with
+ * the paragraph that stands for a requirement's Implementation list replaced
+ * by the table of its rows.
+ */
+export declare function renderText(reply: DocumentReply): DocumentFragment;
+/**
+ * The table of a requirement's Implementation list: each linked document's id
+ * and title, linking to it by its path from the requirement, the coverage and
+ * the result it records; a missing document is marked missing, and an item
+ * that links to no requirement or test shows its text.
+ */
+export declare function implementationTable(rows: readonly ImplementationRow[]): HTMLTableElement;
+/**
+ * The full path of a requirement or test, which a click copies, showing it
+ * was copied for a moment.
+ */
+export declare function pathLine(file: string): HTMLElement;

package/dist/browser/document.js

@@ -0,0 +1,96 @@
+import { element } from 'asljs-ui-editor';
+import { markdownToHtml } from 'asljs-ui-markdown';
+/**
+ * How long the path line shows that it was copied, in milliseconds.
+ */
+const COPIED_MS = 1000;
+/**
+ * The rendered text of a document of `_/document.json`: its markdown, with
+ * the paragraph that stands for a requirement's Implementation list replaced
+ * by the table of its rows.
+ */
+export function renderText(reply) {
+    const template = element('template');
+    template.innerHTML =
+        markdownToHtml(reply.text);
+    const content = template.content;
+    if (reply.implementation
+        !== undefined) {
+        const { placeholder, rows } = reply.implementation;
+        for (const paragraph of content.querySelectorAll('p')) {
+            if (paragraph.textContent
+                === placeholder) {
+                paragraph.replaceWith(implementationTable(rows));
+            }
+        }
+    }
+    return content;
+}
+/**
+ * The table of a requirement's Implementation list: each linked document's id
+ * and title, linking to it by its path from the requirement, the coverage and
+ * the result it records; a missing document is marked missing, and an item
+ * that links to no requirement or test shows its text.
+ */
+export function implementationTable(rows) {
+    const table = element('table', 'rq-implementation');
+    const headings = element('tr');
+    for (const heading of ['ID',
+        'Title',
+        'Coverage',
+        'Result']) {
+        headings.append(element('th', undefined, heading));
+    }
+    const head = element('thead');
+    head.append(headings);
+    const body = element('tbody');
+    for (const row of rows) {
+        body.append(implementationRow(row));
+    }
+    table.append(head, body);
+    return table;
+}
+function implementationRow(row) {
+    const cell = (content, className) => {
+        const made = element('td', className);
+        made.append(content);
+        return made;
+    };
+    const link = (text) => {
+        if (row.href === null
+            || text === '') {
+            return text;
+        }
+        const anchor = element('a', undefined, text);
+        anchor.setAttribute('href', encodeURI(row.href));
+        return anchor;
+    };
+    const tr = element('tr', row.missing
+        ? 'rq-missing'
+        : undefined);
+    tr.append(cell(link(row.id)), cell(row.missing
+        ? 'missing'
+        : link(row.title)), cell(row.coverage), cell(row.result, row.result === ''
+        ? undefined
+        : `rq-${row.result
+            .toLowerCase()
+            .replace(' ', '-')}`));
+    return tr;
+}
+/**
+ * The full path of a requirement or test, which a click copies, showing it
+ * was copied for a moment.
+ */
+export function pathLine(file) {
+    const line = element('p', 'rq-path', file);
+    line.title = 'Copy the path';
+    line.addEventListener('click', () => {
+        void navigator.clipboard
+            .writeText(file)
+            .then(() => {
+            line.classList.add('copied');
+            setTimeout(() => line.classList.remove('copied'), COPIED_MS);
+        });
+    });
+    return line;
+}

package/dist/browser/icons.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The icon of the application, drawn in the text colour.
+ */
+export declare const ICONS: {
+    graph: string;
+};

package/dist/browser/icons.js

@@ -0,0 +1,4 @@
+/**
+ * The icon of the application, drawn in the text colour.
+ */
+export const ICONS = { graph: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="6" cy="12" r="2.5"/><circle cx="18" cy="6" r="2.5"/><circle cx="18" cy="18" r="2.5"/><path d="m8.2 10.9 7.6-3.8M8.2 13.1l7.6 3.8"/></svg>' };

package/dist/{index-script.d.ts → browser/outline.d.ts}

@@ -9,9 +9,6 @@ export interface OutlineItem {
  * each followed by what it links to, in link order. A node linked from several,
  * such as a test, is listed under the first that reaches it; a node no root
  * reaches, as in a cycle, is listed at the top.
- *
- * Its source is sent to the browser as part of the index page, so it uses
- * nothing but its arguments.
  */
 export declare function buildOutline(nodes: readonly {
     id: string;

package/dist/{index-script.js → browser/outline.js}

@@ -3,9 +3,6 @@
  * each followed by what it links to, in link order. A node linked from several,
  * such as a test, is listed under the first that reaches it; a node no root
  * reaches, as in a cycle, is listed at the top.
- *
- * Its source is sent to the browser as part of the index page, so it uses
- * nothing but its arguments.
  */
 export function buildOutline(nodes, links) {
     const labels = new Map(nodes.map(node => [node.id,

package/dist/browser/plugin.d.ts

@@ -0,0 +1,21 @@
+import { type EditorPluginFactory } from 'asljs-ui-editor';
+/**
+ * The plugin of a project, the browser module of `asljs-ui-editor` the
+ * server serves. It loads the graph from `_/data.json` of the project's
+ * `base`. The graph is the first document, `rq:graph`, and stays open; a
+ * double click on a node opens its document as another tab,
+ * `rq:doc:<path>`. The diagram's selection is the editor's: a click on a node
+ * selects it, and so does choosing it in the Nodes list, which also moves the
+ * view to it. The graph's preview, on its right, views or edits the selected
+ * node, as the View and Edit tabs of its action bar choose. The diagram is
+ * read-only: nodes move, but delete and resize do nothing. The search finds
+ * the nodes by their titles, and opens their documents.
+ *
+ * A document is rendered here from `_/document.json`: a requirement's
+ * Implementation list as a table, a requirement or test as a tab with its
+ * full path, which a click copies, above it. A link to a markdown document of
+ * the project opens it as another tab. Edit edits the title and the text of a
+ * requirement or test, saved with a `POST` to `_/document.json`.
+ */
+declare const createPlugin: EditorPluginFactory;
+export default createPlugin;

package/dist/browser/plugin.js

@@ -0,0 +1,278 @@
+import { createModelFromDocument, createPreviewModel, searchElements } from 'asljs-ui-diagram';
+import { element, fetchJson, ICONS as EDITOR_ICONS, note, pathHref, projectPath, searchMatcher, trackActive } from 'asljs-ui-editor';
+import { markdownDocument } from 'asljs-ui-markdown';
+import { pathLine, renderText } from './document.js';
+import { ICONS } from './icons.js';
+import { buildOutline } from './outline.js';
+/**
+ * Where the browser keeps the state of the graph's preview.
+ */
+const LAYOUT_KEY = 'rq-view-layout';
+/**
+ * What the editor says under the text of a requirement or test.
+ */
+const EDIT_NOTE = 'Implementation, Coverage and Status are kept as they are, after the text. Ids such as R2 or T3 become links when saved.';
+/**
+ * The plugin of a project, the browser module of `asljs-ui-editor` the
+ * server serves. It loads the graph from `_/data.json` of the project's
+ * `base`. The graph is the first document, `rq:graph`, and stays open; a
+ * double click on a node opens its document as another tab,
+ * `rq:doc:<path>`. The diagram's selection is the editor's: a click on a node
+ * selects it, and so does choosing it in the Nodes list, which also moves the
+ * view to it. The graph's preview, on its right, views or edits the selected
+ * node, as the View and Edit tabs of its action bar choose. The diagram is
+ * read-only: nodes move, but delete and resize do nothing. The search finds
+ * the nodes by their titles, and opens their documents.
+ *
+ * A document is rendered here from `_/document.json`: a requirement's
+ * Implementation list as a table, a requirement or test as a tab with its
+ * full path, which a click copies, above it. A link to a markdown document of
+ * the project opens it as another tab. Edit edits the title and the text of a
+ * requirement or test, saved with a `POST` to `_/document.json`.
+ */
+const createPlugin = async ({ id, base, model }) => {
+    const { title, problems, diagram: { document: data, hrefs } } = await fetchJson(base, '_/data.json');
+    const graphId = `${id}:graph`;
+    const labels = new Map(data.nodes.map(node => [node.id,
+        node.label]));
+    // The path of each node's document, relative to the project; none for a
+    // node outside the served folder.
+    const paths = new Map(Object.entries(hrefs)
+        .map(([node, href]) => [node,
+        decodeURI(href)]));
+    const titles = new Map([...paths]
+        .map(([node, file]) => [file,
+        labels.get(node) ?? file]));
+    const graph = createModelFromDocument(data);
+    graph.deleteElements = () => { };
+    graph.resizeElement = () => false;
+    const toDocument = (file) => ({ id: `${id}:doc:${file}`,
+        title: titles.get(file)
+            ?? file
+                .split('/')
+                .at(-1)
+                .replace(/\.md$/i, ''),
+        data: { path: file } });
+    const nodeDocument = (node) => {
+        const file = paths.get(node);
+        return file === undefined
+            ? null
+            : toDocument(file);
+    };
+    const selectNode = (node) => {
+        model.activate(graphId);
+        graph.select([node]);
+        requestAnimationFrame(() => graph.reveal(node));
+    };
+    const openNode = (node) => {
+        const opened = nodeDocument(node);
+        if (opened !== null) {
+            model.open(opened);
+        }
+    };
+    // The editor's selection is the graph's, which the Nodes list marks.
+    graph.on('change', () => {
+        const ids = graph.selection.filter(node => labels.has(node));
+        const node = ids.length === 1
+            ? ids[0]
+            : null;
+        if ((model.selection?.id
+            ?? null)
+            !== node) {
+            model.select(node === null
+                ? null
+                : { id: node,
+                    title: labels.get(node),
+                    data: { path: paths.get(node) ?? null } });
+        }
+    });
+    // A document of the project: rendered from what `_/document.json`
+    // answers, its links to markdown documents opened as tabs.
+    const documentView = (file, options) => {
+        let reply = null;
+        const head = element('div');
+        return markdownDocument({ url: pathHref(base, file),
+            load: async () => {
+                const loaded = await fetchJson(base, `_/document.json?path=${encodeURIComponent(file)}`);
+                reply = loaded;
+                head.replaceChildren(...loaded.editable === undefined
+                    ? []
+                    : [pathLine(loaded.file)]);
+                return loaded.editable === undefined
+                    ? { body: loaded.text }
+                    : { body: loaded.editable.body,
+                        version: loaded.editable.version,
+                        title: { label: loaded.editable.id,
+                            value: loaded.editable.title } };
+            },
+            render: () => renderText(reply),
+            save: options.save === true
+                ? async (edit) => {
+                    const saved = await fetchJson(base, '_/document.json', { path: file,
+                        version: edit.version,
+                        title: edit.title ?? '',
+                        body: edit.body });
+                    return saved.warning;
+                }
+                : undefined,
+            head: options.head === true
+                ? () => head
+                : undefined,
+            note: EDIT_NOTE,
+            editing: options.editing,
+            openLink: (url) => {
+                const target = projectPath(base, url);
+                if (target === null
+                    || !/\.md$/i.test(target)) {
+                    return false;
+                }
+                model.open(toDocument(target));
+                return true;
+            },
+            onInput: options.keep === undefined
+                ? undefined
+                : () => model.keep(options.keep) });
+    };
+    const nodeButton = (node, label) => {
+        const button = element('button', 'asljs-plugin-item', label);
+        button.type = 'button';
+        button.dataset.node = node;
+        button.title = label;
+        button.addEventListener('click', () => selectNode(node));
+        button.addEventListener('dblclick', () => openNode(node));
+        return button;
+    };
+    // The graph's preview: View shows the selected node's document, Edit
+    // edits it; its state is kept in this browser.
+    let stored = {};
+    try {
+        stored =
+            JSON.parse(localStorage.getItem(LAYOUT_KEY) ?? '{}');
+    }
+    catch {
+        // Without storage, the preview starts open, viewing.
+    }
+    const preview = createPreviewModel(stored.preview
+        ?? { open: true,
+            mode: 'view' });
+    preview.on('change', () => {
+        try {
+            localStorage.setItem(LAYOUT_KEY, JSON.stringify({ preview: { open: preview.open,
+                    mode: preview.mode,
+                    width: preview.width } }));
+        }
+        catch {
+            // Without storage, the preview lasts until the page is reloaded.
+        }
+    });
+    const previewed = (selection) => selection.length === 1
+        ? paths.get(selection[0]) ?? null
+        : null;
+    const previewModes = [{ id: 'view',
+            title: 'View',
+            isEnabled: selection => previewed(selection) !== null,
+            render: selection => documentView(previewed(selection), {}) },
+        { id: 'edit',
+            title: 'Edit',
+            isEnabled: selection => previewed(selection) !== null,
+            render: selection => documentView(previewed(selection), { editing: true,
+                save: true }) }];
+    const graphView = () => {
+        const view = element('div', 'rq-graph');
+        const diagram = document.createElement('asljs-diagram');
+        diagram.tabIndex = 0;
+        diagram.model = graph;
+        diagram.addEventListener('dblclick', (event) => {
+            const node = event.target
+                ?.closest?.('g[data-id]')
+                ?.getAttribute('data-id');
+            if (node) {
+                openNode(node);
+            }
+        });
+        const panel = document.createElement('asljs-diagram-preview');
+        panel.placeholder =
+            'Select a requirement or test to preview it.';
+        panel.modes = previewModes;
+        panel.model = graph;
+        panel.preview = preview;
+        const stage = element('div', 'rq-stage');
+        stage.append(diagram, panel);
+        const zoom = document.createElement('asljs-diagram-zoom');
+        zoom.viewport = graph.viewport;
+        const tabs = document.createElement('asljs-diagram-preview-tabs');
+        tabs.modes = previewModes;
+        tabs.preview = preview;
+        const bar = element('div', 'rq-actionbar');
+        bar.append(zoom, tabs);
+        view.append(stage, bar);
+        requestAnimationFrame(() => graph.viewport.fit());
+        return view;
+    };
+    const outline = (items) => {
+        const list = element('ul', 'asljs-plugin-list');
+        for (const item of items) {
+            const entry = element('li');
+            entry.append(nodeButton(item.id, item.label));
+            if (item.children.length > 0) {
+                entry.append(outline(item.children));
+            }
+            list.append(entry);
+        }
+        return list;
+    };
+    // The nodes whose title matches: as searchElements finds them, or, with a
+    // regular expression or the case matched, as searchMatcher does.
+    const matching = (query) => {
+        if (!query.regex
+            && !query.matchCase) {
+            return searchElements(graph.diagram.elements, query.text)
+                .map(item => String(item.value));
+        }
+        const matches = searchMatcher(query);
+        return data.nodes
+            .filter(node => matches(node.label))
+            .map(node => node.id);
+    };
+    return { id,
+        title: 'Requirements',
+        icon: ICONS.graph,
+        documents: [{ id: graphId,
+                title,
+                closable: false }],
+        operations: [{ id: 'nodes',
+                title: 'Nodes',
+                icon: EDITOR_ICONS.list,
+                render: () => {
+                    const list = outline(buildOutline(data.nodes, data.links));
+                    trackActive(model, list, { attribute: 'node',
+                        current: () => model.selection?.id ?? null });
+                    return list;
+                } },
+            ...problems.length === 0
+                ? []
+                : [{ id: 'problems',
+                        title: `Problems (${problems.length})`,
+                        icon: EDITOR_ICONS.warning,
+                        render: () => {
+                            const list = element('div');
+                            list.append(...problems.map(note));
+                            return list;
+                        } }]],
+        renderDocument: (opened) => opened.id === graphId
+            ? graphView()
+            : documentView(opened.data.path, { head: true,
+                save: true,
+                keep: opened.id }),
+        search: async (query) => matching(query)
+            .filter(node => labels.has(node))
+            .flatMap((node) => {
+            const found = nodeDocument(node);
+            return found === null
+                ? []
+                : [{ document: found,
+                        title: labels.get(node) }];
+        }),
+        dispose: () => model.select(null) };
+};
+export default createPlugin;

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { execView, type ViewOptions } from './view.js';
+export { main } from './main.js';
+export { createApp, type RqAppOptions } from './view.js';

package/dist/index.js

@@ -1 +1,2 @@
-export { execView } from './view.js';
+export { main } from './main.js';
+export { createApp } from './view.js';

package/dist/main.d.ts

@@ -0,0 +1,11 @@
+import { Io } from 'asljs-rq';
+/**
+ * The `rq-srv` executable: serves the projects of the working folder, on the
+ * port of `--port`, else of the nearest `rq.json`, until SIGINT or SIGTERM,
+ * then closes the application and returns the exit code. Its logger provider
+ * is made from `--loglevel`, `--logfile`, `--logformat`, the `RQ_LOG_`
+ * variables and `rq.json` (`runMain`); help and the version answer 0, a
+ * wrong argument or a server that cannot start 1, with the reason on
+ * `io.stderr`.
+ */
+export declare function main(args: string[], io: Io): Promise<number>;

package/dist/main.js

@@ -0,0 +1,40 @@
+import { commandLine, configPort, loadConfig, packageVersion, parsePort, runMain, serveApp } from 'asljs-appbase';
+import { CONFIG_FILE } from 'asljs-rq';
+import { Command } from 'commander';
+import path from 'node:path';
+import { createApp } from './view.js';
+const WORKING_DIR = 'The folder the projects are looked for in: its rq.json, else each rq.json of its subfolders; the current directory by default. The port and the logging come from the nearest rq.json of it or a parent';
+/**
+ * The `rq-srv` executable: serves the projects of the working folder, on the
+ * port of `--port`, else of the nearest `rq.json`, until SIGINT or SIGTERM,
+ * then closes the application and returns the exit code. Its logger provider
+ * is made from `--loglevel`, `--logfile`, `--logformat`, the `RQ_LOG_`
+ * variables and `rq.json` (`runMain`); help and the version answer 0, a
+ * wrong argument or a server that cannot start 1, with the reason on
+ * `io.stderr`.
+ */
+export async function main(args, io) {
+    return await runMain(args, io, { prefix: 'RQ_LOG_',
+        configFile: CONFIG_FILE }, async (loggerProvider) => {
+        const cli = commandLine(new Command('rq-srv'), io, { workingDir: WORKING_DIR });
+        cli
+            .description('Serve a requirements graph and its documents over HTTP: the graph in an editor, and the documents rendered and editable.')
+            .version(packageVersion(import.meta.url))
+            .helpCommand(false)
+            .option('--port <port>', 'Port to listen on, exactly; 0 picks a free one. By default port of rq.json, else the first free port from 3000 on')
+            .action(async (options) => {
+            const cwd = path.resolve(io.cwd, options.workingDir ?? '.');
+            const port = parsePort(options.port)
+                ?? configPort(await loadConfig(cwd, CONFIG_FILE));
+            await serveApp(await createApp({ cwd,
+                base: '/',
+                env: io.env,
+                loggerProvider }, { stderr: io.stderr }), { io,
+                cwd,
+                port,
+                loggerProvider });
+        });
+        await cli.parseAsync(args, { from: 'user' });
+        return 0;
+    });
+}