@koffeekat/diana 0.0.0-stage → 0.1.0-beta.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "koffeeapps-diana",
+  "description": "Diana's shared knowledge-retrieval skill for Claude Code.",
+  "owner": {
+    "name": "KoffeeKat"
+  },
+  "plugins": [
+    {
+      "name": "diana",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "diana",
+  "version": "0.1.0-beta.1",
+  "description": "Search local Markdown knowledge through the read-only Diana CLI.",
+  "author": {
+    "name": "KoffeeKat"
+  },
+  "repository": "https://github.com/K0ffeeKat/diana"
+}

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KoffeeKat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+<div>
+  <img alt="diana-banner" src="./img/diana-banner.webp" />
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+  <p>&#8202;</p>
+  <h1 align="center">diana</h1>
+  <h4 align="center">A lightweight local Markdown search layer for agents</h4>
+  <p>&#8202;</p>
+</div>
+
+### Search for relevant sections and read only what you need.
+
+Backed by SQLite FTS5 and a selective indexing engine, Diana helps agents navigate large document collections with precision. It aims to reduce token usage and keep the context window uncluttered.
+
+<p>&#8202;</p>
+
+## Installation
+
+Requires **Node.js >=22.13.0**.
+
+```sh
+npm install -g @koffeekat/diana@beta
+```
+
+<p>&#8202;</p>
+
+## Quick start
+
+From your project root:
+
+```sh
+diana init
+```
+
+[Add a source](#adding-sources), then index it:
+
+```sh
+diana index
+```
+
+Run Diana from this same root. `diana index` refreshes every configured source.
+
+> Quick hint: consider adding `diana index` as a pre-commit hook.
+
+<p>&#8202;</p>
+
+## Other CLI commands
+
+| Command                                                     | What it does                                               |
+| ----------------------------------------------------------- | ---------------------------------------------------------- |
+| `diana search "token rotation"`                             | Find matching sections. Words are ANDed; results are JSON. |
+| `diana read notes/architecture.md`                          | Read a note with limited output, returned as JSON.         |
+| `diana read notes/architecture.md --section token-rotation` | Read one section using its search-result anchor.           |
+| `diana --help`                                              | Show available commands.                                   |
+
+Search-result `path` values are relative to `sourceRoot`; join both for an absolute read path. If a read returns `truncated: true`, request a narrower section where possible.
+
+<p>&#8202;</p>
+
+## Adding sources
+
+Edit `diana.config.json` to share project sources:
+
+```json
+{
+  "version": 1,
+  "sources": [
+    {
+      "path": "notes",
+      "include": ["**/*.md"],
+      "exclude": ["drafts/**"]
+    }
+  ]
+}
+```
+
+> The directory must already exist. Exclude patterns take priority. Use `exclude: []` when nothing should be excluded.
+
+- **Project config — `diana.config.json`:** commit it so teammates share the same setup. Sources must stay inside the project.
+- **Local config — `.diana/local.config.json`:** same format, for personal sources, including directories outside the project. Use an absolute path for an external source directory; `~` isn't expanded. Relative paths in either config start at the project root.
+
+For example, `.diana/local.config.json` can point to a personal source directory:
+
+```json
+{
+  "version": 1,
+  "sources": [
+    {
+      "path": "/Users/you/Documents/personal-notes",
+      "include": ["**/*.md"],
+      "exclude": [],
+      "autoReindex": true
+    }
+  ]
+}
+```
+
+Replace the path with your source directory's absolute path, then run `diana index` once.
+
+- `autoReindex` - refresh this source before each search. Useful for sources updated independently of your project. Defaults to false.
+
+> 💡 Prefer pre-commit/post-merge hooks when commit-level freshness is enough. Use autoReindex when searches should also pick up uncommitted changes; it reads and hashes the source’s included files on every search.
+
+**Keep the generated `.diana/.gitignore`.** It excludes your local config and index, helping prevent personal paths and cached note content from being committed. Git ignore rules aren't access controls; review both configs in unfamiliar projects. See [security and privacy](docs/security.md).
+
+<p>&#8202;</p>
+
+## Installing skills
+
+Skills teach agents to search first and read only relevant sections. Install the CLI above first; your harness manages skill installation.
+
+**Pi**
+
+```sh
+pi install npm:@koffeekat/diana@beta
+```
+
+Reload with `/reload` if needed; invoke `/skill:diana`.
+
+**Claude Code**
+
+```text
+/plugin marketplace add K0ffeeKat/diana
+/plugin install diana@koffeeapps-diana
+```
+
+Invoke `/diana:diana`.
+
+**Codex** — ask `$skill-installer`:
+
+```text
+Install skills/diana from the GitHub repository K0ffeeKat/diana.
+```
+
+Invoke `$diana` once available.
+
+<p>&#8202;</p>
+
+## Using Diana with Obsidian
+
+Your vault can live inside the project:
+
+```text
+project/
+├── diana.config.json        # source path: "notes"
+├── .diana/                  # local config and index
+└── notes/                   # open this folder as an Obsidian vault
+    ├── .obsidian/           # skipped by Diana
+    └── architecture.md
+```
+
+Keep editing in Obsidian as usual. Diana indexes the Markdown, skips hidden entries and symlinks, and leaves the vault unchanged. An external vault works through the local config instead.
+
+<p>&#8202;</p>
+
+## Troubleshooting
+
+- **Command not found:** check the npm installation and your PATH. Installing a skill alone doesn't install the CLI.
+- **No configuration:** run from the project root, where you ran `diana init`.
+- **No sources/index, outdated schema, or stale results:** add a source if needed, check its patterns, and run `diana index`. Automatic refresh still needs an initial, compatible index.
+- **Source outside project:** put it in the local config, not the project config.
+- **Section not found:** reindex for current anchors; omit `--section` for headingless notes or pre-heading text.
+- **File too large:** split notes larger than 1 MiB; requesting a section doesn't bypass this limit.
+
+Removed sources disappear from cached results on the next successful search, even if no sources remain. To discard the cache entirely, stop Diana commands and delete only `.diana/index.sqlite`; preserve your local config.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { initializeWorkspace } from "./commands/init.js";
+import { indexWorkspace } from "./commands/index.js";
+import { readWorkspace } from "./commands/read.js";
+import { searchWorkspace } from "./commands/search.js";
+const [command, ...arguments_] = process.argv.slice(2);
+const USAGE_HINT = `Usage:
+  diana <command>
+
+Commands:
+  init
+  index
+  search <query...>
+  read <path> [--section <anchor>]
+`;
+try {
+    if ((command === "init" ||
+        command === "index" ||
+        command === "--help" ||
+        command === "-h") &&
+        arguments_.length > 0) {
+        throw new Error(`Usage: diana ${command}.`);
+    }
+    switch (command) {
+        case undefined:
+        case "--help":
+        case "-h":
+            process.stdout.write(USAGE_HINT);
+            break;
+        case "init":
+            await initializeWorkspace(process.cwd());
+            process.stdout.write('Initialized Diana workspace.\nAdd sources to diana.config.json or .diana/local.config.json, then run "diana index".\n');
+            break;
+        case "index":
+            await indexWorkspace(process.cwd());
+            process.stdout.write("Index updated.\n");
+            break;
+        case "search": {
+            const results = await searchWorkspace(process.cwd(), arguments_.join(" "));
+            process.stdout.write(`${JSON.stringify(results)}\n`);
+            break;
+        }
+        case "read": {
+            const { path, section } = parseReadArguments(arguments_);
+            const result = await readWorkspace(process.cwd(), path, section);
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+            break;
+        }
+        default:
+            throw new Error(`Unknown command: ${command}\nRun "diana --help" for usage.`);
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message.trim() : "Unexpected error.";
+    process.stderr.write(`Error: ${message}\n`);
+    process.exitCode = 1;
+}
+function parseReadArguments(arguments_) {
+    const [path, ...options] = arguments_;
+    if (path === undefined) {
+        throw new Error("Read path must not be empty.");
+    }
+    if (options.length === 0) {
+        return { path };
+    }
+    const section = options[1];
+    if (options.length === 2 &&
+        options[0] === "--section" &&
+        section !== undefined &&
+        section !== "") {
+        return { path, section };
+    }
+    throw new Error("Usage: diana read <path> [--section <anchor>].");
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/index.d.ts

@@ -0,0 +1,4 @@
+export declare const COMMAND_INDEX_ERRORS: {
+    readonly noSourcesConfiguredError: "No sources configured. Add a source to diana.config.json or .diana/local.config.json.";
+};
+export declare function indexWorkspace(workspaceRoot: string): Promise<void>;

package/dist/commands/index.js

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import { updateIndex } from "../indexer.js";
+import { resolveSources } from "../sources.js";
+import { WORKSPACE_CONSTANTS, loadWorkspace } from "../workspace.js";
+const { databaseFileName, internalDirName } = WORKSPACE_CONSTANTS;
+export const COMMAND_INDEX_ERRORS = {
+    noSourcesConfiguredError: "No sources configured. Add a source to diana.config.json or .diana/local.config.json.",
+};
+const { noSourcesConfiguredError } = COMMAND_INDEX_ERRORS;
+export async function indexWorkspace(workspaceRoot) {
+    const workspace = await loadWorkspace(workspaceRoot);
+    if (workspace.sources.length === 0) {
+        throw new Error(noSourcesConfiguredError);
+    }
+    const sources = await resolveSources(workspace);
+    const databasePath = join(workspace.root, internalDirName, databaseFileName);
+    await updateIndex(databasePath, sources);
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAAC;AAElE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,wBAAwB,EACtB,uFAAuF;CACjF,CAAC;AAEX,MAAM,EAAE,wBAAwB,EAAE,GAAG,oBAAoB,CAAC;AAE1D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,aAAqB;IACxD,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IAErD,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;IAEhD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;IAC7E,MAAM,WAAW,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,4 @@
+export declare const COMMAND_INIT_ERRORS: {
+    readonly dianaWorkspaceExistsError: (workspaceRoot: string) => string;
+};
+export declare function initializeWorkspace(workspaceRoot: string): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { WORKSPACE_CONSTANTS } from "../workspace.js";
+import { configTemplate } from "../templates/config.template.js";
+import { gitIgnoreTemplate } from "../templates/gitignore.template.js";
+import { pathExists } from "../utils/pathExists.js";
+const { configFileName, internalDirName, internalGitIgnoreName, localConfigFileName, } = WORKSPACE_CONSTANTS;
+export const COMMAND_INIT_ERRORS = {
+    dianaWorkspaceExistsError: (workspaceRoot) => `\nDiana workspace already exists at ${workspaceRoot}.\nRemove ${configFileName} and ${internalDirName}/, then call <diana init> for re-initialization.\n`,
+};
+const { dianaWorkspaceExistsError } = COMMAND_INIT_ERRORS;
+export async function initializeWorkspace(workspaceRoot) {
+    const pathToSharedConfig = join(workspaceRoot, configFileName);
+    const pathToInternalDir = join(workspaceRoot, internalDirName);
+    const pathToGitIgnore = join(pathToInternalDir, internalGitIgnoreName);
+    const pathToLocalConfig = join(pathToInternalDir, localConfigFileName);
+    const [sharedConfigExists, internalDirExists] = await Promise.all([
+        pathExists(pathToSharedConfig),
+        pathExists(pathToInternalDir),
+    ]);
+    if (sharedConfigExists || internalDirExists) {
+        throw new Error(dianaWorkspaceExistsError(workspaceRoot));
+    }
+    const sharedConfig = `${JSON.stringify(configTemplate, null, 2)}\n`;
+    await writeFile(pathToSharedConfig, sharedConfig, {
+        flag: "wx",
+    });
+    await mkdir(pathToInternalDir);
+    await writeFile(pathToGitIgnore, gitIgnoreTemplate, {
+        flag: "wx",
+    });
+    await writeFile(pathToLocalConfig, sharedConfig, {
+        flag: "wx",
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,MAAM,EACJ,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,mBAAmB,GACpB,GAAG,mBAAmB,CAAC;AAExB,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,yBAAyB,EAAE,CAAC,aAAqB,EAAE,EAAE,CACnD,uCAAuC,aAAa,aAAa,cAAc,QAAQ,eAAe,oDAAoD;CACpJ,CAAC;AAEX,MAAM,EAAE,yBAAyB,EAAE,GAAG,mBAAmB,CAAC;AAE1D,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,aAAqB;IAErB,MAAM,kBAAkB,GAAG,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC/D,MAAM,iBAAiB,GAAG,IAAI,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAC/D,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;IACvE,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;IAEvE,MAAM,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChE,UAAU,CAAC,kBAAkB,CAAC;QAC9B,UAAU,CAAC,iBAAiB,CAAC;KAC9B,CAAC,CAAC;IAEH,IAAI,kBAAkB,IAAI,iBAAiB,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IAEpE,MAAM,SAAS,CAAC,kBAAkB,EAAE,YAAY,EAAE;QAChD,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IACH,MAAM,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC/B,MAAM,SAAS,CAAC,eAAe,EAAE,iBAAiB,EAAE;QAClD,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IACH,MAAM,SAAS,CAAC,iBAAiB,EAAE,YAAY,EAAE;QAC/C,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/read.d.ts

@@ -0,0 +1,13 @@
+export declare const COMMAND_READ_ERRORS: {
+    readonly emptyPathError: "Read path must not be empty.";
+    readonly fileTooLargeError: (filePath: string) => string;
+    readonly invalidPathError: (filePath: string) => string;
+    readonly sectionNotFoundError: (anchor: string) => string;
+};
+export type ReadResult = {
+    content: string;
+    path: string;
+    sourceRoot: string;
+    truncated: boolean;
+};
+export declare function readWorkspace(workspaceRoot: string, requestedPath: string, section?: string): Promise<ReadResult>;

package/dist/commands/read.js

@@ -0,0 +1,74 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, posix, relative, resolve, sep } from "node:path";
+import { extractMarkdownSection } from "../indexer.js";
+import { resolveSources } from "../sources.js";
+import { loadWorkspace } from "../workspace.js";
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_OUTPUT_CHARACTERS = 64 * 1024;
+const PROTECTED_DIRECTORY_NAMES = new Set([".diana", ".git"]);
+export const COMMAND_READ_ERRORS = {
+    emptyPathError: "Read path must not be empty.",
+    fileTooLargeError: (filePath) => `Source file exceeds the ${MAX_FILE_BYTES}-byte read limit: ${filePath}.`,
+    invalidPathError: (filePath) => `Path is not a readable Markdown file in a configured source: ${filePath}.`,
+    sectionNotFoundError: (anchor) => `Section not found: ${anchor}.`,
+};
+const { emptyPathError, fileTooLargeError, invalidPathError, sectionNotFoundError, } = COMMAND_READ_ERRORS;
+export async function readWorkspace(workspaceRoot, requestedPath, section) {
+    if (requestedPath.trim() === "") {
+        throw new Error(emptyPathError);
+    }
+    const workspace = await loadWorkspace(workspaceRoot);
+    const configuredPath = resolve(workspace.root, requestedPath);
+    const filePath = await realpath(configuredPath);
+    const source = findContainingSource(filePath, await resolveSources(workspace));
+    if (source === undefined || !isReadableSourceFile(filePath, source)) {
+        throw new Error(invalidPathError(configuredPath));
+    }
+    const fileStats = await stat(filePath);
+    if (!fileStats.isFile()) {
+        throw new Error(invalidPathError(configuredPath));
+    }
+    if (fileStats.size > MAX_FILE_BYTES) {
+        throw new Error(fileTooLargeError(filePath));
+    }
+    const markdown = await readFile(filePath, "utf8");
+    const content = section === undefined ? markdown : readSection(markdown, section);
+    return {
+        content: content.slice(0, MAX_OUTPUT_CHARACTERS),
+        path: toDocumentPath(source.sourceRoot, filePath),
+        sourceRoot: source.sourceRoot,
+        truncated: content.length > MAX_OUTPUT_CHARACTERS,
+    };
+}
+function readSection(markdown, section) {
+    const content = extractMarkdownSection(markdown, section);
+    if (content === undefined) {
+        throw new Error(sectionNotFoundError(section));
+    }
+    return content;
+}
+function findContainingSource(filePath, sources) {
+    return sources.find((source) => isPathInside(source.sourceRoot, filePath));
+}
+function isReadableSourceFile(filePath, source) {
+    const documentPath = toDocumentPath(source.sourceRoot, filePath);
+    const pathSegments = documentPath.split("/");
+    return (filePath.endsWith(".md") &&
+        !pathSegments.some(isProtectedOrHidden) &&
+        source.include.some((pattern) => posix.matchesGlob(documentPath, pattern)) &&
+        !source.exclude.some((pattern) => posix.matchesGlob(documentPath, pattern)));
+}
+function isProtectedOrHidden(pathSegment) {
+    return (pathSegment.startsWith(".") || PROTECTED_DIRECTORY_NAMES.has(pathSegment));
+}
+function isPathInside(parentPath, childPath) {
+    const relativePath = relative(parentPath, childPath);
+    return (relativePath === "" ||
+        (relativePath !== ".." &&
+            !relativePath.startsWith(`..${sep}`) &&
+            !isAbsolute(relativePath)));
+}
+function toDocumentPath(sourceRoot, filePath) {
+    return relative(sourceRoot, filePath).split(sep).join("/");
+}
+//# sourceMappingURL=read.js.map

package/dist/commands/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/commands/read.ts"],"names":[],"mappings":"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"}

package/dist/commands/search.d.ts

@@ -0,0 +1,13 @@
+export declare const COMMAND_SEARCH_ERRORS: {
+    readonly emptyQueryError: "Search query must not be empty.";
+    readonly indexNotFoundError: "No index found. Run diana index first.";
+};
+export type SearchResult = {
+    anchor: string;
+    excerpt: string;
+    heading: string;
+    path: string;
+    sourceRoot: string;
+    title: string;
+};
+export declare function searchWorkspace(workspaceRoot: string, query: string): Promise<SearchResult[]>;

package/dist/commands/search.js

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { updateIndex } from "../indexer.js";
+import { resolveSources } from "../sources.js";
+import { WORKSPACE_CONSTANTS, loadWorkspace } from "../workspace.js";
+import { pathExists } from "../utils/pathExists.js";
+const { databaseFileName, internalDirName } = WORKSPACE_CONSTANTS;
+export const COMMAND_SEARCH_ERRORS = {
+    emptyQueryError: "Search query must not be empty.",
+    indexNotFoundError: "No index found. Run diana index first.",
+};
+const { emptyQueryError, indexNotFoundError } = COMMAND_SEARCH_ERRORS;
+export async function searchWorkspace(workspaceRoot, query) {
+    if (query.trim() === "") {
+        throw new Error(emptyQueryError);
+    }
+    const workspace = await loadWorkspace(workspaceRoot);
+    const databasePath = join(workspace.root, internalDirName, databaseFileName);
+    if (!(await pathExists(databasePath))) {
+        throw new Error(indexNotFoundError);
+    }
+    await updateIndex(databasePath, await resolveSources(workspace), "auto");
+    const database = new DatabaseSync(databasePath, { readOnly: true });
+    try {
+        return database
+            .prepare(`
+        SELECT
+          source_root AS sourceRoot,
+          path,
+          title,
+          heading,
+          anchor,
+          snippet(sections, 5, '', '', '…', 24) AS excerpt
+        FROM sections
+        WHERE sections MATCH ?
+        ORDER BY bm25(sections)
+        LIMIT 10
+      `)
+            .all(toFtsQuery(query));
+    }
+    finally {
+        database.close();
+    }
+}
+function toFtsQuery(query) {
+    return query
+        .trim()
+        .split(/\s+/)
+        .map((term) => `"${term.replaceAll('"', '""')}"`)
+        .join(" AND ");
+}
+//# sourceMappingURL=search.js.map

package/dist/commands/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAAC;AAElE,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,eAAe,EAAE,iCAAiC;IAClD,kBAAkB,EAAE,wCAAwC;CACpD,CAAC;AAEX,MAAM,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,qBAAqB,CAAC;AAWtE,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,aAAqB,EACrB,KAAa;IAEb,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;IAE7E,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,WAAW,CAAC,YAAY,EAAE,MAAM,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAEpE,IAAI,CAAC;QACH,OAAO,QAAQ;aACZ,OAAO,CACN;;;;;;;;;;;;OAYD,CACA;aACA,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAmB,CAAC;IAC9C,CAAC;YAAS,CAAC;QACT,QAAQ,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK;SACT,IAAI,EAAE;SACN,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;SAChD,IAAI,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC"}

package/dist/indexer.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedSource } from "./types/source.types.js";
+export declare const INDEX_ERRORS: {
+    readonly invalidTextError: (filePath: string) => string;
+    readonly fileTooLargeError: (filePath: string) => string;
+    readonly schemaRebuildError: "Index schema changed. Run diana index to rebuild it.";
+};
+export type IndexedSection = {
+    anchor: string;
+    body: string;
+    heading: string;
+    title: string;
+};
+export declare function updateIndex(databasePath: string, sources: ResolvedSource[], mode?: "all" | "auto"): Promise<void>;
+export declare function findMarkdownFiles(source: ResolvedSource): Promise<string[]>;
+export declare function extractMarkdownSection(markdown: string, requestedAnchor: string): string | undefined;
+export declare function splitMarkdownIntoSections(markdown: string, filePath: string): IndexedSection[];