asljs-appbase 0.1.4 → 0.1.5

package/dist/editor-app.d.ts

@@ -32,8 +32,35 @@ export interface Project {
  * 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[]): Promise<Project[]>;
+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.
@@ -61,6 +88,12 @@ export interface EditorAppContext {
      * `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.

package/dist/editor-app.js

@@ -2,7 +2,7 @@ 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, serve, serverUrl, untilStopped, send } from './server.js';
+import { createHandler, mountHandlers, page, scriptJson, send, serve, serverUrl, untilStopped } from './server.js';
 /**
  * The path an application serves its plugin's folder at.
  */
@@ -14,8 +14,13 @@ const PLUGIN_PREFIX = '/_/plugin/';
  * 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) {
+export async function findProjects(folder, name, files, options = {}) {
     const root = path.resolve(folder);
     const listed = files
         ?? await listFiles(root);
@@ -30,7 +35,69 @@ export async function findProjects(folder, name, files) {
         return (await Promise.all(folders.map(found => toProject(root, found, name))))
             .sort((a, b) => a.id.localeCompare(b.id));
     }
-    return [await toProject(root, root, name)];
+    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)

package/dist/index.d.ts

@@ -1,8 +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, findProjects, projectSegment, serveApp, type EditorApp, type EditorAppContext, type EditorAppDescriptor, type EditorAppOptions, type Project, type ProjectContext } from './editor-app.js';
+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, mountHandlers, jsonReply, page, scriptJson, send, serve, serverUrl, startServer, untilStopped, versionConflict, type HandlerOptions, type JsonReply, type ListenOptions, type PostReply, type RequestHandler, type ServerOptions } from './server.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

@@ -1,8 +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, findProjects, projectSegment, serveApp } from './editor-app.js';
+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, mountHandlers, jsonReply, page, scriptJson, send, serve, serverUrl, startServer, untilStopped, versionConflict } from './server.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/docs/appbase.md

@@ -118,14 +118,21 @@ values; the only HTML it sends is `index`, a page that loads its data.
 An application served as a plugin of the editor of `asljs-ui-editor`, with a
 selector of its projects; one server can serve one application, or several.
 
-- `findProjects(folder, name, files?)` - the projects of an application by its
-  configuration file `name`, e.g. `kb.json`: `folder` itself when it has the
-  file; else every folder below it that has one, by id; else `folder` itself
-  with the nearest file of a parent, or none. It looks for the file in `files`,
-  the files of `folder` as `listFiles` gives them, so that a server of several
-  applications lists them once; it lists them itself without. A `Project` is `{
-  id, title, folder, config }`; `id` is the folder relative to `folder`, `.` for
-  itself.
+- `findProjects(folder, name, files?, { required? })` - the projects of an
+  application by its configuration file `name`, e.g. `kb.json`: `folder` itself
+  when it has the file; else every folder below it that has one, by id; else
+  `folder` itself with the nearest file of a parent, or none; with `required`,
+  none throws. It looks for the file in `files`, the files of `folder` as
+  `listFiles` gives them, so that a server of several applications lists them
+  once; it lists them itself without. A `Project` is `{ id, title, folder,
+  config }`; `id` is the folder relative to `folder`, `.` for itself.
+- `findAppProjects(context, name, { required? })` - the projects of an
+  application in the folders of an `EditorAppContext`: `findProjects` of its
+  `cwd` and `files`, or, with several `folders`, the projects of each, whose ids
+  start with the folder's name, such as `docs/notes`, the name alone for the
+  folder itself; a name two folders share gets `-2`, `-3` after the first. With
+  `required`, a folder without the file has no project, and it throws only when
+  no folder has one.
 - `createEditorApp({ id, title, icon, base?, projects, project, plugin, modules,
   style? })` - an `EditorApp`, whose `handler` answers, relative to `base`, `/`
   with the editor whose only plugin is the application, `/_/app.json` with an
@@ -140,11 +147,15 @@ selector of its projects; one server can serve one application, or several.
   prefix of the URLs its plugin reads, and `onClose` registers what `close()` of
   the application runs. `projectSegment(id)` is the segment of a project in a
   path.
-- `EditorAppContext` - `{ cwd, base, env, loggerProvider, files?, host? }`, what
-  the `createApp` of an application server makes its `EditorApp` with, alone or
-  in an aggregating server; `files`, the files of `cwd` an aggregating server
-  listed once, go to `findProjects`, and `host`, the address the server listens
-  on, to the `host` of each project's handler.
+- `EditorAppContext` - `{ cwd, base, env, loggerProvider, files?, host?,
+  folders? }`, what the `createApp` of an application server makes its
+  `EditorApp` with, alone or in an aggregating server; `files`, the files of
+  `cwd` an aggregating server listed once, go to `findProjects`, and `host`, the
+  address the server listens on, to the `host` of each project's handler.
+  `folders`, each a `WorkingFolder` `{ cwd, files? }`, are the folders of an
+  aggregating server that serves several, `cwd` and `files` being the first's;
+  `createApp` finds its projects with `findAppProjects`, in one folder or in
+  all.
 - `combineEditorApps(title, apps)` - a handler that mounts each application at
   `/<id>/`, the `base` it was made with, and answers `/` with the editor whose
   plugins are all of them and `/modules/...` with the modules of them all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-appbase",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "The base of the applications: configuration files and state folders, the entry point of an executable, markdown, the document server and editor applications.",
   "type": "module",
   "asljs": {
@@ -18,23 +18,33 @@
     "dist/**",
     "docs/**",
     "README.md",
-    "LICENSE.md"
+    "LICENSE.md",
+    "!dist/*.tsbuildinfo"
   ],
   "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",
+    "clean:build": "node ../../scripts/cleanBuildOutDir.js",
+    "clean:dist": "node ../../scripts/cleanDistOutDir.js",
+    "compile:build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "compile:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "build:dist": "node ../../scripts/buildDistDeps.js && npm run compile:dist",
     "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",
+    "prepack": "npm run clean:build && npm run clean:dist && npm run build:dist && npm run compile: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\"",
-    "coverage": "npm run build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "coverage": "npm run compile:build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"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"
+    "build": "npm run clean:build && npm run flint && npm run typecheck && npm run compile:build && npm run test"
   },
+  "distDependencies": [
+    "asljs-agents",
+    "asljs-cmdbase",
+    "asljs-locator",
+    "asljs-logging",
+    "asljs-tmpdir"
+  ],
   "keywords": [
     "markdown",
     "cli"