pointfree-docs 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# pf-docs
+
+A CLI tool for searching Point-Free library documentation locally. Uses sparse git checkout and SQLite FTS5 for fast, offline full-text search. Built for use with AI coding assistants like Claude Code.
+
+## Quick Start
+
+```bash
+# Install from npm
+npm install -g pointfree-docs
+
+# Or install from source
+git clone https://github.com/ronnie3786/pointfree-docs.git
+cd pointfree-docs
+npm install
+npm run build
+npm link
+
+# See what libraries are available
+pf-docs list --available
+
+# Download and index the ones you use
+pf-docs init --libs tca dependencies navigation
+
+# Search, browse, and read
+pf-docs search "testing effects"
+pf-docs get tca/Articles/TestingTCA
+pf-docs list tca
+```
+
+## Commands
+
+### `pf-docs list --available`
+
+Show all libraries available to download.
+
+### `pf-docs init`
+
+Download and index documentation. Only fetches `Documentation.docc` folders via sparse checkout.
+
+```bash
+pf-docs init --libs tca dependencies navigation
+pf-docs init --all
+```
+
+### `pf-docs update`
+
+Pull latest changes and re-index.
+
+```bash
+pf-docs update              # All initialized libraries
+pf-docs update --libs tca   # Specific libraries
+```
+
+### `pf-docs search <query>`
+
+Full-text search across all indexed docs.
+
+```bash
+pf-docs search "testing effects"
+pf-docs search "navigation" --lib tca
+pf-docs search "Store" --limit 5
+```
+
+### `pf-docs get <path>`
+
+Fetch a specific article as clean markdown.
+
+```bash
+pf-docs get tca/Articles/TestingTCA
+pf-docs get dependencies/Articles/QuickStart --raw
+```
+
+### `pf-docs list [lib]`
+
+List indexed documentation.
+
+```bash
+pf-docs list                # All indexed docs
+pf-docs list tca --tree     # Tree view for one library
+```
+
+### `pf-docs stats`
+
+Show indexing statistics.
+
+All commands support `--json` for programmatic output.
+
+## Supported Libraries
+
+| Short Name | Library | Description |
+|---|---|---|
+| `tca` | swift-composable-architecture | The Composable Architecture |
+| `dependencies` | swift-dependencies | Dependency injection library |
+| `navigation` | swift-navigation | Navigation tools for Swift |
+| `perception` | swift-perception | @Observable backported to iOS 16 |
+| `sharing` | swift-sharing | Persistence & data sharing |
+| `identified-collections` | swift-identified-collections | Identifiable-aware collections |
+| `case-paths` | swift-case-paths | Key paths for enum cases |
+| `custom-dump` | swift-custom-dump | Debugging/diffing tools |
+| `concurrency-extras` | swift-concurrency-extras | Testable async/await |
+| `clocks` | swift-clocks | Testable Swift concurrency clocks |
+| `snapshot-testing` | swift-snapshot-testing | Snapshot testing library |
+| `issue-reporting` | swift-issue-reporting | Runtime warnings & assertions |
+
+Run `pf-docs list --available` to see this list in your terminal.
+
+## Usage with Claude Code
+
+Add the key commands to your project's `CLAUDE.md`:
+
+```markdown
+Use `pf-docs search "<query>"` to search Point-Free docs, `pf-docs get <path>` to read an article.
+```
+
+## Adding Libraries
+
+Edit `src/config.ts` to add entries, then run `pf-docs init --libs <shortName>` to download.
+
+## Development
+
+```bash
+npm install
+npm run dev      # Watch mode
+npm run build    # Build once
+npm link         # Install globally
+```
+
+Cloned repos and the search index are stored in `data/` (gitignored).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * pf-docs CLI - Point-Free Documentation Tool
+ *
+ * A CLI for searching and browsing Point-Free library documentation.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * pf-docs CLI - Point-Free Documentation Tool
+ *
+ * A CLI for searching and browsing Point-Free library documentation.
+ */
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { updateCommand } from "./commands/update.js";
+import { searchCommand } from "./commands/search.js";
+import { getCommand } from "./commands/get.js";
+import { listCommand } from "./commands/list.js";
+import { statsCommand } from "./commands/stats.js";
+const program = new Command();
+program
+    .name("pf-docs")
+    .description("CLI tool for searching Point-Free library documentation")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize and download documentation for specified libraries")
+    .option("-l, --libs <libs...>", "Libraries to download (e.g., tca dependencies)")
+    .option("-a, --all", "Download all available libraries")
+    .action(initCommand);
+program
+    .command("update")
+    .description("Update documentation from remote repositories")
+    .option("-l, --libs <libs...>", "Specific libraries to update")
+    .action(updateCommand);
+program
+    .command("search <query>")
+    .description("Search across all indexed documentation")
+    .option("-l, --lib <lib>", "Limit search to specific library")
+    .option("-n, --limit <n>", "Max results to return", "10")
+    .option("-j, --json", "Output results as JSON")
+    .action(searchCommand);
+program
+    .command("get <path>")
+    .description("Get a specific documentation article (e.g., tca/Testing)")
+    .option("-j, --json", "Output as JSON")
+    .option("-r, --raw", "Output raw content without header")
+    .action(getCommand);
+program
+    .command("list [lib]")
+    .description("List available documentation articles")
+    .option("-t, --tree", "Show as tree structure")
+    .option("-j, --json", "Output as JSON")
+    .option("-a, --available", "Show all libraries available to download")
+    .action(listCommand);
+program
+    .command("stats")
+    .description("Show indexing statistics")
+    .option("-j, --json", "Output as JSON")
+    .action(statsCommand);
+program.parse();

package/dist/commands/get.d.ts

@@ -0,0 +1,9 @@
+/**
+ * get command - Retrieve a specific documentation article
+ */
+interface GetOptions {
+    json?: boolean;
+    raw?: boolean;
+}
+export declare function getCommand(path: string, options?: GetOptions): void;
+export {};

package/dist/commands/get.js

@@ -0,0 +1,30 @@
+/**
+ * get command - Retrieve a specific documentation article
+ */
+import chalk from "chalk";
+import { getDoc, withIndex } from "../lib/index.js";
+import { formatDocForOutput } from "../lib/markdown.js";
+export function getCommand(path, options = {}) {
+    const doc = withIndex(() => getDoc(path));
+    if (!doc) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: "Document not found", path }, null, 2));
+            return;
+        }
+        console.error(chalk.red(`\n✗ Document not found: ${path}`));
+        console.log(chalk.gray(`\nRun 'pf-docs list' to see available documents.`));
+        console.log(chalk.gray(`Or search: pf-docs search "<query>"`));
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(doc, null, 2));
+        return;
+    }
+    // Raw output (just content, no header)
+    if (options.raw) {
+        console.log(doc.content);
+        return;
+    }
+    // Output the formatted document (clean markdown)
+    console.log(formatDocForOutput(doc));
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,9 @@
+/**
+ * init command - Download and index Point-Free documentation
+ */
+interface InitOptions {
+    libs?: string[];
+    all?: boolean;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,63 @@
+/**
+ * init command - Download and index Point-Free documentation
+ */
+import chalk from "chalk";
+import { LIBRARIES, getLibrary, LIBRARY_NAMES } from "../config.js";
+import { cloneLibrary } from "../lib/repos.js";
+import { indexLibrary, openIndex, closeIndex } from "../lib/index.js";
+export async function initCommand(options) {
+    console.log(chalk.bold("\n📚 Initializing Point-Free Documentation\n"));
+    // Determine which libraries to download
+    let librariesToInit = LIBRARIES;
+    if (options.libs && !options.all) {
+        librariesToInit = [];
+        for (const name of options.libs) {
+            const lib = getLibrary(name);
+            if (lib) {
+                librariesToInit.push(lib);
+            }
+            else {
+                console.log(chalk.yellow(`  ⚠ Unknown library: ${name}`));
+                console.log(chalk.gray(`    Available: ${LIBRARY_NAMES.join(", ")}`));
+            }
+        }
+    }
+    if (librariesToInit.length === 0) {
+        console.log(chalk.red("No valid libraries specified."));
+        console.log(`\nUsage: pf-docs init --libs tca dependencies navigation`);
+        console.log(`       pf-docs init --all`);
+        console.log(`\nAvailable libraries: ${LIBRARY_NAMES.join(", ")}`);
+        return;
+    }
+    console.log(chalk.blue(`Libraries to initialize: ${librariesToInit.map((l) => l.shortName).join(", ")}\n`));
+    // Clone repositories
+    console.log(chalk.bold("Cloning repositories..."));
+    for (const lib of librariesToInit) {
+        try {
+            await cloneLibrary(lib);
+        }
+        catch (error) {
+            console.error(chalk.red(`  ✗ Failed to clone ${lib.shortName}:`), error);
+        }
+    }
+    // Build search index
+    console.log(chalk.bold("\nBuilding search index..."));
+    openIndex();
+    let totalIndexed = 0;
+    for (const lib of librariesToInit) {
+        try {
+            const count = indexLibrary(lib);
+            console.log(`  ✓ Indexed ${lib.shortName}: ${count} documents`);
+            totalIndexed += count;
+        }
+        catch (error) {
+            console.error(chalk.red(`  ✗ Failed to index ${lib.shortName}:`), error);
+        }
+    }
+    closeIndex();
+    console.log(chalk.green(`\n✅ Done! Indexed ${totalIndexed} documents.\n`));
+    console.log(`Try it out:`);
+    console.log(chalk.gray(`  pf-docs search "testing async effects"`));
+    console.log(chalk.gray(`  pf-docs list tca`));
+    console.log(chalk.gray(`  pf-docs get tca/Testing`));
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,10 @@
+/**
+ * list command - List available documentation articles
+ */
+interface ListOptions {
+    tree?: boolean;
+    json?: boolean;
+    available?: boolean;
+}
+export declare function listCommand(lib: string | undefined, options: ListOptions): void;
+export {};

package/dist/commands/list.js

@@ -0,0 +1,86 @@
+/**
+ * list command - List available documentation articles
+ */
+import chalk from "chalk";
+import { listDocs, getStats, withIndex } from "../lib/index.js";
+import { getLibrary, LIBRARIES, LIBRARY_NAMES } from "../config.js";
+export function listCommand(lib, options) {
+    if (options.available) {
+        if (options.json) {
+            const libs = LIBRARIES.map(({ shortName, name, repo, description }) => ({
+                shortName, name, repo, description,
+            }));
+            console.log(JSON.stringify(libs, null, 2));
+            return;
+        }
+        console.log(chalk.bold(`\n📦 Available Libraries\n`));
+        for (const library of LIBRARIES) {
+            console.log(`  ${chalk.blue(library.shortName.padEnd(24))} ${library.description}`);
+            console.log(chalk.gray(`  ${"".padEnd(24)} ${library.repo}\n`));
+        }
+        console.log(chalk.gray(`Total: ${LIBRARIES.length} libraries`));
+        console.log(chalk.gray(`\nTo download: pf-docs init --libs <name> [<name>...]`));
+        return;
+    }
+    const { docs, stats } = withIndex(() => ({
+        docs: listDocs(lib),
+        stats: getStats(),
+    }));
+    // JSON output for programmatic use
+    if (options.json) {
+        console.log(JSON.stringify({ docs, stats }, null, 2));
+        return;
+    }
+    if (docs.length === 0) {
+        if (lib) {
+            console.log(chalk.yellow(`\nNo documents found for library: ${lib}`));
+            console.log(chalk.gray(`Available libraries: ${LIBRARY_NAMES.join(", ")}`));
+        }
+        else {
+            console.log(chalk.yellow(`\nNo documents indexed yet.`));
+            console.log(chalk.gray(`Run 'pf-docs init --libs tca dependencies' to get started.`));
+        }
+        return;
+    }
+    console.log(chalk.bold(`\n📄 Available Documentation\n`));
+    // Show stats summary
+    if (!lib) {
+        console.log(chalk.gray(`Indexed libraries:`));
+        for (const [libName, count] of Object.entries(stats.byLibrary)) {
+            const libConfig = getLibrary(libName);
+            const desc = libConfig?.description || "";
+            console.log(chalk.gray(`  ${chalk.blue(libName)}: ${count} docs — ${desc}`));
+        }
+        console.log();
+    }
+    if (options.tree) {
+        // Group by library and show as tree
+        const byLibrary = new Map();
+        for (const doc of docs) {
+            if (!byLibrary.has(doc.library)) {
+                byLibrary.set(doc.library, []);
+            }
+            byLibrary.get(doc.library).push(doc);
+        }
+        for (const [library, libraryDocs] of byLibrary) {
+            console.log(chalk.blue(`${library}/`));
+            for (let i = 0; i < libraryDocs.length; i++) {
+                const doc = libraryDocs[i];
+                const relativePath = doc.path.replace(`${library}/`, "");
+                const isLast = i === libraryDocs.length - 1;
+                const prefix = isLast ? "└── " : "├── ";
+                console.log(chalk.gray(`  ${prefix}${relativePath}`));
+            }
+            console.log();
+        }
+    }
+    else {
+        // Simple list
+        for (const doc of docs) {
+            console.log(chalk.blue(doc.path));
+            console.log(chalk.gray(`  ${doc.title}`));
+        }
+    }
+    console.log(chalk.gray(`\nTotal: ${docs.length} documents`));
+    console.log(chalk.gray(`\nTo view a document: pf-docs get <path>`));
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,10 @@
+/**
+ * search command - Search across all indexed documentation
+ */
+interface SearchOptions {
+    lib?: string;
+    limit?: string;
+    json?: boolean;
+}
+export declare function searchCommand(query: string, options: SearchOptions): void;
+export {};

package/dist/commands/search.js

@@ -0,0 +1,31 @@
+/**
+ * search command - Search across all indexed documentation
+ */
+import chalk from "chalk";
+import { search as searchIndex, withIndex } from "../lib/index.js";
+export function searchCommand(query, options) {
+    const limit = options.limit ? parseInt(options.limit, 10) : 10;
+    const results = withIndex(() => searchIndex(query, { lib: options.lib, limit }));
+    if (options.json) {
+        console.log(JSON.stringify({ query, results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(chalk.yellow(`\nNo results found for: "${query}"`));
+        if (options.lib) {
+            console.log(chalk.gray(`  (searched in library: ${options.lib})`));
+        }
+        console.log(chalk.gray(`\nTry a different query or run 'pf-docs list' to see available docs.`));
+        return;
+    }
+    console.log(chalk.bold(`\n🔍 Search results for: "${query}"\n`));
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        console.log(chalk.blue(`${i + 1}. ${result.title}`));
+        console.log(chalk.gray(`   Path: ${result.path}`));
+        console.log(chalk.gray(`   ${result.snippet}`));
+        console.log();
+    }
+    console.log(chalk.gray(`\nTo view a document: pf-docs get <path>`));
+    console.log(chalk.gray(`Example: pf-docs get ${results[0].path}`));
+}

package/dist/commands/stats.d.ts

@@ -0,0 +1,8 @@
+/**
+ * stats command - Show indexing statistics
+ */
+interface StatsOptions {
+    json?: boolean;
+}
+export declare function statsCommand(options: StatsOptions): void;
+export {};

package/dist/commands/stats.js

@@ -0,0 +1,37 @@
+/**
+ * stats command - Show indexing statistics
+ */
+import chalk from "chalk";
+import { getStats, withIndex } from "../lib/index.js";
+import { LIBRARIES, getLibrary } from "../config.js";
+import { isLibraryCloned } from "../lib/repos.js";
+export function statsCommand(options) {
+    const stats = withIndex(() => getStats());
+    if (options.json) {
+        console.log(JSON.stringify(stats, null, 2));
+        return;
+    }
+    console.log(chalk.bold("\n📊 pf-docs Statistics\n"));
+    console.log(chalk.blue(`Total indexed documents: ${stats.totalDocs}`));
+    console.log();
+    console.log(chalk.bold("Indexed libraries:"));
+    for (const [libName, count] of Object.entries(stats.byLibrary)) {
+        const libConfig = getLibrary(libName);
+        console.log(`  ${chalk.green("●")} ${libName}: ${count} docs`);
+        if (libConfig) {
+            console.log(chalk.gray(`      ${libConfig.description}`));
+        }
+    }
+    console.log();
+    // Show available but not indexed libraries
+    const notIndexed = LIBRARIES.filter((lib) => !stats.byLibrary[lib.shortName] && !isLibraryCloned(lib));
+    if (notIndexed.length > 0) {
+        console.log(chalk.bold("Available libraries (not indexed):"));
+        for (const lib of notIndexed) {
+            console.log(`  ${chalk.gray("○")} ${lib.shortName}`);
+            console.log(chalk.gray(`      ${lib.description}`));
+        }
+        console.log();
+        console.log(chalk.gray(`To add: pf-docs init --libs ${notIndexed[0].shortName}`));
+    }
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,8 @@
+/**
+ * update command - Update documentation from remote repositories
+ */
+interface UpdateOptions {
+    libs?: string[];
+}
+export declare function updateCommand(options: UpdateOptions): Promise<void>;
+export {};

package/dist/commands/update.js

@@ -0,0 +1,51 @@
+/**
+ * update command - Update documentation from remote repositories
+ */
+import chalk from "chalk";
+import { LIBRARIES, getLibrary } from "../config.js";
+import { updateLibrary, isLibraryCloned } from "../lib/repos.js";
+import { indexLibrary, openIndex, closeIndex } from "../lib/index.js";
+export async function updateCommand(options) {
+    console.log(chalk.bold("\n🔄 Updating Point-Free Documentation\n"));
+    // Determine which libraries to update
+    let librariesToUpdate = LIBRARIES.filter(isLibraryCloned);
+    if (options.libs) {
+        librariesToUpdate = [];
+        for (const name of options.libs) {
+            const lib = getLibrary(name);
+            if (lib && isLibraryCloned(lib)) {
+                librariesToUpdate.push(lib);
+            }
+            else if (lib) {
+                console.log(chalk.yellow(`  ⚠ Library not initialized: ${name}. Run 'pf-docs init --libs ${name}' first.`));
+            }
+            else {
+                console.log(chalk.yellow(`  ⚠ Unknown library: ${name}`));
+            }
+        }
+    }
+    if (librariesToUpdate.length === 0) {
+        console.log(chalk.yellow("No libraries to update. Run 'pf-docs init' first."));
+        return;
+    }
+    // Update repositories
+    console.log(chalk.bold("Pulling latest changes..."));
+    const updatedLibs = [];
+    for (const lib of librariesToUpdate) {
+        const wasUpdated = await updateLibrary(lib);
+        if (wasUpdated) {
+            updatedLibs.push(lib);
+        }
+    }
+    // Re-index updated libraries
+    if (updatedLibs.length > 0) {
+        console.log(chalk.bold("\nRe-indexing updated libraries..."));
+        openIndex();
+        for (const lib of updatedLibs) {
+            const count = indexLibrary(lib);
+            console.log(`  ✓ Re-indexed ${lib.shortName}: ${count} documents`);
+        }
+        closeIndex();
+    }
+    console.log(chalk.green(`\n✅ Update complete!\n`));
+}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Configuration for Point-Free libraries
+ */
+export interface LibraryConfig {
+    name: string;
+    shortName: string;
+    repo: string;
+    docsPaths: string[];
+    description: string;
+}
+/**
+ * All available Point-Free libraries
+ * Add or remove libraries here to customize what's indexed
+ */
+export declare const LIBRARIES: LibraryConfig[];
+/**
+ * Get library config by short name
+ */
+export declare function getLibrary(shortName: string): LibraryConfig | undefined;
+/**
+ * All library short names
+ */
+export declare const LIBRARY_NAMES: string[];
+export declare const PATHS: {
+    dataDir: string;
+    reposDir: string;
+    indexDb: string;
+};

package/dist/config.js

@@ -0,0 +1,121 @@
+/**
+ * Configuration for Point-Free libraries
+ */
+import { join } from "path";
+/**
+ * All available Point-Free libraries
+ * Add or remove libraries here to customize what's indexed
+ */
+export const LIBRARIES = [
+    {
+        name: "swift-composable-architecture",
+        shortName: "tca",
+        repo: "pointfreeco/swift-composable-architecture",
+        docsPaths: ["Sources/ComposableArchitecture/Documentation.docc"],
+        description: "The Composable Architecture",
+    },
+    {
+        name: "swift-dependencies",
+        shortName: "dependencies",
+        repo: "pointfreeco/swift-dependencies",
+        docsPaths: ["Sources/Dependencies/Documentation.docc"],
+        description: "Dependency injection library",
+    },
+    {
+        name: "swift-navigation",
+        shortName: "navigation",
+        repo: "pointfreeco/swift-navigation",
+        docsPaths: [
+            "Sources/SwiftNavigation/Documentation.docc",
+            "Sources/SwiftUINavigation/Documentation.docc",
+            "Sources/UIKitNavigation/Documentation.docc",
+            "Sources/AppKitNavigation/Documentation.docc",
+        ],
+        description: "Navigation tools for Swift",
+    },
+    {
+        name: "swift-perception",
+        shortName: "perception",
+        repo: "pointfreeco/swift-perception",
+        docsPaths: ["Sources/Perception/Documentation.docc"],
+        description: "@Observable backported to iOS 16",
+    },
+    {
+        name: "swift-sharing",
+        shortName: "sharing",
+        repo: "pointfreeco/swift-sharing",
+        docsPaths: ["Sources/Sharing/Documentation.docc"],
+        description: "Persistence & data sharing",
+    },
+    {
+        name: "swift-identified-collections",
+        shortName: "identified-collections",
+        repo: "pointfreeco/swift-identified-collections",
+        docsPaths: ["Sources/IdentifiedCollections/Documentation.docc"],
+        description: "Identifiable-aware collections",
+    },
+    {
+        name: "swift-case-paths",
+        shortName: "case-paths",
+        repo: "pointfreeco/swift-case-paths",
+        docsPaths: ["Sources/CasePaths/Documentation.docc"],
+        description: "Key paths for enum cases",
+    },
+    {
+        name: "swift-custom-dump",
+        shortName: "custom-dump",
+        repo: "pointfreeco/swift-custom-dump",
+        docsPaths: ["Sources/CustomDump/Documentation.docc"],
+        description: "Debugging/diffing tools",
+    },
+    {
+        name: "swift-concurrency-extras",
+        shortName: "concurrency-extras",
+        repo: "pointfreeco/swift-concurrency-extras",
+        docsPaths: ["Sources/ConcurrencyExtras/Documentation.docc"],
+        description: "Testable async/await",
+    },
+    {
+        name: "swift-clocks",
+        shortName: "clocks",
+        repo: "pointfreeco/swift-clocks",
+        docsPaths: ["Sources/Clocks/Documentation.docc"],
+        description: "Testable Swift concurrency clocks",
+    },
+    {
+        name: "swift-snapshot-testing",
+        shortName: "snapshot-testing",
+        repo: "pointfreeco/swift-snapshot-testing",
+        docsPaths: [
+            "Sources/SnapshotTesting/Documentation.docc",
+            "Sources/InlineSnapshotTesting/Documentation.docc",
+        ],
+        description: "Snapshot testing library",
+    },
+    {
+        name: "swift-issue-reporting",
+        shortName: "issue-reporting",
+        repo: "pointfreeco/swift-issue-reporting",
+        docsPaths: ["Sources/IssueReporting/Documentation.docc"],
+        description: "Runtime warnings & assertions",
+    },
+];
+/**
+ * Get library config by short name
+ */
+export function getLibrary(shortName) {
+    return LIBRARIES.find((lib) => lib.shortName === shortName || lib.name === shortName);
+}
+/**
+ * All library short names
+ */
+export const LIBRARY_NAMES = LIBRARIES.map((lib) => lib.shortName);
+/**
+ * Paths configuration
+ */
+const dataDir = new URL("../data", import.meta.url).pathname;
+export const PATHS = {
+    dataDir,
+    reposDir: join(dataDir, "repos"),
+    indexDb: join(dataDir, "index.db"),
+};

package/dist/lib/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Search index using SQLite FTS5 for full-text search
+ */
+import Database from "better-sqlite3";
+import { LibraryConfig } from "../config.js";
+export interface DocEntry {
+    library: string;
+    path: string;
+    title: string;
+}
+export interface DocWithContent extends DocEntry {
+    content: string;
+}
+export interface IndexStats {
+    totalDocs: number;
+    byLibrary: Record<string, number>;
+}
+/**
+ * Initialize or open the search index database
+ */
+export declare function openIndex(): Database.Database;
+/**
+ * Index all documentation files for a library
+ */
+export declare function indexLibrary(lib: LibraryConfig): number;
+/**
+ * Search the index
+ */
+export interface SearchResult {
+    library: string;
+    path: string;
+    title: string;
+    snippet: string;
+    score: number;
+}
+export declare function search(query: string, options?: {
+    lib?: string;
+    limit?: number;
+}): SearchResult[];
+/**
+ * List all indexed documents
+ */
+export declare function listDocs(lib?: string): DocEntry[];
+/**
+ * Get a specific document by path
+ */
+export declare function getDoc(path: string): DocWithContent | null;
+/**
+ * Get index statistics
+ */
+export declare function getStats(): IndexStats;
+/**
+ * Run a function with the index open, closing it automatically afterward.
+ */
+export declare function withIndex<T>(fn: () => T): T;
+/**
+ * Close the database connection
+ */
+export declare function closeIndex(): void;

package/dist/lib/index.js

@@ -0,0 +1,226 @@
+/**
+ * Search index using SQLite FTS5 for full-text search
+ */
+import Database from "better-sqlite3";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import { glob } from "glob";
+import { basename, join } from "path";
+import { PATHS } from "../config.js";
+import { getDocsPaths } from "./repos.js";
+import { cleanMarkdown, extractTitle } from "./markdown.js";
+let db = null;
+/**
+ * Initialize or open the search index database
+ */
+export function openIndex() {
+    if (db)
+        return db;
+    // Ensure data directory exists
+    if (!existsSync(PATHS.dataDir)) {
+        mkdirSync(PATHS.dataDir, { recursive: true });
+    }
+    db = new Database(PATHS.indexDb);
+    // Create tables if they don't exist
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS docs (
+      id INTEGER PRIMARY KEY,
+      library TEXT NOT NULL,
+      path TEXT NOT NULL,
+      title TEXT,
+      content TEXT,
+      UNIQUE(library, path)
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+      title,
+      content,
+      library,
+      path,
+      content='docs',
+      content_rowid='id'
+    );
+
+    -- Triggers to keep FTS index in sync
+    CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
+      INSERT INTO docs_fts(rowid, title, content, library, path)
+      VALUES (new.id, new.title, new.content, new.library, new.path);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path)
+      VALUES ('delete', old.id, old.title, old.content, old.library, old.path);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path)
+      VALUES ('delete', old.id, old.title, old.content, old.library, old.path);
+      INSERT INTO docs_fts(rowid, title, content, library, path)
+      VALUES (new.id, new.title, new.content, new.library, new.path);
+    END;
+  `);
+    return db;
+}
+/**
+ * Index all documentation files for a library
+ */
+export function indexLibrary(lib) {
+    const db = openIndex();
+    const docsPaths = getDocsPaths(lib);
+    const insertStmt = db.prepare(`
+    INSERT OR REPLACE INTO docs (library, path, title, content)
+    VALUES (?, ?, ?, ?)
+  `);
+    let indexed = 0;
+    for (const docsPath of docsPaths) {
+        if (!existsSync(docsPath)) {
+            // Skip if this docs path doesn't exist (some may be optional)
+            continue;
+        }
+        // Find all markdown files
+        const mdFiles = glob.sync("**/*.md", { cwd: docsPath });
+        for (const file of mdFiles) {
+            const fullPath = join(docsPath, file);
+            try {
+                const content = readFileSync(fullPath, "utf-8");
+                const cleanedContent = cleanMarkdown(content);
+                const title = extractTitle(content) || basename(file, ".md");
+                // Logical path like "tca/Testing" or "tca/Articles/Performance"
+                const docPath = `${lib.shortName}/${file.replace(/\.md$/, "")}`;
+                insertStmt.run(lib.shortName, docPath, title, cleanedContent);
+                indexed++;
+            }
+            catch (error) {
+                console.error(`  Warning: Failed to index ${fullPath}:`, error);
+            }
+        }
+    }
+    return indexed;
+}
+export function search(query, options = {}) {
+    const db = openIndex();
+    const limit = options.limit || 10;
+    // Escape special FTS5 characters and format query
+    const ftsQuery = query
+        .replace(/['"]/g, "") // Remove quotes
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((term) => `"${term}"*`) // Prefix matching
+        .join(" ");
+    if (!ftsQuery) {
+        return [];
+    }
+    let sql = `
+    SELECT
+      library,
+      path,
+      title,
+      snippet(docs_fts, 1, '**', '**', '...', 32) as snippet,
+      bm25(docs_fts) as score
+    FROM docs_fts
+    WHERE docs_fts MATCH ?
+  `;
+    const params = [ftsQuery];
+    if (options.lib) {
+        sql += ` AND library = ?`;
+        params.push(options.lib);
+    }
+    sql += ` ORDER BY score LIMIT ?`;
+    params.push(limit);
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.all(...params);
+    }
+    catch (error) {
+        // If FTS query fails, try simpler LIKE search
+        console.error("FTS search failed, falling back to LIKE search:", error);
+        return fallbackSearch(query, options);
+    }
+}
+/**
+ * Fallback search using LIKE (when FTS fails)
+ */
+function fallbackSearch(query, options = {}) {
+    const db = openIndex();
+    const limit = options.limit || 10;
+    let sql = `
+    SELECT
+      library,
+      path,
+      title,
+      substr(content, 1, 200) as snippet,
+      0 as score
+    FROM docs
+    WHERE (title LIKE ? OR content LIKE ?)
+  `;
+    const likePattern = `%${query}%`;
+    const params = [likePattern, likePattern];
+    if (options.lib) {
+        sql += ` AND library = ?`;
+        params.push(options.lib);
+    }
+    sql += ` LIMIT ?`;
+    params.push(limit);
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.all(...params);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List all indexed documents
+ */
+export function listDocs(lib) {
+    const db = openIndex();
+    let sql = `SELECT library, path, title FROM docs`;
+    const params = [];
+    if (lib) {
+        sql += ` WHERE library = ?`;
+        params.push(lib);
+    }
+    sql += ` ORDER BY library, path`;
+    const stmt = db.prepare(sql);
+    return stmt.all(...params);
+}
+/**
+ * Get a specific document by path
+ */
+export function getDoc(path) {
+    const db = openIndex();
+    const stmt = db.prepare(`SELECT library, path, title, content FROM docs WHERE path = ?`);
+    return stmt.get(path);
+}
+/**
+ * Get index statistics
+ */
+export function getStats() {
+    const db = openIndex();
+    const totalStmt = db.prepare(`SELECT COUNT(*) as count FROM docs`);
+    const total = totalStmt.get().count;
+    const byLibStmt = db.prepare(`SELECT library, COUNT(*) as count FROM docs GROUP BY library`);
+    const byLibRows = byLibStmt.all();
+    const byLibrary = Object.fromEntries(byLibRows.map((row) => [row.library, row.count]));
+    return { totalDocs: total, byLibrary };
+}
+/**
+ * Run a function with the index open, closing it automatically afterward.
+ */
+export function withIndex(fn) {
+    openIndex();
+    try {
+        return fn();
+    }
+    finally {
+        closeIndex();
+    }
+}
+/**
+ * Close the database connection
+ */
+export function closeIndex() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}

package/dist/lib/markdown.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Markdown processing utilities
+ *
+ * Handles DocC-flavored markdown and converts it to clean, AI-friendly markdown.
+ */
+import type { DocWithContent } from "./index.js";
+/**
+ * Extract the title from a markdown document
+ * Handles both standard markdown headers and DocC frontmatter
+ */
+export declare function extractTitle(content: string): string | null;
+/**
+ * Clean DocC-flavored markdown for better search and AI consumption
+ */
+export declare function cleanMarkdown(content: string): string;
+/**
+ * Format a document for output to the terminal/AI
+ */
+export declare function formatDocForOutput(doc: DocWithContent): string;

package/dist/lib/markdown.js

@@ -0,0 +1,58 @@
+/**
+ * Markdown processing utilities
+ *
+ * Handles DocC-flavored markdown and converts it to clean, AI-friendly markdown.
+ */
+/**
+ * Extract the title from a markdown document
+ * Handles both standard markdown headers and DocC frontmatter
+ */
+export function extractTitle(content) {
+    // Try to find a DocC title directive: # ``SymbolName``
+    const doccTitleMatch = content.match(/^#\s+``([^`]+)``/m);
+    if (doccTitleMatch) {
+        return doccTitleMatch[1];
+    }
+    // Try standard markdown h1
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    if (h1Match) {
+        return h1Match[1].trim();
+    }
+    // Try YAML frontmatter title
+    const yamlMatch = content.match(/^---\s*\n.*?title:\s*(.+?)\n.*?---/s);
+    if (yamlMatch) {
+        return yamlMatch[1].trim().replace(/^["']|["']$/g, "");
+    }
+    return null;
+}
+/**
+ * Clean DocC-flavored markdown for better search and AI consumption
+ */
+export function cleanMarkdown(content) {
+    let cleaned = content;
+    // Remove DocC directives like @Metadata, @Options, etc.
+    cleaned = cleaned.replace(/@\w+\s*\{[^}]*\}/g, "");
+    // Convert DocC symbol references ``Symbol`` to just Symbol
+    cleaned = cleaned.replace(/``([^`]+)``/g, "$1");
+    // Convert DocC links like <doc:ArticleName> to [ArticleName]
+    cleaned = cleaned.replace(/<doc:([^>]+)>/g, "[$1]");
+    // Remove @Row, @Column and other DocC layout directives
+    cleaned = cleaned.replace(/@(Row|Column|Image|Video|Links|TabNavigator|Tab)\s*(\{[^}]*\})?/g, "");
+    // Clean up excessive whitespace
+    cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+    return cleaned.trim();
+}
+/**
+ * Format a document for output to the terminal/AI
+ */
+export function formatDocForOutput(doc) {
+    const header = `# ${doc.title}
+
+> Library: ${doc.library}
+> Path: ${doc.path}
+
+---
+
+`;
+    return header + doc.content;
+}

package/dist/lib/repos.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Git operations for cloning and updating Point-Free repositories
+ */
+import { LibraryConfig } from "../config.js";
+/**
+ * Clone a library repository (sparse checkout, docs only)
+ */
+export declare function cloneLibrary(lib: LibraryConfig): Promise<void>;
+/**
+ * Update a library repository
+ */
+export declare function updateLibrary(lib: LibraryConfig): Promise<boolean>;
+/**
+ * Get all local paths to a library's docs
+ */
+export declare function getDocsPaths(lib: LibraryConfig): string[];
+/**
+ * Check if a library is cloned
+ */
+export declare function isLibraryCloned(lib: LibraryConfig): boolean;

package/dist/lib/repos.js

@@ -0,0 +1,76 @@
+/**
+ * Git operations for cloning and updating Point-Free repositories
+ */
+import { simpleGit } from "simple-git";
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { PATHS } from "../config.js";
+/**
+ * Clone a library repository (sparse checkout, docs only)
+ */
+export async function cloneLibrary(lib) {
+    const repoDir = join(PATHS.reposDir, lib.name);
+    // Ensure repos directory exists
+    if (!existsSync(PATHS.reposDir)) {
+        mkdirSync(PATHS.reposDir, { recursive: true });
+    }
+    if (existsSync(repoDir)) {
+        console.log(`  Repository already exists: ${lib.name}`);
+        return;
+    }
+    console.log(`  Cloning ${lib.repo}...`);
+    const git = simpleGit();
+    // Sparse checkout: only download docs directories
+    await git.clone(`https://github.com/${lib.repo}.git`, repoDir, [
+        "--depth",
+        "1",
+        "--filter=blob:none",
+        "--sparse",
+    ]);
+    const repoGit = simpleGit(repoDir);
+    // Set up sparse checkout to only get the docs folders
+    await repoGit.raw(["sparse-checkout", "init", "--cone"]);
+    // Set all docs paths for this library
+    await repoGit.raw(["sparse-checkout", "set", ...lib.docsPaths]);
+    console.log(`  ✓ Cloned ${lib.shortName}`);
+}
+/**
+ * Update a library repository
+ */
+export async function updateLibrary(lib) {
+    const repoDir = join(PATHS.reposDir, lib.name);
+    if (!existsSync(repoDir)) {
+        console.log(`  Repository not found: ${lib.name}. Run 'pf-docs init' first.`);
+        return false;
+    }
+    console.log(`  Updating ${lib.shortName}...`);
+    const git = simpleGit(repoDir);
+    try {
+        const pullResult = await git.pull();
+        if (pullResult.summary.changes > 0) {
+            console.log(`  ✓ Updated ${lib.shortName} (${pullResult.summary.changes} changes)`);
+            return true;
+        }
+        else {
+            console.log(`  ✓ ${lib.shortName} is up to date`);
+            return false;
+        }
+    }
+    catch (error) {
+        console.error(`  ✗ Failed to update ${lib.shortName}:`, error);
+        return false;
+    }
+}
+/**
+ * Get all local paths to a library's docs
+ */
+export function getDocsPaths(lib) {
+    return lib.docsPaths.map((docsPath) => join(PATHS.reposDir, lib.name, docsPath));
+}
+/**
+ * Check if a library is cloned
+ */
+export function isLibraryCloned(lib) {
+    const repoDir = join(PATHS.reposDir, lib.name);
+    return existsSync(repoDir);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pointfree-docs",
+  "version": "0.1.0",
+  "description": "CLI tool for searching Point-Free library documentation",
+  "type": "module",
+  "bin": {
+    "pf-docs": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "link": "npm run build && npm link",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ronnie3786/pointfree-docs.git"
+  },
+  "keywords": [
+    "pointfree",
+    "point-free",
+    "swift",
+    "documentation",
+    "cli",
+    "composable-architecture",
+    "tca"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "commander": "^12.0.0",
+    "glob": "^10.3.0",
+    "simple-git": "^3.22.0",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.9",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}