@ashlr/hub 2.2.0

package/dist/cli/open.js

@@ -0,0 +1,86 @@
+/**
+ * cli/open.ts — Launch items in editor, Finder, or Terminal.
+ *
+ * All launchers use spawn (detached, unref'd) so the CLI process exits
+ * immediately. Errors are swallowed — never throw; open operations are
+ * best-effort UI conveniences.
+ */
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Internal helper
+// ---------------------------------------------------------------------------
+/**
+ * Fire-and-forget spawn. Detaches the child process so the parent can exit
+ * without waiting. Errors are silently discarded.
+ */
+function fire(cmd, args) {
+    try {
+        const child = spawn(cmd, args, {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        // best-effort — never propagate
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Open `path` in the configured editor using a deep link URL.
+ *
+ * Strategy:
+ *  1. Cursor  → `open "cursor://file/<abs>"`
+ *     Fallback: `open -a Cursor <path>`
+ *  2. VSCode  → `open "vscode://file/<abs>"`
+ *     Fallback: `open -a "Visual Studio Code" <path>`
+ *
+ * The deep link is tried first; if the URL scheme handler is not registered
+ * (e.g. app not installed) macOS silently does nothing, so we do not attempt
+ * explicit fallback detection — callers are welcome to retry via openInFinder.
+ */
+export function openInEditor(path, cfg) {
+    const abs = resolve(path);
+    // Percent-encode each path segment so paths containing spaces or reserved
+    // URI characters (e.g. "Keys & Recovery", "Rent Application.pdf", "tts
+    // agents") still yield a valid URL. `abs` always begins with '/', so the
+    // first split element is the empty string and the join restores the leading
+    // slash; encodeURIComponent never emits '/', so separators are preserved.
+    const enc = abs.split('/').map(encodeURIComponent).join('/');
+    if (cfg.editor === 'vscode') {
+        // Deep link: vscode://file<enc>  (enc already starts with '/')
+        const url = `vscode://file${enc}`;
+        fire('open', [url]);
+    }
+    else {
+        // Default: Cursor deep link: cursor://file<enc>
+        const url = `cursor://file${enc}`;
+        fire('open', [url]);
+    }
+}
+/**
+ * Reveal `path` in macOS Finder.
+ * Uses `open <path>` which opens directories in Finder and files with their
+ * default app. For "reveal in Finder" semantics on a file, callers can pass
+ * the parent directory instead.
+ */
+export function openInFinder(path) {
+    const abs = resolve(path);
+    fire('open', [abs]);
+}
+/**
+ * Open a new Terminal window cd'd to `path` (best-effort).
+ *
+ * Uses `open -a Terminal <path>`. On macOS this opens a new Terminal window
+ * at the given directory when path is a directory. For files, Terminal opens
+ * at the parent directory. No guarantee for iTerm2 or other terminals — this
+ * targets the system Terminal.app only.
+ */
+export function openInTerminal(path) {
+    const abs = resolve(path);
+    fire('open', ['-a', 'Terminal', abs]);
+}
+//# sourceMappingURL=open.js.map

package/dist/cli/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/cli/open.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,IAAI,CAAC,GAAW,EAAE,IAAc;IACvC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC7B,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,GAAgB;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE7D,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC5B,+DAA+D;QAC/D,MAAM,GAAG,GAAG,gBAAgB,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,gDAAgD;QAChD,MAAM,GAAG,GAAG,gBAAgB,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/cli/orient.d.ts

@@ -0,0 +1,14 @@
+/**
+ * cli/orient.ts — `ashlr orient [--repo <r>] [--json]` (M31).
+ *
+ * The session-start command for agents AND humans: one read-only call that
+ * answers "what should I know before I start working here" — genome memory,
+ * health, backlog, pending proposals, portfolio attention.
+ *
+ * CLI-FIRST AGENT CONTRACT:
+ *   - `--json` emits a stable OrientResult (src/core/types.ts) on stdout,
+ *     no ANSI, exit 0. This shape is part of the M31 contract.
+ *   - Exit codes: 0 success, 2 bad usage. (Sections are best-effort; a
+ *     missing store yields empty sections, never a non-zero exit.)
+ */
+export declare function cmdOrient(args: string[]): Promise<number>;

package/dist/cli/orient.js

@@ -0,0 +1,110 @@
+/**
+ * cli/orient.ts — `ashlr orient [--repo <r>] [--json]` (M31).
+ *
+ * The session-start command for agents AND humans: one read-only call that
+ * answers "what should I know before I start working here" — genome memory,
+ * health, backlog, pending proposals, portfolio attention.
+ *
+ * CLI-FIRST AGENT CONTRACT:
+ *   - `--json` emits a stable OrientResult (src/core/types.ts) on stdout,
+ *     no ANSI, exit 0. This shape is part of the M31 contract.
+ *   - Exit codes: 0 success, 2 bad usage. (Sections are best-effort; a
+ *     missing store yields empty sections, never a non-zero exit.)
+ */
+import { loadConfig } from '../core/config.js';
+import { buildOrientation } from '../core/orient.js';
+import { makeColors, isTty, pad } from './ui.js';
+function printOrientHelp() {
+    const c = makeColors(isTty());
+    console.log('');
+    console.log(c.bold('  ashlr orient') + c.dim(' — session-start context (read-only)'));
+    console.log('');
+    console.log('  Usage:');
+    console.log(`    ${c.cyan('ashlr orient')}                   ${c.dim('portfolio-wide orientation')}`);
+    console.log(`    ${c.cyan('ashlr orient --repo <path>')}     ${c.dim('scope to one repo')}`);
+    console.log(`    ${c.cyan('ashlr orient --json')}            ${c.dim('stable OrientResult JSON (agent contract)')}`);
+    console.log('');
+    console.log('  ' + c.dim('Agents: run this once at session start; see `ashlr docs --agent`.'));
+    console.log('');
+}
+export async function cmdOrient(args) {
+    const json = args.includes('--json');
+    let repo;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json')
+            continue;
+        if (a === '--help' || a === '-h' || a === 'help') {
+            printOrientHelp();
+            return 0;
+        }
+        if (a === '--repo') {
+            const val = args[i + 1];
+            if (!val || val.startsWith('--')) {
+                process.stderr.write('error: --repo requires a path\n');
+                return 2;
+            }
+            repo = val;
+            i++;
+            continue;
+        }
+        process.stderr.write(`error: unknown argument: ${a}\n`);
+        printOrientHelp();
+        return 2;
+    }
+    const cfg = loadConfig();
+    const result = await buildOrientation(cfg, repo);
+    if (json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return 0;
+    }
+    const c = makeColors(isTty());
+    console.log('');
+    console.log(c.bold('  ashlr orient') +
+        c.dim(result.repo ? ` — ${result.repo}` : ' — portfolio-wide'));
+    console.log('');
+    // ── Memory ──────────────────────────────────────────────────────────────
+    console.log('  ' + c.bold('Memory') + c.dim(` (${result.genomeHits.length} hits)`));
+    if (result.genomeHits.length === 0) {
+        console.log(c.dim('    none — seed with `ashlr learn "<text>"`'));
+    }
+    for (const hit of result.genomeHits) {
+        const scope = hit.project ? c.dim(` [${hit.project}]`) : '';
+        console.log(`    ${c.cyan('•')} ${hit.title}${scope}`);
+    }
+    console.log('');
+    // ── Health ──────────────────────────────────────────────────────────────
+    console.log('  ' + c.bold('Health'));
+    if (result.health) {
+        console.log(`    ${c.cyan(String(result.health.score))} (${result.health.grade})` +
+            (result.health.worstDimensions.length
+                ? c.dim(`  worst: ${result.health.worstDimensions.join(', ')}`)
+                : ''));
+    }
+    else {
+        console.log(c.dim('    no health report — run `ashlr health`'));
+    }
+    console.log('');
+    // ── Backlog ─────────────────────────────────────────────────────────────
+    console.log('  ' + c.bold('Backlog') + c.dim(` (top ${result.backlogItems.length})`));
+    if (result.backlogItems.length === 0) {
+        console.log(c.dim('    none persisted — run `ashlr backlog refresh`'));
+    }
+    for (const item of result.backlogItems) {
+        console.log(`    ${c.cyan(pad(String(item.score), 4, 'right'))}  ${c.dim(`[${item.source}]`)} ${item.title}`);
+    }
+    console.log('');
+    // ── Attention + inbox ───────────────────────────────────────────────────
+    const att = result.attention;
+    const attText = att
+        ? `${att.dirtyRepos} dirty, ${att.staleRepos} stale repos`
+        : 'no index — run `ashlr index`';
+    console.log('  ' + c.bold('Attention  ') + attText);
+    console.log('  ' + c.bold('Inbox      ') +
+        (result.pendingProposals > 0
+            ? c.yellow(`${result.pendingProposals} pending proposal(s) — review with \`ashlr inbox\``)
+            : c.dim('no pending proposals')));
+    console.log('');
+    return 0;
+}
+//# sourceMappingURL=orient.js.map

package/dist/cli/orient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orient.js","sourceRoot":"","sources":["../../src/cli/orient.ts"],"names":[],"mappings":"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"}

package/dist/cli/picker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Interactive item picker for the ashlr CLI.
+ *
+ * Strategy:
+ *   1. If stdout/stdin are not a TTY → return null (headless / piped).
+ *   2. If `fzf` is on PATH → pipe formatted lines into fzf and map the
+ *      selection back to the originating IndexedItem.
+ *   3. Otherwise → built-in readline picker: numbered list with optional
+ *      type-to-filter, arrow-free, works in every terminal.
+ */
+import type { IndexedItem } from '../core/types.js';
+/**
+ * Present an interactive picker over `items`.
+ *
+ * - Returns the chosen {@link IndexedItem}, or
+ * - `null` if the user cancelled, there are no items, or the process is
+ *   not running in a TTY (headless / piped context).
+ *
+ * Prefers `fzf` when available; falls back to a built-in readline picker.
+ */
+export declare function pick(items: IndexedItem[]): Promise<IndexedItem | null>;

package/dist/cli/picker.js

@@ -0,0 +1,177 @@
+/**
+ * Interactive item picker for the ashlr CLI.
+ *
+ * Strategy:
+ *   1. If stdout/stdin are not a TTY → return null (headless / piped).
+ *   2. If `fzf` is on PATH → pipe formatted lines into fzf and map the
+ *      selection back to the originating IndexedItem.
+ *   3. Otherwise → built-in readline picker: numbered list with optional
+ *      type-to-filter, arrow-free, works in every terminal.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import * as readline from 'node:readline';
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** True when both stdin and stdout are connected to a real terminal. */
+function isTTY() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** True when `fzf` can be found on PATH without throwing. */
+function hasFzf() {
+    try {
+        execFileSync('which', ['fzf'], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a single item into the line shown to the user.
+ * Format: "<name>  [<category>]  <description>"
+ * Each segment is tab-separated so fzf column alignment works.
+ */
+function formatLine(item) {
+    const cat = item.category ?? 'uncategorized';
+    const desc = item.description ?? item.kind;
+    return `${item.name}\t[${cat}]\t${desc}`;
+}
+// ── fzf picker ───────────────────────────────────────────────────────────────
+/**
+ * Run the selection through fzf.
+ * Returns the chosen IndexedItem or null on cancel / error.
+ */
+function pickWithFzf(items) {
+    const lines = items.map(formatLine);
+    const input = lines.join('\n');
+    const result = spawnSync('fzf', ['--ansi', '--with-nth=1,2,3', '--delimiter=\t', '--height=40%', '--reverse', '--prompt=ashlr> '], {
+        input,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'inherit'],
+    });
+    // Exit code 130 = user cancelled (Ctrl-C / Esc); 1 = no match.
+    if (result.status !== 0 || !result.stdout) {
+        return null;
+    }
+    const chosen = result.stdout.trim();
+    if (!chosen)
+        return null;
+    // Map the selected line back to the item by matching the formatted line.
+    const idx = lines.findIndex((l) => l === chosen);
+    return idx >= 0 ? items[idx] ?? null : null;
+}
+// ── Built-in readline picker ─────────────────────────────────────────────────
+/**
+ * Simple numbered list picker with optional filter query.
+ * Renders up to `PAGE_SIZE` items at a time; user types a number or a
+ * filter string and presses Enter.
+ */
+const PAGE_SIZE = 20;
+async function pickWithReadline(items) {
+    return new Promise((resolve) => {
+        // We open /dev/tty explicitly so the picker works even when stdin is
+        // redirected — though we already guard against non-TTY above.
+        // All picker UI is written to stderr so that stdout stays clean for
+        // capture (e.g. `cd $(ashlr go foo --cd)` must only ever see the chosen
+        // path on stdout, never the interactive prompt chrome).
+        const ttyIn = process.stdin;
+        const ttyOut = process.stderr;
+        /** Print a filtered, numbered list and the prompt. */
+        function renderList(filtered, filter) {
+            ttyOut.write('\x1B[2J\x1B[H'); // clear screen
+            ttyOut.write('\x1B[1mashlr picker\x1B[0m');
+            if (filter)
+                ttyOut.write(`  filter: \x1B[33m${filter}\x1B[0m`);
+            ttyOut.write(`  (${filtered.length} / ${items.length})\n\n`);
+            const page = filtered.slice(0, PAGE_SIZE);
+            for (let i = 0; i < page.length; i++) {
+                const item = page[i];
+                const num = String(i + 1).padStart(3, ' ');
+                const cat = item.category ? `\x1B[36m[${item.category}]\x1B[0m ` : '';
+                const desc = item.description ? `\x1B[2m— ${item.description}\x1B[0m` : '';
+                ttyOut.write(`  ${num}.  \x1B[1m${item.name}\x1B[0m  ${cat}${desc}\n`);
+            }
+            if (filtered.length > PAGE_SIZE) {
+                ttyOut.write(`\n  … and ${filtered.length - PAGE_SIZE} more. Narrow your filter.\n`);
+            }
+            ttyOut.write('\nType a number to select, text to filter, or Enter to cancel: ');
+        }
+        const rl = readline.createInterface({
+            input: ttyIn,
+            output: ttyOut,
+            terminal: true,
+        });
+        let currentFilter = '';
+        let filtered = [...items];
+        /** Re-render and ask for the next input. */
+        function prompt() {
+            renderList(filtered, currentFilter);
+            rl.question('', (answer) => {
+                const trimmed = answer.trim();
+                // Empty input → cancel
+                if (!trimmed) {
+                    rl.close();
+                    resolve(null);
+                    return;
+                }
+                // Numeric input → pick by displayed index (1-based)
+                const num = parseInt(trimmed, 10);
+                const isAllDigits = /^\d+$/.test(trimmed);
+                if (!isNaN(num) && num >= 1 && num <= Math.min(filtered.length, PAGE_SIZE)) {
+                    rl.close();
+                    resolve(filtered[num - 1] ?? null);
+                    return;
+                }
+                // All-digit input that is out of the visible selection range is clearly
+                // a (mis-typed) selection, not a filter. Tell the user and re-prompt
+                // WITHOUT clobbering their current filter.
+                if (isAllDigits) {
+                    ttyOut.write(`\n  \x1B[31mNo item #${trimmed} on this page.\x1B[0m Narrow your filter and pick again.\n`);
+                    prompt();
+                    return;
+                }
+                // Text input → update filter and re-render
+                currentFilter = trimmed.toLowerCase();
+                filtered = items.filter((item) => {
+                    const haystack = [item.name, item.category, item.description, item.kind]
+                        .filter(Boolean)
+                        .join(' ')
+                        .toLowerCase();
+                    return haystack.includes(currentFilter);
+                });
+                if (filtered.length === 0) {
+                    // No matches — reset filter and let user try again
+                    ttyOut.write('\n  \x1B[31mNo matches for that filter.\x1B[0m Press Enter to cancel or type another query.\n');
+                    currentFilter = '';
+                    filtered = [...items];
+                }
+                prompt();
+            });
+        }
+        // Handle Ctrl-C gracefully
+        rl.on('close', () => {
+            resolve(null);
+        });
+        prompt();
+    });
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Present an interactive picker over `items`.
+ *
+ * - Returns the chosen {@link IndexedItem}, or
+ * - `null` if the user cancelled, there are no items, or the process is
+ *   not running in a TTY (headless / piped context).
+ *
+ * Prefers `fzf` when available; falls back to a built-in readline picker.
+ */
+export async function pick(items) {
+    if (items.length === 0)
+        return null;
+    if (!isTTY())
+        return null;
+    if (hasFzf()) {
+        return pickWithFzf(items);
+    }
+    return pickWithReadline(items);
+}
+//# sourceMappingURL=picker.js.map

package/dist/cli/picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker.js","sourceRoot":"","sources":["../../src/cli/picker.ts"],"names":[],"mappings":"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"}

package/dist/cli/plugins.d.ts

@@ -0,0 +1,21 @@
+/**
+ * cli/plugins.ts — `ashlr plugins list|info|enable|disable` + `ashlr x <name>` (M33).
+ *
+ * Trust posture (CONTRACT-M33 / docs/PLUGINS.md):
+ *   - `list` / `info` are DISCOVERY ONLY — they read manifest.json files and
+ *     NEVER import plugin code.
+ *   - `enable` is the consent gate: shows declared capabilities + a trust
+ *     warning, requires interactive confirmation (or --yes), and pins the
+ *     entry file's sha256 into ~/.ashlr/config.json (tamper evidence).
+ *   - `disable` removes the name from plugins.enabled (pin kept for re-enable).
+ *   - `ashlr x <name> [...]` runs an enabled plugin's command through the
+ *     wrapped (audited, exit-code-safe) runner.
+ *
+ * Exit codes: 0 success · 1 runtime error · 2 bad usage.
+ */
+export declare function cmdPlugins(args: string[]): Promise<number>;
+/**
+ * `ashlr x <name> [args...]` — run an enabled plugin's command (wrapped:
+ * audited invocation + exit code; builtin shadowing rejected at load).
+ */
+export declare function cmdX(args: string[]): Promise<number>;