@pieceful/ravel-host-node 0.1.1 → 0.3.0

package/LICENSE

@@ -2,8 +2,20 @@ MIT License
 
 Copyright (c) 2026 James Taylor
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-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 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+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
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @pieceful/ravel-host-node
 
-The Node.js host for Ravel projects. It loads Markdown, JSON Ravel Maps, and
+The Node.js host for [Ravel](https://github.com/jostylr/ravel) projects. It loads Markdown, JSON Ravel Maps, and
 TOML project configuration; confines project filesystem access; and safely
 writes planned deliverables, manifests, provenance maps, cleanups, and backups.
 
@@ -13,6 +13,79 @@ completed program, or use the higher-level `@pieceful/ravel` CLI. Inputs and
 outputs are contained beneath an explicit project root; path escapes and
 symlink traversal are rejected.
 
+Editor hosts can evaluate unsaved project state by supplying absolute,
+normalized in-memory overlays. Imported inputs and configuration consult the
+overlay before disk:
+
+```js
+const loaded = await loadBuildInput("ravel.toml", {
+  overlays: new Map([
+    [absoluteMarkdownPath, { text: dirtyEditorText, version: 12 }],
+  ]),
+});
+```
+
+Loading overlays never writes source, deliverables, manifests, provenance
+sidecars, backups, or stale-output changes. Artifact writes remain separate,
+explicit host operations.
+
+`loadBuildInput` reports `loadedInputUris` for invalidation and separately
+reports `authoredSourceUris` plus `authoredSourceTexts`. The text record contains
+the exact overlay or disk text consumed for each authored non-JSON input, keyed
+relative to the project root. Editor hosts can use it to prove that a newly
+opened clean navigation destination still matches the evaluated snapshot; it
+does not supply an editor version or write permission. A source path merely
+asserted by JSON Ravel Map data is not added to the authored set, and a load
+containing JSON map provenance reports `sourceEditsAllowed: false` for the
+current conservative automatic-edit policy.
+
+Version-1 TOML projects may declare text `[[live.resources]]` and installed
+package exports in `[[live.modules]]`. The host validates and loads those
+declarations; provider-specific package preparation remains outside this
+general filesystem host.
+
+`.qmd` inputs are parsed through the modern Markdown adapter before any Quarto
+execution stage. Markdown entries in `ravel.toml` may select
+`profile = "modern"` or retain the compatibility profile with
+`profile = "fences"`.
+
+Historical projects select the independent LitPro adapter with
+`adapter = "markdown-litpro"` and may choose `dialect = "litpro-2017"`,
+`"pieceful-2020"`, or `"litpro-plus"`. Legacy `load:` directives retain the
+adapter and dialect while loading their declared input; parsing never performs
+other legacy effects.
+
+Noweb sources use `.nw` or `.noweb`, or may be selected explicitly with
+`adapter = "noweb"`. TOML accepts `dialect = "noweb"` or `"noweb-plus"`,
+`references = "noweb"`, `"underscore-quote"`, or `"both"`, and an optional
+`language`. `run = true` and `provider = "..."` retain live execution intent
+as chunk metadata; loading never executes a noweb chunk or writes tangled
+output.
+
+AsciiDoc sources use `.adoc`, `.asciidoc`, or `adapter = "asciidoc"`.
+Section and block pieces retain exact source bodies, pipelines, native
+cross-reference navigation, and `ravel::` graph directives. Loading does not
+invoke Asciidoctor or expand includes.
+
+HTML sources use `.html`, `.htm`, or `adapter = "html"`. Semantic sections and
+figures retain visible names, decoded code, native navigation, pipelines, and
+directive links. Loading uses authored source with scripting disabled; it
+never constructs a browser DOM or observes runtime mutations.
+
+Org sources use `.org` or `adapter = "org"`. TOML can select
+`references = "org-noweb"`, `"underscore-quote"`, or `"both"`, enable
+Ravel-only use-site pipes with `noweb_pipes = true`, and assign Babel
+authority with `execution_owner = "org"` or `"ravel"`. The host retains
+Babel header arguments, result artifacts, and tangle requests as data; loading
+does not invoke Emacs or Babel.
+
+MyST sources use `.myst.md` or `adapter = "myst"`. Labeled `{ravel:piece}`,
+`{code}`, `{code-block}`, and `{code-cell}` directives retain visible
+captions, anchors, exact bodies, cross-reference navigation, front matter, and
+notebook tags. TOML may assign cell authority with
+`execution_owner = "myst"` or `"ravel"`; loading invokes neither MyST nor
+Jupyter.
+
 Requires Node.js 22 or newer. This package is intentionally Node-specific;
 browser and Bun hosts should supply their own I/O boundary around
 `@pieceful/ravel-core`.

package/package.json

@@ -1,25 +1,51 @@
 {
   "name": "@pieceful/ravel-host-node",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Node host capabilities for Ravel.",
   "license": "MIT",
   "author": "James Taylor",
-  "repository": { "type": "git", "url": "git+https://github.com/jostylr/ravel.git", "directory": "packages/host-node" },
-  "bugs": { "url": "https://github.com/jostylr/ravel/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/host-node"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
   "homepage": "https://ravel.jostylr.com/",
-  "engines": { "node": ">=22" },
-  "keywords": ["ravel", "literate-programming", "node", "build"],
-  "publishConfig": { "access": "public" },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "literate-programming",
+    "node",
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": "./src/index.js"
   },
   "types": "./src/index.d.ts",
-  "files": ["src", "README.md", "LICENSE"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
-    "@pieceful/ravel-core": "0.1.1",
-    "@pieceful/ravel-markdown": "0.1.1",
-    "@pieceful/ravel-map": "0.1.1",
-    "smol-toml": "^1.7.0"
+    "@pieceful/ravel-asciidoc": "0.3.0",
+    "@pieceful/ravel-core": "0.3.0",
+    "@pieceful/ravel-html": "0.3.0",
+    "@pieceful/ravel-map": "0.3.0",
+    "@pieceful/ravel-markdown": "0.3.0",
+    "@pieceful/ravel-markdown-litpro": "0.3.0",
+    "@pieceful/ravel-myst": "0.3.0",
+    "@pieceful/ravel-noweb": "0.3.0",
+    "@pieceful/ravel-org": "0.3.0",
+    "@pieceful/ravel-transforms": "0.3.0",
+    "smol-toml": "^1.9.1"
   }
 }

package/src/index.d.ts

@@ -3,11 +3,45 @@ export interface SourceRange { start: SourcePosition; end: SourcePosition; }
 export interface SourceLocation { uri: string; range: SourceRange; }
 export interface Diagnostic { code: string; severity: "error" | "warning" | "info"; message: string; source: SourceLocation; }
 export interface RavelProgram { version?: number; deliverables: Record<string, { name: string; from: string; value: string; segments?: unknown[] }>; }
-export interface BuildInput { pretransform: unknown; outputDirectory?: string; rootDirectory: string; buildOptions?: { clean: boolean; backup: boolean | string }; }
+export interface LiveModuleDeclaration { specifier: string; from: string; source?: SourceLocation; }
+export interface LiveResourceDeclaration { name: string; path: string; source?: SourceLocation; }
+export interface LiveConfiguration { modules: LiveModuleDeclaration[]; resources: Record<string, string>; resourceDeclarations?: LiveResourceDeclaration[]; }
+export interface BuildInput {
+  pretransform: unknown;
+  outputDirectory?: string;
+  rootDirectory: string;
+  /** Relative source documents actually parsed through a source adapter. */
+  authoredSourceUris: string[];
+  /** Exact authored text consumed by source adapters for this evaluation. */
+  authoredSourceTexts: Record<string, string>;
+  /** Relative JSON/markup/config inputs whose overlays invalidate analysis. */
+  loadedInputUris: string[];
+  /** False when any supplied JSON map makes automatic edit provenance unverified. */
+  sourceEditsAllowed: boolean;
+  buildOptions?: { clean: boolean; backup: boolean | string };
+  live?: LiveConfiguration;
+}
+export interface SourceAdapterOptions {
+  document?: string;
+  mode?: "opt-in" | "primary";
+  profile?: "fences" | "modern" | "litpro";
+  adapter?: "asciidoc" | "html" | "markdown" | "markdown-litpro" | "myst" | "noweb" | "org";
+  dialect?: "litpro-2017" | "pieceful-2020" | "litpro-plus" | "noweb" | "noweb-plus";
+  references?: "noweb" | "org-noweb" | "underscore-quote" | "both";
+  language?: string;
+  nowebPipes?: boolean;
+  executionOwner?: "org" | "myst" | "ravel";
+  run?: boolean;
+  provider?: string;
+  overlays?: Map<string, string | { text: string; version?: number }> | Record<string, string | { text: string; version?: number }>;
+  /** Keep live resource declarations but do not read their contents. Intended for editor analysis. */
+  readLiveResources?: boolean;
+  signal?: AbortSignal;
+}
 export class RavelInputError extends Error { diagnostics: Diagnostic[]; }
-export function loadPretransformGraph(entryPath: string, options?: { document?: string; mode?: "opt-in" | "primary" }): Promise<unknown>;
-export function loadTomlBuild(configPath: string): Promise<BuildInput>;
-export function loadBuildInput(inputPath: string, options?: { document?: string; mode?: "opt-in" | "primary" }): Promise<BuildInput>;
+export function loadPretransformGraph(entryPath: string, options?: SourceAdapterOptions): Promise<unknown>;
+export function loadTomlBuild(configPath: string, options?: SourceAdapterOptions): Promise<BuildInput>;
+export function loadBuildInput(inputPath: string, options?: SourceAdapterOptions): Promise<BuildInput>;
 export function planDeliverables(program: RavelProgram, outputDirectory: string): { version: 1; outputDirectory: string; manifest: string; deliverables: Array<Record<string, unknown>> };
 export function planStaleDeliverables(program: RavelProgram, outputDirectory: string, options?: { rootDirectory?: string; staleSince?: string }): Promise<Array<Record<string, unknown>>>;
 export function writeDeliverables(program: RavelProgram, outputDirectory: string, options?: { rootDirectory?: string }): Promise<string[]>;