asljs-part-srv 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Permissive No-Derivatives License 1.0
+
+Copyright (c) 2026 Alexandrite Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software (the "Software") to:
+
+1. Use the Software for any purpose, including commercial purposes.
+2. Copy and redistribute the Software, including as part of another application,
+   library, or package.
+3. Modify the Software for private or internal use.
+
+Subject to the following conditions:
+
+## 1. No Distribution of Modified Versions
+
+Modified versions of the Software, or substantial portions thereof, must not be
+distributed without prior written permission from the copyright holder.
+
+Routine build transformations, including minification, transpilation, and
+bundling, are permitted for distribution, provided they do not intentionally
+alter the Software's functionality.
+
+## 2. Licence and Copyright Preservation
+
+All distributed copies of the Software must retain this copyright notice and
+licence.
+
+The Software itself, including copies incorporated into other applications,
+libraries, or packages, remains subject to this licence.
+
+The Software must not be sublicensed or redistributed under a different licence.
+
+## 3. Use in Other Software
+
+Applications and libraries that merely use, import, link to, or bundle the
+Software are not considered modified versions of the Software and may be
+distributed under any licence.
+
+Such use, incorporation, or bundling does not grant permission to relicense the
+Software or distribute modified versions of it.
+
+### 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# part-srv
 
-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.
+> Part of [Alexandrite Software Library][#1] - a set of high-quality, performant
+> JavaScript libraries and tools for everyday use.
+
+## Overview
+
+`asljs-part-srv` is the `part-srv` web server: the files of projects in an
+editor in the browser, as a tree of folders, each opened as a tab of its
+details - path, size, modification time - and the artefact definitions that
+match it. Each `part.json` of the working directory, else of its folders, is a
+project, chosen in a list box. It reads a project on every request and never
+serves the content of a file.
+
+## Installation
+
+```bash
+npm install -g asljs-part-srv
+```
+
+## Usage
+
+```bash
+part-srv
+```
+
+serves the projects of the working folder at the address it prints, until
+stopped with Ctrl+C; `part-srv --working-dir ~/work` serves those of `~/work`.
+Each project takes its root, definitions and state folder from its own
+`part.json` only.
+
+As a library:
+
+```ts
+import { NullLoggerProvider } from 'asljs-logging';
+import { serve } from 'asljs-appbase';
+import { createApp } from 'asljs-part-srv';
+
+const app = await createApp(
+  { cwd: process.cwd(),
+    base: '/',
+    env: process.env,
+    loggerProvider: new NullLoggerProvider() });
+
+const server = await serve(app.handler, { port: 8080 });
+```
+
+`createApp(context)` is the application as an editor plugin, an `EditorApp` of
+`asljs-appbase`, served at `context.base`, with a project for each `part.json`
+found from `context.cwd`. `listProject(project)` gives the files and the other
+artefacts the Artefacts panel lists, and `describeArtefact(project, location)`
+the details a tab shows; the server answers them as JSON at `DATA_PATH` and
+`ARTEFACT_PATH` of each project, and the plugin renders them in the browser.
+`main(args, environment)` is the `part-srv` command.
+
+## Further reading
+
+- [part-srv][DOC] - the command, the projects, the editor and the data the
+  server answers.
+- [Requirements][REQ] - what the server guarantees, as rq requirements.
+
+## Related packages
+
+- [asljs-part][PRT] - definitions, artefacts and plugins, as a library.
+- [asljs-part-cli][CLI] - the `part` command line.
+- [asljs-ui-editor][EDT] - the editor and its plugins.
+- [appbase][MDC] - the document server behind `part-srv`.
+
+## License
+
+See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[CLI]: ../part-cli/README.md
+[DOC]: docs/part-srv.md
+[EDT]: ../../../ui/editor/README.md
+[LIC]: LICENSE.md
+[MDC]: ../../../libs/appbase/README.md
+[PRT]: ../part/README.md
+[REQ]: <dev/rq/R32 part-srv server.md>

package/bin/part-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/app.d.ts

@@ -0,0 +1,10 @@
+import { type EditorApp, type EditorAppContext } from 'asljs-appbase';
+/**
+ * The part application as an editor plugin: its projects, by `part.json`.
+ * Each `part.json` `findProjects` finds from the working directory is a
+ * project. A project's root, definitions and state folder come from its own
+ * `part.json` only, else the default, when it is first requested; no option
+ * or environment variable sets them, since one value cannot suit every
+ * project.
+ */
+export declare function createApp(context: EditorAppContext): Promise<EditorApp>;

package/dist/app.js

@@ -0,0 +1,58 @@
+import { configPath, configStrings, createEditorApp, findBrowserModules, findProjects, stateFolder } from 'asljs-appbase';
+import { CONFIG_FILE, resolveDefinitionSource } from 'asljs-part';
+import { ICONS } from 'asljs-ui-editor';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createProjectHandler } from './view.js';
+/**
+ * The style of an artefact's details: a scrolling view of the tab, its
+ * table of the location, path, size and modification time, and its list of
+ * definitions.
+ */
+const STYLE = `.part-view { height: 100%; box-sizing: border-box; overflow: auto; padding: 0.75rem 1rem; line-height: 1.5; }
+.part-details { border-collapse: collapse; margin: 0 0 1rem; }
+.part-details th { text-align: left; color: #555; font-weight: normal; padding: 2px 1rem 2px 0; vertical-align: top; }
+.part-details td { padding: 2px 0; word-break: break-all; }
+.part-definitions { padding-left: 1.25rem; }
+.part-definitions li { margin: 0 0 0.6rem; }
+.part-note { color: #757575; }`;
+/**
+ * The part application as an editor plugin: its projects, by `part.json`.
+ * Each `part.json` `findProjects` finds from the working directory is a
+ * project. A project's root, definitions and state folder come from its own
+ * `part.json` only, else the default, when it is first requested; no option
+ * or environment variable sets them, since one value cannot suit every
+ * project.
+ */
+export async function createApp(context) {
+    const projects = await findProjects(context.cwd, CONFIG_FILE, context.files);
+    return createEditorApp({ id: 'part',
+        title: 'Part',
+        icon: ICONS.document,
+        base: context.base,
+        projects,
+        project: project => createProjectHandler(resolveProject(project, context)),
+        plugin: fileURLToPath(new URL('./browser/plugin.js', import.meta.url)),
+        // The page loads the plugin's packages, and what they import, from
+        // the server.
+        modules: findBrowserModules(['asljs-ui-editor'], path.dirname(fileURLToPath(import.meta.url))),
+        style: STYLE });
+}
+/**
+ * The project part reads in an application project: `project`,
+ * `definitions` and `stateDir` of its `part.json`, each path resolved
+ * against the file's folder; the root defaults to the project's folder, the
+ * state folder to `.part` in the root (`stateFolder`). A definition source
+ * may be a package specifier, not a path, so `configPaths` does not apply.
+ */
+function resolveProject(project, context) {
+    const { config } = project;
+    const root = path.normalize(configPath(config, 'project')
+        ?? project.folder);
+    return { root,
+        definitions: (configStrings(config, 'definitions')
+            ?? [])
+            .map(source => resolveDefinitionSource(source, config.folder)),
+        stateDir: stateFolder(root, 'part', config),
+        loggerProvider: context.loggerProvider };
+}

package/dist/browser/locations.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The segments of a location, for `pathTree`: its scheme with its colon, as
+ * `file:`, then each segment of its path, anything between `/` or `\`. A
+ * location without a scheme, a relative path, is a `file:` one.
+ */
+export declare function locationSegments(location: string): string[];

package/dist/browser/locations.js

@@ -0,0 +1,13 @@
+/**
+ * The segments of a location, for `pathTree`: its scheme with its colon, as
+ * `file:`, then each segment of its path, anything between `/` or `\`. A
+ * location without a scheme, a relative path, is a `file:` one.
+ */
+export function locationSegments(location) {
+    const scheme = /^[a-z][a-z0-9+.-]*:/i.exec(location)?.[0];
+    return [scheme ?? 'file:',
+        ...location
+            .slice(scheme?.length ?? 0)
+            .split(/[/\\]/)
+            .filter(segment => segment !== '')];
+}

package/dist/browser/plugin.d.ts

@@ -0,0 +1,14 @@
+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 project's files and other artefacts from
+ * `_/data.json` once, when it is made. Its Artefacts operation is a
+ * `pathTree` of their locations, grouped by `locationSegments`, its groups
+ * folded. Choosing an entry opens its details as a document whose id is
+ * `part:<location>`, rendered here from `_/artefact.json`. Its search finds
+ * artefacts by location (`searchMatcher`), at most `MAX_RESULTS` of them: a
+ * file by its path, with or without `file:`, and another artefact by its
+ * location. Every URL is relative to the project's `base`.
+ */
+declare const createPlugin: EditorPluginFactory;
+export default createPlugin;

package/dist/browser/plugin.js

@@ -0,0 +1,121 @@
+import { element, fetchJson, ICONS, note, pathTree, searchMatcher, tree } from 'asljs-ui-editor';
+import { locationSegments } from './locations.js';
+/**
+ * How many matches a search shows.
+ */
+const MAX_RESULTS = 200;
+/**
+ * The plugin of a project, the browser module of `asljs-ui-editor` the
+ * server serves. It loads the project's files and other artefacts from
+ * `_/data.json` once, when it is made. Its Artefacts operation is a
+ * `pathTree` of their locations, grouped by `locationSegments`, its groups
+ * folded. Choosing an entry opens its details as a document whose id is
+ * `part:<location>`, rendered here from `_/artefact.json`. Its search finds
+ * artefacts by location (`searchMatcher`), at most `MAX_RESULTS` of them: a
+ * file by its path, with or without `file:`, and another artefact by its
+ * location. Every URL is relative to the project's `base`.
+ */
+const createPlugin = async ({ id, base, model }) => {
+    const { files, others } = await fetchJson(base, '_/data.json');
+    const documentOf = (location, title) => ({ id: `${id}:${location}`,
+        title,
+        data: { location } });
+    const artefactsPanel = () => {
+        const locations = [...files.map(file => `file:${file}`),
+            ...others.map(other => other.location)];
+        if (locations.length === 0) {
+            return note('The project has no artefacts.');
+        }
+        return tree(model, pathTree(locations, { segments: locationSegments,
+            document: location => documentOf(location, locationSegments(location).at(-1)),
+            open: false }));
+    };
+    const renderDocument = (opened) => {
+        const { location } = opened.data;
+        const view = element('div', 'part-view');
+        void fetchJson(base, `_/artefact.json?location=${encodeURIComponent(location)}`)
+            .then(details => view.append(...detailsView(details)), (error) => view.append(note(error instanceof Error
+            ? error.message
+            : String(error))));
+        return view;
+    };
+    return { id,
+        title: 'Part',
+        icon: ICONS.document,
+        operations: [{ id: 'artefacts',
+                title: 'Artefacts',
+                icon: ICONS.document,
+                render: artefactsPanel }],
+        renderDocument,
+        search: async (query) => {
+            const matches = searchMatcher(query);
+            return [...files
+                    .filter(file => matches(`file:${file}`))
+                    .map(file => ({ document: documentOf(`file:${file}`, file),
+                    title: file })),
+                ...others
+                    .filter(other => matches(other.location))
+                    .map(other => ({ document: documentOf(other.location, other.location),
+                    title: other.location,
+                    detail: other.name }))]
+                .slice(0, MAX_RESULTS);
+        } };
+};
+export default createPlugin;
+/**
+ * The details of an artefact: its name, a table of its location and, for a
+ * file, its path, size and modification time, and the definitions that
+ * match it.
+ */
+function detailsView(details) {
+    const table = element('table', 'part-details');
+    table.append(row('Location', text(details.location)));
+    if (details.path !== null) {
+        table.append(row('Path', text(details.path)));
+    }
+    if (details.size !== null) {
+        table.append(row('Size', text(`${details.size} bytes`)));
+    }
+    if (details.modified !== null) {
+        const time = element('time', undefined, details.modified);
+        time.dateTime = details.modified;
+        table.append(row('Modified', time));
+    }
+    return [element('h1', undefined, details.name),
+        table,
+        element('h2', undefined, 'Definitions'),
+        definitionsView(details.definitions)];
+}
+function row(label, value) {
+    const made = element('tr');
+    const cell = element('td');
+    cell.append(value);
+    made.append(element('th', undefined, label), cell);
+    return made;
+}
+function text(value) {
+    return document.createTextNode(value);
+}
+/**
+ * The definitions that match an artefact, each with where it comes from and
+ * its description, or a note that none does.
+ */
+function definitionsView(definitions) {
+    if (definitions.length === 0) {
+        return note('No artefact definition matches it.');
+    }
+    const list = element('ul', 'part-definitions');
+    for (const definition of definitions) {
+        const origin = [definition.source,
+            definition.document]
+            .filter((part) => part !== null)
+            .join(', ');
+        const item = element('li');
+        item.append(element('strong', undefined, definition.name), ' ', element('span', 'part-note', `(${origin})`));
+        if (definition.description !== '') {
+            item.append(element('br'), definition.description);
+        }
+        list.append(item);
+    }
+    return list;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createApp } from './app.js';
+export { main } from './main.js';
+export { describeArtefact, listProject, type ArtefactDetails, type MatchingDefinition, type Project, type ProjectEntries } from './project.js';
+export { ARTEFACT_PATH, DATA_PATH } from './view.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createApp } from './app.js';
+export { main } from './main.js';
+export { describeArtefact, listProject } from './project.js';
+export { ARTEFACT_PATH, DATA_PATH } from './view.js';

package/dist/main.d.ts

@@ -0,0 +1,15 @@
+import { type CommandIo } from 'asljs-appbase';
+/**
+ * Run the `part-srv` command: serve the projects in a browser until SIGINT or
+ * SIGTERM, then return 0; return 1, with the message on standard error, when
+ * the arguments are wrong or the server cannot start.
+ *
+ * Each `part.json` of the working folder, `--working-dir` else the working
+ * directory, else of its folders, is a project (`createApp`), its root,
+ * definitions and state folder from that file only. The port, the host and
+ * logging come from the options, else the nearest `part.json` of the working
+ * folder or a parent: `port` and `host`, and, below the `PART_LOG_`
+ * variables, the logging keys of `docs/Logging.md` at the repository root
+ * (`runMain`). A path of `part.json` resolves against its folder.
+ */
+export declare function main(args: string[], io?: CommandIo): Promise<number>;

package/dist/main.js

@@ -0,0 +1,49 @@
+import { commandLine, configPort, configString, loadConfig, packageVersion, parsePort, runMain, serveApp } from 'asljs-appbase';
+import { CONFIG_FILE } from 'asljs-part';
+import { Command } from 'commander';
+import path from 'node:path';
+import { createApp } from './app.js';
+/**
+ * Run the `part-srv` command: serve the projects in a browser until SIGINT or
+ * SIGTERM, then return 0; return 1, with the message on standard error, when
+ * the arguments are wrong or the server cannot start.
+ *
+ * Each `part.json` of the working folder, `--working-dir` else the working
+ * directory, else of its folders, is a project (`createApp`), its root,
+ * definitions and state folder from that file only. The port, the host and
+ * logging come from the options, else the nearest `part.json` of the working
+ * folder or a parent: `port` and `host`, and, below the `PART_LOG_`
+ * variables, the logging keys of `docs/Logging.md` at the repository root
+ * (`runMain`). A path of `part.json` resolves against its folder.
+ */
+export async function main(args, io = { cwd: process.cwd(),
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr }) {
+    return await runMain(args, io, { prefix: 'PART_LOG_',
+        configFile: CONFIG_FILE }, async (loggerProvider) => {
+        const cli = commandLine(new Command('part-srv'), io, { workingDir: 'The folder the projects are looked for in; defaults to the current directory' });
+        cli
+            .description('Serve the projects of part.json files in a browser: the files of each as a tree, each with its details and the artefact definitions that match it.')
+            .version(packageVersion(import.meta.url), '--version')
+            .allowExcessArguments(false)
+            .option('--port <port>', 'Port to listen on, exactly; 0 picks a free one. By default port of part.json, else the first free port from 3000 on')
+            .option('--host <host>', 'Address to listen on. Defaults to host of part.json, then 127.0.0.1')
+            .action(async (options) => {
+            const cwd = path.resolve(io.cwd, options.workingDir ?? '.');
+            const config = await loadConfig(cwd, CONFIG_FILE);
+            await serveApp(await createApp({ cwd,
+                base: '/',
+                env: io.env,
+                loggerProvider }), { io,
+                cwd,
+                port: parsePort(options.port)
+                    ?? configPort(config),
+                host: options.host
+                    ?? configString(config, 'host'),
+                loggerProvider });
+        });
+        await cli.parseAsync(args, { from: 'user' });
+        return 0;
+    });
+}

package/dist/project.d.ts

@@ -0,0 +1,96 @@
+import { LoggerProvider } from 'asljs-logging';
+/**
+ * The project part-srv shows, and how to read it.
+ */
+export interface Project {
+    /**
+     * Absolute path of the project root.
+     */
+    root: string;
+    /**
+     * Definition sources, as `providersFactory` takes them.
+     */
+    definitions: readonly string[];
+    /**
+     * The folder part keeps its caches in; `.part` under the root when absent.
+     */
+    stateDir?: string;
+    loggerProvider: LoggerProvider;
+}
+/**
+ * What the Files panel lists: the files of the project, and the artefacts
+ * that are not files.
+ */
+export interface ProjectEntries {
+    /**
+     * Project-relative POSIX paths, sorted: every file `.gitignore` does not
+     * leave out, outside `node_modules` and dot folders, and every file a
+     * definition covers.
+     */
+    files: string[];
+    /**
+     * The artefacts that are not files, e.g. `npm:` or `git:` ones, sorted by
+     * location.
+     */
+    others: {
+        location: string;
+        name: string;
+    }[];
+}
+/**
+ * A definition that matches an artefact.
+ */
+export interface MatchingDefinition {
+    name: string;
+    /**
+     * The first paragraph of its description.
+     */
+    description: string;
+    /**
+     * Where it comes from: `markdown`, or the name of the plugin that gives it.
+     */
+    source: string;
+    /**
+     * Project-relative path of its definition document, or the absolute path
+     * of one outside the project; `null` for a definition a plugin gives
+     * without a document.
+     */
+    document: string | null;
+}
+/**
+ * What part-srv shows of a file or another artefact.
+ */
+export interface ArtefactDetails {
+    location: string;
+    name: string;
+    /**
+     * Project-relative POSIX path of a file; `null` for another artefact.
+     */
+    path: string | null;
+    /**
+     * The size of a file in bytes; `null` for another artefact.
+     */
+    size: number | null;
+    /**
+     * When a file was last modified, as an ISO 8601 UTC time; `null` for
+     * another artefact.
+     */
+    modified: string | null;
+    /**
+     * The definitions that match it, in the order part reports them; none for
+     * a file no definition covers.
+     */
+    definitions: MatchingDefinition[];
+}
+/**
+ * The files and other artefacts of the project.
+ */
+export declare function listProject(project: Project): Promise<ProjectEntries>;
+/**
+ * The details of a file or another artefact, by its location: a `file:`
+ * location, or the path of a file, gives the file, whatever definitions
+ * match it; another location gives the artefact of that location. Throws
+ * for a file that does not exist or is outside the project, and for another
+ * location no artefact has.
+ */
+export declare function describeArtefact(project: Project, location: string): Promise<ArtefactDetails>;

package/dist/project.js

@@ -0,0 +1,134 @@
+import { isInside } from 'asljs-locator';
+import { toDisplayPath } from 'asljs-appbase';
+import { FILE_SCHEME, providersFactory } from 'asljs-part';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The files and other artefacts of the project.
+ */
+export async function listProject(project) {
+    return await withProviders(project, async (providers) => {
+        const files = new Set((await providers.locationResolver.resolve(project.root, { pattern: '/**/*',
+            exclude: ['/**/node_modules/**',
+                '/**/.*/**'],
+            filters: [{ name: 'GitIgnore' }] }))
+            .map(file => toDisplayPath(project.root, file)));
+        const others = [];
+        for (const artefact of await providers.artefactProvider.getArtefacts()) {
+            if (artefact.location.startsWith(FILE_SCHEME)) {
+                files.add(artefact.location.slice(FILE_SCHEME.length));
+            }
+            else {
+                others.push({ location: artefact.location,
+                    name: artefact.name });
+            }
+        }
+        return { files: [...files].sort(),
+            others: others.sort((left, right) => left.location.localeCompare(right.location)) };
+    });
+}
+/**
+ * The details of a file or another artefact, by its location: a `file:`
+ * location, or the path of a file, gives the file, whatever definitions
+ * match it; another location gives the artefact of that location. Throws
+ * for a file that does not exist or is outside the project, and for another
+ * location no artefact has.
+ */
+export async function describeArtefact(project, location) {
+    const filePath = fileLocationPath(location);
+    return await withProviders(project, async (providers) => {
+        const artefact = await providers.artefactProvider.tryGetArtefact(fileLocationOf(location, filePath));
+        const definitions = await matchingDefinitions(project, providers, artefact?.definitions ?? []);
+        if (filePath !== null) {
+            return await describeFile(project, filePath, artefact?.name, definitions);
+        }
+        if (artefact === null) {
+            throw new Error(`No artefact at ${location}`);
+        }
+        return { location: artefact.location,
+            name: artefact.name,
+            path: null,
+            size: null,
+            modified: null,
+            definitions };
+    });
+}
+/**
+ * The project-relative path of a file location, or of a location without a
+ * scheme; `null` for any other location.
+ */
+function fileLocationPath(location) {
+    if (location.startsWith(FILE_SCHEME)) {
+        return location.slice(FILE_SCHEME.length);
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(location)) {
+        return null;
+    }
+    return location;
+}
+function fileLocationOf(location, filePath) {
+    if (filePath === null) {
+        return location;
+    }
+    return `${FILE_SCHEME}${filePath}`;
+}
+async function describeFile(project, filePath, name, definitions) {
+    const absolute = path.resolve(project.root, filePath);
+    const relative = toDisplayPath(project.root, absolute);
+    const stats = isInside(project.root, absolute, { orSame: false })
+        && await stat(absolute).catch(() => null);
+    if (!stats
+        || !stats.isFile()) {
+        throw new Error(`No file at ${filePath}`);
+    }
+    return { location: `${FILE_SCHEME}${relative}`,
+        name: name ?? path.posix.basename(relative),
+        path: relative,
+        size: stats.size,
+        modified: stats.mtime.toISOString(),
+        definitions };
+}
+/**
+ * The definitions of the names, in their order.
+ */
+async function matchingDefinitions(project, providers, names) {
+    if (names.length === 0) {
+        return [];
+    }
+    const definitions = await providers.artefactDefinitionProvider
+        .getDefinitions();
+    return names
+        .map(name => definitions.find(definition => definition.name === name))
+        .filter((definition) => definition !== undefined)
+        .map(definition => ({ name: definition.name,
+        description: firstParagraph(definition.description),
+        source: definition.source,
+        document: documentOf(project.root, definition.path) }));
+}
+function documentOf(root, document) {
+    if (document === undefined) {
+        return null;
+    }
+    if (!isInside(root, document, { orSame: false })) {
+        return document;
+    }
+    return toDisplayPath(root, document);
+}
+function firstParagraph(text) {
+    return (text.trim().split(/\n\s*\n/)[0] ?? '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Runs an action with providers made for it, and closes the content store
+ * after it, so that each request sees the project as it is.
+ */
+async function withProviders(project, action) {
+    const providers = providersFactory(project.loggerProvider, project.root, project.definitions, { stateFolder: project.stateDir });
+    try {
+        return await action(providers);
+    }
+    finally {
+        providers.contentStore.close();
+    }
+}

package/dist/view.d.ts

@@ -0,0 +1,20 @@
+import { type RequestHandler } from 'asljs-appbase';
+import { type Project } from './project.js';
+/**
+ * The details of an artefact, `describeArtefact`, by its `location` in the
+ * query, as JSON, relative to the project's path.
+ */
+export declare const ARTEFACT_PATH = "/_/artefact.json";
+/**
+ * The files and other artefacts of the project, `listProject`, as JSON,
+ * relative to the project's path.
+ */
+export declare const DATA_PATH = "/_/data.json";
+/**
+ * The handler of a project, relative to where it is mounted. It answers
+ * data, which the plugin renders: `DATA_PATH` the files and the other
+ * artefacts of the project, and `ARTEFACT_PATH` the details of an artefact,
+ * or 404 with `{ error }` saying why there is none. No file of the project
+ * is served; the project is read on every request.
+ */
+export declare function createProjectHandler(project: Project): RequestHandler;

package/dist/view.js

@@ -0,0 +1,32 @@
+import { createHandler, jsonReply, messageOf } from 'asljs-appbase';
+import { describeArtefact, listProject } from './project.js';
+/**
+ * The details of an artefact, `describeArtefact`, by its `location` in the
+ * query, as JSON, relative to the project's path.
+ */
+export const ARTEFACT_PATH = '/_/artefact.json';
+/**
+ * The files and other artefacts of the project, `listProject`, as JSON,
+ * relative to the project's path.
+ */
+export const DATA_PATH = '/_/data.json';
+/**
+ * The handler of a project, relative to where it is mounted. It answers
+ * data, which the plugin renders: `DATA_PATH` the files and the other
+ * artefacts of the project, and `ARTEFACT_PATH` the details of an artefact,
+ * or 404 with `{ error }` saying why there is none. No file of the project
+ * is served; the project is read on every request.
+ */
+export function createProjectHandler(project) {
+    return createHandler({ folder: project.root,
+        json: { [DATA_PATH]: async () => await listProject(project),
+            [ARTEFACT_PATH]: async (url) => {
+                try {
+                    return await describeArtefact(project, url.searchParams.get('location') ?? '');
+                }
+                catch (error) {
+                    return jsonReply(404, { error: `${messageOf(error)}.` });
+                }
+            } },
+        allow: () => false });
+}

package/docs/part-srv.md

@@ -0,0 +1,126 @@
+# part-srv
+
+Starts a web server that shows the files of projects and the artefact
+definitions that match each, and runs until stopped, by SIGINT (Ctrl+C) or
+SIGTERM.
+
+```text
+part-srv [--working-dir <folder>] [--port <port>] [--host <host>]
+         [--loglevel <level>] [--logfile <target>] [--logformat <format>]
+```
+
+The server listens on `127.0.0.1` and prints the folder of its projects and its
+address when it starts.
+
+```text
+part-srv --working-dir ~/work --port 8080
+```
+
+## Projects
+
+A project is a folder with its own `part.json`, looked for in the working
+folder, `--working-dir` or else the working directory:
+
+- When the working folder has a `part.json`, it is the one project.
+- Otherwise, every folder below it that has a `part.json` is a project, by its
+  path from the working folder, leaving out what `.gitignore` ignores, `.git`
+  and `node_modules`.
+- With none, the working folder is the one project, with the nearest `part.json`
+  of a parent, or none.
+
+The root, the definitions and the state folder of each project come from its own
+`part.json` only, `project`, `definitions` and `stateDir`, its paths resolved
+against its folder; see [Options][OPT] for the keys. Without `project`, the root
+is the project's folder; without `definitions`, no definition matches anything;
+without `stateDir`, the state folder is `.part` under the project. No option or
+environment variable of the server sets them, since one value cannot suit every
+project: `PART_PROJECT`, `PART_DEFINITIONS` and `PART_STATE_DIR` are read by
+`part` only. They are read when the project is first opened: an invalid key of
+one project's `part.json` fails the requests of that project only.
+
+## Pages
+
+The paths are relative to where the server serves `part-srv`, `/` alone; a
+server that shows several applications serves it at `/part/`.
+
+- `/` - an editor filling the window, built with [`asljs-editor`][ED] of
+  `asljs-ui-editor`, whose only plugin is part. Down the left is a column of
+  operations, and beside it the open details as tabs. Pressing the operation's
+  icon opens its panel next to the column; the button at the bottom of the
+  column hides and shows the panel. Dragging the panel's inner edge resizes it,
+  and the browser remembers the width, and the project shown, for the next
+  visit. With more than one project, a list box heads the panel; choosing
+  another project closes the details of the one before.
+  - **Artefacts** - the artefacts of the project as one tree of their locations,
+    folded at first: grouped by scheme, such as `file:`, `npm:` or `git:`, then
+    by each segment of the path, anything between `/` or `\`, as `npm:` >
+    `apps` > `kb` > `package.json#dependencies` > `asljs-part`; a location
+    without a scheme is a `file:` one. In each group its groups come first, then
+    its artefacts, by name. The files are every file `.gitignore` does not leave
+    out, outside `node_modules` and dot folders, and every file a definition
+    covers.
+  - **Search** - the shared search of the editor: the files and other artefacts
+    whose location holds the text, regardless of case unless Match case is
+    checked, or matches it as a regular expression: a file by its path, with or
+    without `file:`. At most 200 are listed.
+
+  Choosing a file or an artefact opens its details as a tab, or shows its tab
+  when it is open; the active one is marked in the list. The tab is a preview,
+  with its title in italics, which the next one chosen replaces, until it is
+  double clicked. A tab closes with its ×, a middle click, or Delete on the tab.
+  The details are rendered in the browser from `_/artefact.json`: the artefact's
+  name and location; for a file, its path, its size and when it was last
+  modified, in UTC; the artefact definitions that match it, each with where it
+  comes from - `markdown` or a plugin, and its definition document - and the
+  first paragraph of its description; a file no definition matches says so. A
+  file that does not exist, a path outside the project and an unknown location
+  give a note that says so.
+- `/_/app.json` - the application and its projects, each with the path it is
+  served at; `/_/plugin/plugin.js` - the plugin the editor loads, a browser
+  module, with the modules beside it under `/_/plugin/`.
+- `/p/<project>/` - a project, by its path from the working folder, `~` for the
+  working folder itself. It answers data only, which the plugin renders:
+  - `/p/<project>/_/data.json` - `{ files, others }`, the files and the other
+    artefacts of the project, which the plugin loads once, when the project is
+    shown;
+  - `/p/<project>/_/artefact.json?location=<location>` - the details of a file
+    or another artefact: `{ location, name, path, size, modified, definitions
+    }`, `path`, `size` and `modified` `null` for an artefact that is not a file,
+    and each definition `{ name, description, source, document }`. A location is
+    a `file:` location, a path relative to the project root, or the location of
+    another artefact. When there is none, the answer is 404 with `{ error }`,
+    the message the details tab shows.
+
+The content of a file is never read or served: the server answers the details
+only, and serves nothing of a project but its data. The project is read on every
+request, so a reload shows the files as they are. The page loads
+`asljs-ui-editor` and what it imports from the server, under `/modules/`, so it
+needs no network.
+
+## Options
+
+- `--working-dir <folder>` - the folder the projects are looked for in, resolved
+  against the working directory; the working directory by default.
+- `--port <port>` - the port, exactly: one in use is an error, and 0 picks any
+  free one. Without it, `port` of `part.json`, else the first free port from
+  3000 on, up to 3099.
+- `--host <host>` - the address to listen on; `host` of `part.json`, else
+  `127.0.0.1`.
+- `--loglevel`, `--logfile`, `--logformat` - logging, silent by default; they
+  take precedence over `PART_LOG_LEVEL`, `PART_LOG_FILE` and `PART_LOG_FORMAT`,
+  which take precedence over `logLevel`, `logFile` and `logFormat` of
+  `part.json`. See [Logging][LG].
+- `--version`, `--help` - print the version of `asljs-part-srv`, or the help.
+
+The `part.json` of `port`, `host` and logging is the nearest one in the working
+folder or a parent of it; that of a project's settings is the project's, see
+[Projects][PRJ]. A path of the file resolves against its folder; see
+[Configuration][CFG] and the keys in [Options][OPT]. A `part.json` that cannot
+be read, or a wrong `port`, `host` or logging key, stops the server with a
+message naming the file.
+
+[CFG]: ../../../../docs/Configuration.md
+[ED]: ../../../../ui/editor/docs/Editor.md
+[LG]: ../../../../docs/Logging.md
+[OPT]: ../../part-cli/docs/Options.md
+[PRJ]: #projects

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "asljs-part-srv",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The part-srv web server: a project's files in an editor, each with its details and the artefact definitions that match it.",
+  "type": "module",
+  "asljs": {
+    "type": "app"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "part-srv": "bin/part-srv.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin/**",
+    "dist/**",
+    "docs/**",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "artefacts",
+    "project",
+    "server"
+  ],
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "dependencies": {
+    "asljs-locator": "^0.1.1",
+    "asljs-logging": "^0.1.1",
+    "asljs-appbase": "^0.1.3",
+    "asljs-part": "^0.3.2",
+    "asljs-ui-editor": "^0.1.1",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.0",
+    "asljs-tmpdir": "^0.1.13",
+    "asljs-toolkit": "^0.1.0"
+  }
+}