datanotes 3.2.0 → 3.3.1

package/README.md

@@ -15,6 +15,7 @@ Datanotes is the open-source database engine for Markdown: it runs a folder of n
 - **Agents can't write garbage.** Every write is checked against its table: types, links, unique values and CHECK constraints. A refused write changes nothing. Its answer says which value broke which rule and how to fix it.
 - **Every change can be undone.** The engine journals every write it makes. It records who made it: the agent, its session and its token. `undo_migration` takes any change back.
 - **It's still just Markdown.** A row is a note, and its front matter keys are the columns. Read it, edit it, grep it or commit it to Git. The engine reads your hand edits and checks them too.
+- **Extensions.** Install tables and MCP tools from a git repository, pinned and confirmed (`datanotes extension install`).
 - **Local first.** Datanotes is Apache-2.0 and runs on your machine. Nothing leaves it unless you turn that feature on.
 
 ## When not to use it

package/SECURITY.md

@@ -65,6 +65,18 @@ The owner creates a named token with `POST /datanotes/tokens/create/`, and the e
 
 A named token can’t create webhooks, manage tokens or read the engine’s status, and without `maintain` it can’t undo.
 
+### Extensions
+
+An extension adds tables and Model Context Protocol (MCP) tools from a git repository. Its code is trusted code that runs inside the MCP server's process, not in a sandbox. Install only extensions you trust, and read the plan first.
+
+- **Pinned code**: the installer takes a version tag or a full commit id, and refuses a branch. It fetches the tag itself, even when a branch has the same name. It records the commit and the SHA-256 hashes of the manifest and the entry file. The server refuses cached code that differs.
+- **No install scripts**: the installer runs no script, no build and no `npm install`. The entry file may import only Node built-ins. The installer reads the imports in the file. Code that builds a module name at run time escapes this check.
+- **One token for each extension**: `ext-<name>` writes only the tables the manifest lists. It cannot change the schema or undo. The installer changes the schema with the owner's token, after you confirm the plan.
+- **An invoker check**: before a tool that writes runs, the server checks the calling agent's token. That token must be able to write the tool's tables. A read-only client cannot write through an extension.
+- **The secret stays on one machine**: the token file sits under the data home with mode 0600. The registry in the engine's store holds no secret.
+
+Known limits: extension code is not isolated from the MCP server's process. Its token reads every table until read patterns ship. Migrations are declarative and run no code. [Install extensions](https://datanotes.dev/administration/extensions/) has the details.
+
 ### Who made each write
 
 The engine journals every write with its actor. The client sends the agent’s name, model and session, so they’re self-reported. The server sets the credential, `auth` (`owner`, or the named token’s name), and no client can claim another one.

package/dist/api/client.d.cts

@@ -82,6 +82,8 @@ export interface RecordedToolCall {
     takes_summary?: boolean;
 }
 export declare const fetchTransport: Transport;
+/** `s` without its trailing "/" characters. A loop, not `/\/+$/`: that regex is quadratic on a long run of "/" not at the end. */
+export declare function trimTrailingSlashes(s: string): string;
 export declare class DatanotesClient {
     private readonly o;
     readonly url: string;

package/dist/api/client.d.ts

@@ -82,6 +82,8 @@ export interface RecordedToolCall {
     takes_summary?: boolean;
 }
 export declare const fetchTransport: Transport;
+/** `s` without its trailing "/" characters. A loop, not `/\/+$/`: that regex is quadratic on a long run of "/" not at the end. */
+export declare function trimTrailingSlashes(s: string): string;
 export declare class DatanotesClient {
     private readonly o;
     readonly url: string;

package/dist/api/docs.d.cts

@@ -131,14 +131,24 @@ export interface DocsQuery {
  * word. Words that say nothing (`+the`) require nothing.
  */
 export declare function parseQuery(query: string): DocsQuery;
-/** The docs in a folder (null: there are none, and every call says how to get them). */
+/** A folder of extra pages shown under a prefix of the docs (an installed extension's `docs/`). */
+export interface DocsMount {
+    /** The path its pages appear under: "extensions/tasks". */
+    prefix: string;
+    /** The folder of .md pages. */
+    dir: string;
+}
+/** The docs in a folder (null: there are none, and every call says how to get them), and the mounts added to them. */
 export declare class DocsLibrary {
     readonly dir: string | null;
+    readonly mounts: readonly DocsMount[];
     private loaded;
+    /** The keys of the pages that come from mounts: the docs' version leaves them out. */
+    private readonly mounted;
     private index;
     private hash;
     private sectionList;
-    constructor(dir: string | null);
+    constructor(dir: string | null, mounts?: readonly DocsMount[]);
     private missing;
     private all;
     /** The pages, sorted by path; only those under `prefix` (`guides/`) when it is given. */
@@ -206,6 +216,6 @@ export declare class DocsLibrary {
 export declare const RRF_K = 60;
 /** How many sections of each ranking hybrid search fuses. */
 export declare const FUSION_DEPTH = 50;
-/** The docs of a folder (default: `findDocsDir()`), loaded once per folder. */
-export declare function openDocs(dir?: string | null): DocsLibrary;
+/** The docs of a folder (default: `findDocsDir()`) with its mounts, loaded once per folder and mounts. */
+export declare function openDocs(dir?: string | null, mounts?: readonly DocsMount[]): DocsLibrary;
 export {};

package/dist/api/docs.d.ts

@@ -131,14 +131,24 @@ export interface DocsQuery {
  * word. Words that say nothing (`+the`) require nothing.
  */
 export declare function parseQuery(query: string): DocsQuery;
-/** The docs in a folder (null: there are none, and every call says how to get them). */
+/** A folder of extra pages shown under a prefix of the docs (an installed extension's `docs/`). */
+export interface DocsMount {
+    /** The path its pages appear under: "extensions/tasks". */
+    prefix: string;
+    /** The folder of .md pages. */
+    dir: string;
+}
+/** The docs in a folder (null: there are none, and every call says how to get them), and the mounts added to them. */
 export declare class DocsLibrary {
     readonly dir: string | null;
+    readonly mounts: readonly DocsMount[];
     private loaded;
+    /** The keys of the pages that come from mounts: the docs' version leaves them out. */
+    private readonly mounted;
     private index;
     private hash;
     private sectionList;
-    constructor(dir: string | null);
+    constructor(dir: string | null, mounts?: readonly DocsMount[]);
     private missing;
     private all;
     /** The pages, sorted by path; only those under `prefix` (`guides/`) when it is given. */
@@ -206,6 +216,6 @@ export declare class DocsLibrary {
 export declare const RRF_K = 60;
 /** How many sections of each ranking hybrid search fuses. */
 export declare const FUSION_DEPTH = 50;
-/** The docs of a folder (default: `findDocsDir()`), loaded once per folder. */
-export declare function openDocs(dir?: string | null): DocsLibrary;
+/** The docs of a folder (default: `findDocsDir()`) with its mounts, loaded once per folder and mounts. */
+export declare function openDocs(dir?: string | null, mounts?: readonly DocsMount[]): DocsLibrary;
 export {};

package/dist/api/extension-files.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Where an extension's files live on this machine (<data home>/extensions): the immutable code of each
+ * installed commit and the secret of the extension's token. The installation record itself is in the
+ * engine's store. No Node types in the exported signatures: the package's consumer check compiles
+ * without them.
+ */
+export declare const EXTENSIONS_FOLDER = "extensions";
+/** <data home>/extensions. */
+export declare function extensionsHome(env?: Record<string, string | undefined>): string;
+/** The folder holding an immutable copy of an extension's published files at one commit. */
+export declare function codeDir(home: string, name: string, commit: string): string;
+/** The file holding an extension's token for one database. */
+export declare function tokenPath(home: string, databaseId: string, name: string): string;
+/** SHA-256 of the raw bytes, hex. */
+export declare function sha256Hex(data: string | Uint8Array): string;
+/** SHA-256 of a file's bytes, hex. */
+export declare function fileSha256(file: string): string;
+/** Write a token file (the token and a newline, mode 0600), creating its folders. */
+export declare function writeTokenFile(file: string, token: string): void;
+/** The token in a file, trimmed; null when the file is missing or empty. */
+export declare function readTokenFile(file: string): string | null;
+/** Delete a token file; a missing one is fine. */
+export declare function removeTokenFile(file: string): void;

package/dist/api/extension-files.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where an extension's files live on this machine (<data home>/extensions): the immutable code of each
+ * installed commit and the secret of the extension's token. The installation record itself is in the
+ * engine's store. No Node types in the exported signatures: the package's consumer check compiles
+ * without them.
+ */
+export declare const EXTENSIONS_FOLDER = "extensions";
+/** <data home>/extensions. */
+export declare function extensionsHome(env?: Record<string, string | undefined>): string;
+/** The folder holding an immutable copy of an extension's published files at one commit. */
+export declare function codeDir(home: string, name: string, commit: string): string;
+/** The file holding an extension's token for one database. */
+export declare function tokenPath(home: string, databaseId: string, name: string): string;
+/** SHA-256 of the raw bytes, hex. */
+export declare function sha256Hex(data: string | Uint8Array): string;
+/** SHA-256 of a file's bytes, hex. */
+export declare function fileSha256(file: string): string;
+/** Write a token file (the token and a newline, mode 0600), creating its folders. */
+export declare function writeTokenFile(file: string, token: string): void;
+/** The token in a file, trimmed; null when the file is missing or empty. */
+export declare function readTokenFile(file: string): string | null;
+/** Delete a token file; a missing one is fine. */
+export declare function removeTokenFile(file: string): void;

package/dist/api/extension-host.d.cts

@@ -0,0 +1,108 @@
+/**
+ * What an MCP server needs to offer the extensions installed in a database: read the registry,
+ * verify and load each extension's code, build the context its tool handlers get (the extension's
+ * own token, never the agent's), check arguments and the client's write permission, and answer
+ * refusals with offline docs lines (3.0.9 of the extensions plan). `datanotes mcp` and DatanotesOS
+ * both use it through `datanotes/extensions`. The engine never runs extension code.
+ */
+import { type Transport } from "./client.cjs";
+import { type DocsLibrary, type DocsMount } from "./docs.cjs";
+import { type ExtensionManifest } from "./extension-manifest.cjs";
+import { type InstalledExtension } from "./extension-record.cjs";
+import { type ExtensionActor } from "./extension-sdk.cjs";
+/** The log of the MCP server: a constant body, the variable parts as attributes. */
+export type HostLog = (level: "DEBUG" | "INFO" | "WARN" | "ERROR", body: string, attributes?: Record<string, string | number | boolean>) => void;
+export interface LoadOptions {
+    engineUrl: string;
+    /** Any token the engine accepts: reads the registry, the engine's version and time zone. */
+    token: string;
+    env?: Record<string, string | undefined>;
+    transport?: Transport;
+    /** Tool names the server already offers. */
+    reserved?: readonly string[];
+    /** Only the read-only tools (datanotes mcp --profile read). */
+    readOnlyOnly?: boolean;
+    log?: HostLog;
+}
+/** A tool as MCP lists it. */
+export interface ExtensionToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: Record<string, unknown>;
+    _meta: {
+        "datanotes/extension": string;
+        "datanotes/tables": string[];
+    };
+}
+/** Who calls a tool: the agent as the MCP server knows it, and the token its client connected with. */
+export interface ExtensionCaller {
+    actor: ExtensionActor;
+    clientToken: string;
+}
+export interface LoadedExtension {
+    readonly name: string;
+    readonly version: string;
+    /** "ext-<name>": the token's name, and the `served_by` of its tool calls. */
+    readonly servedBy: string;
+    readonly tools: ExtensionToolDefinition[];
+    readonly instructions: string;
+    /** Whether this server offers the tool: with readOnlyOnly, only the read-only ones. */
+    has(tool: string): boolean;
+    call(tool: string, args: Record<string, unknown>, caller: ExtensionCaller): Promise<{
+        ok: boolean;
+        value: unknown;
+    }>;
+}
+export type SkipCode = "api" | "code_missing" | "code_changed" | "engine" | "token_missing" | "tool_taken" | "entry" | "handler";
+export interface SkippedExtension {
+    name: string;
+    version: string;
+    code: SkipCode;
+    reason: string;
+}
+export interface ExtensionLoad {
+    databaseId: string | null;
+    loaded: LoadedExtension[];
+    skipped: SkippedExtension[];
+    docsMounts: DocsMount[];
+}
+/** Does a qualified table name match a write pattern? (The rule of the engine's named tokens.) */
+export declare function tableAllowed(full: string, patterns: readonly string[]): boolean;
+/**
+ * The actor recorded for an engine call of an extension: the agent's, the tool it called, and the
+ * client's token name in the harness ("claude-code via phone").
+ */
+export declare function engineActor(actor: ExtensionActor, tool: string, clientName: string | null): ExtensionActor & {
+    tool: string;
+};
+/** Where an extension was installed from, as the commands print it: the git URL with its ref, or the folder. */
+export declare function sourceLabel(r: InstalledExtension): string;
+/**
+ * The file URL to import an extension's entry from. `pathToFileURL` writes `~` as `%7E`; Node decodes it,
+ * but other loaders (vite, under vitest) do not, and a Windows 8.3 short path (`C:\Users\RUNNER~1\...`)
+ * then fails to load. `~` is unreserved in a URL, so the literal form names the same file.
+ */
+export declare function entryUrl(file: string): string;
+/** The problems of an entry file's default export against the manifest (empty: it fits). */
+export declare function validateModule(mod: unknown, manifest: ExtensionManifest): string[];
+/** The docs library of the package with the extensions' pages mounted under `extensions/<name>/`. */
+export declare function extensionDocs(mounts: readonly DocsMount[], dir?: string | null): DocsLibrary;
+/** What the engine knows of a client's token: its name and the tables it may write ("all": the owner). */
+export interface ClientToken {
+    name: string;
+    write: readonly string[] | "all";
+}
+/** Asks the engine who a client's token is, and remembers the answer for a while. */
+export declare class ClientTokens {
+    private readonly engineUrl;
+    private readonly transport?;
+    private readonly ttlMs;
+    private readonly clock;
+    private readonly cache;
+    constructor(engineUrl: string, transport?: Transport | undefined, ttlMs?: number, clock?: () => number);
+    /** The token's name and write patterns; null when the engine refuses the token. */
+    describe(token: string): Promise<ClientToken | null>;
+}
+/** Load the extensions installed in the database the engine serves; one that cannot be loaded is skipped with its reason. */
+export declare function loadExtensions(o: LoadOptions): Promise<ExtensionLoad>;

package/dist/api/extension-host.d.ts

@@ -0,0 +1,108 @@
+/**
+ * What an MCP server needs to offer the extensions installed in a database: read the registry,
+ * verify and load each extension's code, build the context its tool handlers get (the extension's
+ * own token, never the agent's), check arguments and the client's write permission, and answer
+ * refusals with offline docs lines (3.0.9 of the extensions plan). `datanotes mcp` and DatanotesOS
+ * both use it through `datanotes/extensions`. The engine never runs extension code.
+ */
+import { type Transport } from "./client.js";
+import { type DocsLibrary, type DocsMount } from "./docs.js";
+import { type ExtensionManifest } from "./extension-manifest.js";
+import { type InstalledExtension } from "./extension-record.js";
+import { type ExtensionActor } from "./extension-sdk.js";
+/** The log of the MCP server: a constant body, the variable parts as attributes. */
+export type HostLog = (level: "DEBUG" | "INFO" | "WARN" | "ERROR", body: string, attributes?: Record<string, string | number | boolean>) => void;
+export interface LoadOptions {
+    engineUrl: string;
+    /** Any token the engine accepts: reads the registry, the engine's version and time zone. */
+    token: string;
+    env?: Record<string, string | undefined>;
+    transport?: Transport;
+    /** Tool names the server already offers. */
+    reserved?: readonly string[];
+    /** Only the read-only tools (datanotes mcp --profile read). */
+    readOnlyOnly?: boolean;
+    log?: HostLog;
+}
+/** A tool as MCP lists it. */
+export interface ExtensionToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: Record<string, unknown>;
+    _meta: {
+        "datanotes/extension": string;
+        "datanotes/tables": string[];
+    };
+}
+/** Who calls a tool: the agent as the MCP server knows it, and the token its client connected with. */
+export interface ExtensionCaller {
+    actor: ExtensionActor;
+    clientToken: string;
+}
+export interface LoadedExtension {
+    readonly name: string;
+    readonly version: string;
+    /** "ext-<name>": the token's name, and the `served_by` of its tool calls. */
+    readonly servedBy: string;
+    readonly tools: ExtensionToolDefinition[];
+    readonly instructions: string;
+    /** Whether this server offers the tool: with readOnlyOnly, only the read-only ones. */
+    has(tool: string): boolean;
+    call(tool: string, args: Record<string, unknown>, caller: ExtensionCaller): Promise<{
+        ok: boolean;
+        value: unknown;
+    }>;
+}
+export type SkipCode = "api" | "code_missing" | "code_changed" | "engine" | "token_missing" | "tool_taken" | "entry" | "handler";
+export interface SkippedExtension {
+    name: string;
+    version: string;
+    code: SkipCode;
+    reason: string;
+}
+export interface ExtensionLoad {
+    databaseId: string | null;
+    loaded: LoadedExtension[];
+    skipped: SkippedExtension[];
+    docsMounts: DocsMount[];
+}
+/** Does a qualified table name match a write pattern? (The rule of the engine's named tokens.) */
+export declare function tableAllowed(full: string, patterns: readonly string[]): boolean;
+/**
+ * The actor recorded for an engine call of an extension: the agent's, the tool it called, and the
+ * client's token name in the harness ("claude-code via phone").
+ */
+export declare function engineActor(actor: ExtensionActor, tool: string, clientName: string | null): ExtensionActor & {
+    tool: string;
+};
+/** Where an extension was installed from, as the commands print it: the git URL with its ref, or the folder. */
+export declare function sourceLabel(r: InstalledExtension): string;
+/**
+ * The file URL to import an extension's entry from. `pathToFileURL` writes `~` as `%7E`; Node decodes it,
+ * but other loaders (vite, under vitest) do not, and a Windows 8.3 short path (`C:\Users\RUNNER~1\...`)
+ * then fails to load. `~` is unreserved in a URL, so the literal form names the same file.
+ */
+export declare function entryUrl(file: string): string;
+/** The problems of an entry file's default export against the manifest (empty: it fits). */
+export declare function validateModule(mod: unknown, manifest: ExtensionManifest): string[];
+/** The docs library of the package with the extensions' pages mounted under `extensions/<name>/`. */
+export declare function extensionDocs(mounts: readonly DocsMount[], dir?: string | null): DocsLibrary;
+/** What the engine knows of a client's token: its name and the tables it may write ("all": the owner). */
+export interface ClientToken {
+    name: string;
+    write: readonly string[] | "all";
+}
+/** Asks the engine who a client's token is, and remembers the answer for a while. */
+export declare class ClientTokens {
+    private readonly engineUrl;
+    private readonly transport?;
+    private readonly ttlMs;
+    private readonly clock;
+    private readonly cache;
+    constructor(engineUrl: string, transport?: Transport | undefined, ttlMs?: number, clock?: () => number);
+    /** The token's name and write patterns; null when the engine refuses the token. */
+    describe(token: string): Promise<ClientToken | null>;
+}
+/** Load the extensions installed in the database the engine serves; one that cannot be loaded is skipped with its reason. */
+export declare function loadExtensions(o: LoadOptions): Promise<ExtensionLoad>;

package/dist/api/extension-manifest.d.cts

@@ -0,0 +1,154 @@
+/**
+ * The manifest of a Datanotes extension (`datanotes-extension.json`, format version 1): parsing, validation
+ * with errors that teach (every problem at once, each as `<path>: <text>`), version comparison and the
+ * binding of table roles to real tables. The installer reads only this file before the user confirms, so
+ * everything an extension can do is declared here. No dependency but ./guidance.js.
+ */
+/** The manifest's file name at the root of the extension's repository. */
+export declare const MANIFEST_FILE = "datanotes-extension.json";
+/** Docs pages and headings that the errors of extensions point to (the pages are in docs/). */
+export declare const EXT_DOCS: {
+    readonly install: "https://datanotes.dev/administration/extensions.md#install-an-extension";
+    readonly tables: "https://datanotes.dev/administration/extensions.md#choose-the-tables-an-extension-uses";
+    readonly permissions: "https://datanotes.dev/administration/extensions.md#what-an-extension-can-do";
+    readonly update: "https://datanotes.dev/administration/extensions.md#update-an-extension";
+    readonly rollback: "https://datanotes.dev/administration/extensions.md#undo-an-install-or-an-update";
+    readonly remove: "https://datanotes.dev/administration/extensions.md#remove-an-extension";
+    readonly skipped: "https://datanotes.dev/administration/extensions.md#when-the-mcp-server-skips-an-extension";
+    readonly where: "https://datanotes.dev/administration/extensions.md#where-extensions-live";
+    readonly layout: "https://datanotes.dev/develop/write-an-extension.md#lay-out-the-repository";
+    readonly manifest: "https://datanotes.dev/develop/write-an-extension.md#write-the-manifest";
+    readonly declare: "https://datanotes.dev/develop/write-an-extension.md#declare-the-tables";
+    readonly tools: "https://datanotes.dev/develop/write-an-extension.md#write-the-tools";
+    readonly migrations: "https://datanotes.dev/develop/write-an-extension.md#migrate-the-schema-between-versions";
+    readonly publish: "https://datanotes.dev/develop/write-an-extension.md#check-and-publish-an-extension";
+};
+/** An extension's name (its token is `ext-<name>`). */
+export declare const EXTENSION_NAME: RegExp;
+/** A role, a table, a schema, a column, a base. */
+export declare const IDENT: RegExp;
+/** A tool's name. */
+export declare const TOOL_NAME: RegExp;
+/** The column types of the engine (a test checks the list against src/core). */
+export declare const COLUMN_TYPES: readonly string[];
+/** The attributes of a column spec in the engine (src/core/table-loader.ts; a test checks the list). */
+export declare const COLUMN_ATTRS: readonly string[];
+/** The operations a batch takes (src/server/rest.ts; a test checks the list). */
+export declare const BATCH_OPERATIONS: readonly string[];
+/** The operations that write rows. */
+export declare const DATA_OPERATIONS: readonly string[];
+/** An extension's own error: what is wrong, how to fix it, where to read more. */
+export declare class ExtensionError extends Error {
+    readonly hint: string;
+    readonly docs: string;
+    readonly code: string;
+    readonly name: string;
+    constructor(message: string, hint: string, docs: string, code?: string);
+}
+/** A manifest that is not valid: every problem, in the order of the walk. */
+export declare class ExtensionManifestError extends ExtensionError {
+    readonly problems: string[];
+    readonly name = "ExtensionManifestError";
+    constructor(problems: string[], file?: string);
+}
+/** Whether a table the extension depends on must have the column. */
+export type ColumnNeed = "required" | "optional";
+/** A column spec as the engine's operations take it, plus `need`. */
+export interface ManifestColumn {
+    name: string;
+    type: string;
+    description: string;
+    need: ColumnNeed;
+    [attribute: string]: unknown;
+}
+export interface ManifestConstraint {
+    name: string;
+    check: Record<string, unknown>;
+    hint: string;
+}
+export interface ManifestTable {
+    owned: boolean;
+    /** The table's name when created; the role when missing. */
+    name?: string;
+    schema?: string;
+    names?: string[];
+    description: string;
+    aliases?: string[];
+    filename?: string;
+    columns: ManifestColumn[];
+    constraints?: ManifestConstraint[];
+    instructions?: string;
+    bases?: string[];
+}
+export interface ManifestBase {
+    description: string;
+    columns: ManifestColumn[];
+}
+export interface ManifestView {
+    description: string;
+    query: Record<string, unknown>;
+    aliases?: string[];
+    labels?: Record<string, unknown>;
+}
+export interface ManifestTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: Record<string, unknown>;
+    /** Roles the tool reads or writes. */
+    tables: string[];
+    /** Roles the tool writes. */
+    writes: string[];
+}
+export interface ManifestMigration {
+    version: string;
+    description: string;
+    operations: ({
+        op: string;
+    } & Record<string, unknown>)[];
+}
+export interface ExtensionManifest {
+    manifest_version: 1;
+    name: string;
+    version: string;
+    description: string;
+    datanotes: string;
+    api: 1;
+    entry: string;
+    default_schema: string;
+    instructions?: string;
+    tables: Record<string, ManifestTable>;
+    /** The keys of `tables`, in order. */
+    roles: string[];
+    bases: Record<string, ManifestBase>;
+    views: Record<string, ManifestView>;
+    permissions: {
+        write: string[];
+    };
+    tools: ManifestTool[];
+    migrations: ManifestMigration[];
+}
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+/** MAJOR.MINOR.PATCH[-pre] (no leading `v`); null when it is not a version. */
+export declare function parseVersion(v: string): SemVer | null;
+/** Negative when a is older than b, 0 when equal, positive when newer. Throws for text that is not a version. */
+export declare function compareVersions(a: string, b: string): number;
+/** Whether an engine version meets a manifest's `">=X.Y.Z"`. A source run ("dev", "") meets every range. */
+export declare function satisfiesEngine(range: string, engineVersion: string): boolean;
+/** A string that is exactly a role: `@task`. */
+export declare const ROLE_REF: RegExp;
+/** A role inside a text: `@{task}`. */
+export declare const ROLE_TEXT: RegExp;
+/** A deep copy of `value` with every `@role` string and every `@{role}` in a string replaced by the role's table. Keys stay. */
+export declare function bindRoles<T>(value: T, tables: Readonly<Record<string, string>>): T;
+/** The roles a value names, in order of first appearance (both forms). */
+export declare function rolesNamed(value: unknown): string[];
+/** Read a manifest's text (a leading BOM is fine) and validate it. */
+export declare function parseManifest(text: string, file?: string): ExtensionManifest;
+/** Check a parsed manifest, collecting every problem; returns the typed manifest (a deep copy) or throws ExtensionManifestError. */
+export declare function validateManifest(raw: unknown, file?: string): ExtensionManifest;