hafez 1.0.1

package/dist/parser.d.ts

@@ -0,0 +1,18 @@
+import type { SessionLogEntry, SessionLogType } from './types.js';
+export declare function parseSessionLogHeading(line: string): {
+    date: string;
+    agent: string;
+    type: SessionLogType;
+} | null;
+export declare function formatSessionLogEntry(entry: SessionLogEntry): string;
+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;

package/dist/parser.js

@@ -0,0 +1,68 @@
+import { findNextStructuralHeading } from './sections.js';
+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');
+}
+export function countSessionLogEntries(body) {
+    return (body.match(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm) || []).length;
+}
+export function parseSessionLog(body) {
+    // Inline section extraction to avoid circular import with sections.ts
+    const idx = body.indexOf('## Session Log');
+    if (idx === -1)
+        return [];
+    const afterPos = idx + '## Session Log'.length;
+    // Find end: next structural ## heading or end of string
+    const nextH = findNextStructuralHeading(body, afterPos);
+    const sectionContent = nextH !== -1 ? body.slice(afterPos, nextH) : body.slice(afterPos);
+    const entries = [];
+    const lines = sectionContent.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 sectionStart = body.indexOf('## Session Log');
+    if (sectionStart === -1)
+        return null;
+    const afterHeader = body.slice(sectionStart + '## Session Log'.length);
+    const entryStarts = [...afterHeader.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 lastIdx = entryStarts.length - 1;
+    const oldestStart = entryStarts[lastIdx].index;
+    const entry = afterHeader.slice(oldestStart).trim();
+    const remaining = body.slice(0, sectionStart + '## Session Log'.length) + afterHeader.slice(0, oldestStart);
+    return { entry, remaining };
+}

package/dist/query.d.ts

@@ -0,0 +1,24 @@
+import type { QueryResult, KnowledgeQueryResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedResult } from './types.js';
+import type { HafezIndex } from './db.js';
+export declare function queryEntities(index: HafezIndex, opts?: EntityQueryOpts): {
+    items: QueryResult[];
+    total: number;
+};
+export declare function queryChildren(index: HafezIndex, parentSlug: string): {
+    items: QueryResult[];
+    total: number;
+};
+export declare function queryRelatedTo(index: HafezIndex, slug: string, relation?: string): {
+    items: (QueryResult | KnowledgeQueryResult)[];
+    total: number;
+};
+export declare function queryKnowledge(index: HafezIndex, opts?: KnowledgeQueryOpts): {
+    items: KnowledgeQueryResult[];
+    total: number;
+};
+export declare function queryUnified(index: HafezIndex, opts?: EntityQueryOpts & {
+    kind?: 'entity' | 'knowledge' | 'all';
+}): {
+    items: UnifiedResult[];
+    total: number;
+};

package/dist/query.js

@@ -0,0 +1,167 @@
+import { HafezError } from './types.js';
+function toQueryResult(slug, row) {
+    return {
+        slug,
+        name: row.name,
+        type: row.type,
+        status: row.status,
+        description: row.description ?? null,
+        resource: row.resource ?? null,
+        domain: row.domain ?? [],
+        last_touched: row.last_touched,
+        next_action: row.next_action ?? null,
+        next_action_count: row.next_action_count ?? 0,
+        parent: row.parent ?? null,
+        related: row.related ?? [],
+        staleness_days: row.staleness_days ?? null,
+        tags: row.tags ?? [],
+        brief: row.brief ?? null,
+        session_log_count: row.session_log_count ?? 0,
+        last_session_date: row.last_session_date ?? null,
+        last_session_type: row.last_session_type ?? null,
+        last_session_summary: row.last_session_summary ?? null,
+    };
+}
+function toKnowledgeResult(slug, row) {
+    return {
+        slug,
+        name: row.name,
+        description: row.description ?? null,
+        domain: row.domain ?? [],
+        confidence: row.confidence ?? 'observation',
+        related: row.related ?? [],
+        reinforcement_count: row.reinforcement_count ?? 0,
+        last_reinforced: row.last_reinforced ?? null,
+        last_touched: row.last_touched ?? null,
+    };
+}
+const STATUS_FILTERS = new Set(['active', 'paused', 'done']);
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function validateDateOpts(opts) {
+    const fields = ['since', 'before', 'createdSince', 'createdBefore'];
+    for (const f of fields) {
+        if (opts?.[f] !== undefined && !ISO_DATE.test(opts[f])) {
+            throw new HafezError('VALIDATION_FAILED', `Invalid date format for ${f}: "${opts[f]}". Must be YYYY-MM-DD.`);
+        }
+    }
+}
+export function queryEntities(index, opts) {
+    index.syncIfStale();
+    validateDateOpts(opts);
+    const qopts = { kind: 'entity' };
+    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
+        qopts.status = opts.filter;
+    if (opts?.filter === 'stale')
+        qopts.filter = 'stale';
+    if (opts?.filter === 'capture')
+        qopts.filter = 'capture';
+    if (opts?.type)
+        qopts.type = opts.type;
+    if (opts?.parent)
+        qopts.parent = opts.parent;
+    if (opts?.domain)
+        qopts.domain = opts.domain;
+    if (opts?.since)
+        qopts.since = opts.since;
+    if (opts?.before)
+        qopts.before = opts.before;
+    if (opts?.createdSince)
+        qopts.createdSince = opts.createdSince;
+    if (opts?.createdBefore)
+        qopts.createdBefore = opts.createdBefore;
+    if (opts?.tags)
+        qopts.tags = opts.tags;
+    if (opts?.sort_by)
+        qopts.sort_by = opts.sort_by;
+    if (opts?.sort_order)
+        qopts.sort_order = opts.sort_order;
+    if (opts?.limit != null)
+        qopts.limit = opts.limit;
+    if (opts?.offset != null)
+        qopts.offset = opts.offset;
+    const { items, total } = index.queryItems(qopts);
+    return { items: items.map(i => toQueryResult(i.slug, i)), total };
+}
+export function queryChildren(index, parentSlug) {
+    return queryEntities(index, { parent: parentSlug });
+}
+export function queryRelatedTo(index, slug, relation) {
+    index.syncIfStale();
+    const { items, total } = index.queryItems({ relatedTo: slug, relation });
+    return {
+        items: items.map(i => i.kind === 'entity' ? toQueryResult(i.slug, i) : toKnowledgeResult(i.slug, i)),
+        total,
+    };
+}
+export function queryKnowledge(index, opts) {
+    index.syncIfStale();
+    const qopts = { kind: 'knowledge' };
+    if (opts?.domain)
+        qopts.domain = opts.domain;
+    if (opts?.confidence)
+        qopts.confidence = opts.confidence;
+    if (opts?.subtype)
+        qopts.subtype = opts.subtype;
+    if (opts?.tags)
+        qopts.tags = opts.tags;
+    if (opts?.sort_by)
+        qopts.sort_by = opts.sort_by;
+    if (opts?.sort_order)
+        qopts.sort_order = opts.sort_order;
+    if (opts?.limit != null)
+        qopts.limit = opts.limit;
+    if (opts?.offset != null)
+        qopts.offset = opts.offset;
+    const { items, total } = index.queryItems(qopts);
+    return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
+}
+export function queryUnified(index, opts) {
+    index.syncIfStale();
+    validateDateOpts(opts);
+    const qopts = {};
+    if (opts?.kind && opts.kind !== 'all')
+        qopts.kind = opts.kind;
+    // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
+    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
+        qopts.status = opts.filter;
+    if (opts?.filter === 'stale')
+        qopts.filter = 'stale';
+    if (opts?.filter === 'capture')
+        qopts.filter = 'capture';
+    if (opts?.type)
+        qopts.type = opts.type;
+    if (opts?.parent)
+        qopts.parent = opts.parent;
+    if (opts?.domain)
+        qopts.domain = opts.domain;
+    if (opts?.confidence)
+        qopts.confidence = opts.confidence;
+    if (opts?.since)
+        qopts.since = opts.since;
+    if (opts?.before)
+        qopts.before = opts.before;
+    if (opts?.createdSince)
+        qopts.createdSince = opts.createdSince;
+    if (opts?.createdBefore)
+        qopts.createdBefore = opts.createdBefore;
+    if (opts?.tags)
+        qopts.tags = opts.tags;
+    if (opts?.sort_by)
+        qopts.sort_by = opts.sort_by;
+    if (opts?.sort_order)
+        qopts.sort_order = opts.sort_order;
+    if (opts?.limit !== undefined)
+        qopts.limit = opts.limit;
+    if (opts?.offset !== undefined)
+        qopts.offset = opts.offset;
+    const result = index.queryItems(qopts);
+    const items = result.items.map(i => {
+        if (i.kind === 'entity') {
+            return { ...toQueryResult(i.slug, i), kind: 'entity' };
+        }
+        else {
+            return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
+        }
+    });
+    return { items, total: result.total };
+}

package/dist/schema.d.ts

@@ -0,0 +1,9 @@
+export declare function validateEntityFrontmatter(fm: Record<string, any>): string[];
+export declare function validateKnowledgeFrontmatter(fm: Record<string, any>): string[];
+export declare function validateKnowledgeSubtype(fm: Record<string, any>): string[];
+export declare function validateSlugReference(slug: string, field: string, exists: (s: string) => boolean): string | null;
+export declare function validateSessionLogEntry(entry: {
+    type?: string;
+    summary?: string;
+    agent?: string;
+}): string[];

package/dist/schema.js

@@ -0,0 +1,59 @@
+// src/schema.ts
+import { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, } from './contracts.js';
+export function validateEntityFrontmatter(fm) {
+    const errors = [];
+    if (!fm.name || typeof fm.name !== 'string')
+        errors.push('missing required field: name');
+    if (!fm.type || !ENTITY_TYPES.includes(fm.type))
+        errors.push(`invalid type: ${fm.type} (expected: ${ENTITY_TYPES.join(', ')})`);
+    if (!fm.status || !ENTITY_STATUSES.includes(fm.status))
+        errors.push(`invalid status: ${fm.status} (expected: ${ENTITY_STATUSES.join(', ')})`);
+    if (!fm.created)
+        errors.push('missing required field: created');
+    if (!fm['last-touched'])
+        errors.push('missing required field: last-touched');
+    if (fm.domain !== undefined && !Array.isArray(fm.domain))
+        errors.push('entity domain must be an array');
+    return errors;
+}
+export function validateKnowledgeFrontmatter(fm) {
+    const errors = [];
+    if (!fm.name || typeof fm.name !== 'string')
+        errors.push('missing required field: name');
+    if (!fm.created)
+        errors.push('missing required field: created');
+    if (fm.confidence && !CONFIDENCE_LEVELS.includes(fm.confidence)) {
+        errors.push(`invalid confidence: ${fm.confidence} (expected: ${CONFIDENCE_LEVELS.join(', ')})`);
+    }
+    if (fm.domain !== undefined && !Array.isArray(fm.domain))
+        errors.push('knowledge domain must be an array');
+    errors.push(...validateKnowledgeSubtype(fm));
+    return errors;
+}
+export function validateKnowledgeSubtype(fm) {
+    const errors = [];
+    if (fm.subtype && !VALID_SUBTYPES.includes(fm.subtype)) {
+        errors.push(`invalid subtype: ${fm.subtype} (expected: ${VALID_SUBTYPES.join(', ')})`);
+    }
+    // Plan-specific: status must be active or done
+    if (fm.subtype === 'plan' && fm.status && !['active', 'done'].includes(fm.status)) {
+        errors.push(`invalid plan status: ${fm.status} (expected: active, done)`);
+    }
+    return errors;
+}
+export function validateSlugReference(slug, field, exists) {
+    if (!exists(slug))
+        return `${field} reference '${slug}' does not exist`;
+    return null;
+}
+export function validateSessionLogEntry(entry) {
+    const errors = [];
+    if (!entry.type || !SESSION_LOG_TYPES.includes(entry.type)) {
+        errors.push(`invalid session log type: ${entry.type} (expected: ${SESSION_LOG_TYPES.join(', ')})`);
+    }
+    if (!entry.summary || typeof entry.summary !== 'string')
+        errors.push('session log entry must have a summary');
+    if (!entry.agent || typeof entry.agent !== 'string')
+        errors.push('session log entry must have an agent');
+    return errors;
+}

package/dist/sections.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+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, end, content } or null if not found.
+ * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
+ * 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;
+    end: number;
+    content: 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;
+/** 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 declare const WIKI_LINK_RE: RegExp;
+export declare function syncRelatedSection(body: string, frontmatter: {
+    parent?: string;
+    related?: string[];
+}): string;