@facetlayer/docs-tool 0.1.0

package/dist/index.js

@@ -0,0 +1,471 @@
+// src/index.ts
+import { readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join3, basename, relative } from "path";
+
+// src/browseLocalLibrary.ts
+import { resolve, join } from "path";
+import { existsSync } from "fs";
+function browseLocalLibrary(targetPath) {
+  const resolvedPath = resolve(targetPath);
+  const docsPath = join(resolvedPath, "docs");
+  const hasDocsFolder = existsSync(docsPath);
+  const dirs = [resolvedPath];
+  if (hasDocsFolder) {
+    dirs.push(docsPath);
+  }
+  const helper = new DocFilesHelper({
+    dirs,
+    overrideGetSubcommand: `show ${targetPath}`
+  });
+  return {
+    libraryPath: resolvedPath,
+    helper,
+    hasDocsFolder
+  };
+}
+
+// src/browseNpmLibrary.ts
+import { readFileSync, readdirSync, existsSync as existsSync2, mkdirSync, writeFileSync } from "fs";
+import { join as join2, dirname } from "path";
+import { homedir } from "os";
+import { runShellCommand } from "@facetlayer/subprocess-wrapper";
+function findExactMatch(nodeModulesPath, libraryName) {
+  if (libraryName.startsWith("@")) {
+    const [scope, pkgName] = libraryName.split("/");
+    const scopePath = join2(nodeModulesPath, scope);
+    if (pkgName && existsSync2(scopePath)) {
+      const fullPath2 = join2(scopePath, pkgName);
+      if (existsSync2(fullPath2) && existsSync2(join2(fullPath2, "package.json"))) {
+        return fullPath2;
+      }
+    }
+    return null;
+  }
+  const fullPath = join2(nodeModulesPath, libraryName);
+  if (existsSync2(fullPath) && existsSync2(join2(fullPath, "package.json"))) {
+    return fullPath;
+  }
+  return null;
+}
+function findPartialMatches(nodeModulesPath, partialName) {
+  const matches = [];
+  const lowerPartial = partialName.toLowerCase();
+  if (!existsSync2(nodeModulesPath)) {
+    return matches;
+  }
+  const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith("@")) {
+      const scopePath = join2(nodeModulesPath, entry.name);
+      const scopedEntries = readdirSync(scopePath, { withFileTypes: true });
+      for (const scopedEntry of scopedEntries) {
+        if (!scopedEntry.isDirectory()) continue;
+        const fullName = `${entry.name}/${scopedEntry.name}`;
+        if (fullName.toLowerCase().includes(lowerPartial)) {
+          const fullPath = join2(scopePath, scopedEntry.name);
+          if (existsSync2(join2(fullPath, "package.json"))) {
+            matches.push({
+              libraryPath: fullPath,
+              libraryName: fullName,
+              matchType: "partial"
+            });
+          }
+        }
+      }
+    } else {
+      if (entry.name.toLowerCase().includes(lowerPartial)) {
+        const fullPath = join2(nodeModulesPath, entry.name);
+        if (existsSync2(join2(fullPath, "package.json"))) {
+          matches.push({
+            libraryPath: fullPath,
+            libraryName: entry.name,
+            matchType: "partial"
+          });
+        }
+      }
+    }
+  }
+  return matches;
+}
+function getNodeModulesPaths(startDir) {
+  const paths = [];
+  let currentDir = startDir;
+  while (true) {
+    const nodeModulesPath = join2(currentDir, "node_modules");
+    if (existsSync2(nodeModulesPath)) {
+      paths.push(nodeModulesPath);
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return paths;
+}
+function findLibraryInNodeModules(libraryName, startDir) {
+  const cwd = startDir || process.cwd();
+  const nodeModulesPaths = getNodeModulesPaths(cwd);
+  for (const nodeModulesPath of nodeModulesPaths) {
+    const exactPath = findExactMatch(nodeModulesPath, libraryName);
+    if (exactPath) {
+      return {
+        libraryPath: exactPath,
+        libraryName,
+        matchType: "exact"
+      };
+    }
+  }
+  for (const nodeModulesPath of nodeModulesPaths) {
+    const partialMatches = findPartialMatches(nodeModulesPath, libraryName);
+    if (partialMatches.length === 1) {
+      return partialMatches[0];
+    }
+    if (partialMatches.length > 1) {
+      console.warn(`Multiple partial matches found for "${libraryName}":`);
+      for (const match of partialMatches) {
+        console.warn(`  - ${match.libraryName}`);
+      }
+      console.warn(`Using: ${partialMatches[0].libraryName}`);
+      return partialMatches[0];
+    }
+  }
+  return null;
+}
+function getInstallationDirectory() {
+  const stateDir = join2(homedir(), ".cache", "docs-tool");
+  const installDir = join2(stateDir, "installed-packages");
+  if (!existsSync2(installDir)) {
+    mkdirSync(installDir, { recursive: true });
+  }
+  return installDir;
+}
+function ensureInstallDirInitialized(installDir) {
+  const packageJsonPath = join2(installDir, "package.json");
+  if (!existsSync2(packageJsonPath)) {
+    const packageJson = {
+      name: "docs-tool-installed-packages",
+      version: "1.0.0",
+      private: true,
+      description: "Packages installed by docs-tool for documentation viewing"
+    };
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+  }
+}
+function findInInstallDir(installDir, libraryName) {
+  const nodeModulesPath = join2(installDir, "node_modules");
+  if (!existsSync2(nodeModulesPath)) {
+    return null;
+  }
+  const exactPath = findExactMatch(nodeModulesPath, libraryName);
+  if (exactPath) {
+    return {
+      libraryPath: exactPath,
+      libraryName,
+      matchType: "exact"
+    };
+  }
+  const partialMatches = findPartialMatches(nodeModulesPath, libraryName);
+  if (partialMatches.length >= 1) {
+    return partialMatches[0];
+  }
+  return null;
+}
+async function getLatestVersion(libraryName) {
+  var _a;
+  try {
+    const result = await runShellCommand("npm", ["view", libraryName, "version"]);
+    if (result.failed() || !result.stdout) {
+      return null;
+    }
+    return ((_a = result.stdout[0]) == null ? void 0 : _a.trim()) || null;
+  } catch {
+    return null;
+  }
+}
+function getInstalledVersion(libraryPath) {
+  try {
+    const packageJsonPath = join2(libraryPath, "package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version || null;
+  } catch {
+    return null;
+  }
+}
+async function installLibrary(installDir, libraryName) {
+  ensureInstallDirInitialized(installDir);
+  console.log(`Installing ${libraryName}...`);
+  const result = await runShellCommand("npm", ["install", libraryName, "--ignore-scripts"], {
+    cwd: installDir
+  });
+  if (result.failed()) {
+    throw new Error(`Failed to install ${libraryName}: ${result.stderrAsString()}`);
+  }
+  console.log(`Successfully installed ${libraryName}`);
+}
+async function updateLibrary(installDir, libraryName) {
+  console.log(`Updating ${libraryName} to latest version...`);
+  const result = await runShellCommand("npm", ["update", libraryName, "--ignore-scripts"], {
+    cwd: installDir
+  });
+  if (result.failed()) {
+    console.warn(`Warning: Failed to update ${libraryName}: ${result.stderrAsString()}`);
+  } else {
+    console.log(`Successfully updated ${libraryName}`);
+  }
+}
+async function findLibrary(libraryName, options) {
+  const localResult = findLibraryInNodeModules(libraryName);
+  if (localResult) {
+    return localResult;
+  }
+  if (options == null ? void 0 : options.skipInstall) {
+    return null;
+  }
+  const installDir = getInstallationDirectory();
+  let installedResult = findInInstallDir(installDir, libraryName);
+  if (installedResult) {
+    const installedVersion = getInstalledVersion(installedResult.libraryPath);
+    const latestVersion = await getLatestVersion(installedResult.libraryName);
+    if (installedVersion && latestVersion && installedVersion !== latestVersion) {
+      console.log(`Found ${installedResult.libraryName}@${installedVersion}, latest is ${latestVersion}`);
+      await updateLibrary(installDir, installedResult.libraryName);
+      installedResult = findInInstallDir(installDir, libraryName);
+    }
+    return installedResult;
+  }
+  await installLibrary(installDir, libraryName);
+  return findInInstallDir(installDir, libraryName);
+}
+function getLibraryDocs(libraryPath, libraryName) {
+  const dirs = [];
+  const files = [];
+  const readmePath = join2(libraryPath, "README.md");
+  const docsPath = join2(libraryPath, "docs");
+  const hasReadme = existsSync2(readmePath);
+  const hasDocsFolder = existsSync2(docsPath);
+  if (hasReadme) {
+    files.push(readmePath);
+  }
+  if (hasDocsFolder) {
+    dirs.push(docsPath);
+  }
+  const helper = new DocFilesHelper({
+    dirs,
+    files,
+    overrideGetSubcommand: `show ${libraryName}`
+  });
+  return {
+    libraryName,
+    libraryPath,
+    helper,
+    hasReadme,
+    hasDocsFolder
+  };
+}
+async function browseNpmLibrary(libraryName, options) {
+  const location = await findLibrary(libraryName, options);
+  if (!location) {
+    return null;
+  }
+  return getLibraryDocs(location.libraryPath, location.libraryName);
+}
+
+// src/index.ts
+function parseFrontmatter(text) {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const match = text.match(frontmatterRegex);
+  if (!match) {
+    return {
+      frontmatter: {},
+      content: text
+    };
+  }
+  const [, frontmatterBlock, content] = match;
+  const frontmatter = {};
+  for (const line of frontmatterBlock.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+    frontmatter[key] = value;
+  }
+  return {
+    frontmatter,
+    content: content.trim()
+  };
+}
+var DocFilesHelper = class {
+  constructor(options) {
+    this.options = options;
+    this.fileMap = /* @__PURE__ */ new Map();
+    if (options.dirs) {
+      for (const dir of options.dirs) {
+        const files = readdirSync2(dir);
+        for (const file of files) {
+          if (!file.endsWith(".md")) continue;
+          this.fileMap.set(file, join3(dir, file));
+        }
+      }
+    }
+    if (options.files) {
+      for (const filePath of options.files) {
+        const baseFilename = basename(filePath);
+        this.fileMap.set(baseFilename, filePath);
+      }
+    }
+  }
+  formatGetDocCommand(filename) {
+    const script = relative(process.cwd(), process.argv[1]);
+    const binName = basename(script);
+    const subcommand = this.options.overrideGetSubcommand || "show";
+    if (binName === "." || binName.endsWith(".js") || binName.endsWith(".mjs") || binName.endsWith(".ts")) {
+      return `node ${script} ${subcommand} ${filename}`;
+    }
+    return `${binName} ${subcommand} ${filename}`;
+  }
+  /**
+   * List all doc files, returning their metadata from frontmatter.
+   * Files that don't exist are silently skipped.
+   */
+  listDocs() {
+    const docs = [];
+    for (const [baseFilename, fullPath] of this.fileMap) {
+      let rawContent;
+      try {
+        rawContent = readFileSync2(fullPath, "utf-8");
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          continue;
+        }
+        throw err;
+      }
+      const { frontmatter } = parseFrontmatter(rawContent);
+      docs.push({
+        name: frontmatter.name || basename(baseFilename, ".md"),
+        description: frontmatter.description || "",
+        filename: baseFilename
+      });
+    }
+    return docs;
+  }
+  /**
+   * Get the contents of a specific doc file by name.
+   * If the exact filename doesn't exist, looks for a partial match.
+   * Throws an error if the doc file is not found or if multiple matches are found.
+   */
+  getDoc(name) {
+    const baseName = name.endsWith(".md") ? name.slice(0, -3) : name;
+    const filename = `${baseName}.md`;
+    const fullPath = this.fileMap.get(filename);
+    if (fullPath) {
+      const rawContent2 = readFileSync2(fullPath, "utf-8");
+      const { frontmatter: frontmatter2, content: content2 } = parseFrontmatter(rawContent2);
+      return {
+        name: frontmatter2.name || baseName,
+        description: frontmatter2.description || "",
+        filename,
+        content: content2,
+        rawContent: rawContent2,
+        fullPath
+      };
+    }
+    const docs = this.listDocs();
+    const matches = docs.filter(
+      (doc) => doc.filename.toLowerCase().includes(baseName.toLowerCase()) || doc.name.toLowerCase().includes(baseName.toLowerCase())
+    );
+    if (matches.length === 0) {
+      throw new Error(`Doc file not found: ${baseName}`);
+    }
+    if (matches.length > 1) {
+      const matchNames = matches.map((m) => m.filename).join(", ");
+      throw new Error(
+        `Multiple docs match "${baseName}": ${matchNames}. Please be more specific.`
+      );
+    }
+    const matchedFilename = matches[0].filename;
+    const matchedPath = this.fileMap.get(matchedFilename);
+    const rawContent = readFileSync2(matchedPath, "utf-8");
+    const { frontmatter, content } = parseFrontmatter(rawContent);
+    return {
+      name: frontmatter.name || basename(matchedFilename, ".md"),
+      description: frontmatter.description || "",
+      filename: matchedFilename,
+      content,
+      rawContent,
+      fullPath: matchedPath
+    };
+  }
+  /**
+   * Print a formatted list of all doc files to stdout.
+   * Used by the 'list-docs' command.
+   */
+  printDocFileList() {
+    const docs = this.listDocs();
+    console.log("Available doc files:\n");
+    for (const doc of docs) {
+      if (doc.description) {
+        console.log(`  ${doc.name} (${this.formatGetDocCommand(doc.filename)}):`);
+        console.log(`    ${doc.description}
+`);
+      } else {
+        console.log(`  ${doc.name} (${this.formatGetDocCommand(doc.filename)})
+`);
+      }
+    }
+  }
+  /**
+   * Print the raw contents of a specific doc file to stdout.
+   *
+   * Used by the 'get-doc' command.
+   */
+  printDocFileContents(name) {
+    try {
+      const doc = this.getDoc(name);
+      console.log(doc.rawContent);
+      console.log(`
+(File source: ${doc.fullPath})`);
+    } catch {
+      console.error(`Doc file not found: ${name}`);
+      console.error('Run with "list-docs" or "list" command to see available docs.');
+      process.exit(1);
+    }
+  }
+  yargsSetup(yargs) {
+    yargs.command(
+      "list-docs",
+      "List available documentation files",
+      {},
+      async () => this.printDocFileList()
+    ).command(
+      "get-doc <name>",
+      "Display the contents of a documentation file",
+      (yargs2) => {
+        return yargs2.positional("name", {
+          type: "string",
+          describe: "Name of the doc file",
+          demandOption: true
+        });
+      },
+      async (argv) => this.printDocFileContents(argv.name)
+    );
+  }
+};
+function parseTarget(target) {
+  if (target.startsWith(".") || target.startsWith("/")) {
+    return { type: "directory", value: target };
+  }
+  return { type: "npm", value: target };
+}
+export {
+  DocFilesHelper,
+  browseLocalLibrary,
+  browseNpmLibrary,
+  findLibrary,
+  findLibraryInNodeModules,
+  getInstallationDirectory,
+  getLibraryDocs,
+  parseFrontmatter,
+  parseTarget
+};

package/docs/project-setup.md

@@ -0,0 +1,188 @@
+---
+name: project-setup
+description: Instructions for adding docs-tool to your CLI application
+---
+
+# Project Setup
+
+This guide explains how to add `@facetlayer/docs-tool` to your CLI application.
+
+## Installation
+
+```bash
+pnpm add @facetlayer/docs-tool
+```
+
+## Setting Up the Doc Files Folder
+
+Create a `docs` directory in your project root to store your documentation files:
+
+```
+my-project/
+├── docs/
+│   ├── getting-started.md
+│   └── configuration.md
+├── src/
+│   └── cli.ts
+└── package.json
+```
+
+Each doc file should include YAML frontmatter with `name` and `description`:
+
+```markdown
+---
+name: getting-started
+description: Quick start guide for new users
+---
+
+# Getting Started
+
+Your markdown content here.
+```
+
+## Creating a DocFilesHelper Instance
+
+In your CLI script (e.g., `src/cli.ts`), create a `DocFilesHelper` instance:
+
+```typescript
+import { DocFilesHelper } from '@facetlayer/docs-tool';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const __packageRoot = join(__dirname, '..');
+
+const docFiles = new DocFilesHelper({
+  dirs: [join(__packageRoot, 'docs')],
+  files: [join(__packageRoot, 'README.md')],
+});
+```
+
+### Configuration Options
+
+```typescript
+interface DocFilesHelperOptions {
+  // List of directories to search for *.md files
+  dirs?: string[];
+
+  // List of specific files to include
+  files?: string[];
+
+  // Override the subcommand name for getting a single doc (default: 'get-doc')
+  overrideGetSubcommand?: string;
+}
+```
+
+## Adding Commands to Yargs
+
+There are two approaches depending on how your CLI is structured.
+
+### Option 1: Using yargsSetup() with parse()
+
+If your CLI uses yargs with `.parse()` and command handlers, call `yargsSetup()`:
+
+```typescript
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { DocFilesHelper } from '@facetlayer/docs-tool';
+
+const docFiles = new DocFilesHelper({
+  dirs: [join(__packageRoot, 'docs')],
+});
+
+async function main() {
+  const args = yargs(hideBin(process.argv))
+    .command(
+      'my-command',
+      'Description of my command',
+      {},
+      async () => {
+        // Your command implementation
+      }
+    );
+
+  // Add list-docs and get-doc commands
+  docFiles.yargsSetup(args);
+
+  args
+    .strictCommands()
+    .demandCommand(1, 'You must specify a command')
+    .help()
+    .parse();  // Must use parse(), not parseSync()
+}
+
+main();
+```
+
+**Important:** `yargsSetup()` registers async command handlers. You must use `.parse()` instead of `.parseSync()`, otherwise yargs will throw an error.
+
+### Option 2: Manual registration with parseSync()
+
+If your CLI uses `.parseSync()` with a switch statement to handle commands, register the commands manually for help text and handle them in your switch:
+
+```typescript
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { DocFilesHelper } from '@facetlayer/docs-tool';
+
+const docFiles = new DocFilesHelper({
+  dirs: [join(__packageRoot, 'docs')],
+});
+
+function configureYargs() {
+  return yargs(hideBin(process.argv))
+    .command('my-command', 'Description of my command', () => {})
+    // Register doc commands for help text (no handlers)
+    .command('list-docs', 'List available documentation files', () => {})
+    .command('get-doc <name>', 'Display contents of a doc file', () => {})
+    .help();
+}
+
+function main() {
+  const argv = configureYargs().parseSync();
+  const command = argv._[0] as string;
+  const name = argv.name as string;
+
+  switch (command) {
+    case 'my-command':
+      // handle my-command
+      break;
+
+    case 'list-docs':
+      docFiles.printDocFileList();
+      break;
+
+    case 'get-doc':
+      docFiles.printDocFileContents(name);
+      break;
+  }
+}
+
+main();
+```
+
+This adds two commands to your CLI:
+
+- `<app> list-docs` - List all available doc files with descriptions
+- `<app> get-doc <name>` - Display the contents of a specific doc file
+
+## Manual Usage (Without Yargs)
+
+If you're not using Yargs or want more control, use the helper methods directly:
+
+```typescript
+// List all docs
+const docs = docFiles.listDocs();
+// Returns: [{ name, description, filename }, ...]
+
+// Get a specific doc
+const doc = docFiles.getDoc('getting-started');
+// Returns: { name, description, filename, content, rawContent, fullPath }
+
+// Print formatted list to stdout
+docFiles.printDocFileList();
+
+// Print doc contents to stdout
+docFiles.printDocFileContents('getting-started');
+```