@mdsnai/sdk 0.1.0

package/dist/core/model/block.d.ts

@@ -0,0 +1,30 @@
+import type { InputDefinition } from "./input";
+export interface ReadDefinition {
+    id: string;
+    block: string;
+    name: string;
+    target: string;
+    inputs: string[];
+    order: number;
+}
+export interface WriteDefinition {
+    id: string;
+    block: string;
+    name: string;
+    target: string;
+    inputs: string[];
+    order: number;
+}
+export interface RedirectDefinition {
+    id: string;
+    block: string;
+    target: string;
+    order: number;
+}
+export interface BlockDefinition {
+    name: string;
+    inputs: InputDefinition[];
+    reads: ReadDefinition[];
+    writes: WriteDefinition[];
+    redirects: RedirectDefinition[];
+}

package/dist/core/model/block.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/model/document.d.ts

@@ -0,0 +1,13 @@
+import type { BlockDefinition } from "./block";
+import type { SchemaDefinition } from "./schema";
+export type FrontmatterData = Record<string, unknown>;
+export interface BlockAnchorDefinition {
+    name: string;
+}
+export interface DocumentDefinition {
+    frontmatter: FrontmatterData;
+    markdown: string;
+    schemas: SchemaDefinition[];
+    blocks: BlockDefinition[];
+    blockAnchors: BlockAnchorDefinition[];
+}

package/dist/core/model/document.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/model/fragment.d.ts

@@ -0,0 +1,4 @@
+export interface MarkdownFragmentDefinition {
+    markdown: string;
+    hasExecutableMdsn: boolean;
+}

package/dist/core/model/fragment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/model/index.d.ts

@@ -0,0 +1,5 @@
+export type { BlockAnchorDefinition, DocumentDefinition, FrontmatterData, } from "./document";
+export type { BlockDefinition, ReadDefinition, RedirectDefinition, WriteDefinition, } from "./block";
+export type { InputDefinition, InputType, } from "./input";
+export type { SchemaDefinition } from "./schema";
+export type { MarkdownFragmentDefinition } from "./fragment";

package/dist/core/model/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/model/input.d.ts

@@ -0,0 +1,11 @@
+export type InputType = "text" | "number" | "boolean" | "choice" | "file" | "json";
+export interface InputDefinition {
+    id: string;
+    block: string;
+    name: string;
+    type: InputType;
+    required: boolean;
+    secret: boolean;
+    options?: string[];
+    schema?: string;
+}

package/dist/core/model/input.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/model/schema.d.ts

@@ -0,0 +1,4 @@
+export interface SchemaDefinition {
+    name: string;
+    shape: Record<string, unknown>;
+}

package/dist/core/model/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/protocol/mdsn.d.ts

@@ -0,0 +1,6 @@
+import type { BlockDefinition } from "../model/block";
+import type { SchemaDefinition } from "../model/schema";
+export declare function parseMdsnBlocks(blocks: string[]): {
+    schemas: SchemaDefinition[];
+    blocks: BlockDefinition[];
+};

package/dist/core/protocol/mdsn.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMdsnBlocks = parseMdsnBlocks;
+const statements_1 = require("./statements");
+function createBlock(name) {
+    return {
+        name,
+        inputs: [],
+        reads: [],
+        writes: [],
+        redirects: [],
+    };
+}
+function parseMdsnBlocks(blocks) {
+    const schemas = [];
+    const documentBlocks = [];
+    let currentBlock = null;
+    for (const blockText of blocks) {
+        const lines = blockText.split(/\r?\n/);
+        let index = 0;
+        while (index < lines.length) {
+            const line = lines[index].trim();
+            if (!line) {
+                index += 1;
+                continue;
+            }
+            if (!currentBlock) {
+                if (line.startsWith("schema ")) {
+                    const parsed = (0, statements_1.parseSchemaBlock)(lines, index);
+                    schemas.push(parsed.schema);
+                    index = parsed.nextIndex;
+                    continue;
+                }
+                if (line.startsWith("block ")) {
+                    currentBlock = createBlock((0, statements_1.parseBlockHeaderLine)(line));
+                    documentBlocks.push(currentBlock);
+                    index += 1;
+                    continue;
+                }
+                if (line === "}") {
+                    throw new Error(`Unexpected block terminator: ${line}`);
+                }
+                throw new Error(`Unsupported MDSN statement: ${line}`);
+            }
+            if (line === "}") {
+                currentBlock = null;
+                index += 1;
+                continue;
+            }
+            if (line.startsWith("input ")) {
+                currentBlock.inputs.push((0, statements_1.parseInputLine)(line, currentBlock.name));
+                index += 1;
+                continue;
+            }
+            if (line.startsWith("read ")) {
+                currentBlock.reads.push((0, statements_1.parseReadOrWriteLine)(line, "read", currentBlock.name, (0, statements_1.getNextOperationOrder)(currentBlock)));
+                index += 1;
+                continue;
+            }
+            if (line.startsWith("write ")) {
+                currentBlock.writes.push((0, statements_1.parseReadOrWriteLine)(line, "write", currentBlock.name, (0, statements_1.getNextOperationOrder)(currentBlock)));
+                index += 1;
+                continue;
+            }
+            if (line.startsWith("redirect ")) {
+                currentBlock.redirects.push((0, statements_1.parseRedirectLine)(line, currentBlock.name, (0, statements_1.getNextOperationOrder)(currentBlock)));
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unsupported MDSN statement: ${line}`);
+        }
+    }
+    if (currentBlock) {
+        throw new Error(`Unterminated block declaration: ${currentBlock.name}`);
+    }
+    return {
+        schemas,
+        blocks: documentBlocks,
+    };
+}

package/dist/core/protocol/statements.d.ts

@@ -0,0 +1,12 @@
+import type { BlockDefinition, ReadDefinition, RedirectDefinition, WriteDefinition } from "../model/block";
+import type { InputDefinition } from "../model/input";
+import type { SchemaDefinition } from "../model/schema";
+export declare function parseBlockHeaderLine(line: string): string;
+export declare function parseInputLine(line: string, blockName: string): InputDefinition;
+export declare function parseReadOrWriteLine(line: string, kind: "read" | "write", blockName: string, index: number): ReadDefinition | WriteDefinition;
+export declare function parseRedirectLine(line: string, blockName: string, index: number): RedirectDefinition;
+export declare function parseSchemaBlock(lines: string[], startIndex: number): {
+    schema: SchemaDefinition;
+    nextIndex: number;
+};
+export declare function getNextOperationOrder(block: BlockDefinition): number;

package/dist/core/protocol/statements.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBlockHeaderLine = parseBlockHeaderLine;
+exports.parseInputLine = parseInputLine;
+exports.parseReadOrWriteLine = parseReadOrWriteLine;
+exports.parseRedirectLine = parseRedirectLine;
+exports.parseSchemaBlock = parseSchemaBlock;
+exports.getNextOperationOrder = getNextOperationOrder;
+function isIdentifier(value) {
+    return /^[a-zA-Z_][\w-]*$/.test(value);
+}
+function parseIdentifierList(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    const items = trimmed.split(",").map((part) => part.trim()).filter(Boolean);
+    for (const item of items) {
+        if (!isIdentifier(item)) {
+            throw new Error(`Invalid identifier in argument list: ${item}`);
+        }
+    }
+    return items;
+}
+function parseStringArrayLiteral(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid array literal: ${raw}`);
+    }
+    return parsed;
+}
+function parseSchemaLiteral(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Schema body must be a JSON object");
+    }
+    return parsed;
+}
+function parseBlockHeaderLine(line) {
+    const match = line.trim().match(/^block\s+([a-zA-Z_][\w-]*)\s*\{$/);
+    if (!match) {
+        throw new Error(`Invalid block declaration: ${line}`);
+    }
+    return match[1];
+}
+function parseInputLine(line, blockName) {
+    const match = line
+        .trim()
+        .match(/^input\s+([a-zA-Z_][\w-]*)(!)?:\s*(text|number|boolean|choice|file|json)(?:\s+(secret))?(?:\s+(\[.*\]))?(?:\s+([a-zA-Z_][\w-]*))?$/);
+    if (!match) {
+        throw new Error(`Invalid input declaration: ${line}`);
+    }
+    const [, name, requiredMarker, type, secretMarker, optionsLiteral, schemaName] = match;
+    const input = {
+        id: `${blockName}::input::${name}`,
+        block: blockName,
+        name,
+        type: type,
+        required: requiredMarker === "!",
+        secret: secretMarker === "secret",
+    };
+    if (optionsLiteral) {
+        input.options = parseStringArrayLiteral(optionsLiteral);
+    }
+    if (schemaName) {
+        input.schema = schemaName;
+    }
+    if (input.type === "choice" && (!input.options || input.options.length === 0)) {
+        throw new Error(`Choice input ${name} in block ${blockName} must define options`);
+    }
+    if (input.type === "json" && !input.schema) {
+        throw new Error(`JSON input ${name} in block ${blockName} must define schema`);
+    }
+    return input;
+}
+function parseReadOrWriteLine(line, kind, blockName, index) {
+    const match = line
+        .trim()
+        .match(/^(read|write)\s+([a-zA-Z_][\w-]*)\s*:\s*"([^"]+)"(?:\s*\(([^)]*)\))?$/);
+    if (!match) {
+        throw new Error(`Invalid ${kind} declaration: ${line}`);
+    }
+    const [, parsedKind, name, target, rawInputs] = match;
+    if (parsedKind !== kind) {
+        throw new Error(`Expected ${kind} declaration: ${line}`);
+    }
+    const base = {
+        id: `${blockName}::${kind}::${index}`,
+        block: blockName,
+        name,
+        target,
+        inputs: parseIdentifierList(rawInputs ?? ""),
+        order: index,
+    };
+    return kind === "read" ? base : base;
+}
+function parseRedirectLine(line, blockName, index) {
+    const match = line.trim().match(/^redirect\s+"([^"]+)"$/);
+    if (!match) {
+        throw new Error(`Invalid redirect declaration: ${line}`);
+    }
+    return {
+        id: `${blockName}::redirect::${index}`,
+        block: blockName,
+        target: match[1],
+        order: index,
+    };
+}
+function parseSchemaBlock(lines, startIndex) {
+    const firstLine = lines[startIndex].trim();
+    const match = firstLine.match(/^schema\s+([a-zA-Z_][\w-]*)\s*(\{.*)?$/);
+    if (!match) {
+        throw new Error(`Invalid schema declaration: ${firstLine}`);
+    }
+    const name = match[1];
+    let literal = (match[2] ?? "").trim();
+    let braceDepth = (literal.match(/\{/g) ?? []).length - (literal.match(/\}/g) ?? []).length;
+    let index = startIndex;
+    while (braceDepth > 0) {
+        index += 1;
+        if (index >= lines.length) {
+            throw new Error(`Unterminated schema declaration: ${name}`);
+        }
+        literal += "\n" + lines[index];
+        braceDepth += (lines[index].match(/\{/g) ?? []).length;
+        braceDepth -= (lines[index].match(/\}/g) ?? []).length;
+    }
+    if (!literal.startsWith("{")) {
+        throw new Error(`schema ${name} must start with {`);
+    }
+    return {
+        schema: {
+            name,
+            shape: parseSchemaLiteral(literal),
+        },
+        nextIndex: index + 1,
+    };
+}
+function getNextOperationOrder(block) {
+    return block.reads.length + block.writes.length + block.redirects.length;
+}

package/dist/core/protocol/validation.d.ts

@@ -0,0 +1,4 @@
+import type { BlockDefinition } from "../model/block";
+import type { BlockAnchorDefinition } from "../model/document";
+import type { SchemaDefinition } from "../model/schema";
+export declare function validateDocumentStructure(schemas: SchemaDefinition[], blocks: BlockDefinition[], blockAnchors: BlockAnchorDefinition[]): void;

package/dist/core/protocol/validation.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDocumentStructure = validateDocumentStructure;
+function validateDocumentStructure(schemas, blocks, blockAnchors) {
+    const schemaNames = new Set();
+    for (const schema of schemas) {
+        if (schemaNames.has(schema.name)) {
+            throw new Error(`Duplicate schema name: ${schema.name}`);
+        }
+        schemaNames.add(schema.name);
+    }
+    const blockNames = new Set();
+    for (const block of blocks) {
+        if (blockNames.has(block.name)) {
+            throw new Error(`Duplicate block name: ${block.name}`);
+        }
+        blockNames.add(block.name);
+    }
+    const anchorNames = new Set();
+    for (const anchor of blockAnchors) {
+        if (anchorNames.has(anchor.name)) {
+            throw new Error(`Duplicate block anchor: ${anchor.name}`);
+        }
+        anchorNames.add(anchor.name);
+        if (!blockNames.has(anchor.name)) {
+            throw new Error(`Unknown block ${anchor.name} referenced by mdsn:block anchor`);
+        }
+    }
+    if (blockAnchors.length > 0) {
+        for (const block of blocks) {
+            if (!anchorNames.has(block.name)) {
+                throw new Error(`Missing mdsn:block anchor for block ${block.name}`);
+            }
+        }
+    }
+    for (const block of blocks) {
+        const inputNames = new Set();
+        const operationNames = new Set();
+        for (const input of block.inputs) {
+            if (inputNames.has(input.name)) {
+                throw new Error(`Duplicate input name in block ${block.name}: ${input.name}`);
+            }
+            inputNames.add(input.name);
+            if (input.schema && !schemaNames.has(input.schema)) {
+                throw new Error(`Unknown schema ${input.schema} referenced by input ${input.name}`);
+            }
+        }
+        for (const operation of [...block.reads, ...block.writes]) {
+            if (operationNames.has(operation.name)) {
+                throw new Error(`Duplicate operation name in block ${block.name}: ${operation.name}`);
+            }
+            operationNames.add(operation.name);
+            for (const inputName of operation.inputs) {
+                if (!inputNames.has(inputName)) {
+                    throw new Error(`Unknown input ${inputName} referenced by ${operation.id}`);
+                }
+            }
+        }
+    }
+}

package/dist/framework/create-framework-app.d.ts

@@ -0,0 +1,12 @@
+import type { ActionHandler } from "../server/action-host";
+import type { MdsnConfig } from "../server/config";
+export interface CreateFrameworkAppOptions {
+    rootDir: string;
+    config?: MdsnConfig;
+    actions?: Record<string, ActionHandler<{
+        inputs: Record<string, unknown>;
+    }>>;
+    mode?: "dev" | "start";
+    devState?: unknown;
+}
+export declare function createFrameworkApp(options: CreateFrameworkAppOptions): import("express-serve-static-core").Express;

package/dist/framework/create-framework-app.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFrameworkApp = createFrameworkApp;
+const site_app_1 = require("./site-app");
+function createFrameworkApp(options) {
+    return (0, site_app_1.createSiteApp)({
+        rootDir: options.rootDir,
+        config: options.config,
+        actions: options.actions,
+    });
+}

package/dist/framework/hosted-app.d.ts

@@ -0,0 +1,13 @@
+import { type ActionHandler } from "../server/action-host";
+import { type RenderHostedPageOptions } from "../server/page-host";
+export interface CreateHostedAppOptions {
+    pages: Record<string, string>;
+    actions?: Record<string, ActionHandler<{
+        inputs: Record<string, unknown>;
+    }>>;
+    publicDir?: string;
+    render?: Omit<RenderHostedPageOptions, "accept" | "routePath" | "layoutTemplate"> & {
+        resolveLayoutTemplate?: (routePath: string, rawPage: string) => string | undefined;
+    };
+}
+export declare function createHostedApp(options: CreateHostedAppOptions): import("express-serve-static-core").Express;

package/dist/framework/hosted-app.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHostedApp = createHostedApp;
+const express_1 = __importDefault(require("express"));
+const page_definition_1 = require("../core/document/page-definition");
+const action_host_1 = require("../server/action-host");
+const page_links_1 = require("../server/page-links");
+const page_host_1 = require("../server/page-host");
+const negotiate_1 = require("../server/negotiate");
+const route_matcher_1 = require("../server/route-matcher");
+const fragment_render_1 = require("../web/fragment-render");
+const page_client_script_1 = require("../web/page-client-script");
+function normalizeActionId(target) {
+    const trimmed = String(target).trim();
+    if (!trimmed || /^https?:\/\//i.test(trimmed)) {
+        return null;
+    }
+    if (trimmed.toLowerCase().endsWith(".md")) {
+        return null;
+    }
+    return trimmed.replace(/^\/+/u, "");
+}
+function buildActionBindings(pages) {
+    const bindings = new Map();
+    for (const pageSource of Object.values(pages)) {
+        let document;
+        try {
+            document = (0, page_definition_1.parsePageDefinition)(pageSource);
+        }
+        catch {
+            continue;
+        }
+        for (const block of document.blocks) {
+            for (const operation of [...block.reads, ...block.writes]) {
+                const targetPath = (0, page_links_1.mapPageTargetToHttpPath)(operation.target);
+                const actionId = normalizeActionId(operation.target);
+                if (!actionId) {
+                    continue;
+                }
+                const existing = bindings.get(targetPath);
+                if (existing && (existing.actionId !== actionId || existing.blockName !== block.name)) {
+                    throw new Error(`Action target must bind to one stable block context: ${targetPath}`);
+                }
+                bindings.set(targetPath, {
+                    actionId,
+                    blockName: block.name,
+                });
+            }
+        }
+    }
+    return bindings;
+}
+function createHostedApp(options) {
+    const app = (0, express_1.default)();
+    const actionBindings = buildActionBindings(options.pages);
+    const routedPages = (0, route_matcher_1.sortRoutedPagesForMatching)(Object.entries(options.pages).map(([routePath, source]) => ({
+        routePath,
+        source,
+    })));
+    app.use(express_1.default.json());
+    if (typeof options.publicDir === "string") {
+        app.use(express_1.default.static(options.publicDir));
+    }
+    app.get("/__mdsn/client.js", (_req, res) => {
+        res.type("application/javascript; charset=utf-8").send((0, page_client_script_1.getPageClientRuntimeScript)());
+    });
+    app.post("*", async (req, res, next) => {
+        const binding = actionBindings.get(req.path);
+        if (!binding) {
+            next();
+            return;
+        }
+        const action = options.actions?.[binding.actionId];
+        if (!action) {
+            res.status(404).json({
+                ok: false,
+                errorCode: "NOT_FOUND",
+            });
+            return;
+        }
+        try {
+            const result = await (0, action_host_1.executeActionHandler)(action, {
+                inputs: (req.body?.inputs ?? {}),
+            });
+            if (result.ok && result.kind === "fragment") {
+                if ((0, negotiate_1.wantsMarkdown)(req.headers.accept)) {
+                    res.status(200).type("text/markdown; charset=utf-8").send(result.markdown);
+                    return;
+                }
+                res.status(200).json({
+                    ...result,
+                    html: (0, fragment_render_1.renderBlockFragmentHtml)(result.markdown, binding.blockName, {
+                        mapActionTarget: options.render?.mapActionTarget ?? page_links_1.mapPageTargetToHttpPath,
+                        markdown: options.render?.markdown,
+                    }),
+                });
+                return;
+            }
+            res.status(result.ok ? 200 : 400).json(result);
+        }
+        catch (error) {
+            res.status(500).json({
+                ok: false,
+                errorCode: "INTERNAL_ERROR",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    app.get("*", (req, res) => {
+        const matchedPage = (0, route_matcher_1.resolveRoutedPageForPath)(req.path, routedPages);
+        if (!matchedPage) {
+            res.status(404).type("text/plain; charset=utf-8").send("Not Found");
+            return;
+        }
+        const rendered = (0, page_host_1.renderHostedPage)(matchedPage.source, {
+            accept: req.headers.accept,
+            routePath: req.path,
+            siteTitle: options.render?.siteTitle,
+            siteDescription: options.render?.siteDescription,
+            siteBaseUrl: options.render?.siteBaseUrl,
+            locales: options.render?.locales,
+            defaultLocale: options.render?.defaultLocale,
+            markdown: options.render?.markdown,
+            mapActionTarget: options.render?.mapActionTarget ?? page_links_1.mapPageTargetToHttpPath,
+            layoutTemplate: options.render?.resolveLayoutTemplate?.(req.path, matchedPage.source),
+        });
+        res.status(rendered.status).type(rendered.contentType).send(rendered.body);
+    });
+    return app;
+}

package/dist/framework/index.d.ts

@@ -0,0 +1,4 @@
+export { createFrameworkApp } from "./create-framework-app";
+export type { CreateFrameworkAppOptions } from "./create-framework-app";
+export { defineConfig } from "../server/config";
+export type { MdsnConfig } from "../server/config";

package/dist/framework/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = exports.createFrameworkApp = void 0;
+var create_framework_app_1 = require("./create-framework-app");
+Object.defineProperty(exports, "createFrameworkApp", { enumerable: true, get: function () { return create_framework_app_1.createFrameworkApp; } });
+var config_1 = require("../server/config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });

package/dist/framework/site-app.d.ts

@@ -0,0 +1,12 @@
+import { type CreateHostedAppOptions } from "./hosted-app";
+import type { ActionHandler } from "../server/action-host";
+import { type MdsnConfig } from "../server/config";
+export declare function loadActionHandlers(serverDir: string): Record<string, ActionHandler<{
+    inputs: Record<string, unknown>;
+}>>;
+export interface CreateSiteAppOptions {
+    rootDir: string;
+    config?: MdsnConfig;
+    actions?: CreateHostedAppOptions["actions"];
+}
+export declare function createSiteApp(options: CreateSiteAppOptions): import("express-serve-static-core").Express;