hafez 2.1.0 → 2.3.0

package/dist/batch-ops.js

@@ -101,6 +101,9 @@ export const CreateSessionFieldsSchema = z.object({
     insight: nonEmptyText.optional(),
     related: stringList.optional(),
     'session-date': z.string().optional(),
+    // Decisions are prose: a list only, never a comma string split apart.
+    decisions: z.array(nonEmptyText).optional(),
+    entities_touched: stringList.optional(),
 }).strict();
 const CreateEntityBranch = z.object({
     op: z.literal('create'),
@@ -264,7 +267,9 @@ export function duplicateSessionWarning(slug) {
  * batch). The builder runs before the claim — it must see the pre-claim
  * world so a self-referencing parent still fails. */
 function claimNew(ctx, errors, slug, info, build) {
-    const taken = ctx.existsAnywhere(slug);
+    // A session note holds its slug too: every kind shares one index row per
+    // slug, so a create must not take one a session already has.
+    const taken = ctx.existsAnywhere(slug) || ctx.sessionExists(slug);
     if (taken)
         errors.push(`Slug '${slug}' already exists`);
     if (build) {
@@ -309,6 +314,48 @@ function parentCycleError(slug, parent, ctx) {
     const cycle = parentCycle(slug, parent, s => ctx.linksOf(s).parent);
     return cycle ? `Parent '${parent}' would make a cycle: ${cycle.join(' → ')}` : null;
 }
+/** An entity and its own parent or child are never `related` (ADR 0002):
+ * `parent` subsumes it. The errors for the links `slug` would carry after
+ * the op — the parent named in its related, a related whose parent is
+ * `slug`, or a parent whose related names `slug` (a legacy one-way edge) —
+ * against the batch so far. */
+function parentSubsumesErrors(slug, links, ctx) {
+    const errors = [];
+    for (const r of links.related ?? []) {
+        if (r === links.parent)
+            errors.push(`'${r}' is the parent of '${slug}' — parent subsumes related`);
+        else if (ctx.existsAnywhere(r) && ctx.linksOf(r).parent === slug)
+            errors.push(`'${r}' is a child of '${slug}' — parent subsumes related`);
+    }
+    const p = links.parent;
+    if (p && ctx.existsAnywhere(p) && ctx.linksOf(p).related?.includes(slug))
+        errors.push(`'${p}' names '${slug}' in its related — parent subsumes related`);
+    return errors;
+}
+/** Record what the edge writer and dropper will do to the targets: a
+ * same-kind `related` edge has two ends, so after `slug`'s related changes
+ * from `before` to `after`, every added same-kind target carries `slug` and
+ * every dropped one loses it. Cross-kind and unknown targets are left as
+ * they are, like the files. */
+function simulateBackEdges(slug, before, after, ctx) {
+    const kind = ctx.resolve(slug)?.kind;
+    const was = before ?? [];
+    const now = after ?? [];
+    for (const r of [...now.filter(r => !was.includes(r)), ...was.filter(r => !now.includes(r))]) {
+        if (r === slug || !kind || !ctx.existsAnywhere(r) || ctx.resolve(r)?.kind !== kind)
+            continue;
+        const links = ctx.linksOf(r);
+        const rest = (links.related ?? []).filter(x => x !== slug);
+        const related = now.includes(r) ? [...rest, slug] : rest;
+        ctx.simulateLinks(r, { ...links, related: related.length > 0 ? related : undefined });
+    }
+}
+/** The link fields after an op, simulated for `slug` and mirrored on the
+ * targets its related gained or lost. */
+function simulateLinkChange(slug, before, after, ctx) {
+    ctx.simulateLinks(slug, after);
+    simulateBackEdges(slug, before.related, after.related, ctx);
+}
 // `as const satisfies` rather than a `: OpSpec[]` annotation: it keeps each
 // row's `name` a literal, which is what OpSpecName (and through it the Apply
 // table's key type) is derived from. OP_SPECS below re-exports the rows under
@@ -381,8 +428,12 @@ const OP_SPEC_ROWS = [
             }
             if (target) {
                 const links = linkFieldsOf(op.fields);
-                if (links)
-                    ctx.simulateLinks(op.slug, { ...ctx.linksOf(op.slug), ...links });
+                if (links) {
+                    const before = ctx.linksOf(op.slug);
+                    const after = { ...before, ...links };
+                    errors.push(...parentSubsumesErrors(op.slug, after, ctx));
+                    simulateLinkChange(op.slug, before, after, ctx);
+                }
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -398,8 +449,11 @@ const OP_SPEC_ROWS = [
             const errors = [];
             const slug = slugify(op.name);
             const primaryCode = claimNew(ctx, errors, slug, { kind: 'entity', type: op.fields.type }, () => ctx.buildEntityFrontmatter(op.name, op.fields));
-            if (!primaryCode)
-                ctx.simulateLinks(slug, { parent: op.fields.parent, related: op.fields.related });
+            if (!primaryCode) {
+                const links = { parent: op.fields.parent, related: op.fields.related };
+                errors.push(...parentSubsumesErrors(slug, links, ctx));
+                simulateLinkChange(slug, {}, links, ctx);
+            }
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -415,7 +469,7 @@ const OP_SPEC_ROWS = [
             const slug = slugify(op.name);
             const primaryCode = claimNew(ctx, errors, slug, { kind: 'knowledge', type: 'knowledge', subtype: op.fields?.subtype }, () => ctx.buildKnowledgeFrontmatter(op.name, (op.fields || {})));
             if (!primaryCode)
-                ctx.simulateLinks(slug, { related: op.fields?.related });
+                simulateLinkChange(slug, {}, { related: op.fields?.related }, ctx);
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -424,7 +478,7 @@ const OP_SPEC_ROWS = [
         op: 'create',
         kind: 'session',
         schema: CreateSessionBranch,
-        description: 'Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).',
+        description: 'Create a new session note linked to an entity. `synthesis` writes Summary, `decisions` one bullet each under Decisions, `entities_touched` one `[[slug]]` bullet each under Entities Touched. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).',
         exampleInclude: ['synthesis'],
         check(op, ctx) {
             const slug = slugify(op.name);
@@ -452,7 +506,7 @@ const OP_SPEC_ROWS = [
         name: 'link',
         op: 'link',
         schema: LinkBranch,
-        description: 'Add a parent or related link between two entities.',
+        description: 'Add a parent or related link. A same-kind related link (entity↔entity, knowledge↔knowledge) is written on both files; a related naming the entity\'s parent or a child is rejected (parent subsumes related).',
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
@@ -470,9 +524,11 @@ const OP_SPEC_ROWS = [
             }
             if (!primaryCode) {
                 const links = ctx.linksOf(op.slug);
-                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                const after = op.relation === 'parent'
                     ? { ...links, parent: op.target }
-                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] });
+                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] };
+                errors.push(...parentSubsumesErrors(op.slug, after, ctx));
+                simulateLinkChange(op.slug, links, after, ctx);
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -481,7 +537,7 @@ const OP_SPEC_ROWS = [
         name: 'unlink',
         op: 'unlink',
         schema: UnlinkBranch,
-        description: 'Remove a parent or related link between two entities.',
+        description: 'Remove a parent or related link. A same-kind related link is dropped from both files, a legacy one-way edge from whichever file carries it.',
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
@@ -492,9 +548,13 @@ const OP_SPEC_ROWS = [
             }
             else {
                 const links = ctx.linksOf(op.slug);
-                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                simulateLinkChange(op.slug, links, op.relation === 'parent'
                     ? { ...links, parent: links.parent === op.target ? undefined : links.parent }
-                    : { ...links, related: links.related?.filter(r => r !== op.target) });
+                    : { ...links, related: links.related?.filter(r => r !== op.target) }, ctx);
+                // A legacy one-way edge may live on the target alone: the dropper
+                // takes it there too.
+                if (op.relation === 'related' && !links.related?.includes(op.target))
+                    simulateBackEdges(op.slug, [op.target], [], ctx);
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -538,7 +598,7 @@ const OP_SPEC_ROWS = [
         name: 'delete',
         op: 'delete',
         schema: DeleteBranch,
-        description: 'Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. Rejected while another entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.',
+        description: 'Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. The back-edges the note owns (a knowledge note in its own related that names it back) are dropped with it, in the same commit. Rejected while any other entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.',
         exampleInclude: [],
         addressesSessions: true,
         check(op, ctx) {
@@ -558,12 +618,19 @@ const OP_SPEC_ROWS = [
             }
             else {
                 // Only knowledge can be linked to: a parent/related slug must name an
-                // entity or knowledge note, never a session.
-                const referrers = target ? ctx.referrers(op.slug) : [];
+                // entity or knowledge note, never a session. A same-kind back-edge
+                // the note owns — a note in its own related that names it back — is
+                // the other end of its edge, dropped with it (#243), not a blocker.
+                const own = target ? ctx.linksOf(op.slug).related ?? [] : [];
+                const referrers = target
+                    ? ctx.referrers(op.slug).filter(r => !(own.includes(r) && ctx.resolve(r)?.kind === target.kind))
+                    : [];
                 if (referrers.length > 0) {
                     errors.push(`'${op.slug}' is still linked from ${referrers.join(', ')} (parent/related) — unlink or re-point those first; an earlier op in the same batch counts`);
                 }
                 else {
+                    if (target)
+                        simulateBackEdges(op.slug, own, [], ctx);
                     ctx.simulateDelete(op.slug, target ? 'knowledge' : 'session');
                 }
             }

package/dist/cli/block-hook.d.ts

@@ -7,3 +7,9 @@ export interface BlockHookCtx extends ConfigHome {
 }
 /** The render, or null for any failure: the caller prints nothing. */
 export declare function blockHook(ctx: BlockHookCtx): Promise<string | null>;
+/** The working directory, its git root, and in a linked worktree the main
+ * repository's root. */
+export declare function foldersOf(cwd: string): string[];
+/** Every remote's URL, normalised. */
+export declare function remoteUrls(cwd: string): string[];
+export declare function resourceMatches(resource: string, folders: string[], remotes: string[]): boolean;

package/dist/cli/block-hook.js

@@ -26,11 +26,16 @@ export async function blockHook(ctx) {
         // leave an index file in it.
         if (typeof vaultPath !== 'string' || !isVault(vaultPath))
             return null;
-        const cwd = realpathSync(ctx.cwd ?? process.cwd());
+        const dir = ctx.cwd ?? process.cwd();
+        // A deleted working directory: no folder to match.
+        if (!existsSync(dir))
+            return null;
+        const cwd = canonical(dir);
         const folders = foldersOf(cwd);
         const remotes = remoteUrls(cwd);
         const { createHafez } = await import('../index.js');
-        const { items } = await createHafez({ vaultPath, git: { push: false } }).query({ filter: 'all' });
+        const os = createHafez({ vaultPath, git: { push: false } });
+        const { items } = await os.query({ filter: 'all' }).finally(() => os.close());
         const matches = items
             .filter(e => folders.some(f => basename(f) === e.slug) || (e.resource !== null && resourceMatches(e.resource, folders, remotes)))
             // Active first: the status tuple is ordered active, paused, done.
@@ -53,21 +58,33 @@ function git(cwd, ...args) {
 }
 /** The working directory, its git root, and in a linked worktree the main
  * repository's root. */
-function foldersOf(cwd) {
+export function foldersOf(cwd) {
     const folders = [cwd];
     const out = git(cwd, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir');
     const [top, common] = out?.split('\n') ?? [];
     // Before git 2.31 `--path-format` is echoed back, not obeyed: no git root.
     if (top && common && isAbsolute(top) && isAbsolute(common)) {
-        folders.push(top);
+        const root = canonical(top);
+        folders.push(root);
         // A linked worktree shares the main checkout's `.git` as its common dir.
-        if (basename(common) === '.git' && dirname(common) !== top)
-            folders.push(dirname(common));
+        // The shape is read off git's own path: a symlinked `.git` resolves to a
+        // directory with some other name.
+        const main = canonical(dirname(common));
+        if (basename(common) === '.git' && main !== root)
+            folders.push(main);
     }
     return [...new Set(folders)];
 }
+/** One spelling per folder, so paths from git, the working directory and a
+ * `resource` compare equal: git prints `C:/…` on Windows, realpath `C:\…`.
+ * The native realpath, since only it returns the filesystem's own letter case
+ * (`c:\users\…` is `C:\Users\…`) and long names for 8.3 ones. */
+function canonical(path) {
+    const abs = resolve(path);
+    return existsSync(abs) ? realpathSync.native(abs) : abs;
+}
 /** Every remote's URL, normalised. */
-function remoteUrls(cwd) {
+export function remoteUrls(cwd) {
     const out = git(cwd, 'config', '--get-regexp', '^remote\\..*\\.url$');
     return out ? out.split('\n').map(line => normaliseUrl(line.slice(line.indexOf(' ') + 1))) : [];
 }
@@ -81,10 +98,8 @@ function normaliseUrl(url) {
         .replace(/\/+$/, '')
         .replace(/\.git$/, '');
 }
-function resourceMatches(resource, folders, remotes) {
-    if (isAbsolute(resource)) {
-        const path = resolve(resource);
-        return folders.includes(existsSync(path) ? realpathSync(path) : path);
-    }
+export function resourceMatches(resource, folders, remotes) {
+    if (isAbsolute(resource))
+        return folders.includes(canonical(resource));
     return remotes.includes(normaliseUrl(resource));
 }

package/dist/cli/commands.d.ts

@@ -9,7 +9,7 @@ export interface CommandOpts {
 export declare function cmdRead(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 /** Every flag the query parser accepts, for the branch-support matrix. */
 export declare const QUERY_FLAG_NAMES: string[];
-export type QueryBranch = 'entity' | 'knowledge' | 'all' | 'related-to';
+export type QueryBranch = 'entity' | 'knowledge' | 'session' | 'all' | 'related-to';
 /** Which flags each kind branch actually applies. A branch that cannot honour
  * a flag rejects it (below) instead of dropping it: `--kind knowledge --filter
  * stale` used to return every knowledge note with exit 0, and `--confidence`
@@ -36,6 +36,8 @@ export declare function cmdCapture(os: Hafez, args: string[], opts?: CommandOpts
 export declare function cmdPromote(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdDelete(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdValidate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdHealth(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdGraph(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdIndexRebuild(os: Hafez): Promise<string>;
 export declare function cmdSync(os: Hafez, args: string[]): Promise<string>;
 export declare function cmdStats(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;