hafez 1.2.0 → 1.4.0

package/dist/cli/commands.js

@@ -1,56 +1,120 @@
 // src/cli/commands.ts
-import { z } from 'zod';
 import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parseArgs, splitList, str, UsageError } from './args.js';
 import { HafezError } from '../types.js';
-import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, } from '../contracts.js';
+import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader } from '../batch-ops.js';
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
+const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full]';
+const READ_FLAGS = { depth: 'string' };
 export async function cmdRead(os, args, opts = {}) {
-    const slug = args[0];
+    const { flags, positionals } = parseArgs(args, READ_FLAGS, READ_USAGE);
+    const slug = positionals[0];
     if (!slug)
-        throw new Error('Usage: hafez read <slug> [--depth frontmatter|summary|full]');
-    const depth = (getFlag(args, '--depth') ?? 'summary');
+        throw new UsageError(READ_USAGE);
+    const depth = (str(flags.depth) ?? 'summary');
     const result = await os.read(slug, depth);
     if (opts.json)
         return jsonOut(result);
     const fm = result.frontmatter;
-    if ('type' in fm)
+    if (result.kind === 'entity')
         return formatEntityHeader(fm, result.body);
     return formatKnowledgeHeader(fm, result.body);
 }
+const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
+
+  --filter active|paused|done matches entity status; knowledge notes carry no
+  status, so under --kind all they are always included alongside the matching
+  entities. --filter stale|capture are entity-only views and return no
+  knowledge. --filter/--type/--parent are rejected with --kind knowledge, and
+  --confidence/--subtype are rejected with --kind entity, rather than being
+  silently dropped. --related-to takes no other query flags.`;
+const QUERY_FLAGS = {
+    kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
+    domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
+    since: 'string', before: 'string', 'created-since': 'string', 'created-before': 'string',
+    'sort-by': 'string', 'sort-order': 'string', limit: 'string', offset: 'string',
+};
+/** Every flag the query parser accepts, for the branch-support matrix. */
+export const QUERY_FLAG_NAMES = Object.keys(QUERY_FLAGS);
+/** 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`
+ * never reached an entity query at all. */
+export const QUERY_FLAG_SUPPORT = {
+    entity: ['kind', 'filter', 'type', 'parent', 'domain', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    knowledge: ['kind', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    all: ['kind', 'filter', 'type', 'parent', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    'related-to': ['related-to'],
+};
+const FLAG_SCOPE_REASON = {
+    filter: 'it selects entity status (or the entity-only stale/capture views); knowledge notes carry no status',
+    type: 'entity types only',
+    parent: 'entity hierarchy only',
+    confidence: 'knowledge notes only',
+    subtype: 'knowledge notes only',
+};
+const QUERY_KINDS = ['entity', 'knowledge', 'all'];
+function rejectUnsupportedFlags(branch, flags) {
+    const supported = new Set(QUERY_FLAG_SUPPORT[branch]);
+    for (const [name, value] of Object.entries(flags)) {
+        if (value === undefined || supported.has(name))
+            continue;
+        const where = branch === 'related-to'
+            ? 'with --related-to (it returns every entity and knowledge note linked to the slug)'
+            : `with --kind ${branch}`;
+        const reason = FLAG_SCOPE_REASON[name] ? ` — ${FLAG_SCOPE_REASON[name]}` : '';
+        throw new UsageError(`--${name} is not supported ${where}${reason}\n${QUERY_USAGE}`);
+    }
+}
+/** Paging flags reach SQL as text — parse them strictly here so `--limit abc`
+ * is a usage error rather than a prepare-time SqliteError. */
+function intFlag(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new UsageError(`--${name} must be a non-negative integer (got "${raw}")\n${QUERY_USAGE}`);
+    return Number(raw);
+}
 export async function cmdQuery(os, args, opts = {}) {
-    const kind = getFlag(args, '--kind') ?? 'entity';
-    const filter = (getFlag(args, '--filter') ?? 'active');
-    const type = getFlag(args, '--type');
-    const parent = getFlag(args, '--parent');
-    const relatedTo = getFlag(args, '--related-to');
-    const domain = getFlag(args, '--domain');
-    const confidence = getFlag(args, '--confidence');
-    const since = getFlag(args, '--since');
-    const before = getFlag(args, '--before');
-    const createdSince = getFlag(args, '--created-since');
-    const createdBefore = getFlag(args, '--created-before');
-    const tagRaw = getFlag(args, '--tag');
+    const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
+    const relatedTo = str(flags['related-to']);
+    const branch = relatedTo !== undefined ? 'related-to' : (str(flags.kind) ?? 'entity');
+    if (branch !== 'related-to' && !QUERY_KINDS.includes(branch)) {
+        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${branch}")\n${QUERY_USAGE}`);
+    }
+    rejectUnsupportedFlags(branch, flags);
+    const filter = (str(flags.filter) ?? 'active');
+    const type = str(flags.type);
+    const parent = str(flags.parent);
+    const domain = str(flags.domain);
+    const confidence = str(flags.confidence);
+    const subtype = str(flags.subtype);
+    const since = str(flags.since);
+    const before = str(flags.before);
+    const createdSince = str(flags['created-since']);
+    const createdBefore = str(flags['created-before']);
+    const tagRaw = str(flags.tag);
     const tags = tagRaw ? tagRaw.split(',').map(t => t.trim()).filter(Boolean) : undefined;
-    const sortBy = getFlag(args, '--sort-by');
-    const sortOrder = getFlag(args, '--sort-order');
-    const limitRaw = getFlag(args, '--limit');
-    const offsetRaw = getFlag(args, '--offset');
-    const limit = limitRaw != null ? parseInt(limitRaw, 10) : undefined;
-    const offset = offsetRaw != null ? parseInt(offsetRaw, 10) : undefined;
+    const sortBy = str(flags['sort-by']);
+    const sortOrder = str(flags['sort-order']);
+    const limit = intFlag(str(flags.limit), 'limit');
+    const offset = intFlag(str(flags.offset), 'offset');
     const sortOpts = { sort_by: sortBy, sort_order: sortOrder, limit, offset };
+    const timeOpts = { since, before, createdSince, createdBefore };
     // --related-to: always returns both entities and knowledge
     if (relatedTo) {
         const result = await os.related_to(relatedTo);
         if (opts.json)
             return jsonOut(result);
         const { items: results, total } = result;
-        const entities = results.filter((r) => 'type' in r);
-        const knowledge = results.filter((r) => 'confidence' in r);
+        const entities = results.filter(r => r.kind === 'entity');
+        const knowledge = results.filter(r => r.kind === 'knowledge');
         const sections = [];
         if (entities.length > 0)
             sections.push('## Entities\n\n' + formatQueryTable(entities, total));
@@ -58,20 +122,19 @@ export async function cmdQuery(os, args, opts = {}) {
             sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge, total));
         return sections.length > 0 ? sections.join('\n\n') : 'No results.';
     }
-    const queryOpts = { filter, type, parent, domain, since, before, createdSince, createdBefore, tags, ...sortOpts };
-    // --kind knowledge: query knowledge only
-    // Note: time flags only apply to entity queries.
-    if (kind === 'knowledge') {
-        const subtype = getFlag(args, '--subtype');
-        const kOpts = { domain: domain ?? undefined, confidence, subtype, tags, ...sortOpts };
+    const queryOpts = { filter, type, parent, domain, ...timeOpts, tags, ...sortOpts };
+    // --kind knowledge: query knowledge only. The time window applies here too —
+    // knowledge rows carry created (and last-touched for the plan subtype).
+    if (branch === 'knowledge') {
+        const kOpts = { domain: domain ?? undefined, confidence, subtype, ...timeOpts, tags, ...sortOpts };
         const result = await os.query_knowledge(kOpts);
         if (opts.json)
             return jsonOut(result);
         return formatKnowledgeTable(result.items, result.total);
     }
     // --kind all: query both entities and knowledge via unified query
-    if (kind === 'all') {
-        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence });
+    if (branch === 'all') {
+        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence, subtype });
         if (opts.json)
             return jsonOut(result);
         const { items, total } = result;
@@ -92,129 +155,161 @@ export async function cmdQuery(os, args, opts = {}) {
         return jsonOut(result);
     return formatQueryTable(result.items, result.total);
 }
+const SEARCH_USAGE = 'Usage: hafez search <terms> [--kind entity|knowledge|all]';
+const SEARCH_FLAGS = { kind: 'string' };
 export async function cmdSearch(os, args, opts = {}) {
-    const terms = positionalArgs(args).join(' ');
+    const { flags, positionals } = parseArgs(args, SEARCH_FLAGS, SEARCH_USAGE);
+    const terms = positionals.join(' ');
     if (!terms)
-        throw new Error('Usage: hafez search <terms> [--kind entity|knowledge|all]');
-    const kind = (getFlag(args, '--kind') ?? 'all');
+        throw new UsageError(SEARCH_USAGE);
+    const kind = (str(flags.kind) ?? 'all');
     const results = await os.search(terms, kind);
     if (opts.json)
         return jsonOut(results);
     return formatSearchResults(results);
 }
+// --status is knowledge/plan only, and --purpose needs --type project: a field
+// whose section the chosen template lacks is rejected, never silently dropped.
+const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]\n  entity:    --type capture|entity|project [--purpose text (project only)] [--brief text] [--add-action text] …\n  knowledge: [--subtype insight|plan] [--status active|done (plan only)] [--synthesis text (insight only)] …';
+/** Exported so tests can assert the flag × kind matrix is exhaustive. */
+export const CREATE_FLAGS = {
+    type: 'string', purpose: 'string', description: 'string', resource: 'string',
+    domain: 'string', parent: 'string', related: 'string', tags: 'string',
+    brief: 'string', 'add-action': 'string',
+    subtype: 'string', synthesis: 'string', insight: 'string',
+    // knowledge, plan subtype only — insights have no lifecycle
+    status: 'string',
+};
+/** Flags whose value is a comma list. Everything else is a plain string. */
+const CREATE_LIST_FLAGS = new Set(['domain', 'related', 'tags']);
+/** Every provided create flag → its field name (dashes become underscores),
+ * kind-agnostic on purpose. Which fields a kind accepts is the Op Spec's
+ * call, not the CLI's: the per-kind hand-filter this replaces discarded
+ * whatever its branch didn't name (--brief on knowledge, --subtype on
+ * entity) and still exited 0 with the value nowhere on disk. Only provided
+ * flags are included — a present-but-undefined key would trip the same
+ * strict shape that does the rejecting. */
+function createFields(flags) {
+    const fields = {};
+    for (const flag of Object.keys(CREATE_FLAGS)) {
+        if (flags[flag] === undefined)
+            continue;
+        fields[flag.replace(/-/g, '_')] = CREATE_LIST_FLAGS.has(flag)
+            ? splitList(flags[flag])
+            : str(flags[flag]);
+    }
+    return fields;
+}
 export async function cmdCreate(os, args, opts = {}) {
-    const kind = args[0];
+    const { flags, positionals } = parseArgs(args, CREATE_FLAGS, CREATE_USAGE);
+    const kind = positionals[0];
     if (!kind)
-        throw new Error('Usage: hafez create <entity|knowledge> <name> [options]');
-    const name = positionalArgs(args.slice(1)).join(' ');
+        throw new UsageError(CREATE_USAGE);
+    const name = positionals.slice(1).join(' ');
     if (!name)
-        throw new Error(`Usage: hafez create ${kind} <name> [options]`);
+        throw new UsageError(`Usage: hafez create ${kind} <name> [options]`);
+    const fields = createFields(flags);
     if (kind === 'entity') {
-        const type = getFlag(args, '--type');
-        if (!type)
-            throw new Error('--type is required for entity creation');
-        const slug = await os.create('entity', name, {
-            type,
-            purpose: getFlag(args, '--purpose'),
-            description: getFlag(args, '--description'),
-            resource: getFlag(args, '--resource'),
-            domain: getFlag(args, '--domain')?.split(',').map(d => d.trim()),
-            parent: getFlag(args, '--parent'),
-            related: getFlag(args, '--related')?.split(','),
-            tags: getFlag(args, '--tags')?.split(','),
-            brief: getFlag(args, '--brief'),
-            add_action: getFlag(args, '--add-action'),
-        });
+        // The only per-kind rule the CLI still owns: --type is required, and a
+        // missing one deserves better than a shape error naming a JSON field.
+        if (fields.type === undefined)
+            throw new UsageError('--type is required for entity creation');
+        const slug = await os.create('entity', name, fields);
         return opts.json ? jsonOut({ slug }) : slug;
     }
     if (kind === 'knowledge') {
-        const slug = await os.create('knowledge', name, {
-            subtype: getFlag(args, '--subtype'),
-            synthesis: getFlag(args, '--synthesis') ?? getFlag(args, '--insight'),
-            description: getFlag(args, '--description'),
-            domain: getFlag(args, '--domain')?.split(','),
-            related: getFlag(args, '--related')?.split(','),
-            tags: getFlag(args, '--tags')?.split(','),
-        });
+        // --insight passes through untouched: the Op Spec normalizes the alias
+        // (and drops it when --synthesis is also given). On entity it stays
+        // `insight` and the kind gate rejects it. --status flows through the
+        // same way; the subtype-aware gate accepts it on plans only.
+        const slug = await os.create('knowledge', name, fields);
         return opts.json ? jsonOut({ slug }) : slug;
     }
-    throw new Error(`Unknown kind: ${kind}. Use entity or knowledge.`);
+    throw new UsageError(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
-export async function cmdUpdate(os, args, opts = {}) {
-    const slug = args[0];
-    if (!slug)
-        throw new Error('Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]');
+const UPDATE_USAGE = 'Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]';
+/** Exported so tests can assert the table covers the update schema. */
+export const UPDATE_FLAGS = {
+    status: 'string', 'current-state': 'string', brief: 'string',
+    'add-action': 'string', 'complete-action': 'string', 'remove-action': 'string',
+    'clear-actions': 'boolean',
+    description: 'string', resource: 'string', domain: 'string', confidence: 'string',
+    tags: 'string', related: 'string', insight: 'string', synthesis: 'string',
+    'add-evidence': 'string', 'add-source': 'string',
+    // Composed, not mapped: --log "type: summary" plus --agent build session_log.
+    log: 'string', agent: 'string',
+    // Removed flag, declared so it fails with guidance instead of a generic
+    // unknown-flag error: older installed skills/scripts still pass it, and
+    // "Updated <slug>" with the action discarded is a false success.
+    'next-action': 'string',
+};
+/** Flags whose value is a comma list. Everything else is a plain string. */
+const UPDATE_LIST_FLAGS = new Set(['domain', 'tags', 'related']);
+/** Flags where an empty string is the clear signal — exactly the nullable
+ * fields of the update shape. Every other flag passes its value through
+ * untouched, so `--status ""` reaches the enum and is rejected by name
+ * instead of silently no-opping (which is how it read before: the guard
+ * each flag got was an accident of which one was typed). */
+const UPDATE_CLEARABLE_FLAGS = new Set(['brief', 'description', 'resource']);
+/** Flags the generic loop skips because they are not a field of the update
+ * shape — each is hand-handled in cmdUpdate. */
+export const UPDATE_SPECIAL_FLAGS = new Set(['log', 'agent', 'next-action']);
+/** Update-shape fields with no flag of their own, and why. The exhaustiveness
+ * test consults this, so a gap here is a stated decision rather than the
+ * silent hole `add_actions` was. */
+export const UPDATE_FIELDS_WITHOUT_FLAGS = {
+    session_log: 'composed by --log "type: summary" (+ --agent), never passed raw',
+    add_actions: 'array-valued: comma-splitting would mangle action text (actions carry commas), and the parser takes no repeated flags — batch payloads are the interface for multi-action writes',
+};
+/** Every provided update flag → its field name (dashes become underscores).
+ * Which fields the target accepts is the Op Spec's call, not the CLI's — the
+ * strict shape does all accepting and rejecting, exactly as on create. Only
+ * provided flags are included: a present-but-undefined key would trip that
+ * same strict shape. */
+function updateFields(flags) {
     const fields = {};
-    const status = getFlag(args, '--status');
-    if (status)
-        fields.status = status;
-    // Removed flag must fail loudly, not silently drop the value: older
-    // installed skills/scripts still pass it, and "Updated <slug>" with the
-    // action discarded is a false success.
-    if (args.includes('--next-action')) {
-        throw new Error('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
+    for (const [flag, type] of Object.entries(UPDATE_FLAGS)) {
+        const raw = flags[flag];
+        if (raw === undefined || UPDATE_SPECIAL_FLAGS.has(flag))
+            continue;
+        const field = flag.replace(/-/g, '_');
+        if (type === 'boolean') {
+            fields[field] = true;
+            continue;
+        }
+        if (UPDATE_LIST_FLAGS.has(flag)) {
+            fields[field] = splitList(raw);
+            continue;
+        }
+        const value = str(raw);
+        fields[field] = value === '' && UPDATE_CLEARABLE_FLAGS.has(flag) ? null : value;
     }
-    const currentState = getFlag(args, '--current-state');
-    if (currentState)
-        fields.current_state = currentState;
-    // Brief
-    const brief = getFlag(args, '--brief');
-    if (brief !== undefined) {
-        fields.brief = brief === '' ? null : brief;
+    return fields;
+}
+export async function cmdUpdate(os, args, opts = {}) {
+    const { flags, positionals } = parseArgs(args, UPDATE_FLAGS, UPDATE_USAGE);
+    const slug = positionals[0];
+    if (!slug)
+        throw new UsageError(UPDATE_USAGE);
+    if (flags['next-action'] !== undefined) {
+        throw new UsageError('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
     }
-    // Next Actions
-    const addAction = getFlag(args, '--add-action');
-    if (addAction)
-        fields.add_action = addAction;
-    const completeAction = getFlag(args, '--complete-action');
-    if (completeAction)
-        fields.complete_action = completeAction;
-    const removeAction = getFlag(args, '--remove-action');
-    if (removeAction)
-        fields.remove_action = removeAction;
-    if (args.includes('--clear-actions'))
-        fields.clear_actions = true;
-    const log = getFlag(args, '--log');
-    if (log) {
+    // --insight is the declared alias; the Op Spec normalizes it (and drops it
+    // when --synthesis is also given).
+    const fields = updateFields(flags);
+    // The one genuinely CLI-owned convenience: session_log is a nested object,
+    // so the flag pair composes it rather than naming a field.
+    const log = str(flags.log);
+    if (log !== undefined) {
         const colonIdx = log.indexOf(':');
         if (colonIdx === -1)
-            throw new Error('--log format: "type: summary". Types: progress, decision, blocker, research');
-        const type = log.slice(0, colonIdx).trim();
-        const summary = log.slice(colonIdx + 1).trim();
-        const agent = getFlag(args, '--agent') ?? 'claude';
-        fields.session_log = { type, summary, agent };
+            throw new UsageError('--log format: "type: summary". Types: progress, decision, blocker, research');
+        fields.session_log = {
+            type: log.slice(0, colonIdx).trim(),
+            summary: log.slice(colonIdx + 1).trim(),
+            agent: str(flags.agent) ?? 'claude',
+        };
     }
-    // Shared metadata (entity + knowledge)
-    const description = getFlag(args, '--description');
-    if (description !== undefined)
-        fields.description = description;
-    const resource = getFlag(args, '--resource');
-    if (resource !== undefined)
-        fields.resource = resource;
-    const domainRaw = getFlag(args, '--domain');
-    if (domainRaw)
-        fields.domain = domainRaw.split(',').map((d) => d.trim());
-    const conf = getFlag(args, '--confidence');
-    if (conf)
-        fields.confidence = conf;
-    const tagsRaw = getFlag(args, '--tags');
-    if (tagsRaw)
-        fields.tags = tagsRaw.split(',').map((t) => t.trim());
-    const relatedRaw = getFlag(args, '--related');
-    if (relatedRaw)
-        fields.related = relatedRaw.split(',').map((r) => r.trim());
-    const insight = getFlag(args, '--insight');
-    if (insight)
-        fields.synthesis = insight;
-    const synthesis = getFlag(args, '--synthesis');
-    if (synthesis)
-        fields.synthesis = synthesis;
-    const addEvidence = getFlag(args, '--add-evidence');
-    if (addEvidence)
-        fields.add_evidence = addEvidence;
-    const addSource = getFlag(args, '--add-source');
-    if (addSource)
-        fields.add_source = addSource;
     const result = await os.update(slug, fields);
     if (opts.json)
         return jsonOut({ slug, ...result });
@@ -224,23 +319,17 @@ export async function cmdUpdate(os, args, opts = {}) {
     }
     return lines.join('\n');
 }
+const LINK_FLAGS = { relation: 'string' };
 function parseLinkArgs(args, verb) {
-    const relation = getFlag(args, '--relation');
-    // After getFlag the relation value is still at its original positional slot
-    // (getFlag does NOT splice), so strip it manually before reading positionals.
-    const positionals = args.filter((a, i) => {
-        if (a === '--relation')
-            return false;
-        if (i > 0 && args[i - 1] === '--relation')
-            return false;
-        return !a.startsWith('--');
-    });
+    const usage = `Usage: hafez ${verb} <slug> <target> --relation <parent|related>`;
+    const { flags, positionals } = parseArgs(args, LINK_FLAGS, usage);
+    const relation = str(flags.relation);
     const [slug, target] = positionals;
     if (!slug || !target || !relation) {
-        throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
+        throw new UsageError(usage);
     }
     if (!['parent', 'related'].includes(relation)) {
-        throw new Error(`Invalid relation: ${relation}. Must be parent or related.`);
+        throw new UsageError(`Invalid relation: ${relation}. Must be parent or related.`);
     }
     return { slug, target, relation };
 }
@@ -255,22 +344,24 @@ export async function cmdUnlink(os, args, opts = {}) {
     return opts.json ? jsonOut({ slug, target, relation }) : `Unlinked ${slug} — ${target} (${relation})`;
 }
 /** Top-level capture command — aligns the CLI verb with the batch op name. */
+const CAPTURE_USAGE = 'Usage: hafez capture <name> [--notes "text"]';
+const CAPTURE_FLAGS = { notes: 'string' };
 export async function cmdCapture(os, args, opts = {}) {
-    const name = positionalArgs(args).join(' ');
+    const { flags, positionals } = parseArgs(args, CAPTURE_FLAGS, CAPTURE_USAGE);
+    const name = positionals.join(' ');
     if (!name)
-        throw new Error('Usage: hafez capture <name> [--notes "text"]');
-    const notes = getFlag(args, '--notes');
+        throw new UsageError(CAPTURE_USAGE);
+    const notes = str(flags.notes);
     const slug = await os.capture(name, notes);
     return opts.json ? jsonOut({ slug }) : slug;
 }
+const PROMOTE_USAGE = 'Usage: hafez promote <slug> <entity|project|knowledge>';
 export async function cmdPromote(os, args, opts = {}) {
-    const slug = args[0];
-    const target = args[1];
+    const { positionals } = parseArgs(args, {}, PROMOTE_USAGE);
+    const [slug, target] = positionals;
     if (!slug || !target)
-        throw new Error('Usage: hafez promote <slug> <entity|project|knowledge>');
-    if (!['entity', 'project', 'knowledge'].includes(target)) {
-        throw new Error(`Invalid target: ${target}. Must be entity, project, or knowledge.`);
-    }
+        throw new UsageError(PROMOTE_USAGE);
+    // Target validity is core's rule (contract canPromoteTo) — no CLI re-check.
     await os.promote(slug, target);
     if (opts.json)
         return jsonOut({ slug, target });
@@ -304,10 +395,13 @@ export async function cmdStats(os, _args, opts = {}) {
         return jsonOut(stats);
     return formatStats(stats);
 }
+const CHANGELOG_USAGE = 'Usage: hafez changelog --since <date|relative>\nExamples: --since 2026-03-20, --since 7.days.ago, --since 1.week.ago';
+const CHANGELOG_FLAGS = { since: 'string' };
 export async function cmdChangelog(os, args, opts = {}) {
-    const since = getFlag(args, '--since');
+    const { flags } = parseArgs(args, CHANGELOG_FLAGS, CHANGELOG_USAGE);
+    const since = str(flags.since);
     if (!since)
-        throw new Error('Usage: hafez changelog --since <date|relative>\nExamples: --since 2026-03-20, --since 7.days.ago, --since 1.week.ago');
+        throw new UsageError(CHANGELOG_USAGE);
     const entries = await os.changelog(since);
     if (opts.json)
         return jsonOut(entries);
@@ -315,127 +409,11 @@ export async function cmdChangelog(os, args, opts = {}) {
 }
 // --- Batch ---
 // All enums are built from contracts.ts tuples so help-renderer, file validators,
-// and CLI-input validator share a single source of truth. cli-schema-parity.test.ts
-// enforces this on every build.
+// and CLI-input validator share a single source of truth — drift is structurally
+// impossible (the Op Spec table in batch-ops.ts is the only consumer).
 // 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();
-export const UpdateFieldsSchema = z.object({
-    status: z.enum([...ENTITY_STATUSES]).optional(),
-    current_state: z.string().optional(),
-    session_log: SessionLogSchema.optional(),
-    brief: z.string().nullable().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
-    complete_action: z.string().optional(),
-    remove_action: z.string().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: z.string().optional(),
-    insight: z.string().optional(), // alias for synthesis (normalized in parseBatchInput)
-    add_evidence: z.string().optional(),
-    add_source: z.string().optional(),
-}).strict();
-const CreateEntityFieldsSchema = z.object({
-    type: z.enum([...ENTITY_TYPES]),
-    purpose: z.string().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: z.string().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
-}).strict();
-const CreateKnowledgeFieldsSchema = z.object({
-    subtype: z.enum([...VALID_SUBTYPES]).optional(),
-    synthesis: z.string().optional(),
-    insight: z.string().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();
-const CreateSessionFieldsSchema = z.object({
-    synthesis: z.string().optional(),
-    insight: z.string().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();
-// 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', [
-    z.object({
-        op: z.literal('update'),
-        slug: z.string(),
-        fields: UpdateFieldsSchema,
-    }).strict(),
-    // create is a nested discriminatedUnion on `kind` — see CreateBranch above.
-    // discriminatedUnion accepts a ZodDiscriminatedUnion as a branch via option-flattening.
-    CreateBranch,
-    z.object({
-        op: z.literal('capture'),
-        name: z.string(),
-        notes: z.string().optional(),
-    }).strict(),
-    z.object({
-        op: z.literal('link'),
-        slug: z.string(),
-        target: z.string(),
-        relation: z.enum(['parent', 'related']),
-    }).strict(),
-    z.object({
-        op: z.literal('unlink'),
-        slug: z.string(),
-        target: z.string(),
-        relation: z.enum(['parent', 'related']),
-    }).strict(),
-    z.object({
-        op: z.literal('promote'),
-        slug: z.string(),
-        target: z.enum(['entity', 'project', 'knowledge']),
-    }).strict(),
-]);
 export function parseBatchInput(json) {
     let parsed;
     try {
@@ -475,19 +453,12 @@ export function parseBatchInput(json) {
             continue;
         }
         const op = result.data;
-        // Alias: insight → synthesis for create knowledge/session and update ops.
-        // Runs only on successfully-parsed ops, preserving prior semantics.
-        if (op.fields) {
-            if (op.fields.insight && !op.fields.synthesis) {
-                op.fields.synthesis = op.fields.insight;
-                delete op.fields.insight;
-            }
-        }
-        operations.push(op);
+        // Alias normalization is the Op Spec's (normalizeAliases) — the CLI just
+        // hands back canonical ops so `batch --dry-run` output names real fields.
+        operations.push(normalizeAliases(op));
     }
     if (failureBlocks.length > 0) {
-        const header = `Batch contains ${failureBlocks.length} invalid operation${failureBlocks.length === 1 ? '' : 's'} (0 of ${parsed.length} applied, batch aborted):`;
-        throw new HafezError('VALIDATION_FAILED', header, failureBlocks);
+        throw new HafezError('VALIDATION_FAILED', batchInvalidHeader(failureBlocks.length, parsed.length), failureBlocks);
     }
     return operations;
 }
@@ -517,9 +488,12 @@ function readStdin() {
         process.stdin.on('error', reject);
     });
 }
+const BATCH_USAGE = "Usage: hafez batch [--dry-run] [--file payload.json]  (or pipe JSON to stdin)";
+const BATCH_FLAGS = { 'dry-run': 'boolean', file: 'string' };
 export async function cmdBatch(os, args, opts = {}) {
-    const dryRun = args.includes('--dry-run');
-    const file = getFlag(args, '--file');
+    const { flags } = parseArgs(args, BATCH_FLAGS, BATCH_USAGE);
+    const dryRun = flags['dry-run'] === true;
+    const file = str(flags.file);
     const input = file ? readPayloadFile(file) : await readStdin();
     if (!input.trim()) {
         throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin (echo \'[...]\' | hafez batch) or pass --file payload.json');
@@ -533,7 +507,9 @@ export async function cmdBatch(os, args, opts = {}) {
             return jsonOut(report);
         if (!report.valid) {
             const invalidCount = report.operations.filter(o => o.errors.length > 0).length;
-            const lines = report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+            const lines = report.operations.flatMap(o => o.errors.map(e => opErrorLine(o.index, o.op, o.slug, e)));
+            // Dry-run's own header: it reports a hypothetical, so it says "would be
+            // applied" rather than the refusal wording batchInvalidHeader carries.
             throw new HafezError('VALIDATION_FAILED', `Batch invalid: ${invalidCount} of ${operations.length} operation${operations.length === 1 ? '' : 's'} failed validation (0 would be applied)`, lines);
         }
         const out = [`Batch valid: ${operations.length} operations would be applied`];
@@ -556,13 +532,22 @@ export async function cmdBatch(os, args, opts = {}) {
     let output = `Batch complete: ${operations.length} operations`;
     if (created.length > 0)
         output += ` (created: ${created.join(', ')})`;
-    return output;
+    // Skipped ops carry the same warning line dry-run printed for them.
+    const lines = [output];
+    results.forEach((r, i) => {
+        if (r.status === 'skipped' && r.warning)
+            lines.push(`Warning: op[${i}] ${r.warning}`);
+    });
+    return lines.join('\n');
 }
+const DIGEST_USAGE = 'Usage: hafez digest [--file summary.json]  (or pipe JSON to stdin)';
+const DIGEST_FLAGS = { file: 'string' };
 export async function cmdDigest(os, args, _opts = {}) {
-    const file = getFlag(args, '--file');
+    const { flags } = parseArgs(args, DIGEST_FLAGS, DIGEST_USAGE);
+    const file = str(flags.file);
     const raw = file ? readPayloadFile(file) : await readStdin();
     if (!raw.trim()) {
-        throw new Error('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
+        throw new UsageError('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
     }
     // Parse JSON
     let parsed;
@@ -570,12 +555,12 @@ export async function cmdDigest(os, args, _opts = {}) {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error('Invalid JSON on stdin: ' + (raw.slice(0, 80)));
+        throw new HafezError('VALIDATION_FAILED', 'Invalid JSON on stdin: ' + (raw.slice(0, 80)));
     }
     const result = parseDigestInput(parsed);
     if (!result.success) {
         const fields = result.error.issues.map(i => i.path.join('.')).join(', ');
-        throw new Error(`Invalid digest input — missing or invalid fields: ${fields}`);
+        throw new HafezError('VALIDATION_FAILED', `Invalid digest input — missing or invalid fields: ${fields}`);
     }
     // Warn about unknown fields
     if (result.unknownFields.length > 0) {
@@ -592,23 +577,22 @@ export async function cmdDigest(os, args, _opts = {}) {
     const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
-// --- Arg helpers ---
-function getFlag(args, flag) {
-    const idx = args.indexOf(flag);
-    if (idx === -1)
-        return undefined;
-    return args[idx + 1];
-}
-/** Extract positional args by skipping --flag value pairs */
-function positionalArgs(args) {
-    const result = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
-            i++; // skip the flag's value too
-        }
-        else {
-            result.push(args[i]);
-        }
-    }
-    return result;
+export async function cmdExport(_os, args, opts = {}) {
+    const EXPORT_USAGE = 'Usage: hafez export --okf [--out <dir>]';
+    const { flags } = parseArgs(args, { okf: 'boolean', out: 'string' }, EXPORT_USAGE);
+    if (flags.okf !== true)
+        throw new UsageError(EXPORT_USAGE);
+    const outDir = typeof flags.out === 'string' ? resolve(flags.out) : resolve(process.cwd(), 'okf-export');
+    if (!opts.vaultPath)
+        throw new HafezError('VALIDATION_FAILED', 'export requires a resolved vault path (CommandOpts.vaultPath)');
+    const { exportOkf } = await import('../export-okf.js');
+    const exportReport = exportOkf(opts.vaultPath, outDir);
+    if (opts.json)
+        return JSON.stringify(exportReport, null, 2);
+    const lines = [`Exported ${exportReport.entities} entities, ${exportReport.knowledge} knowledge, ${exportReport.sessions} sessions to ${exportReport.outDir}`];
+    for (const s of exportReport.skipped)
+        lines.push(`  skipped ${s.file}: ${s.reason}`);
+    if (exportReport.unresolvedLinks > 0)
+        lines.push(`  unresolved links: ${exportReport.unresolvedLinks}`);
+    return lines.join('\n');
 }