asljs-appbase 0.0.0-stage → 0.1.5

package/dist/editor-app.js

@@ -0,0 +1,268 @@
+import { loadConfig } from 'asljs-cmdbase';
+import path from 'node:path';
+import { createImportMap, MODULES_PREFIX } from './browser-modules.js';
+import { listFiles } from './files.js';
+import { createHandler, mountHandlers, page, scriptJson, send, serve, serverUrl, untilStopped } from './server.js';
+/**
+ * The path an application serves its plugin's folder at.
+ */
+const PLUGIN_PREFIX = '/_/plugin/';
+/**
+ * The projects of an application in `folder`, by its configuration file
+ * `name`, e.g. `kb.json`: the folder itself when it has the file; else every
+ * folder below it that has one, by id; else the folder itself, with the
+ * nearest file of a parent, or with none (`loadConfig`). The files are
+ * `files`, the files of `folder` as `listFiles` gives them, so that a server
+ * of several applications lists them once; `listFiles(folder)` when absent.
+ *
+ * With `required`, a project needs the file: when the folder, the folders
+ * below it and those above it have none, it throws, for an application whose
+ * projects cannot be told without it, e.g. which artefacts a part project
+ * supports.
+ */
+export async function findProjects(folder, name, files, options = {}) {
+    const root = path.resolve(folder);
+    const listed = files
+        ?? await listFiles(root);
+    if (listed.includes(name)) {
+        return [await toProject(root, root, name)];
+    }
+    const suffix = `/${name}`;
+    const folders = listed
+        .filter(file => file.endsWith(suffix))
+        .map(file => path.join(root, file.slice(0, -suffix.length)));
+    if (folders.length > 0) {
+        return (await Promise.all(folders.map(found => toProject(root, found, name))))
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    const project = await toProject(root, root, name);
+    if (options.required === true
+        && project.config.file === null) {
+        throw new Error(`No ${name} in ${root}, in a folder below it, or in a folder above it.`);
+    }
+    return [project];
+}
+/**
+ * The projects of an application in the folders of `context` by its
+ * configuration file `name`: `findProjects` of `cwd` and `files` alone, or of
+ * each of `folders` when there are several. Then the id of a project starts
+ * with the name of its folder, `docs/notes` for `notes` of `docs`, the name
+ * alone for the folder itself, and a name that two folders share gets `-2`,
+ * `-3` and so on after the first. With `required`, a folder without the file
+ * has no project, and an error is thrown only when no folder has one.
+ */
+export async function findAppProjects(context, name, options = {}) {
+    const folders = context.folders
+        ?? [{ cwd: context.cwd,
+                files: context.files }];
+    if (folders.length === 1) {
+        return await findProjects(folders[0].cwd, name, folders[0].files, options);
+    }
+    const labels = folderLabels(folders.map(folder => folder.cwd));
+    const projects = [];
+    for (const [index, folder] of folders.entries()) {
+        for (const project of await findProjects(folder.cwd, name, folder.files)) {
+            if (options.required === true
+                && project.config.file === null) {
+                continue;
+            }
+            const id = project.id === '.'
+                ? labels[index]
+                : `${labels[index]}/${project.id}`;
+            projects.push({ ...project,
+                id,
+                title: id });
+        }
+    }
+    if (projects.length === 0) {
+        throw new Error(`No ${name} in ${folders
+            .map(folder => path.resolve(folder.cwd))
+            .join(', ')}, in a folder below them, or in a folder above them.`);
+    }
+    return projects;
+}
+/**
+ * The name of each folder, by its base name, `-2`, `-3` and so on added to a
+ * name an earlier folder has.
+ */
+function folderLabels(folders) {
+    const labels = [];
+    for (const folder of folders) {
+        const resolved = path.resolve(folder);
+        const base = path.basename(resolved)
+            || resolved;
+        let label = base;
+        for (let n = 2; labels.includes(label); n++) {
+            label = `${base}-${n}`;
+        }
+        labels.push(label);
+    }
+    return labels;
+}
+async function toProject(root, folder, name) {
+    const id = path.relative(root, folder)
+        .split(path.sep)
+        .join('/')
+        || '.';
+    return { id,
+        title: id === '.'
+            ? path.basename(root)
+            : id,
+        folder,
+        config: await loadConfig(folder, name) };
+}
+/**
+ * The segment of a project in its path: its id, `~` for `.`.
+ */
+export function projectSegment(id) {
+    return id === '.'
+        ? '~'
+        : encodeURIComponent(id);
+}
+/**
+ * An application served as an editor plugin; see `EditorApp`.
+ */
+export function createEditorApp(options) {
+    const base = options.base ?? '/';
+    const handlers = new Map();
+    const closers = [];
+    const modules = createHandler({ folder: '/',
+        modules: options.modules,
+        index: async () => '',
+        allow: () => false });
+    const style = options.style ?? '';
+    const pluginFiles = createHandler({ folder: path.dirname(options.plugin),
+        methods: ['GET',
+            'HEAD'],
+        allow: relative => /\.(?:m?js|map)$/.test(relative) });
+    const descriptor = () => ({ id: options.id,
+        title: options.title,
+        icon: options.icon,
+        plugin: `${base}${PLUGIN_PREFIX.slice(1)}${encodeURIComponent(path.basename(options.plugin))}`,
+        projects: options.projects.map(project => ({ id: project.id,
+            title: project.title,
+            base: `${base}p/${projectSegment(project.id)}/` })) });
+    const handler = async (request, response, url) => {
+        if (url.pathname === '/') {
+            send(response, 200, 'text/html; charset=utf-8', editorPage({ title: options.title,
+                apps: [`${base}_/app.json`],
+                modules: options.modules,
+                style }));
+            return;
+        }
+        if (url.pathname === '/_/app.json') {
+            send(response, 200, 'application/json; charset=utf-8', JSON.stringify(descriptor()));
+            return;
+        }
+        if (url.pathname.startsWith(PLUGIN_PREFIX)) {
+            const inner = new URL(url);
+            inner.pathname =
+                url.pathname.slice(PLUGIN_PREFIX.length - 1);
+            await pluginFiles(request, response, inner);
+            return;
+        }
+        if (url.pathname.startsWith(MODULES_PREFIX)) {
+            await modules(request, response, url);
+            return;
+        }
+        const match = /^\/p\/([^/]+)(\/.*)?$/.exec(url.pathname);
+        const id = match === null
+            ? undefined
+            : match[1] === '~'
+                ? '.'
+                : decodeURIComponent(match[1]);
+        const project = options.projects.find(candidate => candidate.id === id);
+        if (match === null
+            || project === undefined) {
+            send(response, 404, 'text/plain; charset=utf-8', `Not found: ${url.pathname}`);
+            return;
+        }
+        if (match[2] === undefined) {
+            response.writeHead(302, { location: `${base}p/${match[1]}/${url.search}` });
+            response.end();
+            return;
+        }
+        let made = handlers.get(project.id);
+        if (made === undefined) {
+            made =
+                Promise.resolve(options.project(project, { base: `${base}p/${match[1]}/`,
+                    onClose: action => closers.push(action) }));
+            handlers.set(project.id, made);
+        }
+        const inner = new URL(url);
+        inner.pathname = match[2];
+        await (await made)(request, response, inner);
+    };
+    return { id: options.id,
+        title: options.title,
+        base,
+        style,
+        modules: options.modules,
+        handler,
+        close: async () => {
+            for (const close of closers.splice(0)) {
+                await close();
+            }
+        } };
+}
+/**
+ * A handler for several applications, each mounted at `/<id>/`, which is the
+ * `base` it was made with: `/` is the editor with every application as a
+ * plugin, and `/modules/...` the modules of them all.
+ */
+export function combineEditorApps(title, apps) {
+    const modules = [...new Map(apps
+            .flatMap(app => app.modules)
+            .map(module => [module.name,
+            module]))
+            .values()];
+    const files = createHandler({ folder: '/',
+        modules,
+        index: async () => '',
+        allow: () => false });
+    const style = apps
+        .map(app => app.style)
+        .join('\n');
+    return mountHandlers(Object.fromEntries(apps.map(app => [app.id,
+        app.handler])), async (request, response, url) => {
+        if (url.pathname === '/') {
+            send(response, 200, 'text/html; charset=utf-8', editorPage({ title,
+                apps: apps.map(app => `${app.base}_/app.json`),
+                modules,
+                style }));
+            return;
+        }
+        await files(request, response, url);
+    });
+}
+/**
+ * An editor page whose plugins are the applications of `apps`, the URLs of
+ * their `/_/app.json`; see `mountEditorApps` of `asljs-ui-editor`.
+ */
+export function editorPage(options) {
+    return page(options.title, `<script type="importmap">${scriptJson(createImportMap(options.modules, MODULES_PREFIX))}</script>
+<asljs-editor id="editor"></asljs-editor>
+<script type="module">
+import { mountEditorApps } from 'asljs-ui-editor';
+await mountEditorApps(
+  document.getElementById('editor'),
+  ${scriptJson(options.apps)},
+  { storageKey: ${scriptJson(`asljs-editor:${options.title}`)} });
+</script>`, options.style ?? '');
+}
+/**
+ * Serves an editor application, as `<app>-srv` does: prints where it serves
+ * `cwd`, serves until SIGINT or SIGTERM, then closes the application.
+ */
+export async function serveApp(app, options) {
+    const server = await serve(app.handler, { port: options.port,
+        host: options.host,
+        logger: options.loggerProvider.getLogger(`${app.id}.srv`) });
+    options.io.stdout.write(`Serving ${options.cwd} at ${serverUrl(server)}\n`);
+    try {
+        await untilStopped(server);
+    }
+    finally {
+        await app.close();
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,25 @@
+export interface FindOptions {
+    /**
+     * Names of folders to skip besides those starting with `.` and
+     * `node_modules`, e.g. `Archive`.
+     */
+    skip?: readonly string[];
+}
+/**
+ * Every markdown file of a folder and its subfolders, sorted, by absolute
+ * path, as the `LocationResolver` of `asljs-locator` finds them: skipping
+ * folders whose name starts with `.`, `node_modules`, and the `skip` names.
+ */
+export declare function findMarkdownFiles(folder: string, options?: FindOptions): Promise<string[]>;
+/**
+ * Every file of a folder and its subfolders, relative to it with `/`
+ * separators, sorted, as the `LocationResolver` of `asljs-locator` finds them:
+ * what `.gitignore` files ignore is left out, and so are `.git` and
+ * `node_modules`. One list serves every search of the folder's files, such as
+ * each application's `findProjects`.
+ */
+export declare function listFiles(folder: string): Promise<string[]>;
+/**
+ * A path relative to `folder`, with `/` separators.
+ */
+export declare function toDisplayPath(folder: string, file: string): string;

package/dist/files.js

@@ -0,0 +1,48 @@
+import { LocationResolver } from 'asljs-locator';
+import { NullLogger } from 'asljs-logging';
+import path from 'node:path';
+/**
+ * Every markdown file of a folder and its subfolders, sorted, by absolute
+ * path, as the `LocationResolver` of `asljs-locator` finds them: skipping
+ * folders whose name starts with `.`, `node_modules`, and the `skip` names.
+ */
+export async function findMarkdownFiles(folder, options = {}) {
+    const root = path.resolve(folder);
+    return (await new LocationResolver(new NullLogger(), root)
+        .resolve(root, 
+    // Any case of the extension, as `.MD`.
+    { patterns: ['**/*.md',
+            '**/*.MD',
+            '**/*.Md',
+            '**/*.mD'],
+        exclude: ['**/.*/**',
+            '**/node_modules/**',
+            ...(options.skip ?? []).map(name => `**/${name}/**`)] }))
+        .sort();
+}
+/**
+ * Every file of a folder and its subfolders, relative to it with `/`
+ * separators, sorted, as the `LocationResolver` of `asljs-locator` finds them:
+ * what `.gitignore` files ignore is left out, and so are `.git` and
+ * `node_modules`. One list serves every search of the folder's files, such as
+ * each application's `findProjects`.
+ */
+export async function listFiles(folder) {
+    const root = path.resolve(folder);
+    const files = await new LocationResolver(new NullLogger(), root)
+        .resolve(root, { pattern: '**/*',
+        exclude: ['.git/**',
+            '**/node_modules/**'],
+        filters: [{ name: 'GitIgnore' }] });
+    return files
+        .map(file => toDisplayPath(root, file))
+        .sort();
+}
+/**
+ * A path relative to `folder`, with `/` separators.
+ */
+export function toDisplayPath(folder, file) {
+    return path.relative(folder, file)
+        .split(path.sep)
+        .join('/');
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createImportMap, findBrowserModules, findModuleFile, MODULES_PREFIX, type BrowserModule } from './browser-modules.js';
+export { commandLine, configBoolean, configLogging, configPath, configPaths, configPort, configString, configStrings, loadCommandLineConfig, loadConfig, messageOf, packageVersion, parsePort, readOptionValue, runMain, workingFolder, type CommandIo, type Config } from 'asljs-cmdbase';
+export { combineEditorApps, createEditorApp, editorPage, findAppProjects, findProjects, projectSegment, serveApp, type EditorApp, type EditorAppContext, type EditorAppDescriptor, type EditorAppOptions, type Project, type ProjectContext, type WorkingFolder } from './editor-app.js';
+export { findMarkdownFiles, listFiles, toDisplayPath, type FindOptions } from './files.js';
+export { findSectionHeading, formatUrl, getSection, parseMarkdown, plainText, splitLocalUrl, type MarkdownNode } from './markdown.js';
+export { findConfig, postProcess, takeWritten, writeMarkdown, type PostProcessIo, type ToolConfig } from './post-process.js';
+export { createHandler, DEFAULT_PORT, escapeHtml, jsonReply, mountHandlers, page, scriptJson, send, serve, serverUrl, startServer, untilStopped, versionConflict, type HandlerOptions, type JsonReply, type ListenOptions, type PostReply, type RequestHandler, type ServerOptions } from './server.js';
+export { stateFolder, type GivenStateFolder } from './state-folder.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createImportMap, findBrowserModules, findModuleFile, MODULES_PREFIX } from './browser-modules.js';
+export { commandLine, configBoolean, configLogging, configPath, configPaths, configPort, configString, configStrings, loadCommandLineConfig, loadConfig, messageOf, packageVersion, parsePort, readOptionValue, runMain, workingFolder } from 'asljs-cmdbase';
+export { combineEditorApps, createEditorApp, editorPage, findAppProjects, findProjects, projectSegment, serveApp } from './editor-app.js';
+export { findMarkdownFiles, listFiles, toDisplayPath } from './files.js';
+export { findSectionHeading, formatUrl, getSection, parseMarkdown, plainText, splitLocalUrl } from './markdown.js';
+export { findConfig, postProcess, takeWritten, writeMarkdown } from './post-process.js';
+export { createHandler, DEFAULT_PORT, escapeHtml, jsonReply, mountHandlers, page, scriptJson, send, serve, serverUrl, startServer, untilStopped, versionConflict } from './server.js';
+export { stateFolder } from './state-folder.js';

package/dist/markdown.d.ts

@@ -0,0 +1,27 @@
+import { type Heading, type Root, type RootContent } from 'mdast';
+export type MarkdownNode = Root | RootContent;
+export declare function parseMarkdown(text: string): Root;
+/**
+ * The level 2 heading with the given text.
+ */
+export declare function findSectionHeading(root: Root, name: string): Heading | null;
+/**
+ * The nodes between a level 2 heading and the next heading of level 1 or 2,
+ * or `null` when there is no such heading.
+ */
+export declare function getSection(root: Root, name: string): RootContent[] | null;
+export declare function plainText(node: MarkdownNode): string;
+/**
+ * Splits a link target that points at a local file into the path, with
+ * percent-encoding decoded, and the `#` fragment; `null` for a target with a
+ * scheme, a protocol-relative, root-relative or fragment-only target.
+ */
+export declare function splitLocalUrl(url: string): {
+    path: string;
+    fragment: string;
+} | null;
+/**
+ * A link target in the form written by `rq`: in angle brackets when it has
+ * spaces or parentheses.
+ */
+export declare function formatUrl(url: string): string;

package/dist/markdown.js

@@ -0,0 +1,84 @@
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+export function parseMarkdown(text) {
+    return unified()
+        .use(remarkParse)
+        .parse(text);
+}
+/**
+ * The level 2 heading with the given text.
+ */
+export function findSectionHeading(root, name) {
+    return root.children.find((node) => node.type === 'heading'
+        && node.depth === 2
+        && plainText(node) === name)
+        ?? null;
+}
+/**
+ * The nodes between a level 2 heading and the next heading of level 1 or 2,
+ * or `null` when there is no such heading.
+ */
+export function getSection(root, name) {
+    const heading = findSectionHeading(root, name);
+    if (!heading) {
+        return null;
+    }
+    const nodes = [];
+    for (const node of root.children.slice(root.children.indexOf(heading) + 1)) {
+        if (node.type === 'heading'
+            && node.depth <= 2) {
+            break;
+        }
+        nodes.push(node);
+    }
+    return nodes;
+}
+export function plainText(node) {
+    if ('value' in node) {
+        return node.value;
+    }
+    if ('children' in node) {
+        return node.children
+            .map(child => plainText(child))
+            .join('');
+    }
+    return '';
+}
+/**
+ * Splits a link target that points at a local file into the path, with
+ * percent-encoding decoded, and the `#` fragment; `null` for a target with a
+ * scheme, a protocol-relative, root-relative or fragment-only target.
+ */
+export function splitLocalUrl(url) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(url)
+        || url.startsWith('/')
+        || url.startsWith('#')
+        || url === '') {
+        return null;
+    }
+    const hash = url.indexOf('#');
+    const encoded = hash < 0
+        ? url
+        : url.slice(0, hash);
+    let decoded;
+    try {
+        decoded =
+            decodeURIComponent(encoded);
+    }
+    catch {
+        decoded = encoded;
+    }
+    return { path: decoded,
+        fragment: hash < 0
+            ? ''
+            : url.slice(hash) };
+}
+/**
+ * A link target in the form written by `rq`: in angle brackets when it has
+ * spaces or parentheses.
+ */
+export function formatUrl(url) {
+    return /[\s()]/.test(url)
+        ? `<${url}>`
+        : url;
+}

package/dist/post-process.d.ts

@@ -0,0 +1,50 @@
+import { type Logger } from 'asljs-logging';
+/**
+ * What a tool's configuration file, e.g. `rq.json`, says.
+ */
+export interface ToolConfig {
+    /**
+     * A command line run, in the folder of the configuration file, with the
+     * markdown files a command wrote as arguments, e.g. a project's formatter
+     * and linter.
+     */
+    markdownPostProcessing?: string;
+}
+/**
+ * Where `postProcess` reports a failure.
+ */
+export interface PostProcessIo {
+    cwd: string;
+    stderr: {
+        write(text: string): unknown;
+    };
+    /**
+     * Where the command line and its exit code are logged; nothing is logged
+     * when absent.
+     */
+    logger?: Logger;
+}
+/**
+ * Writes a markdown file and remembers it for `postProcess`.
+ */
+export declare function writeMarkdown(file: string, text: string): Promise<void>;
+/**
+ * The markdown files written since the last call, and forgets them.
+ */
+export declare function takeWritten(): string[];
+/**
+ * The nearest configuration file named `name`, e.g. `rq.json`, of `folder` or
+ * a parent, and its folder; `null` when there is none.
+ */
+export declare function findConfig(folder: string, name: string): Promise<{
+    folder: string;
+    config: ToolConfig;
+} | null>;
+/**
+ * Runs the `markdownPostProcessing` command of the nearest configuration file
+ * named `config`, e.g. `rq.json`, with the markdown files a command wrote and
+ * that still exist, relative to the folder of the configuration file, where it
+ * runs. Returns 1 and reports the output when the command fails, 0 otherwise
+ * or when there is nothing to do.
+ */
+export declare function postProcess(io: PostProcessIo, files: readonly string[], config: string): Promise<number>;

package/dist/post-process.js

@@ -0,0 +1,84 @@
+import { runCommand } from 'asljs-agents';
+import { loadConfig } from 'asljs-cmdbase';
+import { NullLogger } from 'asljs-logging';
+import { stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const written = new Set();
+/**
+ * Writes a markdown file and remembers it for `postProcess`.
+ */
+export async function writeMarkdown(file, text) {
+    await writeFile(file, text, 'utf8');
+    written.add(path.resolve(file));
+}
+/**
+ * The markdown files written since the last call, and forgets them.
+ */
+export function takeWritten() {
+    const files = [...written];
+    written.clear();
+    return files;
+}
+/**
+ * The nearest configuration file named `name`, e.g. `rq.json`, of `folder` or
+ * a parent, and its folder; `null` when there is none.
+ */
+export async function findConfig(folder, name) {
+    const config = await loadConfig(folder, name);
+    if (config.folder === null) {
+        return null;
+    }
+    const command = config.values.markdownPostProcessing;
+    if (command !== undefined
+        && typeof command
+            !== 'string') {
+        throw new Error(`${config.file}: "markdownPostProcessing" must be a command line.`);
+    }
+    return { folder: config.folder,
+        config: config.values };
+}
+/**
+ * Runs the `markdownPostProcessing` command of the nearest configuration file
+ * named `config`, e.g. `rq.json`, with the markdown files a command wrote and
+ * that still exist, relative to the folder of the configuration file, where it
+ * runs. Returns 1 and reports the output when the command fails, 0 otherwise
+ * or when there is nothing to do.
+ */
+export async function postProcess(io, files, config) {
+    const existing = [];
+    for (const file of files) {
+        if ((await stat(file).catch(() => null))?.isFile()) {
+            existing.push(file);
+        }
+    }
+    if (existing.length === 0) {
+        return 0;
+    }
+    const found = await findConfig(io.cwd, config);
+    const command = found?.config.markdownPostProcessing?.trim();
+    if (found === null
+        || command === undefined
+        || command === '') {
+        return 0;
+    }
+    const line = [command,
+        ...existing.map(file => JSON.stringify(path.relative(found.folder, file)
+            .split(path.sep)
+            .join('/')))]
+        .join(' ');
+    const logger = io.logger ?? new NullLogger();
+    logger.debug({ command: line,
+        cwd: found.folder }, 'post-processing');
+    const run = await runCommand(line, found.folder)
+        .catch((error) => ({ code: -1,
+        stdout: '',
+        stderr: error instanceof Error
+            ? error.message
+            : String(error) }));
+    logger.debug({ code: run.code }, 'post-processing exited');
+    if (run.code === 0) {
+        return 0;
+    }
+    io.stderr.write(`Post-processing failed: ${command} exited with code ${run.code}\n${`${run.stdout}${run.stderr}`.trimEnd()}\n`);
+    return 1;
+}