@taurgis/bonsai 3.2.2 → 4.1.0

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,27 +1,39 @@
 /** 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
+ * reaches a human-readable terminal line. Fields like `topic` and section headings can originate
+ * from fetched web content or agent-supplied notes — both untrusted per the repo's trust-boundary
+ * rules — so a value containing raw escape bytes must never be echoed as-is to a TTY. Newlines and
+ * tabs collapse to a single space rather than being stripped outright, so injected content can't
+ * fake extra output lines while still being removed. JSON output is unaffected: `JSON.stringify`
+ * already escapes control characters, so this only needs to run on the human-readable path.
+ */
+export declare function sanitizeForTerminal(value: string): string;
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
  * rather than derived.
  */
 export declare function pluralize(count: number, singular: string, plural: string): string;
-/** How a command labels a result listing, so its heading and truncation notice stay consistent. */
+/** Shared "Tip: " prefix for contextual next-step suggestions in human-mode output. */
+export declare function formatTip(message: string): string;
+/** How a command labels a result listing, so its heading stays consistent. */
 export interface ResultListLabels {
     /** Noun phrase after the count, e.g. "cached research"; the "entry/entries" plural is appended. */
     noun: string;
     /** Ordering word shown when truncated: "first" (recency order) or "top" (ranked order). */
     order: 'first' | 'top';
-    /** The command's --limit ceiling, surfaced in the truncation hint. */
-    maxLimit: number;
 }
 /** Heading for a result listing; notes truncation inline when more matched than are shown. */
 export declare function resultListHeading(total: number, shown: number, labels: ResultListLabels): string;
-/**
- * One-line truncation notice for stderr, or null when nothing was cut. Available for human-mode
- * tips; `list --json` surfaces truncation via the envelope `truncation` field instead (#91).
- */
-export declare function truncationNotice(total: number, shown: number, labels: ResultListLabels): string | null;
 /** Max edit distance for a plausible typo; scales with input length. */
 export declare function maxFuzzyDistance(input: string): number;
 /**

package/dist/lib/text.js

@@ -1,5 +1,33 @@
 /** 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
+// multi-line-content variant (which preserves tab/newline/CR) shares this one definition.
+export const CONTROL_CHAR_PATTERN = /\p{Cc}/gu;
+/**
+ * Strip ANSI escape codes and other control characters from a cached metadata string before it
+ * reaches a human-readable terminal line. Fields like `topic` and section headings can originate
+ * from fetched web content or agent-supplied notes — both untrusted per the repo's trust-boundary
+ * rules — so a value containing raw escape bytes must never be echoed as-is to a TTY. Newlines and
+ * tabs collapse to a single space rather than being stripped outright, so injected content can't
+ * fake extra output lines while still being removed. JSON output is unaffected: `JSON.stringify`
+ * already escapes control characters, so this only needs to run on the human-readable path.
+ */
+export function sanitizeForTerminal(value) {
+    return value.replace(/[\t\n\r]/g, ' ').replace(CONTROL_CHAR_PATTERN, '');
+}
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
@@ -8,6 +36,10 @@ export const NO_TOPIC_LABEL = '(no topic)';
 export function pluralize(count, singular, plural) {
     return count === 1 ? singular : plural;
 }
+/** Shared "Tip: " prefix for contextual next-step suggestions in human-mode output. */
+export function formatTip(message) {
+    return `Tip: ${message}`;
+}
 /** Heading for a result listing; notes truncation inline when more matched than are shown. */
 export function resultListHeading(total, shown, labels) {
     const noun = `${labels.noun} ${pluralize(total, 'entry', 'entries')}`;
@@ -15,15 +47,6 @@ export function resultListHeading(total, shown, labels) {
         ? `Found ${total} ${noun} (showing ${labels.order} ${shown}; raise --limit to see more):`
         : `Found ${total} ${noun}:`;
 }
-/**
- * One-line truncation notice for stderr, or null when nothing was cut. Available for human-mode
- * tips; `list --json` surfaces truncation via the envelope `truncation` field instead (#91).
- */
-export function truncationNotice(total, shown, labels) {
-    if (total <= shown)
-        return null;
-    return `${total} entries matched; returning the ${labels.order} ${shown}. Raise --limit (max ${labels.maxLimit}) to see more.`;
-}
 /** Max edit distance for a plausible typo; scales with input length. */
 export function maxFuzzyDistance(input) {
     if (input.length <= 3)