@facetlayer/docs-tool 0.1.0

package/docs/writing-doc-files.md

@@ -0,0 +1,156 @@
+---
+name: writing-doc-files
+description: How to write and add documentation files for CLI tools
+---
+
+# Writing Doc Files
+
+This guide explains how to write documentation files that work with `@facetlayer/docs-tool`.
+
+## Doc File Format
+
+Doc files are Markdown files with YAML frontmatter. The frontmatter provides metadata that's displayed when listing docs.
+
+### Basic Structure
+
+```markdown
+---
+name: my-doc-name
+description: A brief description of what this doc covers
+---
+
+# Doc Title
+
+Your markdown content here.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Recommended | Short identifier for the doc (used in `get-doc` command) |
+| `description` | Recommended | One-line description shown in `list-docs` output |
+
+If `name` is not provided, the filename (without `.md`) is used as the name.
+
+### Example Doc File
+
+```markdown
+---
+name: configuration
+description: How to configure the application settings
+---
+
+# Configuration Guide
+
+## Environment Variables
+
+The app reads the following environment variables:
+
+- `API_KEY` - Your API key for authentication
+- `DEBUG` - Set to "true" to enable debug logging
+
+## Config File
+
+Create a `config.json` in your project root:
+
+\`\`\`json
+{
+  "timeout": 30,
+  "retries": 3
+}
+\`\`\`
+```
+
+## Adding Docs to Your CLI
+
+To ensure your doc files are available through the CLI, you need to:
+
+1. **Create a docs directory** - Typically `./docs` in your project root
+
+2. **Configure DocFilesHelper** - In your CLI script, create an instance pointing to your docs:
+
+```typescript
+import { DocFilesHelper } from '@facetlayer/docs-tool';
+
+const docFiles = new DocFilesHelper({
+  dirs: [join(__packageRoot, 'docs')],
+  files: [join(__packageRoot, 'README.md')],  // Optional
+});
+```
+
+3. **Verify the configuration** - Check that your docs are included by running:
+
+```bash
+# List all available docs
+your-cli list-docs
+
+# Verify a specific doc works
+your-cli get-doc your-doc-name
+```
+
+## Troubleshooting
+
+### Doc not showing in list-docs
+
+1. **Check the file location** - Ensure the file is in a directory listed in `dirs` or explicitly in `files`
+
+2. **Check the file extension** - Only `.md` files are included from directories
+
+3. **Verify DocFilesHelper setup** - Look for where `DocFilesHelper` is instantiated in your CLI code:
+
+```typescript
+// Look for something like this in your cli.ts or main script:
+const docFiles = new DocFilesHelper({
+  dirs: [...],  // Your docs directory should be here
+  files: [...], // Or specific files listed here
+});
+```
+
+4. **Check path resolution** - Make sure paths are absolute. Use the `__packageRoot` pattern:
+
+```typescript
+import { dirname, join } 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')],  // Absolute path
+});
+```
+
+Relative paths like `'./docs'` will resolve from the current working directory, not your package root, which breaks when the CLI is run from different directories
+
+### Doc content not displaying correctly
+
+1. **Check frontmatter syntax** - Ensure the `---` delimiters are on their own lines
+2. **Validate YAML** - Make sure frontmatter uses valid YAML (proper spacing, no tabs)
+
+## Publishing Docs with Your Package
+
+If you publish your CLI to npm, make sure to include the docs directory in your `package.json`:
+
+```json
+{
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md"
+  ]
+}
+```
+
+Without this, the docs folder won't be included when users install your package, and `list-docs` will show nothing.
+
+## Best Practices
+
+1. **Use descriptive names** - Choose names that are easy to type and remember
+2. **Write clear descriptions** - The description appears in `list-docs` so make it helpful
+3. **Keep docs focused** - One topic per doc file
+4. **Include examples** - Show concrete usage examples in your docs
+5. **Test your docs** - Run `list-docs` and `get-doc` after adding new files
+6. **Include README.md** - Add your README to the `files` array so it shows in `list-docs`

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@facetlayer/docs-tool",
+  "version": "0.1.0",
+  "description": "Library and CLI tool for browsing docs in NPM packages",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "docs": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "node build.mts build",
+    "prepublishOnly": "node build.mts validate && node build.mts build",
+    "typecheck": "tsc -p .",
+    "test": "vitest run --testTimeout=30000"
+  },
+  "keywords": [
+    "doc",
+    "frontmatter",
+    "markdown",
+    "documentation"
+  ],
+  "author": "andyfischer",
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.1",
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@facetlayer/subprocess-wrapper": "^1.1.0",
+    "yargs": "18.0.0"
+  },
+  "devDependencies": {
+    "@facetlayer/build-config-nodejs": "0.3.1",
+    "@types/node": "^22.10.2",
+    "@types/yargs": "17.0.34",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}

package/src/__tests__/cli.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { runShellCommand } from '@facetlayer/subprocess-wrapper';
+import { join } from 'path';
+
+const projectRoot = join(import.meta.dirname, '../..');
+const cliPath = join(projectRoot, 'src/cli.ts');
+const sampleDir = join(projectRoot, 'sample');
+
+async function runCli(...args: string[]) {
+  return runShellCommand('npx', ['tsx', cliPath, ...args], {
+    cwd: projectRoot,
+  });
+}
+
+describe('CLI', () => {
+  describe('list command', () => {
+    it('should list all doc files in the sample directory', async () => {
+      const result = await runCli('list', sampleDir);
+
+      expect(result.exitCode).toBe(0);
+
+      const output = result.stdoutAsString();
+      expect(output).toContain('Available doc files:');
+      expect(output).toContain('getting-started.md');
+      expect(output).toContain('api-reference.md');
+      expect(output).toContain('configuration.md');
+    });
+
+    it('should show descriptions from frontmatter', async () => {
+      const result = await runCli('list', sampleDir);
+
+      expect(result.exitCode).toBe(0);
+
+      const output = result.stdoutAsString();
+      expect(output).toContain('Quick start guide for new users');
+      expect(output).toContain('Complete API documentation');
+      expect(output).toContain('Configuration options and settings');
+    });
+
+    it('should fail with non-existent directory', async () => {
+      const result = await runCli('list', './nonexistent-dir');
+
+      expect(result.exitCode).not.toBe(0);
+    });
+  });
+
+  describe('help and version', () => {
+    it('should show help with --help flag', async () => {
+      const result = await runCli('--help');
+
+      expect(result.exitCode).toBe(0);
+
+      const output = result.stdoutAsString();
+      expect(output).toContain('list');
+    });
+
+    it('should show version with --version flag', async () => {
+      const result = await runCli('--version');
+
+      expect(result.exitCode).toBe(0);
+
+      const output = result.stdoutAsString();
+      expect(output).toMatch(/\d+\.\d+\.\d+/);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should require a command', async () => {
+      const result = await runCli();
+
+      expect(result.exitCode).not.toBe(0);
+    });
+
+    it('should reject unknown commands', async () => {
+      const result = await runCli('unknown-command');
+
+      expect(result.exitCode).not.toBe(0);
+    });
+  });
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,333 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { parseFrontmatter, DocFilesHelper } from '../index.ts';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+
+describe('parseFrontmatter', () => {
+  it('should parse frontmatter with name and description', () => {
+    const input = `---
+name: test-doc
+description: A test document
+---
+
+# Test Content
+
+This is the body.`;
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter.name).toBe('test-doc');
+    expect(result.frontmatter.description).toBe('A test document');
+    expect(result.content).toBe('# Test Content\n\nThis is the body.');
+  });
+
+  it('should parse frontmatter with custom fields', () => {
+    const input = `---
+name: my-doc
+author: John Doe
+version: 1.0
+---
+
+Content here`;
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter.name).toBe('my-doc');
+    expect(result.frontmatter.author).toBe('John Doe');
+    expect(result.frontmatter.version).toBe('1.0');
+  });
+
+  it('should return empty frontmatter when none exists', () => {
+    const input = '# No Frontmatter\n\nJust content.';
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter).toEqual({});
+    expect(result.content).toBe(input);
+  });
+
+  it('should handle frontmatter with colons in values', () => {
+    const input = `---
+name: doc-name
+description: This has: a colon in it
+---
+
+Content`;
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter.description).toBe('This has: a colon in it');
+  });
+
+  it('should handle Windows-style line endings', () => {
+    const input = '---\r\nname: test\r\ndescription: desc\r\n---\r\n\r\nContent';
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter.name).toBe('test');
+    expect(result.frontmatter.description).toBe('desc');
+    expect(result.content).toBe('Content');
+  });
+
+  it('should handle empty content after frontmatter', () => {
+    const input = `---
+name: empty
+---
+
+`;
+
+    const result = parseFrontmatter(input);
+
+    expect(result.frontmatter.name).toBe('empty');
+    expect(result.content).toBe('');
+  });
+});
+
+describe('DocFilesHelper', () => {
+  const testDir = join(import.meta.dirname, '../../test/temp/docs');
+  const extraDir = join(import.meta.dirname, '../../test/temp/extra');
+  const standaloneFile = join(import.meta.dirname, '../../test/temp/standalone.md');
+
+  beforeAll(() => {
+    mkdirSync(testDir, { recursive: true });
+    mkdirSync(extraDir, { recursive: true });
+
+    writeFileSync(
+      join(testDir, 'first-doc.md'),
+      `---
+name: first-doc
+description: The first test doc
+---
+
+# First Doc
+
+Content of first doc.`
+    );
+
+    writeFileSync(
+      join(testDir, 'second-doc.md'),
+      `---
+name: second-doc
+description: The second test doc
+---
+
+# Second Doc
+
+Content of second doc.`
+    );
+
+    writeFileSync(
+      join(testDir, 'no-frontmatter.md'),
+      `# No Frontmatter
+
+Just content without frontmatter.`
+    );
+
+    // Non-md file should be ignored
+    writeFileSync(join(testDir, 'ignored.txt'), 'This should be ignored');
+
+    // File in extra directory
+    writeFileSync(
+      join(extraDir, 'extra-doc.md'),
+      `---
+name: extra-doc
+description: An extra doc file
+---
+
+# Extra Doc
+
+Content of extra doc.`
+    );
+
+    // Standalone file outside of directories
+    writeFileSync(
+      standaloneFile,
+      `---
+name: standalone
+description: A standalone file
+---
+
+# Standalone
+
+Standalone content.`
+    );
+  });
+
+  afterAll(() => {
+    rmSync(join(import.meta.dirname, '../../test/temp'), { recursive: true, force: true });
+  });
+
+  describe('with dirs option', () => {
+    let helper: DocFilesHelper;
+
+    beforeAll(() => {
+      helper = new DocFilesHelper({ dirs: [testDir] });
+    });
+
+    describe('listDocs', () => {
+      it('should list all doc files with their metadata', () => {
+        const docs = helper.listDocs();
+
+        expect(docs).toHaveLength(3);
+
+        const firstDoc = docs.find((s) => s.name === 'first-doc');
+        expect(firstDoc).toBeDefined();
+        expect(firstDoc?.description).toBe('The first test doc');
+        expect(firstDoc?.filename).toBe('first-doc.md');
+
+        const secondDoc = docs.find((s) => s.name === 'second-doc');
+        expect(secondDoc).toBeDefined();
+        expect(secondDoc?.description).toBe('The second test doc');
+      });
+
+      it('should use filename as name when frontmatter has no name', () => {
+        const docs = helper.listDocs();
+
+        const noFrontmatter = docs.find((s) => s.filename === 'no-frontmatter.md');
+        expect(noFrontmatter?.name).toBe('no-frontmatter');
+        expect(noFrontmatter?.description).toBe('');
+      });
+
+      it('should ignore non-md files', () => {
+        const docs = helper.listDocs();
+
+        const txtFile = docs.find((s) => s.filename === 'ignored.txt');
+        expect(txtFile).toBeUndefined();
+      });
+    });
+
+    describe('getDoc', () => {
+      it('should return doc content by name', () => {
+        const doc = helper.getDoc('first-doc');
+
+        expect(doc.name).toBe('first-doc');
+        expect(doc.description).toBe('The first test doc');
+        expect(doc.content).toBe('# First Doc\n\nContent of first doc.');
+        expect(doc.rawContent).toContain('---');
+      });
+
+      it('should throw error for non-existent doc', () => {
+        expect(() => helper.getDoc('nonexistent')).toThrow('Doc file not found: nonexistent');
+      });
+
+      it('should handle doc without frontmatter', () => {
+        const doc = helper.getDoc('no-frontmatter');
+
+        expect(doc.name).toBe('no-frontmatter');
+        expect(doc.description).toBe('');
+        expect(doc.content).toContain('# No Frontmatter');
+      });
+
+      it('should handle name with .md extension', () => {
+        const doc = helper.getDoc('first-doc.md');
+
+        expect(doc.name).toBe('first-doc');
+        expect(doc.filename).toBe('first-doc.md');
+      });
+
+      it('should find doc by partial match', () => {
+        const doc = helper.getDoc('first');
+
+        expect(doc.name).toBe('first-doc');
+        expect(doc.filename).toBe('first-doc.md');
+      });
+
+      it('should throw error when multiple docs match', () => {
+        expect(() => helper.getDoc('doc')).toThrow(/Multiple docs match/);
+      });
+    });
+  });
+
+  describe('with multiple dirs', () => {
+    let helper: DocFilesHelper;
+
+    beforeAll(() => {
+      helper = new DocFilesHelper({ dirs: [testDir, extraDir] });
+    });
+
+    it('should list docs from all directories', () => {
+      const docs = helper.listDocs();
+
+      expect(docs).toHaveLength(4);
+      expect(docs.find((s) => s.name === 'first-doc')).toBeDefined();
+      expect(docs.find((s) => s.name === 'extra-doc')).toBeDefined();
+    });
+
+    it('should get doc from any directory', () => {
+      const doc = helper.getDoc('extra-doc');
+
+      expect(doc.name).toBe('extra-doc');
+      expect(doc.description).toBe('An extra doc file');
+    });
+  });
+
+  describe('with files option', () => {
+    let helper: DocFilesHelper;
+
+    beforeAll(() => {
+      helper = new DocFilesHelper({ files: [standaloneFile] });
+    });
+
+    it('should list standalone files', () => {
+      const docs = helper.listDocs();
+
+      expect(docs).toHaveLength(1);
+      expect(docs[0].name).toBe('standalone');
+      expect(docs[0].filename).toBe('standalone.md');
+    });
+
+    it('should get standalone file by base filename', () => {
+      const doc = helper.getDoc('standalone');
+
+      expect(doc.name).toBe('standalone');
+      expect(doc.description).toBe('A standalone file');
+      expect(doc.content).toBe('# Standalone\n\nStandalone content.');
+    });
+  });
+
+  describe('with non-existent files', () => {
+    it('should silently skip non-existent files in listDocs', () => {
+      const helper = new DocFilesHelper({
+        files: [
+          standaloneFile,
+          '/non/existent/file.md',
+        ],
+      });
+
+      const docs = helper.listDocs();
+
+      // Should only include the existing file, not throw an error
+      expect(docs).toHaveLength(1);
+      expect(docs[0].name).toBe('standalone');
+    });
+  });
+
+  describe('with both dirs and files', () => {
+    let helper: DocFilesHelper;
+
+    beforeAll(() => {
+      helper = new DocFilesHelper({
+        dirs: [testDir],
+        files: [standaloneFile],
+      });
+    });
+
+    it('should list docs from both dirs and files', () => {
+      const docs = helper.listDocs();
+
+      expect(docs).toHaveLength(4);
+      expect(docs.find((s) => s.name === 'first-doc')).toBeDefined();
+      expect(docs.find((s) => s.name === 'standalone')).toBeDefined();
+    });
+
+    it('should get doc from dirs', () => {
+      const doc = helper.getDoc('first-doc');
+      expect(doc.name).toBe('first-doc');
+    });
+
+    it('should get doc from files', () => {
+      const doc = helper.getDoc('standalone');
+      expect(doc.name).toBe('standalone');
+    });
+  });
+});

package/src/browseLocalLibrary.ts

@@ -0,0 +1,35 @@
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { DocFilesHelper } from './index.ts';
+
+export interface LocalLibraryDocs {
+  libraryPath: string;
+  helper: DocFilesHelper;
+  hasDocsFolder: boolean;
+}
+
+/**
+ * Create a DocFilesHelper for browsing docs in a local directory.
+ * Looks for .md files in the target directory and also in a ./docs subdirectory if it exists.
+ */
+export function browseLocalLibrary(targetPath: string): LocalLibraryDocs {
+  const resolvedPath = resolve(targetPath);
+  const docsPath = join(resolvedPath, 'docs');
+  const hasDocsFolder = existsSync(docsPath);
+
+  const dirs: string[] = [resolvedPath];
+  if (hasDocsFolder) {
+    dirs.push(docsPath);
+  }
+
+  const helper = new DocFilesHelper({
+    dirs,
+    overrideGetSubcommand: `show ${targetPath}`,
+  });
+
+  return {
+    libraryPath: resolvedPath,
+    helper,
+    hasDocsFolder,
+  };
+}