hafez 1.3.0 → 1.4.0

package/dist/cli/index.js

@@ -1,45 +1,67 @@
 // src/cli/index.ts
+//
+// Import discipline: this module is loaded for EVERY invocation, so it may
+// only import what every invocation needs — node builtins, the flag parser,
+// and the error type. Everything else (the core factory and its native SQLite
+// binding, zod-backed schema introspection, the markdown formatters, even
+// vault-path resolution) loads on demand from the command that needs it, so
+// `hafez --version` / `help` / `init` no longer pay for the whole program.
 import { readFileSync } from 'fs';
-import { dirname, join, resolve } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { createHafez } from '../index.js';
 import { HafezError } from '../types.js';
-import { parseArgs, UsageError } from './args.js';
-import { cmdRead, cmdQuery, cmdSearch, cmdCreate, cmdUpdate, cmdLink, cmdUnlink, cmdPromote, cmdValidate, cmdIndexRebuild, cmdBatch, cmdSync, cmdStats, cmdChangelog, cmdDigest, cmdCapture } from './commands.js';
-import { cmdSchema } from './commands-schema.js';
-import { renderAgentHelp } from './help-agent.js';
-import { renderOnboard } from './onboard.js';
-import { resolveVaultPath, noVaultMessage, cmdInit } from './resolve-vault.js';
-const COMMANDS = {
-    read: cmdRead,
-    sync: cmdSync,
-    query: cmdQuery,
-    search: cmdSearch,
-    create: cmdCreate,
-    capture: cmdCapture,
-    update: cmdUpdate,
-    link: cmdLink,
-    unlink: cmdUnlink,
-    promote: cmdPromote,
-    batch: cmdBatch,
-    schema: cmdSchema,
-    validate: cmdValidate,
-    index: (os, args) => {
-        if (args[0] === 'rebuild')
-            return cmdIndexRebuild(os);
-        throw new UsageError('Usage: hafez index rebuild');
+import { UsageError } from './args.js';
+/** Bind a vault command to its handler without importing the handler module
+ * until the command actually runs. */
+function lazy(pick) {
+    return async (os, args, opts) => pick(await import('./commands.js'))(os, args, opts);
+}
+export const COMMANDS = {
+    // --- pre-vault ---
+    help: { phase: 'pre-vault', run: async (args) => (args[0] === '--agent' ? (await import('./help-agent.js')).renderAgentHelp() : USAGE) },
+    onboard: { phase: 'pre-vault', run: async () => (await import('./onboard.js')).renderOnboard() },
+    schema: { phase: 'pre-vault', run: async (args) => (await import('./commands-schema.js')).cmdSchema(null, args) },
+    version: { phase: 'pre-vault', run: () => versionLine() },
+    init: { phase: 'pre-vault', run: async (args, ctx) => { (await import('./resolve-vault.js')).cmdInit(args, ctx.vaultFlag); return null; } },
+    // Binds (args, ctx) explicitly: cmdUpgrade's third parameter is its
+    // dependency seam, and PreVaultRun's signature keeps dispatch from ever
+    // passing a third argument into it.
+    upgrade: { phase: 'pre-vault', run: async (args, ctx) => (await import('./upgrade.js')).cmdUpgrade(args, ctx) },
+    // --- vault ---
+    read: { phase: 'vault', run: lazy(m => m.cmdRead) },
+    sync: { phase: 'vault', run: lazy(m => m.cmdSync) },
+    query: { phase: 'vault', run: lazy(m => m.cmdQuery) },
+    search: { phase: 'vault', run: lazy(m => m.cmdSearch) },
+    create: { phase: 'vault', mutating: true, run: lazy(m => m.cmdCreate) },
+    capture: { phase: 'vault', mutating: true, run: lazy(m => m.cmdCapture) },
+    update: { phase: 'vault', mutating: true, run: lazy(m => m.cmdUpdate) },
+    link: { phase: 'vault', mutating: true, run: lazy(m => m.cmdLink) },
+    unlink: { phase: 'vault', mutating: true, run: lazy(m => m.cmdUnlink) },
+    promote: { phase: 'vault', mutating: true, run: lazy(m => m.cmdPromote) },
+    batch: { phase: 'vault', mutating: true, run: lazy(m => m.cmdBatch) },
+    validate: { phase: 'vault', run: lazy(m => m.cmdValidate) },
+    index: {
+        phase: 'vault',
+        run: async (os, args) => {
+            if (args[0] === 'rebuild')
+                return (await import('./commands.js')).cmdIndexRebuild(os);
+            throw new UsageError('Usage: hafez index rebuild');
+        },
     },
-    stats: cmdStats,
-    changelog: cmdChangelog,
-    digest: cmdDigest,
+    stats: { phase: 'vault', run: lazy(m => m.cmdStats) },
+    changelog: { phase: 'vault', run: lazy(m => m.cmdChangelog) },
+    digest: { phase: 'vault', run: lazy(m => m.cmdDigest) },
+    export: { phase: 'vault', run: lazy(m => m.cmdExport) },
 };
-// Commands that modify vault files — auto-sync after these
-const MUTATING_COMMANDS = new Set(['update', 'create', 'capture', 'link', 'unlink', 'batch', 'promote']);
-const USAGE = `Usage: hafez <command> [args]
+/** Exported so a guard test can assert every registered command is documented
+ * here — a registered-but-undocumented command is otherwise invisible. */
+export const USAGE = `Usage: hafez <command> [args]
 
 Commands:
   read <slug>                Read entity or knowledge note
   query [--filter ...] ...   Filter entities/knowledge
+    --kind all               Both kinds; --filter matches entity status only,
+                             so knowledge notes (which have none) always show
   search <terms>             Full-text search
   create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
@@ -69,6 +91,7 @@ Commands:
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
   onboard                    Agent-directed first run: seed the vault, pick integration level
+  upgrade                    Check whether hafez is outdated and print the update steps
   help --agent               Full API reference for agents
 
 Global flags:
@@ -80,7 +103,7 @@ Vault discovery: --vault flag > ~/.config/hafez/vault
 `;
 /** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
  * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
-const EXIT_CODES = {
+export const EXIT_CODES = {
     NOT_FOUND: 1,
     VALIDATION_FAILED: 2,
     GIT_PUSH_FAILED: 3,
@@ -88,12 +111,21 @@ const EXIT_CODES = {
     GIT_COMMIT_FAILED: 6,
     VAULT_LOCKED: 7,
 };
+/** The pure half of the error → exit adapter: which code an error maps to.
+ * Exported so the exit-code contract is testable without spawning the CLI. */
+export function exitCodeFor(err) {
+    if (err instanceof UsageError)
+        return 2;
+    if (err instanceof HafezError)
+        return EXIT_CODES[err.code] ?? 1;
+    return 1;
+}
 /** The one error → exit adapter. Usage errors (bad flags/args) are distinct
  * from vault errors and from unknown crashes. */
 function report(err) {
     if (err instanceof UsageError) {
         process.stderr.write(`Error: ${err.message}\n`);
-        process.exit(2);
+        process.exit(exitCodeFor(err));
     }
     if (err instanceof HafezError) {
         process.stderr.write(`Error: ${err.message}\n`);
@@ -101,17 +133,29 @@ function report(err) {
             for (const detail of err.details)
                 process.stderr.write(`  - ${detail}\n`);
         }
-        process.exit(EXIT_CODES[err.code] ?? 1);
+        process.exit(exitCodeFor(err));
     }
     failUnknown(err);
 }
+/** Does this error mean the native module failed to load/build?
+ *
+ * Matched on the MESSAGE only, and only on the messages a load/ABI failure
+ * actually produces. The old test also scanned the stack for "better-sqlite3",
+ * which every SqliteError's stack contains — so a plain query error ("near
+ * 'abc': syntax error") printed reinstall advice instead of itself. */
+export function isBindingsFailure(err) {
+    const message = err?.message;
+    if (typeof message !== 'string')
+        return false;
+    return /Could not locate the bindings file|better_sqlite3\.node|was compiled against a different Node\.js version|NODE_MODULE_VERSION|invalid ELF header/i.test(message);
+}
 // Terminal handler for non-Hafez errors. Special-cases unbuilt better-sqlite3
 // bindings: npm 11+ blocks install scripts by default, so `npm install -g
 // hafez` reports success with the native module unbuilt and the first indexed
 // command dies here — guide instead of stack-tracing.
 function failUnknown(err) {
     const e = err;
-    if (/better[-_]sqlite3|Could not locate the bindings file/i.test(`${e.message}\n${e.stack ?? ''}`)) {
+    if (isBindingsFailure(e)) {
         process.stderr.write('Error: the SQLite bindings (better-sqlite3) are not built.\n' +
             'npm 11+ blocks install scripts by default, so the install reports success\n' +
             'while skipping the native build. Fix with:\n\n' +
@@ -121,108 +165,84 @@ function failUnknown(err) {
     process.stderr.write(`Error: ${e.message}\n`);
     process.exit(1);
 }
-export async function main(argv) {
-    const args = argv.slice(2);
-    // Extract global flags
-    const vaultIdx = args.indexOf('--vault');
-    let flagValue;
-    if (vaultIdx !== -1) {
-        flagValue = args[vaultIdx + 1];
-        args.splice(vaultIdx, 2);
-    }
-    const jsonIdx = args.indexOf('--json');
-    const json = jsonIdx !== -1;
-    if (json)
-        args.splice(jsonIdx, 1);
-    const command = args.shift();
-    if (!command || command === '--help' || command === '-h') {
-        process.stdout.write(USAGE);
-        return;
-    }
-    if (command === '--version' || command === '-v' || command === 'version') {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
-        process.stdout.write(`hafez ${pkg.version}\n`);
-        return;
+function versionLine() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
+    return `hafez ${pkg.version}`;
+}
+/** Extract the global flags (--vault <path>, --json) from anywhere in argv.
+ * Exported for the in-process dispatch tests. A flag sitting where the vault
+ * path should be means the value is missing — never consume it (the same
+ * value-position rule parseArgs applies to declared command flags). */
+export function extractGlobalFlags(args) {
+    const rest = [];
+    let vaultFlag;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--vault') {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('--'))
+                throw new UsageError('--vault requires a path value');
+            // The old one-shot extraction left a second --vault in the command args
+            // where the declared-flag parser rejected it — keep failing loudly
+            // rather than silently letting the last one win (a mutating command
+            // would write to a different vault than the first flag named).
+            if (vaultFlag !== undefined)
+                throw new UsageError('--vault specified more than once');
+            vaultFlag = v;
+            i++;
+        }
+        else if (a === '--json') {
+            json = true;
+        }
+        else {
+            rest.push(a);
+        }
     }
-    // help runs before vault resolution — works without a registered vault
-    if (command === 'help') {
-        if (args[0] === '--agent') {
-            process.stdout.write(renderAgentHelp());
+    return { rest, vaultFlag, json };
+}
+export async function main(argv) {
+    try {
+        const { rest: args, vaultFlag, json } = extractGlobalFlags(argv.slice(2));
+        const command = args.shift();
+        if (!command || command === '--help' || command === '-h') {
+            process.stdout.write(USAGE);
             return;
         }
-        process.stdout.write(USAGE);
-        return;
-    }
-    // onboard runs before vault resolution — static agent-directed text
-    if (command === 'onboard') {
-        process.stdout.write(renderOnboard());
-        return;
-    }
-    // schema runs before vault resolution — pure Zod introspection, no vault needed.
-    if (command === 'schema') {
-        try {
-            const result = await cmdSchema(null, args);
-            process.stdout.write(result + '\n');
+        const name = command === '--version' || command === '-v' ? 'version' : command;
+        const spec = COMMANDS[name];
+        if (!spec) {
+            process.stderr.write(`Unknown command: ${command}\n${USAGE}`);
+            process.exit(1);
         }
-        catch (err) {
-            report(err);
+        if (spec.phase === 'pre-vault') {
+            const out = await spec.run(args, { json, vaultFlag });
+            if (out !== null)
+                process.stdout.write(out.endsWith('\n') ? out : out + '\n');
+            return;
         }
-        return;
-    }
-    // init runs before vault resolution
-    if (command === 'init') {
-        cmdInit(args, flagValue);
-        return;
-    }
-    // Resolve vault
-    const resolution = resolveVaultPath(flagValue);
-    if (resolution === null) {
-        process.stderr.write(noVaultMessage());
-        process.exit(1);
-    }
-    if (typeof resolution === 'object' && 'error' in resolution) {
-        process.stderr.write(`Error: ${resolution.error}\n`);
-        process.exit(1);
-    }
-    const vaultPath = resolution;
-    // export runs before Hafez instance creation — read-only, no auto-sync
-    if (command === 'export') {
-        try {
-            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');
-            const { exportOkf } = await import('../export-okf.js');
-            const exportReport = exportOkf(vaultPath, outDir);
-            if (json) {
-                process.stdout.write(JSON.stringify(exportReport, null, 2) + '\n');
-            }
-            else {
-                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}`);
-                process.stdout.write(lines.join('\n') + '\n');
-            }
+        // Resolve vault (loaded here, not at module top: the pre-vault commands
+        // above return without ever needing the vault machinery)
+        const { resolveVaultPath, noVaultMessage } = await import('./resolve-vault.js');
+        const resolution = resolveVaultPath(vaultFlag);
+        if (resolution === null) {
+            process.stderr.write(noVaultMessage());
+            process.exit(1);
         }
-        catch (err) {
-            report(err);
+        if (typeof resolution === 'object' && 'error' in resolution) {
+            process.stderr.write(`Error: ${resolution.error}\n`);
+            process.exit(1);
         }
-        return;
-    }
-    const handler = COMMANDS[command];
-    if (!handler) {
-        process.stderr.write(`Unknown command: ${command}\n${USAGE}`);
-        process.exit(1);
-    }
-    const os = createHafez({ vaultPath, git: { push: false } });
-    try {
-        const result = await handler(os, args, { json });
+        const vaultPath = resolution;
+        // First touch of the core — and so of the native SQLite binding. A
+        // failure to load it lands in the catch below and is recognised by
+        // isBindingsFailure, exactly as it was when this import was static.
+        const { createHafez } = await import('../index.js');
+        const os = createHafez({ vaultPath, git: { push: false } });
+        const result = await spec.run(os, args, { json, vaultPath });
         // Auto-sync after mutating commands
-        if (MUTATING_COMMANDS.has(command)) {
+        if (spec.mutating) {
             try {
                 await os.sync();
             }

package/dist/cli/upgrade.d.ts

@@ -0,0 +1,42 @@
+export type Comparison = 'behind' | 'equal' | 'ahead' | 'unknown';
+/** `command` entries are directly executable (after user approval); `action`
+ * entries are prose, so an agent that shells out every entry does not try to
+ * run English. */
+export interface UpgradeStep {
+    kind: 'command' | 'action';
+    text: string;
+}
+export interface UpgradeState {
+    current: string;
+    latest: string | null;
+    comparison: Comparison;
+    registryReachable: boolean;
+    npmMajor: number | null;
+    install: 'registry' | 'dev-checkout';
+    skill: 'present' | 'absent';
+    skillSource: string;
+    skillTarget: string;
+    /** Mutually exclusive with the registry install in `steps` — exposed
+     * separately so an agent iterating `steps` cannot run both. */
+    alternativeInstall: string | null;
+    steps: UpgradeStep[];
+}
+export interface UpgradeDeps {
+    fetch: typeof globalThis.fetch;
+    registryUrl: string;
+    packageRoot: string;
+    installedSkillPath: string;
+    npmVersion: () => string;
+}
+/** Three-way compare on the numeric segments. Hand-rolled string compare is
+ * the trap this exists to avoid: `1.10.0` < `1.9.0` lexicographically.
+ * Anything that is not plain X.Y.Z (a prerelease, a build tag) is `unknown` —
+ * this tool never guesses at a version it cannot order. */
+export declare function compareVersions(local: string, latest: string): Comparison;
+export declare function buildUpgradeState(deps: UpgradeDeps): Promise<UpgradeState>;
+export declare function renderUpgrade(state: UpgradeState): string;
+/** `deps` is the third parameter, unreachable from dispatch (PreVaultRun is
+ * `(args, ctx)`) — the tests inject it directly. */
+export declare function cmdUpgrade(args: string[], ctx: {
+    json: boolean;
+}, deps?: UpgradeDeps): Promise<string>;