hafez 1.3.0 → 1.4.0

package/dist/export-okf.js

@@ -8,18 +8,44 @@
 import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve, sep, basename } from 'path';
 import { parseFilePath, serializeFile, scanVaultDir, kindDir } from './vault.js';
+import { DEFAULT_KNOWLEDGE_SUBTYPE } from './contracts.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');
+/** `index.md` is reserved in every bundle directory for the generated index, so
+ * a vault doc slugged `index` cannot keep its name — before this it was silently
+ * overwritten by the index that ran after it. Deterministic rule: rename to
+ * `index-doc`, then `index-doc-2`, `index-doc-3`, … until the name is free among
+ * that directory's real slugs (a vault may legitimately hold both `index` and
+ * `index-doc`). Same vault contents always produce the same bundle names, and
+ * every link/index reference is written against the renamed file. */
+const RESERVED_INDEX = 'index';
+function assignBundleNames(docs) {
+    const slugsByDir = new Map();
+    for (const doc of docs) {
+        const slugs = slugsByDir.get(doc.dir) ?? new Set();
+        slugs.add(doc.slug);
+        slugsByDir.set(doc.dir, slugs);
+    }
+    for (const doc of docs) {
+        if (doc.slug !== RESERVED_INDEX)
+            continue;
+        const taken = slugsByDir.get(doc.dir);
+        let candidate = `${RESERVED_INDEX}-doc`;
+        for (let n = 2; taken.has(candidate); n++)
+            candidate = `${RESERVED_INDEX}-doc-${n}`;
+        doc.file = candidate;
+    }
+}
 function mapFrontmatter(doc) {
     const { fm, kind, body } = doc;
     const mapped = {};
     if (kind === 'entity')
         mapped.type = fm.type ?? 'entity';
     else if (kind === 'knowledge')
-        mapped.type = fm.subtype ? `knowledge/${fm.subtype}` : 'knowledge';
+        mapped.type = `knowledge/${fm.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}`;
     else
         mapped.type = 'session';
     mapped.title = fm.name;
@@ -95,28 +121,28 @@ export function exportOkf(vaultPath, outDir) {
                 process.stderr.write(`Warning: skipping ${relFile}: missing name\n`);
                 continue;
             }
-            docs.push({ slug, dir, kind, fm, body });
+            docs.push({ slug, dir, kind, fm, body, file: slug });
         }
     }
-    // Slug→dir map: insertion order entities/knowledge/sessions, first write wins,
-    // giving entity precedence on cross-kind slug collisions.
-    const slugDirs = new Map();
+    assignBundleNames(docs);
+    // Slug→bundle path map: insertion order entities/knowledge/sessions, first write
+    // wins, giving entity precedence on cross-kind slug collisions. Paths are
+    // bundle-root-absolute with hardcoded '/' separators.
+    const slugPaths = new Map();
     for (const doc of docs) {
-        if (!slugDirs.has(doc.slug))
-            slugDirs.set(doc.slug, doc.dir);
+        if (!slugPaths.has(doc.slug))
+            slugPaths.set(doc.slug, `/${doc.dir}/${doc.file}.md`);
     }
     function transformBody(body) {
         return body.replace(OKF_LINK_RE, (_m, rawSlug, rawDisplay) => {
-            // Trim: Obsidian-idiomatic [[ foo ]] / [[foo | Label]] carry whitespace in the captures
             const slug = rawSlug.trim();
             const label = rawDisplay?.trim() || slug;
-            const dir = slugDirs.get(slug);
-            if (!dir) {
+            const path = slugPaths.get(slug);
+            if (!path) {
                 report.unresolvedLinks++;
                 return label;
             }
-            // Bundle-root-absolute path, hardcoded '/' separators
-            return `[${label}](/${dir}/${slug}.md)`;
+            return `[${label}](${path})`;
         });
     }
     mkdirSync(resolvedOut, { recursive: true });
@@ -125,7 +151,7 @@ export function exportOkf(vaultPath, outDir) {
         const mapped = mapFrontmatter(doc);
         const outSubdir = join(resolvedOut, doc.dir);
         mkdirSync(outSubdir, { recursive: true });
-        writeFileSync(join(outSubdir, `${doc.slug}.md`), serializeFile(mapped, transformBody(doc.body)));
+        writeFileSync(join(outSubdir, `${doc.file}.md`), serializeFile(mapped, transformBody(doc.body)));
         if (doc.kind === 'entity')
             report.entities++;
         else if (doc.kind === 'knowledge')
@@ -133,7 +159,7 @@ export function exportOkf(vaultPath, outDir) {
         else
             report.sessions++;
         const list = byDir.get(doc.dir) ?? [];
-        list.push({ slug: doc.slug, title: mapped.title, description: mapped.description ?? '' });
+        list.push({ file: doc.file, title: mapped.title, description: mapped.description ?? '' });
         byDir.set(doc.dir, list);
     }
     // Per-dir index.md — reserved file: NO frontmatter, sorted bullets
@@ -142,7 +168,7 @@ export function exportOkf(vaultPath, outDir) {
         const lines = [`# ${heading}`, ''];
         for (const item of items.sort((a, b) => a.title.localeCompare(b.title))) {
             const desc = item.description ? ` — ${item.description}` : '';
-            lines.push(`- [${item.title}](/${dir}/${item.slug}.md)${desc}`);
+            lines.push(`- [${item.title}](/${dir}/${item.file}.md)${desc}`);
         }
         writeFileSync(join(resolvedOut, dir, 'index.md'), lines.join('\n') + '\n');
     }

package/dist/git.js

@@ -3,7 +3,8 @@ 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 { VAULT_FILE_RE, INDEXED_DIR_PATHSPECS, classifyIndexedRelPath, vaultKindFromRelPath } from './vault.js';
+import { normalizeSinceDate } from './dates.js';
 import { HafezError } from './types.js';
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
@@ -50,6 +51,61 @@ async function hasOriginRemote(git) {
     const remotes = await git.getRemotes();
     return remotes.some(r => r.name === 'origin');
 }
+/** The branch this vault is on (symbolic HEAD). */
+async function currentBranch(git) {
+    return (await git.raw(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+}
+/** The branch's configured upstream (`origin/main`), or null when it has none. */
+async function upstreamRef(git) {
+    try {
+        const ref = (await git.raw(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])).trim();
+        return ref || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Give the current branch an upstream when git does not know about one yet.
+ *
+ * `git remote add origin …` on a vault that has only ever been local leaves
+ * the branch both unpublished and untracked, and in that state `git pull`,
+ * `git push` and `@{u}` are all fatal — so every mutation after the remote
+ * was added died at the sync/push stage. Returns false when origin does not
+ * carry the branch at all: there is nothing to pull and nothing to track
+ * until the first push creates it (see pushCurrent).
+ *
+ * A remote we cannot reach also reports false — the caller's push, and its
+ * retry loop, is where a network failure belongs.
+ */
+async function ensureUpstream(git) {
+    if (await upstreamRef(git))
+        return true;
+    try {
+        const branch = await currentBranch(git);
+        const heads = await git.raw(['ls-remote', '--heads', 'origin', branch]);
+        if (!heads.trim())
+            return false;
+        await git.fetch('origin', branch);
+        await git.raw(['branch', `--set-upstream-to=origin/${branch}`, branch]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Push the current branch, publishing it when it has no upstream yet. That
+ * first `push --set-upstream` is what turns a freshly-added origin into a
+ * normal tracking setup; every push after it is the plain push.
+ */
+async function pushCurrent(git) {
+    if (await upstreamRef(git)) {
+        await git.push();
+        return;
+    }
+    await git.push(['--set-upstream', 'origin', await currentBranch(git)]);
+}
 /** Read one side of a conflicted file from the index; null if that side deleted it. */
 async function showStage(git, stage, file) {
     try {
@@ -104,9 +160,12 @@ async function resolveRebaseConflicts(git, vaultPath) {
                     await git.raw(['rm', '--force', '--ignore-unmatch', '--', file]);
                     continue;
                 }
+                // Classify from the repo-relative path: every file here passed
+                // VAULT_FILE_RE, so the Layout classifier is total over it — no
+                // fallback kind to drift when a vault dir is added.
                 const merged = localContent === null ? remoteContent
                     : remoteContent === null ? localContent
-                        : mergeVaultContent(remoteContent, localContent);
+                        : mergeVaultContent(remoteContent, localContent, vaultKindFromRelPath(file));
                 const fullPath = join(vaultPath, file);
                 mkdirSync(dirname(fullPath), { recursive: true });
                 writeFileSync(fullPath, merged);
@@ -188,10 +247,13 @@ async function pullResolving(git, vaultPath, conflictMessage) {
  * local data survives a conflict.
  */
 async function pushResolving(git, vaultPath, conflictMessage, exhaustedMessage) {
+    // Bootstrap a freshly-added origin before the retry loop: without an
+    // upstream the rejection handling below (pull --rebase) is itself fatal.
+    await ensureUpstream(git);
     let lastDetail = '';
     for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
         try {
-            await git.push();
+            await pushCurrent(git);
             return;
         }
         catch (pushErr) {
@@ -226,29 +288,36 @@ export async function gitSync(vaultPath) {
     await ensureCleanState(git, vaultPath);
     const syncConflictMessage = (files) => `Git conflict during sync (files: ${files.join(', ')}). Changes saved locally.`;
     let pulled = false;
-    // Always pull first (bidirectional sync)
-    const headBefore = (await git.revparse(['HEAD'])).trim();
-    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
-        try {
-            await pullResolving(git, vaultPath, syncConflictMessage);
-            const headAfter = (await git.revparse(['HEAD'])).trim();
-            pulled = headAfter !== headBefore;
-            break;
-        }
-        catch (err) {
-            if (err instanceof HafezError)
-                throw err;
-            if (attempt === MAX_PUSH_RETRIES) {
-                const detail = err instanceof Error ? err.message : String(err);
-                throw new HafezError('GIT_PUSH_FAILED', `Git pull failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
+    // A remote that does not carry this branch yet (freshly added to a vault
+    // that has only ever been local) has nothing to pull and no `@{u}` to count
+    // against — both steps would be fatal. Skip straight to the push, which
+    // publishes the branch and sets the upstream.
+    const tracking = await ensureUpstream(git);
+    if (tracking) {
+        // Always pull first (bidirectional sync)
+        const headBefore = (await git.revparse(['HEAD'])).trim();
+        for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
+            try {
+                await pullResolving(git, vaultPath, syncConflictMessage);
+                const headAfter = (await git.revparse(['HEAD'])).trim();
+                pulled = headAfter !== headBefore;
+                break;
+            }
+            catch (err) {
+                if (err instanceof HafezError)
+                    throw err;
+                if (attempt === MAX_PUSH_RETRIES) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new HafezError('GIT_PUSH_FAILED', `Git pull failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
+                }
+                await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
             }
-            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
         }
+        // Check if there are local commits to push
+        const ahead = await git.raw(['rev-list', '--count', '@{u}..HEAD']).then(s => parseInt(s.trim(), 10));
+        if (ahead === 0)
+            return { pulled, pushed: false, remote: true };
     }
-    // Check if there are local commits to push
-    const ahead = await git.raw(['rev-list', '--count', '@{u}..HEAD']).then(s => parseInt(s.trim(), 10));
-    if (ahead === 0)
-        return { pulled, pushed: false, remote: true };
     await pushResolving(git, vaultPath, syncConflictMessage, `Git push failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`);
     return { pulled, pushed: true, remote: true };
 }
@@ -265,6 +334,23 @@ async function gitUnstage(vaultPath, files) {
     }
     catch { /* best effort — rollback must not mask the original error */ }
 }
+/**
+ * The subset of `files` that `git add` can actually stage. `git add` is fatal
+ * on a pathspec matching nothing, and a batch that creates then deletes the
+ * same slug (capture then cross-kind promote) hands the Journal a deleted path
+ * that is absent from the worktree AND was never tracked — unstageable by
+ * construction, and it needs no staging: git never knew about it. A deleted
+ * path git DOES track still goes through `add`, which stages its removal.
+ */
+async function stageablePaths(git, vaultPath, files) {
+    const absent = files.filter(f => !existsSync(join(vaultPath, f)));
+    if (absent.length === 0)
+        return files;
+    // -z: NUL-separated, so git never quotes/escapes the paths it echoes back.
+    const tracked = new Set((await git.raw(['ls-files', '-z', '--', ...absent])).split('\0').filter(Boolean));
+    const absentSet = new Set(absent);
+    return files.filter(f => !absentSet.has(f) || tracked.has(f));
+}
 /** Get list of files with unresolved conflicts */
 async function getConflictingFiles(git) {
     try {
@@ -280,13 +366,35 @@ const FILE_STATUS_MAP = {
     M: 'updated',
     D: 'deleted',
 };
+/**
+ * One `--name-status` line → the (path, operation) pairs it stands for.
+ *
+ * Rename and copy lines carry a similarity score and TWO paths
+ * (`R100\told\tnew`), so they match neither the single-path shape nor a
+ * bare status letter. A promote moves entities/<slug>.md to
+ * knowledge/<slug>.md, which git reports exactly that way — dropping the
+ * line made every promote invisible in the changelog. A rename reads as the
+ * old path disappearing and the new one appearing; a copy leaves the source
+ * in place, so only the destination is news.
+ */
+function parseNameStatusLine(line) {
+    const moveMatch = line.match(/^([RC])\d*\t([^\t]+)\t(.+)$/);
+    if (moveMatch) {
+        const [, statusChar, from, to] = moveMatch;
+        const dest = [{ path: to, operation: 'created' }];
+        return statusChar === 'C' ? dest : [{ path: from, operation: 'deleted' }, ...dest];
+    }
+    const match = line.match(/^([A-Z])\t(.+)$/);
+    if (!match)
+        return [];
+    const operation = FILE_STATUS_MAP[match[1]];
+    return operation ? [{ path: match[2], operation }] : [];
+}
 export async function gitChangelog(vaultPath, since) {
     const git = simpleGit(vaultPath);
-    // git approxidate fills a date-only --since with the *current* time of
-    // day, so `--since <today>` means "since right now" and silently returns
-    // nothing — the obvious "what happened today" query was the one that
-    // failed. Normalise bare dates to local midnight.
-    const normalizedSince = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+    // Bare dates become local midnight — the same calendar-day boundary the
+    // vault stamps and query comparisons use (see dates.ts).
+    const normalizedSince = normalizeSinceDate(since);
     let output;
     try {
         output = await git.raw([
@@ -310,21 +418,16 @@ export async function gitChangelog(vaultPath, since) {
             continue;
         const [, , timestamp, commit_message] = headerMatch;
         for (let i = 1; i < lines.length; i++) {
-            const fileMatch = lines[i].match(/^([AMDRC])\t(.+)$/);
-            if (!fileMatch)
-                continue;
-            const [, statusChar, filePath] = fileMatch;
-            const operation = FILE_STATUS_MAP[statusChar];
-            if (!operation)
-                continue;
-            // Only vault documents — scaffold files (.gitkeep) live in the same
-            // dirs and would otherwise surface as changelog rows.
-            if (!filePath.endsWith('.md'))
-                continue;
-            const classified = classifyIndexedRelPath(filePath);
-            if (!classified)
-                continue;
-            entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
+            for (const { path: filePath, operation } of parseNameStatusLine(lines[i])) {
+                // Only vault documents — scaffold files (.gitkeep) live in the same
+                // dirs and would otherwise surface as changelog rows.
+                if (!filePath.endsWith('.md'))
+                    continue;
+                const classified = classifyIndexedRelPath(filePath);
+                if (!classified)
+                    continue;
+                entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
+            }
         }
     }
     return entries;
@@ -377,10 +480,19 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
             writeFileSync(fullPath, content);
         }
     }
-    await git.add(files);
-    // Handle "nothing to commit" (e.g., idempotent update wrote identical content)
-    const status = await git.status();
-    if (status.staged.length === 0)
+    const stageable = await stageablePaths(git, vaultPath, files);
+    if (stageable.length === 0)
+        return;
+    await git.add(stageable);
+    // Handle "nothing to commit" (e.g., idempotent update wrote identical
+    // content). Ask the index directly rather than via simple-git's status:
+    // its `staged` list omits renamed paths (they go to `renamed` only), so a
+    // promote git detected as a rename read as "nothing to commit" and was
+    // silently dropped — left staged, uncommitted, absent from the changelog.
+    // Same output-based protocol the rebase loop uses, and it is well-defined
+    // against an unborn HEAD (diffs the empty tree).
+    const stagedPaths = (await git.raw(['diff', '--cached', '--name-only'])).trim();
+    if (stagedPaths.length === 0)
         return;
     const committed = await git.commit(message);
     // simple-git swallows some commit failures (e.g. a rejected pre-commit
@@ -415,7 +527,12 @@ export function createGitJournal(vaultPath, config = {}) {
                 if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
                     await gitUnstage(vaultPath, files);
                 }
-                throw err;
+                // The Journal is the seam: git's own error types must not escape it,
+                // or callers (and the CLI exit-code table) see an unclassified failure.
+                if (err instanceof HafezError)
+                    throw err;
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new HafezError('GIT_COMMIT_FAILED', `git commit failed for: ${files.join(', ')}`, [detail]);
             }
         },
         sync: () => gitSync(vaultPath),

package/dist/index.d.ts

@@ -1,6 +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, Journal, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
-export { getBrief, getNextActions, findSection } from './document.js';
+export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, 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 } from './document.js';
 export { parseSessionLogHeading, parseSessionLog } from './document.js';