hafez 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shrvn-r
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# Hafez
+
+**An agent-native personal knowledge vault.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. It keeps a durable, structured memory for AI agents: plain markdown files you own, backed by SQLite full-text search and git.
+
+## Why
+
+AI agents forget everything between sessions. Hafez gives them a place to remember — projects, insights, decisions, session history — as a knowledge graph they can read, query, and write through a CLI.
+
+The files stay yours. Everything is markdown with YAML frontmatter in a git repo: readable in any editor, Obsidian-compatible, diffable, and synced like code. The SQLite index (`.hafez.db`) is a disposable read cache rebuilt from the files; git is the source of truth and the sync mechanism.
+
+## Setup
+
+Hafez is a tool for agents — so let an agent install it. Paste this into
+Claude Code (or any agent with shell access):
+
+```text
+Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
+
+1. Install the CLI (needs Node.js 22+ and git):
+   npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
+   On npm 12+, append --allow-remote=root --allow-scripts=better-sqlite3
+   (npm 12 blocks URL-tarball installs and install scripts by default;
+   the SQLite bindings need their install script).
+2. Check git identity is configured (git config user.name and user.email);
+   if not, ask me for a name and email and set them with git config --global.
+3. Create my vault — a git repo with entities/ and knowledge/ directories and an
+   initial commit. Suggest ~/vault but ask me where I want it first.
+4. Register it: hafez init --register <vault-path>
+5. Install the bundled agent skill: copy skill/SKILL.md from the installed
+   package ("$(npm root -g)/hafez/skill/SKILL.md") to ~/.claude/skills/hafez/SKILL.md
+6. Read hafez help --agent, then verify end-to-end: create a test capture,
+   hafez read it back, and show me hafez stats.
+7. Tell me what you set up, and give me three example asks I can use in future
+   sessions to see the vault working (e.g. "what am I working on?").
+```
+
+From then on, just mention your projects by name in any session — the skill
+teaches the agent when to read and write the vault, no commands required.
+
+### Manual setup
+
+The same thing by hand:
+
+```bash
+# Install (Node.js 22+ and git required).
+# On npm 12+, append: --allow-remote=root --allow-scripts=better-sqlite3
+npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
+
+# One-time, if you've never used git on this machine:
+#   git config --global user.name "Your Name"
+#   git config --global user.email "you@example.com"
+
+mkdir -p ~/vault/entities ~/vault/knowledge
+cd ~/vault && git init && git commit --allow-empty -m "init vault"
+
+hafez init --register ~/vault           # remember this vault (one-time)
+hafez init                              # show current vault resolution
+
+# Claude Code skill (optional but recommended)
+mkdir -p ~/.claude/skills/hafez
+cp "$(npm root -g)/hafez/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
+```
+
+On npm ≤11, `npm install -g github:shrvn-r/hafez` also works (npm 12 disables
+git installs by default). An npm registry package is planned; GitHub is the
+distribution channel for now.
+
+## Quick start
+
+Whether you drive it or an agent does, the CLI is the whole interface:
+
+```bash
+# Create a project
+hafez create entity "Auth Refactor" --type project \
+  --description "Move auth service to JWT" --add-action "Write migration plan"
+
+# Quick capture for later triage
+hafez capture "Look into passkeys" --notes "Saw this mentioned in an RFC"
+
+# Read it back
+hafez read auth-refactor
+
+# Query
+hafez query --filter active --type project
+hafez query --kind knowledge --domain security
+
+# Full-text search across the whole vault
+hafez search "token rotation"
+
+# Record progress
+hafez update auth-refactor --log "progress: JWT flow implemented" --agent claude
+hafez update auth-refactor --complete-action "migration plan"
+```
+
+Every mutating command commits to git and syncs with the remote (if one is configured).
+
+## Core concepts
+
+Three kinds of documents, all markdown + YAML frontmatter:
+
+- **Entities** (`entities/*.md`) — the things you're working on. Types: `capture` (inbox item), `entity` (anything worth tracking), `project` (has outcomes). Statuses: `active | paused | done`. Bodies start from a per-type template (capture: `## Notes`; entity: `## Context`; project: `## Purpose` + `## Goals`) plus a `## Session Log` of dated agent entries; `## Brief` (freeform handoff context) and `## Next Actions` (checkbox list) appear when first written to.
+- **Knowledge** (`knowledge/*.md`) — durable insights that outlive any one project. Subtypes `insight | plan`; confidence levels `observation → pattern → principle` (promoted manually). Bodies hold `## Synthesis`, `## Evidence`, and `## Sources` — evidence accumulates over time via `--add-evidence`.
+- **Sessions** (`sessions/*.md`) — session summaries written via `batch`, kept as history, not indexed.
+
+Frontmatter at a glance:
+
+| Field | Entities | Knowledge |
+|---|---|---|
+| `name`, `created` | required | required |
+| `type`, `status`, `last-touched` | required | — |
+| `description` (one-line summary) | optional | optional |
+| `domain` (string[]), `tags`, `related` | optional | optional |
+| `parent` (slug) | optional | — |
+| `resource` (canonical URI) | optional | — |
+| `subtype`, `confidence` | — | optional |
+
+Links (`parent`, `related`) are validated — they must point at slugs that exist. `hafez validate` checks vault integrity.
+
+## CLI overview
+
+| Command | What it does |
+|---|---|
+| `hafez read <slug> [--depth frontmatter\|summary\|full]` | Read an entity or knowledge note |
+| `hafez query [--filter active\|paused\|done\|stale\|capture\|all] [--type] [--kind entity\|knowledge\|all] [--domain] [--tag] [--parent] [--related-to] [--limit]` | Filter and list |
+| `hafez search <terms> [--kind ...]` | FTS5 full-text search |
+| `hafez create <entity\|knowledge> <name> [flags]` | Create a document |
+| `hafez capture <name> [--notes]` | Quick inbox capture |
+| `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
+| `hafez update <slug> [flags]` | Status, brief, actions, session log, synthesis, evidence… |
+| `hafez link / unlink <slug> <target> --relation <parent\|related>` | Manage relationships |
+| `hafez batch [--dry-run]` | JSON ops on stdin → atomic multi-op, single git commit, rollback on failure |
+| `hafez stats` | Vault summary: counts, stale items, recents |
+| `hafez changelog --since 7.days.ago` | Git-derived change history |
+| `hafez sync` | Pull remote, push local commits (semantic merge on conflicts) |
+| `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
+| `hafez schema [op] [--examples]` | Machine-readable JSON schema for every operation |
+| `hafez export --okf [--out <dir>]` | Read-only OKF v0.1 bundle export |
+
+This is not exhaustive — `hafez help --agent` prints the full, always-current reference. Add `--json` to any command for structured output.
+
+## Library usage
+
+```typescript
+import { createHafez } from 'hafez'
+
+const os = createHafez({ vaultPath: '/path/to/vault' })
+
+const slug = await os.create('entity', 'New Project', {
+  type: 'project',
+  brief: 'Context here',
+  add_action: 'Start design',
+})
+
+await os.update(slug, { status: 'active', add_action: 'Write tests' })
+
+const { items } = await os.query({ filter: 'active', type: 'project' })
+const results = await os.search('auth pattern')
+const note = await os.read(slug, 'full')
+
+// Atomic multi-op — single git commit, rollback on failure
+await os.batch([
+  { op: 'update', slug, fields: { status: 'done' } },
+  { op: 'create', kind: 'knowledge', name: 'What we learned', fields: { domain: ['auth'] } },
+])
+```
+
+Writes are serialized through an internal mutex, so a single `Hafez` instance is safe to share.
+
+## Agent integration
+
+Hafez is built to be operated by agents:
+
+- **Claude Code skill** — the package bundles a skill (installed in [Setup](#setup)) covering the full session lifecycle: loading context at session start, vault ops mid-session, and a session-end digest.
+- **`hafez help --agent`** — a complete API reference designed to be loaded into an agent's context.
+- **`hafez schema <op> --examples`** — JSON schemas with working examples for every batch operation, so agents can self-correct.
+- **`hafez batch`** — apply a whole session's worth of updates atomically from a single JSON payload. Validation errors report every bad op at once with did-you-mean hints.
+- **Markdown-native output** by default, `--json` everywhere for machine consumption.
+
+## Vault discovery
+
+The CLI resolves the vault in order:
+
+1. `--vault <path>` flag (explicit, highest priority)
+2. `~/.config/hafez/vault` (or `$XDG_CONFIG_HOME/hafez/vault`) — a plain-text file containing the vault path, written by `hafez init --register`
+
+If the config points at a path that isn't a vault, the CLI errors loudly instead of silently falling through.
+
+## License
+
+MIT

package/dist/cli/batch-errors.d.ts

@@ -0,0 +1,24 @@
+import type { z } from 'zod';
+export declare function levenshtein(a: string, b: string): number;
+export declare function didYouMean(key: string, validKeys: readonly string[], maxDistance?: number): string | null;
+/**
+ * Given the raw op JSON, determine a display name for the schema pointer.
+ * For create ops, returns `create-<kind>` if kind is a valid literal, else `create`.
+ * For typos in `op` itself, returns null.
+ */
+export declare function opNameOf(raw: Record<string, unknown> | undefined): string | null;
+export interface FormattedError {
+    /** The block shown to the user — one issue, multi-line. */
+    block: string;
+}
+/**
+ * Format a single Zod issue into a readable block. Caller supplies the op
+ * index and the raw op JSON so the block can reference the right `hafez
+ * schema <op>` pointer.
+ */
+export declare function formatIssue(issue: z.ZodIssue, opIndex: number, raw: Record<string, unknown> | undefined): string;
+/**
+ * Top-level entry for a single op. Returns one composite block that concatenates
+ * every issue the safeParse returned, preserving all N issues (never drops).
+ */
+export declare function formatBatchError(issues: z.ZodIssue[], opIndex: number, raw: Record<string, unknown> | undefined): string;

package/dist/cli/batch-errors.js

@@ -0,0 +1,236 @@
+// src/cli/batch-errors.ts
+//
+// Multi-error batch formatter. Takes a Zod `safeParse` issue list for one op
+// index and returns a human-readable block keyed to the op + index, with a
+// "did you mean" suggestion on unknown keys and a `hafez schema <op>`
+// pointer at the end of every block.
+//
+// Depends on Phase 0 step 2 (discriminatedUnion) and step 3 (.strict()):
+// without those, the `unrecognized_keys` and `invalid_union_discriminator`
+// paths are unreachable.
+import { getOpSchema, listOps } from './schema-introspect.js';
+// --- did-you-mean (cheap Levenshtein) ---
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const prev = new Array(b.length + 1).fill(0).map((_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur.push(Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost));
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = cur[j];
+    }
+    return prev[b.length];
+}
+/**
+ * Known deprecated key names that don't match their canonical name by
+ * Levenshtein distance. Checked before the generic Levenshtein pass so
+ * `{"kind": "parent"}` on a link op maps to "relation" even though the
+ * edit distance is much larger than the threshold.
+ */
+const DEPRECATED_KEY_ALIASES = {
+    kind: 'relation',
+};
+export function didYouMean(key, validKeys, maxDistance = 3) {
+    // Manual alias pass first — covers rename history where the new and old
+    // names have no shared letters.
+    const manual = DEPRECATED_KEY_ALIASES[key];
+    if (manual && validKeys.includes(manual))
+        return manual;
+    let best = null;
+    for (const k of validKeys) {
+        const d = levenshtein(key, k);
+        if (d === 0)
+            continue;
+        if (d <= maxDistance && (!best || d < best.dist))
+            best = { key: k, dist: d };
+    }
+    return best ? best.key : null;
+}
+// --- Schema-key lookup for unrecognized_keys hints ---
+/**
+ * Collect the full set of valid keys at the level where `path` points. Used for
+ * did-you-mean across `unrecognized_keys` issues. `path` is the Zod issue path —
+ * typically something like `['fields']` or `[]` at the op level.
+ */
+function validKeysAtPath(opName, path) {
+    const opSchema = getOpSchema(opName);
+    if (!opSchema)
+        return [];
+    let cur = { type: 'object', fields: opSchema.fields, strict: true };
+    for (const seg of path) {
+        if (cur.type !== 'object' || !cur.fields)
+            return [];
+        const next = cur.fields[String(seg)];
+        if (!next)
+            return [];
+        cur = next;
+    }
+    if (cur.type === 'object' && cur.fields)
+        return Object.keys(cur.fields);
+    return [];
+}
+// --- Op-name resolution from an unknown input ---
+/**
+ * Given the raw op JSON, determine a display name for the schema pointer.
+ * For create ops, returns `create-<kind>` if kind is a valid literal, else `create`.
+ * For typos in `op` itself, returns null.
+ */
+export function opNameOf(raw) {
+    if (!raw)
+        return null;
+    const op = raw.op;
+    if (typeof op !== 'string')
+        return null;
+    if (op === 'create') {
+        const kind = raw.kind;
+        if (typeof kind === 'string')
+            return `create-${kind}`;
+        return 'create';
+    }
+    const known = new Set(listOps().map(o => o.op));
+    return known.has(op) ? op : null;
+}
+function formatPath(path) {
+    if (!path.length)
+        return '(root)';
+    return path.map(p => (typeof p === 'number' ? `[${p}]` : typeof p === 'symbol' ? p.toString() : p)).join('.');
+}
+function lookupByPath(obj, path) {
+    let cur = obj;
+    for (const p of path) {
+        if (cur == null)
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function toStr(v) {
+    if (typeof v === 'string')
+        return `"${v}"`;
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'undefined';
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+const VALID_OPS = ['update', 'create', 'capture', 'link', 'unlink', 'promote'];
+/**
+ * Format a single Zod issue into a readable block. Caller supplies the op
+ * index and the raw op JSON so the block can reference the right `hafez
+ * schema <op>` pointer.
+ */
+export function formatIssue(issue, opIndex, raw) {
+    const opDisplay = opNameOf(raw) ?? (typeof raw?.op === 'string' ? String(raw.op) : '?');
+    const pointerName = opNameOf(raw) ?? 'update'; // fallback pointer so the tip still renders
+    const fieldPath = formatPath(issue.path);
+    const tip = `tip: run \`hafez schema ${pointerName}\` for the full field list`;
+    const header = `[index ${opIndex}] op=${opDisplay}`;
+    const anyIssue = issue;
+    const code = anyIssue.code;
+    // Zod v4 emits `invalid_union` with a `discriminator` field when the
+    // discriminatedUnion can't match the discriminator value to a branch.
+    // For the outer `op` union this means "unknown op". For the inner create
+    // union this means "unknown kind".
+    if (code === 'invalid_union' && anyIssue.discriminator) {
+        const discriminator = anyIssue.discriminator;
+        if (discriminator === 'op') {
+            const got = typeof raw?.op === 'string' ? `"${raw.op}"` : toStr(raw?.op);
+            return [
+                header,
+                `  field: op`,
+                `  issue: unknown op ${got} (expected one of [${VALID_OPS.join(', ')}])`,
+                `  tip: run \`hafez schema\` for the op catalog`,
+            ].join('\n');
+        }
+        if (discriminator === 'kind') {
+            const got = typeof raw?.kind === 'string' ? `"${raw.kind}"` : toStr(raw?.kind);
+            return [
+                header,
+                `  field: kind`,
+                `  issue: unknown kind ${got} (expected one of [entity, knowledge, session])`,
+                `  ${tip}`,
+            ].join('\n');
+        }
+    }
+    if (code === 'unrecognized_keys') {
+        const keys = issue.keys;
+        const first = keys?.[0] ?? '<unknown>';
+        const stringPath = [];
+        for (const p of issue.path)
+            stringPath.push(typeof p === 'symbol' ? p.toString() : p);
+        const valid = validKeysAtPath(pointerName, stringPath);
+        const suggestion = didYouMean(first, valid);
+        const suggestText = suggestion ? ` (did you mean "${suggestion}"?)` : '';
+        return [
+            header,
+            `  field: ${first}${fieldPath === '(root)' ? '' : ` (under ${fieldPath})`}`,
+            `  issue: unknown field${suggestText}`,
+            ...(valid.length ? [`  allowed: ${valid.join(', ')}`] : []),
+            `  ${tip}`,
+        ].join('\n');
+    }
+    if (code === 'invalid_enum_value' || code === 'invalid_value') {
+        // Zod v3 uses `options`, Zod v4 uses `values`.
+        const expected = anyIssue.options ?? anyIssue.values;
+        // Zod v4 doesn't attach the received value to the issue, so walk the raw
+        // input by path to find it.
+        const received = anyIssue.received ?? anyIssue.input ?? lookupByPath(raw, issue.path);
+        return [
+            header,
+            `  field: ${fieldPath}`,
+            `  issue: invalid value`,
+            ...(expected ? [`  expected: one of [${expected.join(', ')}]`] : []),
+            `  got:      ${toStr(received)}`,
+            `  ${tip}`,
+        ].join('\n');
+    }
+    if (code === 'invalid_type') {
+        const expected = issue.expected;
+        const received = issue.received;
+        return [
+            header,
+            `  field: ${fieldPath}`,
+            `  issue: wrong type`,
+            `  expected: ${expected}`,
+            `  got:      ${received}`,
+            `  ${tip}`,
+        ].join('\n');
+    }
+    if (code === 'invalid_literal') {
+        const expected = issue.expected;
+        return [
+            header,
+            `  field: ${fieldPath}`,
+            `  issue: invalid literal`,
+            `  expected: ${toStr(expected)}`,
+            `  ${tip}`,
+        ].join('\n');
+    }
+    // Fallback — unknown issue code.
+    return [
+        header,
+        `  field: ${fieldPath}`,
+        `  issue: ${issue.message}`,
+        `  ${tip}`,
+    ].join('\n');
+}
+/**
+ * Top-level entry for a single op. Returns one composite block that concatenates
+ * every issue the safeParse returned, preserving all N issues (never drops).
+ */
+export function formatBatchError(issues, opIndex, raw) {
+    return issues.map(i => formatIssue(i, opIndex, raw)).join('\n');
+}

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

@@ -0,0 +1,3 @@
+import { getEnumValues } from './schema-introspect.js';
+export declare function cmdSchema(_os: unknown, args: string[]): Promise<string>;
+export { getEnumValues };

package/dist/cli/commands-schema.js

@@ -0,0 +1,80 @@
+// src/cli/commands-schema.ts
+//
+// `hafez schema` — machine-readable lookup surface. Three forms:
+//
+//   hafez schema                 # list every op
+//   hafez schema <op>            # full JSON schema for one op
+//   hafez schema <op> --examples # working JSON examples per enum value
+//
+// Output is JSON by default. All data is derived from schema-introspect.ts.
+// Unknown op names produce a did-you-mean error and exit non-zero.
+import { HafezError } from '../types.js';
+import { listOps, zodToJsonSchema, getOpExample, getEnumValues, getOpSchema, DIGEST_DESCRIPTION } from './schema-introspect.js';
+import { didYouMean } from './batch-errors.js';
+export async function cmdSchema(_os, args) {
+    // args come in already-stripped of global flags; first positional is the op name (if any)
+    const target = args[0];
+    const wantExamples = args.includes('--examples');
+    if (!target) {
+        // Form 1 — list ops. Digest is appended by hand: it is a stdin pipe, not
+        // a BatchOperationSchema branch, so listOps() deliberately excludes it.
+        const ops = listOps().map(o => ({ name: o.name, op: o.op, kind: o.kind, description: o.description }));
+        ops.push({ name: 'digest', op: 'digest', kind: undefined, description: DIGEST_DESCRIPTION });
+        return JSON.stringify({ ops }, null, 2);
+    }
+    // Form 2 / 3 — single op
+    const json = zodToJsonSchema(target);
+    if (!json) {
+        const names = [...listOps().map(o => o.name), 'digest'];
+        const suggestion = didYouMean(target, names);
+        const hint = suggestion ? ` (did you mean "${suggestion}"?)` : '';
+        throw new HafezError('VALIDATION_FAILED', `Unknown op: "${target}"${hint}`, [`Available ops: ${names.join(', ')}`]);
+    }
+    if (!wantExamples) {
+        return JSON.stringify(json, null, 2);
+    }
+    // Form 3 — include working examples, one per enum value on primary enums.
+    const examples = [];
+    const base = getOpExample(target);
+    if (base)
+        examples.push(base);
+    // Expand examples across each enum field in the op's fields tree.
+    const opSchema = getOpSchema(target);
+    if (opSchema && base) {
+        for (const [enumPath, enumValues] of enumFieldsOf(target, opSchema.fields)) {
+            // Skip literal fields (op, kind) — those are fixed for the branch.
+            if (enumPath === 'op' || enumPath === 'kind')
+                continue;
+            for (const v of enumValues) {
+                const variant = structuredClone(base);
+                setDottedValue(variant, enumPath, v);
+                examples.push(variant);
+            }
+        }
+    }
+    return JSON.stringify({ schema: json, examples }, null, 2);
+}
+function* enumFieldsOf(_opName, fields, prefix = []) {
+    for (const [k, f] of Object.entries(fields)) {
+        const path = [...prefix, k];
+        if (f.type === 'enum' && f.enum) {
+            yield [path.join('.'), f.enum];
+        }
+        else if (f.type === 'object' && f.fields) {
+            yield* enumFieldsOf(_opName, f.fields, path);
+        }
+    }
+}
+function setDottedValue(obj, path, value) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        if (cur[p] == null || typeof cur[p] !== 'object')
+            cur[p] = {};
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+// Re-export for consumers that want a direct enum lookup.
+export { getEnumValues };