@dropsh/plugin-markdown 0.5.2

package/LICENSE

@@ -0,0 +1,51 @@
+drupal-cli is dual-licensed. You may use this software under the terms of
+either the MIT License or the GNU General Public License version 2 or any
+later version, at your option.
+
+SPDX-License-Identifier: (MIT OR GPL-2.0-or-later)
+
+================================================================================
+MIT License
+================================================================================
+
+Copyright (c) 2026 Christian Wiedemann
+
+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.
+
+================================================================================
+GNU General Public License, version 2 or later
+================================================================================
+
+The full text of the GNU GPL v2 is available at:
+  https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+
+The full text of any later GPL version is available at:
+  https://www.gnu.org/licenses/
+
+Copyright (C) 2026 Christian Wiedemann
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@dropsh/plugin-markdown",
+  "version": "0.5.2",
+  "type": "module",
+  "main": "./dist/plugins/markdown/src/index.js",
+  "exports": {
+    ".": "./dist/plugins/markdown/src/index.js",
+    "./render": "./dist/plugins/markdown/src/render-md.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "dropsh": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "dropsh": "0.5.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+import type { DropSHPlugin } from "dropsh/plugin";
+import { renderMarkdown } from "./render-md.js";
+
+export { renderMarkdown };
+
+export function markdownPlugin(): DropSHPlugin {
+  return {
+    id: "markdown",
+    requiredModules: [],
+    async extendSchema(_entityType, _bundle, schema) {
+      return schema;
+    },
+    renderers: [{ id: "md", render: renderMarkdown }],
+  };
+}

package/src/render-md.ts

@@ -0,0 +1,80 @@
+import {
+  indexIncluded,
+  type JsonApiDocument,
+  type JsonApiResource,
+  type RenderContext,
+} from "dropsh/plugin";
+
+type Scalar = string | number | boolean;
+
+function isScalar(v: unknown): v is Scalar {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+
+function yamlScalar(v: Scalar): string {
+  if (typeof v === "string") {
+    return v === "" || v.trim() !== v || /[:#\n"'[\]{}]/.test(v) ? JSON.stringify(v) : v;
+  }
+  return String(v);
+}
+
+function isRef(x: unknown): x is { type: string; id: string } {
+  return (
+    !!x &&
+    typeof x === "object" &&
+    typeof (x as { type?: unknown }).type === "string" &&
+    typeof (x as { id?: unknown }).id === "string"
+  );
+}
+
+function relIds(rel: unknown): string[] {
+  if (!rel || typeof rel !== "object") return [];
+  const data = (rel as { data?: unknown }).data;
+  if (Array.isArray(data)) return data.filter(isRef).map((r) => `${r.type}/${r.id}`);
+  if (isRef(data)) return [`${data.type}/${data.id}`];
+  return [];
+}
+
+// Flattens any attribute value to a single-line string for `label: value`
+// output. Text-field objects (`{ processed | value }`) collapse to their text;
+// other objects/arrays fall back to compact JSON.
+function fieldValue(v: unknown): string {
+  if (isScalar(v)) return yamlScalar(v);
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    if (typeof o.processed === "string") return yamlScalar(o.processed);
+    if (typeof o.value === "string") return yamlScalar(o.value);
+    return JSON.stringify(v);
+  }
+  return "";
+}
+
+// Renders a resource as a flat `label: value` list: type/id first, then every
+// attribute, then relationships as `[type/id]` reference lists.
+function renderResource(res: JsonApiResource): string {
+  const lines: string[] = [`type: ${res.type}`, `id: ${res.id}`];
+  for (const [k, v] of Object.entries(res.attributes ?? {})) {
+    lines.push(`${k}: ${fieldValue(v)}`);
+  }
+  for (const [k, v] of Object.entries(res.relationships ?? {})) {
+    const ids = relIds(v);
+    if (ids.length) lines.push(`${k}: [${ids.join(", ")}]`);
+  }
+  return lines.join("\n");
+}
+
+export function renderMarkdown(doc: JsonApiDocument, _ctx: RenderContext): string {
+  const data = doc.data;
+  const primary = Array.isArray(data)
+    ? data.length === 0
+      ? "_(no results)_"
+      : data.map(renderResource).join("\n\n---\n\n")
+    : renderResource(data);
+
+  // Resources pulled in via `--include` are appended under an Included section
+  // so the related entities are visible, not just their reference ids.
+  const included = [...indexIncluded(doc).values()];
+  if (included.length === 0) return primary;
+  const inc = included.map(renderResource).join("\n\n---\n\n");
+  return `${primary}\n\n## Included\n\n${inc}`;
+}

package/tests/unit/render-md.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { renderMarkdown } from "../../src/render-md.js";
+
+const ctx = { command: "read" as const };
+
+describe("renderMarkdown", () => {
+  it("appends an Included section for --include'd resources", () => {
+    const out = renderMarkdown(
+      {
+        data: {
+          type: "node--article",
+          id: "u1",
+          attributes: { title: "Primary" },
+          relationships: { field_related: { data: { type: "node--article", id: "r1" } } },
+        },
+        included: [{ type: "node--article", id: "r1", attributes: { title: "Related One" } }],
+      },
+      ctx,
+    );
+    expect(out).toContain("title: Primary");
+    expect(out).toContain("## Included");
+    expect(out).toContain("id: r1");
+    expect(out).toContain("title: Related One");
+    // primary comes before the included section
+    expect(out.indexOf("title: Primary")).toBeLessThan(out.indexOf("## Included"));
+  });
+
+  it("omits the Included section when there is no included", () => {
+    const out = renderMarkdown(
+      { data: { type: "node--article", id: "u1", attributes: { title: "Solo" } } },
+      ctx,
+    );
+    expect(out).not.toContain("## Included");
+  });
+
+  it("renders every field as label: value", () => {
+    const out = renderMarkdown(
+      {
+        data: {
+          type: "node--article",
+          id: "u1",
+          attributes: { title: "Hello", status: true, body: { value: "The text." } },
+        },
+      },
+      ctx,
+    );
+    expect(out).toContain("type: node--article");
+    expect(out).toContain("id: u1");
+    expect(out).toContain("title: Hello");
+    expect(out).toContain("status: true");
+    // text-field objects collapse to their text, still as label: value
+    expect(out).toContain("body: The text.");
+    // no frontmatter fence
+    expect(out.startsWith("---")).toBe(false);
+  });
+
+  it("does not duplicate any field when there is no body field", () => {
+    const out = renderMarkdown(
+      {
+        data: {
+          type: "node--page",
+          id: "p1",
+          attributes: { title: "T", summary: "short", teaser: "a much longer piece of text here" },
+        },
+      },
+      ctx,
+    );
+    expect(out).toContain("title: T");
+    expect(out).toContain("summary: short");
+    expect(out).toContain("teaser: a much longer piece of text here");
+    // each field appears exactly once (no body-fallback duplication)
+    expect(out.match(/teaser: /g)).toHaveLength(1);
+  });
+
+  it("lists relationships as type/id arrays", () => {
+    const out = renderMarkdown(
+      {
+        data: {
+          type: "node--article",
+          id: "u1",
+          attributes: {},
+          relationships: { uid: { data: { type: "user--user", id: "a1" } } },
+        },
+      },
+      ctx,
+    );
+    expect(out).toContain("uid: [user--user/a1]");
+  });
+
+  it("joins a collection with a separator", () => {
+    const out = renderMarkdown(
+      {
+        data: [
+          { type: "node--article", id: "u1", attributes: { title: "A" } },
+          { type: "node--article", id: "u2", attributes: { title: "B" } },
+        ],
+      },
+      { command: "search" },
+    );
+    expect(out).toContain("id: u1");
+    expect(out).toContain("id: u2");
+    expect(out).toContain("\n\n---\n\n");
+  });
+
+  it("renders an empty collection as a placeholder", () => {
+    expect(renderMarkdown({ data: [] }, { command: "search" })).toBe("_(no results)_");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "noEmit": false
+  },
+  "include": ["src", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "dropsh/plugin": resolve(__dirname, "../../src/plugin-api.ts"),
+    },
+  },
+  test: {
+    include: ["tests/unit/**/*.test.ts"],
+    environment: "node",
+  },
+});