hafez 2.1.0 → 2.2.0

package/dist/validate.js

@@ -1,29 +1,42 @@
 import { join, basename } from 'path';
-import { parseFilePath, scanVaultDir, kindDir, vaultFileExists } from './vault.js';
-import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
+import { parseFilePath, scanVaultDir, kindDir, findReadableFile } from './vault.js';
+import { validateEntityFrontmatter, validateKnowledgeFrontmatter, validateSessionFrontmatter } from './schema.js';
 import { parentCycle } from './batch-ops.js';
+const FRONTMATTER_CHECKS = {
+    entity: validateEntityFrontmatter,
+    knowledge: validateKnowledgeFrontmatter,
+    session: validateSessionFrontmatter,
+};
 /** The vault integrity scan. Deliberately independent of the SQLite index:
  * this is the one operation that does not trust the index, so it reads the
  * files directly. Re-implementing it as an index query was considered and
  * rejected — an integrity checker that reads the index is checking the
  * index's model of the vault, not the vault. */
 export function validateVault(vaultPath) {
-    const exists = (slug) => vaultFileExists(vaultPath, slug);
+    // Any readable file satisfies a link: an invalid slug definitionally does
+    // not exist, and must report as missing rather than crash.
+    const exists = (slug) => { try {
+        return findReadableFile(vaultPath, slug) !== null;
+    }
+    catch {
+        return false;
+    } };
     const report = {
         broken_slugs: [],
         orphaned_knowledge: [],
         missing_fields: [],
         total_entities: 0,
         total_knowledge: 0,
+        total_sessions: 0,
     };
-    const knowledgeSlugs = new Set();
+    const knowledgeRelated = new Map();
     const referencedKnowledge = new Set();
     const parents = new Map();
-    // Scan entities
-    const entDir = join(vaultPath, kindDir('entity'));
-    {
-        const files = scanVaultDir(entDir);
-        report.total_entities = files.length;
+    // One scan per kind: parse, the kind's frontmatter check, then every
+    // `related` must exist. What a kind adds on top (parent, the orphan
+    // bookkeeping) is in `each`.
+    function scan(kind, each) {
+        const files = scanVaultDir(join(vaultPath, kindDir(kind)));
         for (const filePath of files) {
             const slug = basename(filePath, '.md');
             let fm;
@@ -34,24 +47,29 @@ export function validateVault(vaultPath) {
                 report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
                 continue;
             }
-            const errors = validateEntityFrontmatter(fm);
-            for (const e of errors)
+            for (const e of FRONTMATTER_CHECKS[kind](fm))
                 report.missing_fields.push({ slug, field: '', issue: e });
-            if (fm.parent) {
-                parents.set(slug, fm.parent);
-                if (!exists(fm.parent))
-                    report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
-            }
             if (fm.related && Array.isArray(fm.related)) {
                 for (const r of fm.related) {
                     if (!exists(r))
                         report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
-                    // Track referenced knowledge
-                    referencedKnowledge.add(r);
                 }
             }
+            each(slug, fm);
         }
+        return files.length;
     }
+    report.total_entities = scan('entity', (slug, fm) => {
+        if (fm.parent) {
+            parents.set(slug, fm.parent);
+            if (!exists(fm.parent))
+                report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
+        }
+        // Track referenced knowledge
+        if (Array.isArray(fm.related))
+            for (const r of fm.related)
+                referencedKnowledge.add(r);
+    });
     // Parent cycles: reported once each, under the first member found
     const inCycle = new Set();
     for (const [slug, parent] of parents) {
@@ -64,46 +82,16 @@ export function validateVault(vaultPath) {
             inCycle.add(s);
         report.broken_slugs.push({ slug, field: 'parent', issue: `parent cycle: ${cycle.join(' → ')}` });
     }
-    // Scan knowledge
-    const knDir = join(vaultPath, kindDir('knowledge'));
-    {
-        const files = scanVaultDir(knDir);
-        report.total_knowledge = files.length;
-        for (const filePath of files) {
-            const slug = basename(filePath, '.md');
-            knowledgeSlugs.add(slug);
-            let fm;
-            try {
-                fm = parseFilePath(filePath).frontmatter;
-            }
-            catch {
-                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
-                continue;
-            }
-            const errors = validateKnowledgeFrontmatter(fm);
-            for (const e of errors)
-                report.missing_fields.push({ slug, field: '', issue: e });
-            if (fm.related && Array.isArray(fm.related)) {
-                for (const r of fm.related) {
-                    if (!exists(r))
-                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
-                }
-            }
-        }
-    }
+    report.total_knowledge = scan('knowledge', (slug, fm) => {
+        knowledgeRelated.set(slug, Array.isArray(fm.related) ? fm.related.length : 0);
+    });
+    // A session with no related is never an orphan — a session that touched
+    // nothing is legitimate.
+    report.total_sessions = scan('session', () => { });
     // Find orphaned knowledge: no related, and not referenced by any entity
-    for (const slug of knowledgeSlugs) {
-        let fm;
-        try {
-            fm = parseFilePath(join(knDir, `${slug}.md`)).frontmatter;
-        }
-        catch {
-            continue; // already reported above
-        }
-        const hasRelated = fm.related && Array.isArray(fm.related) && fm.related.length > 0;
-        if (!hasRelated && !referencedKnowledge.has(slug)) {
+    for (const [slug, related] of knowledgeRelated) {
+        if (related === 0 && !referencedKnowledge.has(slug))
             report.orphaned_knowledge.push(slug);
-        }
     }
     return report;
 }

package/dist/vault.d.ts

@@ -1,21 +1,25 @@
 import type { ParsedVaultFile } from './types.js';
 export declare function slugify(name: string): string;
 export type VaultKind = 'entity' | 'knowledge' | 'session';
-/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
-export declare const INDEXED_KINDS: ReadonlyArray<'entity' | 'knowledge'>;
+/** Kinds that live in the SQLite read index: every kind. Sessions joined in
+ * #35 — before that they were files-and-git only, for no recorded reason. */
+export declare const INDEXED_KINDS: ReadonlyArray<VaultKind>;
+/** The two kinds a mutation can address. A session note is written once and
+ * read; `update`, `link`, `promote` never resolve one. */
+export declare const MUTABLE_KINDS: ReadonlyArray<'entity' | 'knowledge'>;
 /** Vault directory for a kind, relative to the vault root. */
 export declare function kindDir(kind: VaultKind): string;
 /** A vault content file: anything a sync/merge must treat semantically. */
 export declare const VAULT_FILE_RE: RegExp;
-/** True for vault-relative paths whose kind lives in the read index. */
-export declare function isIndexedRelPath(relPath: string): boolean;
+/** True for vault-relative paths of a mutable kind — what index.md shows. */
+export declare function isMutableRelPath(relPath: string): boolean;
 /** History pathspecs covering the indexed dirs (changelog, file times). */
 export declare const INDEXED_DIR_PATHSPECS: ReadonlyArray<string>;
 /** Classify a vault-relative path into an indexed kind + slug; null outside
  * the indexed dirs (sessions, non-vault files). Nested paths keep their
  * historical shape: entities/archive/x-log.md → entity 'archive/x-log'. */
 export declare function classifyIndexedRelPath(relPath: string): {
-    kind: 'entity' | 'knowledge';
+    kind: VaultKind;
     slug: string;
 } | null;
 /** All .md files directly in dir — non-recursive (archive/ subdirs are
@@ -25,9 +29,18 @@ export declare function scanVaultDir(dirPath: string): string[];
 /** Where an entity's overflow session-log entries are archived. */
 export declare function archiveLogPath(vaultPath: string, slug: string): string;
 export declare function resolveFilePath(vaultPath: string, slug: string, kind: VaultKind): string;
-/** The file a slug names, or null — entities are resolved before knowledge,
- * the one resolution order every operation sees. */
+/** The inverse of resolveFilePath / archiveLogPath: a vault file as the
+ * Journal names it — vault-relative and '/'-separated on every platform.
+ * Everything downstream compares these lists as POSIX paths: stageablePaths
+ * (src/git.ts) keeps an absent path only if `git ls-files` echoes it back,
+ * always with '/', so a '\' deletion was dropped and never staged; and the
+ * index.md gate (isMutableRelPath) never matched a '\' path (#187). */
+export declare function vaultRel(vaultPath: string, filePath: string): string;
+/** The mutable file a slug names, or null — entities are resolved before
+ * knowledge, the one resolution order every mutation sees. */
 export declare function findVaultFile(vaultPath: string, slug: string): string | null;
+/** The file `read` resolves: the mutable kinds first, then a session note. */
+export declare function findReadableFile(vaultPath: string, slug: string): string | null;
 /** Does this slug name a vault file? An invalid slug definitionally doesn't
  * exist — reference checks (create parent/related, link targets, validate)
  * must report "does not exist", not crash. validate() in particular exists to

package/dist/vault.js

@@ -2,7 +2,7 @@
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, relative, sep } from 'path';
 import { HafezError } from './types.js';
 // Prevent gray-matter from auto-coercing YAML date strings into JS Date objects
 const MATTER_OPTIONS = { engines: { yaml: (s) => yaml.load(s, { schema: yaml.JSON_SCHEMA }) } };
@@ -17,17 +17,21 @@ export function slugify(name) {
         .replace(/-{2,}/g, '-');
 }
 const KIND_DIRS = { entity: 'entities', knowledge: 'knowledge', session: 'sessions' };
-/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
-export const INDEXED_KINDS = ['entity', 'knowledge'];
+/** Kinds that live in the SQLite read index: every kind. Sessions joined in
+ * #35 — before that they were files-and-git only, for no recorded reason. */
+export const INDEXED_KINDS = ['entity', 'knowledge', 'session'];
+/** The two kinds a mutation can address. A session note is written once and
+ * read; `update`, `link`, `promote` never resolve one. */
+export const MUTABLE_KINDS = ['entity', 'knowledge'];
 /** Vault directory for a kind, relative to the vault root. */
 export function kindDir(kind) {
     return KIND_DIRS[kind];
 }
 /** A vault content file: anything a sync/merge must treat semantically. */
 export const VAULT_FILE_RE = new RegExp(`^(?:${Object.values(KIND_DIRS).join('|')})/.+\\.md$`);
-/** True for vault-relative paths whose kind lives in the read index. */
-export function isIndexedRelPath(relPath) {
-    return INDEXED_KINDS.some(k => relPath.startsWith(`${KIND_DIRS[k]}/`));
+/** True for vault-relative paths of a mutable kind — what index.md shows. */
+export function isMutableRelPath(relPath) {
+    return MUTABLE_KINDS.some(k => relPath.startsWith(`${KIND_DIRS[k]}/`));
 }
 /** History pathspecs covering the indexed dirs (changelog, file times). */
 export const INDEXED_DIR_PATHSPECS = INDEXED_KINDS.map(k => `${KIND_DIRS[k]}/`);
@@ -69,8 +73,17 @@ export function resolveFilePath(vaultPath, slug, kind) {
     }
     return join(vaultPath, KIND_DIRS[kind], `${slug}.md`);
 }
-/** The file a slug names, or null — entities are resolved before knowledge,
- * the one resolution order every operation sees. */
+/** The inverse of resolveFilePath / archiveLogPath: a vault file as the
+ * Journal names it — vault-relative and '/'-separated on every platform.
+ * Everything downstream compares these lists as POSIX paths: stageablePaths
+ * (src/git.ts) keeps an absent path only if `git ls-files` echoes it back,
+ * always with '/', so a '\' deletion was dropped and never staged; and the
+ * index.md gate (isMutableRelPath) never matched a '\' path (#187). */
+export function vaultRel(vaultPath, filePath) {
+    return relative(vaultPath, filePath).split(sep).join('/');
+}
+/** The mutable file a slug names, or null — entities are resolved before
+ * knowledge, the one resolution order every mutation sees. */
 export function findVaultFile(vaultPath, slug) {
     const entity = resolveFilePath(vaultPath, slug, 'entity');
     if (existsSync(entity))
@@ -80,6 +93,14 @@ export function findVaultFile(vaultPath, slug) {
         return knowledge;
     return null;
 }
+/** The file `read` resolves: the mutable kinds first, then a session note. */
+export function findReadableFile(vaultPath, slug) {
+    const mutable = findVaultFile(vaultPath, slug);
+    if (mutable)
+        return mutable;
+    const session = resolveFilePath(vaultPath, slug, 'session');
+    return existsSync(session) ? session : null;
+}
 /** Does this slug name a vault file? An invalid slug definitionally doesn't
  * exist — reference checks (create parent/related, link targets, validate)
  * must report "does not exist", not crash. validate() in particular exists to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,7 +30,7 @@
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.1",
     "proper-lockfile": "^4.1.2",
-    "simple-git": "^3.33.0",
+    "simple-git": "^4.0.2",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/skill/hafez/SKILL.md

@@ -6,7 +6,7 @@ description: >
   wants to promote, link, unlink, delete, change a status or validate, or
   wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez").
   Also the reference to read when no Hafez block is in your instructions.
-hash: 01a30ae1e209
+hash: 24f12671554e
 ---
 
 # Hafez
@@ -32,10 +32,13 @@ A plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowle
 
 ```
 hafez query --filter <active|paused|done|stale|capture>
-hafez search "<terms>" --kind <entity|knowledge>
+hafez search "<terms>" --kind <entity|knowledge|session|all>
+hafez query --kind session --related-to <slug>
 hafez stats
 ```
 
+`search` and `query` reach entities and knowledge notes; `--kind all` adds the session notes, `--kind session` lists them alone, newest first. `hafez read <slug> --archive` prints an entity's archived log entries.
+
 ## Less common operations
 
 ```