@mdsnai/sdk 0.1.0 → 0.2.0

package/dist/server/action.js

@@ -42,7 +42,11 @@ function actionExportNameToActionId(filePath, actionsDir, exportName) {
     return baseId ? `${baseId}/${exportName}` : exportName;
 }
 function isActionDefinition(value) {
-    return !!value && typeof value === "object" && typeof value.run === "function";
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const obj = value;
+    return typeof obj.run === "function";
 }
 function actionDefinitionEntriesFromMap(candidate) {
     if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {

package/dist/server/build.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const action_1 = require("./action");
 const config_1 = require("./config");
 const page_definition_1 = require("../core/document/page-definition");
+const block_1 = require("../core/model/block");
 const routes_1 = require("./routes");
 const site_1 = require("./site");
 function copyDirectoryContents(sourceDir, destinationDir) {
@@ -94,6 +95,9 @@ async function buildFrameworkSite(options) {
         }
         for (const block of page.blocks) {
             for (const operation of [...block.reads, ...block.writes]) {
+                if ("accept" in operation && (!operation.name || (0, block_1.isStreamAccept)(operation.accept))) {
+                    continue;
+                }
                 const actionId = normalizeDeclaredActionId(operation.target);
                 if (!actionId) {
                     continue;

package/dist/server/error-fragments.d.ts

@@ -0,0 +1,46 @@
+import { type SerializableBlock } from "./markdown";
+export interface RenderErrorFragmentOptions {
+    preface?: string[];
+    heading?: string;
+    message: string;
+    nextStep?: string;
+    details?: string[];
+    block?: SerializableBlock;
+}
+export declare function renderErrorFragment(options: RenderErrorFragmentOptions): string;
+export interface RenderActionNotAvailableFragmentOptions {
+    heading?: string;
+    message?: string;
+    nextStep?: string;
+    block?: SerializableBlock;
+}
+export declare function renderActionNotAvailableFragment(options?: RenderActionNotAvailableFragmentOptions): string;
+export interface RenderUnsupportedContentTypeFragmentOptions {
+    heading?: string;
+    message?: string;
+    nextStep?: string;
+    block?: SerializableBlock;
+}
+export declare function renderUnsupportedContentTypeFragment(options?: RenderUnsupportedContentTypeFragmentOptions): string;
+export interface RenderInternalErrorFragmentOptions {
+    heading?: string;
+    message?: string;
+    nextStep?: string;
+    error?: unknown;
+    block?: SerializableBlock;
+}
+export declare function renderInternalErrorFragment(options?: RenderInternalErrorFragmentOptions): string;
+export interface RenderAuthRequiredFragmentOptions {
+    heading?: string;
+    message?: string;
+    nextStep?: string;
+    blockName?: string;
+    emailInputName?: string;
+    passwordInputName?: string;
+    loginActionName?: string;
+    loginTarget?: string;
+    registerActionName?: string;
+    registerTarget?: string;
+    includeRegisterAction?: boolean;
+}
+export declare function renderAuthRequiredFragment(options?: RenderAuthRequiredFragmentOptions): string;

package/dist/server/error-fragments.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderErrorFragment = renderErrorFragment;
+exports.renderActionNotAvailableFragment = renderActionNotAvailableFragment;
+exports.renderUnsupportedContentTypeFragment = renderUnsupportedContentTypeFragment;
+exports.renderInternalErrorFragment = renderInternalErrorFragment;
+exports.renderAuthRequiredFragment = renderAuthRequiredFragment;
+const markdown_1 = require("./markdown");
+function renderErrorFragment(options) {
+    return (0, markdown_1.renderMarkdownFragment)({
+        body: [
+            ...(options.preface ?? []),
+            options.heading ?? "## Action Status",
+            options.message,
+            ...(options.details ?? []),
+            options.nextStep,
+        ].filter((value) => typeof value === "string" && value.trim().length > 0),
+        block: options.block,
+    });
+}
+function renderActionNotAvailableFragment(options = {}) {
+    return renderErrorFragment({
+        heading: options.heading ?? "## Action Status",
+        message: options.message ?? "This action is not available on the current server.",
+        nextStep: options.nextStep ?? "Next step: follow another declared action or reload the current page definition.",
+        block: options.block,
+    });
+}
+function renderUnsupportedContentTypeFragment(options = {}) {
+    return renderErrorFragment({
+        heading: options.heading ?? "## Action Status",
+        message: options.message ?? "Unsupported content type for write action.",
+        nextStep: options.nextStep
+            ?? "Next step: resend with `Content-Type: text/markdown` and a plain-text `key: value` body.",
+        block: options.block,
+    });
+}
+function renderInternalErrorFragment(options = {}) {
+    return renderErrorFragment({
+        heading: options.heading ?? "## Action Status",
+        message: options.message ?? "The action failed due to an internal error.",
+        nextStep: options.nextStep ?? "Next step: retry the action, or inspect server logs if the problem persists.",
+        details: options.error == null
+            ? []
+            : [options.error instanceof Error ? options.error.message : String(options.error)],
+        block: options.block,
+    });
+}
+function renderAuthRequiredFragment(options = {}) {
+    const emailInputName = options.emailInputName ?? "email";
+    const passwordInputName = options.passwordInputName ?? "password";
+    const loginActionName = options.loginActionName ?? "login";
+    const loginTarget = options.loginTarget ?? "/login";
+    const includeRegisterAction = options.includeRegisterAction ?? true;
+    const registerActionName = options.registerActionName ?? "go_register";
+    const registerTarget = options.registerTarget ?? "/register";
+    const block = {
+        name: options.blockName ?? "auth",
+        inputs: [
+            { name: emailInputName, type: "text", required: true },
+            { name: passwordInputName, type: "text", required: true, secret: true },
+        ],
+        reads: includeRegisterAction
+            ? [{ name: registerActionName, target: registerTarget }]
+            : [],
+        writes: [
+            { name: loginActionName, target: loginTarget, inputs: [emailInputName, passwordInputName] },
+        ],
+    };
+    return renderErrorFragment({
+        heading: options.heading ?? "## Login Status",
+        message: options.message ?? "Login required: sign in before continuing.",
+        nextStep: options.nextStep
+            ?? "Next step: enter email/password and run login, or go to register if no account exists.",
+        block,
+    });
+}

package/dist/server/index.d.ts

@@ -1,8 +1,15 @@
 export { defineAction, defineActions } from "./action";
+export { normalizeActionInputPayloadToMarkdown, parseActionInputs, serializeActionInputsAsMarkdown, } from "./action-inputs";
+export { createActionContextFromRequest, } from "./action-context";
 export { renderMarkdownFragment, renderMarkdownValue, serializeBlock, } from "./markdown";
+export { HttpCookieJar, parseCookieHeader, requireSessionFromCookie, } from "./session";
+export { renderActionNotAvailableFragment, renderAuthRequiredFragment, renderErrorFragment, renderInternalErrorFragment, renderUnsupportedContentTypeFragment, } from "./error-fragments";
 export { wantsHtml } from "./negotiate";
 export { executeActionHandler } from "./action-host";
 export { renderHostedPage } from "./page-host";
-export type { ActionContext, ActionDefinition, ActionDefinitionMap, ActionResult, } from "./action";
-export type { MarkdownImageValue, MarkdownTableValue, MarkdownValueType, RenderMarkdownFragmentOptions, SerializableBlock, SerializableInput, SerializableRead, SerializableRedirect, SerializableWrite, } from "./markdown";
+export type { ActionContext, ActionDefinition, ActionDefinitionMap, } from "./action";
+export type { CreateActionContextFromRequestOptions, } from "./action-context";
+export type { MarkdownImageValue, MarkdownTableValue, MarkdownValueType, RenderMarkdownFragmentOptions, SerializableBlock, SerializableInput, SerializableRead, SerializableWrite, } from "./markdown";
+export type { HeaderCarrier, RequireSessionFromCookieOptions, SessionGuardFailure, SessionGuardResult, SessionGuardSuccess, } from "./session";
+export type { RenderActionNotAvailableFragmentOptions, RenderAuthRequiredFragmentOptions, RenderErrorFragmentOptions, RenderInternalErrorFragmentOptions, RenderUnsupportedContentTypeFragmentOptions, } from "./error-fragments";
 export type { HostedPageResponse } from "./page-host";

package/dist/server/index.js

@@ -1,13 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderHostedPage = exports.executeActionHandler = exports.wantsHtml = exports.serializeBlock = exports.renderMarkdownValue = exports.renderMarkdownFragment = exports.defineActions = exports.defineAction = void 0;
+exports.renderHostedPage = exports.executeActionHandler = exports.wantsHtml = exports.renderUnsupportedContentTypeFragment = exports.renderInternalErrorFragment = exports.renderErrorFragment = exports.renderAuthRequiredFragment = exports.renderActionNotAvailableFragment = exports.requireSessionFromCookie = exports.parseCookieHeader = exports.HttpCookieJar = exports.serializeBlock = exports.renderMarkdownValue = exports.renderMarkdownFragment = exports.createActionContextFromRequest = exports.serializeActionInputsAsMarkdown = exports.parseActionInputs = exports.normalizeActionInputPayloadToMarkdown = exports.defineActions = exports.defineAction = void 0;
 var action_1 = require("./action");
 Object.defineProperty(exports, "defineAction", { enumerable: true, get: function () { return action_1.defineAction; } });
 Object.defineProperty(exports, "defineActions", { enumerable: true, get: function () { return action_1.defineActions; } });
+var action_inputs_1 = require("./action-inputs");
+Object.defineProperty(exports, "normalizeActionInputPayloadToMarkdown", { enumerable: true, get: function () { return action_inputs_1.normalizeActionInputPayloadToMarkdown; } });
+Object.defineProperty(exports, "parseActionInputs", { enumerable: true, get: function () { return action_inputs_1.parseActionInputs; } });
+Object.defineProperty(exports, "serializeActionInputsAsMarkdown", { enumerable: true, get: function () { return action_inputs_1.serializeActionInputsAsMarkdown; } });
+var action_context_1 = require("./action-context");
+Object.defineProperty(exports, "createActionContextFromRequest", { enumerable: true, get: function () { return action_context_1.createActionContextFromRequest; } });
 var markdown_1 = require("./markdown");
 Object.defineProperty(exports, "renderMarkdownFragment", { enumerable: true, get: function () { return markdown_1.renderMarkdownFragment; } });
 Object.defineProperty(exports, "renderMarkdownValue", { enumerable: true, get: function () { return markdown_1.renderMarkdownValue; } });
 Object.defineProperty(exports, "serializeBlock", { enumerable: true, get: function () { return markdown_1.serializeBlock; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "HttpCookieJar", { enumerable: true, get: function () { return session_1.HttpCookieJar; } });
+Object.defineProperty(exports, "parseCookieHeader", { enumerable: true, get: function () { return session_1.parseCookieHeader; } });
+Object.defineProperty(exports, "requireSessionFromCookie", { enumerable: true, get: function () { return session_1.requireSessionFromCookie; } });
+var error_fragments_1 = require("./error-fragments");
+Object.defineProperty(exports, "renderActionNotAvailableFragment", { enumerable: true, get: function () { return error_fragments_1.renderActionNotAvailableFragment; } });
+Object.defineProperty(exports, "renderAuthRequiredFragment", { enumerable: true, get: function () { return error_fragments_1.renderAuthRequiredFragment; } });
+Object.defineProperty(exports, "renderErrorFragment", { enumerable: true, get: function () { return error_fragments_1.renderErrorFragment; } });
+Object.defineProperty(exports, "renderInternalErrorFragment", { enumerable: true, get: function () { return error_fragments_1.renderInternalErrorFragment; } });
+Object.defineProperty(exports, "renderUnsupportedContentTypeFragment", { enumerable: true, get: function () { return error_fragments_1.renderUnsupportedContentTypeFragment; } });
 var negotiate_1 = require("./negotiate");
 Object.defineProperty(exports, "wantsHtml", { enumerable: true, get: function () { return negotiate_1.wantsHtml; } });
 var action_host_1 = require("./action-host");

package/dist/server/init.js

@@ -29,7 +29,7 @@ function createStarterSite(targetDir) {
             start: "mdsn start",
         },
         dependencies: {
-            "@mdsnai/sdk": "^0.1.0",
+            "@mdsnai/sdk": "^0.2.0",
         },
     }, null, 2) + "\n", "utf8");
     (0, node_fs_1.writeFileSync)(node_path_1.default.join(targetDir, "pages", "index.md"), `---
@@ -42,7 +42,7 @@ description: A runnable MDSN guestbook starter
 
 Start with a working guestbook and reshape it into your own app.
 
-- \`read\` / \`write\` both return Markdown fragments
+- \`GET\` / \`POST\` both return Markdown fragments
 - the Host only replaces the current \`guestbook\` block region
 - page content stays static while the block keeps updating
 
@@ -50,10 +50,10 @@ Start with a working guestbook and reshape it into your own app.
 
 \`\`\`mdsn
 block guestbook {
-  input nickname: text
-  input message!: text
-  read refresh: "/list"
-  write submit: "/post" (nickname, message)
+  INPUT text -> nickname
+  INPUT text required -> message
+  GET "/list" -> refresh
+  POST "/post" (nickname, message) -> submit
 }
 \`\`\`
 `, "utf8");
@@ -130,13 +130,13 @@ module.exports = defineActions({
       const message = String(ctx.inputs.message ?? "").trim();
 
       if (!message) {
-        return {
-          ok: false,
-          errorCode: "EMPTY_MESSAGE",
-          fieldErrors: {
-            message: "Please enter a message.",
-          },
-        };
+        return renderMarkdownFragment({
+          body: [
+            "## Action Status",
+            "Please enter a message before submitting.",
+          ],
+          block: guestbookBlock,
+        });
       }
 
       addGuestbookMessage({ nickname, message });

package/dist/server/markdown.d.ts

@@ -16,27 +16,23 @@ export type SerializableInput = {
     required?: boolean;
     secret?: boolean;
     options?: string[];
-    schema?: string;
 };
 export type SerializableRead = {
-    name: string;
+    name?: string;
     target: string;
     inputs?: string[];
+    accept?: string;
 };
 export type SerializableWrite = {
     name: string;
     target: string;
     inputs?: string[];
 };
-export type SerializableRedirect = {
-    target: string;
-};
 export type SerializableBlock = {
     name: string;
     inputs?: SerializableInput[];
     reads?: SerializableRead[];
     writes?: SerializableWrite[];
-    redirects?: SerializableRedirect[];
 };
 export type RenderMarkdownFragmentOptions = {
     body?: string | string[];

package/dist/server/markdown.js

@@ -14,8 +14,11 @@ function joinBody(body) {
 function escapeTableCell(value) {
     return String(value ?? "").replace(/\|/g, "\\|").replace(/\n/g, "<br />");
 }
-function formatIdentifierList(inputs) {
-    return inputs && inputs.length > 0 ? ` (${inputs.join(", ")})` : "";
+function formatIdentifierList(inputs, options) {
+    if (inputs && inputs.length > 0) {
+        return ` (${inputs.join(", ")})`;
+    }
+    return options?.always ? " ()" : "";
 }
 function renderMarkdownValue(type, value, options) {
     switch (type) {
@@ -45,20 +48,18 @@ function renderMarkdownValue(type, value, options) {
 function serializeBlock(block) {
     const lines = ["```mdsn", `block ${block.name} {`];
     for (const input of block.inputs ?? []) {
-        const requiredMarker = input.required ? "!" : "";
+        const requiredMarker = input.required ? " required" : "";
         const secretMarker = input.secret ? " secret" : "";
         const optionsLiteral = input.options ? ` ${JSON.stringify(input.options)}` : "";
-        const schemaName = input.schema ? ` ${input.schema}` : "";
-        lines.push(`  input ${input.name}${requiredMarker}: ${input.type}${secretMarker}${optionsLiteral}${schemaName}`);
+        lines.push(`  INPUT ${input.type}${requiredMarker}${secretMarker}${optionsLiteral} -> ${input.name}`);
     }
     for (const read of block.reads ?? []) {
-        lines.push(`  read ${read.name}: "${read.target}"${formatIdentifierList(read.inputs)}`);
+        const acceptClause = read.accept ? ` accept:${JSON.stringify(read.accept)}` : "";
+        const nameClause = read.name ? ` -> ${read.name}` : "";
+        lines.push(`  GET "${read.target}"${formatIdentifierList(read.inputs)}${acceptClause}${nameClause}`);
     }
     for (const write of block.writes ?? []) {
-        lines.push(`  write ${write.name}: "${write.target}"${formatIdentifierList(write.inputs)}`);
-    }
-    for (const redirect of block.redirects ?? []) {
-        lines.push(`  redirect "${redirect.target}"`);
+        lines.push(`  POST "${write.target}"${formatIdentifierList(write.inputs, { always: true })} -> ${write.name}`);
     }
     lines.push("}", "```");
     return lines.join("\n");

package/dist/server/server.d.ts

@@ -1,6 +1,7 @@
 import type { Express } from "express";
 import { type CreateFrameworkAppOptions } from "../framework/create-framework-app";
 import { type MdsnConfig } from "./config";
+import { type Logger } from "../core";
 export type CreateFrameworkAppFn = (options: CreateFrameworkAppOptions) => Express;
 export type ListenFn = (options: {
     app: Express;
@@ -8,7 +9,7 @@ export type ListenFn = (options: {
     log: (message: string) => void;
 }) => Promise<void>;
 export type OpenBrowserFn = (url: string) => Promise<void> | void;
-export declare function loadUserConfig(rootDir: string): Promise<MdsnConfig>;
+export declare function loadUserConfig(rootDir: string, logger?: Logger): Promise<MdsnConfig>;
 export declare function loadBuiltConfig(distDir: string): MdsnConfig | null;
 export declare function listenOnPort(options: {
     app: Express;

package/dist/server/server.js

@@ -15,6 +15,7 @@ const create_framework_app_1 = require("../framework/create-framework-app");
 const config_1 = require("./config");
 const dev_1 = require("./dev");
 const module_loader_1 = require("./module-loader");
+const core_1 = require("../core");
 const USER_CONFIG_CANDIDATES = [
     "mdsn.config.cjs",
     "mdsn.config.js",
@@ -33,7 +34,7 @@ function formatConfigLoadError(configPath, error) {
     }
     return new Error(`Failed to load ${node_path_1.default.basename(configPath)}: ${message}`);
 }
-async function loadConfigFromFile(configPath) {
+async function loadConfigFromFile(configPath, logger) {
     const extension = node_path_1.default.extname(configPath).toLowerCase();
     if (extension === ".json") {
         return JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf8"));
@@ -43,20 +44,24 @@ async function loadConfigFromFile(configPath) {
         return (loadedModule.default ?? loadedModule);
     }
     catch (error) {
+        logger.debug("Failed to load config file", { path: configPath });
         throw formatConfigLoadError(configPath, error);
     }
 }
-async function loadUserConfig(rootDir) {
+async function loadUserConfig(rootDir, logger) {
+    const log = logger ?? (0, core_1.createLogger)({ prefix: "config" });
     const availableConfigPaths = USER_CONFIG_CANDIDATES
         .map((name) => node_path_1.default.join(rootDir, name))
         .filter((candidatePath) => (0, node_fs_1.existsSync)(candidatePath));
     if (availableConfigPaths.length === 0) {
+        log.debug("No config file found, using defaults");
         return {};
     }
     const errors = [];
     for (const configPath of availableConfigPaths) {
         try {
-            return await loadConfigFromFile(configPath);
+            log.debug("Loading config file", { path: configPath });
+            return await loadConfigFromFile(configPath, log);
         }
         catch (error) {
             errors.push(error instanceof Error ? error : new Error(String(error)));
@@ -98,12 +103,13 @@ function openBrowser(url) {
     child.unref();
 }
 async function startFrameworkServer(options = {}) {
+    const logger = (0, core_1.createLogger)({ prefix: "server" });
     const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
     const distDir = node_path_1.default.join(cwd, "dist");
     const shouldUseDist = options.mode === "start";
     const builtConfig = shouldUseDist ? loadBuiltConfig(distDir) : null;
     const rootDir = builtConfig ? distDir : cwd;
-    const config = builtConfig ?? await loadUserConfig(rootDir);
+    const config = builtConfig ?? await loadUserConfig(rootDir, logger);
     const resolvedConfig = (0, config_1.resolveConfig)(config);
     const devState = options.mode === "dev" ? (0, dev_1.createDevState)() : undefined;
     const app = (options.createApp ?? create_framework_app_1.createFrameworkApp)({
@@ -128,10 +134,12 @@ async function startFrameworkServer(options = {}) {
                         ? node_path_1.default.join(directoryName, fileName).split(node_path_1.default.sep).join("/")
                         : directoryName;
                     devState.bumpVersion(relativeName);
+                    logger.debug("File changed, bumping version", { file: relativeName });
                 });
+                logger.info("Watching directory for changes", { directory: directoryName });
             }
-            catch {
-                // Ignore watcher setup failures for now; the dev server remains usable without auto-reload.
+            catch (error) {
+                logger.warn("Failed to setup file watcher", { directory: directoryName, error: String(error) });
             }
         }
     }
@@ -144,9 +152,10 @@ async function startFrameworkServer(options = {}) {
     if (options.mode === "dev" && resolvedConfig.dev.openBrowser) {
         try {
             await (options.openBrowser ?? openBrowser)(`http://localhost:${port}`);
+            logger.info("Opening browser", { url: `http://localhost:${port}` });
         }
-        catch {
-            // Keep the dev server usable even if the opener is unavailable.
+        catch (error) {
+            logger.warn("Failed to open browser", { error: String(error) });
         }
     }
 }

package/dist/server/session.d.ts

@@ -0,0 +1,40 @@
+export type HeaderCarrier = {
+    get(name: string): string | null;
+    getSetCookie?: () => string[];
+};
+export declare function parseCookieHeader(cookieHeader: string | undefined): Record<string, string>;
+export declare class HttpCookieJar {
+    private readonly values;
+    constructor(initialValues?: Record<string, string>);
+    get(name: string): string | undefined;
+    set(name: string, value: string): void;
+    delete(name: string): void;
+    clear(): void;
+    toCookieHeader(): string;
+    applyToHeaders(headers?: Record<string, string>): Record<string, string>;
+    ingestSetCookieHeader(setCookieHeader: string | string[] | null | undefined): void;
+    ingestFromResponse(response: {
+        headers: HeaderCarrier;
+    }): void;
+}
+export type SessionGuardSuccess<Session> = {
+    ok: true;
+    cookies: Record<string, string>;
+    sessionId: string;
+    session: Session;
+};
+export type SessionGuardFailure = {
+    ok: false;
+    status: 401;
+    cookies: Record<string, string>;
+    markdown: string;
+};
+export type SessionGuardResult<Session> = SessionGuardSuccess<Session> | SessionGuardFailure;
+export interface RequireSessionFromCookieOptions<Session> {
+    cookieHeader?: string;
+    cookieName: string;
+    resolveSession: (sessionId: string) => Session | null;
+    unauthorizedMarkdown?: string;
+    unauthorizedMessage?: string;
+}
+export declare function requireSessionFromCookie<Session>(options: RequireSessionFromCookieOptions<Session>): SessionGuardResult<Session>;