anchormd 0.1.0

package/src/qmd.ts

@@ -0,0 +1,136 @@
+/**
+ * QMD integration layer
+ *
+ * Integrates @tobilu/qmd for hybrid search over plan files.
+ * Requires Bun runtime (QMD uses better-sqlite3 and sqlite-vec).
+ */
+
+import path from 'node:path';
+import { createStore, type QMDStore } from '@tobilu/qmd';
+import type { AnchorConfig, SearchResult } from './types.js';
+
+export type QmdStore = QMDStore;
+
+// Cache the store instance to avoid recreating it on every call
+let cachedStore: QMDStore | null = null;
+let cachedStoreKey: string | null = null;
+
+/**
+ * Get a QMD store instance.
+ *
+ * Creates a QMD store backed by `.anchor/search.sqlite` with a single
+ * collection pointing at `.anchor/plans/`. The store is cached so
+ * subsequent calls with the same anchorDir reuse the same instance.
+ *
+ * Returns null when QMD is disabled in config.
+ */
+export async function getQmdStore(anchorDir: string, config: AnchorConfig): Promise<QMDStore | null> {
+  if (config.qmd === false) {
+    return null;
+  }
+
+  const dbPath = path.join(anchorDir, 'search.sqlite');
+  const plansPath = path.join(anchorDir, 'plans');
+
+  // Return cached store if it matches the same anchor directory
+  if (cachedStore && cachedStoreKey === anchorDir) {
+    return cachedStore;
+  }
+
+  // Close previous store if switching directories
+  if (cachedStore) {
+    await cachedStore.close();
+    cachedStore = null;
+    cachedStoreKey = null;
+  }
+
+  const store = await createStore({
+    dbPath,
+    config: {
+      collections: {
+        plans: {
+          path: plansPath,
+          pattern: '**/*.md',
+        },
+      },
+    },
+  });
+
+  cachedStore = store;
+  cachedStoreKey = anchorDir;
+
+  return store;
+}
+
+/**
+ * Reindex the QMD search database.
+ *
+ * Scans the plans directory for new/changed/removed files and updates
+ * the FTS and vector indexes.
+ *
+ * No-op when QMD is disabled or unavailable.
+ */
+export async function reindexQmd(store: QMDStore | null): Promise<void> {
+  if (store === null) {
+    return;
+  }
+
+  await store.update();
+  await store.embed();
+}
+
+/**
+ * Search using QMD.
+ *
+ * Supports three modes:
+ * - lexical: BM25 full-text search (fast, no LLM)
+ * - semantic: vector similarity search (uses embedding model)
+ * - hybrid: full pipeline with query expansion, multi-signal retrieval, and LLM reranking
+ *
+ * Throws a helpful error when QMD is not available.
+ */
+export async function searchQmd(
+  store: QMDStore | null,
+  query: string,
+  options: { mode: 'lexical' | 'semantic' | 'hybrid'; limit: number }
+): Promise<SearchResult[]> {
+  if (store === null) {
+    throw new Error(
+      'QMD search is not available. Ensure QMD is enabled in your project config.\n' +
+      'Run `anchormd init` (without --no-qmd) to enable QMD search.\n' +
+      'Use `anchormd read <plan>` or `anchormd ls` to find plans manually.'
+    );
+  }
+
+  switch (options.mode) {
+    case 'lexical': {
+      const results = await store.searchLex(query, { limit: options.limit });
+      return results.map(r => ({
+        path: r.displayPath,
+        score: r.score,
+        content: r.body,
+      }));
+    }
+
+    case 'semantic': {
+      const results = await store.searchVector(query, { limit: options.limit });
+      return results.map(r => ({
+        path: r.displayPath,
+        score: r.score,
+        content: r.body,
+      }));
+    }
+
+    case 'hybrid': {
+      const results = await store.search({
+        query,
+        limit: options.limit,
+      });
+      return results.map(r => ({
+        path: r.displayPath,
+        score: r.score,
+        content: r.bestChunk,
+      }));
+    }
+  }
+}

package/src/scaffold.ts

@@ -0,0 +1,97 @@
+/**
+ * Project initialization scaffold
+ *
+ * Creates the .anchor/ directory structure and template files
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { saveConfig, getAnchorDir, getPlansDir } from './config.js';
+import { writeIndex } from './index-graph.js';
+import { getQmdStore, reindexQmd } from './qmd.js';
+import { color } from './format.js';
+import type { IndexGraph } from './types.js';
+
+const TEMPLATE_ANCHOR_PLAN = `---
+name: anchor
+description: Project overview and architecture
+status: planned
+---
+# Project Overview
+
+Describe your project here.
+
+## Architecture
+
+## Key Decisions
+`;
+
+/**
+ * Initialize AnchorMD in a project directory.
+ *
+ * Creates:
+ * - .anchor/ directory
+ * - .anchor/plans/ directory with template anchor.md
+ * - .anchor/config.json
+ * - .anchor/index.json (empty graph)
+ * - Appends to .gitignore
+ */
+export async function scaffold(
+  projectRoot: string,
+  options: { qmd: boolean }
+): Promise<void> {
+  const anchorDir = getAnchorDir(projectRoot);
+  const plansDir = getPlansDir(projectRoot);
+
+  // Create directories
+  mkdirSync(plansDir, { recursive: true });
+
+  // Write config
+  saveConfig(projectRoot, { qmd: options.qmd });
+
+  // Write template plan
+  const templatePath = path.join(plansDir, 'anchor.md');
+  if (!existsSync(templatePath)) {
+    writeFileSync(templatePath, TEMPLATE_ANCHOR_PLAN, 'utf-8');
+  }
+
+  // Write empty index
+  const emptyGraph: IndexGraph = {
+    nodes: {},
+    lastBuilt: new Date().toISOString(),
+  };
+  writeIndex(anchorDir, emptyGraph);
+
+  // Append to .gitignore
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const gitignoreEntry = '.anchor/search.sqlite';
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes(gitignoreEntry)) {
+      appendFileSync(gitignorePath, `\n${gitignoreEntry}\n`, 'utf-8');
+    }
+  } else {
+    writeFileSync(gitignorePath, `${gitignoreEntry}\n`, 'utf-8');
+  }
+
+  // Initialize QMD if enabled
+  if (options.qmd) {
+    const store = await getQmdStore(anchorDir, { qmd: true });
+    await reindexQmd(store);
+  }
+
+  // Print success message
+  console.log(color.green('AnchorMD initialized successfully!'));
+  console.log('');
+  console.log('  Created:');
+  console.log(`    ${color.dim('.anchor/config.json')}`);
+  console.log(`    ${color.dim('.anchor/plans/anchor.md')}`);
+  console.log(`    ${color.dim('.anchor/index.json')}`);
+  console.log('');
+  console.log('  Next steps:');
+  console.log(`    1. Edit ${color.bold('.anchor/plans/anchor.md')} with your project overview`);
+  console.log(`    2. Run ${color.bold('anchormd write <plan-name>')} to create more plans`);
+  console.log(`    3. Run ${color.bold('anchormd context')} to see your project context`);
+  console.log('');
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared types for AnchorMD
+ */
+
+/** Valid plan status values */
+export type PlanStatus = 'planned' | 'in-progress' | 'built' | 'deprecated';
+
+/** All valid status values for runtime validation */
+export const VALID_STATUSES: PlanStatus[] = ['planned', 'in-progress', 'built', 'deprecated'];
+
+/** Frontmatter metadata for a plan file */
+export interface PlanFrontmatter {
+  name: string;
+  description: string;
+  status: PlanStatus;
+  tags?: string[];
+}
+
+/** A parsed plan file */
+export interface PlanFile {
+  frontmatter: PlanFrontmatter;
+  body: string;
+  filename: string;
+}
+
+/** A strong link: [[target]] */
+export interface StrongLink {
+  target: string;
+}
+
+/** A deep link: [[target#section]] */
+export interface DeepLink {
+  target: string;
+  section: string;
+}
+
+/** A link is either a strong link or a deep link */
+export type Link = StrongLink | DeepLink;
+
+/** Entity types extractable from plan content */
+export type EntityType = 'file' | 'model' | 'route' | 'script';
+
+/** An extracted entity reference */
+export interface Entity {
+  type: EntityType;
+  value: string;
+}
+
+/** A node in the index graph */
+export interface IndexGraphNode {
+  name: string;
+  links: string[];
+  entities: Entity[];
+  weakEdges: string[];
+}
+
+/** The full index graph */
+export interface IndexGraph {
+  nodes: Record<string, IndexGraphNode>;
+  lastBuilt: string;
+}
+
+/** Project configuration stored in .anchor/config.json */
+export interface AnchorConfig {
+  qmd: boolean;
+}
+
+/** Search result from QMD or fallback */
+export interface SearchResult {
+  path: string;
+  score: number;
+  content?: string;
+}