hafez 1.0.1

package/dist/cli/resolve-vault.js

@@ -0,0 +1,124 @@
+// src/cli/resolve-vault.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+export function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    return join(xdg || join(homedir(), '.config'), 'hafez');
+}
+export function getConfigPath() {
+    return join(getConfigDir(), 'vault');
+}
+export function readVaultConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const content = readFileSync(configPath, 'utf-8').trim();
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveVaultConfig(vaultPath) {
+    const dir = getConfigDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'vault'), resolve(vaultPath) + '\n');
+}
+function isVault(dirPath) {
+    return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, 'entities'));
+}
+/**
+ * Resolve vault path. Returns string or null.
+ * If config exists but points to a bad path, returns an error object instead.
+ */
+export function resolveVaultPath(flagValue) {
+    // 1. Explicit flag
+    if (flagValue)
+        return flagValue;
+    // 2. Config file
+    const configValue = readVaultConfig();
+    if (configValue) {
+        if (isVault(configValue))
+            return configValue;
+        // Config exists but points to bad path — loud failure
+        return {
+            error: `Config (${getConfigPath()}) points to ${configValue} but it doesn't look like a vault.\nRun 'hafez init --register /correct/path' to fix.`,
+        };
+    }
+    return null;
+}
+export function noVaultMessage() {
+    const configPath = getConfigPath();
+    const configStatus = existsSync(configPath) ? 'path invalid' : 'no config file';
+    return `No vault found.
+
+Checked:
+  --vault flag            not provided
+  ${configPath}  ${configStatus}
+
+Get started:
+  hafez init --register /path/to/vault    Register an existing vault
+`;
+}
+export function cmdInit(args, flagValue) {
+    const registerIdx = args.indexOf('--register');
+    if (registerIdx !== -1) {
+        // hafez init --register <path>
+        const path = args[registerIdx + 1];
+        if (!path) {
+            process.stderr.write('Usage: hafez init --register <path>\n');
+            process.exit(1);
+        }
+        const abs = resolve(path);
+        if (!isVault(abs)) {
+            process.stderr.write(`Error: ${abs} does not exist or is not a vault (missing entities/ directory).\n`);
+            process.exit(1);
+        }
+        // Every vault write is a git commit — catch the two states that would
+        // otherwise make every later command fail with a raw git error.
+        if (!existsSync(join(abs, '.git'))) {
+            process.stderr.write(`Error: ${abs} is not a git repository — hafez uses git for history and sync.\n` +
+                `Set it up, then re-register:\n` +
+                `  cd ${abs} && git init && git commit --allow-empty -m "init vault"\n`);
+            process.exit(1);
+        }
+        let identityOk = false;
+        try {
+            const email = execSync('git config user.email', { cwd: abs, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+            const name = execSync('git config user.name', { cwd: abs, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+            identityOk = email.length > 0 && name.length > 0;
+        }
+        catch { /* unset config exits non-zero */ }
+        if (!identityOk) {
+            process.stderr.write(`Error: git has no identity configured — every vault write is a git commit.\n` +
+                `Fix (one-time), then re-register:\n` +
+                `  git config --global user.name "Your Name"\n` +
+                `  git config --global user.email "you@example.com"\n`);
+            process.exit(1);
+        }
+        saveVaultConfig(abs);
+        process.stdout.write(`Registered vault: ${abs}\n`);
+        return;
+    }
+    // Bare `hafez init` — show current resolution status
+    if (flagValue) {
+        process.stdout.write(`Vault: ${flagValue} (--vault flag)\n`);
+        return;
+    }
+    const configValue = readVaultConfig();
+    if (configValue) {
+        if (isVault(configValue)) {
+            process.stdout.write(`Vault: ${configValue} (config: ${getConfigPath()})\n`);
+        }
+        else {
+            process.stderr.write(`Config (${getConfigPath()}) points to ${configValue} but it doesn't look like a vault.\nRun 'hafez init --register /correct/path' to fix.\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    process.stderr.write(noVaultMessage());
+    process.exit(1);
+}

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

@@ -0,0 +1,70 @@
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema } from './commands.js';
+export interface FieldSchema {
+    type: string;
+    optional?: boolean;
+    nullable?: boolean;
+    enum?: readonly string[];
+    literal?: unknown;
+    items?: FieldSchema;
+    fields?: Record<string, FieldSchema>;
+    description?: string;
+    strict?: boolean;
+}
+export interface OpSchema {
+    op: string;
+    /** For create: kind name (entity | knowledge | session). Undefined for others. */
+    kind?: string;
+    /** Top-level required/optional fields for the op body. */
+    fields: Record<string, FieldSchema>;
+    strict: boolean;
+    description?: string;
+}
+/**
+ * List every op in canonical order. `create` is one entry per kind — so the
+ * list has 8 entries, not 6. Each entry carries the display name the help
+ * renderer uses in the op catalog.
+ */
+export interface OpCatalogEntry {
+    op: string;
+    kind?: string;
+    /** Stable identifier used by `schema <name>`. `create-entity` / `update` / `link`. */
+    name: string;
+    description: string;
+}
+export declare const DIGEST_DESCRIPTION = "Convert session-context JSON (stdin) into a batch payload. Not a batch op \u2014 pipe: echo '<json>' | hafez digest | hafez batch";
+/** Canonical digest input example. The drift test asserts it parses against
+ * DigestInputSchema, so it cannot silently diverge from the schema. */
+export declare const DIGEST_EXAMPLE: Record<string, unknown>;
+export declare function listOps(): OpCatalogEntry[];
+/** Return the full introspected schema for a single op, by `name`. */
+export declare function getOpSchema(name: string): OpSchema | null;
+/**
+ * Look up an enum's values by dotted path. Supported paths include:
+ *   - 'update.fields.status'
+ *   - 'update.fields.confidence'
+ *   - 'update.fields.session_log.type'
+ *   - 'create-entity.fields.type'
+ *   - 'create-knowledge.fields.subtype'
+ *   - 'link.relation'
+ *
+ * Returns `null` if the path does not resolve to an enum field.
+ */
+export declare function getEnumValues(path: string): readonly string[] | null;
+/**
+ * Build a minimal, valid-looking example payload for an op. Uses the first
+ * enum value for enums, "<slug>"/"<name>"/"text" placeholders for strings,
+ * 0 for numbers, empty arrays for arrays, and recurses for nested objects.
+ * Optional fields are skipped unless they are the only way to make the
+ * example illustrative (op / kind literals are always emitted).
+ *
+ * Aliased keys (per contracts.ts ALIAS_KEYS) are stripped from the output
+ * so only canonical names appear in rendered help.
+ */
+export declare function getOpExample(name: string): Record<string, unknown> | null;
+/**
+ * Flatten an OpSchema to a JSON-schema-shaped plain object for the
+ * `hafez schema <op>` command. Not full draft-7 — just a readable
+ * structure agents can parse.
+ */
+export declare function zodToJsonSchema(name: string): Record<string, unknown> | null;
+export { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema };

package/dist/cli/schema-introspect.js

@@ -0,0 +1,372 @@
+// src/cli/schema-introspect.ts
+//
+// Single introspection surface that `help --agent`, `schema <op>`, and error
+// formatters all read from. Walks the Zod v4 `BatchOperationSchema` tree to
+// produce plain objects describing ops, fields, enums, and example payloads.
+// The digest stdin pipe is introspected too (special-cased — it is not a
+// batch op and stays out of listOps()).
+//
+// Hand-rolled walker (no zod-to-json-schema dependency). Supports the node
+// types actually used in BatchOperationSchema plus a few forward-looking ones
+// (`default`, `effects`, `union`) so the walker does not explode when the
+// schema is extended.
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema, } from './commands.js';
+import { DigestInputSchema } from '../digest.js';
+import { ALIAS_KEYS } from '../contracts.js';
+// --- Walker ---
+/** Unwrap optional/nullable/default wrappers and mark the metadata on the result. */
+function walk(node) {
+    if (!node)
+        return { type: 'unknown' };
+    const def = node._def;
+    if (!def)
+        return { type: 'unknown' };
+    const type = def.type;
+    // Zod v4 stores .describe() text on the schema's registry-backed
+    // `description` getter, not on _def — read both, _def first for
+    // forward-compatibility.
+    const description = def.description ?? node.description;
+    // Wrapper types — unwrap and annotate. A .describe() applied after the
+    // wrapper lands on the wrapper node, so carry it down to the inner schema.
+    if (type === 'optional') {
+        const inner = walk(def.innerType);
+        inner.optional = true;
+        inner.description ??= description;
+        return inner;
+    }
+    if (type === 'nullable') {
+        const inner = walk(def.innerType);
+        inner.nullable = true;
+        inner.description ??= description;
+        return inner;
+    }
+    if (type === 'default') {
+        const inner = walk(def.innerType);
+        inner.optional = true;
+        inner.description ??= description;
+        return inner;
+    }
+    if (type === 'pipe' || type === 'effects' || type === 'transform' || type === 'readonly') {
+        // Zod effects / transforms / pipes — descend to the inner schema.
+        const inner = def.in ?? def.schema ?? def.innerType;
+        if (inner)
+            return walk(inner);
+    }
+    // Leaf / container types.
+    if (type === 'string')
+        return { type: 'string', description };
+    if (type === 'number')
+        return { type: 'number', description };
+    if (type === 'boolean')
+        return { type: 'boolean', description };
+    if (type === 'null')
+        return { type: 'null' };
+    if (type === 'any' || type === 'unknown')
+        return { type: 'unknown' };
+    if (type === 'literal') {
+        const values = def.values;
+        const literal = Array.isArray(values) ? values[0] : def.value;
+        return { type: 'literal', literal };
+    }
+    if (type === 'enum') {
+        const entries = def.entries;
+        const values = entries && typeof entries === 'object'
+            ? Object.values(entries)
+            : (Array.isArray(def.values) ? def.values : []);
+        return { type: 'enum', enum: values, description };
+    }
+    if (type === 'array') {
+        const element = def.element ?? def.type;
+        return { type: 'array', items: walk(element), description };
+    }
+    if (type === 'object') {
+        const rawShape = def.shape;
+        const shape = typeof rawShape === 'function' ? rawShape() : rawShape ?? {};
+        const fields = {};
+        for (const [k, v] of Object.entries(shape))
+            fields[k] = walk(v);
+        // Zod v4: strict objects use a catchall that throws on extra keys. For our
+        // purposes we flag every object we emit as strict (we opt in explicitly on
+        // all BatchOperationSchema objects) — the plan's error surface depends on it.
+        return { type: 'object', fields, strict: true, description };
+    }
+    if (type === 'union') {
+        // A plain z.union is uncommon in the current schema but possible. Return
+        // the first option as a representative. The error formatter has specific
+        // handling for union discriminators; introspection just needs shape.
+        const first = def.options?.[0];
+        if (first)
+            return walk(first);
+        return { type: 'unknown' };
+    }
+    return { type: 'unknown' };
+}
+// --- Branch discovery for the top-level schema ---
+function topOptions() {
+    return BatchOperationSchema._def.options ?? [];
+}
+function shapeOf(obj) {
+    const rawShape = obj?._def?.shape;
+    return typeof rawShape === 'function' ? rawShape() : rawShape ?? {};
+}
+function literalOf(schema) {
+    const vs = schema?._def?.values;
+    return Array.isArray(vs) ? vs[0] : schema?._def?.value;
+}
+function unwrapOptional(s) {
+    let cur = s;
+    while (cur?._def?.type === 'optional' || cur?._def?.type === 'nullable')
+        cur = cur._def.innerType;
+    return cur;
+}
+function enumerateBranches() {
+    const out = [];
+    for (const opt of topOptions()) {
+        if (opt?._def?.type === 'object') {
+            const shape = shapeOf(opt);
+            const op = literalOf(shape.op);
+            out.push({ op, branch: opt });
+        }
+        else if (opt?._def?.type === 'union') {
+            for (const inner of opt._def.options ?? []) {
+                const shape = shapeOf(inner);
+                const op = literalOf(shape.op);
+                const kind = literalOf(shape.kind);
+                out.push({ op, kind, branch: inner });
+            }
+        }
+    }
+    return out;
+}
+// --- Digest (stdin pipe, NOT a batch op) ---
+//
+// `hafez digest` reads its own JSON from stdin and prints a batch payload:
+//   echo '<digest-json>' | hafez digest | hafez batch
+// It is deliberately excluded from listOps() so the op catalog and batch
+// examples never imply {"op":"digest"} is valid batch JSON. It still gets
+// `hafez schema digest` via the special cases below.
+export const DIGEST_DESCRIPTION = 'Convert session-context JSON (stdin) into a batch payload. Not a batch op — pipe: echo \'<json>\' | hafez digest | hafez batch';
+/** Canonical digest input example. The drift test asserts it parses against
+ * DigestInputSchema, so it cannot silently diverge from the schema. */
+export const DIGEST_EXAMPLE = {
+    entities_touched: ['slug-1', 'slug-2'],
+    decisions: ['Decision made'],
+    narrative: 'One to three sentence cross-cutting summary.',
+    session_date: '2026-01-15',
+    agent: 'claude',
+};
+const OP_DESCRIPTIONS = {
+    'update': 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …).',
+    'create-entity': 'Create a new entity (capture / entity / project).',
+    'create-knowledge': 'Create a new knowledge note (insight / plan subtype).',
+    'create-session': 'Create a new session note linked to an entity.',
+    'capture': 'Quick capture — a raw inbox item with no structure required.',
+    'link': 'Add a parent or related link between two entities.',
+    'unlink': 'Remove a parent or related link between two entities.',
+    'promote': 'Promote a capture to entity/project/knowledge, or an entity to project.',
+};
+export function listOps() {
+    return enumerateBranches().map(({ op, kind }) => {
+        const name = kind ? `${op}-${kind}` : op;
+        return { op, kind, name, description: OP_DESCRIPTIONS[name] ?? '' };
+    });
+}
+/** Return the full introspected schema for a single op, by `name`. */
+export function getOpSchema(name) {
+    if (name === 'digest') {
+        const root = walk(DigestInputSchema);
+        return {
+            op: 'digest',
+            fields: root.fields ?? {},
+            strict: false,
+            description: DIGEST_DESCRIPTION,
+        };
+    }
+    for (const { op, kind, branch } of enumerateBranches()) {
+        const n = kind ? `${op}-${kind}` : op;
+        if (n !== name)
+            continue;
+        const shape = shapeOf(branch);
+        const fields = {};
+        for (const [k, v] of Object.entries(shape))
+            fields[k] = walk(v);
+        return {
+            op,
+            kind,
+            fields,
+            strict: true,
+            description: OP_DESCRIPTIONS[n],
+        };
+    }
+    return null;
+}
+/**
+ * Look up an enum's values by dotted path. Supported paths include:
+ *   - 'update.fields.status'
+ *   - 'update.fields.confidence'
+ *   - 'update.fields.session_log.type'
+ *   - 'create-entity.fields.type'
+ *   - 'create-knowledge.fields.subtype'
+ *   - 'link.relation'
+ *
+ * Returns `null` if the path does not resolve to an enum field.
+ */
+export function getEnumValues(path) {
+    const parts = path.split('.');
+    const opName = parts.shift();
+    if (!opName)
+        return null;
+    const opSchema = getOpSchema(opName);
+    if (!opSchema)
+        return null;
+    let cur = { type: 'object', fields: opSchema.fields, strict: true };
+    for (const part of parts) {
+        if (!cur || cur.type !== 'object' || !cur.fields)
+            return null;
+        cur = cur.fields[part];
+    }
+    if (!cur)
+        return null;
+    if (cur.type === 'enum' && cur.enum)
+        return cur.enum;
+    return null;
+}
+/**
+ * Build a minimal, valid-looking example payload for an op. Uses the first
+ * enum value for enums, "<slug>"/"<name>"/"text" placeholders for strings,
+ * 0 for numbers, empty arrays for arrays, and recurses for nested objects.
+ * Optional fields are skipped unless they are the only way to make the
+ * example illustrative (op / kind literals are always emitted).
+ *
+ * Aliased keys (per contracts.ts ALIAS_KEYS) are stripped from the output
+ * so only canonical names appear in rendered help.
+ */
+export function getOpExample(name) {
+    if (name === 'digest')
+        return structuredClone(DIGEST_EXAMPLE);
+    const opSchema = getOpSchema(name);
+    if (!opSchema)
+        return null;
+    const opPath = name; // 'update' | 'create-entity' | ...
+    const out = {};
+    for (const [k, field] of Object.entries(opSchema.fields)) {
+        const fullPath = `${opPath === 'update' ? 'update' : opPath}.${k}`;
+        if (shouldStrip(fullPath, k))
+            continue;
+        if (k === 'fields') {
+            if (field.type === 'object' && field.fields) {
+                const inner = {};
+                for (const [fk, ff] of Object.entries(field.fields)) {
+                    const fp = aliasPathFor(opSchema.op, opSchema.kind, fk);
+                    if (shouldStrip(fp, fk))
+                        continue;
+                    // Skip most optional fields for minimalism, but always include the
+                    // primary discriminator-like fields (type for create-entity,
+                    // subtype for create-knowledge).
+                    const keepOptional = isDefaultIncluded(opSchema.op, opSchema.kind, fk);
+                    if (ff.optional && !keepOptional)
+                        continue;
+                    inner[fk] = sampleValue(ff);
+                }
+                out[k] = inner;
+            }
+            continue;
+        }
+        if (field.type === 'literal') {
+            out[k] = field.literal;
+            continue;
+        }
+        if (!field.optional) {
+            out[k] = sampleValue(field);
+        }
+    }
+    return out;
+}
+function aliasPathFor(op, kind, fieldKey) {
+    if (op === 'update')
+        return `update.fields.${fieldKey}`;
+    if (op === 'create' && kind)
+        return `create.${kind}.fields.${fieldKey}`;
+    return `${op}.${fieldKey}`;
+}
+function shouldStrip(path, _key) {
+    return Object.prototype.hasOwnProperty.call(ALIAS_KEYS, path);
+}
+function isDefaultIncluded(op, kind, fieldKey) {
+    if (op === 'create' && kind === 'entity' && fieldKey === 'type')
+        return true;
+    if (op === 'create' && kind === 'knowledge' && (fieldKey === 'subtype' || fieldKey === 'synthesis'))
+        return true;
+    if (op === 'create' && kind === 'session' && fieldKey === 'synthesis')
+        return true;
+    if (op === 'update' && fieldKey === 'status')
+        return true;
+    if (op === 'capture' && fieldKey === 'notes')
+        return true;
+    return false;
+}
+function sampleValue(field) {
+    switch (field.type) {
+        case 'string': return 'text';
+        case 'number': return 0;
+        case 'boolean': return true;
+        case 'null': return null;
+        case 'literal': return field.literal;
+        case 'enum': return field.enum?.[0] ?? 'value';
+        case 'array': return field.items ? [sampleValue(field.items)] : [];
+        case 'object': {
+            const o = {};
+            if (field.fields) {
+                for (const [k, f] of Object.entries(field.fields)) {
+                    if (f.optional)
+                        continue;
+                    o[k] = sampleValue(f);
+                }
+            }
+            return o;
+        }
+        default: return null;
+    }
+}
+/**
+ * Flatten an OpSchema to a JSON-schema-shaped plain object for the
+ * `hafez schema <op>` command. Not full draft-7 — just a readable
+ * structure agents can parse.
+ */
+export function zodToJsonSchema(name) {
+    const opSchema = getOpSchema(name);
+    if (!opSchema)
+        return null;
+    return {
+        op: opSchema.op,
+        kind: opSchema.kind,
+        description: opSchema.description,
+        fields: fieldsToJson(opSchema.fields),
+    };
+}
+function fieldsToJson(fields) {
+    const out = {};
+    for (const [k, f] of Object.entries(fields))
+        out[k] = fieldToJson(f);
+    return out;
+}
+function fieldToJson(f) {
+    const j = { type: f.type };
+    if (f.optional)
+        j.optional = true;
+    if (f.nullable)
+        j.nullable = true;
+    if (f.enum)
+        j.enum = f.enum;
+    if (f.literal !== undefined)
+        j.literal = f.literal;
+    if (f.description)
+        j.description = f.description;
+    if (f.type === 'array' && f.items)
+        j.items = fieldToJson(f.items);
+    if (f.type === 'object' && f.fields)
+        j.fields = fieldsToJson(f.fields);
+    return j;
+}
+// Small re-exports so callers don't need to import from multiple places.
+export { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema };

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './cli/index.js';
+main(process.argv);

package/dist/contracts.d.ts

@@ -0,0 +1,26 @@
+export interface TypeContract {
+    type: string;
+    description: string;
+    kind: 'item' | 'knowledge';
+    requiredFields: string[];
+    optionalFields: string[];
+    validStatuses: string[];
+    defaultSections: string[];
+    optionalSections: string[];
+    canPromoteTo: string[];
+}
+export declare const ALL_CONTRACTS: TypeContract[];
+export declare function getContract(type: string): TypeContract;
+export declare function hasCapability(type: string, section: string): boolean;
+import type { KnowledgeSubtype } from './types.js';
+export declare const ENTITY_TYPES: readonly ["capture", "entity", "project"];
+export declare const ENTITY_STATUSES: readonly ["active", "paused", "done"];
+export declare const SESSION_LOG_TYPES: readonly ["progress", "decision", "blocker", "research"];
+export declare const CONFIDENCE_LEVELS: readonly ["observation", "pattern", "principle"];
+export declare const VALID_SUBTYPES: readonly ["insight", "plan"];
+export declare const ALIAS_KEYS: {
+    readonly 'update.fields.insight': "synthesis";
+    readonly 'create.knowledge.fields.insight': "synthesis";
+    readonly 'create.session.fields.insight': "synthesis";
+};
+export declare const SUBTYPE_SECTIONS: Record<KnowledgeSubtype, string[]>;