fantsec-docmost-cli 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moritz Krause
+
+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,137 @@
+[![CI](https://github.com/dapi/docmost-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dapi/docmost-cli/actions/workflows/ci.yml)
+
+# Docmost CLI + MCP Server
+
+A Docmost CLI plus standard stdio and HTTP Model Context Protocol (MCP) servers for [Docmost](https://docmost.com/), enabling AI agents to search, create, modify, and organize documentation pages and spaces.
+
+## Features
+
+### Core Management
+
+- **`create_page`**: Smart creation tool. Creates content (via import) AND handles hierarchy (nesting under a parent) in one go.
+- **`update_page`**: Update a page's content and/or title. Updates are performed via real-time collaboration (WebSocket).
+- **`delete_page` / `delete_pages`**: Delete single or multiple pages at once.
+- **`move_page`**: Organize pages hierarchically by moving them to a new parent or root.
+
+### Exploration & Retrieval
+
+- **`search`**: Full-text search across spaces with optional space filtering (`query`, `spaceId`).
+- **`get_workspace`**: Get information about the current Docmost workspace.
+- **`list_spaces`**: View all spaces within the current workspace.
+- **`list_groups`**: View all groups within the current workspace.
+- **`list_pages`**: List pages within a space (ordered by `updatedAt` descending).
+- **`get_page`**: Retrieve full content and metadata of a specific page.
+
+### Technical Details
+
+- **Standard MCP over stdio**: Ships a dedicated `docmost-mcp` executable for Codex, Claude Desktop, and other MCP clients.
+- **Automatic tool generation**: Every supported CLI command is exposed as an MCP tool with JSON schema derived from Commander options.
+- **Automatic Markdown Conversion**: Page content is automatically converted from Docmost's internal ProseMirror/TipTap JSON format to clean Markdown for easy agent consumption. Supports all Docmost extensions including callouts, task lists, math blocks, embeds, and more.
+- **Smart Import API**: Uses Docmost's import API to ensure clean Markdown-to-ProseMirror conversion when creating pages.
+- **Child Preservation**: The `update_page` tool creates a new page ID but effectively simulates an in-place update by reparenting existing child pages to the new version.
+- **Pagination Support**: Automatically handles pagination for large datasets (spaces, pages, groups).
+- **Filtered Responses**: API responses are filtered to include only relevant information, optimizing data transfer for agents.
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g fantsec-docmost-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/youngwawapro/docmost-cli.git
+cd docmost-cli
+npm install
+npm run build
+```
+
+## Configuration
+
+The CLI and MCP server use the same environment variables:
+
+- `DOCMOST_API_URL`: The full URL to your Docmost API (e.g., `https://docs.example.com/api`).
+- `DOCMOST_EMAIL`: The email address for authentication.
+- `DOCMOST_PASSWORD`: The password for authentication.
+
+For remote HTTP MCP mode, set `DOCMOST_API_URL` on the server and send user credentials in the bearer token:
+
+- `Authorization: Bearer <docmost-api-token>`
+- `Authorization: Bearer <email>:<password>`
+
+## Usage with Codex / MCP Clients
+
+### Codex
+
+Add the server directly with `codex mcp add`:
+
+```bash
+codex mcp add docmost \
+  --env DOCMOST_API_URL=http://localhost:3000/api \
+  --env DOCMOST_EMAIL=test@docmost.com \
+  --env DOCMOST_PASSWORD=test \
+  -- npx -y -p fantsec-docmost-cli docmost-mcp
+```
+
+### Generic MCP config
+
+If your MCP client uses a JSON config file, point it at the dedicated `docmost-mcp` executable:
+
+#### Using `npx`
+
+```json
+{
+  "mcpServers": {
+    "docmost": {
+      "command": "npx",
+      "args": ["-y", "-p", "fantsec-docmost-cli", "docmost-mcp"],
+      "env": {
+        "DOCMOST_API_URL": "http://localhost:3000/api",
+        "DOCMOST_EMAIL": "test@docmost.com",
+        "DOCMOST_PASSWORD": "test"
+      }
+    }
+  }
+}
+```
+
+#### Using local build
+
+```json
+{
+  "mcpServers": {
+    "docmost": {
+      "command": "node",
+      "args": ["./build/mcp.js"],
+      "env": {
+        "DOCMOST_API_URL": "http://localhost:3000/api",
+        "DOCMOST_EMAIL": "test@docmost.com",
+        "DOCMOST_PASSWORD": "test"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Watch mode
+npm run watch
+
+# Build
+npm run build
+
+# Start stdio MCP server
+npm run start:mcp
+
+# Start HTTP MCP server
+npm run start:mcp:http
+```
+
+## License
+
+MIT

package/build/__tests__/cli-utils.test.js

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { AxiosError, AxiosHeaders } from "axios";
+import { CommanderError } from "commander";
+const { normalizeOutputFormat, resolveOptions, normalizeError, flattenForTable, toTableRows, parseCommaSeparatedIds, CliError, EXIT_CODES, isCommanderHelpExit, } = await import("../lib/cli-utils.js");
+// ── normalizeOutputFormat ────────────────────────────────────────────
+describe("normalizeOutputFormat", () => {
+    it.each(["json", "table", "text"])("accepts '%s'", (fmt) => {
+        expect(normalizeOutputFormat(fmt)).toBe(fmt);
+    });
+    it("is case insensitive", () => {
+        expect(normalizeOutputFormat("JSON")).toBe("json");
+        expect(normalizeOutputFormat("Table")).toBe("table");
+        expect(normalizeOutputFormat("TEXT")).toBe("text");
+    });
+    it("defaults to json when undefined", () => {
+        expect(normalizeOutputFormat(undefined)).toBe("json");
+    });
+    it("throws VALIDATION_ERROR for invalid format", () => {
+        expect(() => normalizeOutputFormat("csv")).toThrow(CliError);
+        try {
+            normalizeOutputFormat("csv");
+        }
+        catch (e) {
+            expect(e.code).toBe("VALIDATION_ERROR");
+        }
+    });
+});
+// ── resolveOptions ───────────────────────────────────────────────────
+describe("resolveOptions", () => {
+    const savedEnv = {};
+    beforeEach(() => {
+        for (const key of [
+            "DOCMOST_API_URL",
+            "DOCMOST_TOKEN",
+            "DOCMOST_EMAIL",
+            "DOCMOST_PASSWORD",
+        ]) {
+            savedEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+    });
+    afterEach(() => {
+        for (const [key, value] of Object.entries(savedEnv)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    });
+    it("throws when apiUrl is missing", () => {
+        expect(() => resolveOptions({})).toThrow(CliError);
+        expect(() => resolveOptions({})).toThrow(/API URL is required/);
+    });
+    it("reads apiUrl from env", () => {
+        process.env.DOCMOST_API_URL = "http://env-url";
+        process.env.DOCMOST_TOKEN = "tok";
+        const opts = resolveOptions({});
+        expect(opts.apiUrl).toBe("http://env-url");
+    });
+    it("throws when requireAuth=true and no auth provided", () => {
+        expect(() => resolveOptions({ apiUrl: "http://x" })).toThrow(/Authentication is required/);
+    });
+    it("skips auth check when requireAuth=false", () => {
+        const opts = resolveOptions({ apiUrl: "http://x" }, { requireAuth: false });
+        expect(opts.apiUrl).toBe("http://x");
+    });
+    it("accepts token auth", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", token: "t1" });
+        expect(opts.auth).toEqual({ token: "t1" });
+    });
+    it("accepts email/password auth", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", email: "a@b", password: "p" });
+        expect(opts.auth).toEqual({ email: "a@b", password: "p" });
+    });
+    it("token takes precedence over email/password", () => {
+        const opts = resolveOptions({
+            apiUrl: "http://x",
+            token: "tok",
+            email: "a@b",
+            password: "p",
+        });
+        expect(opts.auth).toEqual({ token: "tok" });
+    });
+    it("clamps limit below 1 to 1", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", token: "t", limit: "0" });
+        expect(opts.limit).toBe(1);
+    });
+    it("clamps limit above 100 to 100", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", token: "t", limit: "999" });
+        expect(opts.limit).toBe(100);
+    });
+    it("defaults limit to 100", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", token: "t" });
+        expect(opts.limit).toBe(100);
+    });
+    it("maxItems defaults to Infinity when 0 or not set", () => {
+        const opts1 = resolveOptions({ apiUrl: "http://x", token: "t" });
+        expect(opts1.maxItems).toBe(Infinity);
+        const opts2 = resolveOptions({ apiUrl: "http://x", token: "t", maxItems: "0" });
+        expect(opts2.maxItems).toBe(Infinity);
+    });
+    it("maxItems set to positive value", () => {
+        const opts = resolveOptions({ apiUrl: "http://x", token: "t", maxItems: "50" });
+        expect(opts.maxItems).toBe(50);
+    });
+    it("throws on invalid limit", () => {
+        expect(() => resolveOptions({ apiUrl: "http://x", token: "t", limit: "abc" })).toThrow(/Invalid --limit/);
+    });
+    it("throws on invalid maxItems", () => {
+        expect(() => resolveOptions({ apiUrl: "http://x", token: "t", maxItems: "abc" })).toThrow(/Invalid --max-items/);
+    });
+});
+// ── normalizeError ───────────────────────────────────────────────────
+describe("normalizeError", () => {
+    it("passes CliError through unchanged", () => {
+        const err = new CliError("NOT_FOUND", "gone");
+        expect(normalizeError(err)).toBe(err);
+    });
+    it("converts CommanderError to VALIDATION_ERROR", () => {
+        const err = new CommanderError(1, "commander.missingArgument", "missing arg");
+        const result = normalizeError(err);
+        expect(result).toBeInstanceOf(CliError);
+        expect(result.code).toBe("VALIDATION_ERROR");
+    });
+    it.each([401, 403])("converts AxiosError %d to AUTH_ERROR", (status) => {
+        const err = new AxiosError("fail", "ERR", undefined, undefined, {
+            status,
+            data: {},
+            statusText: "",
+            headers: {},
+            config: { headers: new AxiosHeaders() },
+        });
+        expect(normalizeError(err).code).toBe("AUTH_ERROR");
+    });
+    it("converts AxiosError 404 to NOT_FOUND", () => {
+        const err = new AxiosError("fail", "ERR", undefined, undefined, {
+            status: 404,
+            data: {},
+            statusText: "",
+            headers: {},
+            config: { headers: new AxiosHeaders() },
+        });
+        expect(normalizeError(err).code).toBe("NOT_FOUND");
+    });
+    it.each([400, 422])("converts AxiosError %d to VALIDATION_ERROR", (status) => {
+        const err = new AxiosError("fail", "ERR", undefined, undefined, {
+            status,
+            data: {},
+            statusText: "",
+            headers: {},
+            config: { headers: new AxiosHeaders() },
+        });
+        expect(normalizeError(err).code).toBe("VALIDATION_ERROR");
+    });
+    it("converts AxiosError without response to NETWORK_ERROR", () => {
+        const err = new AxiosError("timeout", "ECONNABORTED");
+        expect(normalizeError(err).code).toBe("NETWORK_ERROR");
+    });
+    it("converts plain Error to INTERNAL_ERROR", () => {
+        const result = normalizeError(new Error("boom"));
+        expect(result.code).toBe("INTERNAL_ERROR");
+        expect(result.message).toBe("boom");
+    });
+    it("converts unknown value to INTERNAL_ERROR", () => {
+        const result = normalizeError("string-error");
+        expect(result.code).toBe("INTERNAL_ERROR");
+        expect(result.message).toBe("Unknown error");
+    });
+    it("converts AxiosError with response message from data", () => {
+        const err = new AxiosError("generic", "ERR", undefined, undefined, {
+            status: 404,
+            data: { message: "Page not found" },
+            statusText: "",
+            headers: {},
+            config: { headers: new AxiosHeaders() },
+        });
+        const result = normalizeError(err);
+        expect(result.message).toBe("Page not found");
+    });
+});
+// ── flattenForTable ──────────────────────────────────────────────────
+describe("flattenForTable", () => {
+    it("wraps primitives in { value }", () => {
+        expect(flattenForTable(42)).toEqual({ value: 42 });
+        expect(flattenForTable("hello")).toEqual({ value: "hello" });
+        expect(flattenForTable(true)).toEqual({ value: true });
+    });
+    it("handles null", () => {
+        expect(flattenForTable(null)).toEqual({ value: null });
+    });
+    it("passes through primitive object values", () => {
+        expect(flattenForTable({ a: 1, b: "x", c: null, d: true })).toEqual({
+            a: 1,
+            b: "x",
+            c: null,
+            d: true,
+        });
+    });
+    it("joins primitive arrays with comma", () => {
+        expect(flattenForTable({ tags: ["a", "b", "c"] })).toEqual({
+            tags: "a, b, c",
+        });
+    });
+    it("stringifies non-primitive arrays", () => {
+        const result = flattenForTable({ items: [{ id: 1 }] });
+        expect(result.items).toBe(JSON.stringify([{ id: 1 }]));
+    });
+    it("stringifies nested objects", () => {
+        const result = flattenForTable({ nested: { x: 1 } });
+        expect(result.nested).toBe(JSON.stringify({ x: 1 }));
+    });
+});
+// ── toTableRows ──────────────────────────────────────────────────────
+describe("toTableRows", () => {
+    it("handles array input", () => {
+        const rows = toTableRows([{ id: 1 }, { id: 2 }]);
+        expect(rows).toHaveLength(2);
+        expect(rows[0]).toEqual({ id: 1 });
+    });
+    it("handles object with items", () => {
+        const rows = toTableRows({ items: [{ id: 1 }] });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toEqual({ id: 1 });
+    });
+    it("handles nested data.items", () => {
+        const rows = toTableRows({ data: { items: [{ id: 1 }] } });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toEqual({ id: 1 });
+    });
+    it("falls back to single object row", () => {
+        const rows = toTableRows({ name: "test" });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toEqual({ name: "test" });
+    });
+});
+// ── parseCommaSeparatedIds ───────────────────────────────────────────
+describe("parseCommaSeparatedIds", () => {
+    it("parses normal CSV", () => {
+        expect(parseCommaSeparatedIds("--ids", "a,b,c")).toEqual(["a", "b", "c"]);
+    });
+    it("trims whitespace", () => {
+        expect(parseCommaSeparatedIds("--ids", " a , b , c ")).toEqual(["a", "b", "c"]);
+    });
+    it("throws on empty string", () => {
+        expect(() => parseCommaSeparatedIds("--ids", "")).toThrow(CliError);
+        expect(() => parseCommaSeparatedIds("--ids", "")).toThrow(/must not be empty/);
+    });
+    it("throws on whitespace-only input", () => {
+        expect(() => parseCommaSeparatedIds("--ids", " , , ")).toThrow(/must not be empty/);
+    });
+});
+// ── CliError ─────────────────────────────────────────────────────────
+describe("CliError", () => {
+    it.each(Object.entries(EXIT_CODES))("sets exitCode %d for code %s", (code, exitCode) => {
+        const err = new CliError(code, "msg");
+        expect(err.exitCode).toBe(exitCode);
+    });
+    it("stores details", () => {
+        const err = new CliError("NOT_FOUND", "gone", { id: "x" });
+        expect(err.details).toEqual({ id: "x" });
+    });
+    it("is an instance of Error", () => {
+        expect(new CliError("INTERNAL_ERROR", "x")).toBeInstanceOf(Error);
+    });
+});
+// ── isCommanderHelpExit ──────────────────────────────────────────────
+describe("isCommanderHelpExit", () => {
+    it("returns true for commander.helpDisplayed", () => {
+        expect(isCommanderHelpExit(new CommanderError(0, "commander.helpDisplayed", ""))).toBe(true);
+    });
+    it("returns true for commander.help", () => {
+        expect(isCommanderHelpExit(new CommanderError(0, "commander.help", ""))).toBe(true);
+    });
+    it("returns true for commander.version", () => {
+        expect(isCommanderHelpExit(new CommanderError(0, "commander.version", ""))).toBe(true);
+    });
+    it("returns true for (outputHelp) message", () => {
+        expect(isCommanderHelpExit(new CommanderError(0, "other", "(outputHelp)"))).toBe(true);
+    });
+    it("returns false for other CommanderError codes", () => {
+        expect(isCommanderHelpExit(new CommanderError(1, "commander.missingArgument", "x"))).toBe(false);
+    });
+    it("returns false for non-CommanderError", () => {
+        expect(isCommanderHelpExit(new Error("help"))).toBe(false);
+        expect(isCommanderHelpExit("commander.helpDisplayed")).toBe(false);
+    });
+});

package/build/__tests__/client-pagination.test.js

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const postMock = vi.fn();
+const createMock = vi.fn(() => ({
+    post: postMock,
+    defaults: {
+        headers: {
+            common: {},
+        },
+    },
+}));
+vi.mock("axios", () => {
+    const axiosDefault = {
+        create: createMock,
+        isAxiosError: () => false,
+    };
+    return {
+        default: axiosDefault,
+        create: createMock,
+        AxiosError: class AxiosError extends Error {
+        },
+        AxiosHeaders: class AxiosHeaders {
+        },
+    };
+});
+const { DocmostClient } = await import("../client.js");
+describe("DocmostClient paginateAll", () => {
+    beforeEach(() => {
+        postMock.mockReset();
+        createMock.mockClear();
+    });
+    it("uses nextCursor when the API returns cursor pagination metadata", async () => {
+        postMock
+            .mockResolvedValueOnce({
+            data: {
+                data: {
+                    items: [{ id: "1" }, { id: "2" }],
+                    meta: {
+                        hasNextPage: true,
+                        nextCursor: "cursor-1",
+                        prevCursor: null,
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            data: {
+                data: {
+                    items: [{ id: "3" }],
+                    meta: {
+                        hasNextPage: false,
+                        nextCursor: null,
+                        prevCursor: "cursor-1",
+                    },
+                },
+            },
+        });
+        const client = new DocmostClient("https://example.test", { token: "token" });
+        const result = await client.paginateAll("/pages/recent", { spaceId: "space-1" }, 2);
+        expect(postMock).toHaveBeenNthCalledWith(1, "/pages/recent", {
+            spaceId: "space-1",
+            limit: 2,
+            page: 1,
+        });
+        expect(postMock).toHaveBeenNthCalledWith(2, "/pages/recent", {
+            spaceId: "space-1",
+            limit: 2,
+            cursor: "cursor-1",
+        });
+        expect(result).toEqual({
+            items: [{ id: "1" }, { id: "2" }, { id: "3" }],
+            hasMore: false,
+        });
+    });
+    it("fails fast when cursor pagination starts looping", async () => {
+        postMock
+            .mockResolvedValueOnce({
+            data: {
+                data: {
+                    items: [{ id: "1" }],
+                    meta: {
+                        hasNextPage: true,
+                        nextCursor: "cursor-1",
+                        prevCursor: null,
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            data: {
+                data: {
+                    items: [{ id: "2" }],
+                    meta: {
+                        hasNextPage: true,
+                        nextCursor: "cursor-1",
+                        prevCursor: "cursor-1",
+                    },
+                },
+            },
+        });
+        const client = new DocmostClient("https://example.test", { token: "token" });
+        await expect(client.paginateAll("/pages/recent", {}, 1)).rejects.toThrow("Pagination loop detected for /pages/recent: repeated cursor:cursor-1");
+    });
+});

package/build/__tests__/discovery.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "child_process";
+import { resolve } from "path";
+const CLI = resolve(import.meta.dirname, "../../build/index.js");
+describe("commands discovery", () => {
+    it("returns envelope with all commands", () => {
+        const output = execFileSync("node", [CLI, "commands"], { encoding: "utf-8" });
+        const result = JSON.parse(output);
+        expect(result.ok).toBe(true);
+        expect(Array.isArray(result.data)).toBe(true);
+        expect(result.data.length).toBeGreaterThan(50);
+        expect(result.meta).toEqual({ count: result.data.length, hasMore: false });
+    });
+    it("each command has name, description, options", () => {
+        const output = execFileSync("node", [CLI, "commands"], { encoding: "utf-8" });
+        const result = JSON.parse(output);
+        for (const cmd of result.data) {
+            expect(cmd).toHaveProperty("name");
+            expect(cmd).toHaveProperty("description");
+            expect(cmd).toHaveProperty("options");
+            expect(Array.isArray(cmd.options)).toBe(true);
+        }
+    });
+    it("does not include 'commands' itself", () => {
+        const output = execFileSync("node", [CLI, "commands"], { encoding: "utf-8" });
+        const result = JSON.parse(output);
+        const names = result.data.map((c) => c.name);
+        expect(names).not.toContain("commands");
+    });
+    it("options have flags and description", () => {
+        const output = execFileSync("node", [CLI, "commands"], { encoding: "utf-8" });
+        const result = JSON.parse(output);
+        const pageInfo = result.data.find((c) => c.name === "page-info");
+        expect(pageInfo).toBeDefined();
+        expect(pageInfo.options.length).toBeGreaterThan(0);
+        const pageIdOpt = pageInfo.options.find((o) => o.flags.includes("--page-id"));
+        expect(pageIdOpt).toBeDefined();
+        expect(pageIdOpt.required).toBe(true);
+    });
+});

package/build/__tests__/envelope.test.js

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+// Must mock console before importing the module
+const mockLog = vi.fn();
+const mockError = vi.fn();
+vi.stubGlobal("console", { ...console, log: mockLog, error: mockError, table: console.table });
+const { printResult, printError, CliError } = await import("../lib/cli-utils.js");
+describe("printResult envelope", () => {
+    const baseOpts = {
+        apiUrl: "http://localhost",
+        format: "json",
+        quiet: false,
+        limit: 100,
+        maxItems: Infinity,
+        auth: { token: "test" },
+    };
+    beforeEach(() => {
+        mockLog.mockClear();
+        mockError.mockClear();
+    });
+    it("wraps single object in { ok: true, data }", () => {
+        const data = { id: "abc", title: "Test" };
+        printResult(data, baseOpts);
+        const output = JSON.parse(mockLog.mock.calls[0][0]);
+        expect(output).toEqual({ ok: true, data: { id: "abc", title: "Test" } });
+        expect(output.meta).toBeUndefined();
+    });
+    it("wraps array in { ok: true, data, meta }", () => {
+        const data = [{ id: "1" }, { id: "2" }];
+        printResult(data, baseOpts, { allowTable: true });
+        const output = JSON.parse(mockLog.mock.calls[0][0]);
+        expect(output.ok).toBe(true);
+        expect(output.data).toHaveLength(2);
+        expect(output.meta).toEqual({ count: 2, hasMore: false });
+    });
+    it("passes hasMore from options to meta", () => {
+        const data = [{ id: "1" }];
+        printResult(data, baseOpts, { allowTable: true, hasMore: true });
+        const output = JSON.parse(mockLog.mock.calls[0][0]);
+        expect(output.meta).toEqual({ count: 1, hasMore: true });
+    });
+    it("wraps empty array with meta count 0", () => {
+        printResult([], baseOpts, { allowTable: true });
+        const output = JSON.parse(mockLog.mock.calls[0][0]);
+        expect(output).toEqual({ ok: true, data: [], meta: { count: 0, hasMore: false } });
+    });
+    it("does not output when quiet", () => {
+        printResult({ id: "1" }, { ...baseOpts, quiet: true });
+        expect(mockLog).not.toHaveBeenCalled();
+    });
+    it("table format is not wrapped in envelope", () => {
+        const data = [{ id: "1", name: "Test" }];
+        printResult(data, { ...baseOpts, format: "table" }, { allowTable: true });
+        // table uses console.table, not console.log with JSON
+        expect(mockLog).not.toHaveBeenCalled();
+    });
+    it("text format is not wrapped in envelope", () => {
+        const mockWrite = vi.fn();
+        const original = process.stdout.write;
+        process.stdout.write = mockWrite;
+        printResult("hello", { ...baseOpts, format: "text" }, {
+            textExtractor: (d) => d,
+        });
+        process.stdout.write = original;
+        expect(mockLog).not.toHaveBeenCalled();
+        expect(mockWrite.mock.calls[0][0]).toBe("hello");
+    });
+});
+describe("printError envelope", () => {
+    beforeEach(() => {
+        mockLog.mockClear();
+        mockError.mockClear();
+    });
+    it("wraps error in { ok: false, error } for json format", () => {
+        const error = new CliError("NOT_FOUND", "Page not found", { pageId: "abc" });
+        printError(error, "json");
+        const output = JSON.parse(mockError.mock.calls[0][0]);
+        expect(output).toEqual({
+            ok: false,
+            error: {
+                code: "NOT_FOUND",
+                message: "Page not found",
+                details: { pageId: "abc" },
+            },
+        });
+    });
+    it("uses plain text for non-json format", () => {
+        const error = new CliError("AUTH_ERROR", "Unauthorized");
+        printError(error, "text");
+        expect(mockError.mock.calls[0][0]).toBe("Error [AUTH_ERROR]: Unauthorized");
+    });
+});