pi-para 0.6.3 → 0.6.5

package/src/lint.ts

@@ -24,6 +24,7 @@ import {
   extractWikilinks,
   removeWikilink,
   autoLinkSlugs,
+  findUnlinkedSlugs,
   syncFrontmatterLinks,
 } from "./link-utils.js";
 import { normalizeTags, normalizeScopes } from "./tag-registry.js";
@@ -415,22 +416,9 @@ function checkLinkSync(
 ): LintIssue[] {
   const issues: LintIssue[] = [];
   for (const p of pages) {
-    // Find slugs mentioned in body but not wrapped in [[...]]
-    const bodyLinks = new Set(extractWikilinks(p.body));
-    const sortedSlugs = [...allSlugs]
-      .filter(s => s !== p.slug)
-      .sort((a, b) => b.length - a.length);
-
-    const unlinked: string[] = [];
-    for (const slug of sortedSlugs) {
-      if (bodyLinks.has(slug)) continue;
-      // Check if slug appears as plain text in body (word-boundary match)
-      const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const re = new RegExp(`(?<![a-z0-9-])${escaped}(?![a-z0-9-])`);
-      if (re.test(p.body)) {
-        unlinked.push(slug);
-      }
-    }
+    // Use the exact same protected-range semantics as the fixer so every
+    // auto-fixable issue is actionable (no code-block/heading false positives).
+    const unlinked = findUnlinkedSlugs(p.body, allSlugs, p.slug);
 
     if (unlinked.length > 0) {
       issues.push({
@@ -603,7 +591,9 @@ async function fixSecrets(
           updated: new Date().toISOString(),
         },
       };
-      await writePage(wikiDir, fixedPage);
+      p.body = fixedPage.body;
+      p.frontmatter = fixedPage.frontmatter;
+      await writePage(wikiDir, p);
 
       fixed.push({
         severity: "error",
@@ -650,7 +640,9 @@ async function fixLinkSync(
           updated: new Date().toISOString(),
         },
       };
-      await writePage(wikiDir, fixedPage);
+      p.body = fixedPage.body;
+      p.frontmatter = fixedPage.frontmatter;
+      await writePage(wikiDir, p);
 
       if (addedLinks.length > 0) {
         fixed.push({
@@ -729,7 +721,9 @@ async function fixBrokenLinks(
       body: newBody,
       frontmatter: { ...p.frontmatter, links: newFmLinks },
     };
-    await writePage(wikiDir, fixedPage);
+    p.body = fixedPage.body;
+    p.frontmatter = fixedPage.frontmatter;
+    await writePage(wikiDir, p);
 
     for (const link of broken) {
       fixed.push({
@@ -931,11 +925,10 @@ export async function lintWiki(
 
   // Load all pages
   const refs = await listPages(wikiDir);
-  const pages: WikiPage[] = [];
-  for (const ref of refs) {
-    const page = await readPage(wikiDir, ref.category, ref.slug);
-    if (page) pages.push(page);
-  }
+  const loadedPages = await Promise.all(
+    refs.map((ref) => readPage(wikiDir, ref.category, ref.slug)),
+  );
+  const pages = loadedPages.filter((page): page is WikiPage => page !== null);
 
   // Build slug set
   const allSlugs = new Set(pages.map((p) => p.slug));
@@ -978,15 +971,38 @@ export async function lintWiki(
   // Auto-fix if enabled
   const fixed: LintIssue[] = [];
   if (autoFix) {
-    // Fix secrets first — highest priority
-    fixed.push(...(await fixSecrets(wikiDir, pages)));
-    fixed.push(...(await fixBrokenLinks(wikiDir, pages, allSlugs)));
-    fixed.push(...(await fixLinkSync(wikiDir, pages, allSlugs)));
-    fixed.push(...(await fixTagHealth(wikiDir, pages)));
-    fixed.push(...(await fixIndexDrift(wikiDir, pages, indexContent)));
-    fixed.push(...(await fixFrontmatter(wikiDir, pages)));
-    fixed.push(...(await fixScopeDrift(wikiDir, pages)));
-    fixed.push(...(await fixSchemaVersion(wikiDir, pages)));
+    // Only run a fixer against pages its check identified. Previously every
+    // fixer rescanned all P pages (and link sync scanned all S slugs per page)
+    // even when that category had zero issues.
+    const affectedPages = (category: LintIssue["category"]): WikiPage[] => {
+      const paths = new Set(
+        issues
+          .filter((issue) => issue.category === category && issue.autoFixable && issue.page)
+          .map((issue) => issue.page!),
+      );
+      return paths.size === 0
+        ? []
+        : pages.filter((page) => paths.has(`${page.category}/${page.slug}`));
+    };
+    const hasIssue = (category: LintIssue["category"]): boolean =>
+      issues.some((issue) => issue.category === category && issue.autoFixable);
+
+    // Fix secrets first — highest priority.
+    const secretPages = affectedPages("secrets");
+    if (secretPages.length > 0) fixed.push(...(await fixSecrets(wikiDir, secretPages)));
+    const brokenPages = affectedPages("broken-link");
+    if (brokenPages.length > 0) fixed.push(...(await fixBrokenLinks(wikiDir, brokenPages, allSlugs)));
+    const linkPages = affectedPages("link-sync");
+    if (linkPages.length > 0) fixed.push(...(await fixLinkSync(wikiDir, linkPages, allSlugs)));
+    const tagPages = affectedPages("tag-health");
+    if (tagPages.length > 0) fixed.push(...(await fixTagHealth(wikiDir, tagPages)));
+    if (hasIssue("index-drift")) fixed.push(...(await fixIndexDrift(wikiDir, pages, indexContent)));
+    const frontmatterPages = affectedPages("frontmatter");
+    if (frontmatterPages.length > 0) fixed.push(...(await fixFrontmatter(wikiDir, frontmatterPages)));
+    const scopePages = affectedPages("scope-drift");
+    if (scopePages.length > 0) fixed.push(...(await fixScopeDrift(wikiDir, scopePages)));
+    const schemaPages = affectedPages("schema-version");
+    if (schemaPages.length > 0) fixed.push(...(await fixSchemaVersion(wikiDir, schemaPages)));
   }
 
   // Recount broken links for stats

package/src/scheduler/index.ts

@@ -1,7 +1,7 @@
 import type { QMDStore } from "qmd-engine";
 import { randomUUID } from "node:crypto";
 import { gitCommit, rebuildIndex } from "../wiki.js";
-import { reindex } from "../store.js";
+import { reindex, storeHasApiProviders } from "../store.js";
 import { getParaPaths } from "../paths.js";
 import { acquireLease, releaseLease } from "./leases.js";
 import { SchedulerStateDB, type QueueItem } from "./state.js";
@@ -155,6 +155,9 @@ export class WikiScheduler {
   private async runQmdEmbed(): Promise<void> {
     const store = this.storeProvider();
     if (!store) return;
+    // No real embedding provider configured — embed calls would hit the inert
+    // shim endpoint (slow TCP timeouts on Windows) and always fail. Skip.
+    if (!storeHasApiProviders(store)) return;
 
     const status = await store.getStatus();
     const pending = status.needsEmbedding ?? 0;

package/src/status.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import Database from "better-sqlite3";
 import { loadParaConfig } from "./config.js";
 import { getParaPaths } from "./paths.js";
 import { listPages, type ParaCategory } from "./wiki.js";
@@ -20,6 +21,8 @@ export interface PiParaStatusResult {
   };
   scheduler: Record<QueueStatus, number>;
   qmdDbExists: boolean;
+  /** Read-only probe of the QMD DB (null when the DB doesn't exist/can't be read). */
+  embedding: { hasVectorIndex: boolean; needsEmbedding: number } | null;
   warnings: string[];
 }
 
@@ -46,6 +49,7 @@ export async function getPiParaStatus(options: PiParaStatusOptions = {}): Promis
     pages,
     scheduler,
     qmdDbExists: existsSync(paths.qmdDbPath),
+    embedding: getQmdEmbeddingStats(paths.qmdDbPath, warnings),
     warnings,
   };
 }
@@ -58,6 +62,9 @@ export function formatPiParaStatus(status: PiParaStatusResult): string {
     `  Pages: ${status.pages.total} total (${formatCategoryCounts(status.pages.byCategory)})`,
     `  Scheduler: ${status.scheduler.queued} queued, ${status.scheduler.running} running, ${status.scheduler.failed} failed`,
     `  QMD SDK DB: ${status.qmdDbExists ? status.qmdDbPath : "not initialized"}`,
+    ...(status.embedding
+      ? [`  Embeddings: vector index ${status.embedding.hasVectorIndex ? "yes" : "no"}, pending ${status.embedding.needsEmbedding}`]
+      : []),
   ];
 
   if (status.warnings.length > 0) {
@@ -110,6 +117,43 @@ function getSchedulerCounts(dbPath: string, warnings: string[]): Record<QueueSta
   return counts;
 }
 
+/**
+ * Cheap read-only probe of the QMD SQLite DB for embedding state — avoids
+ * opening the full store (~1s). Mirrors qmd-engine's getHashesNeedingEmbedding
+ * query (documents ⋈ content_vectors), which is stable across qmd 2.x.
+ */
+function getQmdEmbeddingStats(
+  dbPath: string,
+  warnings: string[],
+): { hasVectorIndex: boolean; needsEmbedding: number } | null {
+  if (!existsSync(dbPath)) return null;
+  try {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+      const tables = new Set(
+        (db.prepare("SELECT name FROM sqlite_master WHERE type IN ('table','view')").all() as Array<{ name: string }>)
+          .map((row) => row.name),
+      );
+      if (!tables.has("documents") || !tables.has("content_vectors")) {
+        return { hasVectorIndex: false, needsEmbedding: 0 };
+      }
+      const vectors = db.prepare("SELECT COUNT(*) AS c FROM content_vectors").get() as { c: number };
+      const pending = db.prepare(`
+        SELECT COUNT(DISTINCT d.hash) AS c
+        FROM documents d
+        LEFT JOIN content_vectors v ON d.hash = v.hash AND v.seq = 0
+        WHERE d.active = 1 AND v.hash IS NULL
+      `).get() as { c: number };
+      return { hasVectorIndex: vectors.c > 0, needsEmbedding: pending.c };
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    warnings.push(`could not read QMD embedding stats: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
 function formatCategoryCounts(counts: Record<ParaCategory, number>): string {
   return `projects ${counts.projects}, areas ${counts.areas}, resources ${counts.resources}, archives ${counts.archives}`;
 }

package/src/store.ts

@@ -73,6 +73,21 @@ const RAW_CONTEXT = "Immutable source material: articles, documents, notes. Not
 
 const pendingEmbeds = new WeakMap<QMDStore, Promise<void>>();
 
+// -- Inert-provider tracking ---------------------------------------------------
+
+/** Stores opened with the NO_LOCAL_PROVIDERS shim (no real API provider). */
+const inertProviderStores = new WeakSet<QMDStore>();
+
+/**
+ * Whether the store was opened with a real (configured) embedding provider.
+ * When false, embedding calls would hit the inert shim endpoint and fail —
+ * slowly on platforms where localhost connects to closed ports time out
+ * (Windows firewall drops) — so background embedding must be skipped.
+ */
+export function storeHasApiProviders(store: QMDStore): boolean {
+  return !inertProviderStores.has(store);
+}
+
 // -- qmd provider config -----------------------------------------------------
 
 /**
@@ -132,6 +147,7 @@ export async function openStore(wikiDir: string, opts: OpenStoreOptions = {}): P
       })
     : loadQmdProviders();
   const providers = configuredProviders ?? NO_LOCAL_PROVIDERS;
+  const usingInertShim = !configuredProviders;
 
   const store = await createStore({
     dbPath: join(wikiDir, ".qmd.sqlite"),
@@ -152,6 +168,8 @@ export async function openStore(wikiDir: string, opts: OpenStoreOptions = {}): P
     },
   });
 
+  if (usingInertShim) inertProviderStores.add(store);
+
   // Add PARA category contexts to the wiki collection
   for (const [prefix, description] of Object.entries(PARA_CONTEXTS)) {
     await store.addContext("wiki", prefix, description);

package/src/tools.ts

@@ -860,13 +860,23 @@ function createMoveExecute(
 
 // -- Factory: wiki_lint execute ----------------------------------------------
 
-function createLintExecute(wikiDir: string) {
+function createLintExecute(
+  wikiDir: string,
+  store: QMDStore,
+  markDirty: () => void,
+  getLintConfig?: () => { autoFix: boolean; staleDays: number },
+) {
   return async (
     params: { autoFix?: boolean },
   ): Promise<AgentToolResult<WikiLintDetails>> => {
+    const configured = getLintConfig?.();
     const report = await lintWiki(wikiDir, {
-      autoFix: params.autoFix ?? true,
+      autoFix: params.autoFix ?? configured?.autoFix ?? true,
+      staleDays: configured?.staleDays ?? 90,
     });
+    if (report.fixed.length > 0) {
+      scheduleWikiMaintenance(wikiDir, store, markDirty);
+    }
 
     const { issues, fixed, stats } = report;
 
@@ -1057,6 +1067,7 @@ export function registerTools(
   getScope: () => ProjectScope,
   markDirty: () => void,
   getGraphBoost?: () => boolean,
+  getLintConfig?: () => { autoFix: boolean; staleDays: number },
 ): void {
   const ingestExec = createIngestExecute(wikiDir, store, getScope);
   const queryExec = createQueryExecute(wikiDir, store, getScope, getGraphBoost);
@@ -1064,7 +1075,7 @@ export function registerTools(
   const editExec = createEditExecute(wikiDir, store, markDirty);
   const readExec = createReadExecute(wikiDir);
   const moveExec = createMoveExecute(wikiDir, store, markDirty);
-  const lintExec = createLintExecute(wikiDir);
+  const lintExec = createLintExecute(wikiDir, store, markDirty, getLintConfig);
   const migrateExec = createMigrateExecute(wikiDir);
   const summarizeExec = createSummarizeExecute(wikiDir, getScope);
 
@@ -1306,7 +1317,8 @@ export function registerTools(
       try { return await lintExec(params); } finally { ctx.ui.setStatus("pi-para", undefined); }
     },
     renderCall(args, theme) {
-      const mode = args.autoFix === false ? "report-only" : "auto-fix";
+      const configuredAutoFix = getLintConfig?.().autoFix ?? true;
+      const mode = (args.autoFix ?? configuredAutoFix) ? "auto-fix" : "report-only";
       return new Text(
         theme.fg("toolTitle", theme.bold("wiki_lint ")) +
           theme.fg("muted", `[${mode}]`),