hafez 1.0.1 → 1.0.2

package/README.md

@@ -16,11 +16,9 @@ Claude Code (or any agent with shell access):
 ```text
 Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 
-1. Install the CLI (needs Node.js 22+ and git):
-   npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
-   On npm 12+, append --allow-remote=root --allow-scripts=better-sqlite3
-   (npm 12 blocks URL-tarball installs and install scripts by default;
-   the SQLite bindings need their install script).
+1. Install the CLI (needs Node.js 22+ and git): npm install -g hafez
+   On npm 12+, append --allow-scripts=better-sqlite3 (npm 12 blocks install
+   scripts by default; the SQLite bindings need theirs).
 2. Check git identity is configured (git config user.name and user.email);
    if not, ask me for a name and email and set them with git config --global.
 3. Create my vault — a git repo with entities/ and knowledge/ directories and an
@@ -43,8 +41,8 @@ The same thing by hand:
 
 ```bash
 # Install (Node.js 22+ and git required).
-# On npm 12+, append: --allow-remote=root --allow-scripts=better-sqlite3
-npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
+# On npm 12+, append: --allow-scripts=better-sqlite3
+npm install -g hafez
 
 # One-time, if you've never used git on this machine:
 #   git config --global user.name "Your Name"
@@ -61,9 +59,9 @@ mkdir -p ~/.claude/skills/hafez
 cp "$(npm root -g)/hafez/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
 ```
 
-On npm ≤11, `npm install -g github:shrvn-r/hafez` also works (npm 12 disables
-git installs by default). An npm registry package is planned; GitHub is the
-distribution channel for now.
+Prefer installing without the npm registry? The GitHub release tarball is the
+same artifact: `npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz`
+(npm 12+ additionally needs `--allow-remote=root`).
 
 ## Quick start
 

package/dist/cli/commands.d.ts

@@ -10,10 +10,7 @@ export declare function cmdCreate(os: Hafez, args: string[], opts?: CommandOpts)
 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>;
-/**
- * Top-level capture command — aliases to the same handler used by
- * `hafez create inbox`. Added to align the CLI verb with the batch op name.
- */
+/** Top-level capture command — aligns the CLI verb with the batch op name. */
 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>;
@@ -107,27 +104,26 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     slug: z.ZodString;
     target: z.ZodString;
     relation: z.ZodEnum<{
-        related: "related";
         parent: "parent";
+        related: "related";
     }>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"unlink">;
     slug: z.ZodString;
     target: z.ZodString;
     relation: z.ZodEnum<{
-        related: "related";
         parent: "parent";
+        related: "related";
     }>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"promote">;
     slug: z.ZodString;
     target: z.ZodEnum<{
         entity: "entity";
-        knowledge: "knowledge";
         project: "project";
+        knowledge: "knowledge";
     }>;
 }, z.core.$strict>], "op">;
 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 cmdMigrateKnowledgeV2(args: string[], vaultPath: string): Promise<void>;

package/dist/cli/commands.js

@@ -5,7 +5,6 @@ import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VA
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
-import { migrateKnowledgeV2 } from '../migrate-knowledge-v2.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
@@ -105,16 +104,7 @@ export async function cmdSearch(os, args, opts = {}) {
 export async function cmdCreate(os, args, opts = {}) {
     const kind = args[0];
     if (!kind)
-        throw new Error('Usage: hafez create <entity|knowledge|inbox> <name> [options]');
-    if (kind === 'inbox') {
-        const name = positionalArgs(args.slice(1)).join(' ');
-        if (!name)
-            throw new Error('Usage: hafez create inbox <name> [--notes "text"]');
-        const notes = getFlag(args, '--notes');
-        process.stderr.write('Warning: `hafez create inbox` is deprecated. Use `hafez capture <name>` instead.\n');
-        const slug = await os.capture(name, notes);
-        return opts.json ? jsonOut({ slug }) : slug;
-    }
+        throw new Error('Usage: hafez create <entity|knowledge> <name> [options]');
     const name = positionalArgs(args.slice(1)).join(' ');
     if (!name)
         throw new Error(`Usage: hafez create ${kind} <name> [options]`);
@@ -147,7 +137,7 @@ export async function cmdCreate(os, args, opts = {}) {
         });
         return opts.json ? jsonOut({ slug }) : slug;
     }
-    throw new Error(`Unknown kind: ${kind}. Use entity, knowledge, or inbox.`);
+    throw new Error(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
 export async function cmdUpdate(os, args, opts = {}) {
     const slug = args[0];
@@ -157,13 +147,11 @@ export async function cmdUpdate(os, args, opts = {}) {
     const status = getFlag(args, '--status');
     if (status)
         fields.status = status;
-    // Legacy --next-action: deprecation notice
-    const nextAction = getFlag(args, '--next-action');
-    if (nextAction !== undefined) {
-        process.stderr.write('Warning: --next-action is deprecated. Use --add-action instead.\n');
-        fields.add_action = nextAction === '' ? undefined : nextAction;
-        if (nextAction === '')
-            fields.clear_actions = true;
+    // 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.');
     }
     const currentState = getFlag(args, '--current-state');
     if (currentState)
@@ -235,18 +223,10 @@ export async function cmdUpdate(os, args, opts = {}) {
     }
     return lines.join('\n');
 }
-/**
- * Parse link/unlink args, supporting both the legacy positional form
- * (`hafez link <slug> <target> <parent|related>`) and the new
- * `--relation <value>` named flag. Positional remains accepted as a
- * deprecated alias — emits a one-line warning to stderr.
- */
 function parseLinkArgs(args, verb) {
-    const relationFlag = getFlag(args, '--relation');
+    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 to prevent it from being
-    // mistaken for a positional if someone passes both forms. Here we only
-    // consume the flag once above.
+    // (getFlag does NOT splice), so strip it manually before reading positionals.
     const positionals = args.filter((a, i) => {
         if (a === '--relation')
             return false;
@@ -254,18 +234,10 @@ function parseLinkArgs(args, verb) {
             return false;
         return !a.startsWith('--');
     });
-    const [slug, target, positionalRelation] = positionals;
-    if (!slug || !target) {
+    const [slug, target] = positionals;
+    if (!slug || !target || !relation) {
         throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
     }
-    let relation = relationFlag;
-    if (!relation) {
-        if (!positionalRelation) {
-            throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
-        }
-        relation = positionalRelation;
-        process.stderr.write(`Warning: positional relation is deprecated. Use: hafez ${verb} ${slug} ${target} --relation ${relation}\n`);
-    }
     if (!['parent', 'related'].includes(relation)) {
         throw new Error(`Invalid relation: ${relation}. Must be parent or related.`);
     }
@@ -281,10 +253,7 @@ export async function cmdUnlink(os, args, opts = {}) {
     await os.unlink(slug, target, relation);
     return opts.json ? jsonOut({ slug, target, relation }) : `Unlinked ${slug} — ${target} (${relation})`;
 }
-/**
- * Top-level capture command — aliases to the same handler used by
- * `hafez create inbox`. Added to align the CLI verb with the batch op name.
- */
+/** Top-level capture command — aligns the CLI verb with the batch op name. */
 export async function cmdCapture(os, args, opts = {}) {
     const name = positionalArgs(args).join(' ');
     if (!name)
@@ -584,28 +553,6 @@ export async function cmdDigest(os, _args, _opts = {}) {
     const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
-export async function cmdMigrateKnowledgeV2(args, vaultPath) {
-    const apply = args.includes('--apply');
-    const report = migrateKnowledgeV2(vaultPath, { apply });
-    console.log(`## Migration: knowledge-v2 ${apply ? '(APPLIED)' : '(dry run)'}`);
-    console.log(`- Sessions to move: ${report.sessionsToMove.length}`);
-    for (const f of report.sessionsToMove)
-        console.log(`  - ${f}`);
-    console.log(`- Empty notes to delete: ${report.emptyToDelete.length}`);
-    for (const f of report.emptyToDelete)
-        console.log(`  - ${f}`);
-    console.log(`- ## Insight → ## Synthesis: ${report.insightToRename.length}`);
-    for (const f of report.insightToRename)
-        console.log(`  - ${f}`);
-    console.log(`- ## Related to generate: ${report.relatedToGenerate.length}`);
-    for (const f of report.relatedToGenerate)
-        console.log(`  - ${f}`);
-    console.log(`- .gitignore needs update: ${report.gitignoreNeeded}`);
-    if (apply && report.gitCommitFailed)
-        console.log('⚠ Warning: git commit failed — changes are applied but not committed.');
-    if (!apply)
-        console.log('\nRun with --apply to execute migration.');
-}
 // --- Arg helpers ---
 function getFlag(args, flag) {
     const idx = args.indexOf(flag);

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { createHafez } from '../index.js';
 import { HafezError } from '../types.js';
-import { cmdRead, cmdQuery, cmdSearch, cmdCreate, cmdUpdate, cmdLink, cmdUnlink, cmdPromote, cmdValidate, cmdIndexRebuild, cmdBatch, cmdSync, cmdStats, cmdChangelog, cmdDigest, cmdMigrateKnowledgeV2, cmdCapture } from './commands.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 { resolveVaultPath, noVaultMessage, cmdInit } from './resolve-vault.js';
@@ -38,7 +38,7 @@ Commands:
   read <slug>                Read entity or knowledge note
   query [--filter ...] ...   Filter entities/knowledge
   search <terms>             Full-text search
-  create <kind> <name>       Create entity, knowledge, or inbox
+  create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
   promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
   update <slug> [--status]   Update an entity or knowledge note
@@ -56,12 +56,8 @@ Commands:
   digest                     Apply digest input (JSON stdin) → batch payload (JSON stdout)
   export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)
   sync                       Pull remote changes and push local commits
-  migrate next-actions       Migrate next-action frontmatter to body sections
-  migrate types              Migrate vault to v2 type system (dry-run by default)
-  migrate knowledge-v2       Migrate knowledge notes to v2 section structure (dry-run by default)
-    --apply                  Execute migration (writes files, does not commit)
-  link <slug> <target> <rel> Add a link
-  unlink <slug> <target> <rel> Remove a link
+  link <slug> <target> --relation <rel>    Add a link
+  unlink <slug> <target> --relation <rel>  Remove a link
   stats                      Vault summary: counts, stale items, recents
   changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)
   schema [op] [--examples]   Machine-readable JSON schema for batch operations
@@ -184,64 +180,6 @@ export async function main(argv) {
         }
         return;
     }
-    // migrate runs before Hafez instance creation
-    if (command === 'migrate') {
-        const subcommand = args[0];
-        if (subcommand === 'next-actions') {
-            const { migrateNextActions } = await import('../migrate-next-actions.js');
-            const apply = args.includes('--apply');
-            const report = migrateNextActions(vaultPath, apply);
-            const lines = [];
-            if (!apply)
-                lines.push('DRY RUN — use --apply to execute');
-            lines.push(`Candidates: ${report.candidates}`);
-            if (apply)
-                lines.push(`Migrated: ${report.migrated}`);
-            for (const d of report.details)
-                lines.push(`  ${d}`);
-            process.stdout.write(lines.join('\n') + '\n');
-            return;
-        }
-        if (subcommand === 'types') {
-            const { migrateTypes } = await import('../migrate-types.js');
-            const apply = args.includes('--apply');
-            const report = migrateTypes(vaultPath, apply);
-            const lines = [];
-            if (!apply) {
-                lines.push('DRY RUN — use --apply to execute');
-                lines.push('');
-            }
-            lines.push(`Type renames:         ${report.typeChanges}`);
-            lines.push(`Status renames:       ${report.statusChanges}`);
-            lines.push(`Subtypes added:       ${report.knowledgeSubtypeAdded}`);
-            lines.push(`Body restructures:    ${report.bodySectionsRestructured}`);
-            lines.push(`Malformed (skipped):  ${report.malformed.length}`);
-            if (report.malformed.length > 0) {
-                lines.push('');
-                lines.push('Malformed files (no type field):');
-                for (const f of report.malformed)
-                    lines.push(`  ⚠ ${f}`);
-            }
-            if (report.details.length > 0) {
-                lines.push('');
-                lines.push('Changes:');
-                for (const d of report.details)
-                    lines.push(`  ${d}`);
-            }
-            if (apply) {
-                lines.push('');
-                lines.push('Migration applied. Run `hafez index rebuild` to refresh the index.');
-            }
-            process.stdout.write(lines.join('\n') + '\n');
-            return;
-        }
-        if (subcommand === 'knowledge-v2') {
-            await cmdMigrateKnowledgeV2(args.slice(1), vaultPath);
-            return;
-        }
-        process.stderr.write('Usage: hafez migrate <next-actions|types|knowledge-v2> [--apply]\n');
-        process.exit(1);
-    }
     // sync is handled specially — always runs, not gated by MUTATING_COMMANDS
     if (command === 'sync') {
         const os = createHafez({ vaultPath, git: { push: false } });

package/dist/db.js

@@ -88,7 +88,9 @@ function hashContent(content) {
 }
 function scanDir(dirPath) {
     try {
-        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
+        // Skip dotfiles: their slugs are rejected by resolveFilePath, so indexing
+        // them would list entities that read/update can never reach.
+        return readdirSync(dirPath).filter(f => f.endsWith('.md') && !f.startsWith('.')).map(f => join(dirPath, f));
     }
     catch {
         return [];
@@ -401,46 +403,65 @@ export function createIndex(vaultPath, opts) {
     // The db files are a disposable local cache — keep them out of the user's
     // `git status` without dirtying their vault with a tracked .gitignore.
     ensureLocalExclude(vaultPath);
+    function removeDbFiles() {
+        // The -wal/-shm siblings must go too: a fresh db next to a stale WAL is
+        // itself corrupt.
+        for (const suffix of ['', '-wal', '-shm']) {
+            try {
+                unlinkSync(dbPath + suffix);
+            }
+            catch { /* may not exist */ }
+        }
+    }
+    function openDb() {
+        const fresh = new Database(dbPath);
+        try {
+            fresh.pragma('journal_mode = WAL');
+            fresh.pragma('busy_timeout = 5000');
+            fresh.pragma('foreign_keys = ON');
+            fresh.exec(SCHEMA);
+            return fresh;
+        }
+        catch (err) {
+            // Close before the caller unlinks — on filesystems without POSIX
+            // delete-while-open semantics, unlinking an open db fails silently and
+            // recovery would just reopen the same corrupt file.
+            try {
+                fresh.close();
+            }
+            catch { /* already unusable */ }
+            throw err;
+        }
+    }
     let db;
     try {
-        db = new Database(dbPath);
+        db = openDb();
     }
     catch {
-        // Corrupted DB — delete and recreate
-        try {
-            unlinkSync(dbPath);
-        }
-        catch { }
-        db = new Database(dbPath);
+        // Corrupted DB (garbage bytes, truncated WAL checkpoint). better-sqlite3
+        // doesn't touch the file until the first statement, so corruption surfaces
+        // at the pragma/exec inside openDb, not at the constructor — the whole
+        // open sequence must be inside this catch. The index is a disposable
+        // cache: delete and rebuild.
+        removeDbFiles();
+        db = openDb();
     }
-    db.pragma('journal_mode = WAL');
-    db.pragma('busy_timeout = 5000');
-    db.pragma('foreign_keys = ON');
-    db.exec(SCHEMA);
     // Schema migration: if next_action_count column missing, delete DB and recreate
     try {
         db.prepare('SELECT next_action_count FROM items LIMIT 0').run();
     }
     catch {
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
     }
     // Schema migration: if domain_entity column exists, delete DB and recreate
     try {
         db.prepare('SELECT domain_entity FROM items LIMIT 0').run();
         // Column exists — old schema, needs rebuild
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
     }
     catch {
         // Column doesn't exist — correct schema, continue
@@ -449,12 +470,8 @@ export function createIndex(vaultPath, opts) {
     const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     if (!versionRow || versionRow.value !== SCHEMA_VERSION) {
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
         db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
     }
     // Prepared statements
@@ -496,9 +513,8 @@ export function createIndex(vaultPath, opts) {
             process.stderr.write(`Warning: skipping ${kind}/${slug}.md: missing required field(s): ${missing}\n`);
             return;
         }
-        // Parse next actions from body (new), fall back to frontmatter (legacy pre-migration)
         const bodyActions = getNextActions(body);
-        const nextAction = bodyActions.length > 0 ? bodyActions[0] : (fm['next-action'] ?? null);
+        const nextAction = bodyActions.length > 0 ? bodyActions[0] : null;
         const nextActionCount = bodyActions.length;
         const brief = getBrief(body)?.slice(0, 300) ?? null;
         const logs = parseSessionLog(body);

package/dist/export-okf.js

@@ -1,7 +1,7 @@
 // src/export-okf.ts
 // Read-only export of the vault as an OKF v0.1 bundle (entities + knowledge + sessions).
 // Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
-// Pure sync function — no Hafez instance, index, git, or lock (mirrors migrate-*.ts).
+// Pure sync function — no Hafez instance, index, git, or lock.
 // Re-export overwrites a prior bundle in place but never deletes: files for vault
 // docs renamed or removed since the last export linger (unreferenced by the
 // regenerated indexes) until the bundle directory is deleted and re-exported.

package/dist/git.d.ts

@@ -8,5 +8,12 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
+/**
+ * Unstage files (best effort). Used by batch rollback: a commit that fails
+ * after `git add` leaves the new blobs staged in .git/index, and the next
+ * successful commit would publish the rolled-back content under the wrong
+ * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ */
+export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
 export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;