hafez 1.3.0 → 2.0.0

package/dist/cli/args.d.ts

@@ -1,15 +1,57 @@
+import { HafezError, type HafezErrorCode } from '../types.js';
 /** Bad invocation (unknown flag, missing value, missing positional).
- * Distinct from crashes: the error adapter maps it to exit 2. */
+ * Distinct from crashes: the error adapter maps it to exit 2. The message is
+ * the reason, then the usage text when one is given; `reason` is the problem
+ * alone, for a command that follows it with a shape of its own. */
 export declare class UsageError extends Error {
+    reason: string;
+    constructor(reason: string, usage?: string);
 }
-export type FlagType = 'string' | 'boolean';
+/** A flag the command does not declare. */
+export declare class UnknownFlagError extends UsageError {
+    flag: string;
+    constructor(flag: string, usage: string);
+}
+/** `--help` or `-h` given to a command: the error adapter prints `usage` to
+ * stdout and exits 0. Not a UsageError, so no misuse handler wraps it. */
+export declare class HelpRequest extends Error {
+    usage: string;
+    constructor(usage: string);
+}
+/** For a command that does not go through parseArgs: `--help` or `-h`
+ * anywhere in its args is a HelpRequest for its usage. */
+export declare function helpIfAsked(args: string[], usage: string): void;
+/** A failure whose output the command rendered in full (the `read` miss):
+ * the error adapter writes `output` verbatim to `stream` and exits by `code`. */
+export declare class RenderedError extends HafezError {
+    output: string;
+    stream: 'stdout' | 'stderr';
+    constructor(code: HafezErrorCode, output: string, stream: 'stdout' | 'stderr');
+}
+/** A misuse whose report ends with the shape to retry from (Agent Contract: a
+ * misuse returns the corrected shape). Keeps the wrapped error's code, so its
+ * exit code is unchanged. */
+export declare class MisuseError extends HafezError {
+    shape: string;
+    constructor(cause: HafezError, shape: string);
+}
+/** `repeat` is the one flag that may be given more than once: each repeat
+ * appends, and its value is always a list. Every other flag given twice is a
+ * UsageError on every command — never last-wins, which would drop the first
+ * value with exit 0 (`query --tag a --tag b` used to query `b` alone). */
+export type FlagType = 'string' | 'boolean' | 'repeat';
+export type FlagValue = string | boolean | string[] | undefined;
 /** 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>;
+    flags: Record<string, FlagValue>;
     positionals: string[];
 }
 export declare function parseArgs(args: string[], spec: FlagSpec, usage: string): ParsedArgs;
-/** Comma-separated list flag → trimmed array (undefined stays undefined). */
-export declare function splitList(value: string | boolean | undefined): string[] | undefined;
-export declare function str(value: string | boolean | undefined): string | undefined;
+/** 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: FlagValue): string[] | undefined;
+export declare function str(value: FlagValue): string | undefined;

package/dist/cli/args.js

@@ -3,21 +3,81 @@
 // 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).
+// stream). It also holds the error classes the error → exit adapter maps,
+// since the dispatch module may statically import only this file and types.
+import { HafezError } from '../types.js';
+import { splitCommaList } from '../batch-ops.js';
 /** Bad invocation (unknown flag, missing value, missing positional).
- * Distinct from crashes: the error adapter maps it to exit 2. */
+ * Distinct from crashes: the error adapter maps it to exit 2. The message is
+ * the reason, then the usage text when one is given; `reason` is the problem
+ * alone, for a command that follows it with a shape of its own. */
 export class UsageError extends Error {
+    reason;
+    constructor(reason, usage) {
+        super(usage === undefined ? reason : `${reason}\n${usage}`);
+        this.reason = reason;
+    }
+}
+/** A flag the command does not declare. */
+export class UnknownFlagError extends UsageError {
+    flag;
+    constructor(flag, usage) {
+        super(`Unknown flag --${flag}`, usage);
+        this.flag = flag;
+    }
+}
+/** `--help` or `-h` given to a command: the error adapter prints `usage` to
+ * stdout and exits 0. Not a UsageError, so no misuse handler wraps it. */
+export class HelpRequest extends Error {
+    usage;
+    constructor(usage) {
+        super(usage);
+        this.usage = usage;
+    }
+}
+/** For a command that does not go through parseArgs: `--help` or `-h`
+ * anywhere in its args is a HelpRequest for its usage. */
+export function helpIfAsked(args, usage) {
+    if (args.includes('--help') || args.includes('-h'))
+        throw new HelpRequest(usage);
+}
+/** A failure whose output the command rendered in full (the `read` miss):
+ * the error adapter writes `output` verbatim to `stream` and exits by `code`. */
+export class RenderedError extends HafezError {
+    output;
+    stream;
+    constructor(code, output, stream) {
+        super(code, output);
+        this.output = output;
+        this.stream = stream;
+    }
+}
+/** A misuse whose report ends with the shape to retry from (Agent Contract: a
+ * misuse returns the corrected shape). Keeps the wrapped error's code, so its
+ * exit code is unchanged. */
+export class MisuseError extends HafezError {
+    shape;
+    constructor(cause, shape) {
+        super(cause.code, cause.message, cause.details);
+        this.shape = shape;
+    }
 }
 export function parseArgs(args, spec, usage) {
     const flags = {};
     const positionals = [];
     for (let i = 0; i < args.length; i++) {
         const token = args[i];
+        if (token === '--help' || token === '-h')
+            throw new HelpRequest(usage);
         if (token.startsWith('--')) {
             const name = token.slice(2);
-            const type = spec[name];
+            // Own keys only: `--constructor` must not find Object.prototype's (#134)
+            const type = Object.hasOwn(spec, name) ? spec[name] : undefined;
             if (!type)
-                throw new UsageError(`Unknown flag --${name}\n${usage}`);
+                throw new UnknownFlagError(name, usage);
+            if (type !== 'repeat' && Object.hasOwn(flags, name)) {
+                throw new UsageError(`--${name} was given more than once; it takes one value`, usage);
+            }
             if (type === 'boolean') {
                 flags[name] = true;
                 continue;
@@ -26,10 +86,11 @@ export function parseArgs(args, spec, usage) {
             // 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}`);
+            if (value === undefined || (value.startsWith('--') && Object.hasOwn(spec, value.slice(2)))) {
+                throw new UsageError(`--${name} requires a value`, usage);
             }
-            flags[name] = value;
+            const prev = flags[name];
+            flags[name] = type === 'repeat' ? [...(Array.isArray(prev) ? prev : []), value] : value;
             i++;
         }
         else {
@@ -38,11 +99,15 @@ export function parseArgs(args, spec, usage) {
     }
     return { flags, positionals };
 }
-/** Comma-separated list flag → trimmed array (undefined stays undefined). */
+/** 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());
+    return splitCommaList(value);
 }
 export function str(value) {
     return typeof value === 'string' ? value : undefined;

package/dist/cli/batch-errors.js

@@ -105,14 +105,24 @@ function formatPath(path) {
         return '(root)';
     return path.map(p => (typeof p === 'number' ? `[${p}]` : typeof p === 'symbol' ? p.toString() : p)).join('.');
 }
-function lookupByPath(obj, path) {
-    let cur = obj;
+const GOT_MAX = 60;
+/**
+ * What the op sent at `path`, as one JSON line capped at GOT_MAX chars. Zod v4
+ * attaches no received value to an issue, so the raw op is walked instead.
+ * Null when nothing is at the path (a missing field) — the caller then omits
+ * its `got:` line rather than print `undefined`.
+ */
+function gotAt(raw, path) {
+    let cur = raw;
     for (const p of path) {
-        if (cur == null)
-            return undefined;
+        if (cur === null || typeof cur !== 'object' || !Object.hasOwn(cur, p))
+            return null;
         cur = cur[p];
     }
-    return cur;
+    const s = JSON.stringify(cur);
+    if (s === undefined)
+        return null; // raw itself absent — never print `undefined`
+    return s.length > GOT_MAX ? `${s.slice(0, GOT_MAX - 1)}…` : s;
 }
 function toStr(v) {
     if (typeof v === 'string')
@@ -188,27 +198,25 @@ export function formatIssue(issue, opIndex, raw) {
     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);
+        const got = gotAt(raw, issue.path);
         return [
             header,
             `  field: ${fieldPath}`,
             `  issue: invalid value`,
             ...(expected ? [`  expected: one of [${expected.join(', ')}]`] : []),
-            `  got:      ${toStr(received)}`,
+            ...(got !== null ? [`  got:      ${got}`] : []),
             `  ${tip}`,
         ].join('\n');
     }
     if (code === 'invalid_type') {
         const expected = issue.expected;
-        const received = issue.received;
+        const got = gotAt(raw, issue.path);
         return [
             header,
             `  field: ${fieldPath}`,
             `  issue: wrong type`,
             `  expected: ${expected}`,
-            `  got:      ${received}`,
+            ...(got !== null ? [`  got:      ${got}`] : []),
             `  ${tip}`,
         ].join('\n');
     }

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

@@ -0,0 +1,9 @@
+import type { ConfigHome } from './resolve-vault.js';
+export interface BlockHookCtx extends ConfigHome {
+    /** Defaults to the process's; read inside the catch, since a deleted
+     * working directory makes reading it throw. */
+    cwd?: string;
+    vaultFlag?: string;
+}
+/** The render, or null for any failure: the caller prints nothing. */
+export declare function blockHook(ctx: BlockHookCtx): Promise<string | null>;

package/dist/cli/block-hook.js

@@ -0,0 +1,90 @@
+// src/cli/block-hook.ts
+//
+// `onboard --block`, what the SessionStart hook prints (onboard decision #58):
+// the Block, then the read line for every entity whose `resource` or slug
+// matches the folder. Three folders are tried, each exactly: the working
+// directory, its git root, and in a linked worktree the main repository's
+// root; no directory in between. A `resource` matches a folder's path or the
+// URL of one of its git remotes (case, `.git`, ssh vs https aside); a slug
+// matches a folder's name. The hook never loads: the agent does the read.
+//
+// The hook must never block a session: any failure (no vault, bad config, an
+// unbuilt native binding, no git) prints nothing. So the core and its native
+// binding load here, inside the catch, never at module top. A bad invocation
+// (unknown flag or harness) throws a usage error from `cmdOnboard`, which the
+// CLI's `main` silences for `onboard --block` like any other failure (#132).
+import { execFileSync } from 'child_process';
+import { existsSync, realpathSync } from 'fs';
+import { basename, dirname, isAbsolute, resolve } from 'path';
+import { ENTITY_STATUSES } from '../contracts.js';
+/** The render, or null for any failure: the caller prints nothing. */
+export async function blockHook(ctx) {
+    try {
+        const { isVault, resolveVaultPath } = await import('./resolve-vault.js');
+        const vaultPath = resolveVaultPath(ctx.vaultFlag, ctx);
+        // A --vault flag is not checked by resolution; opening a non-vault would
+        // leave an index file in it.
+        if (typeof vaultPath !== 'string' || !isVault(vaultPath))
+            return null;
+        const cwd = realpathSync(ctx.cwd ?? process.cwd());
+        const folders = foldersOf(cwd);
+        const remotes = remoteUrls(cwd);
+        const { createHafez } = await import('../index.js');
+        const { items } = await createHafez({ vaultPath, git: { push: false } }).query({ filter: 'all' });
+        const matches = items
+            .filter(e => folders.some(f => basename(f) === e.slug) || (e.resource !== null && resourceMatches(e.resource, folders, remotes)))
+            // Active first: the status tuple is ordered active, paused, done.
+            .sort((a, b) => ENTITY_STATUSES.indexOf(a.status) - ENTITY_STATUSES.indexOf(b.status));
+        const { renderBlockHook } = await import('../surfaces/surfaces.js');
+        return renderBlockHook(matches);
+    }
+    catch {
+        return null;
+    }
+}
+/** git's output, or null when git fails or is absent. */
+function git(cwd, ...args) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The working directory, its git root, and in a linked worktree the main
+ * repository's root. */
+function foldersOf(cwd) {
+    const folders = [cwd];
+    const out = git(cwd, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir');
+    const [top, common] = out?.split('\n') ?? [];
+    // Before git 2.31 `--path-format` is echoed back, not obeyed: no git root.
+    if (top && common && isAbsolute(top) && isAbsolute(common)) {
+        folders.push(top);
+        // A linked worktree shares the main checkout's `.git` as its common dir.
+        if (basename(common) === '.git' && dirname(common) !== top)
+            folders.push(dirname(common));
+    }
+    return [...new Set(folders)];
+}
+/** Every remote's URL, normalised. */
+function remoteUrls(cwd) {
+    const out = git(cwd, 'config', '--get-regexp', '^remote\\..*\\.url$');
+    return out ? out.split('\n').map(line => normaliseUrl(line.slice(line.indexOf(' ') + 1))) : [];
+}
+/** `git@github.com:Org/Repo.git`, `ssh://git@github.com/org/repo` and
+ * `https://github.com/org/repo/` are all `github.com/org/repo`. */
+function normaliseUrl(url) {
+    return url.trim().toLowerCase()
+        .replace(/^[a-z+]+:\/\//, '')
+        .replace(/^[^@/]+@/, '')
+        .replace(/^([^/:]+):(?!\d)/, '$1/')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '');
+}
+function resourceMatches(resource, folders, remotes) {
+    if (isAbsolute(resource)) {
+        const path = resolve(resource);
+        return folders.includes(existsSync(path) ? realpathSync(path) : path);
+    }
+    return remotes.includes(normaliseUrl(resource));
+}

package/dist/cli/commands-schema.js

@@ -11,7 +11,9 @@
 import { HafezError } from '../types.js';
 import { listOps, zodToJsonSchema, getOpExample, getEnumValues, getOpSchema, DIGEST_DESCRIPTION } from './schema-introspect.js';
 import { didYouMean } from './batch-errors.js';
+import { helpIfAsked } from './args.js';
 export async function cmdSchema(_os, args) {
+    helpIfAsked(args, 'Usage: hafez schema [op] [--examples]');
     // 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');

package/dist/cli/commands.d.ts

@@ -1,21 +1,46 @@
+import { type FlagSpec } from './args.js';
 import type { Hafez, BatchOperation } from '../types.js';
 export interface CommandOpts {
     json?: boolean;
+    /** Resolved vault path — for handlers that read the vault directly
+     * (export) rather than through the Hafez instance. */
+    vaultPath?: string;
 }
 export declare function cmdRead(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Every flag the query parser accepts, for the branch-support matrix. */
+export declare const QUERY_FLAG_NAMES: string[];
+export type QueryBranch = 'entity' | 'knowledge' | 'all' | 'related-to';
+/** 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 declare const QUERY_FLAG_SUPPORT: Record<QueryBranch, readonly string[]>;
 export declare function cmdQuery(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdSearch(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Exported so tests can assert the flag × kind matrix is exhaustive. */
+export declare const CREATE_FLAGS: FlagSpec;
 export declare function cmdCreate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Exported so tests can assert the table covers the update schema. */
+export declare const UPDATE_FLAGS: FlagSpec;
+/** Flags the generic loop skips because they are not a field of the update
+ * shape — each is hand-handled in cmdUpdate. */
+export declare const UPDATE_SPECIAL_FLAGS: Set<string>;
+/** 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 declare const UPDATE_FIELDS_WITHOUT_FLAGS: Record<string, string>;
 export declare function cmdUpdate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdLink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdUnlink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdCapture(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdPromote(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
-export declare function cmdValidate(os: Hafez, _args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdDelete(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdValidate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdIndexRebuild(os: Hafez): Promise<string>;
-export declare function cmdSync(os: Hafez, _args: string[]): Promise<string>;
-export declare function cmdStats(os: Hafez, _args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdSync(os: Hafez, args: string[]): Promise<string>;
+export declare function cmdStats(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdChangelog(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function parseBatchInput(json: string): BatchOperation[];
 export declare function cmdBatch(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdDigest(os: Hafez, args: string[], _opts?: CommandOpts): Promise<string>;
+export declare function cmdExport(_os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;