@aragon-agent/cli 0.4.3 → 0.5.1

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/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>;

package/dist/logging/cli-commands.js

@@ -0,0 +1,221 @@
+/**
+ * `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 { existsSync, readFileSync, readdirSync, rmSync, statSync, unwatchFile, watchFile, } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import process from 'node:process';
+import { getLogsDir } from '../config/app-paths.js';
+import { loadConfig } from '../config/load.js';
+import { isLogFileName } from './file-sink.js';
+import { getLogger } from './logger.js';
+import { LOG_LEVELS, isLogLevel } from './levels.js';
+const EXIT_OK = 0;
+const EXIT_RUNTIME = 1;
+const EXIT_USAGE = 2;
+const DEFAULT_TAIL_LINES = 100;
+/** `watchFile` poll interval for `--follow` (Q2). */
+const FOLLOW_POLL_MS = 500;
+/** The effective log directory for this run (flag › env › file › default). */
+function resolveLogsDir(flags) {
+    const configured = loadConfig(flags).log.dir.trim();
+    return configured.length > 0 ? configured : getLogsDir();
+}
+function listLogFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter(isLogFileName)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function runLogsCommand(subcommand, opts, flags) {
+    const dir = resolveLogsDir(flags);
+    switch (subcommand) {
+        case 'path':
+            return runPath(dir);
+        case 'list':
+            return runList(dir);
+        case 'tail':
+            return runTail(dir, opts);
+        case 'clear':
+            return runClear(dir, opts);
+        case 'open':
+            return runOpen(dir);
+        default:
+            process.stderr.write(`Unknown logs subcommand "${subcommand}". Try: path | list | tail | clear | open.\n`);
+            return EXIT_USAGE;
+    }
+}
+function runPath(dir) {
+    const logger = getLogger();
+    process.stdout.write(`${logger.currentLogPath()}\n`);
+    process.stdout.write(`directory: ${dir}\n`);
+    // `debug` and `trace` write prompt and tool output verbatim; a user about to
+    // attach a log to a bug report should be told that here, not discover it.
+    process.stdout.write('level: ' + logger.level + ' (debug/trace record prompt and tool content)\n');
+    if (logger.sinkDisabled) {
+        process.stdout.write(`WARNING: logging is disabled after write failures: ${logger.sinkError}\n`);
+    }
+    return EXIT_OK;
+}
+function runList(dir) {
+    const files = listLogFiles(dir);
+    if (files.length === 0) {
+        process.stdout.write(`No log files in ${dir}.\n`);
+        return EXIT_OK;
+    }
+    for (const name of files) {
+        try {
+            const stat = statSync(join(dir, name));
+            process.stdout.write(`${name}  ${stat.size} bytes  ${stat.mtime.toISOString()}\n`);
+        }
+        catch {
+            process.stdout.write(`${name}  (unreadable)\n`);
+        }
+    }
+    return EXIT_OK;
+}
+/** Render one JSONL record as a human-readable line; pass unparseable ones through. */
+function renderRecord(line) {
+    try {
+        const record = JSON.parse(line);
+        const data = record.data ? ` ${JSON.stringify(record.data)}` : '';
+        const level = (record.lv ?? '?').padEnd(5);
+        return `${record.ts ?? ''} ${level} ${record.scope ?? '-'}: ${record.msg ?? ''}${data}`;
+    }
+    catch {
+        return line;
+    }
+}
+function passesLevel(line, min) {
+    if (!min)
+        return true;
+    try {
+        const record = JSON.parse(line);
+        if (!isLogLevel(record.lv))
+            return true;
+        return LOG_LEVELS[record.lv] <= LOG_LEVELS[min];
+    }
+    catch {
+        return true;
+    }
+}
+function printLines(lines, opts, min) {
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        if (!passesLevel(line, min))
+            continue;
+        process.stdout.write(`${opts.json ? line : renderRecord(line)}\n`);
+    }
+}
+function runTail(dir, opts) {
+    const files = listLogFiles(dir);
+    const target = files.length > 0 ? join(dir, files[files.length - 1]) : null;
+    if (!target) {
+        process.stdout.write(`No log files in ${dir}.\n`);
+        return EXIT_OK;
+    }
+    if (opts.level !== undefined && !isLogLevel(opts.level)) {
+        process.stderr.write(`Unknown level "${opts.level}".\n`);
+        return EXIT_USAGE;
+    }
+    const min = opts.level;
+    const count = Number.parseInt(opts.lines ?? '', 10);
+    const wanted = Number.isFinite(count) && count > 0 ? count : DEFAULT_TAIL_LINES;
+    let consumed = 0;
+    try {
+        const raw = readFileSync(target, 'utf-8');
+        consumed = raw.length;
+        printLines(raw.split('\n').slice(-wanted), opts, min);
+    }
+    catch (err) {
+        process.stderr.write(`Could not read ${target}: ${err instanceof Error ? err.message : err}\n`);
+        return EXIT_RUNTIME;
+    }
+    if (!opts.follow)
+        return EXIT_OK;
+    // `watchFile` (polling) rather than `fs.watch`: these files are ROTATED by
+    // rename, which is exactly the case `fs.watch` reports inconsistently across
+    // platforms. Half a second of latency is invisible to someone reading a log.
+    watchFile(target, { interval: FOLLOW_POLL_MS }, () => {
+        try {
+            const raw = readFileSync(target, 'utf-8');
+            if (raw.length < consumed)
+                consumed = 0; // truncated or rotated underneath us
+            printLines(raw.slice(consumed).split('\n'), opts, min);
+            consumed = raw.length;
+        }
+        catch {
+            // The file may vanish mid-rotation; the next poll picks the new one up.
+        }
+    });
+    process.on('SIGINT', () => unwatchFile(target));
+    return EXIT_OK;
+}
+/**
+ * Delete every log file.
+ *
+ * Closes this process's own sink first — otherwise the day's file is held open
+ * by the very command trying to remove it. Failures are reported PER FILE
+ * rather than aborting: another `aragon` window holding one file open should
+ * not stop the other nine from being cleared.
+ */
+function runClear(dir, opts) {
+    if (!opts.yes) {
+        process.stderr.write('Refusing to delete log files without --yes.\n');
+        return EXIT_USAGE;
+    }
+    getLogger().closeSink();
+    const files = listLogFiles(dir);
+    const blocked = [];
+    let removed = 0;
+    for (const name of files) {
+        try {
+            rmSync(join(dir, name), { force: true });
+            removed += 1;
+        }
+        catch {
+            blocked.push(name);
+        }
+    }
+    process.stdout.write(`Deleted ${removed} log file(s).\n`);
+    if (blocked.length === 0)
+        return EXIT_OK;
+    process.stderr.write(`In use, not deleted: ${blocked.join(', ')}\n`);
+    return EXIT_RUNTIME;
+}
+/**
+ * Open the log directory in the platform file manager.
+ *
+ * A convenience, so a failure degrades to printing the path and still exits 0 —
+ * being unable to launch a file manager is not an error in a logging command.
+ */
+function runOpen(dir) {
+    const opener = process.platform === 'win32' ? 'explorer' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    try {
+        const child = spawn(opener, [dir], { stdio: 'ignore', detached: true });
+        child.on('error', () => process.stdout.write(`${dir}\n`));
+        child.unref();
+    }
+    catch {
+        process.stdout.write(`${dir}\n`);
+    }
+    return EXIT_OK;
+}

package/dist/logging/file-sink.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The file sink — a memory queue in front of ONE synchronous append fd.
+ *
+ * WHY NOT `createWriteStream` (design P1-4). Three reasons, each fatal on its
+ * own:
+ *   - a stream's internal buffer is DISCARDED by `process.exit()`, and the
+ *     records still sitting in it during a crash are the ones worth having;
+ *   - an exit-path `appendFileSync` plus a steady-state stream are two writers
+ *     on one file with no defined ordering between them;
+ *   - a stream reports write failures through an async `'error'` event, which
+ *     THROWS when nobody is listening — so "make the log directory read-only"
+ *     would take the whole CLI down instead of degrading.
+ *
+ * With `openSync` + `writeSync` every failure is a synchronous throw one
+ * `try/catch` away, and `flushSync()` and the steady-state flush are literally
+ * the same code path. `O_APPEND` keeps concurrent `aragon` processes from
+ * truncating each other, and one batched `writeSync` stays far below any size
+ * that could tear a line.
+ */
+export interface FileSinkOptions {
+    dir: string;
+    maxFileBytes: number;
+    maxFiles: number;
+    /**
+     * Renders the "records were dropped" warning line. Not a persisted setting —
+     * the sink handles LINES and has no session id or clock of its own, so the
+     * logger supplies the rendering and the sink decides when it is needed.
+     */
+    formatDropNotice?: (count: number) => string;
+    /** Called once, when the sink gives up on writing. */
+    onFailure?: (reason: string) => void;
+}
+/**
+ * `YYYY-MM-DD` in LOCAL time.
+ *
+ * Local, not UTC, and the record timestamps use the same clock deliberately: a
+ * user west of UTC would otherwise find an evening's records filed under the
+ * previous local day and stamped with the next one, which makes "open today's
+ * log" a lie twice over.
+ */
+export declare function localDateStamp(date?: Date): string;
+/**
+ * Delete the oldest files until at most `maxFiles` remain.
+ *
+ * A STANDALONE STEP, called on three occasions — first write of the process,
+ * midnight roll-over, and size rotation — because retention that only ran
+ * during size rotation would never fire for the many users who never reach
+ * `maxFileBytes`: one file per day, forever, under a setting that says 10.
+ *
+ * Never throws. On Windows another `aragon` process may hold a handle on a file
+ * we would like to remove; that is a reason to skip it, not to fail a write.
+ */
+export declare function enforceRetention(dir: string, maxFiles: number): void;
+export declare class FileSink {
+    private options;
+    private queue;
+    private dropped;
+    private fd;
+    private currentFile;
+    private currentDay;
+    private currentSize;
+    private timer;
+    private failures;
+    private failed;
+    private failureReason;
+    private retentionRun;
+    constructor(options: FileSinkOptions);
+    get disabled(): boolean;
+    get lastError(): string | undefined;
+    /** The file records are going to right now (may not exist until first write). */
+    get currentPath(): string;
+    /** Enqueue one already-serialised line (including its trailing newline). */
+    write(line: string): void;
+    /** Threshold/timer flush. Identical to `flushSync` — see the module header. */
+    flush(): void;
+    /** Idempotent: safe to call from `exit`, a signal handler and a crash handler. */
+    flushSync(): void;
+    close(): void;
+    /**
+     * Apply new settings. Changing the directory closes the current fd so the next
+     * write lazily opens the new one; the sink never eagerly creates a directory
+     * the user may never write a record into.
+     */
+    reconfigure(options: FileSinkOptions): void;
+    private takeBatch;
+    /** Open (or roll) the target file so `incomingBytes` can be appended to it. */
+    private prepareTarget;
+    private openTarget;
+    /**
+     * flush → close → rename → open → retention, in that order.
+     *
+     * `closeSync` MUST precede `renameSync`: on Windows renaming a file the
+     * process still holds a handle on fails with EPERM. A failed rename is
+     * swallowed and writing continues into the original file — two instances
+     * rotating at once should cost an extra small file, not the log itself.
+     */
+    private rotateBySize;
+    /** Highest existing `aragon-<day>.<n>.log` index, plus one. */
+    private nextRotationIndex;
+    private closeFd;
+    /**
+     * Logging failure must never become CLI failure, and must never write to the
+     * terminal itself (invariant I-4 — a stray line permanently misaligns the
+     * full-screen frame). The owner is told once through `onFailure`, which routes
+     * to a toast when the TUI is mounted and to stderr when it is not.
+     */
+    private recordFailure;
+    private startTimer;
+    private stopTimer;
+}
+/** Exposed for the CLI's `logs` commands, which list the same file family. */
+export declare function isLogFileName(name: string): boolean;
+/** The log file the CURRENT day would use inside a log directory. */
+export declare function currentLogFileName(date?: Date): string;