@gmickel/gno 2.4.0 → 2.6.0

package/src/sessions/binding.ts

@@ -0,0 +1,105 @@
+/**
+ * Archive config/index binding.
+ *
+ * A session archive is one dedicated config file paired with one named
+ * index. The config side records the pair in `sessions.index`; the index side
+ * records the canonical config path in `schema_meta`. Opening either half
+ * with the wrong partner fails instead of silently pulling archive
+ * collections into a curated index, or curated collections into the archive
+ * index.
+ *
+ * @module src/sessions/binding
+ */
+
+import { Database } from "bun:sqlite";
+
+// Configures the platform SQLite before any Database opens (macOS).
+import "../store/sqlite/setup";
+import type { Config } from "../config/types";
+
+import { canonicalizeIndexName, isValidIndexName } from "../app/index-name";
+import { canonicalOperationalPath } from "../core/config-write-lock";
+import { SessionsError } from "./types";
+
+/** `schema_meta` key naming the archive config an index is bound to. */
+const SESSION_BINDING_META_KEY = "session_archive_config";
+
+/**
+ * Canonical identity of a config path: the same resolution the config writer
+ * uses for its write target and lock. An existing file realpaths; a missing
+ * one (init checks the binding before writing it) resolves through its
+ * nearest existing ancestor, and a dangling symlink through its target, so
+ * the marker matches the path the file later realpaths to (e.g. macOS `/var`
+ * -> `/private/var`, Windows short or case variants).
+ */
+export function canonicalConfigPath(configPath: string): Promise<string> {
+  return canonicalOperationalPath(configPath);
+}
+
+/** Read the binding marker of an index database without creating it. */
+export function readIndexBinding(dbPath: string): string | null {
+  let db: Database | undefined;
+  try {
+    db = new Database(dbPath, { readonly: true });
+    const table = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_meta'"
+      )
+      .get();
+    if (!table) return null;
+    const row = db
+      .query<{ value: string }, [string]>(
+        "SELECT value FROM schema_meta WHERE key = ?"
+      )
+      .get(SESSION_BINDING_META_KEY);
+    return row?.value ?? null;
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
+/** Record the archive binding on an index the caller already opened. */
+export function writeIndexBinding(db: Database, configPath: string): void {
+  db.run(
+    `INSERT INTO schema_meta (key, value, updated_at) VALUES (?, ?, datetime('now'))
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`,
+    [SESSION_BINDING_META_KEY, configPath]
+  );
+}
+
+function sameIndex(left: string, right: string): boolean {
+  if (!(isValidIndexName(left) && isValidIndexName(right)))
+    return left === right;
+  return canonicalizeIndexName(left) === canonicalizeIndexName(right);
+}
+
+/**
+ * Fail when the config/index pair contradicts a recorded archive binding.
+ * `dbPath` may point to a database that does not exist yet.
+ */
+export async function assertSessionBinding(options: {
+  config: Config;
+  configPath: string;
+  indexName: string;
+  dbPath: string;
+}): Promise<void> {
+  const bound = options.config.sessions?.index;
+  if (bound !== undefined && !sameIndex(bound, options.indexName)) {
+    throw new SessionsError(
+      "SESSIONS_BINDING_MISMATCH",
+      `This config is a session archive config bound to index "${bound}", but index "${options.indexName}" was selected. Pass --index ${bound} together with this --config.`
+    );
+  }
+  if (!(await Bun.file(options.dbPath).exists())) return;
+  const marker = readIndexBinding(options.dbPath);
+  if (marker === null) return;
+  const configPath = await canonicalConfigPath(options.configPath);
+  if (marker !== configPath) {
+    throw new SessionsError(
+      "SESSIONS_BINDING_MISMATCH",
+      `Index "${options.indexName}" is a session archive bound to a different config file. Pass the archive's --config with --index ${options.indexName}; curated configs cannot open it.`
+    );
+  }
+}

package/src/sessions/claude-hook.ts

@@ -0,0 +1,240 @@
+/**
+ * Claude Code SessionEnd hook: owned-entry install, removal and inspection.
+ *
+ * GNO edits only the one hook entry it owns in a Claude Code settings file.
+ * Ownership is the command itself: it runs `sessions hook claude-code` for
+ * one archive config and profile, so foreign hooks (including other GNO
+ * profiles) are never touched. A settings file that is not valid JSON, or
+ * whose `hooks` shape is unexpected, is left unchanged. Writes keep a `.bak`
+ * copy and replace the file atomically (the MCP installer's contract).
+ *
+ * @module src/sessions/claude-hook
+ */
+
+// node:os homedir: no Bun equivalent.
+import { homedir } from "node:os";
+// node:path: no Bun path utilities.
+import { join, resolve } from "node:path";
+
+import { resolveDirs } from "../app/constants";
+import {
+  readMcpConfigText,
+  writeMcpConfigText,
+} from "../cli/commands/mcp/config";
+import { findBunPath } from "../cli/commands/mcp/paths";
+import { getCurrentGnoEntrypoint } from "../core/runtime-entrypoint";
+import { canonicalConfigPath } from "./binding";
+import { SessionsError } from "./types";
+
+/**
+ * Ownership is keyed on the canonical archive config path, so a symlinked
+ * path (for example macOS `/var` -> `/private/var`) matches its entry.
+ */
+async function canonicalIdentity(
+  identity: HookIdentity
+): Promise<HookIdentity> {
+  return {
+    ...identity,
+    configPath: await canonicalConfigPath(identity.configPath),
+  };
+}
+
+/**
+ * Claude Code's hook `timeout` (seconds). SessionEnd hooks otherwise share a
+ * 1.5 s budget; the hook itself returns after at most the admission deadline.
+ */
+export const CLAUDE_HOOK_TIMEOUT_SECONDS = 5;
+
+export interface HookIdentity {
+  configPath: string;
+  indexName: string;
+  profileId: string;
+}
+
+/** `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. */
+export function defaultClaudeSettingsPath(
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const dir = env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+  return join(resolve(dir), "settings.json");
+}
+
+const quote = (value: string): string => `'${value.replaceAll("'", `'\\''`)}'`;
+
+const ownedSuffix = (identity: HookIdentity): string =>
+  `sessions hook claude-code --profile ${quote(identity.profileId)}`;
+
+/**
+ * The absolute command the hook runs: this GNO runtime, its data/cache
+ * directories, and the archive config/index pair, so neither PATH nor the
+ * session's working directory can redirect it.
+ */
+export function buildClaudeHookCommand(identity: HookIdentity): string {
+  const dirs = resolveDirs();
+  return [
+    `GNO_DATA_DIR=${quote(resolve(dirs.data))}`,
+    `GNO_CACHE_DIR=${quote(resolve(dirs.cache))}`,
+    quote(findBunPath()),
+    "run",
+    quote(getCurrentGnoEntrypoint()),
+    "--config",
+    quote(resolve(identity.configPath)),
+    "--index",
+    quote(identity.indexName),
+    ownedSuffix(identity),
+  ].join(" ");
+}
+
+/** Owned by this config and profile, whatever runtime path it was built with. */
+export function isOwnedHookCommand(
+  command: unknown,
+  identity: HookIdentity
+): boolean {
+  return (
+    typeof command === "string" &&
+    command.includes(`--config ${quote(resolve(identity.configPath))} `) &&
+    command.endsWith(ownedSuffix(identity))
+  );
+}
+
+type Json = Record<string, unknown>;
+
+const isObject = (value: unknown): value is Json =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const unexpected = (path: string, detail: string): SessionsError =>
+  new SessionsError(
+    "SESSIONS_INVALID_INPUT",
+    `Claude Code settings ${path} ${detail}; nothing was changed. Fix the file, then retry.`
+  );
+
+async function readSettings(path: string): Promise<Json | null> {
+  const text = await readMcpConfigText(path, { returnNullOnMissing: true });
+  if (text === null) return null;
+  if (!text.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw unexpected(path, "is not valid JSON");
+  }
+  if (!isObject(parsed)) throw unexpected(path, "is not a JSON object");
+  return parsed;
+}
+
+/** SessionEnd groups, validated; null when the file has none. */
+function sessionEndGroups(settings: Json, path: string): Json[] | null {
+  const hooks = settings.hooks;
+  if (hooks === undefined) return null;
+  if (!isObject(hooks)) throw unexpected(path, "has a non-object hooks value");
+  const groups = hooks.SessionEnd;
+  if (groups === undefined) return null;
+  if (!Array.isArray(groups) || !groups.every(isObject)) {
+    throw unexpected(path, "has an unexpected hooks.SessionEnd shape");
+  }
+  return groups;
+}
+
+/** Drop owned hooks; groups left empty by that are dropped too. */
+function withoutOwned(groups: Json[], identity: HookIdentity): Json[] {
+  const kept: Json[] = [];
+  for (const group of groups) {
+    const hooks = Array.isArray(group.hooks) ? group.hooks : null;
+    if (!hooks) {
+      kept.push(group);
+      continue;
+    }
+    const remaining = hooks.filter(
+      (hook) => !(isObject(hook) && isOwnedHookCommand(hook.command, identity))
+    );
+    if (remaining.length === hooks.length) kept.push(group);
+    else if (remaining.length > 0) kept.push({ ...group, hooks: remaining });
+  }
+  return kept;
+}
+
+const countOwned = (groups: Json[], identity: HookIdentity): number =>
+  groups
+    .flatMap((group) => (Array.isArray(group.hooks) ? group.hooks : []))
+    .filter(
+      (hook) => isObject(hook) && isOwnedHookCommand(hook.command, identity)
+    ).length;
+
+/** Whether the owned entry is present; null when the file cannot be read. */
+export async function inspectClaudeHook(
+  settingsPath: string,
+  given: HookIdentity
+): Promise<boolean | null> {
+  const identity = await canonicalIdentity(given);
+  try {
+    const settings = await readSettings(settingsPath);
+    if (!settings) return false;
+    return (
+      countOwned(sessionEndGroups(settings, settingsPath) ?? [], identity) > 0
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Install (or repair) exactly one owned SessionEnd entry. */
+export async function installClaudeHook(
+  settingsPath: string,
+  given: HookIdentity
+): Promise<{ command: string; changed: boolean }> {
+  const identity = await canonicalIdentity(given);
+  const settings = (await readSettings(settingsPath)) ?? {};
+  const groups = sessionEndGroups(settings, settingsPath) ?? [];
+  const command = buildClaudeHookCommand(identity);
+  const current = groups.some(
+    (group) =>
+      Array.isArray(group.hooks) &&
+      group.hooks.some(
+        (hook) =>
+          isObject(hook) &&
+          hook.command === command &&
+          hook.timeout === CLAUDE_HOOK_TIMEOUT_SECONDS
+      )
+  );
+  if (current && countOwned(groups, identity) === 1) {
+    return { command, changed: false };
+  }
+  const next = [
+    ...withoutOwned(groups, identity),
+    {
+      hooks: [
+        { type: "command", command, timeout: CLAUDE_HOOK_TIMEOUT_SECONDS },
+      ],
+    },
+  ];
+  const hooks = isObject(settings.hooks) ? settings.hooks : {};
+  settings.hooks = { ...hooks, SessionEnd: next };
+  await writeMcpConfigText(
+    settingsPath,
+    `${JSON.stringify(settings, null, 2)}\n`
+  );
+  return { command, changed: true };
+}
+
+/** Remove owned entries only. A missing file or entry is not an error. */
+export async function removeClaudeHook(
+  settingsPath: string,
+  given: HookIdentity
+): Promise<{ removed: number }> {
+  const identity = await canonicalIdentity(given);
+  const settings = await readSettings(settingsPath);
+  if (!settings) return { removed: 0 };
+  const groups = sessionEndGroups(settings, settingsPath);
+  if (!groups) return { removed: 0 };
+  const removed = countOwned(groups, identity);
+  if (removed === 0) return { removed: 0 };
+  const hooks = settings.hooks as Json;
+  const next = withoutOwned(groups, identity);
+  if (next.length > 0) hooks.SessionEnd = next;
+  else delete hooks.SessionEnd;
+  await writeMcpConfigText(
+    settingsPath,
+    `${JSON.stringify(settings, null, 2)}\n`
+  );
+  return { removed };
+}

package/src/sessions/config.ts

@@ -0,0 +1,176 @@
+/**
+ * `sessions` block of a dedicated session-archive configuration file.
+ *
+ * The block binds the config file to one named index and one archive root,
+ * and lists owner-registered sources. It only ever appears in the archive
+ * config; the curated default config never carries archive collections.
+ *
+ * @module src/sessions/config
+ */
+
+// node:path isAbsolute: no Bun path utilities.
+import { isAbsolute, relative, resolve } from "node:path";
+import { z } from "zod";
+
+import type { Collection, Config } from "../config/types";
+
+import { MAX_IMPORT_LIMIT, SESSION_HARNESSES } from "./types";
+
+const COLLECTION_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SOURCE_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+const AbsolutePathSchema = z
+  .string()
+  .min(1)
+  .refine((value) => isAbsolute(value), { message: "Path must be absolute" });
+
+const SessionProjectMappingSchema = z
+  .object({
+    /** Working-directory prefix (absolute) this mapping applies to. */
+    prefix: AbsolutePathSchema,
+    /** Archive collection that receives threads recorded under the prefix. */
+    collection: z.string().regex(COLLECTION_NAME),
+  })
+  .strict();
+
+export const SessionSourceSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(
+        SOURCE_ID,
+        "Source ID must be lowercase alphanumeric with hyphens/underscores, 1-64 chars"
+      ),
+    harness: z.enum(SESSION_HARNESSES),
+    /** Absolute harness session root, file or database. */
+    path: AbsolutePathSchema,
+    /** Default archive collection for this source. */
+    collection: z.string().regex(COLLECTION_NAME),
+    /** Owner-approved working-directory mappings to other archive collections. */
+    projects: z.array(SessionProjectMappingSchema).max(64).optional(),
+  })
+  .strict();
+
+/** Host hooks GNO can install. Only verified integrations are listed. */
+export const SESSION_HOOK_HARNESSES = ["claude-code"] as const;
+export type SessionHookHarness = (typeof SESSION_HOOK_HARNESSES)[number];
+
+/**
+ * Owner-controlled automation profile. Every trigger is off until the owner
+ * enables it explicitly; nothing here is ever switched on by install,
+ * upgrade, repair or restart. Destinations and privacy routing stay on the
+ * referenced sources (collection + project mappings), never on the profile.
+ */
+export const SessionAutomationProfileSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(
+        SOURCE_ID,
+        "Profile ID must be lowercase alphanumeric with hyphens/underscores, 1-64 chars"
+      ),
+    /** Registered source IDs this profile imports. */
+    sources: z
+      .array(z.string().regex(SOURCE_ID))
+      .min(1)
+      .max(64)
+      .refine((ids) => new Set(ids).size === ids.length, {
+        message: "Profile sources must be unique",
+      }),
+    hook: z
+      .object({
+        harness: z.enum(SESSION_HOOK_HARNESSES),
+        enabled: z.boolean(),
+        /** Absolute host settings file that holds the owned hook entry. */
+        settings: AbsolutePathSchema,
+      })
+      .strict()
+      .optional(),
+    schedule: z
+      .object({
+        enabled: z.boolean(),
+        /** Elapsed cadence `<n>s|m|h|d`; validated by the automation module. */
+        cadence: z.string().min(2).max(8),
+      })
+      .strict()
+      .optional(),
+    /** Changed units imported per source per run (bounded work budget). */
+    limit: z.number().int().min(1).max(MAX_IMPORT_LIMIT).optional(),
+    /** Automatic retries after a failed run before waiting for a new trigger. */
+    retries: z.number().int().min(0).max(10).optional(),
+  })
+  .strict();
+
+export type SessionAutomationProfile = z.infer<
+  typeof SessionAutomationProfileSchema
+>;
+
+export const SessionsConfigSchema = z
+  .object({
+    /** Index name this archive config is bound to. */
+    index: z.string().min(1).max(64),
+    /** Durable archive root (absolute). Collections live directly below it. */
+    archiveRoot: AbsolutePathSchema,
+    sources: z
+      .array(SessionSourceSchema)
+      .max(64)
+      .default([])
+      .superRefine((sources, ctx) => {
+        const ids = new Set<string>();
+        for (const [index, source] of sources.entries()) {
+          if (ids.has(source.id)) {
+            ctx.addIssue({
+              code: "custom",
+              message: "Session source IDs must be unique",
+              path: [index, "id"],
+            });
+          }
+          ids.add(source.id);
+        }
+      }),
+    redaction: z
+      .object({
+        /** Exact literals always redacted (e.g. internal hostnames, known keys). */
+        literals: z.array(z.string().min(4).max(512)).max(256).default([]),
+      })
+      .strict()
+      .optional(),
+    /** Opt-in automation profiles (hooks and daemon schedules). */
+    automation: z
+      .array(SessionAutomationProfileSchema)
+      .max(16)
+      .optional()
+      .superRefine((profiles, ctx) => {
+        const ids = new Set<string>();
+        for (const [index, profile] of (profiles ?? []).entries()) {
+          if (ids.has(profile.id)) {
+            ctx.addIssue({
+              code: "custom",
+              message: "Automation profile IDs must be unique",
+              path: [index, "id"],
+            });
+          }
+          ids.add(profile.id);
+        }
+      }),
+  })
+  .strict();
+
+export type SessionsConfig = z.infer<typeof SessionsConfigSchema>;
+export type SessionSourceConfig = z.infer<typeof SessionSourceSchema>;
+
+/**
+ * Collections a filesystem watcher follows. Session archive collections are
+ * written and synced only by the importer; a watcher re-syncing them would
+ * duplicate that work on the server's event loop and contend for the index
+ * write lock with the import.
+ */
+export function watchedCollections(config: Config): Collection[] {
+  const archiveRoot = config.sessions?.archiveRoot;
+  if (!archiveRoot) return config.collections;
+  const root = resolve(archiveRoot);
+  return config.collections.filter((collection) => {
+    const rel = relative(root, resolve(collection.path));
+    return rel.startsWith("..") || isAbsolute(rel);
+  });
+}