mdsel 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,1892 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+import { createRequire } from "module";
+
+// src/parser/parse.ts
+import { readFile, access, stat } from "fs/promises";
+
+// src/parser/processor.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+function createProcessor(options = {}) {
+  const { gfm = true } = options;
+  let processor = unified().use(remarkParse);
+  if (gfm) {
+    processor = processor.use(remarkGfm);
+  }
+  return {
+    parse: (markdown) => processor.parse(markdown)
+  };
+}
+
+// src/parser/types.ts
+var ParserError = class _ParserError extends Error {
+  code;
+  filePath;
+  line;
+  column;
+  constructor(code, message, filePath, line, column) {
+    super(message);
+    this.name = "ParserError";
+    this.code = code;
+    this.filePath = filePath;
+    this.line = line;
+    this.column = column;
+    Error.captureStackTrace(this, _ParserError);
+  }
+};
+
+// src/utils/validation.ts
+var DEFAULT_MAX_DEPTH = 20;
+var DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;
+var BINARY_THRESHOLD_RATIO = 0.1;
+function isLikelyBinary(content, sampleSize = 1024) {
+  if (!content || content.length === 0) {
+    return false;
+  }
+  const sample = content.slice(0, sampleSize);
+  const nullCount = (sample.match(/\0/g) ?? []).length;
+  const ratio = nullCount / sample.length;
+  return ratio > BINARY_THRESHOLD_RATIO;
+}
+function isValidUtf8(buffer) {
+  try {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    decoder.decode(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getNestingDepth(ast) {
+  let maxDepth = 0;
+  function traverse(node, currentDepth) {
+    maxDepth = Math.max(maxDepth, currentDepth);
+    if ("children" in node && Array.isArray(node.children)) {
+      for (const child of node.children) {
+        traverse(child, currentDepth + 1);
+      }
+    }
+  }
+  traverse(ast, 0);
+  return maxDepth;
+}
+function sanitizeInput(content) {
+  if (!content) return "";
+  let normalized = content.replace(/\r\n?/g, "\n");
+  normalized = normalized.trim();
+  return normalized;
+}
+function formatFileSize(bytes) {
+  const units = ["B", "KB", "MB", "GB"];
+  let size = bytes;
+  let unitIndex = 0;
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+  return `${size.toFixed(2)} ${units[unitIndex] ?? "B"}`;
+}
+
+// src/parser/parse.ts
+function parseMarkdown(content, options) {
+  const processor = createProcessor(options);
+  const ast = processor.parse(content);
+  const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const actualDepth = getNestingDepth(ast);
+  if (actualDepth > maxDepth) {
+    throw new Error(
+      `Maximum nesting depth of ${String(maxDepth)} exceeded (found depth of ${String(actualDepth)}). Consider increasing the maxDepth option if this is expected.`
+    );
+  }
+  return { ast };
+}
+async function parseFile(filePath, options) {
+  const maxFileSize = options?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+  try {
+    await access(filePath);
+  } catch {
+    throw new ParserError("FILE_NOT_FOUND", `File not found: ${filePath}`, filePath);
+  }
+  let fileSize;
+  try {
+    const stats = await stat(filePath);
+    fileSize = stats.size;
+    if (fileSize > maxFileSize) {
+      throw new ParserError(
+        "FILE_TOO_LARGE",
+        `File size (${formatFileSize(fileSize)}) exceeds maximum allowed size (${formatFileSize(maxFileSize)})`,
+        filePath
+      );
+    }
+  } catch (error) {
+    if (error instanceof ParserError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown stat error";
+    throw new ParserError("FILE_READ_ERROR", `Failed to read file stats: ${message}`, filePath);
+  }
+  let buffer;
+  let content;
+  try {
+    buffer = await readFile(filePath);
+    if (!isValidUtf8(buffer)) {
+      throw new ParserError(
+        "ENCODING_ERROR",
+        "File contains invalid UTF-8 byte sequences",
+        filePath
+      );
+    }
+    content = buffer.toString("utf-8");
+  } catch (error) {
+    if (error instanceof ParserError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown read error";
+    throw new ParserError("FILE_READ_ERROR", `Failed to read file: ${message}`, filePath);
+  }
+  if (isLikelyBinary(content)) {
+    throw new ParserError(
+      "BINARY_FILE",
+      "File appears to be binary content rather than text markdown",
+      filePath
+    );
+  }
+  content = sanitizeInput(content);
+  const result = parseMarkdown(content, options);
+  return {
+    ...result,
+    filePath
+  };
+}
+
+// src/output/utils.ts
+function createTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function omitNullFields(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/output/formatters.ts
+function formatIndexResponse(documents, summary) {
+  return {
+    success: true,
+    command: "index",
+    timestamp: createTimestamp(),
+    data: {
+      documents,
+      summary
+    }
+  };
+}
+function formatSelectResponse(matches, unresolved = []) {
+  const hasErrors = unresolved.length > 0;
+  const response = {
+    success: !hasErrors,
+    command: "select",
+    timestamp: createTimestamp(),
+    data: {
+      matches,
+      unresolved
+    }
+  };
+  if (unresolved.length > 0) {
+    response.unresolved_selectors = unresolved.map((u) => u.selector);
+  }
+  return response;
+}
+function formatErrorResponse(command, errors, partialResults) {
+  const response = {
+    success: false,
+    command,
+    timestamp: createTimestamp(),
+    data: null,
+    errors
+  };
+  if (partialResults && partialResults.length > 0) {
+    response.partial_results = partialResults;
+  }
+  return response;
+}
+function createErrorEntry(type, code, message, file, selector, suggestions) {
+  return omitNullFields({
+    type,
+    code,
+    message,
+    file,
+    selector,
+    suggestions
+  });
+}
+
+// src/output/text-formatters.ts
+function formatIndexText(documents) {
+  const parts = [];
+  const multiDoc = documents.length > 1;
+  for (const doc of documents) {
+    if (multiDoc) {
+      parts.push(`${doc.namespace} ${doc.file_path}`);
+    }
+    const headingLines = formatHeadingTree(doc.headings);
+    if (headingLines.length > 0) {
+      parts.push(...headingLines);
+    }
+    const blocks = doc.blocks;
+    const blockParts = [];
+    if (blocks.code_blocks > 0) blockParts.push(`code:${blocks.code_blocks}`);
+    if (blocks.paragraphs > 0) blockParts.push(`para:${blocks.paragraphs}`);
+    if (blocks.lists > 0) blockParts.push(`list:${blocks.lists}`);
+    if (blocks.tables > 0) blockParts.push(`table:${blocks.tables}`);
+    if (blocks.blockquotes > 0) blockParts.push(`quote:${blocks.blockquotes}`);
+    if (blockParts.length > 0) {
+      parts.push("---");
+      parts.push(blockParts.join(" "));
+    }
+  }
+  return parts.join("\n");
+}
+function formatHeadingTree(headings) {
+  const lines = [];
+  const counts = {};
+  for (const h of headings) {
+    const idx = counts[h.depth] ?? 0;
+    counts[h.depth] = idx + 1;
+    const indent = h.depth > 1 ? " ".repeat(h.depth - 1) : "";
+    lines.push(`${indent}h${h.depth}.${idx} ${h.text}`);
+  }
+  return lines;
+}
+function formatSelectText(matches, unresolved) {
+  const parts = [];
+  for (let i = 0; i < matches.length; i++) {
+    if (matches.length > 1) parts.push(`${matches[i].selector}:`);
+    parts.push(matches[i].content);
+  }
+  for (const u of unresolved) {
+    parts.push(`!${u.selector}`);
+    parts.push(u.reason);
+    if (u.suggestions.length > 0) {
+      const suggestions = u.suggestions.slice(0, 5).map((s) => `~${s}`).join(" ");
+      parts.push(suggestions);
+    }
+  }
+  return parts.join("\n");
+}
+function formatErrorText(errors) {
+  const parts = [];
+  for (const err of errors) {
+    parts.push(`!${err.type}: ${err.message}`);
+    if (err.file) {
+      parts.push(`file: ${err.file}`);
+    }
+    if (err.selector) {
+      parts.push(`selector: ${err.selector}`);
+    }
+    if (err.suggestions && err.suggestions.length > 0) {
+      const suggestions = err.suggestions.slice(0, 5).map((s) => `~${s}`).join(" ");
+      parts.push(suggestions);
+    }
+  }
+  return parts.join("\n");
+}
+var FORMAT_SPECS = {
+  index: {
+    terse: "hN.I title (indented)\\n---\\ncode:N para:N list:N table:N",
+    example: `h1.0 mdsel
+ h2.0 Installation
+ h2.1 Quick Start
+ h2.2 Commands
+  h3.0 index
+  h3.1 select
+---
+code:19 para:23 list:5 table:3`
+  },
+  select: {
+    terse: "content only. multiple: selector: prefix. no index = all",
+    example: `h2.0:
+## Installation
+content...
+h2.1:
+## Quick Start
+content...
+
+# single result: no prefix
+## Installation
+content...
+
+# error format
+!selector
+reason
+~suggestion1 ~suggestion2`
+  }
+};
+
+// src/cli/utils/namespace.ts
+import { basename, extname } from "path";
+function deriveNamespace(filePath) {
+  const base = basename(filePath, extname(filePath));
+  return base.toLowerCase();
+}
+
+// src/cli/utils/content-extractor.ts
+import { toString } from "mdast-util-to-string";
+import { toMarkdown } from "mdast-util-to-markdown";
+import { gfmToMarkdown } from "mdast-util-gfm";
+var PREVIEW_LENGTH = 80;
+var TRUNCATION_MARKER = "[truncated]";
+function extractMarkdown(node) {
+  if (isSectionNode(node)) {
+    const root = { type: "root", children: node.children };
+    return toMarkdown(root, { extensions: [gfmToMarkdown()] }).trimEnd();
+  }
+  return toMarkdown(node, { extensions: [gfmToMarkdown()] }).trimEnd();
+}
+function isSectionNode(node) {
+  return typeof node === "object" && node !== null && "type" in node && node.type === "section" && "children" in node;
+}
+function extractText(node) {
+  return toString(node);
+}
+function countWords(text) {
+  const trimmed = text.trim();
+  if (trimmed === "") return 0;
+  return trimmed.split(/\s+/).filter((w) => w.length > 0).length;
+}
+function getContentPreview(text, maxLen = PREVIEW_LENGTH) {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLen) return normalized;
+  return normalized.slice(0, maxLen) + "...";
+}
+function truncateContent(content, options = {}) {
+  const lines = content.split("\n");
+  const totalLines = lines.length;
+  if (options.head !== void 0 && options.head > 0) {
+    if (options.head >= totalLines) {
+      return { content, truncated: false, wordCount: countWords(content) };
+    }
+    const truncatedLines = lines.slice(0, options.head);
+    const truncatedContent = truncatedLines.join("\n") + "\n" + TRUNCATION_MARKER;
+    return {
+      content: truncatedContent,
+      truncated: true,
+      wordCount: countWords(truncatedContent)
+    };
+  }
+  if (options.tail !== void 0 && options.tail > 0) {
+    if (options.tail >= totalLines) {
+      return { content, truncated: false, wordCount: countWords(content) };
+    }
+    const truncatedLines = lines.slice(-options.tail);
+    const truncatedContent = TRUNCATION_MARKER + "\n" + truncatedLines.join("\n");
+    return {
+      content: truncatedContent,
+      truncated: true,
+      wordCount: countWords(truncatedContent)
+    };
+  }
+  return { content, truncated: false, wordCount: countWords(content) };
+}
+
+// src/cli/utils/selector-builder.ts
+function buildAvailableSelectors(tree, namespace) {
+  const selectors = [];
+  const headingCounts = {
+    1: 0,
+    2: 0,
+    3: 0,
+    4: 0,
+    5: 0,
+    6: 0
+  };
+  const blockCounts = {
+    paragraph: 0,
+    code: 0,
+    list: 0,
+    table: 0,
+    blockquote: 0
+  };
+  selectors.push(`${namespace}::root`);
+  for (const child of tree.children) {
+    if (child.type === "heading") {
+      const depth = child.depth;
+      const currentIndex = headingCounts[depth] ?? 0;
+      headingCounts[depth] = currentIndex + 1;
+      selectors.push(`${namespace}::heading:h${String(depth)}[${String(currentIndex)}]`);
+    } else {
+      const blockType = mapNodeTypeToBlockType(child.type);
+      if (blockType) {
+        const currentIndex = blockCounts[blockType] ?? 0;
+        blockCounts[blockType] = currentIndex + 1;
+        selectors.push(`${namespace}::block:${blockType}[${String(currentIndex)}]`);
+      }
+    }
+  }
+  return selectors;
+}
+function buildDocumentIndex(tree, namespace, filePath) {
+  const headings = [];
+  const blockCounts = {
+    paragraphs: 0,
+    code_blocks: 0,
+    lists: 0,
+    tables: 0,
+    blockquotes: 0
+  };
+  const headingIndices = {
+    1: 0,
+    2: 0,
+    3: 0,
+    4: 0,
+    5: 0,
+    6: 0
+  };
+  let root = null;
+  const preHeadingContent = [];
+  let foundHeading = false;
+  for (const child of tree.children) {
+    if (child.type === "heading") {
+      foundHeading = true;
+      const heading = child;
+      const depth = heading.depth;
+      const currentIndex = headingIndices[depth] ?? 0;
+      headingIndices[depth] = currentIndex + 1;
+      const text = extractText(heading);
+      let childrenCount = 0;
+      let i = tree.children.indexOf(heading) + 1;
+      while (i < tree.children.length) {
+        const nextChild = tree.children[i];
+        if (nextChild?.type === "heading" && nextChild.depth <= depth) {
+          break;
+        }
+        childrenCount++;
+        i++;
+      }
+      headings.push({
+        selector: `${namespace}::heading:h${String(depth)}[${String(currentIndex)}]`,
+        type: `heading:h${String(depth)}`,
+        depth,
+        text,
+        content_preview: getContentPreview(text),
+        truncated: false,
+        children_count: childrenCount,
+        word_count: countWords(text),
+        section_word_count: countWords(text),
+        // Simplified - just heading text
+        section_truncated: false
+      });
+    } else {
+      if (!foundHeading) {
+        preHeadingContent.push(child);
+      }
+      countBlock(child, blockCounts);
+    }
+  }
+  if (preHeadingContent.length > 0) {
+    const rootText = preHeadingContent.map((c) => extractText(c)).join("\n");
+    root = {
+      selector: `${namespace}::root`,
+      type: "root",
+      content_preview: getContentPreview(rootText),
+      truncated: false,
+      children_count: preHeadingContent.length,
+      word_count: countWords(rootText)
+    };
+  }
+  return {
+    namespace,
+    file_path: filePath,
+    root,
+    headings,
+    blocks: blockCounts
+  };
+}
+function mapNodeTypeToBlockType(type) {
+  switch (type) {
+    case "paragraph":
+      return "paragraph";
+    case "code":
+      return "code";
+    case "list":
+      return "list";
+    case "table":
+      return "table";
+    case "blockquote":
+      return "blockquote";
+    default:
+      return null;
+  }
+}
+function countBlock(node, counts) {
+  switch (node.type) {
+    case "paragraph":
+      counts.paragraphs++;
+      break;
+    case "code":
+      counts.code_blocks++;
+      break;
+    case "list":
+      counts.lists++;
+      break;
+    case "table":
+      counts.tables++;
+      break;
+    case "blockquote":
+      counts.blockquotes++;
+      break;
+  }
+}
+
+// src/cli/utils/file-reader.ts
+function isStdinPiped() {
+  return !process.stdin.isTTY;
+}
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      if (typeof chunk === "string") {
+        chunks.push(Buffer.from(chunk, "utf8"));
+      } else {
+        chunks.push(chunk);
+      }
+    });
+    process.stdin.on("end", () => {
+      const content = Buffer.concat(chunks).toString("utf8");
+      resolve(content);
+    });
+    process.stdin.on("error", (error) => {
+      reject(error);
+    });
+  });
+}
+
+// src/cli/utils/exit-codes.ts
+var ExitCode = {
+  /** All operations completed successfully */
+  SUCCESS: 0,
+  /** Complete failure (file not found, parse error, etc.) */
+  ERROR: 1,
+  /** Invalid arguments or usage */
+  USAGE_ERROR: 2
+};
+function exitWithCode(code) {
+  process.exit(code);
+}
+
+// src/cli/commands/index-command.ts
+async function indexCommand(files, options = {}) {
+  const documents = [];
+  const errors = [];
+  const useJson = options.json === true;
+  if (files.length === 0 && isStdinPiped()) {
+    await indexStdin(useJson);
+    return;
+  }
+  if (files.length === 0) {
+    const error = createErrorEntry(
+      "PARSE_ERROR",
+      "NO_FILES",
+      "No files provided. Specify files to index or pipe content via stdin."
+    );
+    outputError([error], useJson);
+    exitWithCode(ExitCode.ERROR);
+    return;
+  }
+  for (const file of files) {
+    try {
+      const result = await parseFile(file);
+      const namespace = deriveNamespace(file);
+      const index = buildDocumentIndex(result.ast, namespace, file);
+      documents.push(index);
+    } catch (error) {
+      if (error instanceof ParserError) {
+        errors.push(
+          createErrorEntry(
+            error.code,
+            error.code,
+            error.message,
+            error.filePath
+          )
+        );
+      } else if (error instanceof Error) {
+        errors.push(createErrorEntry("PROCESSING_ERROR", "UNKNOWN", error.message, file));
+      }
+    }
+  }
+  if (documents.length === 0 && errors.length > 0) {
+    outputError(errors, useJson);
+    exitWithCode(ExitCode.ERROR);
+    return;
+  }
+  if (errors.length > 0) {
+    const summary = calculateSummary(documents);
+    if (useJson) {
+      const response = formatErrorResponse(
+        "index",
+        errors,
+        documents
+      );
+      response.partial_results = documents;
+      response.data = { documents, summary };
+      response.warnings = [
+        `${String(errors.length)} of ${String(files.length)} file(s) could not be processed`
+      ];
+      console.log(JSON.stringify(response));
+    } else {
+      console.log(formatIndexText(documents));
+      console.log("");
+      console.error(formatErrorText(errors));
+    }
+    exitWithCode(ExitCode.ERROR);
+    return;
+  }
+  if (useJson) {
+    const summary = calculateSummary(documents);
+    const response = formatIndexResponse(documents, summary);
+    console.log(JSON.stringify(response));
+  } else {
+    console.log(formatIndexText(documents));
+  }
+  exitWithCode(ExitCode.SUCCESS);
+}
+function outputError(errors, useJson) {
+  if (useJson) {
+    console.log(JSON.stringify(formatErrorResponse("index", errors)));
+  } else {
+    console.error(formatErrorText(errors));
+  }
+}
+async function indexStdin(useJson) {
+  const documents = [];
+  const errors = [];
+  try {
+    const content = await readStdin();
+    const result = parseMarkdown(content);
+    const namespace = "stdin";
+    const index = buildDocumentIndex(result.ast, namespace, "<stdin>");
+    documents.push(index);
+    if (useJson) {
+      const summary = calculateSummary(documents);
+      const response = formatIndexResponse(documents, summary);
+      console.log(JSON.stringify(response));
+    } else {
+      console.log(formatIndexText(documents));
+    }
+    exitWithCode(ExitCode.SUCCESS);
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(createErrorEntry("PARSE_ERROR", "PARSE_ERROR", error.message, "<stdin>"));
+    }
+    outputError(errors, useJson);
+    exitWithCode(ExitCode.ERROR);
+  }
+}
+function calculateSummary(documents) {
+  let totalNodes = 0;
+  let totalSelectors = 0;
+  for (const doc of documents) {
+    if (doc.root) {
+      totalNodes++;
+      totalSelectors++;
+    }
+    totalNodes += doc.headings.length;
+    totalSelectors += doc.headings.length;
+    const blockCount = doc.blocks.paragraphs + doc.blocks.code_blocks + doc.blocks.lists + doc.blocks.tables + doc.blocks.blockquotes;
+    totalNodes += blockCount;
+    totalSelectors += blockCount;
+  }
+  return {
+    total_documents: documents.length,
+    total_nodes: totalNodes,
+    total_selectors: totalSelectors
+  };
+}
+
+// src/selector/types.ts
+var SelectorParseError = class _SelectorParseError extends Error {
+  code;
+  position;
+  input;
+  constructor(code, message, position, input) {
+    super(message);
+    this.name = "SelectorParseError";
+    this.code = code;
+    this.position = position;
+    this.input = input;
+    Error.captureStackTrace?.(this, _SelectorParseError);
+  }
+  /**
+   * Format error message with position context.
+   */
+  toString() {
+    const { line, column, offset } = this.position;
+    const lineStart = this.input.lastIndexOf("\n", offset - 1) + 1;
+    const lineEnd = this.input.indexOf("\n", offset);
+    const lineContent = this.input.slice(lineStart, lineEnd === -1 ? void 0 : lineEnd);
+    const pointer = " ".repeat(column - 1) + "^";
+    return `${this.message}
+  at line ${String(line)}, column ${String(column)}
+  ${lineContent}
+  ${pointer}`;
+  }
+};
+
+// src/selector/tokenizer.ts
+function tokenize(input) {
+  const tokens = [];
+  let index = 0;
+  let line = 1;
+  let column = 1;
+  const position = () => ({ line, column, offset: index });
+  const isAtEnd = () => index >= input.length;
+  const advance = () => {
+    if (!isAtEnd()) {
+      if (input[index] === "\n") {
+        line++;
+        column = 1;
+      } else {
+        column++;
+      }
+      index++;
+    }
+  };
+  const peek = (offset = 0) => {
+    const pos = index + offset;
+    return pos < input.length ? input[pos] ?? "" : "";
+  };
+  const skipWhitespace = () => {
+    while (!isAtEnd() && /\s/.test(peek())) {
+      advance();
+    }
+  };
+  const scanIdentifier = () => {
+    const start = index;
+    while (!isAtEnd() && /[a-zA-Z0-9_-]/.test(peek())) {
+      advance();
+    }
+    return input.slice(start, index);
+  };
+  const scanNumber = () => {
+    const start = index;
+    while (!isAtEnd() && /[0-9]/.test(peek())) {
+      advance();
+    }
+    return input.slice(start, index);
+  };
+  const scanString = () => {
+    const quote = peek();
+    advance();
+    const start = index;
+    while (!isAtEnd() && peek() !== quote) {
+      advance();
+    }
+    const value = input.slice(start, index);
+    advance();
+    return value;
+  };
+  const addToken = (type, value, pos) => {
+    tokens.push({ type, value, position: pos ?? position() });
+  };
+  if (input.trim() === "") {
+    addToken("EOF" /* EOF */, "");
+    return tokens;
+  }
+  while (!isAtEnd()) {
+    skipWhitespace();
+    if (isAtEnd()) break;
+    const char = peek();
+    const pos = position();
+    if (char === ":" && peek(1) === ":") {
+      advance();
+      advance();
+      addToken("NAMESPACE_SEP" /* NAMESPACE_SEP */, "::", pos);
+      continue;
+    }
+    switch (char) {
+      case "/":
+        advance();
+        addToken("SLASH" /* SLASH */, "/", pos);
+        continue;
+      case ":":
+        advance();
+        addToken("COLON" /* COLON */, ":", pos);
+        continue;
+      case ".":
+        advance();
+        addToken("DOT" /* DOT */, ".", pos);
+        continue;
+      case "-":
+        advance();
+        addToken("HYPHEN" /* HYPHEN */, "-", pos);
+        continue;
+      case ",":
+        advance();
+        addToken("COMMA" /* COMMA */, ",", pos);
+        continue;
+      case "[":
+        advance();
+        addToken("OPEN_BRACKET" /* OPEN_BRACKET */, "[", pos);
+        continue;
+      case "]":
+        advance();
+        addToken("CLOSE_BRACKET" /* CLOSE_BRACKET */, "]", pos);
+        continue;
+      case "?":
+        advance();
+        addToken("QUESTION" /* QUESTION */, "?", pos);
+        continue;
+      case "&":
+        advance();
+        addToken("AMPERSAND" /* AMPERSAND */, "&", pos);
+        continue;
+      case "=":
+        advance();
+        addToken("EQUALS" /* EQUALS */, "=", pos);
+        continue;
+      case '"':
+      case "'": {
+        const strPos = position();
+        const str = scanString();
+        addToken("STRING" /* STRING */, str, strPos);
+        continue;
+      }
+    }
+    if (/[0-9]/.test(char)) {
+      const numPos = position();
+      const num = scanNumber();
+      addToken("NUMBER" /* NUMBER */, num, numPos);
+      continue;
+    }
+    if (/[a-zA-Z_]/.test(char)) {
+      const identPos = position();
+      const identifier = scanIdentifier();
+      switch (identifier) {
+        case "root":
+          addToken("ROOT" /* ROOT */, identifier, identPos);
+          break;
+        case "heading":
+          addToken("HEADING" /* HEADING */, identifier, identPos);
+          break;
+        case "section":
+          addToken("SECTION" /* SECTION */, identifier, identPos);
+          break;
+        case "block":
+          addToken("BLOCK" /* BLOCK */, identifier, identPos);
+          break;
+        case "page":
+          addToken("PAGE" /* PAGE */, identifier, identPos);
+          break;
+        default:
+          addToken("IDENTIFIER" /* IDENTIFIER */, identifier, identPos);
+      }
+      continue;
+    }
+    throw new SelectorParseError(
+      "INVALID_SYNTAX",
+      `Invalid character '${char}' in selector`,
+      pos,
+      input
+    );
+  }
+  addToken("EOF" /* EOF */, "");
+  return tokens;
+}
+
+// src/selector/parser.ts
+var validHeadingLevels = ["h1", "h2", "h3", "h4", "h5", "h6"];
+var validBlockTypes = ["paragraph", "list", "code", "table", "blockquote"];
+var blockAliases = {
+  para: "paragraph",
+  paragraph: "paragraph",
+  list: "list",
+  code: "code",
+  table: "table",
+  quote: "blockquote",
+  blockquote: "blockquote"
+};
+function parseSelector(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new SelectorParseError(
+      "EMPTY_SELECTOR",
+      "Selector cannot be empty",
+      { line: 1, column: 1, offset: 0 },
+      input
+    );
+  }
+  const tokens = tokenize(input);
+  const parser = new Parser(tokens, input);
+  return parser.parse();
+}
+var Parser = class {
+  tokens;
+  current = 0;
+  input;
+  constructor(tokens, input) {
+    this.tokens = tokens;
+    this.input = input;
+  }
+  parse() {
+    const segments = [];
+    let namespace;
+    let queryParams;
+    const startPos = this.peek().position;
+    if (this.check("IDENTIFIER" /* IDENTIFIER */) && this.peekType(1) === "NAMESPACE_SEP" /* NAMESPACE_SEP */) {
+      const nsToken = this.advance();
+      namespace = nsToken.value;
+      this.consume("NAMESPACE_SEP" /* NAMESPACE_SEP */, "Expected '::' after namespace");
+    }
+    if (this.check("EOF" /* EOF */)) {
+      throw this.error("INVALID_SYNTAX", "Expected at least one path segment");
+    }
+    do {
+      segments.push(this.parsePathSegment());
+    } while (this.match("SLASH" /* SLASH */));
+    if (segments.length > 0) {
+      void segments[segments.length - 1];
+    }
+    if (this.match("QUESTION" /* QUESTION */)) {
+      queryParams = this.parseQueryParams();
+    }
+    if (!this.check("EOF" /* EOF */)) {
+      throw this.error("INVALID_SYNTAX", `Unexpected token '${this.peek().value}' after selector`);
+    }
+    return {
+      type: "selector" /* SELECTOR */,
+      namespace,
+      segments,
+      queryParams,
+      position: startPos
+    };
+  }
+  parsePathSegment() {
+    const startPos = this.peek().position;
+    let nodeType;
+    let subtype;
+    let index;
+    if (this.match("ROOT" /* ROOT */)) {
+      nodeType = "root";
+    } else if (this.match("HEADING" /* HEADING */)) {
+      nodeType = "heading";
+      if (!this.match("COLON" /* COLON */)) {
+        throw this.error("INVALID_SYNTAX", `Expected ':' after 'heading'`);
+      }
+      if (!this.check("IDENTIFIER" /* IDENTIFIER */)) {
+        throw this.error(
+          "INVALID_HEADING_LEVEL",
+          `Expected heading level (h1-h6) after 'heading:'`
+        );
+      }
+      const levelToken = this.advance();
+      const level = levelToken.value;
+      if (!validHeadingLevels.includes(level)) {
+        throw new SelectorParseError(
+          "INVALID_HEADING_LEVEL",
+          `Invalid heading level '${level}' - must be h1-h6`,
+          levelToken.position,
+          this.input
+        );
+      }
+      subtype = level;
+    } else if (this.match("BLOCK" /* BLOCK */)) {
+      nodeType = "block";
+      if (!this.match("COLON" /* COLON */)) {
+        throw this.error("INVALID_SYNTAX", `Expected ':' after 'block'`);
+      }
+      if (!this.check("IDENTIFIER" /* IDENTIFIER */)) {
+        throw this.error("INVALID_BLOCK_TYPE", `Expected block type after 'block:'`);
+      }
+      const typeToken = this.advance();
+      const type = typeToken.value;
+      if (!validBlockTypes.includes(type)) {
+        throw new SelectorParseError(
+          "INVALID_BLOCK_TYPE",
+          `Invalid block type '${type}' - must be one of: ${validBlockTypes.join(", ")}`,
+          typeToken.position,
+          this.input
+        );
+      }
+      subtype = type;
+    } else if (this.match("SECTION" /* SECTION */)) {
+      nodeType = "section";
+    } else if (this.match("PAGE" /* PAGE */)) {
+      nodeType = "page";
+    } else if (this.check("IDENTIFIER" /* IDENTIFIER */)) {
+      const identValue = this.peek().value;
+      if (validHeadingLevels.includes(identValue)) {
+        this.advance();
+        nodeType = "heading";
+        subtype = identValue;
+      } else if (identValue in blockAliases) {
+        this.advance();
+        nodeType = "block";
+        subtype = blockAliases[identValue];
+      } else {
+        throw new SelectorParseError(
+          "INVALID_SYNTAX",
+          `Unknown selector '${identValue}' - use h1-h6, code, para, list, table, quote, root, or section`,
+          this.peek().position,
+          this.input
+        );
+      }
+    } else if (this.check("SLASH" /* SLASH */) || this.check("EOF" /* EOF */)) {
+      throw this.error(
+        "INVALID_SYNTAX",
+        "Expected selector type"
+      );
+    } else {
+      throw this.error(
+        "INVALID_SYNTAX",
+        `Expected selector type`
+      );
+    }
+    if (this.match("DOT" /* DOT */)) {
+      if (!this.check("NUMBER" /* NUMBER */)) {
+        throw this.error("INVALID_INDEX", `Expected number after '.'`);
+      }
+      const indexToken = this.advance();
+      const numValue = parseInt(indexToken.value, 10);
+      if (numValue < 0) {
+        throw this.error("INVALID_INDEX", `Index must be non-negative`);
+      }
+      index = numValue;
+      index = this.parseIndexList(numValue);
+    } else if (this.match("OPEN_BRACKET" /* OPEN_BRACKET */)) {
+      if (!this.check("NUMBER" /* NUMBER */)) {
+        throw this.error("INVALID_INDEX", `Expected number inside brackets`);
+      }
+      const indexToken = this.advance();
+      const numValue = parseInt(indexToken.value, 10);
+      if (numValue < 0) {
+        throw this.error("INVALID_INDEX", `Index must be non-negative`);
+      }
+      index = numValue;
+      index = this.parseIndexList(numValue);
+      if (!this.match("CLOSE_BRACKET" /* CLOSE_BRACKET */)) {
+        throw this.error("UNCLOSED_BRACKET", `Unclosed bracket, expected ']'`);
+      }
+    }
+    return {
+      type: "path_segment" /* PATH_SEGMENT */,
+      nodeType,
+      subtype,
+      index,
+      position: startPos
+    };
+  }
+  /**
+   * Parse index list after initial number.
+   * Supports:
+   * - Single: 1 → returns 1
+   * - Range: 1-3 → returns [1, 2, 3]
+   * - Comma list: 1,3,5 → returns [1, 3, 5]
+   */
+  parseIndexList(firstIndex) {
+    const indices = [firstIndex];
+    while (true) {
+      if (this.match("HYPHEN" /* HYPHEN */)) {
+        if (!this.check("NUMBER" /* NUMBER */)) {
+          throw this.error("INVALID_INDEX", `Expected number after '-' for range`);
+        }
+        const endToken = this.advance();
+        const endIndex = parseInt(endToken.value, 10);
+        if (endIndex < firstIndex) {
+          throw this.error("INVALID_INDEX", `Range end must be >= start`);
+        }
+        for (let i = firstIndex + 1; i <= endIndex; i++) {
+          indices.push(i);
+        }
+        break;
+      } else if (this.match("COMMA" /* COMMA */)) {
+        if (!this.check("NUMBER" /* NUMBER */)) {
+          throw this.error("INVALID_INDEX", `Expected number after ','`);
+        }
+        const nextToken = this.advance();
+        const nextIndex = parseInt(nextToken.value, 10);
+        indices.push(nextIndex);
+      } else {
+        break;
+      }
+    }
+    return indices.length === 1 ? indices[0] : indices;
+  }
+  parseQueryParams() {
+    const params = [];
+    const startPos = this.peek().position;
+    if (!this.check("IDENTIFIER" /* IDENTIFIER */)) {
+      throw this.error("MALFORMED_QUERY", `Expected parameter name`);
+    }
+    const key = this.advance().value;
+    if (!this.match("EQUALS" /* EQUALS */)) {
+      throw this.error("MALFORMED_QUERY", `Expected '=' after parameter name '${key}'`);
+    }
+    let value;
+    if (this.check("STRING" /* STRING */)) {
+      value = this.advance().value;
+    } else if (this.check("IDENTIFIER" /* IDENTIFIER */)) {
+      value = this.advance().value;
+    } else if (this.check("NUMBER" /* NUMBER */)) {
+      value = this.advance().value;
+    } else {
+      value = "";
+    }
+    params.push({ key, value, position: startPos });
+    while (this.match("AMPERSAND" /* AMPERSAND */)) {
+      const paramStart = this.peek().position;
+      if (!this.check("IDENTIFIER" /* IDENTIFIER */)) {
+        throw this.error("MALFORMED_QUERY", `Expected parameter name`);
+      }
+      const paramKey = this.advance().value;
+      if (!this.match("EQUALS" /* EQUALS */)) {
+        throw this.error("MALFORMED_QUERY", `Expected '=' after parameter name '${paramKey}'`);
+      }
+      let paramValue;
+      if (this.check("STRING" /* STRING */)) {
+        paramValue = this.advance().value;
+      } else if (this.check("IDENTIFIER" /* IDENTIFIER */)) {
+        paramValue = this.advance().value;
+      } else if (this.check("NUMBER" /* NUMBER */)) {
+        paramValue = this.advance().value;
+      } else {
+        paramValue = "";
+      }
+      params.push({ key: paramKey, value: paramValue, position: paramStart });
+    }
+    return params;
+  }
+  check(type) {
+    return this.peek().type === type;
+  }
+  peekType(offset = 0) {
+    const pos = this.current + offset;
+    return pos < this.tokens.length ? this.tokens[pos]?.type ?? "EOF" /* EOF */ : "EOF" /* EOF */;
+  }
+  match(...types) {
+    for (const type of types) {
+      if (this.check(type)) {
+        this.advance();
+        return true;
+      }
+    }
+    return false;
+  }
+  advance() {
+    if (!this.check("EOF" /* EOF */)) {
+      this.current++;
+    }
+    return this.previous();
+  }
+  peek() {
+    return this.tokens[this.current] ?? this.tokens[this.tokens.length - 1];
+  }
+  previous() {
+    return this.tokens[this.current - 1] ?? this.tokens[0];
+  }
+  consume(type, message) {
+    if (this.check(type)) {
+      return this.advance();
+    }
+    throw this.error("INVALID_SYNTAX", message);
+  }
+  error(code, message) {
+    return new SelectorParseError(code, message, this.peek().position, this.input);
+  }
+};
+
+// src/resolver/levenshtein.ts
+function levenshteinDistance(str1, str2) {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  if (len1 < len2) {
+    return levenshteinDistance(str2, str1);
+  }
+  if (len2 === 0) {
+    return len1;
+  }
+  let prevRow = Array.from({ length: len2 + 1 }, (_, i) => i);
+  let currRow = Array.from({ length: len2 + 1 }, () => 0);
+  for (let i = 1; i <= len1; i++) {
+    currRow[0] = i;
+    for (let j = 1; j <= len2; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      const prevRowVal = prevRow[j] ?? 0;
+      const prevRowPrevVal = prevRow[j - 1] ?? 0;
+      currRow[j] = Math.min(
+        (currRow[j - 1] ?? 0) + 1,
+        // insertion
+        prevRowVal + 1,
+        // deletion
+        prevRowPrevVal + cost
+        // substitution
+      );
+    }
+    [prevRow, currRow] = [currRow, prevRow];
+  }
+  return prevRow[len2] ?? 0;
+}
+
+// src/resolver/suggestions.ts
+var SuggestionEngine = class {
+  candidates;
+  constructor(candidates) {
+    this.candidates = candidates;
+  }
+  /**
+   * Get suggestions for a query selector.
+   *
+   * @param query - The query selector
+   * @param options - Configuration options
+   * @returns Ranked array of suggestions
+   *
+   * @example
+   * ```typescript
+   * const engine = new SuggestionEngine(['heading:h1[0]', 'heading:h2[0]', 'block:code[0]']);
+   * const suggestions = engine.getSuggestions('headng:h1[0]'); // typo in 'heading'
+   * // Returns: [{ selector: 'heading:h1[0]', distance: 1, ratio: 0.95, reason: 'typo_correction' }, ...]
+   * ```
+   */
+  getSuggestions(query, options = {}) {
+    const { maxResults = 5, minRatio = 0.4, includeExact = true } = options;
+    const normalizedQuery = query.toLowerCase().trim();
+    const results = [];
+    if (includeExact) {
+      const exactMatches = this.candidates.filter(
+        (candidate) => candidate.toLowerCase() === normalizedQuery
+      );
+      for (const selector of exactMatches) {
+        results.push({
+          selector,
+          distance: 0,
+          ratio: 1,
+          reason: "exact_match",
+          normalizedSelector: selector.toLowerCase()
+        });
+      }
+    }
+    const hasExactMatch = results.length > 0;
+    const fuzzyMatches = this.findFuzzyMatches(normalizedQuery, hasExactMatch, minRatio);
+    results.push(...fuzzyMatches);
+    return this.sortAndLimitResults(results, maxResults);
+  }
+  /**
+   * Find fuzzy matches using Levenshtein distance.
+   */
+  findFuzzyMatches(normalizedQuery, skipExact, minRatio) {
+    const results = [];
+    for (const candidate of this.candidates) {
+      const normalizedCandidate = candidate.toLowerCase().trim();
+      if (normalizedCandidate === normalizedQuery) {
+        continue;
+      }
+      const distance = levenshteinDistance(normalizedQuery, normalizedCandidate);
+      const maxLen = Math.max(normalizedQuery.length, normalizedCandidate.length);
+      const ratio = maxLen === 0 ? 1 : (maxLen - distance) / maxLen;
+      if (ratio >= minRatio) {
+        const reason = distance <= 2 ? "typo_correction" : "fuzzy_match";
+        results.push({
+          selector: candidate,
+          distance,
+          ratio,
+          reason,
+          normalizedSelector: normalizedCandidate
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Sort results by ratio (desc), distance (asc), length (asc) and limit to maxResults.
+   */
+  sortAndLimitResults(results, maxResults) {
+    return results.sort((a, b) => {
+      if (Math.abs(b.ratio - a.ratio) > 1e-3) {
+        return b.ratio - a.ratio;
+      }
+      if (a.distance !== b.distance) {
+        return a.distance - b.distance;
+      }
+      return a.selector.length - b.selector.length;
+    }).slice(0, maxResults).map(({ normalizedSelector: _, ...suggestion }) => suggestion);
+  }
+};
+
+// src/resolver/single-resolver.ts
+function resolveSingle(tree, namespace, selector, availableSelectors) {
+  try {
+    if (selector.namespace && selector.namespace !== namespace) {
+      return createNamespaceError(selector, [namespace], availableSelectors);
+    }
+    const context = {
+      namespace,
+      path: [],
+      currentNode: tree,
+      segmentIndex: 0,
+      totalSegments: selector.segments.length
+    };
+    const result = resolvePathSegments(context, selector.segments);
+    if (result.success) {
+      const lastSeg = selector.segments[selector.segments.length - 1];
+      const indices = Array.isArray(lastSeg?.index) ? lastSeg.index : void 0;
+      const results = result.nodes.map(({ node, path }, idx) => ({
+        namespace,
+        node,
+        selector: selectorToString(selector, indices?.[idx]),
+        path,
+        wordCount: estimateWordCount(node),
+        childrenAvailable: hasChildren(node)
+      }));
+      return {
+        success: true,
+        results
+      };
+    } else {
+      const engine = new SuggestionEngine(availableSelectors);
+      const suggestions = engine.getSuggestions(selectorToString(selector));
+      const error = {
+        type: result.errorType,
+        message: result.errorMessage,
+        selector: selectorToString(selector),
+        suggestions
+      };
+      const failedSegment = selector.segments[result.failedAtSegment];
+      if (failedSegment) {
+        error.failedSegment = failedSegment;
+      }
+      return {
+        success: false,
+        error,
+        partialResults: result.partialResults
+      };
+    }
+  } catch (error) {
+    const errorOut = {
+      type: "INVALID_PATH",
+      message: error instanceof Error ? error.message : "Unknown error",
+      selector: selectorToString(selector),
+      suggestions: []
+    };
+    return {
+      success: false,
+      error: errorOut
+    };
+  }
+}
+function resolvePathSegments(context, segments) {
+  let currentNodes = [{ node: context.currentNode, path: [...context.path] }];
+  const partialResults = [];
+  const maxDepth = DEFAULT_MAX_DEPTH;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (!segment) {
+      return {
+        success: false,
+        errorType: "SELECTOR_NOT_FOUND",
+        errorMessage: `Invalid segment at index ${i}`,
+        failedAtSegment: i
+      };
+    }
+    context.segmentIndex = i;
+    const isLastSegment = i === segments.length - 1;
+    if (i >= maxDepth) {
+      return {
+        success: false,
+        errorType: "SELECTOR_NOT_FOUND",
+        errorMessage: `Selector depth ${i + 1} exceeds maximum of ${maxDepth}`,
+        failedAtSegment: i,
+        partialResults
+      };
+    }
+    if (segment.nodeType === "root") {
+      if (currentNodes[0]?.node.type !== "root") {
+        return {
+          success: false,
+          errorType: "SELECTOR_NOT_FOUND",
+          errorMessage: "Root segment can only be used at the beginning",
+          failedAtSegment: i
+        };
+      }
+      currentNodes = currentNodes.map(({ node, path }) => ({ node, path: [...path, node] }));
+      continue;
+    }
+    const currentNode = currentNodes[0]?.node;
+    const currentPath = currentNodes[0]?.path ?? [];
+    const matches = findMatchingChildren(currentNode, segment);
+    if (matches.length === 0) {
+      return {
+        success: false,
+        errorType: "SELECTOR_NOT_FOUND",
+        errorMessage: `No matches found for segment at index ${i}`,
+        failedAtSegment: i,
+        partialResults
+      };
+    }
+    if (segment.index !== void 0) {
+      const indices = Array.isArray(segment.index) ? segment.index : [segment.index];
+      const maxIndex = Math.max(...indices);
+      if (maxIndex >= matches.length) {
+        const subtype = segment.subtype ? ":" + segment.subtype : "";
+        return {
+          success: false,
+          errorType: "INDEX_OUT_OF_RANGE",
+          errorMessage: `Index ${maxIndex} out of range (only ${matches.length} ${segment.nodeType}${subtype}(s) found)`,
+          failedAtSegment: i,
+          partialResults
+        };
+      }
+      currentNodes = indices.map((idx) => {
+        const selected = matches[idx];
+        return { node: selected, path: [...currentPath, selected] };
+      });
+    } else if (isLastSegment) {
+      currentNodes = matches.map((m) => ({ node: m, path: [...currentPath, m] }));
+    } else {
+      currentNodes = [{ node: matches[0], path: [...currentPath, matches[0]] }];
+    }
+    partialResults.push({
+      namespace: context.namespace,
+      node: currentNodes[0]?.node,
+      selector: segmentToString(segment),
+      path: currentNodes[0]?.path ?? [],
+      wordCount: estimateWordCount(currentNodes[0]?.node),
+      childrenAvailable: hasChildren(currentNodes[0]?.node)
+    });
+  }
+  return {
+    success: true,
+    nodes: currentNodes
+  };
+}
+function findMatchingChildren(parent, segment) {
+  if (!parent?.children || !Array.isArray(parent.children)) {
+    return [];
+  }
+  const matches = [];
+  switch (segment.nodeType) {
+    case "heading":
+      if (segment.subtype?.startsWith("h")) {
+        const depth = parseInt(segment.subtype.slice(1), 10);
+        const children = parent.children;
+        for (let i = 0; i < children.length; i++) {
+          const child = children[i];
+          if (child.type === "heading" && child.depth === depth) {
+            const sectionChildren = [child];
+            for (let j = i + 1; j < children.length; j++) {
+              const sibling = children[j];
+              if (sibling.type === "heading" && sibling.depth <= depth) {
+                break;
+              }
+              sectionChildren.push(sibling);
+            }
+            matches.push({
+              type: "section",
+              depth,
+              children: sectionChildren,
+              position: child.position
+            });
+          }
+        }
+      }
+      break;
+    case "section":
+    case "page":
+      break;
+    case "block":
+      if (segment.subtype) {
+        for (const child of parent.children) {
+          if (child.type === segment.subtype) {
+            matches.push(child);
+          }
+        }
+      }
+      break;
+  }
+  return matches;
+}
+function estimateWordCount(node) {
+  if (!node) return 0;
+  if (node.value && typeof node.value === "string") {
+    return node.value.trim().split(/\s+/).filter((w) => w.length > 0).length;
+  }
+  if (node.children && Array.isArray(node.children)) {
+    let count = 0;
+    for (const child of node.children) {
+      count += estimateWordCount(child);
+    }
+    return count;
+  }
+  return 0;
+}
+function hasChildren(node) {
+  return node?.children && Array.isArray(node.children) && node.children.length > 0;
+}
+function selectorToString(selector, resultIndex) {
+  let result = "";
+  if (selector.namespace) {
+    result += `${selector.namespace}::`;
+  }
+  result += selector.segments.map((seg, i) => {
+    const isLast = i === selector.segments.length - 1;
+    if (isLast && resultIndex !== void 0) {
+      return segmentToStringWithIndex(seg, resultIndex);
+    }
+    return segmentToString(seg);
+  }).join("/");
+  if (selector.queryParams && selector.queryParams.length > 0) {
+    const params = selector.queryParams.map((p) => `${p.key}=${p.value}`).join("&");
+    result += `?${params}`;
+  }
+  return result;
+}
+function segmentToStringWithIndex(segment, index) {
+  let segStr = segment.nodeType;
+  if (segment.subtype) {
+    segStr += `:${segment.subtype}`;
+  }
+  segStr += `.${index}`;
+  return segStr;
+}
+function segmentToString(segment) {
+  let segStr = segment.nodeType;
+  if (segment.subtype) {
+    segStr += `:${segment.subtype}`;
+  }
+  if (segment.index !== void 0) {
+    const idx = segment.index;
+    if (Array.isArray(idx)) {
+      segStr += `.${idx.join(",")}`;
+    } else {
+      segStr += `.${idx}`;
+    }
+  }
+  return segStr;
+}
+function createNamespaceError(selector, availableNamespaces, availableSelectors) {
+  const engine = new SuggestionEngine(availableNamespaces);
+  const nsSuggestions = engine.getSuggestions(selector.namespace || "");
+  const suggestions = nsSuggestions.map((s) => ({
+    selector: `${s.selector}::${selectorToString(selector).replace(/^[^:]+::/, "")}`,
+    distance: s.distance,
+    ratio: s.ratio,
+    reason: s.reason
+  }));
+  return {
+    success: false,
+    error: {
+      type: "NAMESPACE_NOT_FOUND",
+      message: `Namespace '${selector.namespace}' not found. Available namespaces: ${availableNamespaces.join(", ")}`,
+      selector: selectorToString(selector),
+      suggestions
+    }
+  };
+}
+
+// src/resolver/multi-resolver.ts
+function resolveMulti(documents, selector) {
+  if (selector.namespace) {
+    return resolveInNamespace(documents, selector);
+  }
+  return resolveAcrossAll(documents, selector);
+}
+function resolveInNamespace(documents, selector) {
+  const targetDoc = documents.find((doc) => doc.namespace === selector.namespace);
+  if (!targetDoc) {
+    const availableNamespaces = documents.map((doc) => doc.namespace);
+    const engine = new SuggestionEngine(availableNamespaces);
+    const nsSuggestions = engine.getSuggestions(selector.namespace || "");
+    const suggestions = nsSuggestions.map((s) => ({
+      selector: `${s.selector}::${selectorToString2(selector).replace(/^[^:]+::/, "")}`,
+      distance: s.distance,
+      ratio: s.ratio,
+      reason: s.reason
+    }));
+    return {
+      success: false,
+      error: {
+        type: "NAMESPACE_NOT_FOUND",
+        message: `Namespace '${selector.namespace}' not found. Available namespaces: ${availableNamespaces.join(", ")}`,
+        selector: selectorToString2(selector),
+        suggestions
+      }
+    };
+  }
+  return resolveSingle(targetDoc.tree, targetDoc.namespace, selector, targetDoc.availableSelectors);
+}
+function resolveAcrossAll(documents, selector) {
+  const outcomes = [];
+  for (const doc of documents) {
+    const outcome = resolveSingle(doc.tree, doc.namespace, selector, doc.availableSelectors);
+    outcomes.push(outcome);
+  }
+  return mergeOutcomes(outcomes, selector, documents);
+}
+function mergeOutcomes(outcomes, selector, documents) {
+  const allResults = [];
+  const allErrors = [];
+  let hasSuccess = false;
+  for (const outcome of outcomes) {
+    if (outcome.success) {
+      allResults.push(...outcome.results);
+      hasSuccess = true;
+    } else {
+      allErrors.push(outcome.error);
+    }
+  }
+  if (hasSuccess) {
+    return {
+      success: true,
+      results: allResults
+    };
+  }
+  const allSelectors = documents.flatMap((doc) => doc.availableSelectors);
+  const engine = new SuggestionEngine(allSelectors);
+  const suggestions = engine.getSuggestions(selectorToString2(selector));
+  return {
+    success: false,
+    error: {
+      type: "SELECTOR_NOT_FOUND",
+      message: "No matches found in any document",
+      selector: selectorToString2(selector),
+      suggestions
+    }
+  };
+}
+function selectorToString2(selector) {
+  let result = "";
+  if (selector.namespace) {
+    result += `${selector.namespace}::`;
+  }
+  result += selector.segments.map((seg) => {
+    let segStr = seg.nodeType;
+    if (seg.subtype) {
+      segStr += `:${seg.subtype}`;
+    }
+    if (seg.index !== void 0) {
+      segStr += `[${seg.index}]`;
+    }
+    return segStr;
+  }).join("/");
+  if (selector.queryParams && selector.queryParams.length > 0) {
+    const params = selector.queryParams.map((p) => `${p.key}=${p.value}`).join("&");
+    result += `?${params}`;
+  }
+  return result;
+}
+
+// src/cli/commands/select-command.ts
+async function selectCommand(selector, files, options = {}) {
+  const useJson = options.json === true;
+  if (files.length === 0) {
+    const error = createErrorEntry(
+      "PARSE_ERROR",
+      "NO_FILES",
+      "No files provided. Specify files to search."
+    );
+    outputError2([error], useJson);
+    exitWithCode(ExitCode.ERROR);
+    return;
+  }
+  let selectorAst;
+  try {
+    selectorAst = parseSelector(selector);
+  } catch (error) {
+    if (error instanceof SelectorParseError) {
+      const errorEntry = createErrorEntry(
+        "INVALID_SELECTOR",
+        error.code,
+        error.message,
+        void 0,
+        selector
+      );
+      outputError2([errorEntry], useJson);
+      exitWithCode(ExitCode.ERROR);
+      return;
+    }
+    throw error;
+  }
+  const truncateOptions = {};
+  if (selectorAst.queryParams) {
+    for (const param of selectorAst.queryParams) {
+      if (param.key === "head") {
+        const value = parseInt(param.value, 10);
+        if (!isNaN(value) && value > 0) {
+          truncateOptions.head = value;
+        }
+      } else if (param.key === "tail") {
+        const value = parseInt(param.value, 10);
+        if (!isNaN(value) && value > 0) {
+          truncateOptions.tail = value;
+        }
+      }
+    }
+  }
+  const documents = [];
+  const parseErrors = [];
+  for (const file of files) {
+    try {
+      const result = await parseFile(file);
+      const namespace = deriveNamespace(file);
+      const selectors = buildAvailableSelectors(result.ast, namespace);
+      documents.push({
+        namespace,
+        tree: result.ast,
+        availableSelectors: selectors
+      });
+    } catch (error) {
+      if (error instanceof ParserError) {
+        parseErrors.push(
+          createErrorEntry(
+            error.code,
+            error.code,
+            error.message,
+            error.filePath
+          )
+        );
+      } else if (error instanceof Error) {
+        parseErrors.push(createErrorEntry("PROCESSING_ERROR", "UNKNOWN", error.message, file));
+      }
+    }
+  }
+  if (documents.length === 0) {
+    outputError2(parseErrors, useJson);
+    exitWithCode(ExitCode.ERROR);
+    return;
+  }
+  const outcome = resolveMulti(documents, selectorAst);
+  if (outcome.success) {
+    const matches = formatMatches(outcome.results, truncateOptions);
+    if (useJson) {
+      const response = formatSelectResponse(matches, []);
+      console.log(JSON.stringify(response));
+    } else {
+      console.log(formatSelectText(matches, []));
+    }
+    exitWithCode(ExitCode.SUCCESS);
+    return;
+  }
+  const err = outcome.error;
+  const unresolved = [
+    {
+      selector: err.selector,
+      reason: err.message,
+      suggestions: err.suggestions.map((s) => s.selector)
+    }
+  ];
+  if (useJson) {
+    const response = formatSelectResponse([], unresolved);
+    console.log(JSON.stringify(response));
+  } else {
+    console.log(formatSelectText([], unresolved));
+  }
+  exitWithCode(ExitCode.ERROR);
+}
+function outputError2(errors, useJson) {
+  if (useJson) {
+    console.log(JSON.stringify(formatErrorResponse("select", errors)));
+  } else {
+    console.error(formatErrorText(errors));
+  }
+}
+var SELECTABLE_BLOCKS = {
+  paragraph: "para",
+  code: "code",
+  list: "list",
+  table: "table",
+  blockquote: "quote"
+};
+function formatMatches(results, truncateOpts) {
+  return results.map((result) => {
+    const { content, truncated } = truncateContent(extractMarkdown(result.node), truncateOpts);
+    const childrenAvailable = [];
+    if (result.childrenAvailable && result.node.children) {
+      const typeCounts = {};
+      for (const child of result.node.children) {
+        const childType = String(child.type);
+        if (childType === "heading" && "depth" in child) {
+          const level = `h${child.depth}`;
+          const idx = typeCounts[level] ?? 0;
+          typeCounts[level] = idx + 1;
+          const childText = extractMarkdown(child);
+          const childPreview = childText.slice(0, 80).replace(/^#+\s*/, "");
+          childrenAvailable.push({
+            selector: `${level}[${idx}]`,
+            type: "heading",
+            preview: childPreview
+          });
+        } else if (childType in SELECTABLE_BLOCKS) {
+          const shorthand = SELECTABLE_BLOCKS[childType];
+          const idx = typeCounts[shorthand] ?? 0;
+          typeCounts[shorthand] = idx + 1;
+          const childText = extractMarkdown(child);
+          const childPreview = childText.slice(0, 80);
+          childrenAvailable.push({
+            selector: `${shorthand}[${idx}]`,
+            type: childType,
+            preview: childPreview
+          });
+        }
+      }
+    }
+    return {
+      selector: String(result.selector),
+      type: String(result.node.type),
+      content,
+      truncated,
+      children_available: childrenAvailable
+    };
+  });
+}
+
+// src/cli/commands/format-command.ts
+function formatCommand(command, options = {}) {
+  const style = options.example ? "example" : "terse";
+  if (command === "index") {
+    console.log(FORMAT_SPECS.index[style]);
+  } else if (command === "select") {
+    console.log(FORMAT_SPECS.select[style]);
+  } else {
+    console.log("# index");
+    console.log(FORMAT_SPECS.index[style]);
+    console.log("");
+    console.log("# select");
+    console.log(FORMAT_SPECS.select[style]);
+  }
+}
+
+// src/cli/index.ts
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var program = new Command();
+program.name("mdsel").description(pkg.description).version(pkg.version).option("--json", "Output JSON instead of minimal text");
+program.command("index", { isDefault: true }).description("Parse documents and emit selector inventory").argument("<files...>", "Markdown files to index").action(async (files) => {
+  try {
+    const globalOpts = program.opts();
+    await indexCommand(files, { json: globalOpts.json });
+  } catch (error) {
+    console.error("Unexpected error:", error);
+    process.exit(ExitCode.ERROR);
+  }
+});
+program.command("select").description("Retrieve content via selectors").argument("<selector>", "Selector string").argument("[files...]", "Markdown files to search").action(async (selector, files) => {
+  try {
+    const globalOpts = program.opts();
+    await selectCommand(selector, files, { json: globalOpts.json });
+  } catch (error) {
+    console.error("Unexpected error:", error);
+    process.exit(ExitCode.ERROR);
+  }
+});
+program.command("format").description("Output format specification for tool descriptions").argument("[command]", "Command to describe (index, select, or omit for all)").option("--example", "Show example output instead of terse spec").action((command, options) => {
+  formatCommand(command, options);
+});
+program.parse();