@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/config/store.js

@@ -1,51 +1,51 @@
 /**
- * Config store — read/atomic-write the user config JSON and resolve OS-specific
- * paths via `env-paths`. The file may hold secrets, so it is written with
- * `0600` permissions on POSIX (spec §3.5 / §6.1).
+ * Config store — read/atomic-write the user config JSON. Paths come from
+ * `app-paths.ts`; nothing here does its own path arithmetic. The file may hold
+ * secrets, so it is written with `0600` permissions on POSIX (spec §3.5 / §6.1).
+ *
+ * There is deliberately no `getConfigDir()` / `getSkillsDir()` here any more.
+ * The first would now return the entire user root under a name that says
+ * otherwise (see the test-isolation contract in `app-paths.ts`); the second was
+ * a second name for `skills/paths.ts::getUserSkillsDir()`, which is precisely
+ * the drift the header of that module warns about.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 import process from 'node:process';
-import { appPaths as paths } from './app-paths.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampSkillsConfig, } from './schema.js';
-// ---------------------------------------------------------------------------
-// Locations
-// ---------------------------------------------------------------------------
-export function getConfigDir() {
-    return paths.config;
-}
-export function getConfigPath() {
-    return join(paths.config, 'config.json');
-}
-export function getSessionsDir() {
-    return join(paths.data, 'sessions');
-}
-/** User-scope skills root — `aragon skills install`'s default target. */
-export function getSkillsDir() {
-    return join(paths.data, 'skills');
-}
-// ---------------------------------------------------------------------------
-// Read
-// ---------------------------------------------------------------------------
+import { getConfigPath, getSessionsDir } from './app-paths.js';
+import { registerSecretsFrom } from '../logging/secret-registry.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, } from './schema.js';
+// Re-exported so the many existing importers of `store.js` keep working; the
+// definitions live in `app-paths.ts` because they are pure path arithmetic.
+export { getConfigPath, getSessionsDir };
 /**
- * Read the persisted config file. Returns a partial config (only the keys the
- * user actually wrote) or `null` when the file is absent or unparseable.
+ * Read the persisted config file.
+ *
+ * A corrupt config file still must never crash the CLI — the fallback to
+ * defaults is unchanged. What changed is that it is no longer SILENT: a single
+ * stray comma used to reset the model, theme, timeouts, skills and (as far as
+ * the user could tell) the API key, with nothing anywhere saying why. Now the
+ * failure travels out of band in `parseError`, and `loadConfig()` turns it into
+ * a log record plus one visible line. Hand-editing this file is a supported
+ * workflow, so the failure mode had to become visible.
  */
 export function readConfigFile() {
     const file = getConfigPath();
     if (!existsSync(file))
-        return null;
+        return { config: null };
     try {
         const raw = readFileSync(file, 'utf-8');
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object') {
-            return parsed;
+            return { config: parsed };
         }
-        return null;
+        return { config: null, parseError: `${file} does not contain a JSON object` };
     }
-    catch {
-        // A corrupt config file must never crash the CLI — fall back to defaults.
-        return null;
+    catch (err) {
+        return {
+            config: null,
+            parseError: `${file}: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }
 // ---------------------------------------------------------------------------
@@ -82,7 +82,7 @@ export function writeConfigFile(config) {
  * Unlike `readConfigFile`, this always returns a complete `PersistedConfig`.
  */
 export function loadPersistedConfig() {
-    const partial = readConfigFile() ?? {};
+    const partial = readConfigFile().config ?? {};
     return {
         ...DEFAULT_CONFIG,
         ...partial,
@@ -93,6 +93,8 @@ export function loadPersistedConfig() {
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
         skills: clampSkillsConfig({ ...DEFAULT_CONFIG.skills, ...(partial.skills ?? {}) }),
+        // `log` is the third. Same one-level rule, same merge.
+        log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
     };
 }
 /**
@@ -110,9 +112,15 @@ export function loadPersistedConfig() {
  *
  * `SkillsConfig` is therefore capped at ONE level of nesting (scalars and
  * string arrays only). A third level requires replacing this hand-written merge
- * with a real deep-merge utility first, or the same bug returns.
+ * with a real deep-merge utility first, or the same bug returns. `LogConfig` is
+ * a third SECTION, but it is still one level deep (scalars only), so the same
+ * hand-written merge covers it — and it must stay that way for that reason.
  */
 export function updatePersistedConfig(patch) {
+    // Registration site 5. Whatever route a key took to get here, this is the one
+    // function that writes it to disk, so this is the last place it can be added
+    // to the redactor's backstop before it also starts appearing in log records.
+    registerSecretsFrom(patch.apiKeys);
     const current = loadPersistedConfig();
     const merged = {
         ...current,
@@ -120,6 +128,10 @@ export function updatePersistedConfig(patch) {
         version: CONFIG_VERSION,
         apiKeys: { ...current.apiKeys, ...(patch.apiKeys ?? {}) },
         skills: clampSkillsConfig({ ...current.skills, ...(patch.skills ?? {}) }),
+        // Without this line, changing the log level from the settings screen would
+        // replace the whole section and quietly revert `maxFiles`, `previewChars`
+        // and — worst of all — `redactSecrets`.
+        log: clampLogConfig({ ...current.log, ...(patch.log ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/input/mouse-events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+export interface WheelEvent {
+    readonly kind: 'wheel';
+    readonly dir: 'up' | 'down';
+    /** 1-based terminal column, as reported. */
+    readonly x: number;
+    /** 1-based terminal row, as reported. */
+    readonly y: number;
+    readonly shift: boolean;
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+}
+export interface MouseSplit {
+    /** Wheel events, in arrival order. Non-wheel reports are dropped, not returned. */
+    readonly events: WheelEvent[];
+    /** Everything that was not a mouse report — forward this to Ink verbatim. */
+    readonly text: string;
+    /** Trailing strict prefix of a possible report; feed it back in with the next chunk. */
+    readonly pending: string;
+}
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export declare const MAX_PENDING_MOUSE_CHARS = 32;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export declare function isMousePrefix(s: string): boolean;
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export declare function splitMouseEvents(buffer: string): MouseSplit;

package/dist/input/mouse-events.js

@@ -0,0 +1,153 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export const MAX_PENDING_MOUSE_CHARS = 32;
+const ESC = '\x1b';
+/** `\x1b[<b;x;yM` (press) or `…m` (release) — the only form we request. */
+const SGR_REPORT = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+/** A strict prefix of an SGR report: `\x1b[<` plus digits and semicolons. */
+const SGR_PREFIX = /^\x1b\[<[\d;]*$/;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export function isMousePrefix(s) {
+    return /^\x1B(\[(<[\d;]*|M[\s\S]{0,2})?)?$/.test(s);
+}
+/**
+ * Decode an SGR button byte into a wheel event, or `null` when the report is
+ * not a wheel notch we act on.
+ *
+ * THE ORDER OF THESE TESTS IS THE SPECIFICATION, not a presentation choice.
+ * Button 66 (wheel-left) has `b & 1 === 0` and would decode as `'up'`, so the
+ * horizontal test has to precede the direction decode.
+ */
+function decodeWheel(b, x, y, final) {
+    // 1. Not a wheel report at all (press / release / drag) — consume, emit nothing.
+    if ((b & 64) === 0)
+        return null;
+    // 2. Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+    if ((b & 3) >= 2)
+        return null;
+    // 3. Wheel buttons are press-only; a terminal that ever sent a release for one
+    //    must not produce a second step for the same physical notch.
+    if (final !== 'M')
+        return null;
+    return {
+        kind: 'wheel',
+        dir: (b & 1) === 1 ? 'down' : 'up',
+        x,
+        y,
+        shift: (b & 4) !== 0,
+        alt: (b & 8) !== 0,
+        ctrl: (b & 16) !== 0,
+    };
+}
+/**
+ * X10 legacy reports (`\x1b[M` + three chars, each `code - 32`).
+ *
+ * We never request this encoding — `?1006h` is over a decade old and every
+ * terminal that implements `?1000` implements it — but a terminal that ignored
+ * the SGR request would fall back to it, and a leaked `\x1b[M` + garbage is
+ * exactly the draft corruption I-1 exists to prevent. So it is consumed
+ * unconditionally; the coordinates are only trusted when all three bytes are
+ * plausible, because `setEncoding('utf8')` mangles raw bytes above 0x7F.
+ */
+function matchX10(s) {
+    if (s.length < 6)
+        return { kind: 'partial' };
+    const codes = [s.charCodeAt(3), s.charCodeAt(4), s.charCodeAt(5)];
+    if (codes.some((c) => c < 32 || c > 255))
+        return { kind: 'complete', length: 6, event: null };
+    const [b, x, y] = codes;
+    return { kind: 'complete', length: 6, event: decodeWheel(b - 32, x - 32, y - 32, 'M') };
+}
+/** Classify the escape sequence starting at `s[0] === ESC`. */
+function matchReport(s) {
+    if (s.length === 1)
+        return { kind: 'partial' }; // lone ESC so far
+    if (s[1] !== '[')
+        return { kind: 'none' };
+    if (s.length === 2)
+        return { kind: 'partial' }; // `\x1b[`
+    if (s[2] === '<') {
+        const m = SGR_REPORT.exec(s);
+        if (m) {
+            const b = Number(m[1]);
+            const x = Number(m[2]);
+            const y = Number(m[3]);
+            return { kind: 'complete', length: m[0].length, event: decodeWheel(b, x, y, m[4]) };
+        }
+        return SGR_PREFIX.test(s) ? { kind: 'partial' } : { kind: 'none' };
+    }
+    if (s[2] === 'M')
+        return matchX10(s);
+    return { kind: 'none' };
+}
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export function splitMouseEvents(buffer) {
+    const events = [];
+    let text = '';
+    let i = 0;
+    while (i < buffer.length) {
+        const esc = buffer.indexOf(ESC, i);
+        if (esc === -1) {
+            text += buffer.slice(i);
+            return { events, text, pending: '' };
+        }
+        text += buffer.slice(i, esc);
+        const rest = buffer.slice(esc);
+        const m = matchReport(rest);
+        if (m.kind === 'complete') {
+            if (m.event)
+                events.push(m.event);
+            i = esc + m.length;
+            continue;
+        }
+        if (m.kind === 'partial') {
+            // A tail that never resolves must not hold input hostage: past the
+            // ceiling it is ordinary text, and parsing continues after the ESC.
+            if (rest.length > MAX_PENDING_MOUSE_CHARS) {
+                text += rest;
+                return { events, text, pending: '' };
+            }
+            return { events, text, pending: rest };
+        }
+        // Not a mouse report — an arrow key, a paste, anything. Emit the ESC and
+        // resume scanning after it so the rest of the sequence reaches Ink intact.
+        text += ESC;
+        i = esc + 1;
+    }
+    return { events, text, pending: '' };
+}

package/dist/input/stdin-mouse-filter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * — some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { type WheelEvent } from './mouse-events.js';
+export interface MouseSource {
+    /** Returns an unsubscribe function. Multiple subscribers are allowed. */
+    subscribe(listener: (event: WheelEvent) => void): () => void;
+}
+export interface MouseFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /** Idempotent. Detaches from the real stdin and clears the flush timer (I-7). */
+    dispose(): void;
+}
+export declare function createMouseFilter(real: NodeJS.ReadStream): MouseFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export declare function tryCreateMouseFilter(real: NodeJS.ReadStream, onError?: (reason: string) => void): MouseFilter | null;

package/dist/input/stdin-mouse-filter.js

@@ -0,0 +1,153 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * — some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { PassThrough } from 'node:stream';
+import { splitMouseEvents } from './mouse-events.js';
+/**
+ * How long a possible-prefix tail is held before being flushed as text.
+ *
+ * This is what stops a lone `\x1b` — the Esc key, which aborts a run — from
+ * being held hostage waiting for a `[` that will never arrive. Worst-case Esc
+ * latency becomes 12 ms, and only for the keystroke that is literally a bare
+ * ESC; every other key resolves `isMousePrefix` to false immediately.
+ */
+const PENDING_FLUSH_MS = 12;
+/** Assign a method onto the PassThrough without widening its public type. */
+function define(target, name, value) {
+    Object.defineProperty(target, name, { value, writable: true, configurable: true });
+}
+export function createMouseFilter(real) {
+    const wrapper = new PassThrough();
+    const listeners = new Set();
+    let pending = '';
+    let flushTimer = null;
+    let disposed = false;
+    // --- The surface Ink reads off the stream it is handed. ------------------
+    // `isRawModeSupported()` reads `props.stdin.isTTY` (App.js:34), so this has
+    // to be a DELEGATING GETTER rather than a snapshot: a stdin that is not a TTY
+    // must still report so through the wrapper, or Ink throws instead of falling
+    // back.
+    Object.defineProperty(wrapper, 'isTTY', {
+        get: () => real.isTTY,
+        configurable: true,
+    });
+    define(wrapper, 'setRawMode', (mode) => {
+        real.setRawMode?.(mode);
+        return wrapper;
+    });
+    define(wrapper, 'ref', () => {
+        real.ref?.();
+        return wrapper;
+    });
+    define(wrapper, 'unref', () => {
+        real.unref?.();
+        return wrapper;
+    });
+    const emit = (event) => {
+        for (const listener of [...listeners])
+            listener(event);
+    };
+    const clearFlushTimer = () => {
+        if (!flushTimer)
+            return;
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    };
+    const flushPending = () => {
+        clearFlushTimer();
+        if (pending.length === 0 || disposed)
+            return;
+        const text = pending;
+        pending = '';
+        wrapper.write(text);
+    };
+    const onData = (chunk) => {
+        if (disposed)
+            return;
+        clearFlushTimer();
+        const decoded = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const split = splitMouseEvents(pending + decoded);
+        pending = split.pending;
+        if (split.text.length > 0)
+            wrapper.write(split.text);
+        for (const event of split.events)
+            emit(event);
+        if (pending.length > 0) {
+            // `.unref()` so a held tail can never keep the process alive on its own.
+            flushTimer = setTimeout(flushPending, PENDING_FLUSH_MS);
+            flushTimer.unref?.();
+        }
+    };
+    // P2-7: a closed stdin must still terminate Ink's reader, or it waits forever
+    // on a stream that will never produce another byte.
+    const onEnd = () => {
+        flushPending();
+        if (!wrapper.writableEnded)
+            wrapper.end();
+    };
+    // `setEncoding('utf8')` on the REAL stream so Node's StringDecoder handles
+    // multi-byte boundaries for us — the parser works on characters, and a UTF-8
+    // sequence split across two chunks would otherwise become two mojibake
+    // characters before it ever reached `splitMouseEvents`.
+    real.setEncoding?.('utf8');
+    real.on('data', onData);
+    real.once('end', onEnd);
+    real.once('close', onEnd);
+    return {
+        stdin: wrapper,
+        source: {
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearFlushTimer();
+            real.removeListener('data', onData);
+            real.removeListener('end', onEnd);
+            real.removeListener('close', onEnd);
+            listeners.clear();
+            // I-7: a live `'data'` listener on stdin keeps the event loop alive, and
+            // `aragon` would hang on exit instead of returning to the shell.
+            real.pause?.();
+            real.unref?.();
+        },
+    };
+}
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export function tryCreateMouseFilter(real, onError) {
+    try {
+        return createMouseFilter(real);
+    }
+    catch (err) {
+        onError?.(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}

package/dist/logging/cli-commands.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `aragon logs path | list | tail | clear | open` — the non-interactive surface.
+ *
+ * Exit codes follow the existing convention: 0 success · 1 run-time failure ·
+ * 2 usage error.
+ *
+ * THE WHOLE GROUP IS EXEMPT from the "every subcommand records one info line"
+ * rule, and that is a correctness requirement rather than tidiness. Recording a
+ * line opens today's log file, and Node opens files without
+ * `FILE_SHARE_DELETE`; on Windows — the platform this feature was asked for —
+ * `aragon logs clear --yes` would then be unable to delete the very file its own
+ * announcement had just created. These commands are the log's operations
+ * surface; giving them observable side effects on the log is backwards.
+ */
+import { type CliFlags } from '../config/load.js';
+export interface LogsCliOptions {
+    /** `-n <N>` — how many trailing lines `tail` prints (default 100). */
+    lines?: string;
+    follow?: boolean;
+    level?: string;
+    json?: boolean;
+    /** Required by `clear`; without it the command refuses. */
+    yes?: boolean;
+}
+export declare function runLogsCommand(subcommand: string, opts: LogsCliOptions, flags: CliFlags): Promise<number>;