agent-tail-core 0.0.1

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { n as cmd_run, r as cmd_wrap, t as cmd_init } from "./commands-BO9MYtxZ.mjs";
+import { parseArgs } from "node:util";
+
+//#region src/cli.ts
+const HELP = `
+  \x1b[1magent-tail\x1b[0m — Pipe any dev server's output into your unified log session
+
+  \x1b[1mUsage:\x1b[0m
+    agent-tail init                          Create a new log session
+    agent-tail wrap <name> -- <command...>   Wrap a command, pipe output to <name>.log
+    agent-tail run <config...>               Run multiple services concurrently
+
+  \x1b[1mOptions:\x1b[0m
+    --log-dir <dir>       Log directory relative to cwd (default: tmp/logs)
+    --max-sessions <n>    Max sessions to keep (default: 10)
+    --no-combined         Don't write to combined.log
+    -h, --help            Show this help
+
+  \x1b[1mExamples:\x1b[0m
+    agent-tail init
+    agent-tail wrap api -- uv run fastapi-server
+    agent-tail wrap worker -- python -m celery worker
+    agent-tail run "fe: npm run dev" "api: uv run server" "worker: uv run worker"
+`;
+function parse_cli_options(args) {
+	const dash_index = args.indexOf("--");
+	const before_dash = dash_index >= 0 ? args.slice(0, dash_index) : args;
+	const rest = dash_index >= 0 ? args.slice(dash_index + 1) : [];
+	const { values, positionals } = parseArgs({
+		args: before_dash,
+		options: {
+			"log-dir": {
+				type: "string",
+				default: "tmp/logs"
+			},
+			"max-sessions": {
+				type: "string",
+				default: "10"
+			},
+			"no-combined": {
+				type: "boolean",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		},
+		allowPositionals: true,
+		strict: false
+	});
+	if (values.help) {
+		console.log(HELP);
+		process.exit(0);
+	}
+	return {
+		options: {
+			log_dir: values["log-dir"] ?? "tmp/logs",
+			max_sessions: parseInt(values["max-sessions"] ?? "10", 10),
+			combined: !values["no-combined"]
+		},
+		positionals,
+		rest
+	};
+}
+async function main() {
+	const args = process.argv.slice(2);
+	if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+		console.log(HELP);
+		process.exit(0);
+	}
+	const subcommand = args[0];
+	const { options, positionals, rest } = parse_cli_options(args.slice(1));
+	const project_root = process.cwd();
+	try {
+		switch (subcommand) {
+			case "init": {
+				const session_dir = cmd_init(project_root, options);
+				console.log(session_dir);
+				break;
+			}
+			case "wrap": {
+				const code = await cmd_wrap(project_root, positionals[0], rest, options);
+				process.exit(code);
+				break;
+			}
+			case "run":
+				await cmd_run(project_root, positionals, options);
+				process.exit(0);
+				break;
+			default:
+				console.error(`\x1b[36m[agent-tail]\x1b[0m Unknown command: ${subcommand}`);
+				console.log(HELP);
+				process.exit(1);
+		}
+	} catch (err) {
+		console.error(`\x1b[36m[agent-tail]\x1b[0m Error: ${err.message}`);
+		process.exit(1);
+	}
+}
+main();
+
+//#endregion
+export {  };

package/dist/commands-BO9MYtxZ.mjs

@@ -0,0 +1,291 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+//#region src/log-manager.ts
+const PLUGIN_PREFIX = "\x1B[36m[agent-tail]\x1B[0m";
+let session_counter = 0;
+var LogManager = class {
+	constructor(options) {
+		this.options = options;
+	}
+	initialize(project_root) {
+		const log_dir = path.resolve(project_root, this.options.logDir);
+		let session_name = this.create_session_name();
+		let session_dir = path.join(log_dir, session_name);
+		while (fs.existsSync(session_dir)) {
+			session_counter++;
+			session_name = `${this.create_session_name()}-${session_counter}`;
+			session_dir = path.join(log_dir, session_name);
+		}
+		fs.mkdirSync(session_dir, { recursive: true });
+		this.update_latest_symlink(log_dir, session_dir);
+		this.prune_sessions(log_dir);
+		const log_file = path.join(session_dir, this.options.logFileName);
+		fs.writeFileSync(log_file, "");
+		if (this.options.warnOnMissingGitignore) this.check_gitignore(project_root);
+		console.log(`${PLUGIN_PREFIX} Writing to ${log_file}`);
+		return log_file;
+	}
+	create_session_name() {
+		return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+	}
+	update_latest_symlink(log_dir, session_dir) {
+		const latest_link = path.join(log_dir, "latest");
+		try {
+			fs.unlinkSync(latest_link);
+		} catch {}
+		const relative_target = path.relative(log_dir, session_dir);
+		fs.symlinkSync(relative_target, latest_link);
+	}
+	prune_sessions(log_dir) {
+		try {
+			const session_dirs = fs.readdirSync(log_dir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== "latest").map((e) => e.name).sort();
+			const to_remove = session_dirs.slice(0, Math.max(0, session_dirs.length - this.options.maxLogSessions));
+			for (const dir_name of to_remove) {
+				const dir_path = path.join(log_dir, dir_name);
+				fs.rmSync(dir_path, {
+					recursive: true,
+					force: true
+				});
+				console.log(`${PLUGIN_PREFIX} Pruned old session: ${dir_name}`);
+			}
+		} catch {}
+	}
+	/**
+	* Resolve the current session directory. If a `latest` symlink exists and
+	* points to a valid directory, return it. Otherwise create a new session.
+	*/
+	resolve_session(project_root) {
+		const log_dir = path.resolve(project_root, this.options.logDir);
+		const latest_link = path.join(log_dir, "latest");
+		try {
+			const real = fs.realpathSync(latest_link);
+			if (fs.statSync(real).isDirectory()) return real;
+		} catch {}
+		const log_path = this.initialize(project_root);
+		return path.dirname(log_path);
+	}
+	check_gitignore(project_root) {
+		const gitignore_path = path.join(project_root, ".gitignore");
+		try {
+			const lines = fs.readFileSync(gitignore_path, "utf-8").split("\n").map((l) => l.trim());
+			const log_dir = this.options.logDir;
+			const parts = log_dir.split("/");
+			let covered = false;
+			for (let i = 1; i <= parts.length; i++) {
+				const prefix = parts.slice(0, i).join("/");
+				if (lines.includes(prefix) || lines.includes(prefix + "/") || lines.includes("/" + prefix) || lines.includes("/" + prefix + "/")) {
+					covered = true;
+					break;
+				}
+			}
+			if (!covered) console.warn(`${PLUGIN_PREFIX} \x1b[33mWarning:\x1b[0m "${log_dir}" is not in your .gitignore. Add "${log_dir}/" to your .gitignore to avoid committing log files.`);
+		} catch {
+			console.warn(`${PLUGIN_PREFIX} \x1b[33mWarning:\x1b[0m No .gitignore found. Consider adding one with "${this.options.logDir}/" to avoid committing log files.`);
+		}
+	}
+};
+
+//#endregion
+//#region src/types.ts
+const DEFAULT_OPTIONS = {
+	logDir: "tmp/logs",
+	logFileName: "browser.log",
+	maxLogSessions: 10,
+	endpoint: "/__browser-logs",
+	flushInterval: 500,
+	maxBatchSize: 50,
+	maxSerializeLength: 2e3,
+	warnOnMissingGitignore: true,
+	levels: [
+		"log",
+		"warn",
+		"error",
+		"info",
+		"debug"
+	],
+	captureErrors: true,
+	captureRejections: true
+};
+function resolve_options(user_options) {
+	return {
+		...DEFAULT_OPTIONS,
+		...user_options
+	};
+}
+
+//#endregion
+//#region src/commands.ts
+const PREFIX = "\x1B[36m[agent-tail]\x1B[0m";
+const DEFAULT_CLI_OPTIONS = {
+	log_dir: "tmp/logs",
+	max_sessions: 10,
+	combined: true
+};
+function create_manager(options) {
+	return new LogManager(resolve_options({
+		logDir: options.log_dir,
+		maxLogSessions: options.max_sessions
+	}));
+}
+/**
+* Create a new log session. Returns the session directory path.
+*/
+function cmd_init(project_root, options = DEFAULT_CLI_OPTIONS) {
+	const log_path = create_manager(options).initialize(project_root);
+	return path.dirname(log_path);
+}
+/**
+* Resolve the current session directory (reuse if exists, create if not).
+*/
+function resolve_session_dir(project_root, options = DEFAULT_CLI_OPTIONS) {
+	return create_manager(options).resolve_session(project_root);
+}
+function parse_service_configs(args) {
+	return args.map((arg) => {
+		const colon_index = arg.indexOf(":");
+		if (colon_index === -1) throw new Error(`Invalid service format "${arg}". Expected "name: command", e.g. "api: uv run server"`);
+		return {
+			name: arg.slice(0, colon_index).trim(),
+			command: arg.slice(colon_index + 1).trim()
+		};
+	});
+}
+/**
+* Write data to a log stream and optionally to combined.log with a prefix.
+*/
+function write_to_logs(chunk, name, log_stream, combined_stream) {
+	log_stream.write(chunk);
+	if (combined_stream) {
+		const lines = chunk.toString().split("\n");
+		for (let i = 0; i < lines.length; i++) if (lines[i].length > 0) combined_stream.write(`[${name}] ${lines[i]}\n`);
+		else if (i < lines.length - 1) combined_stream.write("\n");
+	}
+}
+/**
+* Wrap a single command, piping its output to {name}.log in the session.
+* Returns a promise that resolves with the exit code.
+*/
+function cmd_wrap(project_root, name, command, options = DEFAULT_CLI_OPTIONS) {
+	if (!name) throw new Error("wrap requires a service name");
+	if (command.length === 0) throw new Error("wrap requires a command after --");
+	const session_dir = resolve_session_dir(project_root, options);
+	const log_file = path.join(session_dir, `${name}.log`);
+	const log_stream = fs.createWriteStream(log_file, { flags: "a" });
+	let combined_stream = null;
+	if (options.combined) {
+		const combined_file = path.join(session_dir, "combined.log");
+		combined_stream = fs.createWriteStream(combined_file, { flags: "a" });
+	}
+	console.log(`${PREFIX} ${name} → ${log_file}`);
+	const child = spawn("sh", ["-c", command.join(" ")], {
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
+		env: { ...process.env }
+	});
+	child.stdout?.on("data", (chunk) => {
+		process.stdout.write(chunk);
+		write_to_logs(chunk, name, log_stream, combined_stream);
+	});
+	child.stderr?.on("data", (chunk) => {
+		process.stderr.write(chunk);
+		write_to_logs(chunk, name, log_stream, combined_stream);
+	});
+	return new Promise((resolve, reject) => {
+		child.on("close", (code) => {
+			log_stream.end();
+			combined_stream?.end();
+			resolve(code ?? 0);
+		});
+		child.on("error", (err) => {
+			log_stream.end();
+			combined_stream?.end();
+			reject(err);
+		});
+		for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => {
+			child.kill(signal);
+		});
+	});
+}
+const COLORS = [
+	"\x1B[34m",
+	"\x1B[32m",
+	"\x1B[33m",
+	"\x1B[35m",
+	"\x1B[36m",
+	"\x1B[31m"
+];
+const RESET = "\x1B[0m";
+/**
+* Run multiple services concurrently.
+* Returns a promise that resolves when all services exit.
+*/
+function cmd_run(project_root, service_args, options = DEFAULT_CLI_OPTIONS) {
+	if (service_args.length === 0) throw new Error("run requires at least one service");
+	const services = parse_service_configs(service_args);
+	const log_path = create_manager(options).initialize(project_root);
+	const session_dir = path.dirname(log_path);
+	let combined_stream = null;
+	if (options.combined) {
+		const combined_file = path.join(session_dir, "combined.log");
+		combined_stream = fs.createWriteStream(combined_file, { flags: "a" });
+	}
+	console.log(`${PREFIX} Session: ${session_dir}`);
+	for (const svc of services) console.log(`${PREFIX}   ${svc.name} → ${svc.name}.log`);
+	if (options.combined) console.log(`${PREFIX}   combined → combined.log`);
+	console.log("");
+	const children = [];
+	const promises = services.map((svc, i) => {
+		const tag = `${COLORS[i % COLORS.length]}[${svc.name}]${RESET}`;
+		const log_file = path.join(session_dir, `${svc.name}.log`);
+		const log_stream = fs.createWriteStream(log_file, { flags: "a" });
+		const child = spawn("sh", ["-c", svc.command], {
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			],
+			env: { ...process.env }
+		});
+		function handle(target, chunk) {
+			const text = chunk.toString();
+			log_stream.write(chunk);
+			const lines = text.split("\n");
+			for (let j = 0; j < lines.length; j++) if (lines[j].length > 0) {
+				target.write(`${tag} ${lines[j]}\n`);
+				combined_stream?.write(`[${svc.name}] ${lines[j]}\n`);
+			} else if (j < lines.length - 1) {
+				target.write("\n");
+				combined_stream?.write("\n");
+			}
+		}
+		child.stdout?.on("data", (chunk) => handle(process.stdout, chunk));
+		child.stderr?.on("data", (chunk) => handle(process.stderr, chunk));
+		children.push(child);
+		return new Promise((resolve) => {
+			child.on("close", (code) => {
+				log_stream.end();
+				if (code !== 0 && code !== null) console.log(`${tag} exited with code ${code}`);
+				resolve();
+			});
+			child.on("error", (err) => {
+				console.error(`${tag} Failed to start: ${err.message}`);
+				log_stream.end();
+				resolve();
+			});
+		});
+	});
+	for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => {
+		for (const child of children) child.kill(signal);
+	});
+	return Promise.all(promises).then(() => {
+		combined_stream?.end();
+	});
+}
+
+//#endregion
+export { resolve_session_dir as a, LogManager as c, parse_service_configs as i, cmd_run as n, DEFAULT_OPTIONS as o, cmd_wrap as r, resolve_options as s, cmd_init as t };

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+//#region src/types.d.ts
+interface BrowserLogsOptions {
+  /** Directory for log storage, relative to project root. Default: "tmp/logs" */
+  logDir?: string;
+  /** Log file name within each session directory. Default: "browser.log" */
+  logFileName?: string;
+  /** Maximum number of log session directories to retain. Default: 10 */
+  maxLogSessions?: number;
+  /** Server endpoint path for receiving log batches. Default: "/__browser-logs" */
+  endpoint?: string;
+  /** Client-side flush interval in milliseconds. Default: 500 */
+  flushInterval?: number;
+  /** Client-side max batch size before immediate flush. Default: 50 */
+  maxBatchSize?: number;
+  /** Max character length for serialized objects in client. Default: 2000 */
+  maxSerializeLength?: number;
+  /** Warn in terminal if logDir is not in .gitignore. Default: true */
+  warnOnMissingGitignore?: boolean;
+  /** Console methods to intercept. Default: ["log", "warn", "error", "info", "debug"] */
+  levels?: string[];
+  /** Capture window unhandled errors. Default: true */
+  captureErrors?: boolean;
+  /** Capture unhandled promise rejections. Default: true */
+  captureRejections?: boolean;
+}
+interface LogEntry {
+  level: string;
+  args: string[];
+  timestamp: string;
+  url?: string;
+  stack?: string;
+}
+type ResolvedOptions = Required<BrowserLogsOptions>;
+declare const DEFAULT_OPTIONS: ResolvedOptions;
+declare function resolve_options(user_options?: BrowserLogsOptions): ResolvedOptions;
+//#endregion
+//#region src/formatter.d.ts
+declare function format_log_line(entry: LogEntry): string;
+//#endregion
+//#region src/client.d.ts
+declare function generate_client_script(options: ResolvedOptions): string;
+//#endregion
+//#region src/log-manager.d.ts
+declare class LogManager {
+  private options;
+  constructor(options: ResolvedOptions);
+  initialize(project_root: string): string;
+  create_session_name(): string;
+  update_latest_symlink(log_dir: string, session_dir: string): void;
+  prune_sessions(log_dir: string): void;
+  /**
+   * Resolve the current session directory. If a `latest` symlink exists and
+   * points to a valid directory, return it. Otherwise create a new session.
+   */
+  resolve_session(project_root: string): string;
+  check_gitignore(project_root: string): void;
+}
+//#endregion
+//#region src/commands.d.ts
+interface CliOptions {
+  log_dir: string;
+  max_sessions: number;
+  combined: boolean;
+}
+/**
+ * Create a new log session. Returns the session directory path.
+ */
+declare function cmd_init(project_root: string, options?: CliOptions): string;
+/**
+ * Resolve the current session directory (reuse if exists, create if not).
+ */
+declare function resolve_session_dir(project_root: string, options?: CliOptions): string;
+interface ServiceConfig {
+  name: string;
+  command: string;
+}
+declare function parse_service_configs(args: string[]): ServiceConfig[];
+/**
+ * Wrap a single command, piping its output to {name}.log in the session.
+ * Returns a promise that resolves with the exit code.
+ */
+declare function cmd_wrap(project_root: string, name: string, command: string[], options?: CliOptions): Promise<number>;
+/**
+ * Run multiple services concurrently.
+ * Returns a promise that resolves when all services exit.
+ */
+declare function cmd_run(project_root: string, service_args: string[], options?: CliOptions): Promise<void>;
+//#endregion
+export { type BrowserLogsOptions, type CliOptions, DEFAULT_OPTIONS, type LogEntry, LogManager, type ResolvedOptions, type ServiceConfig, cmd_init, cmd_run, cmd_wrap, format_log_line, generate_client_script, parse_service_configs, resolve_options, resolve_session_dir };

package/dist/index.mjs

@@ -0,0 +1,105 @@
+import { a as resolve_session_dir, c as LogManager, i as parse_service_configs, n as cmd_run, o as DEFAULT_OPTIONS, r as cmd_wrap, s as resolve_options, t as cmd_init } from "./commands-BO9MYtxZ.mjs";
+
+//#region src/formatter.ts
+function format_log_line(entry) {
+	return `[${entry.timestamp}] [${entry.level.toUpperCase().padEnd(7)}] ${entry.args.join(" ")}${entry.url ? ` (${entry.url})` : ""}${entry.stack ? `\n    ${entry.stack.split("\n").join("\n    ")}` : ""}\n`;
+}
+
+//#endregion
+//#region src/client.ts
+function generate_client_script(options) {
+	return `(function() {
+    var BATCH = [];
+    var FLUSH_INTERVAL = ${options.flushInterval};
+    var MAX_BATCH = ${options.maxBatchSize};
+    var MAX_SERIALIZE = ${options.maxSerializeLength};
+    var ENDPOINT = ${JSON.stringify(options.endpoint)};
+    var LEVELS = ${JSON.stringify(options.levels)};
+    var CAPTURE_ERRORS = ${options.captureErrors};
+    var CAPTURE_REJECTIONS = ${options.captureRejections};
+    var timer = null;
+
+    function serialize(arg) {
+        if (arg === null) return "null";
+        if (arg === undefined) return "undefined";
+        if (arg instanceof Error) return arg.stack || arg.message || String(arg);
+        if (typeof arg === "string") return arg;
+        try {
+            var s = JSON.stringify(arg, null, 2);
+            return s.length > MAX_SERIALIZE ? s.slice(0, MAX_SERIALIZE) + "..." : s;
+        } catch(e) {
+            return String(arg);
+        }
+    }
+
+    function get_timestamp() {
+        var d = new Date();
+        return d.toTimeString().slice(0, 8) + "." + String(d.getMilliseconds()).padStart(3, "0");
+    }
+
+    function queue(level, args, extra) {
+        var entry = {
+            level: level,
+            args: Array.prototype.map.call(args, serialize),
+            timestamp: get_timestamp()
+        };
+        if (extra) {
+            if (extra.url) entry.url = extra.url;
+            if (extra.stack) entry.stack = extra.stack;
+        }
+        BATCH.push(entry);
+        if (BATCH.length >= MAX_BATCH) flush();
+        else if (!timer) timer = setTimeout(flush, FLUSH_INTERVAL);
+    }
+
+    function flush() {
+        if (timer) { clearTimeout(timer); timer = null; }
+        if (!BATCH.length) return;
+        var payload = JSON.stringify(BATCH);
+        BATCH = [];
+        try {
+            navigator.sendBeacon(ENDPOINT, payload);
+        } catch(e) {
+            fetch(ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: payload,
+                keepalive: true
+            }).catch(function() {});
+        }
+    }
+
+    LEVELS.forEach(function(level) {
+        var original = console[level];
+        if (!original) return;
+        console[level] = function() {
+            queue(level, arguments);
+            return original.apply(console, arguments);
+        };
+    });
+
+    if (CAPTURE_ERRORS) {
+        window.addEventListener("error", function(e) {
+            queue("uncaught_error", [e.message], {
+                url: e.filename + ":" + e.lineno + ":" + e.colno,
+                stack: e.error && e.error.stack ? e.error.stack : undefined
+            });
+        });
+    }
+
+    if (CAPTURE_REJECTIONS) {
+        window.addEventListener("unhandledrejection", function(e) {
+            var reason = e.reason;
+            var msg = reason instanceof Error ? reason.message : String(reason);
+            var stack = reason instanceof Error ? reason.stack : undefined;
+            queue("unhandled_rejection", [msg], { stack: stack });
+        });
+    }
+
+    window.addEventListener("beforeunload", flush);
+    window.addEventListener("pagehide", flush);
+})();`;
+}
+
+//#endregion
+export { DEFAULT_OPTIONS, LogManager, cmd_init, cmd_run, cmd_wrap, format_log_line, generate_client_script, parse_service_configs, resolve_options, resolve_session_dir };

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "agent-tail-core",
+    "type": "module",
+    "version": "0.0.1",
+    "description": "Core utilities for agent-tail log capture plugins.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/gillkyle/agent-tail",
+        "directory": "packages/core"
+    },
+    "author": "Kyle Gill",
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.mts"
+        }
+    },
+    "main": "./dist/index.mjs",
+    "types": "./dist/index.d.mts",
+    "bin": {
+        "agent-tail": "./dist/cli.mjs"
+    },
+    "files": ["dist"],
+    "scripts": {
+        "build": "tsdown",
+        "typecheck": "tsc --noEmit"
+    },
+    "devDependencies": {
+        "tsdown": "^0.18.1"
+    }
+}