hafez 1.2.0 → 1.4.0

package/dist/batch-ops.js

@@ -0,0 +1,446 @@
+// src/batch-ops.ts
+// The Op Spec (see CONTEXT.md): one table defining every batch operation —
+// shape (Zod), semantic check, description, and example hints — from which
+// validation, error text, and schema introspection all derive. Adding an op
+// means one entry here plus one arm in the Apply table (src/apply.ts), which
+// the compiler enforces: the arm table is keyed by this table's names.
+//
+// Every semantic gate lives here and runs exactly once, in the validate phase.
+// Apply assumes the payload it receives passed these checks.
+import { z } from 'zod';
+import { ALIAS_KEYS, ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, PLAN_STATUSES, getContract, } from './contracts.js';
+import { slugify } from './vault.js';
+import { HafezError } from './types.js';
+// --- Shapes ---
+// All enums are built from contracts.ts tuples so help-renderer, file validators,
+// and CLI-input validator share a single source of truth.
+// Every z.object(...) is .strict() — unknown keys become `unrecognized_keys` issues
+// (not silently dropped), which is load-bearing for the error-formatter's did-you-mean
+// hints and for catching typos like `{"kind": "parent"}` on a link op.
+export const SessionLogSchema = z.object({
+    type: z.enum([...SESSION_LOG_TYPES]),
+    summary: z.string(),
+    body: z.string().optional(),
+    agent: z.string(),
+}).strict();
+// Body-section text must have text after trimming. An empty or whitespace-only
+// value (an agent expanding an unset variable) used to sail through the shape —
+// on the action/evidence fields it was dropped by a truthiness guard in apply
+// (exit 0, nothing on disk); on the section-setting fields below it was worse,
+// because apply trusts the validate phase and `setSection(body, 'Synthesis',
+// '')` wipes what was already there. Same false-success class the CLI loop
+// closed for the enum flags, once silent and once destructive.
+//
+// The rule: every non-nullable string field that writes body-section text is
+// nonEmptyText. The nullable ones (update's brief/description/resource) are
+// excluded by construction — null is their documented clear signal, and the
+// CLI maps `--brief ""` to it. Trimming also keeps accidental padding out of
+// stored text.
+const nonEmptyText = z.string().trim().min(1, 'must contain text — an empty value is rejected, never silently dropped');
+export const UpdateFieldsSchema = z.object({
+    status: z.enum([...ENTITY_STATUSES]).optional(),
+    current_state: nonEmptyText.optional(),
+    session_log: SessionLogSchema.optional(),
+    brief: z.string().nullable().optional(),
+    add_action: nonEmptyText.optional(),
+    add_actions: z.array(nonEmptyText).optional(),
+    complete_action: nonEmptyText.optional(),
+    remove_action: nonEmptyText.optional(),
+    clear_actions: z.boolean().optional(),
+    // Knowledge metadata
+    description: z.string().nullable().optional(),
+    resource: z.string().nullable().optional(),
+    domain: z.array(z.string()).optional(),
+    confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
+    tags: z.array(z.string()).optional(),
+    related: z.array(z.string()).optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(), // alias for synthesis (normalized by normalizeAliases)
+    add_evidence: nonEmptyText.optional(),
+    add_source: nonEmptyText.optional(),
+}).strict();
+export const CreateEntityFieldsSchema = z.object({
+    type: z.enum([...ENTITY_TYPES]),
+    purpose: nonEmptyText.optional(),
+    description: z.string().optional(),
+    resource: z.string().optional(),
+    domain: z.array(z.string()).optional(),
+    parent: z.string().optional(),
+    related: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    brief: nonEmptyText.optional(),
+    add_action: nonEmptyText.optional(),
+    add_actions: z.array(nonEmptyText).optional(),
+}).strict();
+export const CreateKnowledgeFieldsSchema = z.object({
+    subtype: z.enum([...VALID_SUBTYPES]).optional(),
+    // Plan-only: insights have no lifecycle, so the semantic check rejects
+    // status on any other subtype (the shape only pins the allowed values).
+    status: z.enum([...PLAN_STATUSES]).optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
+    description: z.string().optional(),
+    domain: z.array(z.string()).optional(),
+    related: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    'session-date': z.string().optional(),
+}).strict();
+export const CreateSessionFieldsSchema = z.object({
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
+    related: z.array(z.string()).optional(),
+    'session-date': z.string().optional(),
+}).strict();
+const CreateEntityBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('entity'),
+    name: z.string(),
+    fields: CreateEntityFieldsSchema,
+}).strict();
+const CreateKnowledgeBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('knowledge'),
+    name: z.string(),
+    fields: CreateKnowledgeFieldsSchema.optional(),
+}).strict();
+const CreateSessionBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('session'),
+    name: z.string(),
+    fields: CreateSessionFieldsSchema.optional(),
+}).strict();
+const UpdateBranch = z.object({
+    op: z.literal('update'),
+    slug: z.string(),
+    fields: UpdateFieldsSchema,
+}).strict();
+const CaptureBranch = z.object({
+    op: z.literal('capture'),
+    name: z.string(),
+    notes: z.string().optional(),
+}).strict();
+const LinkBranch = z.object({
+    op: z.literal('link'),
+    slug: z.string(),
+    target: z.string(),
+    relation: z.enum(['parent', 'related']),
+}).strict();
+const UnlinkBranch = z.object({
+    op: z.literal('unlink'),
+    slug: z.string(),
+    target: z.string(),
+    relation: z.enum(['parent', 'related']),
+}).strict();
+const PromoteBranch = z.object({
+    op: z.literal('promote'),
+    slug: z.string(),
+    target: z.enum(['entity', 'project', 'knowledge']),
+}).strict();
+// Nested discriminated union: outer on `op`, inner on `kind` for create branch.
+// A flat `discriminatedUnion('op', [...])` cannot work because three branches share
+// op=create — Zod requires unique discriminator values per branch and throws at
+// schema construction time if violated.
+const CreateBranch = z.discriminatedUnion('kind', [
+    CreateEntityBranch,
+    CreateKnowledgeBranch,
+    CreateSessionBranch,
+]);
+export const BatchOperationSchema = z.discriminatedUnion('op', [
+    UpdateBranch,
+    // create is a nested discriminatedUnion on `kind` — see CreateBranch above.
+    // discriminatedUnion accepts a ZodDiscriminatedUnion as a branch via option-flattening.
+    CreateBranch,
+    CaptureBranch,
+    LinkBranch,
+    UnlinkBranch,
+    PromoteBranch,
+]);
+// --- Alias normalization ---
+// The one place a declared alias (contracts.ts ALIAS_KEYS) becomes its canonical
+// field. It runs before validation, so validate and apply both see the canonical
+// op on every entry point — library create/update/batch and CLI batch input
+// alike. Normalizing anywhere else is what made the alias a silent drop: the
+// strict shapes accepted `insight`, nothing rewrote it, and the apply step (which
+// only reads `synthesis`) wrote an empty Synthesis section and reported ok.
+/** ALIAS_KEYS re-keyed by op path prefix: 'update.fields' → [[alias, canonical]]. */
+const ALIASES_BY_PATH = new Map();
+for (const [path, canonical] of Object.entries(ALIAS_KEYS)) {
+    const cut = path.lastIndexOf('.');
+    const prefix = path.slice(0, cut);
+    const list = ALIASES_BY_PATH.get(prefix) ?? [];
+    list.push([path.slice(cut + 1), canonical]);
+    ALIASES_BY_PATH.set(prefix, list);
+}
+/** Canonicalize an operation's declared aliases.
+ *
+ * Precedence when both are present: the canonical field wins and the alias is
+ * dropped. Never mutates the caller's object — an op carrying no alias is
+ * returned as-is. */
+export function normalizeAliases(op) {
+    const o = op;
+    if (!o || typeof o !== 'object' || !o.fields || typeof o.fields !== 'object')
+        return op;
+    const prefix = `${String(o.op)}${o.kind === undefined ? '' : `.${String(o.kind)}`}.fields`;
+    const aliases = ALIASES_BY_PATH.get(prefix);
+    if (!aliases)
+        return op;
+    let fields;
+    for (const [alias, canonical] of aliases) {
+        if (o.fields[alias] === undefined)
+            continue;
+        fields ??= { ...o.fields };
+        if (fields[canonical] === undefined)
+            fields[canonical] = fields[alias];
+        delete fields[alias];
+    }
+    return fields ? { ...o, fields } : op;
+}
+/** normalizeAliases over a payload — the form the Spine and dry-run use. */
+export function normalizeOperations(operations) {
+    return operations.map(op => normalizeAliases(op));
+}
+function pushErr(errors, err) {
+    const e = err;
+    errors.push(e.details?.length ? `${e.message}: ${e.details.join('; ')}` : e.message);
+}
+/** The one source of the missing-slug error text — specs and the Spine's
+ * shape-failure precedence rule (validateBatchCore) must not drift apart. */
+export function notFoundError(slug) {
+    return `'${slug}' not found`;
+}
+/** The one op-error line format. Every surface that localises an error to its
+ * op — the validate phase's error list, apply's execution-time failures, and
+ * the CLI's dry-run report — renders it through here, so an agent parsing
+ * `op[i] (op slug): …` sees one shape whichever surface produced it. */
+export function opErrorLine(index, op, slug, message) {
+    return `op[${index}] (${op} ${slug}): ${message}`;
+}
+/** The one "the batch was rejected, nothing landed" header — shared by the
+ * library's validate gate and the CLI's shape-parse gate, which reject the
+ * same payload at different depths and must say so identically. `batch
+ * --dry-run` deliberately words its own header differently: it reports a
+ * hypothetical ("would be applied"), not a refusal. */
+export function batchInvalidHeader(invalidCount, total) {
+    return `Batch failed validation: ${invalidCount} invalid operation${invalidCount === 1 ? '' : 's'} (0 of ${total} applied)`;
+}
+/** The one source of the duplicate-session disposition text. A duplicate
+ * session is not an error — the op is skipped and the batch continues — and
+ * dry-run (spec warning) and apply (BatchResult.warning) report it with this
+ * same sentence so the two can never drift. */
+export function duplicateSessionWarning(slug) {
+    return `session '${slug}' already exists — op skipped (batch continues)`;
+}
+/** The create-style gate, in one place so the invariant can't be re-broken:
+ * a taken slug is a SLUG_EXISTS error and must NOT be simulated (simulating
+ * over an existing slug shadows the real file's kind for later ops in the
+ * 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);
+    if (taken)
+        errors.push(`Slug '${slug}' already exists`);
+    if (build) {
+        try {
+            build();
+        }
+        catch (err) {
+            pushErr(errors, err);
+        }
+    }
+    if (!taken)
+        ctx.simulate(slug, info);
+    return taken ? 'SLUG_EXISTS' : undefined;
+}
+// `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
+// the interface, so consumers still read optional fields (`kind`) off them.
+const OP_SPEC_ROWS = [
+    {
+        name: 'update',
+        op: 'update',
+        schema: UpdateBranch,
+        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
+        exampleInclude: ['status'],
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            const target = ctx.resolve(op.slug);
+            if (!target) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            else {
+                try {
+                    ctx.validateKindFields(target.kind, op.fields, target.subtype);
+                }
+                catch (err) {
+                    pushErr(errors, err);
+                }
+            }
+            if (op.fields.session_log) {
+                const logErrors = ctx.validateSessionLogEntry(op.fields.session_log);
+                if (logErrors.length > 0)
+                    errors.push(`Invalid session log entry: ${logErrors.join('; ')}`);
+            }
+            if (op.fields.related) {
+                for (const r of op.fields.related) {
+                    if (!ctx.existsAnywhere(r))
+                        errors.push(`Related slug '${r}' does not exist`);
+                }
+            }
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
+    {
+        name: 'create-entity',
+        op: 'create',
+        kind: 'entity',
+        schema: CreateEntityBranch,
+        description: 'Create a new entity (capture / entity / project). A field whose section the chosen type lacks is rejected, never dropped — `purpose` needs type project.',
+        exampleInclude: ['type'],
+        check(op, ctx) {
+            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));
+            return { slug, errors, created: errors.length === 0, primaryCode };
+        },
+    },
+    {
+        name: 'create-knowledge',
+        op: 'create',
+        kind: 'knowledge',
+        schema: CreateKnowledgeBranch,
+        description: 'Create a new knowledge note (insight / plan subtype). `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.',
+        exampleInclude: ['subtype', 'synthesis'],
+        check(op, ctx) {
+            const errors = [];
+            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 || {})));
+            return { slug, errors, created: errors.length === 0, primaryCode };
+        },
+    },
+    {
+        name: 'create-session',
+        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).',
+        exampleInclude: ['synthesis'],
+        check(op, ctx) {
+            const slug = slugify(op.name);
+            if (ctx.existsAnywhere(slug) || ctx.sessionExists(slug)) {
+                return { slug, errors: [], warning: duplicateSessionWarning(slug) };
+            }
+            ctx.simulateSession(slug);
+            return { slug, errors: [], created: true };
+        },
+    },
+    {
+        name: 'capture',
+        op: 'capture',
+        schema: CaptureBranch,
+        description: 'Quick capture — a raw inbox item with no structure required.',
+        exampleInclude: ['notes'],
+        check(op, ctx) {
+            const errors = [];
+            const slug = slugify(op.name);
+            const primaryCode = claimNew(ctx, errors, slug, { kind: 'entity', type: 'capture' });
+            return { slug, errors, created: errors.length === 0, primaryCode };
+        },
+    },
+    {
+        name: 'link',
+        op: 'link',
+        schema: LinkBranch,
+        description: 'Add a parent or related link between two entities.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            if (!ctx.resolve(op.slug)) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            if (!ctx.existsAnywhere(op.target))
+                errors.push(`Target '${op.target}' does not exist`);
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
+    {
+        name: 'unlink',
+        op: 'unlink',
+        schema: UnlinkBranch,
+        description: 'Remove a parent or related link between two entities.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            if (!ctx.resolve(op.slug)) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
+    {
+        name: 'promote',
+        op: 'promote',
+        schema: PromoteBranch,
+        description: 'Promote a capture to entity/project/knowledge, or an entity to project.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            const cur = ctx.resolve(op.slug);
+            if (!cur) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            else {
+                const currentType = cur.kind === 'knowledge' ? 'knowledge' : cur.type;
+                try {
+                    const contract = getContract(currentType);
+                    if (!contract.canPromoteTo.includes(op.target)) {
+                        errors.push(`Cannot promote ${currentType} to ${op.target}. Valid targets: ${contract.canPromoteTo.join(', ') || 'none (terminal type)'}`);
+                    }
+                    else {
+                        ctx.simulate(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
+                    }
+                }
+                catch (err) {
+                    pushErr(errors, err);
+                }
+            }
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
+];
+export const OP_SPECS = OP_SPEC_ROWS;
+/** Find the spec for a (shape-valid) operation. */
+export function specFor(op) {
+    const spec = OP_SPECS.find(s => s.op === op.op && (s.kind === undefined || s.kind === op.kind));
+    if (!spec)
+        throw new HafezError('VALIDATION_FAILED', `Unknown batch op: ${op.op}`);
+    return spec;
+}
+/** Op names for error text ("expected one of […]") — derived, never hardcoded. */
+export function validOpNames() {
+    return [...new Set(OP_SPECS.map(s => s.op))];
+}
+/** Ops whose payload addresses an existing file by `slug` — derived from the
+ * Zod shapes, so a new slug-bearing op picks up slug-level rules (the
+ * NOT_FOUND precedence on shape failure in validateBatchCore) without a
+ * hand-kept list. */
+export function slugBearingOpNames() {
+    return [...new Set(OP_SPECS
+            .filter(s => {
+            const shape = s.schema.shape;
+            return shape !== undefined && 'slug' in shape;
+        })
+            .map(s => s.op))];
+}
+/** Create kinds for error text — derived from the table. */
+export function validCreateKinds() {
+    return OP_SPECS.filter(s => s.op === 'create' && s.kind).map(s => s.kind);
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,19 @@
+/** Bad invocation (unknown flag, missing value, missing positional).
+ * Distinct from crashes: the error adapter maps it to exit 2. */
+export declare class UsageError extends Error {
+}
+export type FlagType = 'string' | 'boolean';
+/** Flag names WITHOUT the leading dashes, e.g. { 'add-action': 'string' }. */
+export type FlagSpec = Record<string, FlagType>;
+export interface ParsedArgs {
+    flags: Record<string, string | boolean | undefined>;
+    positionals: string[];
+}
+export declare function parseArgs(args: string[], spec: FlagSpec, usage: string): ParsedArgs;
+/** The one comma-list parser — every list flag on every command goes through
+ * it. Trims each segment and drops the empty ones, so `"ai, ml"` is two
+ * domains (not `ai` and ` ml`, which no query matches) and `"eng,"` is one
+ * (not one plus an empty string persisted to frontmatter and the index).
+ * undefined stays undefined; an all-empty list is an empty array (a clear). */
+export declare function splitList(value: string | boolean | undefined): string[] | undefined;
+export declare function str(value: string | boolean | undefined): string | undefined;

package/dist/cli/args.js

@@ -0,0 +1,53 @@
+// src/cli/args.ts
+// The one flag parser behind every CLI command. Each command declares its
+// flags; parseArgs enforces the declaration — unknown flags and missing
+// values are UsageErrors instead of silently ignored tokens (the getFlag era
+// needed a documented workaround because values stayed in the positional
+// stream).
+/** Bad invocation (unknown flag, missing value, missing positional).
+ * Distinct from crashes: the error adapter maps it to exit 2. */
+export class UsageError extends Error {
+}
+export function parseArgs(args, spec, usage) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token.startsWith('--')) {
+            const name = token.slice(2);
+            const type = spec[name];
+            if (!type)
+                throw new UsageError(`Unknown flag --${name}\n${usage}`);
+            if (type === 'boolean') {
+                flags[name] = true;
+                continue;
+            }
+            const value = args[i + 1];
+            // A declared flag in value position means the value was omitted
+            // (`--brief --clear-actions`) — consuming it would both corrupt the
+            // string and silently drop the swallowed flag.
+            if (value === undefined || (value.startsWith('--') && value.slice(2) in spec)) {
+                throw new UsageError(`--${name} requires a value\n${usage}`);
+            }
+            flags[name] = value;
+            i++;
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { flags, positionals };
+}
+/** The one comma-list parser — every list flag on every command goes through
+ * it. Trims each segment and drops the empty ones, so `"ai, ml"` is two
+ * domains (not `ai` and ` ml`, which no query matches) and `"eng,"` is one
+ * (not one plus an empty string persisted to frontmatter and the index).
+ * undefined stays undefined; an all-empty list is an empty array (a clear). */
+export function splitList(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return value.split(',').map(s => s.trim()).filter(Boolean);
+}
+export function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/cli/batch-errors.js

@@ -9,6 +9,7 @@
 // without those, the `unrecognized_keys` and `invalid_union_discriminator`
 // paths are unreachable.
 import { getOpSchema, listOps } from './schema-introspect.js';
+import { validOpNames, validCreateKinds } from '../batch-ops.js';
 // --- did-you-mean (cheap Levenshtein) ---
 export function levenshtein(a, b) {
     if (a === b)
@@ -91,7 +92,8 @@ export function opNameOf(raw) {
         return null;
     if (op === 'create') {
         const kind = raw.kind;
-        if (typeof kind === 'string')
+        const names = new Set(listOps().map(o => o.name));
+        if (typeof kind === 'string' && names.has(`create-${kind}`))
             return `create-${kind}`;
         return 'create';
     }
@@ -126,7 +128,8 @@ function toStr(v) {
         return String(v);
     }
 }
-const VALID_OPS = ['update', 'create', 'capture', 'link', 'unlink', 'promote'];
+// Derived from the Op Spec table — never hardcoded here.
+const VALID_OPS = validOpNames();
 /**
  * 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
@@ -160,7 +163,7 @@ export function formatIssue(issue, opIndex, raw) {
             return [
                 header,
                 `  field: kind`,
-                `  issue: unknown kind ${got} (expected one of [entity, knowledge, session])`,
+                `  issue: unknown kind ${got} (expected one of [${validCreateKinds().join(', ')}])`,
                 `  ${tip}`,
             ].join('\n');
         }