mdsel 0.1.0 → 0.1.1

package/README.md

@@ -4,6 +4,57 @@ Declarative Markdown semantic selection CLI for LLM agents.
 
 mdsel parses Markdown documents into semantic trees and exposes machine-addressable selectors for every meaningful chunk. It enables LLMs to request exactly the content they want—no more, no less—without loading entire files into context.
 
+## Demo
+
+**1. Index a document to see its structure:**
+
+```bash
+$ mdsel README.md
+h1 mdsel
+ h2 Demo
+ h2 Installation
+ h2 Quick Start
+ h2 Commands
+  h3 index
+  h3 select
+ h2 Selectors
+  h3 Syntax
+  h3 Node Types
+  h3 Index Syntax
+  h3 Examples
+  h3 Index Semantics
+ h2 Output Format
+ h2 Error Handling
+ h2 Development
+ h2 License
+---
+code:19 para:23 list:5 table:3
+```
+
+**2. Select specific content by selector:**
+
+```bash
+$ mdsel README.md h2.1
+```
+```
+## Installation
+
+​```bash
+npm install -g mdsel
+​```
+
+**Requirements**: Node.js >=18.0.0
+```
+
+**3. Drill into nested content:**
+
+```bash
+$ mdsel README.md h2.1/code.0
+```
+```
+npm install -g mdsel
+```
+
 ## Installation
 
 ```bash
@@ -16,41 +67,50 @@ npm install -g mdsel
 
 ```bash
 # Index a document to discover available selectors
-mdsel index README.md
+mdsel README.md
 
 # Select a specific heading (shorthand)
-mdsel select h1.0 README.md
+mdsel README.md h1.0
 
 # Select the first code block under a heading
-mdsel select "h2.0/code.0" README.md
+mdsel README.md "h2.0/code.0"
 
 # Select multiple headings with comma syntax
-mdsel select h2.0,2 README.md
+mdsel README.md h2.0,2
+
+# Select multiple selectors at once
+mdsel README.md h2.0 h2.1 code.0
 
 # Limit output to first 10 lines
-mdsel select "h2.0?head=10" README.md
+mdsel README.md "h2.0?head=10"
 
 # Limit output to last 5 lines
-mdsel select "h2.0?tail=5" README.md
+mdsel README.md "h2.0?tail=5"
 
 # Use JSON output for programmatic consumption
-mdsel index README.md --json
+mdsel --json README.md
 ```
 
-## Commands
-
-### index
+## Usage
 
-Parse documents and emit selector inventory.
+mdsel automatically detects whether arguments are files or selectors:
 
 ```bash
-mdsel index <files...>
-mdsel index <files...> --json
+mdsel <files...> [selectors...]
+mdsel [options] <files...> [selectors...]
 ```
 
-**Example**:
+**Options**:
+- `--json` - Output JSON instead of text
+
+### Index (files only)
+
+When only files are provided, mdsel outputs the document structure:
+
 ```bash
-mdsel index README.md docs/API.md
+mdsel README.md
+mdsel README.md docs/API.md
+mdsel --json README.md
 ```
 
 **Text Output** (default):
@@ -58,9 +118,9 @@ mdsel index README.md docs/API.md
 h1.0 mdsel
  h2.0 Installation
  h2.1 Quick Start
- h2.2 Commands
-  h3.0 index
-  h3.1 select
+ h2.2 Usage
+  h3.0 Index
+  h3.1 Select
 ---
 code:19 para:23 list:5 table:3
 ```
@@ -95,44 +155,28 @@ code:19 para:23 list:5 table:3
 }
 ```
 
-### select
+### Select (files + selectors)
 
-Retrieve content via selectors.
+When both files and selectors are provided, mdsel retrieves matching content:
 
 ```bash
-mdsel select <selector> [files...]
-mdsel select <selector> [files...] --json
-```
-
-**Arguments**:
-- `<selector>` - Selector string (see [Selectors](#selectors))
-- `[files...]` - Markdown files to search (optional, uses stdin if omitted)
-
-**Options**:
-- `--json` - Output JSON instead of text
+# Single selector
+mdsel README.md h2.0
 
-**Examples**:
-```bash
-# Select first h2 (shorthand)
-mdsel select h2.0 README.md
-
-# Select first code block
-mdsel select code.0 README.md
+# Multiple selectors
+mdsel README.md h2.0 h2.1 code.0
 
-# Cross-document selection (all documents)
-mdsel select h1.0 README.md GUIDE.md
+# Cross-document selection
+mdsel README.md GUIDE.md h1.0
 
-# Limit output to first 10 lines
-mdsel select "h2.0?head=10" README.md
-
-# Limit output to last 5 lines
-mdsel select "h2.0?tail=5" README.md
+# With query parameters
+mdsel README.md "h2.0?head=10"
 
 # Range selection
-mdsel select h2.1-3 README.md
+mdsel README.md h2.1-3
 
-# Multiple specific indices
-mdsel select h2.0,2,4 README.md
+# Comma list selection
+mdsel README.md h2.0,2,4
 ```
 
 **Text Output** (default):

package/dist/cli.mjs

@@ -3,6 +3,7 @@
 // src/cli/index.ts
 import { Command } from "commander";
 import { createRequire } from "module";
+import { existsSync } from "fs";
 
 // src/parser/parse.ts
 import { readFile, access, stat } from "fs/promises";
@@ -548,7 +549,7 @@ function countBlock(node, counts) {
 
 // src/cli/utils/file-reader.ts
 function isStdinPiped() {
-  return !process.stdin.isTTY;
+  return process.stdin.isTTY === false;
 }
 function readStdin() {
   return new Promise((resolve, reject) => {
@@ -1846,6 +1847,104 @@ function formatMatches(results, truncateOpts) {
     };
   });
 }
+async function selectMultiCommand(selectors, 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;
+  }
+  const documents = [];
+  const parseErrors = [];
+  for (const file of files) {
+    try {
+      const result = await parseFile(file);
+      const namespace = deriveNamespace(file);
+      const availableSelectors = buildAvailableSelectors(result.ast, namespace);
+      documents.push({
+        namespace,
+        tree: result.ast,
+        availableSelectors
+      });
+    } 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 allMatches = [];
+  const allUnresolved = [];
+  for (const selector of selectors) {
+    let selectorAst;
+    try {
+      selectorAst = parseSelector(selector);
+    } catch (error) {
+      if (error instanceof SelectorParseError) {
+        allUnresolved.push({
+          selector,
+          reason: error.message,
+          suggestions: []
+        });
+        continue;
+      }
+      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 outcome = resolveMulti(documents, selectorAst);
+    if (outcome.success) {
+      const matches = formatMatches(outcome.results, truncateOptions);
+      allMatches.push(...matches);
+    } else {
+      const err = outcome.error;
+      allUnresolved.push({
+        selector: err.selector,
+        reason: err.message,
+        suggestions: err.suggestions.map((s) => s.selector)
+      });
+    }
+  }
+  if (useJson) {
+    const response = formatSelectResponse(allMatches, allUnresolved);
+    console.log(JSON.stringify(response));
+  } else {
+    console.log(formatSelectText(allMatches, allUnresolved));
+  }
+  exitWithCode(allUnresolved.length > 0 ? ExitCode.ERROR : ExitCode.SUCCESS);
+}
 
 // src/cli/commands/format-command.ts
 function formatCommand(command, options = {}) {
@@ -1866,21 +1965,54 @@ function formatCommand(command, options = {}) {
 // 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);
+function isFilePath(arg) {
+  if (/\.(md|markdown)$/i.test(arg)) {
+    return true;
   }
-});
-program.command("select").description("Retrieve content via selectors").argument("<selector>", "Selector string").argument("[files...]", "Markdown files to search").action(async (selector, files) => {
+  if (existsSync(arg)) {
+    return true;
+  }
+  return false;
+}
+function partitionArgs(args) {
+  const files = [];
+  const selectors = [];
+  for (const arg of args) {
+    if (isFilePath(arg)) {
+      files.push(arg);
+    } else {
+      selectors.push(arg);
+    }
+  }
+  return { files, selectors };
+}
+var program = new Command();
+program.name("mdsel").description(pkg.description).version(pkg.version).option("--json", "Output JSON instead of minimal text").argument("[args...]", "Files and/or selectors").action(async (args) => {
   try {
     const globalOpts = program.opts();
-    await selectCommand(selector, files, { json: globalOpts.json });
+    if (args.length === 0) {
+      if (isStdinPiped()) {
+        await indexCommand([], { json: globalOpts.json });
+        return;
+      }
+      program.outputHelp();
+      process.exit(0);
+    }
+    const { files, selectors } = partitionArgs(args);
+    if (files.length === 0) {
+      console.error("Error: No markdown files provided.");
+      console.error("Usage: mdsel <file.md> [selector...]");
+      process.exit(ExitCode.ERROR);
+    }
+    if (selectors.length === 0) {
+      await indexCommand(files, { json: globalOpts.json });
+      return;
+    }
+    if (selectors.length === 1) {
+      await selectCommand(selectors[0], files, { json: globalOpts.json });
+    } else {
+      await selectMultiCommand(selectors, files, { json: globalOpts.json });
+    }
   } catch (error) {
     console.error("Unexpected error:", error);
     process.exit(ExitCode.ERROR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdsel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Declarative Markdown semantic selection CLI for LLM agents",
   "type": "module",
   "bin": {