asljs-appbase 0.0.0-stage → 0.1.5

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,82 @@
-# Temporary Holding Version
+# appbase
 
-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.
+
+The base the applications of this repository are built on: their configuration
+files and state folders, the entry point of an executable, markdown, and serving
+documents and editor applications in a browser.
+
+## Overview
+
+The applications - `rq`, `kb`, `part`, `cog`, `board`, `dash` and the tools -
+share these parts:
+
+- **Configuration** - read an application's `<app>.json`, and find the folder it
+  keeps its state in, `.<app>`.
+- **Executables** - the logging options, errors and exit codes of a command
+  line, a web server or an MCP server.
+- **Editor applications** - an application served as a plugin of the editor,
+  with a project per configuration file, alone or with the others.
+- **Markdown** - parse a document, read a section, plain text and local links.
+- **Files** - find the markdown files of a folder.
+- **Post-processing** - remember the files a command wrote, and run the
+  project's formatter on them, named in the tool's configuration file.
+- **Server** - serve a folder's data: its files as they are, markdown as its
+  text, and JSON values, on the first free port from 3000; the page renders
+  them.
+
+## Scope
+
+- Node.js, ES modules.
+- The server is for local use: it serves every file inside its folder, and
+  renders nothing.
+
+## Installation
+
+```bash
+npm install asljs-appbase
+```
+
+## Usage
+
+```ts
+import { getSection,
+         parseMarkdown,
+         plainText }
+  from 'asljs-appbase';
+
+const root =
+  parseMarkdown('# R1 Export\n\n## Implementation\n\n- [T1](<tests/T1 PDF.md>)\n');
+
+const items =
+  getSection(
+    root,
+    'Implementation')
+    ?.map(plainText);
+
+console.log(items);
+```
+
+## Further reading
+
+- [appbase][MD] - every export.
+
+## Related packages
+
+- `asljs-cmdbase` reads the configuration file and starts an executable; this
+  package re-exports it.
+- `asljs-rq` manages requirements in markdown, and `asljs-rq-srv` shows them
+  with this package's server.
+- `asljs-board` keeps a planning board in markdown, and `asljs-board-srv` shows
+  it with this package's server.
+- `asljs-kb` manages a markdown knowledge base, and `asljs-kb-srv` shows it with
+  this package's server.
+- `asljs-mcp` serves a tool's commands over MCP.
+
+## License
+
+MIT
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[MD]: docs/appbase.md

package/dist/browser-modules.d.ts

@@ -0,0 +1,36 @@
+/** A package the browser page loads, and where its files are. */
+export interface BrowserModule {
+    name: string;
+    /** The package folder on disk. */
+    root: string;
+    /** The ES module entry, relative to `root`, with forward slashes. */
+    entry: string;
+    /**
+     * The ES module of each subpath its `exports` names, e.g. `wiki` for
+     * `asljs-kb/wiki`, relative to `root`, with forward slashes.
+     */
+    subpaths?: Readonly<Record<string, string>>;
+}
+/** The path the server serves `modules` under: `/modules/<name>/<file>`. */
+export declare const MODULES_PREFIX = "/modules/";
+/**
+ * Finds `name`, or each of the names, looked up from the folder `from`, and
+ * every package it depends on, at runtime, the way Node resolves them: in the
+ * `node_modules` folders above the folder of the package that depends on it.
+ */
+export declare function findBrowserModules(name: string | readonly string[], from: string): BrowserModule[];
+/**
+ * The import map that points each module name at its served entry, each
+ * subpath its `exports` names, as `asljs-kb/wiki`, at its module, and each
+ * `<name>/` at its folder, for a module that imports a file of a package, as
+ * lit imports `lit/decorators.js`.
+ */
+export declare function createImportMap(modules: readonly BrowserModule[], prefix: string): {
+    imports: Record<string, string>;
+};
+/**
+ * The file of a module a request names, by the path after `MODULES_PREFIX`:
+ * `<name>/<file>` inside that module's folder, or `null` for an unknown module
+ * or a path that leaves its folder.
+ */
+export declare function findModuleFile(rest: string, modules: readonly BrowserModule[]): string | null;

package/dist/browser-modules.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The path the server serves `modules` under: `/modules/<name>/<file>`. */
+export const MODULES_PREFIX = '/modules/';
+/** Export conditions tried in order for a browser ES module entry. */
+const CONDITIONS = ['browser',
+    'import',
+    'module',
+    'default'];
+/**
+ * Finds `name`, or each of the names, looked up from the folder `from`, and
+ * every package it depends on, at runtime, the way Node resolves them: in the
+ * `node_modules` folders above the folder of the package that depends on it.
+ */
+export function findBrowserModules(name, from) {
+    const found = new Map();
+    const pending = (typeof name === 'string'
+        ? [name]
+        : name)
+        .map(root => [root,
+        from]);
+    while (pending.length > 0) {
+        const [next, base] = pending.pop();
+        if (found.has(next)) {
+            continue;
+        }
+        const root = findPackageRoot(next, base);
+        if (!root) {
+            throw new Error(`Cannot find the package ${next} from ${base}.`);
+        }
+        const json = readPackageJson(root);
+        found.set(next, { name: next,
+            root,
+            entry: entryOf(json),
+            subpaths: subpathsOf(json) });
+        for (const dependency of Object.keys(json.dependencies ?? {})) {
+            pending.push([dependency,
+                root]);
+        }
+    }
+    return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * The import map that points each module name at its served entry, each
+ * subpath its `exports` names, as `asljs-kb/wiki`, at its module, and each
+ * `<name>/` at its folder, for a module that imports a file of a package, as
+ * lit imports `lit/decorators.js`.
+ */
+export function createImportMap(modules, prefix) {
+    return { imports: Object.fromEntries(modules.flatMap(module => [[module.name,
+                `${prefix}${module.name}/${module.entry}`],
+            ...Object.entries(module.subpaths ?? {})
+                .map(([subpath, file]) => [`${module.name}/${subpath}`,
+                `${prefix}${module.name}/${file}`]),
+            [`${module.name}/`,
+                `${prefix}${module.name}/`]])) };
+}
+function findPackageRoot(name, from) {
+    let directory = path.resolve(from);
+    while (true) {
+        const candidate = path.join(directory, 'node_modules', name);
+        if (existsSync(path.join(candidate, 'package.json'))) {
+            return candidate;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return null;
+        }
+        directory = parent;
+    }
+}
+function readPackageJson(root) {
+    return JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+}
+function entryOf(json) {
+    const exports = json.exports;
+    const main = typeof exports === 'object'
+        && exports !== null
+        && '.' in exports
+        ? exports['.']
+        : exports;
+    const entry = pickCondition(main)
+        ?? json.module
+        ?? json.main
+        ?? 'index.js';
+    return entry.replace(/^\.\//, '');
+}
+/**
+ * The module of each subpath of `exports` other than `.`, by the subpath
+ * without its `./`; a pattern subpath, with `*`, is left out.
+ */
+function subpathsOf(json) {
+    const exports = json.exports;
+    if (typeof exports
+        !== 'object'
+        || exports === null) {
+        return {};
+    }
+    const found = {};
+    for (const [key, value] of Object.entries(exports)) {
+        const picked = pickCondition(value);
+        if (key.startsWith('./')
+            && !key.includes('*')
+            && picked !== null) {
+            found[key.slice(2)] =
+                picked.replace(/^\.\//, '');
+        }
+    }
+    return found;
+}
+function pickCondition(value) {
+    if (typeof value
+        === 'string') {
+        return value;
+    }
+    if (typeof value
+        !== 'object'
+        || value === null) {
+        return null;
+    }
+    const conditions = value;
+    for (const condition of CONDITIONS) {
+        if (condition in conditions) {
+            const picked = pickCondition(conditions[condition]);
+            if (picked) {
+                return picked;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The file of a module a request names, by the path after `MODULES_PREFIX`:
+ * `<name>/<file>` inside that module's folder, or `null` for an unknown module
+ * or a path that leaves its folder.
+ */
+export function findModuleFile(rest, modules) {
+    for (const module of modules) {
+        if (!rest.startsWith(`${module.name}/`)) {
+            continue;
+        }
+        const target = path.resolve(module.root, rest.slice(module.name.length + 1));
+        return target.startsWith(module.root + path.sep)
+            ? target
+            : null;
+    }
+    return null;
+}

package/dist/editor-app.d.ts

@@ -0,0 +1,232 @@
+import { type CommandIo, type Config } from 'asljs-cmdbase';
+import { type LoggerProvider } from 'asljs-logging';
+import { type BrowserModule } from './browser-modules.js';
+import { type RequestHandler } from './server.js';
+/**
+ * A project of an application: a folder and the configuration file that
+ * configures the application in it, e.g. `apps/kb/kb.json`.
+ */
+export interface Project {
+    /**
+     * The folder relative to the folder the projects were looked for in, with
+     * `/` separators; `.` for that folder itself.
+     */
+    id: string;
+    /**
+     * What the selector shows: the id, or the name of the folder for `.`.
+     */
+    title: string;
+    /**
+     * The folder, by absolute path.
+     */
+    folder: string;
+    /**
+     * The configuration file of the project.
+     */
+    config: Config;
+}
+/**
+ * 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 declare function findProjects(folder: string, name: string, files?: readonly string[], options?: {
+    required?: boolean;
+}): Promise<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 declare function findAppProjects(context: Pick<EditorAppContext, 'cwd' | 'files' | 'folders'>, name: string, options?: {
+    required?: boolean;
+}): Promise<Project[]>;
+/**
+ * A folder whose projects an application serves, and its files as `listFiles`
+ * gives them, when they are listed already.
+ */
+export interface WorkingFolder {
+    cwd: string;
+    files?: readonly string[];
+}
+/**
+ * What the `createApp` of an application server, e.g. `asljs-kb-srv`, makes
+ * its `EditorApp` with, whether it serves alone or in an aggregating server.
+ */
+export interface EditorAppContext {
+    /**
+     * The folder whose projects are served: `findProjects` of it.
+     */
+    cwd: string;
+    /**
+     * The path the application is served at, ending with `/`: `/` alone,
+     * `/<id>/` in an aggregating server.
+     */
+    base: string;
+    env: Readonly<Record<string, string | undefined>>;
+    loggerProvider: LoggerProvider;
+    /**
+     * The files of `cwd`, as `listFiles` gives them, which `findProjects` looks
+     * for the configuration file in: an aggregating server lists them once for
+     * every application. Listed by each application when absent.
+     */
+    files?: readonly string[];
+    /**
+     * The address the server listens on, when it is not a local one: the
+     * `host` of `createHandler`, which a `POST` must be sent to.
+     */
+    host?: string;
+    /**
+     * The folders whose projects are served, when an aggregating server serves
+     * several, `cwd` and `files` being those of the first: `findAppProjects`
+     * finds the projects of them all.
+     */
+    folders?: readonly WorkingFolder[];
+}
+/**
+ * What a project handler is made with.
+ */
+export interface ProjectContext {
+    /**
+     * The path the project is served at, ending with `/`, e.g. `/kb/p/docs/`;
+     * the prefix of every link the project's pages and its plugin make.
+     */
+    base: string;
+    /**
+     * Registers what `EditorApp.close` runs, such as stopping a background
+     * task the project started.
+     */
+    onClose: (action: () => Promise<void>) => void;
+}
+export interface EditorAppOptions {
+    /**
+     * The application's id, e.g. `kb`: the path it is mounted at in an
+     * aggregating server, and the prefix of its documents' ids.
+     */
+    id: string;
+    title: string;
+    /**
+     * The icon of the application as SVG, drawn in the text colour.
+     */
+    icon: string;
+    /**
+     * The path the application is served at, ending with `/`; `/` by default.
+     */
+    base?: string;
+    /**
+     * The projects, as `findProjects` gives them; the first is shown first.
+     */
+    projects: readonly Project[];
+    /**
+     * The handler of a project, made when it is first requested.
+     */
+    project: (project: Project, context: ProjectContext) => RequestHandler | Promise<RequestHandler>;
+    /**
+     * The plugin, by the path of its browser module, whose default export takes
+     * `{ id, base, project, model }` and returns the `EditorPlugin` of that
+     * project (see `asljs-ui-editor`). The plugin renders what the project's
+     * handler answers, which is data. The module's folder is served at
+     * `/_/plugin/`, its scripts and their source maps only, so that the module
+     * imports the modules beside it.
+     */
+    plugin: string;
+    /**
+     * The packages the plugin and the pages import, served under
+     * `MODULES_PREFIX`; see `findBrowserModules`.
+     */
+    modules: readonly BrowserModule[];
+    /**
+     * CSS of the plugin's panels and documents, added to the page.
+     */
+    style?: string;
+}
+/**
+ * What `/_/app.json` of an application says, with absolute paths.
+ */
+export interface EditorAppDescriptor {
+    id: string;
+    title: string;
+    icon: string;
+    /**
+     * The URL of the plugin module.
+     */
+    plugin: string;
+    projects: {
+        id: string;
+        title: string;
+        base: string;
+    }[];
+}
+/**
+ * An application served as an editor plugin: its handler and what an
+ * aggregating page needs of it.
+ */
+export interface EditorApp {
+    id: string;
+    title: string;
+    base: string;
+    style: string;
+    modules: readonly BrowserModule[];
+    /**
+     * Answers the requests of the application, relative to `base`:
+     *
+     * - `/` - the editor with the application as its only plugin;
+     * - `/_/app.json` - `{ id, title, icon, plugin, projects }`, each project
+     *   `{ id, title, base }`, with absolute paths;
+     * - `/_/plugin/...` - the plugin module and the modules beside it;
+     * - `/p/<project>/...` - the project, by its id, `~` for `.`;
+     * - `/modules/...` - the modules.
+     */
+    handler: RequestHandler;
+    /**
+     * Runs what the projects registered with `onClose`.
+     */
+    close: () => Promise<void>;
+}
+/**
+ * The segment of a project in its path: its id, `~` for `.`.
+ */
+export declare function projectSegment(id: string): string;
+/**
+ * An application served as an editor plugin; see `EditorApp`.
+ */
+export declare function createEditorApp(options: EditorAppOptions): EditorApp;
+/**
+ * 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 declare function combineEditorApps(title: string, apps: readonly EditorApp[]): RequestHandler;
+/**
+ * An editor page whose plugins are the applications of `apps`, the URLs of
+ * their `/_/app.json`; see `mountEditorApps` of `asljs-ui-editor`.
+ */
+export declare function editorPage(options: {
+    title: string;
+    apps: readonly string[];
+    modules: readonly BrowserModule[];
+    style?: string;
+}): string;
+/**
+ * Serves an editor application, as `<app>-srv` does: prints where it serves
+ * `cwd`, serves until SIGINT or SIGTERM, then closes the application.
+ */
+export declare function serveApp(app: EditorApp, options: {
+    io: CommandIo;
+    cwd: string;
+    port?: number;
+    host?: string;
+    loggerProvider: LoggerProvider;
+}): Promise<void>;