aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
121 lines • 5.03 kB
TypeScript
/**
* AIWG CLI Structured Logger
*
* Two public surfaces:
*
* debug(scope, msg, ...args) — cheap, env-gated, stderr-only diagnostic log.
* Unchanged from Phase 4 (#921). Use this for
* ad-hoc troubleshooting prints that no-op
* unless AIWG_DEBUG is set.
*
* getLogger(scope) — structured Logger (this file's main surface).
* Every record carries full provenance
* metadata (ts, invocation_id, command, user,
* cwd, aiwg_version, git_sha, channel, node,
* platform, tty, ci) and is written to both
* stderr (pretty) and ~/.aiwg/logs/aiwg-YYYY-
* MM-DD.jsonl (structured).
*
* Phase 4.5 of the CLI Stabilization Epic (#925) extends the Phase 4 debug()
* helper into a full structured-logging stack.
*
* To enable debug-level output:
* AIWG_DEBUG=1 aiwg use all # enable everything (debug)
* AIWG_LOG_LEVEL=debug aiwg use all # same
* AIWG_LOG_LEVEL=info aiwg use all # info and above
* aiwg use all -v # info (verbose)
* aiwg use all -vv # debug
* aiwg use all --quiet # error only
* AIWG_LOG_FILE=/tmp/aiwg.jsonl aiwg use all # override JSONL path
* AIWG_LOG_DISABLE=1 aiwg --version # skip all logging
*
* Scope syntax (passed to both the debug() filter AND the Logger):
* 'cli:*' — any cli:* scope
* 'cli:use:*,net:*' — multiple globs
* 'cli:*,-cli:use:deploy' — include/exclude
*/
export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
interface Provenance {
pid: number;
ppid: number;
user: string;
host: string;
cwd: string;
aiwg_version: string;
git_sha?: string;
channel: string;
node_version: string;
platform: string;
arch: string;
os_release: string;
tty: boolean;
ci: boolean;
invocation_id: string;
}
/**
* Override the invocation ID discovered by the logger. Called from the
* top-level entry (bin/aiwg.mjs) once the ID has been minted or inherited
* from `AIWG_INVOCATION_ID`. Safe to call before the logger is used.
*/
export declare function setInvocationId(id: string): void;
export declare function getInvocationId(): string;
/**
* Override the log level from code (typically from bin/aiwg.mjs after
* parsing -v / -vv / --quiet flags). Must be called before the first
* Logger method to affect records.
*/
export declare function setLogLevel(level: LogLevel): void;
/**
* Prune daily log files older than `retentionDays`. Run once at startup
* (bounded work: one directory listing). Silent on failure.
*/
export declare function pruneOldLogs(): void;
export interface Span {
/** Close the span and emit a duration record. */
end(msg?: string, fields?: Record<string, unknown>): void;
/** Record a debug/info event within the span. */
info(msg: string, fields?: Record<string, unknown>): void;
debug(msg: string, fields?: Record<string, unknown>): void;
warn(msg: string, fields?: Record<string, unknown>): void;
error(msg: string, fields?: Record<string, unknown>): void;
}
export interface Logger {
/** Log at debug level. */
debug(msg: string, fields?: Record<string, unknown>): void;
/** Log at info level. */
info(msg: string, fields?: Record<string, unknown>): void;
/** Log at warn level. */
warn(msg: string, fields?: Record<string, unknown>): void;
/** Log at error level. */
error(msg: string, fields?: Record<string, unknown>): void;
/** Spawn a child logger with a nested scope and merged extra fields. */
child(opts: {
scope?: string;
fields?: Record<string, unknown>;
}): Logger;
/** Start a named span. Call span.end() to emit duration_ms. */
span(name: string, fields?: Record<string, unknown>): Span;
}
export declare function getLogger(scope?: string, extraFields?: Record<string, unknown>): Logger;
/**
* Emit a debug log record to stderr. No-op when AIWG_DEBUG is unset or
* the scope does not match.
*
* Backward-compatible with the Phase 4 API. New code should prefer
* getLogger(scope).debug() which also writes to the JSONL sink.
*/
export declare function debug(scope: string, ...args: unknown[]): void;
export declare function isDebugEnabled(scope: string): boolean;
/**
* Return the effective logger configuration — used by `aiwg version --verbose`
* and `aiwg diagnose` to surface where logs go and what level is in effect.
*/
export declare function getLoggerInfo(): {
level: LogLevel;
disabled: boolean;
logFile: string | null;
retentionDays: number;
provenance: Provenance;
};
export {};
//# sourceMappingURL=log.d.ts.map