hafez 1.2.0 → 1.3.0

package/dist/{sections.js → document.js}

@@ -1,19 +1,23 @@
-// src/sections.ts
-// Pure string→string functions for Brief and Next Actions section manipulation.
-import { ALL_CONTRACTS, SUBTYPE_SECTIONS } from './contracts.js';
+// src/document.ts
+// The Document module (see CONTEXT.md): owns the body of a vault file —
+// structural sections, session-log entries, wiki-links. Absorbs the former
+// sections.ts and parser.ts; every body read or mutation goes through the
+// single structural-heading model defined here. Pure string→string.
+import { ALL_CONTRACTS, SUBTYPE_SECTIONS, SESSION_SECTIONS } from './contracts.js';
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
 /**
- * Known structural section headings in Hafez entities and knowledge notes.
- * Derived from contracts.ts (defaultSections + optionalSections) plus
- * auto-generated sections not tracked in contracts (Related, Summary).
- * Only these are treated as section boundaries. Any other `## ` heading
- * inside section content (e.g. in a brief or session log) is preserved as-is.
+ * Known structural section headings in Hafez entities, knowledge notes, and
+ * session files. Derived from contracts.ts (defaultSections + optionalSections
+ * + session sections) plus auto-generated sections not tracked in contracts
+ * (Related). Only these are treated as section boundaries. Any other `## `
+ * heading inside section content (e.g. in a brief or session log) is
+ * preserved as-is.
  */
 export const STRUCTURAL_SECTIONS = new Set([
     ...ALL_CONTRACTS.flatMap(c => [...c.defaultSections, ...c.optionalSections]),
     ...Object.values(SUBTYPE_SECTIONS).flat(),
+    ...SESSION_SECTIONS,
     'Related', // auto-generated by syncRelatedSection
-    'Summary', // used in session files
 ]);
 /**
  * Find the next structural `## Heading` boundary after a given position.
@@ -32,31 +36,176 @@ export function findNextStructuralHeading(body, from) {
     }
     return -1;
 }
-// --- Internal helpers ---
 /**
  * Find a ## Heading section and its content.
- * Returns { start, end, content } or null if not found.
+ * Returns { start, headingEnd, end, content } or null if not found.
  * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
+ * Trailing whitespace on the heading line is tolerated — the splitter's
+ * boundary tokenizer trims headings, so anything it treats as a boundary
+ * must also be findable here (a hand-edited `## Session Log ` otherwise
+ * gets a duplicate section and archival never fires).
  * Only treats known structural headings as section boundaries -- content
  * inside a section may contain arbitrary `## ` headings without corruption.
  */
 export function findSection(body, heading) {
-    const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)})(?:\\n|$)`);
+    const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)}[ \\t]*)(?:\\n|$)`);
     const match = re.exec(body);
     if (!match)
         return null;
     const start = match.index + match[1].length;
-    const afterHeading = start + match[2].length + 1;
-    // Find the next structural ## heading or EOF
-    const nextHeading = findNextStructuralHeading(body, afterHeading);
+    const headingEnd = start + match[2].length;
+    const afterHeading = headingEnd + 1;
+    // Find the next structural ## heading or EOF. Scan from the heading's own
+    // trailing newline (afterHeading - 1), not past it — otherwise a structural
+    // heading on the immediately following line (no blank line between, as in
+    // hand-edited files) is invisible and mutators swallow the next section.
+    const nextHeading = findNextStructuralHeading(body, Math.max(0, afterHeading - 1));
     const end = nextHeading === -1 ? body.length : nextHeading;
     const rawContent = body.slice(afterHeading, end);
     const content = rawContent.replace(/^\n+/, '').replace(/\n+$/, '');
-    return { start, end, content };
+    return { start, headingEnd, end, content };
 }
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/**
+ * Split a body into preamble + structural sections. Non-structural `## `
+ * headings stay inside the enclosing section's content — sections are
+ * atomic units of authored content, never split at user headings.
+ * Headings and content come back trimmed; reassemble with
+ * `## ${heading}\n\n${content}` joined by blank lines.
+ */
+export function splitStructural(body) {
+    const marks = [];
+    const re = /(^|\n)## ([^\n]*)/g;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const heading = m[2].trim();
+        if (!STRUCTURAL_SECTIONS.has(heading))
+            continue;
+        marks.push({ start: m.index + m[1].length, contentStart: m.index + m[0].length, heading });
+    }
+    if (marks.length === 0)
+        return { preamble: body.trim(), sections: [] };
+    const preamble = body.slice(0, marks[0].start).trim();
+    const sections = marks.map((mk, i) => ({
+        heading: mk.heading,
+        content: body.slice(mk.contentStart, i + 1 < marks.length ? marks[i + 1].start : body.length).trim(),
+    }));
+    return { preamble, sections };
+}
+// --- Generic section mutation ---
+/**
+ * Replace a structural section's content, or create the section: before
+ * `insertBefore` when that section exists, at EOF otherwise.
+ */
+export function setSection(body, heading, content, insertBefore) {
+    const existing = findSection(body, heading);
+    if (existing) {
+        return body.slice(0, existing.start) + `## ${heading}\n\n${content}\n` + body.slice(existing.end);
+    }
+    if (insertBefore) {
+        const target = findSection(body, insertBefore);
+        if (target) {
+            return body.slice(0, target.start) + `## ${heading}\n\n${content}\n\n` + body.slice(target.start);
+        }
+    }
+    return body + `\n\n## ${heading}\n\n${content}\n`;
+}
+/** Append content at the end of a structural section (creating it at EOF if absent). */
+export function appendToSection(body, heading, content) {
+    const section = findSection(body, heading);
+    if (!section)
+        return body + `\n\n## ${heading}\n\n${content}\n`;
+    if (section.end === body.length)
+        return body + '\n' + content + '\n';
+    return body.slice(0, section.end) + '\n' + content + body.slice(section.end);
+}
+/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
+export function prependSessionLogEntry(body, entry) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return body + `\n\n## Session Log\n\n${entry}\n`;
+    const insertPos = section.headingEnd;
+    return body.slice(0, insertPos) + '\n\n' + entry + '\n' + body.slice(insertPos);
+}
+/** Body up to the real Session Log section — the `summary` read depth. */
+export function bodyBeforeSessionLog(body) {
+    const section = findSection(body, 'Session Log');
+    return section ? body.slice(0, section.start).trim() : body;
+}
+// --- Session log parsing ---
+const HEADING_RE = /^### (\d{4}-\d{2}-\d{2}) (?:—|--) (.+?)(?:\s+\[(\w+)\])?$/;
+export function parseSessionLogHeading(line) {
+    const match = line.match(HEADING_RE);
+    if (!match)
+        return null;
+    return {
+        date: match[1],
+        agent: match[2],
+        type: match[3] || 'progress'
+    };
+}
+export function formatSessionLogEntry(entry) {
+    const today = new Date().toISOString().slice(0, 10);
+    const lines = [`### ${today} — ${entry.agent} [${entry.type}]`, `Summary: ${entry.summary}`];
+    if (entry.body)
+        lines.push(entry.body);
+    return lines.join('\n');
+}
+/** Entries inside the real Session Log section only — entry-shaped lines
+ * elsewhere in the body (e.g. quoted in a Brief) do not count. */
+export function countSessionLogEntries(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return 0;
+    return (section.content.match(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm) || []).length;
+}
+export function parseSessionLog(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return [];
+    const entries = [];
+    const lines = section.content.split('\n');
+    let current = null;
+    let summaryLine = null;
+    for (const line of lines) {
+        const heading = parseSessionLogHeading(line);
+        if (heading) {
+            if (current && summaryLine) {
+                entries.push({ ...current, summary: summaryLine });
+            }
+            current = heading;
+            summaryLine = null;
+        }
+        else if (current && !summaryLine && line.startsWith('Summary: ')) {
+            summaryLine = line.slice('Summary: '.length);
+        }
+    }
+    if (current && summaryLine) {
+        entries.push({ ...current, summary: summaryLine });
+    }
+    return entries;
+}
+export function extractOldestSessionLogEntry(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return null;
+    // Work on the raw slice between the heading and the section's structural
+    // end, so the extracted entry can never swallow a following section
+    // (e.g. an auto-appended Related) into the archive.
+    const contentStart = section.headingEnd;
+    const region = body.slice(contentStart, section.end);
+    const entryStarts = [...region.matchAll(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm)];
+    if (entryStarts.length < 2)
+        return null;
+    // Entries are newest-first in the file, so the oldest is the last match
+    const oldestStart = entryStarts[entryStarts.length - 1].index;
+    const entry = region.slice(oldestStart).trim();
+    const remaining = body.slice(0, contentStart) + region.slice(0, oldestStart) + body.slice(section.end);
+    return { entry, remaining };
+}
+// --- Section removal / insertion helpers (Brief, Next Actions) ---
 /**
  * Remove a section (heading + content) from body, cleaning up extra whitespace.
  */
@@ -121,9 +270,9 @@ function insertSectionAfter(body, heading, content, after, beforeFallbacks) {
 function normalizeForMatch(s) {
     return s
         .trim()
-        .replace(/[\u2018\u2019]/g, "'")
-        .replace(/[\u201C\u201D]/g, '"')
-        .replace(/\u2014/g, '-');
+        .replace(/[‘’]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/—/g, '-');
 }
 /**
  * Match an action by case-insensitive substring against unchecked items.
@@ -251,9 +400,11 @@ export function deriveSummary(kind, fm, body) {
     }
     return firstNonEmptyLine(findSection(body, 'Summary')?.content);
 }
-// --- Related section functions ---
-/** Matches [[slug]] or [[slug|display text]], capturing slug in group 1. Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
-export const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/;
+// --- Wiki-links ---
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
+export const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/;
 export function syncRelatedSection(body, frontmatter) {
     const targets = [];
     if (frontmatter.parent)

package/dist/export-okf.js

@@ -7,24 +7,12 @@
 // regenerated indexes) until the bundle directory is deleted and re-exported.
 import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve, sep, basename } from 'path';
-import { parseFilePath, serializeFile } from './vault.js';
-import { deriveSummary } from './sections.js';
-const KIND_DIRS = [
-    { dir: 'entities', kind: 'entity' },
-    { dir: 'knowledge', kind: 'knowledge' },
-    { dir: 'sessions', kind: 'session' },
-];
-// Local capturing variant of the shared WIKI_LINK_RE — captures display text in
-// group 2, which the shared regex's consumers don't need.
-const OKF_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
-function scanDir(dirPath) {
-    try {
-        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
-    }
-    catch {
-        return [];
-    }
-}
+import { parseFilePath, serializeFile, scanVaultDir, kindDir } from './vault.js';
+import { deriveSummary, WIKI_LINK_RE } from './document.js';
+const SOURCE_KINDS = ['entity', 'knowledge', 'session'];
+const KIND_DIRS = SOURCE_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
+// The shared wiki-link syntax (document.ts) — group 1 slug, group 2 display.
+const OKF_LINK_RE = new RegExp(WIKI_LINK_RE.source, 'g');
 function mapFrontmatter(doc) {
     const { fm, kind, body } = doc;
     const mapped = {};
@@ -88,7 +76,7 @@ export function exportOkf(vaultPath, outDir) {
     // Enumerate and parse. Sessions are not in SQLite — disk enumeration is required.
     const docs = [];
     for (const { dir, kind } of KIND_DIRS) {
-        for (const filePath of scanDir(join(resolvedVault, dir))) {
+        for (const filePath of scanVaultDir(join(resolvedVault, dir))) {
             const slug = basename(filePath, '.md');
             const relFile = `${dir}/${slug}.md`;
             let fm, body;
@@ -160,9 +148,9 @@ export function exportOkf(vaultPath, outDir) {
     }
     // Root index.md — the only place okf_version may appear
     const counts = [
-        ['entities', report.entities],
-        ['knowledge', report.knowledge],
-        ['sessions', report.sessions],
+        [kindDir('entity'), report.entities],
+        [kindDir('knowledge'), report.knowledge],
+        [kindDir('session'), report.sessions],
     ];
     const rootLines = ['# Vault Export', ''];
     for (const [dir, count] of counts) {

package/dist/git.d.ts

@@ -1,4 +1,4 @@
-import { type GitConfig, type ChangelogEntry } from './types.js';
+import { type GitConfig, type ChangelogEntry, type Journal } from './types.js';
 /**
  * Bidirectional sync: pull remote changes, push local commits.
  * All work must be committed before calling — no file save/restore needed.
@@ -8,13 +8,6 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
-/**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
- */
-export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
 export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
 /**
  * Latest git time per file (repo-relative, forward-slash paths). Used to
@@ -24,3 +17,9 @@ export declare function gitChangelog(vaultPath: string, since: string): Promise<
  */
 export declare function gitFileTimes(vaultPath: string, mode: 'modified' | 'added'): Promise<Map<string, string>>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export declare function createGitJournal(vaultPath: string, config?: GitConfig): Journal;

package/dist/git.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { simpleGit } from 'simple-git';
 import { mergeVaultContent } from './merge.js';
+import { VAULT_FILE_RE, INDEXED_DIR_PATHSPECS, classifyIndexedRelPath } from './vault.js';
 import { HafezError } from './types.js';
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
@@ -40,7 +41,6 @@ async function ensureCleanState(git, vaultPath) {
         }
     }
 }
-const VAULT_FILE_RE = /^(?:entities|knowledge|sessions)\/.+\.md$/;
 /**
  * True if the vault repo has an `origin` remote. A local-only vault (the
  * default the README setup produces) has none — every pull/push must be
@@ -253,12 +253,13 @@ export async function gitSync(vaultPath) {
     return { pulled, pushed: true, remote: true };
 }
 /**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ * Unstage files (best effort). Used by the journal adapter's commit-failure
+ * repair: a commit that fails after `git add` leaves the new blobs staged in
+ * .git/index, and the next successful commit would publish rolled-back
+ * content under the wrong message. Clearing the index entries restores
+ * worktree/HEAD/index agreement.
  */
-export async function gitUnstage(vaultPath, files) {
+async function gitUnstage(vaultPath, files) {
     try {
         await simpleGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
     }
@@ -290,7 +291,7 @@ export async function gitChangelog(vaultPath, since) {
     try {
         output = await git.raw([
             'log', `--since=${normalizedSince}`, '--name-status',
-            '--pretty=format:%H|%aI|%s', '--', 'entities/', 'knowledge/',
+            '--pretty=format:%H|%aI|%s', '--', ...INDEXED_DIR_PATHSPECS,
         ]);
     }
     catch {
@@ -320,20 +321,10 @@ export async function gitChangelog(vaultPath, since) {
             // dirs and would otherwise surface as changelog rows.
             if (!filePath.endsWith('.md'))
                 continue;
-            let kind;
-            let slug;
-            if (filePath.startsWith('entities/')) {
-                kind = 'entity';
-                slug = filePath.replace('entities/', '').replace('.md', '');
-            }
-            else if (filePath.startsWith('knowledge/')) {
-                kind = 'knowledge';
-                slug = filePath.replace('knowledge/', '').replace('.md', '');
-            }
-            else {
+            const classified = classifyIndexedRelPath(filePath);
+            if (!classified)
                 continue;
-            }
-            entries.push({ slug, kind, operation, timestamp, commit_message });
+            entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
         }
     }
     return entries;
@@ -348,7 +339,7 @@ export async function gitFileTimes(vaultPath, mode) {
     const git = simpleGit(vaultPath);
     let output;
     try {
-        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', 'entities/', 'knowledge/'];
+        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', ...INDEXED_DIR_PATHSPECS];
         if (mode === 'added')
             args.splice(1, 0, '--diff-filter=A');
         output = await git.raw(args);
@@ -405,3 +396,30 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
         return;
     await pushResolving(git, vaultPath, (conflictFiles) => `Git conflict with remote (files: ${conflictFiles.join(', ')}). Changes saved locally.`, `Git push failed after ${MAX_PUSH_RETRIES} attempts. Changes saved locally.`);
 }
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export function createGitJournal(vaultPath, config = {}) {
+    return {
+        async commit(written, deleted, message) {
+            const files = [...written, ...deleted];
+            try {
+                await gitCommitAndPush(vaultPath, files, message, config);
+            }
+            catch (err) {
+                // Commit-stage failure: nothing landed, but `git add` may have staged
+                // the new blobs — clean up our own partial state before rethrowing.
+                // Push-stage failure keeps the local commit (GIT_PUSH_FAILED).
+                if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
+                    await gitUnstage(vaultPath, files);
+                }
+                throw err;
+            }
+        },
+        sync: () => gitSync(vaultPath),
+        changelog: (since) => gitChangelog(vaultPath, since),
+        fileTimes: (mode) => gitFileTimes(vaultPath, mode),
+    };
+}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import type { Hafez, HafezConfig } from './types.js';
 export declare function createHafez(config: HafezConfig): Hafez;
 export { HafezError } from './types.js';
-export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
-export { getBrief, getNextActions, findSection } from './sections.js';
-export { parseSessionLogHeading, parseSessionLog } from './parser.js';
-export { formatStats, formatChangelog, formatValidation } from './cli/format.js';
+export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, Journal, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
+export { getBrief, getNextActions, findSection } from './document.js';
+export { parseSessionLogHeading, parseSessionLog } from './document.js';