@mdsnai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MDSN Contributors
+
+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 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

@@ -0,0 +1,67 @@
+# @mdsnai/sdk
+
+`@mdsnai/sdk` is the reference SDK and runtime for MDSN.
+
+MDSN keeps page content and page interaction in the same source by combining a Markdown body with an executable `mdsn` block.
+
+## Why MDSN
+
+Plain Markdown is good for content, but weak at expressing interaction.
+
+Once a page needs inputs, actions, partial updates, or navigation, that structure usually gets pushed into templates, frontend state, and custom API glue.
+
+MDSN makes that interaction layer explicit while keeping the page source readable for humans, AI agents, and agentic AI systems.
+
+## What This Package Includes
+
+- the MDSN parser and core model
+- server helpers for actions and Markdown fragments
+- a built-in framework host and CLI
+- headless web APIs for custom rendering
+- default browser runtime utilities
+
+## Package Entry Points
+
+- `@mdsnai/sdk`
+- `@mdsnai/sdk/core`
+- `@mdsnai/sdk/server`
+- `@mdsnai/sdk/web`
+- `@mdsnai/sdk/framework`
+- `@mdsnai/sdk/cli`
+
+## Use Cases
+
+- skills apps for non-technical users
+- agent apps that agents can enter and operate directly
+- interactive documents with embedded actions
+- human-agent collaboration on the same page model
+- agentic workflows and AI workflow automation
+- custom hosted interfaces with React, Vue, or your own server stack
+
+## Quick Start
+
+```bash
+npm create mdsn@latest skills-app
+cd skills-app
+npm install
+npm run dev
+```
+
+Open:
+
+```text
+http://localhost:3000/
+```
+
+The starter generates a minimal runnable site with:
+
+- `pages/index.md`
+- `server/actions.cjs`
+
+## Docs
+
+- [Getting Started](https://docs.mdsn.ai/docs/getting-started)
+- [Framework Development](https://docs.mdsn.ai/docs/site-development)
+- [Server Development](https://docs.mdsn.ai/docs/server-development)
+- [Action Reference](https://docs.mdsn.ai/docs/action-reference)
+- [SDK Reference](https://docs.mdsn.ai/docs/sdk-reference)

package/dist/cli/args.d.ts

@@ -0,0 +1,8 @@
+export type ParsedCliArgs = {
+    cwd?: string;
+    port?: number;
+    positional: string[];
+};
+export declare function parseCliArgs(argv: string[], options: {
+    allowPort: boolean;
+}): ParsedCliArgs;

package/dist/cli/args.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliArgs = parseCliArgs;
+function parseCliArgs(argv, options) {
+    const parsed = {
+        positional: [],
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--cwd" || token === "-C") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`Missing value for ${token}`);
+            }
+            parsed.cwd = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--cwd=")) {
+            const value = token.slice("--cwd=".length);
+            if (!value) {
+                throw new Error("Missing value for --cwd");
+            }
+            parsed.cwd = value;
+            continue;
+        }
+        if (token === "--port" || token === "-p") {
+            if (!options.allowPort) {
+                throw new Error("Option --port is only supported by dev/start");
+            }
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`Missing value for ${token}`);
+            }
+            parsed.port = parsePort(value);
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--port=")) {
+            if (!options.allowPort) {
+                throw new Error("Option --port is only supported by dev/start");
+            }
+            const value = token.slice("--port=".length);
+            if (!value) {
+                throw new Error("Missing value for --port");
+            }
+            parsed.port = parsePort(value);
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw new Error(`Unknown option: ${token}`);
+        }
+        parsed.positional.push(token);
+    }
+    return parsed;
+}
+function parsePort(raw) {
+    const numeric = Number(raw);
+    if (!Number.isInteger(numeric) || numeric <= 0 || numeric > 65535) {
+        throw new Error(`Invalid value for --port: ${raw}`);
+    }
+    return numeric;
+}

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,5 @@
+export declare function runBuild(options?: {
+    cwd?: string;
+    positional?: string[];
+    log?: (message: string) => void;
+}): Promise<void>;

package/dist/cli/commands/build.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBuild = runBuild;
+const node_path_1 = __importDefault(require("node:path"));
+const build_1 = require("../../server/build");
+const server_1 = require("../../server/server");
+async function runBuild(options = {}) {
+    if ((options.positional ?? []).length > 0) {
+        throw new Error("build does not accept positional arguments");
+    }
+    const rootDir = node_path_1.default.resolve(options.cwd ?? process.cwd());
+    const config = await (0, server_1.loadUserConfig)(rootDir);
+    const output = await (0, build_1.buildFrameworkSite)({ rootDir, config });
+    const log = options.log ?? console.log;
+    log(`MDSN build complete: ${output.outDir}`);
+}

package/dist/cli/commands/create.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs } from "../args";
+export declare function runCreate(options?: ParsedCliArgs): Promise<void>;

package/dist/cli/commands/create.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCreate = runCreate;
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const init_1 = require("../../server/init");
+function installStarterDependencies(targetDir) {
+    if (process.env.MDSN_CREATE_SKIP_INSTALL === "1") {
+        return;
+    }
+    const command = process.platform === "win32" ? "npm.cmd" : "npm";
+    const result = (0, node_child_process_1.spawnSync)(command, ["install"], {
+        cwd: targetDir,
+        stdio: "inherit",
+        env: process.env,
+    });
+    if (result.error) {
+        throw new Error(`Failed to install starter dependencies: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`npm install failed in ${targetDir}`);
+    }
+}
+async function runCreate(options = { positional: [] }) {
+    if (options.port !== undefined) {
+        throw new Error("Option --port is only supported by dev/start");
+    }
+    if (options.positional.length > 1) {
+        throw new Error("create accepts at most one target directory");
+    }
+    const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
+    const targetDir = options.positional[0] ?? ".";
+    const absoluteTargetDir = node_path_1.default.resolve(cwd, targetDir);
+    (0, init_1.createStarterSite)(absoluteTargetDir);
+    installStarterDependencies(absoluteTargetDir);
+}

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,10 @@
+import type { CreateFrameworkAppFn, ListenFn, OpenBrowserFn } from "../../server/server";
+export declare function runDev(options?: {
+    cwd?: string;
+    port?: number;
+    positional?: string[];
+    createApp?: CreateFrameworkAppFn;
+    listen?: ListenFn;
+    openBrowser?: OpenBrowserFn;
+    log?: (message: string) => void;
+}): Promise<void>;

package/dist/cli/commands/dev.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDev = runDev;
+const server_1 = require("../../server/server");
+async function runDev(options = {}) {
+    if ((options.positional ?? []).length > 0) {
+        throw new Error("dev does not accept positional arguments");
+    }
+    await (0, server_1.startFrameworkServer)({
+        ...options,
+        mode: "dev",
+    });
+}

package/dist/cli/commands/start.d.ts

@@ -0,0 +1,9 @@
+import type { CreateFrameworkAppFn, ListenFn } from "../../server/server";
+export declare function runStart(options?: {
+    cwd?: string;
+    port?: number;
+    positional?: string[];
+    createApp?: CreateFrameworkAppFn;
+    listen?: ListenFn;
+    log?: (message: string) => void;
+}): Promise<void>;

package/dist/cli/commands/start.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStart = runStart;
+const server_1 = require("../../server/server");
+async function runStart(options = {}) {
+    if ((options.positional ?? []).length > 0) {
+        throw new Error("start does not accept positional arguments");
+    }
+    await (0, server_1.startFrameworkServer)({
+        ...options,
+        mode: "start",
+    });
+}

package/dist/cli/entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/entry.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+(0, index_1.runCli)(process.argv.slice(2)).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,9 @@
+export { parseCliArgs } from "./args";
+export type { ParsedCliArgs } from "./args";
+export type CliHandlers = {
+    create?: (args: string[]) => Promise<void> | void;
+    dev?: (args: string[]) => Promise<void> | void;
+    build?: (args: string[]) => Promise<void> | void;
+    start?: (args: string[]) => Promise<void> | void;
+};
+export declare function runCli(argv: string[], handlers?: CliHandlers): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliArgs = void 0;
+exports.runCli = runCli;
+const build_1 = require("./commands/build");
+const create_1 = require("./commands/create");
+const dev_1 = require("./commands/dev");
+const start_1 = require("./commands/start");
+const args_1 = require("./args");
+var args_2 = require("./args");
+Object.defineProperty(exports, "parseCliArgs", { enumerable: true, get: function () { return args_2.parseCliArgs; } });
+const KNOWN_COMMANDS = ["create", "dev", "build", "start"];
+async function runCli(argv, handlers = {}) {
+    const command = argv[0];
+    const commandArgs = argv.slice(1);
+    switch (command) {
+        case "create":
+            if (handlers.create) {
+                await handlers.create(commandArgs);
+                return;
+            }
+            await (0, create_1.runCreate)((0, args_1.parseCliArgs)(commandArgs, { allowPort: false }));
+            return;
+        case "dev":
+            if (handlers.dev) {
+                await handlers.dev(commandArgs);
+                return;
+            }
+            await (0, dev_1.runDev)((0, args_1.parseCliArgs)(commandArgs, { allowPort: true }));
+            return;
+        case "build":
+            if (handlers.build) {
+                await handlers.build(commandArgs);
+                return;
+            }
+            await (0, build_1.runBuild)((0, args_1.parseCliArgs)(commandArgs, { allowPort: false }));
+            return;
+        case "start":
+            if (handlers.start) {
+                await handlers.start(commandArgs);
+                return;
+            }
+            await (0, start_1.runStart)((0, args_1.parseCliArgs)(commandArgs, { allowPort: true }));
+            return;
+        default:
+            throw new Error(`Unknown command: ${command ?? "(none)"}. Expected one of: ${KNOWN_COMMANDS.join(", ")}`);
+    }
+}
+function isDirectExecution() {
+    const entry = process.argv[1];
+    return typeof entry === "string" && /src[\\/]cli[\\/]index\.ts$/.test(entry);
+}
+if (isDirectExecution()) {
+    runCli(process.argv.slice(2)).catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/dist/core/action/execution.d.ts

@@ -0,0 +1,4 @@
+import type { ActionResult, FragmentActionSuccess, RedirectActionSuccess } from "./types";
+export declare function fragmentActionResult(markdown: string): FragmentActionSuccess;
+export declare function redirectActionResult(location: string): RedirectActionSuccess;
+export declare function normalizeActionResult(value: unknown): ActionResult;

package/dist/core/action/execution.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fragmentActionResult = fragmentActionResult;
+exports.redirectActionResult = redirectActionResult;
+exports.normalizeActionResult = normalizeActionResult;
+function isFailure(value) {
+    return !!value && typeof value === "object" && value.ok === false;
+}
+function isFragmentSuccess(value) {
+    return !!value
+        && typeof value === "object"
+        && value.ok === true
+        && value.kind === "fragment"
+        && typeof value.markdown === "string";
+}
+function isRedirectSuccess(value) {
+    return !!value
+        && typeof value === "object"
+        && value.ok === true
+        && value.kind === "redirect"
+        && typeof value.location === "string";
+}
+function fragmentActionResult(markdown) {
+    return {
+        ok: true,
+        kind: "fragment",
+        markdown,
+    };
+}
+function redirectActionResult(location) {
+    return {
+        ok: true,
+        kind: "redirect",
+        location,
+    };
+}
+function normalizeActionResult(value) {
+    if (typeof value === "string") {
+        return fragmentActionResult(value);
+    }
+    if (isFailure(value) || isFragmentSuccess(value) || isRedirectSuccess(value)) {
+        return value;
+    }
+    if (value
+        && typeof value === "object"
+        && value.ok === true
+        && value.kind === "fragment") {
+        throw new Error("Invalid fragment action result");
+    }
+    if (value
+        && typeof value === "object"
+        && value.ok === true
+        && value.kind === "redirect") {
+        throw new Error("Invalid redirect action result");
+    }
+    throw new Error("Invalid action result");
+}

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

@@ -0,0 +1,2 @@
+export { fragmentActionResult, normalizeActionResult, redirectActionResult, } from "./execution";
+export type { ActionFailure, ActionFieldErrors, ActionResult, ActionSuccess, FragmentActionSuccess, RedirectActionSuccess, } from "./types";

package/dist/core/action/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redirectActionResult = exports.normalizeActionResult = exports.fragmentActionResult = void 0;
+var execution_1 = require("./execution");
+Object.defineProperty(exports, "fragmentActionResult", { enumerable: true, get: function () { return execution_1.fragmentActionResult; } });
+Object.defineProperty(exports, "normalizeActionResult", { enumerable: true, get: function () { return execution_1.normalizeActionResult; } });
+Object.defineProperty(exports, "redirectActionResult", { enumerable: true, get: function () { return execution_1.redirectActionResult; } });

package/dist/core/action/types.d.ts

@@ -0,0 +1,19 @@
+export type ActionFieldErrors = Record<string, string>;
+export type FragmentActionSuccess = {
+    ok: true;
+    kind: "fragment";
+    markdown: string;
+};
+export type RedirectActionSuccess = {
+    ok: true;
+    kind: "redirect";
+    location: string;
+};
+export type ActionFailure = {
+    ok: false;
+    errorCode: string;
+    message?: string;
+    fieldErrors?: ActionFieldErrors;
+};
+export type ActionSuccess = FragmentActionSuccess | RedirectActionSuccess;
+export type ActionResult = ActionSuccess | ActionFailure;

package/dist/core/action/types.js

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

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

@@ -0,0 +1,5 @@
+import type { FrontmatterData } from "../model/document";
+export declare function parseFrontmatter(raw: string): {
+    frontmatter: FrontmatterData;
+    body: string;
+};

package/dist/core/document/frontmatter.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+function parseScalarValue(raw) {
+    const value = raw.trim();
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(value))
+        return Number(value);
+    return value.replace(/^["']|["']$/g, "");
+}
+function parseFrontmatter(raw) {
+    if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+        return { frontmatter: {}, body: raw };
+    }
+    const lines = raw.split(/\r?\n/);
+    const frontmatter = {};
+    let index = 1;
+    while (index < lines.length && lines[index] !== "---") {
+        const line = lines[index].trim();
+        if (line) {
+            const separatorIndex = line.indexOf(":");
+            if (separatorIndex === -1) {
+                throw new Error(`Invalid frontmatter line: ${line}`);
+            }
+            const key = line.slice(0, separatorIndex).trim();
+            const value = line.slice(separatorIndex + 1).trim();
+            frontmatter[key] = parseScalarValue(value);
+        }
+        index += 1;
+    }
+    if (index >= lines.length) {
+        throw new Error("Unterminated frontmatter block");
+    }
+    return {
+        frontmatter,
+        body: lines.slice(index + 1).join("\n"),
+    };
+}

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

@@ -0,0 +1,5 @@
+export declare function extractExecutableMdsnBlocks(markdown: string): {
+    markdownWithoutMdsn: string;
+    blocks: string[];
+};
+export declare function extractBlockAnchors(markdown: string): string[];

package/dist/core/document/markdown.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExecutableMdsnBlocks = extractExecutableMdsnBlocks;
+exports.extractBlockAnchors = extractBlockAnchors;
+function trimTrailingBlankLines(value) {
+    return value.replace(/\n+$/u, "\n");
+}
+function extractExecutableMdsnBlocks(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const keptLines = [];
+    const blocks = [];
+    let index = 0;
+    let activeFence = null;
+    while (index < lines.length) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        const fenceMatch = trimmed.match(/^(`{3,}|~{3,})(.*)$/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            const info = fenceMatch[2].trim();
+            if (activeFence) {
+                if (trimmed === activeFence.marker) {
+                    activeFence = null;
+                }
+                keptLines.push(line);
+                index += 1;
+                continue;
+            }
+            if (marker === "```" && info === "mdsn") {
+                index += 1;
+                const blockLines = [];
+                while (index < lines.length && lines[index].trim() !== "```") {
+                    blockLines.push(lines[index]);
+                    index += 1;
+                }
+                if (index >= lines.length) {
+                    throw new Error("Unterminated mdsn code block");
+                }
+                blocks.push(blockLines.join("\n"));
+                index += 1;
+                continue;
+            }
+            activeFence = { marker, info };
+            keptLines.push(line);
+            index += 1;
+            continue;
+        }
+        keptLines.push(line);
+        index += 1;
+    }
+    return {
+        markdownWithoutMdsn: trimTrailingBlankLines(keptLines.join("\n")),
+        blocks,
+    };
+}
+function extractBlockAnchors(markdown) {
+    const anchors = [];
+    let activeFence = null;
+    for (const line of markdown.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        const fenceMatch = trimmed.match(/^(`{3,}|~{3,})(.*)$/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            if (activeFence) {
+                if (trimmed === activeFence) {
+                    activeFence = null;
+                }
+            }
+            else {
+                activeFence = marker;
+            }
+            continue;
+        }
+        if (activeFence) {
+            continue;
+        }
+        const anchorMatch = trimmed.match(/^<!--\s*mdsn:block\s+([a-zA-Z_][\w-]*)\s*-->$/);
+        if (anchorMatch) {
+            anchors.push(anchorMatch[1]);
+        }
+    }
+    return anchors;
+}

package/dist/core/document/page-definition.d.ts

@@ -0,0 +1,2 @@
+import type { DocumentDefinition } from "../model/document";
+export declare function parsePageDefinition(raw: string): DocumentDefinition;

package/dist/core/document/page-definition.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePageDefinition = parsePageDefinition;
+const frontmatter_1 = require("./frontmatter");
+const markdown_1 = require("./markdown");
+const mdsn_1 = require("../protocol/mdsn");
+const validation_1 = require("../protocol/validation");
+function parsePageDefinition(raw) {
+    const { frontmatter, body } = (0, frontmatter_1.parseFrontmatter)(raw);
+    const { markdownWithoutMdsn, blocks } = (0, markdown_1.extractExecutableMdsnBlocks)(body);
+    if (blocks.length > 1) {
+        throw new Error("An MDSN page must contain at most one mdsn code block");
+    }
+    const parsed = (0, mdsn_1.parseMdsnBlocks)(blocks);
+    const blockAnchors = (0, markdown_1.extractBlockAnchors)(markdownWithoutMdsn).map((name) => ({ name }));
+    (0, validation_1.validateDocumentStructure)(parsed.schemas, parsed.blocks, blockAnchors);
+    return {
+        frontmatter,
+        markdown: markdownWithoutMdsn,
+        schemas: parsed.schemas,
+        blocks: parsed.blocks,
+        blockAnchors,
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export { parsePageDefinition } from "./document/page-definition";
+export type { FrontmatterData } from "./model/document";
+export type { BlockAnchorDefinition, BlockDefinition, DocumentDefinition, InputDefinition, InputType, ReadDefinition, RedirectDefinition, SchemaDefinition, WriteDefinition, } from "./model";

package/dist/core/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePageDefinition = void 0;
+var page_definition_1 = require("./document/page-definition");
+Object.defineProperty(exports, "parsePageDefinition", { enumerable: true, get: function () { return page_definition_1.parsePageDefinition; } });