hafez 1.2.0 → 1.3.0

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { createHafez } from '../index.js';
 import { HafezError } from '../types.js';
+import { parseArgs, UsageError } from './args.js';
 import { cmdRead, cmdQuery, cmdSearch, cmdCreate, cmdUpdate, cmdLink, cmdUnlink, cmdPromote, cmdValidate, cmdIndexRebuild, cmdBatch, cmdSync, cmdStats, cmdChangelog, cmdDigest, cmdCapture } from './commands.js';
 import { cmdSchema } from './commands-schema.js';
 import { renderAgentHelp } from './help-agent.js';
@@ -11,6 +12,7 @@ import { renderOnboard } from './onboard.js';
 import { resolveVaultPath, noVaultMessage, cmdInit } from './resolve-vault.js';
 const COMMANDS = {
     read: cmdRead,
+    sync: cmdSync,
     query: cmdQuery,
     search: cmdSearch,
     create: cmdCreate,
@@ -25,7 +27,7 @@ const COMMANDS = {
     index: (os, args) => {
         if (args[0] === 'rebuild')
             return cmdIndexRebuild(os);
-        throw new Error('Usage: hafez index rebuild');
+        throw new UsageError('Usage: hafez index rebuild');
     },
     stats: cmdStats,
     changelog: cmdChangelog,
@@ -76,6 +78,33 @@ Global flags:
 
 Vault discovery: --vault flag > ~/.config/hafez/vault
 `;
+/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+const EXIT_CODES = {
+    NOT_FOUND: 1,
+    VALIDATION_FAILED: 2,
+    GIT_PUSH_FAILED: 3,
+    SLUG_EXISTS: 5,
+    GIT_COMMIT_FAILED: 6,
+    VAULT_LOCKED: 7,
+};
+/** The one error → exit adapter. Usage errors (bad flags/args) are distinct
+ * from vault errors and from unknown crashes. */
+function report(err) {
+    if (err instanceof UsageError) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(2);
+    }
+    if (err instanceof HafezError) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        if (err.details?.length) {
+            for (const detail of err.details)
+                process.stderr.write(`  - ${detail}\n`);
+        }
+        process.exit(EXIT_CODES[err.code] ?? 1);
+    }
+    failUnknown(err);
+}
 // Terminal handler for non-Hafez errors. Special-cases unbuilt better-sqlite3
 // bindings: npm 11+ blocks install scripts by default, so `npm install -g
 // hafez` reports success with the native module unbuilt and the first indexed
@@ -137,15 +166,7 @@ export async function main(argv) {
             process.stdout.write(result + '\n');
         }
         catch (err) {
-            if (err instanceof HafezError) {
-                process.stderr.write(`Error: ${err.message}\n`);
-                if (err.details?.length) {
-                    for (const detail of err.details)
-                        process.stderr.write(`  - ${detail}\n`);
-                }
-                process.exit(2);
-            }
-            failUnknown(err);
+            report(err);
         }
         return;
     }
@@ -167,59 +188,28 @@ export async function main(argv) {
     const vaultPath = resolution;
     // export runs before Hafez instance creation — read-only, no auto-sync
     if (command === 'export') {
-        if (!args.includes('--okf')) {
-            process.stderr.write('Usage: hafez export --okf [--out <dir>]\n');
-            process.exit(1);
-        }
-        const outIdx = args.indexOf('--out');
-        let outDir = resolve(process.cwd(), 'okf-export');
-        if (outIdx !== -1) {
-            const outValue = args[outIdx + 1];
-            if (!outValue) {
-                process.stderr.write('Usage: hafez export --okf [--out <dir>]\n');
-                process.exit(1);
-            }
-            outDir = resolve(outValue);
-        }
-        const { exportOkf } = await import('../export-okf.js');
         try {
-            const report = exportOkf(vaultPath, outDir);
+            const EXPORT_USAGE = 'Usage: hafez export --okf [--out <dir>]';
+            const { flags } = parseArgs(args, { okf: 'boolean', out: 'string' }, EXPORT_USAGE);
+            if (flags.okf !== true)
+                throw new UsageError(EXPORT_USAGE);
+            const outDir = typeof flags.out === 'string' ? resolve(flags.out) : resolve(process.cwd(), 'okf-export');
+            const { exportOkf } = await import('../export-okf.js');
+            const exportReport = exportOkf(vaultPath, outDir);
             if (json) {
-                process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+                process.stdout.write(JSON.stringify(exportReport, null, 2) + '\n');
             }
             else {
-                const lines = [`Exported ${report.entities} entities, ${report.knowledge} knowledge, ${report.sessions} sessions to ${report.outDir}`];
-                for (const s of report.skipped)
+                const lines = [`Exported ${exportReport.entities} entities, ${exportReport.knowledge} knowledge, ${exportReport.sessions} sessions to ${exportReport.outDir}`];
+                for (const s of exportReport.skipped)
                     lines.push(`  skipped ${s.file}: ${s.reason}`);
-                if (report.unresolvedLinks > 0)
-                    lines.push(`  unresolved links: ${report.unresolvedLinks}`);
+                if (exportReport.unresolvedLinks > 0)
+                    lines.push(`  unresolved links: ${exportReport.unresolvedLinks}`);
                 process.stdout.write(lines.join('\n') + '\n');
             }
         }
         catch (err) {
-            failUnknown(err);
-        }
-        return;
-    }
-    // sync is handled specially — always runs, not gated by MUTATING_COMMANDS
-    if (command === 'sync') {
-        const os = createHafez({ vaultPath, git: { push: false } });
-        try {
-            const result = await cmdSync(os, args);
-            process.stdout.write(result + '\n');
-        }
-        catch (err) {
-            if (err instanceof HafezError) {
-                process.stderr.write(`Error: ${err.message}\n`);
-                if (err.details?.length) {
-                    for (const detail of err.details) {
-                        process.stderr.write(`  - ${detail}\n`);
-                    }
-                }
-                const exitCodes = { NOT_FOUND: 1, VALIDATION_FAILED: 2, GIT_PUSH_FAILED: 3 };
-                process.exit(exitCodes[err.code] ?? 1);
-            }
-            failUnknown(err);
+            report(err);
         }
         return;
     }
@@ -246,16 +236,6 @@ export async function main(argv) {
         process.stdout.write(result + '\n');
     }
     catch (err) {
-        if (err instanceof HafezError) {
-            process.stderr.write(`Error: ${err.message}\n`);
-            if (err.details?.length) {
-                for (const detail of err.details) {
-                    process.stderr.write(`  - ${detail}\n`);
-                }
-            }
-            const exitCodes = { NOT_FOUND: 1, VALIDATION_FAILED: 2, GIT_PUSH_FAILED: 3 };
-            process.exit(exitCodes[err.code] ?? 1);
-        }
-        failUnknown(err);
+        report(err);
     }
 }

package/dist/cli/resolve-vault.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs
 import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
+import { kindDir } from '../vault.js';
 export function getConfigDir() {
     const xdg = process.env.XDG_CONFIG_HOME;
     return join(xdg || join(homedir(), '.config'), 'hafez');
@@ -28,7 +29,7 @@ export function saveVaultConfig(vaultPath) {
     writeFileSync(join(dir, 'vault'), resolve(vaultPath) + '\n');
 }
 function isVault(dirPath) {
-    return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, 'entities'));
+    return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, kindDir('entity')));
 }
 /**
  * Resolve vault path. Returns string or null.

package/dist/cli/schema-introspect.d.ts

@@ -1,4 +1,4 @@
-import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema } from './commands.js';
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema } from '../batch-ops.js';
 export interface FieldSchema {
     type: string;
     optional?: boolean;

package/dist/cli/schema-introspect.js

@@ -10,7 +10,7 @@
 // types actually used in BatchOperationSchema plus a few forward-looking ones
 // (`default`, `effects`, `union`) so the walker does not explode when the
 // schema is extended.
-import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema, } from './commands.js';
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema, OP_SPECS, } from '../batch-ops.js';
 import { DigestInputSchema } from '../digest.js';
 import { ALIAS_KEYS } from '../contracts.js';
 // --- Walker ---
@@ -155,16 +155,8 @@ export const DIGEST_EXAMPLE = {
     session_date: '2026-01-15',
     agent: 'claude',
 };
-const OP_DESCRIPTIONS = {
-    'update': 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …).',
-    'create-entity': 'Create a new entity (capture / entity / project).',
-    'create-knowledge': 'Create a new knowledge note (insight / plan subtype).',
-    'create-session': 'Create a new session note linked to an entity.',
-    'capture': 'Quick capture — a raw inbox item with no structure required.',
-    'link': 'Add a parent or related link between two entities.',
-    'unlink': 'Remove a parent or related link between two entities.',
-    'promote': 'Promote a capture to entity/project/knowledge, or an entity to project.',
-};
+// Descriptions live in the Op Spec table (src/batch-ops.ts) — one row per op.
+const OP_DESCRIPTIONS = Object.fromEntries(OP_SPECS.map(s => [s.name, s.description]));
 export function listOps() {
     return enumerateBranches().map(({ op, kind }) => {
         const name = kind ? `${op}-${kind}` : op;
@@ -293,17 +285,9 @@ function shouldStrip(path, _key) {
     return Object.prototype.hasOwnProperty.call(ALIAS_KEYS, path);
 }
 function isDefaultIncluded(op, kind, fieldKey) {
-    if (op === 'create' && kind === 'entity' && fieldKey === 'type')
-        return true;
-    if (op === 'create' && kind === 'knowledge' && (fieldKey === 'subtype' || fieldKey === 'synthesis'))
-        return true;
-    if (op === 'create' && kind === 'session' && fieldKey === 'synthesis')
-        return true;
-    if (op === 'update' && fieldKey === 'status')
-        return true;
-    if (op === 'capture' && fieldKey === 'notes')
-        return true;
-    return false;
+    // Example-inclusion hints live in the Op Spec table, one row per op.
+    const spec = OP_SPECS.find(s => s.op === op && s.kind === kind);
+    return spec ? spec.exampleInclude.includes(fieldKey) : false;
 }
 function sampleValue(field) {
     switch (field.type) {

package/dist/contracts.d.ts

@@ -24,3 +24,9 @@ export declare const ALIAS_KEYS: {
     readonly 'create.session.fields.insight': "synthesis";
 };
 export declare const SUBTYPE_SECTIONS: Record<KnowledgeSubtype, string[]>;
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export declare const APPEND_ONLY_SECTIONS: ReadonlySet<string>;
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export declare const SESSION_SECTIONS: readonly ["Summary", "Entities Touched", "Decisions"];

package/dist/contracts.js

@@ -63,8 +63,8 @@ export function hasCapability(type, section) {
     return contract.defaultSections.includes(section) || contract.optionalSections.includes(section);
 }
 // --- Canonical enum tuples (single source of truth) ---
-// Every consumer (file validators, CLI input validator, help renderer) imports these.
-// The cli-schema-parity test enforces that no other file declares local copies.
+// Every consumer (file validators, the Op Spec table, help renderer) imports
+// these — no other file may declare local copies.
 export const ENTITY_TYPES = ['capture', 'entity', 'project'];
 export const ENTITY_STATUSES = ['active', 'paused', 'done'];
 export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
@@ -85,3 +85,9 @@ export const SUBTYPE_SECTIONS = {
     insight: ['Synthesis', 'Evidence', 'Sources'],
     plan: ['Goal', 'Steps', 'Dependencies'],
 };
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export const APPEND_ONLY_SECTIONS = new Set(['Evidence', 'Sources']);
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export const SESSION_SECTIONS = ['Summary', 'Entities Touched', 'Decisions'];

package/dist/db.js

@@ -1,11 +1,11 @@
 import Database from 'better-sqlite3';
 import { createHash } from 'crypto';
-import { readdirSync, readFileSync, statSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, statSync, existsSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
-import { parseFilePath } from './vault.js';
+import { parseFilePath, scanVaultDir, kindDir, INDEXED_KINDS } from './vault.js';
 import { ensureLocalExclude } from './knowledge-index.js';
-import { getNextActions, getBrief, WIKI_LINK_RE, findSection } from './sections.js';
-import { parseSessionLog } from './parser.js';
+import { getNextActions, getBrief, WIKI_LINK_RE, findSection } from './document.js';
+import { parseSessionLog } from './document.js';
 // Bump this when indexing logic changes to force a full rebuild.
 // v5: wiki link harvesting (mention relations), parent link indexing, relation filter on queries.
 // v6: description column on items.
@@ -86,16 +86,6 @@ const STOPWORDS = new Set([
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
 }
-function scanDir(dirPath) {
-    try {
-        // Skip dotfiles: their slugs are rejected by resolveFilePath, so indexing
-        // them would list entities that read/update can never reach.
-        return readdirSync(dirPath).filter(f => f.endsWith('.md') && !f.startsWith('.')).map(f => join(dirPath, f));
-    }
-    catch {
-        return [];
-    }
-}
 // --- Shared query functions (used by both write and readonly paths) ---
 function sanitizeFtsQuery(raw) {
     const cleaned = raw.replace(/[^\w\s]/g, ' ');
@@ -583,8 +573,8 @@ export function createIndex(vaultPath, opts) {
         while ((wikiMatch = linkRe.exec(authoredBody)) !== null) {
             const targetSlug = wikiMatch[1];
             // Check if target file exists on disk (not in index — target may not be indexed yet)
-            const targetEntityPath = join(vaultPath, 'entities', `${targetSlug}.md`);
-            const targetKnowledgePath = join(vaultPath, 'knowledge', `${targetSlug}.md`);
+            const targetEntityPath = join(vaultPath, kindDir('entity'), `${targetSlug}.md`);
+            const targetKnowledgePath = join(vaultPath, kindDir('knowledge'), `${targetSlug}.md`);
             const targetExists = knownSlugs
                 ? knownSlugs.has(targetSlug)
                 : existsSync(targetEntityPath) || existsSync(targetKnowledgePath);
@@ -598,16 +588,16 @@ export function createIndex(vaultPath, opts) {
         db.exec('DELETE FROM links');
         // Collect all vault slugs for wiki link target validation
         const allVaultSlugs = new Set();
-        for (const file of scanDir(join(vaultPath, 'entities'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
             allVaultSlugs.add(basename(file, '.md'));
         }
-        for (const file of scanDir(join(vaultPath, 'knowledge'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
             allVaultSlugs.add(basename(file, '.md'));
         }
-        for (const file of scanDir(join(vaultPath, 'entities'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
             indexFile(file, 'entity', allVaultSlugs);
         }
-        for (const file of scanDir(join(vaultPath, 'knowledge'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
             indexFile(file, 'knowledge', allVaultSlugs);
         }
         db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('last_sync', ?)")
@@ -624,12 +614,9 @@ export function createIndex(vaultPath, opts) {
         }
         const lastSyncTime = parseInt(lastSync.value, 10);
         let changed = false;
-        const dirs = [
-            { dir: 'entities', kind: 'entity' },
-            { dir: 'knowledge', kind: 'knowledge' },
-        ];
+        const dirs = INDEXED_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
         for (const { dir, kind } of dirs) {
-            for (const file of scanDir(join(vaultPath, dir))) {
+            for (const file of scanVaultDir(join(vaultPath, dir))) {
                 if (statSync(file).mtimeMs > lastSyncTime) {
                     indexFile(file, kind);
                     changed = true;
@@ -640,7 +627,7 @@ export function createIndex(vaultPath, opts) {
         const dbSlugs = db.prepare('SELECT slug FROM items').all().map(r => r.slug);
         const fileSlugs = new Set();
         for (const { dir } of dirs) {
-            for (const file of scanDir(join(vaultPath, dir))) {
+            for (const file of scanVaultDir(join(vaultPath, dir))) {
                 fileSlugs.add(basename(file, '.md'));
             }
         }
@@ -656,8 +643,7 @@ export function createIndex(vaultPath, opts) {
         }
     }
     function upsertFromFile(slug, kind) {
-        const dir = kind === 'entity' ? 'entities' : 'knowledge';
-        const filePath = join(vaultPath, dir, `${slug}.md`);
+        const filePath = join(vaultPath, kindDir(kind), `${slug}.md`);
         if (existsSync(filePath)) {
             // Force re-index by clearing cached hash
             deleteItemStmt.run(slug);

package/dist/digest.js

@@ -60,6 +60,8 @@ export function digest(input, existingSlugs, now = new Date()) {
     //    leak into the note body (the schema promises they are omitted).
     const noteBody = buildSessionNoteBody(input, knownTouched);
     const related = knownTouched;
+    // Typechecked against the Op Spec's session-create schema so digest output
+    // can never silently diverge from what batch validation accepts.
     const noteFields = {
         synthesis: noteBody,
         'session-date': input.session_date,

package/dist/document.d.ts

@@ -0,0 +1,108 @@
+import type { SessionLogEntry, SessionLogType } from './types.js';
+/**
+ * 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 declare const STRUCTURAL_SECTIONS: Set<string>;
+/**
+ * Find the next structural `## Heading` boundary after a given position.
+ * Skips `## ` headings that are not known structural sections (content headings).
+ * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
+ */
+export declare function findNextStructuralHeading(body: string, from: number): number;
+/**
+ * Find a ## Heading section and its content.
+ * 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 declare function findSection(body: string, heading: string): {
+    start: number;
+    headingEnd: number;
+    end: number;
+    content: string;
+} | null;
+export interface DocSection {
+    heading: string;
+    content: string;
+}
+/**
+ * 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 declare function splitStructural(body: string): {
+    preamble: string;
+    sections: DocSection[];
+};
+/**
+ * Replace a structural section's content, or create the section: before
+ * `insertBefore` when that section exists, at EOF otherwise.
+ */
+export declare function setSection(body: string, heading: string, content: string, insertBefore?: string): string;
+/** Append content at the end of a structural section (creating it at EOF if absent). */
+export declare function appendToSection(body: string, heading: string, content: string): string;
+/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
+export declare function prependSessionLogEntry(body: string, entry: string): string;
+/** Body up to the real Session Log section — the `summary` read depth. */
+export declare function bodyBeforeSessionLog(body: string): string;
+export declare function parseSessionLogHeading(line: string): {
+    date: string;
+    agent: string;
+    type: SessionLogType;
+} | null;
+export declare function formatSessionLogEntry(entry: SessionLogEntry): string;
+/** 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 declare function countSessionLogEntries(body: string): number;
+export declare function parseSessionLog(body: string): Array<{
+    date: string;
+    agent: string;
+    type: SessionLogType;
+    summary: string;
+}>;
+export declare function extractOldestSessionLogEntry(body: string): {
+    entry: string;
+    remaining: string;
+} | null;
+export declare function getBrief(body: string): string | null;
+export declare function setBrief(body: string, content: string): string;
+export declare function removeBrief(body: string): string;
+export declare function getNextActions(body: string): string[];
+export declare function addNextAction(body: string, action: string): string;
+export declare function completeNextAction(body: string, query: string): {
+    matched: string;
+    body: string;
+};
+export declare function removeNextAction(body: string, query: string): {
+    matched: string;
+    body: string;
+};
+export declare function clearNextActions(body: string): string;
+export declare function firstNonEmptyLine(s: string | null | undefined): string;
+/**
+ * One-line summary for a doc: frontmatter description first, then the first
+ * non-empty line of the kind's primary section (entity: Brief; knowledge:
+ * Synthesis, falling back to Goal for plans; session: Summary).
+ * Shared by the vault index and the OKF export so the two surfaces agree.
+ */
+export declare function deriveSummary(kind: 'entity' | 'knowledge' | 'session', fm: Record<string, any>, body: string): string;
+/** 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 declare const WIKI_LINK_RE: RegExp;
+export declare function syncRelatedSection(body: string, frontmatter: {
+    parent?: string;
+    related?: string[];
+}): string;