@taurgis/bonsai 4.0.0 → 4.1.0

package/dist/lib/research/metadata-filters.d.ts

@@ -1,4 +1,4 @@
-import type { ResearchArtifactMetadata } from './schema.js';
+import type { ArtifactType, CaptureMethod, ResearchArtifactMetadata } from './schema.js';
 /** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
 export declare function matchesTopicFilter(meta: Pick<ResearchArtifactMetadata, 'topic'>, topic: string | undefined): boolean;
 /** Whether an artifact's tags satisfy a `--tags` filter (case-insensitive, must match all). */
@@ -16,3 +16,24 @@ export declare function emptyTopicFilterError(topic: string | undefined): string
  * matches any artifact's tags — silently returning zero results with no signal. Fail fast instead.
  */
 export declare function emptyTagsFilterError(tags: string[] | undefined): string | undefined;
+/** The metadata filter flags `list` and `search` both expose, beyond content/topic search. */
+export interface CommonMetadataFilterFlags {
+    topic?: string;
+    tags?: string[];
+    url?: string;
+    artifactType?: ArtifactType;
+    captureMethod?: CaptureMethod;
+    freshness?: 'fresh' | 'stale_grace' | 'stale_expired';
+}
+/**
+ * Shared page-level metadata filter combinator for `list` and `search` (topic/tags/url/artifact
+ * type/capture method/freshness) — single source of truth so the two commands can never drift on
+ * what "matches the given filters" means.
+ */
+export declare function matchesCommonMetadataFilters(meta: ResearchArtifactMetadata, freshness: 'fresh' | 'stale_grace' | 'stale_expired', flags: CommonMetadataFilterFlags): boolean;
+/**
+ * Whether any of the shared metadata filter flags was passed — used to pick empty-result guidance
+ * ("no matches for your filters" vs. "the cache is empty"). `search` combines this with its own
+ * `--query` check; `list` has no filters beyond these, so it uses the result directly.
+ */
+export declare function hasActiveMetadataFilters(flags: CommonMetadataFilterFlags): boolean;

package/dist/lib/research/metadata-filters.js

@@ -1,3 +1,4 @@
+import { artifactMatchesUrlFilter } from './url.js';
 /** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
 export function matchesTopicFilter(meta, topic) {
     if (!topic)
@@ -35,3 +36,36 @@ export function emptyTagsFilterError(tags) {
         return undefined;
     return '--tags must be non-empty values (e.g. "react").';
 }
+/**
+ * Shared page-level metadata filter combinator for `list` and `search` (topic/tags/url/artifact
+ * type/capture method/freshness) — single source of truth so the two commands can never drift on
+ * what "matches the given filters" means.
+ */
+export function matchesCommonMetadataFilters(meta, freshness, flags) {
+    if (!matchesTopicFilter(meta, flags.topic))
+        return false;
+    if (!matchesTagsFilter(meta, flags.tags))
+        return false;
+    if (flags.url && !artifactMatchesUrlFilter(meta, flags.url))
+        return false;
+    if (flags.artifactType && meta.artifact_type !== flags.artifactType)
+        return false;
+    if (flags.captureMethod && meta.capture_method !== flags.captureMethod)
+        return false;
+    if (flags.freshness && freshness !== flags.freshness)
+        return false;
+    return true;
+}
+/**
+ * Whether any of the shared metadata filter flags was passed — used to pick empty-result guidance
+ * ("no matches for your filters" vs. "the cache is empty"). `search` combines this with its own
+ * `--query` check; `list` has no filters beyond these, so it uses the result directly.
+ */
+export function hasActiveMetadataFilters(flags) {
+    return Boolean(flags.topic ||
+        (flags.tags && flags.tags.length > 0) ||
+        flags.freshness ||
+        flags.artifactType ||
+        flags.captureMethod ||
+        flags.url);
+}

package/dist/lib/research/schema.d.ts

@@ -11,6 +11,8 @@ export type CaptureMethod = (typeof CAPTURE_METHODS)[number];
 export declare const ARTIFACT_TYPES: readonly ["source", "research_note", "index", "section"];
 /** Classification of a research artifact's role. */
 export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export declare const PAGE_LEVEL_ARTIFACT_TYPES: ("source" | "research_note" | "index")[];
 /** Full metadata block stored alongside every cached research artifact. */
 export interface ResearchArtifactMetadata {
     schema_version: number;

package/dist/lib/research/schema.js

@@ -12,3 +12,7 @@ export const CAPTURE_METHODS = [
 // index; `section` = a heading-level child of a page. Command flag `options` derive from this.
 /** All recognized artifact types. `index` = navigation hub or llms.txt; `section` = heading-level child of a page. */
 export const ARTIFACT_TYPES = ['source', 'research_note', 'index', 'section'];
+// Shared by `list` and `search`: both report pages, never the `section` chunks a page is split
+// into (a single fetch can yield dozens) — `inspect` is where a page's sections are discoverable.
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export const PAGE_LEVEL_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');

package/dist/lib/research/search-match.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** A field a query term can match against, in priority order (most to least specific). */
+export type SearchMatchField = 'topic' | 'tags' | 'summary' | 'compressed';
+/** Fields of an artifact that `search --query` matches against. */
+export interface SearchableFields {
+    topic: string | null;
+    tags: string[];
+    summary: string;
+    compressed: string;
+}
+/** Result of scoring one artifact against a tokenized query. */
+export interface SearchMatch {
+    score: number;
+    matchedFields: SearchMatchField[];
+}
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export declare function tokenizeSearchQuery(query: string): string[];
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export declare function emptySearchQueryError(query: string | undefined): string | undefined;
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export declare function scoreSearchMatch(fields: SearchableFields, terms: readonly string[], matchAny: boolean): SearchMatch | null;
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export declare function extractSearchSnippet(fields: Pick<SearchableFields, 'summary' | 'compressed'>, terms: readonly string[]): string | null;

package/dist/lib/research/search-match.js

@@ -0,0 +1,134 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** Per-term score contribution when it matches the artifact's topic. */
+const SCORE_WEIGHT_TOPIC = 100;
+/** Per matching tag, per term. */
+const SCORE_WEIGHT_TAG = 50;
+/** Per occurrence in `summary`, per term (capped by {@link SUMMARY_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_SUMMARY = 10;
+/** Per occurrence in `compressed`, per term (capped by {@link COMPRESSED_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_COMPRESSED = 2;
+// Repeated boilerplate (e.g. a term that happens to be a common word in a large compressed body)
+// must not let one field dominate the score just by occurring many times; capping occurrences
+// counted keeps the topic/tag weights meaningfully dominant regardless of body length.
+const SUMMARY_OCCURRENCE_CAP = 5;
+const COMPRESSED_OCCURRENCE_CAP = 10;
+/** Characters of original-case text kept on each side of a matched term in an excerpt. */
+const SNIPPET_CONTEXT_CHARS = 90;
+/** Field priority order for a deterministic `matchedFields` list, independent of term iteration order. */
+const FIELD_PRIORITY = ['topic', 'tags', 'summary', 'compressed'];
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export function tokenizeSearchQuery(query) {
+    const terms = query
+        .trim()
+        .split(/\s+/)
+        .map((term) => term.toLowerCase());
+    return [...new Set(terms)];
+}
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export function emptySearchQueryError(query) {
+    if (query === undefined)
+        return undefined;
+    if (query.trim() === '') {
+        return '--query must be a non-empty value (e.g. "suspense boundary").';
+    }
+    return undefined;
+}
+/** Count non-overlapping occurrences of `needle` in `haystack` (both already lowercased). */
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let fromIndex = 0;
+    let index;
+    while ((index = haystack.indexOf(needle, fromIndex)) !== -1) {
+        count++;
+        fromIndex = index + needle.length;
+    }
+    return count;
+}
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export function scoreSearchMatch(fields, terms, matchAny) {
+    const topicLower = (fields.topic ?? '').toLowerCase();
+    const tagsLower = fields.tags.map((tag) => tag.toLowerCase());
+    const summaryLower = fields.summary.toLowerCase();
+    const compressedLower = fields.compressed.toLowerCase();
+    let score = 0;
+    let matchedTermCount = 0;
+    const matchedFieldSet = new Set();
+    for (const term of terms) {
+        let termMatched = false;
+        if (topicLower.includes(term)) {
+            score += SCORE_WEIGHT_TOPIC;
+            matchedFieldSet.add('topic');
+            termMatched = true;
+        }
+        const tagHits = tagsLower.filter((tag) => tag.includes(term)).length;
+        if (tagHits > 0) {
+            score += SCORE_WEIGHT_TAG * tagHits;
+            matchedFieldSet.add('tags');
+            termMatched = true;
+        }
+        const summaryHits = Math.min(countOccurrences(summaryLower, term), SUMMARY_OCCURRENCE_CAP);
+        if (summaryHits > 0) {
+            score += SCORE_WEIGHT_SUMMARY * summaryHits;
+            matchedFieldSet.add('summary');
+            termMatched = true;
+        }
+        const compressedHits = Math.min(countOccurrences(compressedLower, term), COMPRESSED_OCCURRENCE_CAP);
+        if (compressedHits > 0) {
+            score += SCORE_WEIGHT_COMPRESSED * compressedHits;
+            matchedFieldSet.add('compressed');
+            termMatched = true;
+        }
+        if (termMatched)
+            matchedTermCount++;
+    }
+    const satisfied = matchAny ? matchedTermCount > 0 : matchedTermCount === terms.length;
+    if (!satisfied)
+        return null;
+    return { score, matchedFields: FIELD_PRIORITY.filter((field) => matchedFieldSet.has(field)) };
+}
+/** Earliest (leftmost) occurrence of any term in already-lowercased `textLower`, or `null`. */
+function findEarliestMatch(textLower, terms) {
+    let best = null;
+    for (const term of terms) {
+        const index = textLower.indexOf(term);
+        if (index !== -1 && (best === null || index < best.index)) {
+            best = { index, length: term.length };
+        }
+    }
+    return best;
+}
+/** Windowed excerpt of `text` around `match`, collapsed to one line with ellipsis on truncation. */
+function buildSnippetWindow(text, match) {
+    const start = Math.max(0, match.index - SNIPPET_CONTEXT_CHARS);
+    const end = Math.min(text.length, match.index + match.length + SNIPPET_CONTEXT_CHARS);
+    const windowed = text.slice(start, end).replace(/\s+/g, ' ').trim();
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return `${prefix}${windowed}${suffix}`;
+}
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export function extractSearchSnippet(fields, terms) {
+    const compressedMatch = findEarliestMatch(fields.compressed.toLowerCase(), terms);
+    if (compressedMatch)
+        return buildSnippetWindow(fields.compressed, compressedMatch);
+    const summaryMatch = findEarliestMatch(fields.summary.toLowerCase(), terms);
+    if (summaryMatch)
+        return buildSnippetWindow(fields.summary, summaryMatch);
+    return null;
+}

package/dist/lib/scope-flags.d.ts

@@ -0,0 +1,19 @@
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export declare function scopeFlags(descriptions: {
+    global: string;
+    local: string;
+}): {
+    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export declare function assertScopeFlagsExclusive(error: (message: string, options: {
+    exit: 2;
+    code: string;
+    suggestions: string[];
+}) => never, global: boolean | undefined, local: boolean | undefined): void;

package/dist/lib/scope-flags.js

@@ -0,0 +1,27 @@
+import { Flags } from '@oclif/core';
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export function scopeFlags(descriptions) {
+    return {
+        global: Flags.boolean({ char: 'g', description: descriptions.global }),
+        local: Flags.boolean({
+            description: descriptions.local,
+            aliases: ['project'],
+            charAliases: ['p'],
+        }),
+    };
+}
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export function assertScopeFlagsExclusive(error, global, local) {
+    if (global && local) {
+        error('--global and --local are mutually exclusive.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: ['Pass --global or --local, not both.'],
+        });
+    }
+}

package/dist/lib/setup/agents.d.ts

@@ -0,0 +1,16 @@
+import type { SetupAgent } from '../cli-result-types.js';
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export declare const SETUP_AGENTS: readonly SetupAgent[];
+/** Where a SessionStart hook lives for one agent, and how Bonsai's entry is shaped. */
+export interface SetupAgentTarget {
+    /** Hook-config file path, relative to the project root or the user's home directory. */
+    relativePath: string;
+    eventName: string;
+    matcher: string;
+    timeout: number;
+}
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export declare const SETUP_HOOK_COMMAND_SUFFIX = "context";
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export declare const SETUP_HOOK_MANAGED_BY = "bonsai";
+export declare const SETUP_AGENT_TARGETS: Record<SetupAgent, SetupAgentTarget>;

package/dist/lib/setup/agents.js

@@ -0,0 +1,20 @@
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export const SETUP_AGENTS = ['claude-code', 'codex'];
+// Both agents accept plain stdout as SessionStart context and share the same `source` matcher
+// values (startup/resume/clear/compact) — see the cached docs at
+// developers.openai.com/codex/hooks#sessionstart (.bonsai/research/4f69debe...) and
+// code.claude.com/docs/en/hooks (.bonsai/research/20106b0f3bee09dd540039d6a1a5294fbfbe0ae0b182affd4138cf3caa31e0c6.md,
+// imported rather than fetched — Bonsai's own fetch times out on this host in this environment).
+const SESSION_START = {
+    eventName: 'SessionStart',
+    matcher: 'startup|resume|clear|compact',
+    timeout: 10,
+};
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export const SETUP_HOOK_COMMAND_SUFFIX = 'context';
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export const SETUP_HOOK_MANAGED_BY = 'bonsai';
+export const SETUP_AGENT_TARGETS = {
+    'claude-code': { ...SESSION_START, relativePath: '.claude/settings.json' },
+    codex: { ...SESSION_START, relativePath: '.codex/hooks.json' },
+};

package/dist/lib/setup/bin-command.d.ts

@@ -0,0 +1,14 @@
+/** `which`/`where` lookup for a command name; `null` when not found on `PATH`. */
+export declare function findOnPath(command: string): string | null;
+/**
+ * Resolves the command a hook config should invoke to run this CLI (AXI rule: "hook commands
+ * should use a PATH-verified binary name when it resolves to the current executable, and fall
+ * back to the full absolute path otherwise"). This keeps a global install portable across
+ * machines while guaranteeing a hook never silently runs a different `bonsai` than the one that
+ * installed it.
+ *
+ * @param scriptPath - The currently running script (`process.argv[1]`).
+ * @param lookup - `PATH` lookup, injectable for tests.
+ * @returns `"bonsai"` when `PATH` resolves to this same script, otherwise `node "<absolute path>"`.
+ */
+export declare function resolveBinCommand(scriptPath: string, lookup?: typeof findOnPath): string;

package/dist/lib/setup/bin-command.js

@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+/** `which`/`where` lookup for a command name; `null` when not found on `PATH`. */
+export function findOnPath(command) {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const output = execFileSync(finder, [command], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // `where` on Windows can print multiple matches, one per line; the first is the one PATH resolves to.
+        return output.split(/\r?\n/).find((line) => line.trim() !== '') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the command a hook config should invoke to run this CLI (AXI rule: "hook commands
+ * should use a PATH-verified binary name when it resolves to the current executable, and fall
+ * back to the full absolute path otherwise"). This keeps a global install portable across
+ * machines while guaranteeing a hook never silently runs a different `bonsai` than the one that
+ * installed it.
+ *
+ * @param scriptPath - The currently running script (`process.argv[1]`).
+ * @param lookup - `PATH` lookup, injectable for tests.
+ * @returns `"bonsai"` when `PATH` resolves to this same script, otherwise `node "<absolute path>"`.
+ */
+export function resolveBinCommand(scriptPath, lookup = findOnPath) {
+    const realScript = realpathSync(scriptPath);
+    const onPath = lookup('bonsai');
+    if (onPath) {
+        try {
+            if (realpathSync(onPath) === realScript)
+                return 'bonsai';
+        }
+        catch {
+            // onPath didn't resolve to a real file (stale PATH entry) — fall through to the absolute path.
+        }
+    }
+    return `node "${realScript}"`;
+}

package/dist/lib/setup/hook-file-io.d.ts

@@ -0,0 +1,37 @@
+/** The SessionStart hook Bonsai wants installed. */
+export interface SessionStartHookSpec {
+    /** Hook event name, e.g. `"SessionStart"`. */
+    eventName: string;
+    matcher: string;
+    /** Full command to run (already resolved to a PATH-verified name or absolute path). */
+    command: string;
+    timeout: number;
+    /**
+     * Tag stamped on the installed handler (e.g. `"bonsai"`) so a later run can find *this exact*
+     * entry to repair or leave alone, without guessing from `command` text — a user's own hook could
+     * otherwise end in the same word Bonsai's command does (e.g. a wrapped `... && bonsai context`)
+     * and get silently claimed and overwritten.
+     */
+    managedBy: string;
+}
+/** Outcome of planning a hook-file install: what changed, and the file content to persist. */
+export interface HookInstallPlan {
+    status: 'installed' | 'repaired' | 'unchanged';
+    content: string;
+}
+/** Thrown when an existing hook file can't be safely merged into (not JSON, or not an object). */
+export declare class InvalidHookFileError extends Error {
+}
+/**
+ * Plans installing or repairing a Bonsai-managed `SessionStart` hook entry inside an existing (or
+ * not-yet-created) hook-config file, without touching any other hooks already in that file (AXI
+ * rules: explicit opt-in install, path repair, idempotent). Pure — callers own reading the
+ * existing file and persisting `content` (see `setup.ts`).
+ *
+ * - No existing Bonsai entry for this event → append a new matcher group (`installed`).
+ * - An existing Bonsai entry with a stale `command` → update it in place (`repaired`).
+ * - An existing Bonsai entry with the same `command` → no-op, original bytes returned (`unchanged`).
+ *
+ * @throws {InvalidHookFileError} When `existingContent` isn't a mergeable JSON object.
+ */
+export declare function planSessionStartHookInstall(existingContent: string | null, spec: SessionStartHookSpec): HookInstallPlan;

package/dist/lib/setup/hook-file-io.js

@@ -0,0 +1,80 @@
+/** Thrown when an existing hook file can't be safely merged into (not JSON, or not an object). */
+export class InvalidHookFileError extends Error {
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isBonsaiHandler(handler, managedBy) {
+    return isPlainObject(handler) && handler.managedBy === managedBy;
+}
+function serialize(root) {
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/**
+ * Parses an existing hook-file's content into its root JSON object, or `{}` when the file doesn't
+ * exist yet. Deliberately refuses (rather than silently discarding) content that isn't a JSON
+ * object — the file may carry a user's own unrelated hooks, and Bonsai must never clobber content
+ * it can't understand.
+ *
+ * @throws {InvalidHookFileError} When `existingContent` is set but isn't a JSON object.
+ */
+function parseHookFileRoot(existingContent) {
+    if (existingContent === null || existingContent.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(existingContent);
+    }
+    catch (err) {
+        throw new InvalidHookFileError(`not valid JSON: ${err.message}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new InvalidHookFileError('expected a JSON object at the top level');
+    }
+    return parsed;
+}
+/**
+ * Plans installing or repairing a Bonsai-managed `SessionStart` hook entry inside an existing (or
+ * not-yet-created) hook-config file, without touching any other hooks already in that file (AXI
+ * rules: explicit opt-in install, path repair, idempotent). Pure — callers own reading the
+ * existing file and persisting `content` (see `setup.ts`).
+ *
+ * - No existing Bonsai entry for this event → append a new matcher group (`installed`).
+ * - An existing Bonsai entry with a stale `command` → update it in place (`repaired`).
+ * - An existing Bonsai entry with the same `command` → no-op, original bytes returned (`unchanged`).
+ *
+ * @throws {InvalidHookFileError} When `existingContent` isn't a mergeable JSON object.
+ */
+export function planSessionStartHookInstall(existingContent, spec) {
+    const root = parseHookFileRoot(existingContent);
+    const hooks = isPlainObject(root.hooks) ? { ...root.hooks } : {};
+    const eventGroups = Array.isArray(hooks[spec.eventName])
+        ? [...hooks[spec.eventName]]
+        : [];
+    for (const group of eventGroups) {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            continue;
+        const index = group.hooks.findIndex((handler) => isBonsaiHandler(handler, spec.managedBy));
+        if (index === -1)
+            continue;
+        const existingHandler = group.hooks[index];
+        if (existingHandler.command === spec.command) {
+            // Byte-identical no-op: return the original content rather than a reserialized copy, so a
+            // repeated install never churns the file's formatting.
+            return { status: 'unchanged', content: existingContent ?? serialize(root) };
+        }
+        group.hooks[index] = { ...existingHandler, command: spec.command };
+        hooks[spec.eventName] = eventGroups;
+        root.hooks = hooks;
+        return { status: 'repaired', content: serialize(root) };
+    }
+    eventGroups.push({
+        matcher: spec.matcher,
+        hooks: [
+            { type: 'command', command: spec.command, timeout: spec.timeout, managedBy: spec.managedBy },
+        ],
+    });
+    hooks[spec.eventName] = eventGroups;
+    root.hooks = hooks;
+    return { status: 'installed', content: serialize(root) };
+}

package/dist/lib/text.d.ts

@@ -1,5 +1,11 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export declare const NO_TOPIC_LABEL = "(no topic)";
+/**
+ * Collapse a leading home-directory prefix to `~`, matching how shells and tools like `git`
+ * display paths. Used for the home-view "bin:" identity line (AXI principle 10) so the executable
+ * path stays readable instead of a long absolute path.
+ */
+export declare function collapseHomeDir(path: string, homeDir: string): string;
 export declare const CONTROL_CHAR_PATTERN: RegExp;
 /**
  * Strip ANSI escape codes and other control characters from a cached metadata string before it

package/dist/lib/text.js

@@ -1,5 +1,16 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export const NO_TOPIC_LABEL = '(no topic)';
+/**
+ * Collapse a leading home-directory prefix to `~`, matching how shells and tools like `git`
+ * display paths. Used for the home-view "bin:" identity line (AXI principle 10) so the executable
+ * path stays readable instead of a long absolute path.
+ */
+export function collapseHomeDir(path, homeDir) {
+    if (homeDir && (path === homeDir || path.startsWith(`${homeDir}/`))) {
+        return `~${path.slice(homeDir.length)}`;
+    }
+    return path;
+}
 // Unicode "Control" category (C0 + C1) covers ANSI/terminal escape sequences: the ESC control
 // character that starts them is a member, so stripping this category is what keeps injected
 // control bytes from reaching a real terminal. Exported so `prompt-injection.ts`'s