asljs-appbase 0.0.0-stage → 0.1.5

package/docs/appbase.md

@@ -0,0 +1,193 @@
+# appbase
+
+The exports of `asljs-appbase`, by module.
+
+## Logging
+
+The functions that run something take an optional `Logger` of `asljs-logging`
+from their caller, and log nothing without one: they never create a provider.
+What they log is listed with each of them.
+
+Asking an AI agent and running commands are in `asljs-agents`, and the MCP
+server core in `asljs-mcp`.
+
+## Markdown
+
+- `parseMarkdown(text)` - the mdast tree.
+- `findSectionHeading(root, name)`, `getSection(root, name)` - a level 2
+  section: its heading, or its nodes up to the next level 1 or 2 heading.
+- `plainText(node)` - the text of a node.
+- `splitLocalUrl(url)` - a local link target split into a decoded path and its
+  `#` fragment; `null` for a URL with a scheme.
+- `formatUrl(url)` - a link target in angle brackets when it has spaces or
+  parentheses.
+
+## Files
+
+- `findMarkdownFiles(folder, { skip })` - the `.md` files of a folder and its
+  subfolders, any case of the extension, by absolute path, sorted, as the
+  `LocationResolver` of `asljs-locator` finds them, skipping folders whose name
+  starts with `.`, `node_modules`, and the `skip` names.
+- `listFiles(folder)` - 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, `.git` and `node_modules` are left
+  out.
+- `toDisplayPath(folder, file)` - a path relative to `folder` with `/`
+  separators.
+
+## Post-processing
+
+- `writeMarkdown(file, text)` - writes a markdown file and remembers it.
+- `takeWritten()` - the files written since the last call, and forgets them.
+- `findConfig(folder, name)` - the nearest configuration file `name`, e.g.
+  `rq.json`, of `folder` or a parent; an error when it is not valid JSON or its
+  `markdownPostProcessing` is not a string.
+- `postProcess(io, files, name)` - runs the `markdownPostProcessing` command of
+  the nearest `name` with the files that still exist, relative to the
+  configuration file's folder, where it runs. Returns 1 and writes the output to
+  `io.stderr` when the command fails, 0 otherwise. The command line and its exit
+  code go to `io.logger` at `debug`.
+
+## Configuration and executables
+
+The configuration readers, `loadConfig` and the `config*` functions, and the
+entry point of an executable, `runMain`, `commandLine` and the helpers beside
+them, are in [asljs-cmdbase][CMB], and this package re-exports them. The rules
+of the configuration file are in [Configuration][CFG] at the repository root.
+`findConfig` is `loadConfig` with the check of `markdownPostProcessing`.
+
+## State folder
+
+- `stateFolder(folder, app, config, given?)` - where application `app` keeps
+  what it stores between runs for the project in `folder`: `given`, a command
+  line's `{ option, variable, env, cwd }`, the option, else the variable, e.g.
+  `KB_STATE_DIR`, both against `cwd`; else `stateDir` of `config`, against the
+  folder of the file; else `.<app>` in `folder`, e.g. `.kb`. A service passes no
+  `given`: its projects are configured by their own files.
+
+## Server
+
+A server sends data, never a rendering of it: rendering is the page's, e.g. the
+plugin of an editor application. It serves a markdown file as its text, and JSON
+values; the only HTML it sends is `index`, a page that loads its data.
+
+- `startServer({ folder, index?, json?, port?, host?, post?, allow?, modules?,
+  logger? })` - serves `/` with `index()`, made again on every request, and not
+  found without it; a path of `json` with its value; and any file of `folder` as
+  it is, a `.md` file as `text/markdown`. Nothing outside `folder`, or that
+  `allow(relative)` refuses, is served. The files of each of `modules` are
+  served under `MODULES_PREFIX`, `/modules/<name>/<file>`, and nothing outside
+  their folders. It listens on `host`, `127.0.0.1` by default, on `port`, or
+  without one on the first free port from `DEFAULT_PORT`, 3000, up to 3099.
+  `logger` is told that it listens, with its URL, at `information`, each request
+  at `trace`, and a request that failed at `error`. A `POST` is answered by
+  `post(url, body)` with the parsed JSON body; it returns a `PostReply`, `{
+  status, body }`, sent back as JSON. Without `post` a `POST` is not found. Only
+  a `POST` with `Content-Type: application/json`, sent to a local name
+  (`localhost`, `127.0.0.1`, `[::1]` or `host`) and, when it has an `Origin`,
+  from the server's own pages is answered; any other gets 403, a body that is
+  not JSON 400, and one over 10 MB 413.
+- `json` of `startServer`, by path, gives values sent as JSON, e.g.
+  `/_/data.json`, made from the request URL with its query; a value made with
+  `jsonReply(status, body)` is sent with that status, e.g. 422. `methods`, e.g.
+  `[ 'GET', 'HEAD' ]`, refuses any other method with 405, and `moduleTypes`,
+  e.g. `[ '.js', '.mjs', '.map' ]`, limits the module files served by their
+  extensions.
+- `createHandler(options)` - the `RequestHandler` of `startServer` without
+  listening: `(request, response, url)`, whose `url` path is relative to where
+  it is mounted. `serve(handler, { port?, host?, logger? })` listens with any
+  handler, as `startServer` does; `send(response, status, type, body)` answers.
+- `mountHandlers(mounts, fallback?)` - passes a request for `/<name>/...` to
+  `mounts[name]` with the path relative to it, redirects `/<name>` to
+  `/<name>/`, and passes any other request to `fallback`, or answers 404.
+- `untilStopped(server, signals?)` - resolves once the server has closed; the
+  first of `signals`, `SIGINT` and `SIGTERM` by default, closes it and its open
+  connections. A command that serves awaits it, so that it releases what the
+  server used, such as its logger provider, only after the server.
+- `serverUrl(server)` - its address, e.g. `http://127.0.0.1:3000/`, an IPv6
+  address in brackets.
+- `page(title, body, style?)` - an HTML page with the shared style and `style`,
+  e.g. the editor page, or a page printed to PDF.
+- `scriptJson(value)` - JSON that is safe inside a `<script>` element.
+- `versionConflict()` - the 409 reply to a save of a document that changed since
+  its editor read it.
+- `escapeHtml(text)` - the text with `&`, `<`, `>` and `"` escaped.
+
+## Editor applications
+
+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?, { 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
+  `EditorAppDescriptor` - `{ id, title, icon, plugin, projects }`, each project
+  `{ id, title, base }` - `/_/plugin/...` with the folder of `plugin`, the path
+  of the plugin's browser module, its scripts and source maps only, so that it
+  imports the modules beside it, `plugin` being `/_/plugin/<file>` in the
+  descriptor; `/modules/...` with the modules, and `/p/<project>/...` with the
+  handler of that project, `~` naming `.`. `project(project, { base, onClose })`
+  makes that handler when the project is first requested; it answers data, which
+  the plugin renders. `base` is where it is served, e.g. `/kb/p/docs/`, the
+  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?,
+  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.
+- `editorPage({ title, apps, modules, style? })` - the editor page: the import
+  map of `modules`, an `asljs-editor` and `mountEditorApps` of the applications
+  whose `/_/app.json` URLs are `apps`, and `style`; the editor adds its own
+  style, `EDITOR_STYLE` of `asljs-ui-editor`, when it mounts.
+- `serveApp(app, { io, cwd, port?, host?, loggerProvider })` - serves an
+  `EditorApp`, prints `Serving <cwd> at <url>`, waits until SIGINT or SIGTERM,
+  and closes the application.
+
+## Browser modules
+
+A page served by `startServer` can import installed packages, such as
+`asljs-ui-diagram`, without a bundler.
+
+- `findBrowserModules(name, from)` - the package `name`, or each package of an
+  array of names, looked up from the folder `from`, and every package it depends
+  on at runtime, each a `BrowserModule`: its `name`, its folder `root`, and its
+  ES module `entry`, picked from the `browser`, `import`, `module` and `default`
+  conditions of `exports`, else `module`, else `main`, else `index.js`, and its
+  `subpaths`, the module of each other subpath of `exports`, e.g. `wiki` of
+  `asljs-kb/wiki`, a pattern with `*` left out. It throws for a package it
+  cannot find.
+- `createImportMap(modules, prefix)` - the import map that points each name at
+  `<prefix><name>/<entry>`, each `<name>/<subpath>` at its module, and `<name>/`
+  at `<prefix><name>/`, for a module that imports a file of a package, as lit
+  imports `lit/decorators.js`. Pass it to `startServer` as `modules` and put the
+  map, with `MODULES_PREFIX`, in a `<script type="importmap">` of the page.
+- `findModuleFile(rest, modules)` - the file of a module that a path after
+  `MODULES_PREFIX` names, or `null` for an unknown module or a path that leaves
+  its folder.
+
+[CFG]: ../../../docs/Configuration.md
+[CMB]: ../../cmdbase/docs/cmdbase.md

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "asljs-appbase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "type": "lib"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "docs/**",
+    "README.md",
+    "LICENSE.md",
+    "!dist/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "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: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 compile:build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "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"
+  ],
+  "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-agents": "^0.1.0",
+    "asljs-cmdbase": "^0.1.0",
+    "asljs-locator": "^0.1.0",
+    "asljs-logging": "^0.1.2",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "asljs-tmpdir": "^0.1.13",
+    "asljs-toolkit": "^0.1.0"
+  }
+}