@xyd-js/opencli-remark 0.0.0-build-b7bd05c-20260701151111

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @xyd-js/opencli-remark
+
+## 0.0.0-build-b7bd05c-20260701151111
+
+### Patch Changes
+
+- update all packages
+- Updated dependencies
+  - @xyd-js/opencli@0.0.0-build-b7bd05c-20260701151111

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LiveSession Sp.z.o.o
+
+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,222 @@
+# xyd-opencli-remark
+
+The package includes a remark plugin for generating OpenCLI documentation from variables in markdown files.
+
+## Usage
+
+```typescript
+import { remarkOpencliDocs } from '@xyd-js/opencli-remark';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkStringify from 'remark-stringify';
+import { remark } from 'remark';
+
+// Configure multiple CLI specs
+remark()
+  .use(remarkFrontmatter)
+  .use(remarkOpencliDocs, {
+    xyd: { source: './xyd-cli.json' },
+    npm: { source: './npm-cli.json' },
+    // Add more CLIs as needed
+  })
+  .use(remarkStringify)
+  .process(markdown);
+```
+
+## Configuration
+
+The plugin accepts an object where each key represents a CLI identifier, and the value contains the spec configuration:
+
+```typescript
+{
+  [cliKey: string]: {
+    source: string; // Path to OpenCLI spec JSON file (relative to markdown file) or URL
+  }
+}
+```
+
+**Example:**
+```typescript
+remarkOpencliDocs({
+  xyd: { source: './xyd-cli.json' },
+  npm: { source: 'https://example.com/npm-cli.json' }
+})
+```
+
+## Frontmatter Configuration
+
+In your markdown frontmatter, specify which CLI to use and the command path:
+
+```yaml
+---
+xyd.opencli.xyd: "dev"
+---
+```
+
+The CLI key (e.g., `xyd`) must match a key in your plugin configuration. The command path is **relative to the CLI root** (no CLI name prefix needed).
+
+### Command Path Examples
+
+- **Root command**: Use an empty string `""`
+  ```yaml
+  xyd.opencli.xyd: ""
+  ```
+
+- **Top-level command**: Just the command name
+  ```yaml
+  xyd.opencli.xyd: "dev"
+  ```
+
+- **Nested command**: Space-separated path
+  ```yaml
+  xyd.opencli.xyd: "components install"
+  ```
+
+- **Using aliases**: You can use command aliases
+  ```yaml
+  xyd.opencli.xyd: "d"  # if "d" is an alias for "dev"
+  ```
+
+### Indent Style Configuration
+
+You can configure the output format for arguments and options:
+
+```yaml
+---
+xyd.opencli.xyd:
+  command: "dev"
+  indent: list  # or "code" (default)
+---
+```
+
+- **`code`** (default): Tab-indented CLI-style format, suitable for code blocks
+- **`list`**: Markdown list format with backticks, suitable for regular markdown
+
+## Example Markdown
+
+### Code Block Format (default)
+
+**Input:**
+```markdown
+---
+xyd.opencli.xyd: "dev"
+---
+
+```sh
+Usage: {opencli.current.usage}
+
+{opencli.current.description}
+
+Arguments:
+{opencli.current.arguments}
+
+Options:
+{opencli.current.options}
+```
+
+**Output:**
+```markdown
+---
+xyd.opencli.xyd: "dev"
+---
+
+```sh
+Usage: xyd dev [flags]
+
+Run your docs locally in development mode
+
+Options:
+	-p, --port <number>            Port to run the dev server on
+	-l, --logLevel <string>        Set logging level (e.g. info, debug)
+	--verbose                      Enable verbose output
+	--debug                        Enable debug output
+```
+
+### List Format
+
+**Input:**
+```markdown
+---
+xyd.opencli.xyd:
+  command: "dev"
+  indent: list
+---
+
+## Usage
+`{opencli.current.usage}`
+
+{opencli.current.description}
+
+## Arguments
+{opencli.current.arguments}
+
+## Options
+{opencli.current.options}
+```
+
+**Output:**
+```markdown
+---
+xyd.opencli.xyd:
+  command: "dev"
+  indent: list
+---
+
+## Usage
+
+`xyd dev [flags]`
+
+Run your docs locally in development mode
+
+## Arguments
+
+## Options
+
+- `-p`, `--port <number>`  Port to run the dev server on
+- `-l`, `--logLevel <string>`  Set logging level (e.g. info, debug)
+- `--verbose`  Enable verbose output
+- `--debug`  Enable debug output
+```
+
+## Variables
+
+The following Variables are supported:
+
+| Variable | Description | Format Support |
+|------------|-------------|----------------|
+| `{opencli.current.usage}` | Generates usage line (e.g., `xyd dev [flags]`) | All formats |
+| `{opencli.current.description}` | Command description | All formats |
+| `{opencli.current.commands}` | List of available subcommands | All formats |
+| `{opencli.current.arguments}` | Command arguments documentation | Code blocks, text (code style), or list nodes (list style) |
+| `{opencli.current.options}` | Command options/flags documentation | Code blocks, text (code style), or list nodes (list style) |
+
+**Note:** 
+- `{opencli.current.arguments}` and `{opencli.current.options}` work in:
+  - Code blocks (always code format)
+  - Text nodes (code format when `indent: 'code'`)
+  - List nodes (list format when `indent: 'list'` - automatically converted to markdown lists)
+
+## Multiple CLIs
+
+You can configure and use multiple CLI specs in the same project:
+
+```typescript
+remarkOpencliDocs({
+  xyd: { source: './xyd-cli.json' },
+  npm: { source: './npm-cli.json' },
+  git: { source: './git-cli.json' }
+})
+```
+
+Then in different markdown files, reference the appropriate CLI:
+
+```yaml
+# File 1: xyd-dev.md
+---
+xyd.opencli.xyd: "dev"
+---
+
+# File 2: npm-install.md
+---
+xyd.opencli.npm: "install"
+---
+```

package/dist/index.cjs

@@ -0,0 +1,290 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  remarkOpencliDocs: () => remarkOpencliDocs
+});
+module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("@xyd-js/opencli"), module.exports);
+
+// src/remark-opencli.ts
+var import_unist_util_visit = require("unist-util-visit");
+var import_vfile_matter = require("vfile-matter");
+var import_js_yaml = require("js-yaml");
+var import_opencli = require("@xyd-js/opencli");
+function remarkOpencliDocs(options) {
+  return async function transformer(tree, file) {
+    var _a;
+    if (!file) {
+      return;
+    }
+    if (!file.data) {
+      file.data = {};
+    }
+    let hasOpencliKey = false;
+    let yamlContent = null;
+    (0, import_unist_util_visit.visit)(tree, "yaml", (node) => {
+      if (node.value && !yamlContent) {
+        const content = String(node.value);
+        yamlContent = content;
+        if (content.includes("xyd.opencli.")) {
+          hasOpencliKey = true;
+        }
+      }
+    });
+    if (!yamlContent && file.value) {
+      const fileValue = typeof file.value === "string" ? file.value : new TextDecoder().decode(file.value);
+      const frontmatterMatch = fileValue.match(/^---\n([\s\S]*?)\n---/);
+      if (frontmatterMatch && frontmatterMatch[1].includes("xyd.opencli.")) {
+        hasOpencliKey = true;
+        yamlContent = frontmatterMatch[1];
+      }
+    }
+    if (!hasOpencliKey) {
+      return;
+    }
+    let frontmatter = file.data.matter;
+    if (!frontmatter && yamlContent) {
+      try {
+        frontmatter = (0, import_js_yaml.load)(yamlContent);
+        file.data.matter = frontmatter;
+      } catch (error) {
+        if (file.value) {
+          (0, import_vfile_matter.matter)(file);
+          frontmatter = file.data.matter;
+        }
+      }
+    }
+    if (!frontmatter && file.value) {
+      (0, import_vfile_matter.matter)(file);
+      frontmatter = file.data.matter;
+    }
+    let cliKey = null;
+    let opencliConfig = null;
+    for (const key in frontmatter) {
+      if (key.startsWith("xyd.opencli.")) {
+        cliKey = key.substring("xyd.opencli.".length);
+        opencliConfig = frontmatter[key];
+        break;
+      }
+    }
+    if (!cliKey || opencliConfig === void 0 || opencliConfig === null) {
+      return;
+    }
+    const cliConfig = options[cliKey];
+    if (!cliConfig || !cliConfig.source) {
+      console.warn(`No configuration found for CLI key "${cliKey}"`);
+      return;
+    }
+    let commandPath;
+    let indentStyle = "code";
+    if (typeof opencliConfig === "string") {
+      commandPath = opencliConfig;
+    } else if (typeof opencliConfig === "object" && opencliConfig !== null) {
+      commandPath = opencliConfig.command || "";
+      indentStyle = opencliConfig.indent === "list" ? "list" : "code";
+    } else {
+      return;
+    }
+    const normalizedPath = (commandPath == null ? void 0 : commandPath.trim()) || "";
+    const spec = await (0, import_opencli.loadOpencliSpec)(cliConfig.source, { cwd: file.dirname });
+    if (!spec) {
+      console.warn(`Failed to load OpenCLI spec from ${cliConfig.source}`);
+      return;
+    }
+    const command = (0, import_opencli.findCommand)(spec, normalizedPath);
+    if (!command) {
+      console.warn(`Command "${normalizedPath || "(root)"}" not found in OpenCLI spec`);
+      return;
+    }
+    const cliTitle = ((_a = spec.info) == null ? void 0 : _a.title) || "";
+    const displayPath = normalizedPath ? `${cliTitle} ${normalizedPath}`.trim() : cliTitle || command.name;
+    const usage = (0, import_opencli.generateUsage)(spec, command, displayPath);
+    const description = (0, import_opencli.generateDescription)(command);
+    const subcommands = (0, import_opencli.generateCommands)(command);
+    const argsText = (0, import_opencli.generateArguments)(command, "code");
+    const optsText = (0, import_opencli.generateOptions)(command, "code");
+    const replaceSimplePlaceholders = (value) => {
+      return value.replace(/\{opencli\.current\.usage\}/g, usage).replace(/\{opencli\.current\.description\}/g, description).replace(/\{opencli\.current\.commands\}/g, subcommands);
+    };
+    (0, import_unist_util_visit.visit)(tree, "text", (node) => {
+      if (typeof node.value === "string") {
+        node.value = replaceSimplePlaceholders(node.value);
+        if (indentStyle === "code") {
+          node.value = node.value.replace(/\{opencli\.current\.arguments\}/g, argsText).replace(/\{opencli\.current\.options\}/g, optsText);
+        }
+      }
+    });
+    (0, import_unist_util_visit.visit)(tree, "inlineCode", (node) => {
+      if (typeof node.value === "string") {
+        node.value = replaceSimplePlaceholders(node.value);
+        if (indentStyle === "code") {
+          node.value = node.value.replace(/\{opencli\.current\.arguments\}/g, argsText).replace(/\{opencli\.current\.options\}/g, optsText);
+        }
+      }
+    });
+    (0, import_unist_util_visit.visit)(tree, "code", (node) => {
+      if (typeof node.value === "string") {
+        node.value = replaceSimplePlaceholders(node.value).replace(/\{opencli\.current\.arguments\}/g, argsText).replace(/\{opencli\.current\.options\}/g, optsText);
+      }
+    });
+    const mdxExprValue = (expr) => {
+      switch (expr) {
+        case "opencli.current.usage":
+          return usage;
+        case "opencli.current.description":
+          return description;
+        case "opencli.current.commands":
+          return subcommands;
+        case "opencli.current.arguments":
+          return argsText;
+        case "opencli.current.options":
+          return optsText;
+        default:
+          return null;
+      }
+    };
+    (0, import_unist_util_visit.visit)(tree, ["mdxFlowExpression", "mdxTextExpression"], (node, index, parent) => {
+      if (!parent || index === void 0 || typeof node.value !== "string") return;
+      const expr = node.value.trim();
+      if (!expr.startsWith("opencli.current.")) return;
+      if (indentStyle === "list" && (expr === "opencli.current.arguments" || expr === "opencli.current.options")) {
+        const listNode = expr === "opencli.current.arguments" ? createArgumentsListNode(command) : createOptionsListNode(command);
+        parent.children[index] = listNode || { type: "text", value: "" };
+        return;
+      }
+      const value = mdxExprValue(expr);
+      if (value === null) return;
+      if (node.type === "mdxFlowExpression") {
+        parent.children[index] = expr === "opencli.current.description" ? { type: "paragraph", children: [{ type: "text", value }] } : { type: "code", value };
+      } else {
+        parent.children[index] = { type: "text", value };
+      }
+    });
+    if (indentStyle === "list") {
+      (0, import_unist_util_visit.visit)(tree, "paragraph", (node, index, parent) => {
+        var _a2;
+        if (!parent || index === void 0) return;
+        const textChild = (_a2 = node.children) == null ? void 0 : _a2.find(
+          (c) => {
+            var _a3;
+            return c.type === "text" && ((_a3 = c.value) == null ? void 0 : _a3.includes("{opencli.current.arguments}"));
+          }
+        );
+        if (textChild) {
+          const listNode = createArgumentsListNode(command);
+          if (listNode) {
+            parent.children[index] = listNode;
+          } else {
+            textChild.value = textChild.value.replace("{opencli.current.arguments}", "");
+          }
+        }
+      });
+      (0, import_unist_util_visit.visit)(tree, "paragraph", (node, index, parent) => {
+        var _a2;
+        if (!parent || index === void 0) return;
+        const textChild = (_a2 = node.children) == null ? void 0 : _a2.find(
+          (c) => {
+            var _a3;
+            return c.type === "text" && ((_a3 = c.value) == null ? void 0 : _a3.includes("{opencli.current.options}"));
+          }
+        );
+        if (textChild) {
+          const listNode = createOptionsListNode(command);
+          if (listNode) {
+            parent.children[index] = listNode;
+          } else {
+            textChild.value = textChild.value.replace("{opencli.current.options}", "");
+          }
+        }
+      });
+    }
+  };
+}
+function createArgumentsListNode(command) {
+  if (!command.arguments || command.arguments.length === 0) {
+    return null;
+  }
+  const visibleArgs = command.arguments.filter((arg) => !arg.hidden);
+  if (visibleArgs.length === 0) {
+    return null;
+  }
+  return {
+    type: "list",
+    ordered: false,
+    spread: false,
+    children: visibleArgs.map((arg) => ({
+      type: "listItem",
+      spread: false,
+      children: [{
+        type: "paragraph",
+        children: [
+          { type: "inlineCode", value: arg.name.toLowerCase() },
+          { type: "text", value: arg.description ? `  ${arg.description}` : "" }
+        ]
+      }]
+    }))
+  };
+}
+function createOptionsListNode(command) {
+  if (!command.options || command.options.length === 0) {
+    return null;
+  }
+  const visibleOptions = command.options.filter((opt) => !opt.hidden);
+  if (visibleOptions.length === 0) {
+    return null;
+  }
+  return {
+    type: "list",
+    ordered: false,
+    spread: false,
+    children: visibleOptions.map((option) => {
+      var _a;
+      const aliases = ((_a = option.aliases) == null ? void 0 : _a.filter((a) => a.length === 1)) || [];
+      const short = aliases.length > 0 ? `-${aliases[0]}` : "";
+      const long = `--${option.name}`;
+      const children = [];
+      if (short) {
+        children.push({ type: "inlineCode", value: short });
+        children.push({ type: "text", value: ", " });
+      }
+      children.push({ type: "inlineCode", value: long });
+      if (option.description) {
+        children.push({ type: "text", value: `  ${option.description}` });
+      }
+      return {
+        type: "listItem",
+        spread: false,
+        children: [{
+          type: "paragraph",
+          children
+        }]
+      };
+    })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  remarkOpencliDocs,
+  ...require("@xyd-js/opencli")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts","../src/remark-opencli.ts"],"sourcesContent":["// The OpenCLI model + helpers now live in @xyd-js/opencli; re-export them so\n// existing consumers of @xyd-js/opencli-remark keep working.\nexport * from '@xyd-js/opencli';\nexport { remarkOpencliDocs, type OpencliDocsOptions } from './src/remark-opencli';\n","import { visit } from 'unist-util-visit';\nimport { VFile } from 'vfile';\nimport { Root } from 'mdast';\nimport { matter } from 'vfile-matter';\nimport { load } from 'js-yaml';\n\nimport {\n  loadOpencliSpec,\n  findCommand,\n  generateUsage,\n  generateDescription,\n  generateArguments,\n  generateOptions,\n  generateCommands,\n  type Command,\n} from '@xyd-js/opencli';\n\nexport interface OpencliDocsOptions {\n  [cliKey: string]: {\n    source: string; // File path or URL\n  };\n}\n\n/**\n * Remark plugin for generating OpenCLI documentation from placeholders\n *\n * @example\n * ```md\n * ---\n * xyd.opencli.spice: \"install\"\n * ---\n *\n * ### Usage\n * {opencli.current.usage}\n *\n * ### Flags\n * {opencli.current.flags}\n * ```\n *\n * @example\n * ```ts\n * remarkOpencliDocs({\n *   spice: { source: './spice-spec.json' },\n *   npm: { source: './npm-spec.json' }\n * })\n * ```\n */\nexport function remarkOpencliDocs(options: OpencliDocsOptions) {\n  return async function transformer(tree: Root, file?: VFile) {\n    // Return early if no file is provided\n    if (!file) {\n      return;\n    }\n\n    // Ensure file.data exists\n    if (!file.data) {\n      file.data = {};\n    }\n\n    // Quick check: look for xyd.opencli.* pattern in YAML nodes before parsing\n    let hasOpencliKey = false;\n    let yamlContent: string | null = null;\n\n    visit(tree, 'yaml', (node: any) => {\n      if (node.value && !yamlContent) {\n        const content = String(node.value);\n        yamlContent = content;\n        // Quick string check for xyd.opencli. pattern\n        if (content.includes('xyd.opencli.')) {\n          hasOpencliKey = true;\n        }\n      }\n    });\n\n    // If no YAML node found, check file.value directly\n    if (!yamlContent && file.value) {\n      const fileValue = typeof file.value === 'string' ? file.value : new TextDecoder().decode(file.value);\n      const frontmatterMatch = fileValue.match(/^---\\n([\\s\\S]*?)\\n---/);\n      if (frontmatterMatch && frontmatterMatch[1].includes('xyd.opencli.')) {\n        hasOpencliKey = true;\n        yamlContent = frontmatterMatch[1];\n      }\n    }\n\n    // If no xyd.opencli.* key found anywhere, return early without any processing\n    if (!hasOpencliKey) {\n      return;\n    }\n\n    // Now parse frontmatter since we know there's a potential match\n    let frontmatter = file.data.matter as Record<string, any> | undefined;\n\n    // If not parsed, parse from YAML content we found\n    if (!frontmatter && yamlContent) {\n      try {\n        frontmatter = load(yamlContent) as Record<string, any>;\n        file.data.matter = frontmatter;\n      } catch (error) {\n        // Failed to parse YAML, try parsing from file.value\n        if (file.value) {\n          matter(file as any);\n          frontmatter = file.data.matter as Record<string, any> | undefined;\n        }\n      }\n    }\n\n    // Fallback: try to parse from file.value if YAML nodes weren't found\n    if (!frontmatter && file.value) {\n      matter(file as any);\n      frontmatter = file.data.matter as Record<string, any> | undefined;\n    }\n\n    // Find xyd.opencli.{cliKey} pattern in frontmatter\n    let cliKey: string | null = null;\n    let opencliConfig: any = null;\n\n    for (const key in frontmatter) {\n      if (key.startsWith('xyd.opencli.')) {\n        cliKey = key.substring('xyd.opencli.'.length);\n        opencliConfig = frontmatter[key];\n        break;\n      }\n    }\n\n    // If no xyd.opencli.{cliKey} found, return early\n    if (!cliKey || opencliConfig === undefined || opencliConfig === null) {\n      return;\n    }\n\n    // Get the CLI config for this key\n    const cliConfig = options[cliKey];\n    if (!cliConfig || !cliConfig.source) {\n      console.warn(`No configuration found for CLI key \"${cliKey}\"`);\n      return;\n    }\n\n    // Parse xyd.opencli.{cliKey} - can be string or object\n    let commandPath: string;\n    let indentStyle: 'code' | 'list' = 'code'; // default\n\n    if (typeof opencliConfig === 'string') {\n      commandPath = opencliConfig;\n    } else if (typeof opencliConfig === 'object' && opencliConfig !== null) {\n      commandPath = opencliConfig.command || '';\n      indentStyle = opencliConfig.indent === 'list' ? 'list' : 'code';\n    } else {\n      return;\n    }\n\n    const normalizedPath = commandPath?.trim() || '';\n\n    // Load OpenCLI spec (resolve relative file paths from the markdown file's dir)\n    const spec = await loadOpencliSpec(cliConfig.source, { cwd: file.dirname });\n    if (!spec) {\n      console.warn(`Failed to load OpenCLI spec from ${cliConfig.source}`);\n      return;\n    }\n\n    // Find the command in the spec\n    const command = findCommand(spec, normalizedPath);\n    if (!command) {\n      console.warn(`Command \"${normalizedPath || '(root)'}\" not found in OpenCLI spec`);\n      return;\n    }\n\n    // Build display path: CLI title + command path (or just CLI title for root)\n    const cliTitle = spec.info?.title || '';\n    const displayPath = normalizedPath\n      ? `${cliTitle} ${normalizedPath}`.trim()\n      : cliTitle || command.name;\n\n    // Generate documentation content\n    const usage = generateUsage(spec, command, displayPath);\n    const description = generateDescription(command);\n    // const flags = generateFlags(command);\n    const subcommands = generateCommands(command);\n\n    // For code format, generate string content\n    const argsText = generateArguments(command, 'code');\n    const optsText = generateOptions(command, 'code');\n\n    // Helper function to replace simple placeholders (usage, description)\n    const replaceSimplePlaceholders = (value: string) => {\n      return value\n        .replace(/\\{opencli\\.current\\.usage\\}/g, usage)\n        .replace(/\\{opencli\\.current\\.description\\}/g, description)\n        // .replace(/\\{opencli\\.current\\.flags\\}/g, flags)\n        .replace(/\\{opencli\\.current\\.commands\\}/g, subcommands);\n    };\n\n    // Replace placeholders in text nodes\n    visit(tree, 'text', (node: any) => {\n      if (typeof node.value === 'string') {\n        node.value = replaceSimplePlaceholders(node.value);\n        // For code style, also replace arguments/options as text\n        if (indentStyle === 'code') {\n          node.value = node.value\n            .replace(/\\{opencli\\.current\\.arguments\\}/g, argsText)\n            .replace(/\\{opencli\\.current\\.options\\}/g, optsText);\n        }\n      }\n    });\n\n    // Replace placeholders in inline code (backticks)\n    visit(tree, 'inlineCode', (node: any) => {\n      if (typeof node.value === 'string') {\n        node.value = replaceSimplePlaceholders(node.value);\n        if (indentStyle === 'code') {\n          node.value = node.value\n            .replace(/\\{opencli\\.current\\.arguments\\}/g, argsText)\n            .replace(/\\{opencli\\.current\\.options\\}/g, optsText);\n        }\n      }\n    });\n\n    // Replace placeholders in code blocks\n    visit(tree, 'code', (node: any) => {\n      if (typeof node.value === 'string') {\n        node.value = replaceSimplePlaceholders(node.value)\n          .replace(/\\{opencli\\.current\\.arguments\\}/g, argsText)\n          .replace(/\\{opencli\\.current\\.options\\}/g, optsText);\n      }\n    });\n\n    // In an MDX pipeline `{opencli.current.*}` is parsed as a JS expression node\n    // (mdxFlowExpression / mdxTextExpression), not literal text — so the visitors\n    // above never see it (and it would throw at render since `opencli` is undefined).\n    // Resolve those expression nodes here.\n    const mdxExprValue = (expr: string): string | null => {\n      switch (expr) {\n        case 'opencli.current.usage': return usage;\n        case 'opencli.current.description': return description;\n        case 'opencli.current.commands': return subcommands;\n        case 'opencli.current.arguments': return argsText;\n        case 'opencli.current.options': return optsText;\n        default: return null;\n      }\n    };\n    visit(tree, ['mdxFlowExpression', 'mdxTextExpression'], (node: any, index: number | undefined, parent: any) => {\n      if (!parent || index === undefined || typeof node.value !== 'string') return;\n      const expr = node.value.trim();\n      if (!expr.startsWith('opencli.current.')) return;\n\n      if (indentStyle === 'list' && (expr === 'opencli.current.arguments' || expr === 'opencli.current.options')) {\n        const listNode = expr === 'opencli.current.arguments'\n          ? createArgumentsListNode(command)\n          : createOptionsListNode(command);\n        parent.children[index] = listNode || { type: 'text', value: '' };\n        return;\n      }\n\n      const value = mdxExprValue(expr);\n      if (value === null) return;\n\n      if (node.type === 'mdxFlowExpression') {\n        parent.children[index] = expr === 'opencli.current.description'\n          ? { type: 'paragraph', children: [{ type: 'text', value }] }\n          : { type: 'code', value };\n      } else {\n        parent.children[index] = { type: 'text', value };\n      }\n    });\n\n    // For list format, replace argument/option placeholders with mdast list nodes\n    if (indentStyle === 'list') {\n      // Replace {opencli.current.arguments} with list node\n      visit(tree, 'paragraph', (node: any, index: number | undefined, parent: any) => {\n        if (!parent || index === undefined) return;\n\n        const textChild = node.children?.find((c: any) =>\n          c.type === 'text' && c.value?.includes('{opencli.current.arguments}')\n        );\n\n        if (textChild) {\n          const listNode = createArgumentsListNode(command);\n          if (listNode) {\n            parent.children[index] = listNode;\n          } else {\n            // No arguments, just remove the placeholder\n            textChild.value = textChild.value.replace('{opencli.current.arguments}', '');\n          }\n        }\n      });\n\n      // Replace {opencli.current.options} with list node\n      visit(tree, 'paragraph', (node: any, index: number | undefined, parent: any) => {\n        if (!parent || index === undefined) return;\n\n        const textChild = node.children?.find((c: any) =>\n          c.type === 'text' && c.value?.includes('{opencli.current.options}')\n        );\n\n        if (textChild) {\n          const listNode = createOptionsListNode(command);\n          if (listNode) {\n            parent.children[index] = listNode;\n          } else {\n            // No options, just remove the placeholder\n            textChild.value = textChild.value.replace('{opencli.current.options}', '');\n          }\n        }\n      });\n    }\n  };\n}\n\n/**\n * Create mdast list node for arguments (for list indent style)\n */\nfunction createArgumentsListNode(command: Command): any | null {\n  if (!command.arguments || command.arguments.length === 0) {\n    return null;\n  }\n\n  const visibleArgs = command.arguments.filter(arg => !arg.hidden);\n  if (visibleArgs.length === 0) {\n    return null;\n  }\n\n  return {\n    type: 'list',\n    ordered: false,\n    spread: false,\n    children: visibleArgs.map(arg => ({\n      type: 'listItem',\n      spread: false,\n      children: [{\n        type: 'paragraph',\n        children: [\n          { type: 'inlineCode', value: arg.name.toLowerCase() },\n          { type: 'text', value: arg.description ? `  ${arg.description}` : '' }\n        ]\n      }]\n    }))\n  };\n}\n\n/**\n * Create mdast list node for options (for list indent style)\n */\nfunction createOptionsListNode(command: Command): any | null {\n  if (!command.options || command.options.length === 0) {\n    return null;\n  }\n\n  const visibleOptions = command.options.filter(opt => !opt.hidden);\n  if (visibleOptions.length === 0) {\n    return null;\n  }\n\n  return {\n    type: 'list',\n    ordered: false,\n    spread: false,\n    children: visibleOptions.map(option => {\n      const aliases = option.aliases?.filter(a => a.length === 1) || [];\n      const short = aliases.length > 0 ? `-${aliases[0]}` : '';\n      const long = `--${option.name}`;\n\n      const children: any[] = [];\n\n      // Add short alias if exists\n      if (short) {\n        children.push({ type: 'inlineCode', value: short });\n        children.push({ type: 'text', value: ', ' });\n      }\n\n      // Add long option\n      children.push({ type: 'inlineCode', value: long });\n\n      // Add description\n      if (option.description) {\n        children.push({ type: 'text', value: `  ${option.description}` });\n      }\n\n      return {\n        type: 'listItem',\n        spread: false,\n        children: [{\n          type: 'paragraph',\n          children\n        }]\n      };\n    })\n  };\n}\n"],"mappings":"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","names":["_a"]}

package/dist/index.d.cts

@@ -0,0 +1,36 @@
+export * from '@xyd-js/opencli';
+import { VFile } from 'vfile';
+import { Root } from 'mdast';
+
+interface OpencliDocsOptions {
+    [cliKey: string]: {
+        source: string;
+    };
+}
+/**
+ * Remark plugin for generating OpenCLI documentation from placeholders
+ *
+ * @example
+ * ```md
+ * ---
+ * xyd.opencli.spice: "install"
+ * ---
+ *
+ * ### Usage
+ * {opencli.current.usage}
+ *
+ * ### Flags
+ * {opencli.current.flags}
+ * ```
+ *
+ * @example
+ * ```ts
+ * remarkOpencliDocs({
+ *   spice: { source: './spice-spec.json' },
+ *   npm: { source: './npm-spec.json' }
+ * })
+ * ```
+ */
+declare function remarkOpencliDocs(options: OpencliDocsOptions): (tree: Root, file?: VFile) => Promise<void>;
+
+export { type OpencliDocsOptions, remarkOpencliDocs };

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export * from '@xyd-js/opencli';
+import { VFile } from 'vfile';
+import { Root } from 'mdast';
+
+interface OpencliDocsOptions {
+    [cliKey: string]: {
+        source: string;
+    };
+}
+/**
+ * Remark plugin for generating OpenCLI documentation from placeholders
+ *
+ * @example
+ * ```md
+ * ---
+ * xyd.opencli.spice: "install"
+ * ---
+ *
+ * ### Usage
+ * {opencli.current.usage}
+ *
+ * ### Flags
+ * {opencli.current.flags}
+ * ```
+ *
+ * @example
+ * ```ts
+ * remarkOpencliDocs({
+ *   spice: { source: './spice-spec.json' },
+ *   npm: { source: './npm-spec.json' }
+ * })
+ * ```
+ */
+declare function remarkOpencliDocs(options: OpencliDocsOptions): (tree: Root, file?: VFile) => Promise<void>;
+
+export { type OpencliDocsOptions, remarkOpencliDocs };