npm - mdx-artifacts - Versions diffs - 0.1.1 → 0.2.0 - Mend

mdx-artifacts 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/dist/lib/cli/dev-server/vite-artifact.js ADDED Viewed

@@ -0,0 +1,415 @@
+import mdx from "@mdx-js/rollup";
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer, build as viteBuild } from "vite";
+import { createArtifactMeta, createArtifactRoute, readArtifactState, writeArtifactState } from "../state/artifact-state.js";
+import { addInteractionItemService, promoteInteractionService, removeInteractionItemService, resetInteractionService, setInteractionOrderService, updateInteractionItemService } from "../services/interaction-service.js";
+const packageCliDir = path.dirname(fileURLToPath(import.meta.url));
+const defaultStylesPath = path.resolve(packageCliDir, "../../react/styles.css");
+export async function createArtifactProject(projectRoot, mdxPath, config) {
+    const tmpDir = path.join(projectRoot, ".mdx-artifacts", "tmp", randomUUID());
+    const artifact = createArtifactRoute(projectRoot, mdxPath, config.docsDir);
+    const srcDir = path.join(tmpDir, "src");
+    const distDir = path.join(tmpDir, "dist");
+    const entryPath = path.join(srcDir, "entry.tsx");
+    const tailwindSourcePath = path.join(srcDir, "artifact-tailwind-sources.css");
+    const mdxImport = toRelativeImport(entryPath, mdxPath);
+    const styleImports = createStyleImports(projectRoot, entryPath, config, tailwindSourcePath);
+    const reactEntryPath = await resolveReactEntryPath();
+    const reactEntryImport = toRelativeImport(entryPath, reactEntryPath);
+    const reactAliases = resolveReactAliases(projectRoot);
+    await mkdir(srcDir, { recursive: true });
+    await writeFile(tailwindSourcePath, createTailwindSourceCss(projectRoot, tailwindSourcePath, mdxPath, config));
+    await writeFile(path.join(tmpDir, "index.html"), `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MDX Artifact</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/entry.tsx"></script>
+  </body>
+</html>
+`);
+    await writeFile(entryPath, `import React from "react";
+import { createRoot } from "react-dom/client";
+import { ArtifactStateProvider, CommentLayer, artifactMdxComponents } from "${reactEntryImport}";
+import Doc from "${mdxImport}";
+${styleImports}
+function App() {
+  return (
+    <main className="ak-shell">
+      <article className="ak-document">
+        <ArtifactStateProvider>
+          <CommentLayer>
+            <Doc components={artifactMdxComponents} />
+          </CommentLayer>
+        </ArtifactStateProvider>
+      </article>
+    </main>
+  );
+}
+createRoot(document.getElementById("root")!).render(<App />);
+`);
+    const viteConfig = {
+        root: tmpDir,
+        logLevel: "warn",
+        plugins: [artifactStatePlugin(projectRoot, artifact), react(), mdx(), tailwindcss()],
+        resolve: {
+            alias: [
+                ...reactAliases,
+                { find: /^mdx-artifacts\/react$/, replacement: reactEntryPath },
+                { find: /^mdx-artifacts$/, replacement: reactEntryPath }
+            ],
+            dedupe: ["react", "react-dom"]
+        },
+        optimizeDeps: {
+            exclude: ["mdx-artifacts", "mdx-artifacts/react"]
+        },
+        server: {
+            port: config.port,
+            fs: {
+                allow: [projectRoot]
+            }
+        },
+        build: {
+            outDir: distDir,
+            emptyOutDir: true,
+            cssCodeSplit: false,
+            assetsInlineLimit: Number.MAX_SAFE_INTEGER,
+            rollupOptions: {
+                input: path.join(tmpDir, "index.html")
+            }
+        }
+    };
+    return {
+        artifact,
+        tmpDir,
+        distDir,
+        config: viteConfig,
+        cleanup: () => rm(tmpDir, { recursive: true, force: true })
+    };
+}
+function artifactStatePlugin(projectRoot, artifact) {
+    return {
+        name: "mdx-artifacts-state",
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                const requestUrl = new URL(request.url ?? "/", "http://localhost");
+                try {
+                    if (requestUrl.pathname === "/__artifact/meta") {
+                        await handleArtifactMeta(projectRoot, artifact, request, response);
+                        return;
+                    }
+                    if (requestUrl.pathname === "/__artifact/state") {
+                        await handleArtifactState(projectRoot, artifact, request, response);
+                        return;
+                    }
+                    if (requestUrl.pathname.startsWith("/__artifact/interactions/")) {
+                        await handleArtifactInteraction(projectRoot, artifact, requestUrl.pathname, request, response);
+                        return;
+                    }
+                }
+                catch (error) {
+                    sendJson(response, 500, {
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                    return;
+                }
+                next();
+            });
+        }
+    };
+}
+async function handleArtifactMeta(projectRoot, artifact, request, response) {
+    if (request.method !== "GET") {
+        sendJson(response, 405, { error: "Method not allowed." });
+        return;
+    }
+    sendJson(response, 200, await createArtifactMeta(projectRoot, artifact));
+}
+async function handleArtifactState(projectRoot, artifact, request, response) {
+    if (request.method === "GET") {
+        sendJson(response, 200, await readArtifactState(artifact));
+        return;
+    }
+    if (request.method === "POST") {
+        let value;
+        try {
+            value = JSON.parse(await readRequestBody(request));
+        }
+        catch {
+            sendJson(response, 400, { error: "Request body must be valid JSON." });
+            return;
+        }
+        const state = await writeArtifactState(projectRoot, artifact, value);
+        sendJson(response, 200, { ok: true, state });
+        return;
+    }
+    sendJson(response, 405, { error: "Method not allowed." });
+}
+async function handleArtifactInteraction(projectRoot, artifact, pathname, request, response) {
+    if (request.method !== "POST") {
+        sendJson(response, 405, { error: "Method not allowed." });
+        return;
+    }
+    let value;
+    try {
+        value = JSON.parse(await readRequestBody(request));
+    }
+    catch {
+        sendJson(response, 400, { error: "Request body must be valid JSON." });
+        return;
+    }
+    try {
+        if (pathname === "/__artifact/interactions/set-order") {
+            const body = parseSetOrderRequest(value);
+            const result = await setInteractionOrderService(projectRoot, artifact.sourceRelativePath, body.id, body.orderedIds);
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+        if (pathname === "/__artifact/interactions/reset") {
+            const body = parseInteractionIdRequest(value, "reset");
+            const result = await resetInteractionService(projectRoot, artifact.sourceRelativePath, body.id);
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+        if (pathname === "/__artifact/interactions/promote") {
+            const body = parseInteractionIdRequest(value, "promote");
+            const result = await promoteInteractionService(projectRoot, artifact.sourceRelativePath, body.id);
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+        if (pathname === "/__artifact/interactions/add-item") {
+            const body = parseAddItemRequest(value);
+            const result = await addInteractionItemService(projectRoot, artifact.sourceRelativePath, body.id, body.item, {
+                afterId: body.afterId
+            });
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+        if (pathname === "/__artifact/interactions/remove-item") {
+            const body = parseItemIdRequest(value, "remove-item");
+            const result = await removeInteractionItemService(projectRoot, artifact.sourceRelativePath, body.id, body.itemId);
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+        if (pathname === "/__artifact/interactions/update-item") {
+            const body = parseUpdateItemRequest(value);
+            const result = await updateInteractionItemService(projectRoot, artifact.sourceRelativePath, body.id, body.itemId, body.patch);
+            sendJson(response, 200, { ok: true, result, state: result.state });
+            return;
+        }
+    }
+    catch (error) {
+        sendJson(response, 400, { error: error instanceof Error ? error.message : String(error) });
+        return;
+    }
+    sendJson(response, 404, { error: "Interaction endpoint not found." });
+}
+function parseAddItemRequest(value) {
+    const body = parseInteractionIdRequest(value, "add-item");
+    if (!isRecord(value) || !isRecord(value.item)) {
+        throw new Error("interactions add-item requires item.");
+    }
+    if (typeof value.item.id !== "string" || !value.item.id) {
+        throw new Error("interactions add-item requires item.id.");
+    }
+    if (typeof value.item.title !== "string" || !value.item.title) {
+        throw new Error("interactions add-item requires item.title.");
+    }
+    return {
+        id: body.id,
+        item: normalizeItem(value.item),
+        afterId: typeof value.afterId === "string" && value.afterId ? value.afterId : undefined
+    };
+}
+function parseUpdateItemRequest(value) {
+    const body = parseItemIdRequest(value, "update-item");
+    if (!isRecord(value) || !isRecord(value.patch)) {
+        throw new Error("interactions update-item requires patch.");
+    }
+    return {
+        id: body.id,
+        itemId: body.itemId,
+        patch: normalizeItemPatch(value.patch)
+    };
+}
+function parseItemIdRequest(value, action) {
+    const body = parseInteractionIdRequest(value, action);
+    if (!isRecord(value) || typeof value.itemId !== "string" || !value.itemId) {
+        throw new Error(`interactions ${action} requires itemId.`);
+    }
+    return {
+        id: body.id,
+        itemId: value.itemId
+    };
+}
+function parseSetOrderRequest(value) {
+    const body = parseInteractionIdRequest(value, "set-order");
+    if (!isRecord(value) || !Array.isArray(value.orderedIds)) {
+        throw new Error("interactions set-order requires orderedIds.");
+    }
+    const orderedIds = value.orderedIds.filter((itemId) => typeof itemId === "string");
+    if (orderedIds.length !== value.orderedIds.length || orderedIds.length === 0) {
+        throw new Error("interactions set-order requires non-empty string orderedIds.");
+    }
+    return {
+        id: body.id,
+        orderedIds
+    };
+}
+function normalizeItem(value) {
+    return {
+        id: value.id,
+        title: value.title,
+        ...normalizeItemPatch(value)
+    };
+}
+function normalizeItemPatch(value) {
+    return {
+        ...(typeof value.title === "string" ? { title: value.title } : {}),
+        ...("summary" in value ? { summary: typeof value.summary === "string" ? value.summary : undefined } : {}),
+        ...("badge" in value ? { badge: typeof value.badge === "string" ? value.badge : undefined } : {}),
+        ...("tags" in value
+            ? { tags: Array.isArray(value.tags) ? value.tags.filter((tag) => typeof tag === "string") : undefined }
+            : {}),
+        ...(typeof value.disabled === "boolean" ? { disabled: value.disabled } : {})
+    };
+}
+function parseInteractionIdRequest(value, action) {
+    if (!isRecord(value) || typeof value.id !== "string" || !value.id) {
+        throw new Error(`interactions ${action} requires id.`);
+    }
+    return {
+        id: value.id
+    };
+}
+function readRequestBody(request) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        request.setEncoding("utf8");
+        request.on("data", (chunk) => {
+            body += chunk;
+        });
+        request.on("end", () => resolve(body));
+        request.on("error", reject);
+    });
+}
+function sendJson(response, statusCode, value) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(value, null, 2));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function resolveReactEntryPath() {
+    const builtEntryPath = path.resolve(packageCliDir, "../../react/index.js");
+    const sourceEntryPath = path.resolve(packageCliDir, "../../react/index.ts");
+    try {
+        await access(builtEntryPath);
+        return builtEntryPath;
+    }
+    catch {
+        return sourceEntryPath;
+    }
+}
+function resolveReactAliases(projectRoot) {
+    const projectRequire = createRequire(path.join(projectRoot, "package.json"));
+    const packageRequire = createRequire(import.meta.url);
+    return [
+        { find: /^react$/, replacement: resolveFromProjectOrPackage(projectRequire, packageRequire, "react") },
+        {
+            find: /^react\/jsx-runtime$/,
+            replacement: resolveFromProjectOrPackage(projectRequire, packageRequire, "react/jsx-runtime")
+        },
+        {
+            find: /^react\/jsx-dev-runtime$/,
+            replacement: resolveFromProjectOrPackage(projectRequire, packageRequire, "react/jsx-dev-runtime")
+        },
+        { find: /^react-dom$/, replacement: resolveFromProjectOrPackage(projectRequire, packageRequire, "react-dom") },
+        {
+            find: /^react-dom\/client$/,
+            replacement: resolveFromProjectOrPackage(projectRequire, packageRequire, "react-dom/client")
+        }
+    ];
+}
+function resolveFromProjectOrPackage(projectRequire, packageRequire, specifier) {
+    try {
+        return projectRequire.resolve(specifier);
+    }
+    catch {
+        return packageRequire.resolve(specifier);
+    }
+}
+export async function startDevServer(project) {
+    const server = await createServer(project.config);
+    await server.listen();
+    return server;
+}
+export async function buildArtifact(project) {
+    await viteBuild(project.config);
+    return inlineBuildAssets(project.distDir);
+}
+async function inlineBuildAssets(distDir) {
+    const htmlPath = path.join(distDir, "index.html");
+    let html = await readFile(htmlPath, "utf8");
+    html = await replaceAsync(html, /<link rel="stylesheet" crossorigin href="([^"]+)">/g, async (_match, href) => {
+        const css = await readFile(assetPath(distDir, href), "utf8");
+        return `<style>${css}</style>`;
+    });
+    html = await replaceAsync(html, /<script type="module" crossorigin src="([^"]+)"><\/script>/g, async (_match, src) => {
+        const js = await readFile(assetPath(distDir, src), "utf8");
+        return `<script type="module">${escapeScriptContent(js)}</script>`;
+    });
+    return html;
+}
+function assetPath(distDir, value) {
+    return path.join(distDir, value.replace(/^\//, ""));
+}
+function toRelativeImport(fromFile, targetFile) {
+    const relative = path.relative(path.dirname(fromFile), targetFile).replaceAll(path.sep, "/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function createStyleImports(projectRoot, entryPath, config, tailwindSourcePath) {
+    const styles = [
+        tailwindSourcePath,
+        ...(config.includeDefaultStyles ? [defaultStylesPath] : []),
+        ...config.styles.map((stylePath) => path.resolve(projectRoot, stylePath))
+    ];
+    return styles.map((stylePath) => `import "${toRelativeImport(entryPath, stylePath)}";`).join("\n");
+}
+function createTailwindSourceCss(projectRoot, sourceStylesPath, mdxPath, config) {
+    const sources = [
+        mdxPath,
+        ...config.tailwindSources.map((sourcePath) => path.resolve(projectRoot, sourcePath))
+    ];
+    return `@import "tailwindcss";\n${sources
+        .map((sourcePath) => `@source "${escapeCssString(toRelativeImport(sourceStylesPath, sourcePath))}";`)
+        .join("\n")}\n`;
+}
+function escapeCssString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+async function replaceAsync(source, pattern, replacer) {
+    const matches = Array.from(source.matchAll(pattern));
+    let output = source;
+    for (const match of matches) {
+        const replacement = await replacer(match[0], ...match.slice(1));
+        output = output.replace(match[0], () => replacement);
+    }
+    return output;
+}
+function escapeScriptContent(source) {
+    return source.replace(/<\/script/gi, "<\\/script");
+}

package/dist/lib/cli/diagnostics/diagnostics.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+export type ArtifactDiagnostic = {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    sourcePath: string;
+    line?: number;
+    componentName?: string;
+    propName?: string;
+    suggestion?: string;
+    example?: string;
+};

package/dist/lib/cli/diagnostics/diagnostics.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/lib/cli/index.js CHANGED Viewed

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { buildCommand } from "./build.js";
-import { componentsCommand } from "./components.js";
-import { devCommand } from "./dev.js";
-import { reviewCommand } from "./review.js";
-import { initProject } from "./scaffold.js";
-import { printValidationResult, validateMdx } from "./validate.js";
+import { buildCommand } from "./commands/build.js";
+import { componentsCommand } from "./commands/components.js";
+import { devCommand } from "./commands/dev.js";
+import { interactionsCommand } from "./commands/interactions.js";
+import { reviewCommand } from "./commands/review.js";
+import { initProject, parseInitOptions } from "./commands/scaffold.js";
+import { formatValidationJson, printValidationResult, validateMdx } from "./commands/validate.js";
+import { loadConfig } from "./config/config.js";
 const projectRoot = process.cwd();
 const [command, input] = process.argv.slice(2);
 async function main() {
@@ -14,7 +16,7 @@ async function main() {
         return;
     }
     if (command === "init") {
-        await initProject(projectRoot);
+        await initProject(projectRoot, await parseInitOptions(process.argv.slice(3)));
         return;
     }
     if (command === "components") {
@@ -28,12 +30,24 @@ async function main() {
         await reviewCommand(projectRoot, process.argv.slice(3));
         return;
     }
+    if (command === "interactions") {
+        await interactionsCommand(projectRoot, process.argv.slice(3));
+        return;
+    }
     if (!input) {
         throw new Error(`${command} requires a .mdx file path.`);
     }
     if (command === "validate") {
-        const result = await validateMdx(path.resolve(projectRoot, input));
-        printValidationResult(result);
+        const args = process.argv.slice(3);
+        const json = args.includes("--json");
+        const config = await loadConfig(projectRoot);
+        const result = await validateMdx(path.resolve(projectRoot, input), { projectRoot, config });
+        if (json) {
+            console.log(JSON.stringify(formatValidationJson(result), null, 2));
+        }
+        else {
+            printValidationResult(result);
+        }
         if (result.errors.length > 0) {
             process.exitCode = 1;
         }
@@ -50,17 +64,24 @@ async function main() {
     throw new Error(`Unknown command: ${command}`);
 }
 function printHelp() {
-    console.log(`artifact-kit
+    console.log(`mdx-artifacts
 Usage:
-  artifact-kit init
-  artifact-kit components [ComponentName] [--json]
-  artifact-kit validate <file.mdx>
-  artifact-kit review add <file.mdx> --anchor <anchorId> --body <message> [--title <title>]
-  artifact-kit review reply <file.mdx> --thread <threadId> --body <message> [...repeat] [--status <status>]
-  artifact-kit review validate <file.mdx>
-  artifact-kit dev <file.mdx>
-  artifact-kit build <file.mdx>
+  mdx-artifacts init [--yes] [--docs-dir <dir>] [--components-dir <dir>] [--agent <generic|codex|claude-code|cursor|all>]
+  mdx-artifacts components [ComponentName] [--json]
+  mdx-artifacts validate <file.mdx> [--json]
+  mdx-artifacts interactions inspect <file.mdx> <id> [--json]
+  mdx-artifacts interactions set-order <file.mdx> <id> --ordered-ids <id> [...id]
+  mdx-artifacts interactions reset <file.mdx> <id>
+  mdx-artifacts interactions promote <file.mdx> <id>
+  mdx-artifacts interactions add-item <file.mdx> <id> --item-id <id> --title <title> [--summary <text>] [--badge <text>] [--tags <tag,tag>] [--disabled true|false] [--after <itemId>]
+  mdx-artifacts interactions remove-item <file.mdx> <id> --item-id <id>
+  mdx-artifacts interactions update-item <file.mdx> <id> --item-id <id> [--title <title>] [--summary <text>] [--badge <text>] [--tags <tag,tag>] [--disabled true|false]
+  mdx-artifacts review add <file.mdx> --anchor <anchorId> --body <message> [--title <title>]
+  mdx-artifacts review reply <file.mdx> --thread <threadId> --body <message> [...repeat] [--status <status>]
+  mdx-artifacts review validate <file.mdx>
+  mdx-artifacts dev <file.mdx>
+  mdx-artifacts build <file.mdx>
 `);
 }
 main().catch((error) => {

package/dist/lib/cli/mdx/sortable-list.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import type { SortableListItem } from "../../react";
+export type SortableListSeed = {
+    id: string;
+    title: string;
+    summary?: string;
+    items: SortableListItem[];
+};
+export declare function extractSortableListSeeds(source: string): SortableListSeed[];
+export declare function promoteSortableListOrder(source: string, listId: string, orderedIds: string[]): string;
+export declare function addSortableListItem(source: string, listId: string, item: SortableListItem, options?: {
+    afterId?: string;
+}): string;
+export declare function removeSortableListItem(source: string, listId: string, itemId: string): string;
+export declare function updateSortableListItem(source: string, listId: string, itemId: string, patch: Partial<Omit<SortableListItem, "id">>): string;