oh-my-second-brain 0.1.8 → 0.2.0

package/dist/engine/wiki/collection.d.ts

@@ -1,91 +0,0 @@
-/**
- * Wiki Collection Owner.
- *
- * Five responsibilities (Astro-Han collection owner pattern, MIT — idea absorption):
- *   1. Namespace / identity — concept ID → file path mapping
- *   2. Link-graph closure — verify no dangling [[wikilinks]]
- *   3. Staleness ledger — delegate to ledger.ts
- *   4. Navigation surfaces — delegate to navigation.ts
- *   5. Processed→wiki promotion — the ONLY path into wiki/
- *
- * Nvk 3-phase hard separation (Apache-2.0 — idea absorption):
- *   Research(M1) → Compile(M2, sequential) → Wiki(read-only query surface)
- *   - A wiki *query* NEVER triggers compile.
- *   - Compile NEVER writes wiki/ directly (promotion only).
- *   - wiki/ is a read-only query surface; compile writes to processed/ only.
- *   - Sync boundary: processed/ is engine-internal and is NEVER synced to the
- *     Obsidian vault. Only wiki/ crosses the Obsidian sync boundary.
- */
-import type { CascadeFlipResult, LinkClosureResult, NowFn, StalenessLedger } from "./types.js";
-/**
- * Map a concept ID (vault-relative path) to an absolute file path in wiki/.
- * Uses only the basename so nested concept IDs are flattened to wiki/ root.
- */
-export declare function conceptToWikiPath(wikiDir: string, conceptId: string): string;
-/**
- * Map a concept ID to its processed/ output path.
- */
-export declare function conceptToProcessedPath(processedDir: string, conceptId: string): string;
-/**
- * Extract all [[wikilink]] targets from a Markdown body.
- * Exported for use by lint.ts.
- */
-export declare function extractWikilinks(body: string): string[];
-/**
- * Check link-graph closure: every [[wikilink]] in `body` must resolve to a
- * page currently present in wiki/.
- *
- * @param wikiDir - Absolute path to the wiki/ directory.
- * @param body    - Markdown body to check.
- */
-export declare function checkLinkClosure(wikiDir: string, body: string): Promise<LinkClosureResult>;
-/**
- * Promote a compiled page from processed/ to wiki/.
- *
- * Called ONLY after the cascade pass completes.
- * Compile NEVER calls this directly — promotion is the sole entry point into wiki/.
- *
- * @param processedDir - Absolute path to the processed/ tier (Phase-B output).
- * @param wikiDir      - Absolute path to the wiki/ directory.
- * @param conceptId    - Vault-relative concept ID (basename used as filename).
- */
-export declare function promoteToWiki(processedDir: string, wikiDir: string, conceptId: string): Promise<void>;
-export interface CollectionRunOptions {
-    /** Absolute path to the processed/ tier (Phase-B compile output). */
-    processedDir: string;
-    /** Absolute path to the wiki/ directory (read-only query surface). */
-    wikiDir: string;
-    /** Absolute path to the .llmwiki/ dotfolder (ledger + SHA cache). */
-    dotLlmwiki: string;
-    /** Vault-relative concept ID that was just compiled. */
-    conceptId: string;
-    /** Human-readable concept name (for log.md). */
-    conceptName: string;
-    /** Backlinks returned by the M2 cascade pass (affected_backlinks). */
-    affectedBacklinks: readonly string[];
-    /** Injected clock returning ISO-8601 string. */
-    now: NowFn;
-}
-export interface CollectionRunResult {
-    /** Concept IDs whose CLEAN state was flipped to DIRTY by the cascade. */
-    cascadeFlipped: CascadeFlipResult;
-    /** Link-graph closure result for the newly promoted page. */
-    linkClosure: LinkClosureResult;
-    /** The ledger state after this run. */
-    ledger: StalenessLedger;
-}
-/**
- * Run a full collection cycle after a successful M2 compile.
- *
- * Order (enforced to satisfy nvk 3-phase separation):
- *   1. Promote processed/→wiki/ for the compiled concept.
- *   2. Mark compiled concept CLEAN in the ledger.
- *   3. Apply cascade: flip CLEAN backlinks to DIRTY.
- *   4. Detect stubs: wikilinks in the promoted page with no wiki/ target.
- *   5. Detect orphans: wiki/ pages with no incoming wikilinks.
- *   6. Regenerate navigation surfaces (index.md + log.md).
- *   7. Persist ledger.
- *
- * A wiki *query* NEVER calls this function (nvk hard separation enforced here).
- */
-export declare function runCollection(opts: CollectionRunOptions): Promise<CollectionRunResult>;

package/dist/engine/wiki/collection.js

@@ -1,188 +0,0 @@
-/**
- * Wiki Collection Owner.
- *
- * Five responsibilities (Astro-Han collection owner pattern, MIT — idea absorption):
- *   1. Namespace / identity — concept ID → file path mapping
- *   2. Link-graph closure — verify no dangling [[wikilinks]]
- *   3. Staleness ledger — delegate to ledger.ts
- *   4. Navigation surfaces — delegate to navigation.ts
- *   5. Processed→wiki promotion — the ONLY path into wiki/
- *
- * Nvk 3-phase hard separation (Apache-2.0 — idea absorption):
- *   Research(M1) → Compile(M2, sequential) → Wiki(read-only query surface)
- *   - A wiki *query* NEVER triggers compile.
- *   - Compile NEVER writes wiki/ directly (promotion only).
- *   - wiki/ is a read-only query surface; compile writes to processed/ only.
- *   - Sync boundary: processed/ is engine-internal and is NEVER synced to the
- *     Obsidian vault. Only wiki/ crosses the Obsidian sync boundary.
- */
-import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
-import path from "node:path";
-import { applyAffectedBacklinks, loadLedger, saveLedger, transitionClean, transitionOrphan, transitionStub, } from "./ledger.js";
-import { appendLog, regenerateIndex } from "./navigation.js";
-// ---------------------------------------------------------------------------
-// 1. Namespace / identity
-// ---------------------------------------------------------------------------
-/**
- * Map a concept ID (vault-relative path) to an absolute file path in wiki/.
- * Uses only the basename so nested concept IDs are flattened to wiki/ root.
- */
-export function conceptToWikiPath(wikiDir, conceptId) {
-    return path.join(wikiDir, path.basename(conceptId));
-}
-/**
- * Map a concept ID to its processed/ output path.
- */
-export function conceptToProcessedPath(processedDir, conceptId) {
-    return path.join(processedDir, path.basename(conceptId));
-}
-// ---------------------------------------------------------------------------
-// 2. Link-graph closure
-// ---------------------------------------------------------------------------
-/**
- * Extract all [[wikilink]] targets from a Markdown body.
- * Exported for use by lint.ts.
- */
-export function extractWikilinks(body) {
-    const pattern = /\[\[([^\]]+)\]\]/g;
-    const links = [];
-    let match;
-    while ((match = pattern.exec(body)) !== null) {
-        const target = match[1];
-        if (target !== undefined)
-            links.push(target);
-    }
-    return links;
-}
-/**
- * Check link-graph closure: every [[wikilink]] in `body` must resolve to a
- * page currently present in wiki/.
- *
- * @param wikiDir - Absolute path to the wiki/ directory.
- * @param body    - Markdown body to check.
- */
-export async function checkLinkClosure(wikiDir, body) {
-    const links = extractWikilinks(body);
-    if (links.length === 0)
-        return { dangling: [], closed: true };
-    let files = [];
-    try {
-        files = await readdir(wikiDir);
-    }
-    catch {
-        // wiki/ doesn't exist yet — every link is dangling
-    }
-    const pageNames = new Set(files
-        .filter((f) => f.endsWith(".md"))
-        .map((f) => path.basename(f, ".md")));
-    const dangling = links.filter((link) => {
-        const name = link.replace(/\.md$/, "");
-        return !pageNames.has(name);
-    });
-    return { dangling, closed: dangling.length === 0 };
-}
-// ---------------------------------------------------------------------------
-// 5. Processed → wiki promotion (the ONLY path into wiki/)
-// ---------------------------------------------------------------------------
-/**
- * Promote a compiled page from processed/ to wiki/.
- *
- * Called ONLY after the cascade pass completes.
- * Compile NEVER calls this directly — promotion is the sole entry point into wiki/.
- *
- * @param processedDir - Absolute path to the processed/ tier (Phase-B output).
- * @param wikiDir      - Absolute path to the wiki/ directory.
- * @param conceptId    - Vault-relative concept ID (basename used as filename).
- */
-export async function promoteToWiki(processedDir, wikiDir, conceptId) {
-    await mkdir(wikiDir, { recursive: true });
-    const src = conceptToProcessedPath(processedDir, conceptId);
-    const dst = conceptToWikiPath(wikiDir, conceptId);
-    await copyFile(src, dst);
-}
-/**
- * Run a full collection cycle after a successful M2 compile.
- *
- * Order (enforced to satisfy nvk 3-phase separation):
- *   1. Promote processed/→wiki/ for the compiled concept.
- *   2. Mark compiled concept CLEAN in the ledger.
- *   3. Apply cascade: flip CLEAN backlinks to DIRTY.
- *   4. Detect stubs: wikilinks in the promoted page with no wiki/ target.
- *   5. Detect orphans: wiki/ pages with no incoming wikilinks.
- *   6. Regenerate navigation surfaces (index.md + log.md).
- *   7. Persist ledger.
- *
- * A wiki *query* NEVER calls this function (nvk hard separation enforced here).
- */
-export async function runCollection(opts) {
-    const { processedDir, wikiDir, dotLlmwiki, conceptId, conceptName, affectedBacklinks, now, } = opts;
-    // Step 1: promote processed/→wiki/ (the ONLY path into wiki/)
-    await promoteToWiki(processedDir, wikiDir, conceptId);
-    // Load ledger
-    let ledger = await loadLedger(dotLlmwiki);
-    // Step 2: mark compiled concept CLEAN
-    ledger = transitionClean(ledger, conceptId, now);
-    // Step 3: cascade — flip CLEAN backlinks to DIRTY
-    const { ledger: ledgerAfterCascade, flipped } = applyAffectedBacklinks(ledger, affectedBacklinks, now);
-    ledger = ledgerAfterCascade;
-    // Step 4: detect stubs — read promoted page, check all [[wikilinks]]
-    const promotedPath = conceptToWikiPath(wikiDir, conceptId);
-    let promotedBody = "";
-    try {
-        promotedBody = await readFile(promotedPath, "utf8");
-    }
-    catch {
-        // promoted file unreadable — skip stub detection
-    }
-    const linkClosure = await checkLinkClosure(wikiDir, promotedBody);
-    for (const dangling of linkClosure.dangling) {
-        // Use a stable concept ID for stub entries
-        const stubId = dangling.endsWith(".md") ? dangling : `${dangling}.md`;
-        const current = ledger[stubId];
-        if (current === undefined || current.state === "STUB") {
-            ledger = transitionStub(ledger, stubId, now);
-        }
-    }
-    // Step 5: detect orphans — wiki/ pages with no incoming wikilinks
-    let wikiFiles = [];
-    try {
-        wikiFiles = (await readdir(wikiDir)).filter((f) => f.endsWith(".md") && f !== "index.md" && f !== "log.md");
-    }
-    catch {
-        // ok if dir is empty
-    }
-    // Build set of all link targets found across all wiki pages
-    const allLinkTargets = new Set();
-    for (const file of wikiFiles) {
-        try {
-            const content = await readFile(path.join(wikiDir, file), "utf8");
-            for (const link of extractWikilinks(content)) {
-                allLinkTargets.add(link.replace(/\.md$/, ""));
-            }
-        }
-        catch {
-            // ignore unreadable files
-        }
-    }
-    for (const file of wikiFiles) {
-        const baseName = path.basename(file, ".md");
-        if (!allLinkTargets.has(baseName)) {
-            const fileConceptId = file; // use bare filename as ledger key for orphan entries
-            ledger = transitionOrphan(ledger, fileConceptId, now);
-        }
-    }
-    // Step 6: regenerate navigation (index.md + log.md — always written before returning)
-    const cleanIds = Object.keys(ledger)
-        .filter((id) => ledger[id]?.state === "CLEAN")
-        .sort();
-    await regenerateIndex(wikiDir, cleanIds, now);
-    await appendLog(wikiDir, conceptName, now);
-    // Step 7: persist ledger
-    await saveLedger(dotLlmwiki, ledger);
-    return {
-        cascadeFlipped: { flipped },
-        linkClosure,
-        ledger,
-    };
-}
-//# sourceMappingURL=collection.js.map

package/dist/engine/wiki/collection.js.map

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

package/dist/engine/wiki/ledger.d.ts

@@ -1,59 +0,0 @@
-/**
- * Staleness ledger — 5-state FSM for wiki pages.
- *
- * Persists to .llmwiki/staleness.json (human-readable, never synced dotfolder).
- * All state is plain disk JSON written only on explicit calls (R2: stateless/manual).
- * No daemon, no watcher, no setInterval.
- *
- * Pass the dotLlmwiki dir in — no hardcoded vault path.
- *
- * Full-rebuild escape hatch: delete .llmwiki/staleness.json → every known page
- * resets to DIRTY on the next loadLedger call.
- */
-import type { NowFn, StalenessLedger } from "./types.js";
-/**
- * Load the staleness ledger from disk.
- * Returns an empty ledger if the file is absent or unreadable.
- */
-export declare function loadLedger(dotLlmwiki: string): Promise<StalenessLedger>;
-/**
- * Persist the staleness ledger to disk.
- * Creates the dotLlmwiki directory if it does not exist.
- */
-export declare function saveLedger(dotLlmwiki: string, ledger: StalenessLedger): Promise<void>;
-/** Mark a concept DIRTY (source SHA changed or cascade flip). */
-export declare function transitionDirty(ledger: StalenessLedger, conceptId: string, now: NowFn): StalenessLedger;
-/** Mark a concept CLEAN (compile output produced successfully). */
-export declare function transitionClean(ledger: StalenessLedger, conceptId: string, now: NowFn): StalenessLedger;
-/** Mark a concept STUB (referenced by wikilinks but no compile output exists). */
-export declare function transitionStub(ledger: StalenessLedger, conceptId: string, now: NowFn): StalenessLedger;
-/** Mark a concept ORPHAN (no incoming wikilinks from any other wiki page). */
-export declare function transitionOrphan(ledger: StalenessLedger, conceptId: string, now: NowFn): StalenessLedger;
-/**
- * Mark a concept CONFLICT (two compile sources produced conflicting content).
- *
- * @param conflictNote - Human-readable description of the conflict.
- *   Format: "A claims X; B claims Y" — surfaced in lint as:
- *   "> **Conflict:** A claims X; B claims Y. Unresolved."
- */
-export declare function transitionConflict(ledger: StalenessLedger, conceptId: string, now: NowFn, conflictNote: string): StalenessLedger;
-/**
- * Full-rebuild escape hatch: delete staleness.json and return all known concept IDs
- * re-marked as DIRTY.
- *
- * If the file doesn't exist, is a no-op (returns empty ledger).
- * The caller must call saveLedger() to persist the reset state.
- */
-export declare function resetLedger(dotLlmwiki: string, now: NowFn): Promise<StalenessLedger>;
-/**
- * Consume affected_backlinks from an M2 compile cascade return.
- *
- * For each affected page: if the current state is CLEAN, flip to DIRTY and
- * queue for the next compile run. Other states are left unchanged.
- *
- * Returns the updated ledger and the list of concept IDs that were flipped.
- */
-export declare function applyAffectedBacklinks(ledger: StalenessLedger, affectedBacklinks: readonly string[], now: NowFn): {
-    ledger: StalenessLedger;
-    flipped: string[];
-};

package/dist/engine/wiki/ledger.js

@@ -1,130 +0,0 @@
-/**
- * Staleness ledger — 5-state FSM for wiki pages.
- *
- * Persists to .llmwiki/staleness.json (human-readable, never synced dotfolder).
- * All state is plain disk JSON written only on explicit calls (R2: stateless/manual).
- * No daemon, no watcher, no setInterval.
- *
- * Pass the dotLlmwiki dir in — no hardcoded vault path.
- *
- * Full-rebuild escape hatch: delete .llmwiki/staleness.json → every known page
- * resets to DIRTY on the next loadLedger call.
- */
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import path from "node:path";
-// ---------------------------------------------------------------------------
-// File path
-// ---------------------------------------------------------------------------
-function ledgerFilePath(dotLlmwiki) {
-    return path.join(dotLlmwiki, "staleness.json");
-}
-// ---------------------------------------------------------------------------
-// Persistence
-// ---------------------------------------------------------------------------
-/**
- * Load the staleness ledger from disk.
- * Returns an empty ledger if the file is absent or unreadable.
- */
-export async function loadLedger(dotLlmwiki) {
-    try {
-        const raw = await readFile(ledgerFilePath(dotLlmwiki), "utf8");
-        const parsed = JSON.parse(raw);
-        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
-        return {};
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Persist the staleness ledger to disk.
- * Creates the dotLlmwiki directory if it does not exist.
- */
-export async function saveLedger(dotLlmwiki, ledger) {
-    await mkdir(dotLlmwiki, { recursive: true });
-    await writeFile(ledgerFilePath(dotLlmwiki), JSON.stringify(ledger, null, 2), "utf8");
-}
-// ---------------------------------------------------------------------------
-// Internal helper
-// ---------------------------------------------------------------------------
-function makeEntry(state, now, extra) {
-    return { state, updatedAt: now(), ...extra };
-}
-// ---------------------------------------------------------------------------
-// State transitions — pure functions returning a new ledger
-// ---------------------------------------------------------------------------
-/** Mark a concept DIRTY (source SHA changed or cascade flip). */
-export function transitionDirty(ledger, conceptId, now) {
-    return { ...ledger, [conceptId]: makeEntry("DIRTY", now) };
-}
-/** Mark a concept CLEAN (compile output produced successfully). */
-export function transitionClean(ledger, conceptId, now) {
-    return { ...ledger, [conceptId]: makeEntry("CLEAN", now) };
-}
-/** Mark a concept STUB (referenced by wikilinks but no compile output exists). */
-export function transitionStub(ledger, conceptId, now) {
-    return { ...ledger, [conceptId]: makeEntry("STUB", now) };
-}
-/** Mark a concept ORPHAN (no incoming wikilinks from any other wiki page). */
-export function transitionOrphan(ledger, conceptId, now) {
-    return { ...ledger, [conceptId]: makeEntry("ORPHAN", now) };
-}
-/**
- * Mark a concept CONFLICT (two compile sources produced conflicting content).
- *
- * @param conflictNote - Human-readable description of the conflict.
- *   Format: "A claims X; B claims Y" — surfaced in lint as:
- *   "> **Conflict:** A claims X; B claims Y. Unresolved."
- */
-export function transitionConflict(ledger, conceptId, now, conflictNote) {
-    return { ...ledger, [conceptId]: makeEntry("CONFLICT", now, { conflictNote }) };
-}
-// ---------------------------------------------------------------------------
-// Escape hatch: reset by deleting staleness.json
-// ---------------------------------------------------------------------------
-/**
- * Full-rebuild escape hatch: delete staleness.json and return all known concept IDs
- * re-marked as DIRTY.
- *
- * If the file doesn't exist, is a no-op (returns empty ledger).
- * The caller must call saveLedger() to persist the reset state.
- */
-export async function resetLedger(dotLlmwiki, now) {
-    const current = await loadLedger(dotLlmwiki);
-    try {
-        await unlink(ledgerFilePath(dotLlmwiki));
-    }
-    catch {
-        // File doesn't exist — that's fine
-    }
-    const reset = {};
-    for (const conceptId of Object.keys(current)) {
-        reset[conceptId] = makeEntry("DIRTY", now);
-    }
-    return reset;
-}
-// ---------------------------------------------------------------------------
-// Cascade integration
-// ---------------------------------------------------------------------------
-/**
- * Consume affected_backlinks from an M2 compile cascade return.
- *
- * For each affected page: if the current state is CLEAN, flip to DIRTY and
- * queue for the next compile run. Other states are left unchanged.
- *
- * Returns the updated ledger and the list of concept IDs that were flipped.
- */
-export function applyAffectedBacklinks(ledger, affectedBacklinks, now) {
-    let updated = { ...ledger };
-    const flipped = [];
-    for (const conceptId of affectedBacklinks) {
-        if (updated[conceptId]?.state === "CLEAN") {
-            updated = transitionDirty(updated, conceptId, now);
-            flipped.push(conceptId);
-        }
-    }
-    return { ledger: updated, flipped };
-}
-//# sourceMappingURL=ledger.js.map

package/dist/engine/wiki/ledger.js.map

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

package/dist/engine/wiki/lint.d.ts

@@ -1,38 +0,0 @@
-/**
- * Astro-Han 2-tier lint (MIT — idea absorption only).
- *
- * Auto-fix tier (runs automatically, mutates wiki/ files):
- *   - index consistency: concept present in wiki/ but absent from index.md
- *   - internal-link correctness: broken [[wikilinks]] flagged
- *   - See-Also sections: added if missing
- *
- * Report-only tier (reports to return value; NO autofix without forceHumanGate):
- *   - factual contradictions typed as:
- *     "> **Conflict:** A claims X; B claims Y. Unresolved."
- *   - orphan pages (in ledger as ORPHAN state)
- *   - outdated refs (DIRTY pages in the ledger)
- *
- * Mutation policy: report-only findings are NEVER auto-fixed unless the caller
- * explicitly sets forceHumanGate: true. This is the human-gate flag.
- */
-import type { LintResult, StalenessLedger } from "./types.js";
-export interface LintOptions {
-    /** Absolute path to the wiki/ directory. */
-    wikiDir: string;
-    /** Current staleness ledger (used for report-only checks). */
-    ledger: StalenessLedger;
-    /**
-     * Human-gate flag — not set automatically.
-     * When true, allows autofix of report-only findings (not currently implemented;
-     * present as explicit hook for future human-approved bulk operations).
-     */
-    forceHumanGate?: boolean;
-}
-/**
- * Run all lint checks.
- *
- * Auto-fix tier mutates wiki/ files automatically.
- * Report-only tier returns findings but does NOT mutate anything unless
- * forceHumanGate is true (currently reserved — no report-only autofix implemented).
- */
-export declare function runLint(opts: LintOptions): Promise<LintResult>;