@hasna/hooks 0.7.8 → 0.7.10

package/dist/lib/app-home.d.ts

@@ -0,0 +1,65 @@
+/**
+ * App-home resolution for @hasna/hooks — routes the local data root through
+ * the @hasna/paths resolver (XDG / macOS home layout) with gated legacy
+ * adoption.
+ *
+ * The XDG home migration (hotfixes plan 0f49f56a, task P3.3) moves the store
+ * from `~/.hasna/hooks` toward `~/.local/share/hasna/hooks` on Linux and
+ * `~/Library/Application Support/Hasna/hooks` on macOS. Nothing moves on disk
+ * in this phase — the resolver root is adopted only when the operator has
+ * deliberately opted in (`HASNA_DATA_HOME`) or the store has already been
+ * physically migrated there, so a live store at the legacy home never becomes
+ * invisible on upgrade.
+ */
+/** Resolve the user's home directory: $HOME, then $USERPROFILE, then the OS user database. */
+export declare function getHomeDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * The @hasna/paths-resolved (XDG / macOS layout) data root for hooks: the
+ * forward-looking home the XDG migration moves the store toward. The home
+ * override mirrors the pre-existing $HOME-first resolution so the resolver
+ * follows the same home the legacy path does.
+ */
+export declare function getResolverDataRoot(env?: NodeJS.ProcessEnv): string;
+/** The legacy (pre-XDG) data root: ~/.hasna/hooks */
+export declare function getLegacyDataRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether the resolver (XDG) data root should be adopted as the effective data
+ * root. The resolver root is adopted only when the operator has set
+ * `HASNA_DATA_HOME` (the data-kind override — a deliberate opt-in to the XDG
+ * layout) or the store has already been physically migrated there (`hooks.db`
+ * exists). A machine that only redirects another kind (e.g. cache to tmpfs)
+ * must NOT have its data home moved, and a live store at the legacy home must
+ * never become invisible on upgrade.
+ */
+export declare function adoptResolverDataRoot(resolved: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The granular data-dir override root, when set: `HASNA_HOOKS_DATA_DIR`, then
+ * `HOOKS_DATA_DIR`. This preserves the pre-existing exact-data-dir override
+ * behavior verbatim (first-nonblank; a set-but-empty value falls through).
+ */
+export declare function getExplicitDataDir(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The exact-app override root, when set: `HASNA_HOOKS_HOME`, then `HOOKS_HOME`.
+ * First-nonblank selection: a set-but-whitespace override must not suppress a
+ * valid fallback (the same `?.trim() ||` semantics the emails lane settled as
+ * release-review P1).
+ */
+export declare function getExactDataRoot(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The effective data root for hooks. Precedence: the granular data-dir
+ * override (`HASNA_HOOKS_DATA_DIR`/`HOOKS_DATA_DIR`) wins; then the exact-app
+ * override (`HASNA_HOOKS_HOME`/`HOOKS_HOME`); then the resolver (XDG) data
+ * root once adopted; then the legacy `~/.hasna/hooks` default — a live store
+ * never becomes invisible on upgrade. Store/lock/config paths are layered on
+ * top of this by their own overrides, so an explicit path always wins
+ * regardless.
+ */
+export declare function getEffectiveDataRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * The SQLite store path surfaced by help/status surfaces (e.g. `hooks log`,
+ * registry hook descriptions). The explicit `HASNA_HOOKS_DB_PATH` /
+ * `HOOKS_DB_PATH` override wins; otherwise `hooks.db` under the effective data
+ * root. A status surface must never hardcode the legacy literal — the store can
+ * live at the resolver home once adopted.
+ */
+export declare function getReportedDbPath(env?: NodeJS.ProcessEnv): string;

package/dist/lib/profiles.d.ts

@@ -1,7 +1,10 @@
 /**
  * Agent profile management — identity system for hooks
  *
- * Each agent instance gets a unique 8-char UUID stored at ~/.hasna/hooks/profiles/<id>.json.
+ * Each agent instance gets a unique 8-char UUID stored at
+ * <effective-data-root>/profiles/<id>.json, where the effective data root is
+ * resolved through @hasna/paths (legacy ~/.hasna/hooks until adopted, then
+ * the XDG data home).
  * Profiles are injected into HookInput when hooks are run with --profile <id>,
  * allowing hooks to identify which agent is calling them.
  */

package/dist/serve.d.ts

@@ -31,6 +31,13 @@ export interface ArtifactPayload {
     script: string;
 }
 export declare function handleServeRequest(req: Request, apiKey: string | undefined): Promise<Response>;
+export declare function resolveServeOptions(options: {
+    port?: number;
+    host?: string;
+}): {
+    port: number;
+    host: string;
+};
 export declare function startServeServer(options: {
     port?: number;
     host?: string;

package/dist/storage.js

@@ -15,6 +15,132 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
+// ../../node_modules/.bun/@hasna+paths@0.1.0/node_modules/@hasna/paths/dist/index.js
+import { homedir } from "os";
+import { join } from "path";
+function assertApp(app) {
+  if (typeof app !== "string" || app.length === 0) {
+    throw new TypeError("paths: app must be a non-empty string");
+  }
+  if (!APP_SLUG_RE.test(app)) {
+    throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
+  }
+}
+function envOf(options) {
+  return options.env ?? process.env;
+}
+function envValue(options, kind) {
+  const value = envOf(options)[KIND_ENV[kind]];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isMacOS(platform) {
+  return platform === "darwin";
+}
+function baseDir(kind, options) {
+  const override = envValue(options, kind);
+  if (override)
+    return override;
+  const home = options.home ?? homedir();
+  const platform = options.platform ?? process.platform;
+  if (isMacOS(platform)) {
+    switch (kind) {
+      case "config":
+      case "data":
+        return join(home, "Library", "Application Support", "Hasna");
+      case "cache":
+        return join(home, "Library", "Caches", "Hasna");
+      case "state":
+        return join(home, "Library", "Logs", "Hasna");
+    }
+  }
+  switch (kind) {
+    case "config":
+      return join(home, ".config", "hasna");
+    case "data":
+      return join(home, ".local", "share", "hasna");
+    case "state":
+      return join(home, ".local", "state", "hasna");
+    case "cache":
+      return join(home, ".cache", "hasna");
+  }
+}
+function resolvePath(kind, options) {
+  assertApp(options.app);
+  const appSegment = options.internal === true ? join("internal", options.app) : options.app;
+  return join(baseDir(kind, options), appSegment);
+}
+function dataDir(options) {
+  return resolvePath("data", options);
+}
+var KIND_ENV, APP_SLUG_RE;
+var init_dist = __esm(() => {
+  KIND_ENV = {
+    config: "HASNA_CONFIG_HOME",
+    data: "HASNA_DATA_HOME",
+    state: "HASNA_STATE_HOME",
+    cache: "HASNA_CACHE_HOME"
+  };
+  APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+});
+
+// src/lib/app-home.ts
+import { existsSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2, resolve } from "path";
+function getHomeDir(env = process.env) {
+  return env.HOME || env.USERPROFILE || homedir2();
+}
+function getResolverDataRoot(env = process.env) {
+  return dataDir({ app: "hooks", home: getHomeDir(env), env });
+}
+function getLegacyDataRoot(env = process.env) {
+  return join2(getHomeDir(env), ".hasna", "hooks");
+}
+function adoptResolverDataRoot(resolved, env = process.env) {
+  const dataOverride = env.HASNA_DATA_HOME;
+  if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
+    return true;
+  return existsSync(join2(resolved, STORE_MARKER));
+}
+function getExplicitDataDir(env = process.env) {
+  const dir = env.HASNA_HOOKS_DATA_DIR ?? env.HOOKS_DATA_DIR;
+  if (typeof dir === "string" && dir.trim().length > 0)
+    return dir.trim();
+  return;
+}
+function getExactDataRoot(env = process.env) {
+  const dir = env.HASNA_HOOKS_HOME?.trim() || env.HOOKS_HOME?.trim();
+  if (dir)
+    return resolve(dir);
+  return;
+}
+function getEffectiveDataRoot(env = process.env) {
+  const explicit = getExplicitDataDir(env);
+  if (explicit)
+    return explicit;
+  const exact = getExactDataRoot(env);
+  if (exact)
+    return exact;
+  const resolved = getResolverDataRoot(env);
+  return adoptResolverDataRoot(resolved, env) ? resolve(resolved) : getLegacyDataRoot(env);
+}
+function getReportedDbPath(env = process.env) {
+  const explicit = getExplicitDbPath(env);
+  if (explicit)
+    return explicit;
+  return join2(getEffectiveDataRoot(env), "hooks.db");
+}
+function getExplicitDbPath(env = process.env) {
+  const db = env.HASNA_HOOKS_DB_PATH ?? env.HOOKS_DB_PATH;
+  if (typeof db === "string" && db.trim().length > 0)
+    return db.trim();
+  return;
+}
+var STORE_MARKER = "hooks.db";
+var init_app_home = __esm(() => {
+  init_dist();
+});
+
 // src/db/schema.ts
 var CREATE_HOOK_EVENTS_TABLE = `
   CREATE TABLE IF NOT EXISTS hook_events (
@@ -209,9 +335,9 @@ var init_migrations = __esm(() => {
 });
 
 // src/db/legacy-import.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
+import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir3 } from "os";
 function ensureMetaTable(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS _meta (
@@ -285,25 +411,25 @@ function importErrorsLog(db, filePath) {
   } catch {}
   return count;
 }
-function runLegacyImport(db, homeDir = homedir()) {
+function runLegacyImport(db, homeDir = homedir3()) {
   try {
     if (isAlreadyDone(db))
       return;
     let total = 0;
-    const claudeProjectsDir = join(homeDir, ".claude", "projects");
-    if (existsSync(claudeProjectsDir)) {
+    const claudeProjectsDir = join3(homeDir, ".claude", "projects");
+    if (existsSync2(claudeProjectsDir)) {
       try {
         const projectDirs = readdirSync(claudeProjectsDir);
         for (const dir of projectDirs) {
-          const projectDir = join(claudeProjectsDir, dir);
+          const projectDir = join3(claudeProjectsDir, dir);
           try {
             const files = readdirSync(projectDir);
             for (const file of files) {
               if (file.match(/^session-log-\d{4}-\d{2}-\d{2}\.jsonl$/)) {
-                total += importJsonlFile(db, join(projectDir, file));
+                total += importJsonlFile(db, join3(projectDir, file));
               }
               if (file === "errors.log") {
-                total += importErrorsLog(db, join(projectDir, file));
+                total += importErrorsLog(db, join3(projectDir, file));
               }
             }
           } catch {}
@@ -339,31 +465,27 @@ function runRetention(db, days) {
 
 // src/db/index.ts
 import { Database } from "bun:sqlite";
-import { existsSync as existsSync2, mkdirSync, cpSync } from "fs";
-import { join as join2 } from "path";
-import { homedir as homedir2 } from "os";
+import { existsSync as existsSync3, mkdirSync, cpSync } from "fs";
+import { join as join4 } from "path";
 function resolveDataDir() {
-  const explicit = process.env.HASNA_HOOKS_DATA_DIR ?? process.env.HOOKS_DATA_DIR;
-  if (explicit)
-    return explicit;
-  const newDir = join2(homedir2(), ".hasna", "hooks");
-  const oldDir = join2(homedir2(), ".hooks");
-  if (!existsSync2(newDir) && existsSync2(oldDir)) {
-    mkdirSync(join2(homedir2(), ".hasna"), { recursive: true });
-    cpSync(oldDir, newDir, { recursive: true });
+  const effective = getEffectiveDataRoot();
+  const oldDir = join4(getHomeDir(), ".hooks");
+  if (!existsSync3(effective) && existsSync3(oldDir)) {
+    mkdirSync(effective, { recursive: true });
+    cpSync(oldDir, effective, { recursive: true });
   }
-  return newDir;
+  return effective;
 }
 function getDbPath() {
   const explicitDb = process.env.HASNA_HOOKS_DB_PATH ?? process.env.HOOKS_DB_PATH;
   if (explicitDb)
     return explicitDb;
-  const dataDir = resolveDataDir();
-  return join2(dataDir, "hooks.db");
+  const dataDir2 = resolveDataDir();
+  return join4(dataDir2, "hooks.db");
 }
 function ensureDir(dbPath) {
   const dir = dbPath.substring(0, dbPath.lastIndexOf("/"));
-  if (dir && !existsSync2(dir)) {
+  if (dir && !existsSync3(dir)) {
     mkdirSync(dir, { recursive: true });
   }
 }
@@ -371,7 +493,7 @@ function getDb() {
   if (instance)
     return instance;
   const dbPath = getDbPath();
-  const isNew = dbPath === ":memory:" || !existsSync2(dbPath);
+  const isNew = dbPath === ":memory:" || !existsSync3(dbPath);
   ensureDir(dbPath);
   instance = new Database(dbPath);
   instance.exec("PRAGMA busy_timeout=5000");
@@ -395,6 +517,7 @@ function getDb() {
 }
 var instance = null;
 var init_db = __esm(() => {
+  init_app_home();
   init_migrations();
   init_legacy_import();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "dashboard:dev": "cd dashboard && bun run dev",
     "dashboard:build": "cd dashboard && bun run build",
     "dashboard:preview": "cd dashboard && bun run preview",
-    "postinstall": "mkdir -p $HOME/.hasna/hooks/profiles 2>/dev/null || true",
+    "postinstall": "node scripts/ensure-profiles-dir.mjs",
     "scan:artifact": "bun scripts/artifact-scan.ts",
     "prepack": "bun run build && bun run scan:artifact"
   },
@@ -52,10 +52,11 @@
     "@types/react": "^18.2.0",
     "typescript": "^5",
     "bun-types": "1.3.14",
-    "@hasna/contracts": "0.14.0"
+    "@hasna/contracts": "0.14.1"
   },
   "dependencies": {
     "@hasna/events": "^0.1.16",
+    "@hasna/paths": "0.1.0",
     "@hasna/secrets": "0.3.10",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
@@ -68,7 +69,7 @@
     "pg": "^8.16.3",
     "react": "^18.2.0",
     "zod": "3.25.76",
-    "@hasna/contracts": "0.14.0"
+    "@hasna/contracts": "0.14.1"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -82,6 +83,7 @@
     "dist/",
     "hooks/",
     "!hooks/*/dist/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],

package/scripts/artifact-scan.ts

@@ -0,0 +1,49 @@
+// Pack this repo the way `npm publish` would, then scan what actually shipped.
+//
+// `contracts artifact-scan` takes a PACKED .tgz — running it against `src/` is
+// explicitly wrong, and running it with no target at all just exits 1 and takes
+// `npm pack` / `bun publish` down with it. So this script produces the tarball
+// first and hands the real artifact to the scanner.
+//
+// Packing uses `--ignore-scripts`: without it, packing from inside `prepack`
+// would re-enter `prepack` forever.
+//
+// The scanner comes from the pinned `@hasna/contracts` devDependency
+// (node_modules/.bin), never `bunx` — an unpinned package runner makes the
+// release gate depend on whatever the registry serves that day.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+function run(command: string[], cwd: string): string {
+  const result = Bun.spawnSync(command, { cwd, stdout: "pipe", stderr: "pipe" });
+  const stdout = new TextDecoder().decode(result.stdout).trim();
+  if (result.exitCode !== 0) {
+    const stderr = new TextDecoder().decode(result.stderr).trim();
+    throw new Error(`${command.join(" ")} exited ${result.exitCode}\n${stdout}\n${stderr}`);
+  }
+  return stdout;
+}
+
+const repoRoot = join(import.meta.dir, "..");
+const scanner = join(repoRoot, "node_modules", "@hasna", "contracts", "dist", "cli", "index.js");
+const workspace = mkdtempSync(join(tmpdir(), "hooks-artifact-scan-"));
+
+try {
+  const packed = run(["bun", "pm", "pack", "--destination", workspace, "--ignore-scripts", "--quiet"], repoRoot);
+  const archive = isAbsolute(packed) ? packed : join(workspace, packed);
+  // The manifest is where a reviewed waiver would be declared, so the scanner
+  // has to read it; a waiver the enforcement never loads is a dead end.
+  const scan = Bun.spawnSync([scanner, "artifact-scan", archive, "--manifest", join(repoRoot, "hasna.contract.json")], {
+    cwd: repoRoot,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  if (scan.exitCode !== 0) {
+    console.error("\nA published artifact must not carry a bulk asset inventory.");
+    process.exit(scan.exitCode ?? 1);
+  }
+} finally {
+  rmSync(workspace, { recursive: true, force: true });
+}

package/scripts/ensure-profiles-dir.mjs

@@ -0,0 +1,48 @@
+// Ensure the hooks agent-profile directory exists at the effective data root.
+// Runs at install time (postinstall). Mirrors src/lib/app-home.ts resolution:
+// granular data-dir override (HASNA_HOOKS_DATA_DIR/HOOKS_DATA_DIR), then
+// exact-app override (HASNA_HOOKS_HOME/HOOKS_HOME), then the @hasna/paths
+// resolver data root once adopted (HASNA_DATA_HOME set or hooks.db already
+// present there), then the legacy ~/.hasna/hooks default. Best-effort — the
+// package must never fail to install because this script cannot run.
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const HOME = process.env.HOME || process.env.USERPROFILE || homedir();
+
+function legacyDataRoot() {
+  return join(HOME, ".hasna", "hooks");
+}
+
+function adoptResolverRoot(resolved) {
+  const override = process.env.HASNA_DATA_HOME;
+  if (typeof override === "string" && override.trim().length > 0) return true;
+  return existsSync(join(resolved, "hooks.db"));
+}
+
+async function effectiveDataRoot() {
+  const explicit = process.env.HASNA_HOOKS_DATA_DIR ?? process.env.HOOKS_DATA_DIR;
+  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
+
+  const exact = process.env.HASNA_HOOKS_HOME?.trim() || process.env.HOOKS_HOME?.trim();
+  if (exact) return resolve(exact);
+
+  let resolved = null;
+  try {
+    const { dataDir } = await import("@hasna/paths");
+    resolved = dataDir({ app: "hooks", home: HOME });
+  } catch {
+    // @hasna/paths unavailable — fall back to the legacy root.
+  }
+  if (resolved && adoptResolverRoot(resolved)) return resolve(resolved);
+  return legacyDataRoot();
+}
+
+// Best-effort: a profile-directory creation failure must never block install.
+try {
+  const root = await effectiveDataRoot();
+  mkdirSync(join(root, "profiles"), { recursive: true });
+} catch {
+  // ignore
+}