@schema-weaver/pg-connector 0.0.0-stage → 2.0.1

package/dist/types/cli/daemon/state.d.ts

@@ -0,0 +1,157 @@
+import { PidFile } from './pid-file';
+import { DaemonStatus } from './status-file';
+/**
+ * Variables the detached daemon child is allowed to inherit, copied verbatim.
+ *
+ * The child used to be spawned with `{ ...process.env }`, which handed it every
+ * variable the operator's shell happened to contain — including nine that
+ * materially change security posture (see `UNRECOGNISED_SECURITY_ENV`). The
+ * list below is the complete set of variables the daemon actually needs.
+ *
+ * Anything not listed here is dropped rather than inherited.
+ */
+export declare const DAEMON_ENV_ALLOW_LIST: readonly string[];
+/**
+ * Variables that look like configuration but are NOT allow-listed, and each
+ * value that would change the security posture if honoured.
+ *
+ * These are recognised — so they are not silently ignored — but they are
+ * refused rather than applied. `buildDaemonChildEnv` reports them so the parent
+ * can warn, and `stripUnrecognisedSecurityEnv` removes them so an
+ * already-running foreground process cannot be steered by an inherited value.
+ */
+export declare const UNRECOGNISED_SECURITY_ENV: Readonly<Record<string, string>>;
+export interface DaemonChildEnvOptions {
+    /**
+     * Absolute, already-resolved agent home directory. Passed through as
+     * `SW_AGENT_HOME` so the child cannot be redirected to a different state
+     * directory by re-reading `PG_CONNECTOR_HOME` from its own environment.
+     */
+    agentHome: string;
+}
+export interface DaemonChildEnvResult {
+    env: Record<string, string>;
+    /** Recognised-but-refused variables that were present and are now dropped. */
+    refused: Array<{
+        name: string;
+        effect: string;
+    }>;
+}
+/**
+ * Build the environment for the detached daemon child.
+ *
+ * Only allow-listed variables are copied. `SW_AGENT_HOME` is pinned to the
+ * home the parent already resolved, and `SW_AGENT_DAEMON=1` is set. Anything in
+ * `UNRECOGNISED_SECURITY_ENV` that happened to be set is dropped and reported
+ * instead of being inherited.
+ */
+export declare function buildDaemonChildEnv(source: NodeJS.ProcessEnv | undefined, opts: DaemonChildEnvOptions): DaemonChildEnvResult;
+/**
+ * Delete every recognised-but-refused security variable from the live
+ * process environment. Called once at daemon startup so that a foreground
+ * `sw-agent start` cannot be steered by a value inherited from a `.service`
+ * file, wrapper script, PM2 ecosystem file, CI job, or Dockerfile `ENV`.
+ *
+ * Returns the names that were removed so the caller can log them.
+ */
+export declare function stripUnrecognisedSecurityEnv(target?: NodeJS.ProcessEnv): string[];
+/** The one code this module raises. */
+export declare const AGENT_HOME_MISMATCH_CODE = "agent_home_mismatch";
+/**
+ * Raised when the home this process is about to use is not the home its
+ * environment asked for.
+ *
+ * A daemon that silently runs somewhere other than where it was told is the
+ * whole of a different `sw-agent.config.json`, a different
+ * `default_permission`, a different `allowed_databases`, a different audit
+ * directory and therefore a DIFFERENT AUDIT KEY, while the operator's
+ * `sw-agent audit verify` reviews the chain the daemon is not writing.
+ */
+export declare class AgentHomeMismatchError extends Error {
+    readonly code = "agent_home_mismatch";
+    constructor(message: string);
+}
+export interface ResolvedAgentHomeReport {
+    /** `SW_AGENT_HOME` exactly as supplied, or null when it was not set. */
+    requested: string | null;
+    /** The absolute directory the daemon will actually use. */
+    resolved: string;
+    /** True when `resolved` is the absolute form of `requested`. */
+    matches: boolean;
+    /** True when neither home variable was supplied. */
+    defaulted: boolean;
+    /**
+     * True when `PG_CONNECTOR_HOME` is still set. It must never be: it is in
+     * {@link UNRECOGNISED_SECURITY_ENV} and is deleted at startup, so any path
+     * resolved from it before that point silently changes home underneath the
+     * process. Seeing it here means the strip did not run before the paths were
+     * resolved.
+     */
+    stale_home_var_present: boolean;
+    /** Derived paths, so the journal line names what the home actually controls. */
+    config: string;
+    audit_dir: string;
+    credential_key: string;
+    pid_file: string;
+    status_file: string;
+    errors_log: string;
+}
+/**
+ * Resolves the agent home and everything derived from it, without throwing.
+ *
+ * `getAgentHome()` has a side effect — it creates the directory and repairs its
+ * mode — so it is called through the same accessor the rest of the daemon uses.
+ * A failure there (a read-only filesystem under `ProtectSystem=strict`, a
+ * permission problem) is reported as `null` rather than thrown, because the
+ * startup log must not be the thing that kills a daemon that is about to fail
+ * closed on its own.
+ */
+export declare function resolveAgentHomeReport(env?: NodeJS.ProcessEnv): ResolvedAgentHomeReport | null;
+/**
+ * The startup lines. Printed on EVERY daemon start, not only when
+ * `SW_AGENT_HOME` is set, because the failure this defends against is invisible
+ * from the journal: a daemon writing a fresh, empty audit chain in
+ * `~/.sw-agent` looks exactly like a healthy one.
+ *
+ * The absolute resolved path is the whole point. `journalctl -u schemaweaver`
+ * is where an operator checks that the 24/7 service is running against the home
+ * they configured, and before this existed the only evidence available was a
+ * unit file asserting a pin the daemon then ignored.
+ */
+export declare function formatAgentHomeReport(report: ResolvedAgentHomeReport): string[];
+/**
+ * Asserts the resolved agent home matches what the environment asked for, logs
+ * it, and returns the report.
+ *
+ * Called once per daemon start, after
+ * {@link stripUnrecognisedSecurityEnv}. Throws
+ * {@link AgentHomeMismatchError} rather than warning: a daemon running against a
+ * home nobody configured would apply a different `default_permission`, a
+ * different `allowed_databases` and a different audit key, which is worse than
+ * not running.
+ *
+ * A `SW_AGENT_HOME` that is not absolute is refused too. A relative value
+ * resolves against whatever working directory the supervisor happened to use,
+ * which is exactly how a systemd unit ends up pointing somewhere nobody chose.
+ */
+export declare function assertAndLogResolvedAgentHome(env?: NodeJS.ProcessEnv, log?: (line: string) => void): ResolvedAgentHomeReport;
+export type AgentRuntimeKind = 'stopped' | 'starting' | 'running' | 'unresponsive';
+export interface AgentRuntimeState {
+    kind: AgentRuntimeKind;
+    running: boolean;
+    healthy: boolean;
+    pid: number | null;
+    version: string | null;
+    started_at: string | null;
+    uptime_sec: number | null;
+    last_heartbeat: string | null;
+    status: DaemonStatus | null;
+    pidFile: PidFile | null;
+    status_mismatch: boolean;
+    /** Where local error telemetry is written, whether or not the daemon runs. */
+    errors_log: DaemonStatus['errors_log'];
+}
+export declare function resolveAgentRuntimeState(now?: Date): AgentRuntimeState;
+export declare function formatDuration(sec: number): string;
+export declare function formatTimestamp(ts: string): string;
+//# sourceMappingURL=state.d.ts.map

package/dist/types/cli/daemon/state.d.ts.map

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

package/dist/types/cli/daemon/status-file.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Health of the audit writer, mirrored from `AuditSinkHealth` so `sw-agent
+ * status` can show whether the trail is actually being written instead of only
+ * how many events were counted.
+ *
+ * The required fields are exactly the ones an operator needs to tell a healthy
+ * writer from a silently failing one. Everything else the sink exposes is
+ * carried as optional, so an `AuditSinkHealth` can be assigned here directly and
+ * a producer that reports only the essentials still type-checks.
+ */
+export interface AuditStatusHealth {
+    /** False if the last append failed. Audit loss must never be silent. */
+    writable: boolean;
+    /** The audit directory the writer is using. */
+    dir: string;
+    dir_mode: number | null;
+    file_mode: number | null;
+    events_written: number;
+    events_failed: number;
+    /** Records actually lost. Any non-zero value is silent history loss. */
+    dropped: number;
+    last_write_at: string | null;
+    last_error: string | null;
+    chain_id: string | null;
+    /** Sequence number of the newest record this process wrote. */
+    seq: number;
+    chain_error: string | null;
+    /** Oldest sequence number still on disk, or null when nothing is retained. */
+    retained_from_seq: number | null;
+    ready?: boolean;
+    active_path?: string;
+    last_error_at?: string | null;
+    error_count?: number;
+    bytes_written?: number;
+    rotations?: number;
+    queue_depth?: number;
+    overflow_admitted?: number;
+}
+/**
+ * Effective security posture, as the daemon resolved it.
+ *
+ *  and  are both invisible by default: an agent with no database
+ * allow-list used to serve every configured database silently, and the local role
+ * ceiling had no reader at all. Both facts are printed to the console of a
+ * detached daemon that most operators never read, so the daemon also writes them
+ * here — this is the block `sw-agent status` renders.
+ *
+ * Optional because a status file written by an older daemon predates it, and
+ * because a reader that does not understand it must degrade rather than fail.
+ */
+export interface SecurityStatus {
+    /** One line stating the effective database scope in words. */
+    database_scope: string;
+    /** Whether any allow-list (`allowed_databases` / `SW_AGENT_ALLOWED_DATABASES`) is in force. */
+    allowlist_configured: boolean;
+    /**
+     * Whether the pre-remediation permissive default was deliberately restored with
+     * `security.allow_unscoped_databases: true`. When true, one token reaches every
+     * configured database.
+     */
+    allow_unscoped_databases: boolean;
+    /** True when the agent serves `ping` only because nothing is declared. */
+    fail_closed: boolean;
+    /** True when the environment channel narrowed the configured allow-list. */
+    env_narrowed_scope: boolean;
+    /**
+     * Effective local role ceiling. `'admin'` means a compromised relay has the
+     * full capability set on every database the agent can reach.
+     */
+    max_negotiable_role: string;
+}
+export interface DaemonStatus {
+    pid: number;
+    started_at: string;
+    last_heartbeat: string;
+    version: string;
+    channels: {
+        sse: 'connecting' | 'connected' | 'disconnected' | 'error';
+        wss: 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
+        last_sse_reconnect?: string;
+        last_wss_session?: string;
+    };
+    stats: {
+        queries_served: number;
+        streams_served: number;
+        migrations_run: number;
+        cancellations: number;
+        permission_denies: number;
+        audit_events_written: number;
+        /**
+         * Records the sink could not persist. Optional because a status file written
+         * by a daemon without it predates the counter; readers treat an absent value
+         * as 0 rather than as "no failures".
+         */
+        audit_events_failed?: number;
+        audit_buffer_overflows: number;
+        /**
+         * Records the bounded audit queue discarded outright under pressure. Optional
+         * for the same reason as `audit_events_failed`: a status file written by a
+         * daemon without the counter predates it, and an absent value means "no drops
+         * reported", not "the trail is complete". Also available as `audit.dropped`.
+         */
+        audit_dropped?: number;
+    };
+    /**
+     * Audit writer health. Optional because a status file written by a build
+     * without it predates this field: readers must degrade to the counters rather
+     * than fail.
+     */
+    audit?: AuditStatusHealth;
+    config?: {
+        databases: number;
+        projects: number;
+        revision: number;
+    };
+    /** Location and size of the local, rotated error log. Surfaced by `sw-agent status`. */
+    errors_log?: {
+        path: string;
+        size_bytes: number;
+    };
+    /**
+     * Effective security posture (database scope, role ceiling). Optional so a
+     * status file written by a build without it still reads; `sw-agent status`
+     * degrades to the counters rather than failing.
+     */
+    security?: SecurityStatus;
+    last_error?: {
+        ts: string;
+        code: string;
+        message: string;
+    };
+}
+export interface StatusFileOptions {
+    path: string;
+}
+export declare function writeStatusFile(opts: StatusFileOptions, status: DaemonStatus): Promise<void>;
+export declare function readStatusFile(opts: StatusFileOptions): Promise<DaemonStatus | null>;
+export declare function isStatusStale(status: DaemonStatus, now?: Date): boolean;
+//# sourceMappingURL=status-file.d.ts.map

package/dist/types/cli/daemon/status-file.d.ts.map

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

package/dist/types/cli/doctor/checks.d.ts

@@ -0,0 +1,133 @@
+import { MachineConfig } from '../../config/machine-config';
+import { DatabasesConfig } from '../../config/db-config';
+export interface DoctorCheck {
+    name: string;
+    status: 'pass' | 'fail' | 'warn';
+    detail?: string;
+}
+export interface DoctorContext {
+    swAgentDir: string;
+    machineConfig: MachineConfig | null;
+    databasesConfig: DatabasesConfig | null;
+    nodeVersion: string;
+    platform: string;
+}
+export declare function checkSwAgentDirExists(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkMachineConfigValid(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkTokenFormat(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDatabasesConfigValid(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDatabasesReachable(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Files whose contents are credential material and which must therefore be
+ * readable only by their owner.
+ */
+export declare const SECURE_CONFIG_FILES: readonly ["sw-agent.config.json", "databases.config.json"];
+/** Mode every config file must have: read/write for the owner, nothing else. */
+export declare const SECURE_CONFIG_MODE = 384;
+export interface ConfigFileMode {
+    name: string;
+    path: string;
+    mode: number | null;
+    /** True when the path exists but is not a regular file (symlink, socket, …). */
+    irregular: boolean;
+    exists: boolean;
+}
+/**
+ * Resolve the real config file paths and read their modes. Does not follow
+ * symlinks for the permission read: a symlinked config is reported as
+ * irregular rather than silently checking whatever it points at.
+ */
+export declare function inspectConfigFileModes(swAgentDir: string): ConfigFileMode[];
+export declare function formatMode(mode: number): string;
+/**
+ * Check that the config files are owner-only (0o600).
+ *
+ * `databases.config.json` holds encrypted database passwords and
+ * `sw-agent.config.json` holds the agent token that authenticates this agent to
+ * the cloud. A group- or world-readable copy of either is a credential
+ * disclosure to every other local user, so a 0o644 config FAILS here rather
+ * than producing a warning. Missing files are reported as a warning: their
+ * absence is covered by the config-validity checks.
+ */
+export declare function checkConfigFilePermissions(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkAuditDirWritable(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Verifies the existing audit log against its anchor. A log that does not
+ * verify is reported as a failure, not a warning: an operator running `doctor`
+ * is exactly the person who needs to be told.
+ *
+ * This is the one caller that reuses {@link verifyAuditDirCached}: an operator
+ * running `doctor` repeatedly in the same shell re-verifies an unchanged log
+ * over and over, and the archives are the bulk of it. A reused file is only
+ * skipped when it is byte-identical to what was verified (dev/inode/size/mtime
+ * *and* ctime, at nanosecond precision), when the entry was verified from the
+ * chain state the walk is resuming into, when it was verified with the same
+ * signing key, and — for the end of the log — when the tail record on disk is
+ * still the record that was verified. The anchors are re-read from disk on
+ * every call. The result always says how much it did *not* read, so a pass
+ * backed by the cache can never look like a full re-read.
+ */
+export declare function checkAuditChain(ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * Repairs an audit directory that exists with a mode that cannot be traversed.
+ * `mkdir({ recursive: true })` is a no-op on an existing directory, so without
+ * this the wrong mode is permanent and the audit log silently records nothing.
+ */
+export declare function ensureAuditDirForDoctor(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkDiskSpace(_ctx: DoctorContext): Promise<DoctorCheck>;
+/**
+ * One `rolX = false` expectation, parsed out of
+ * {@link RECOMMENDED_PG_ROLE}.required_attributes.
+ *
+ * The role policy is the single source of truth: the SQL and the expectations
+ * are both derived from it, so a new required attribute is enforced the moment
+ * it is documented rather than needing a second edit here.
+ */
+export interface PgRoleAttributeRule {
+    attribute: string;
+    expect: boolean;
+}
+/**
+ * What the connected login role actually holds, as read from the server. Every
+ * probe is nullable: an unanswered probe must never read as "acceptable".
+ */
+export interface PgRoleFacts {
+    alias: string;
+    role: string;
+    /** `pg_roles` attribute name -> value, or null when the probe did not answer. */
+    attributes: Record<string, boolean | null>;
+    can_create_temp: boolean | null;
+    can_create_in_public: boolean | null;
+    /** Predefined roles the login role holds, directly or by inheritance. */
+    forbidden_memberships: string[];
+    default_transaction_read_only: string | null;
+}
+/**
+ * Every way the connected role departs from {@link RECOMMENDED_PG_ROLE}, as
+ * human-readable findings. An empty array means the role is acceptable.
+ *
+ * Pure and fail-closed: an unanswered probe is itself a finding, because a probe
+ * that did not answer has not established anything.
+ */
+export declare function pgRoleFindings(facts: PgRoleFacts): string[];
+/** The label the role check reports under. */
+export declare const PG_ROLE_CHECK_NAME: string;
+/**
+ * Verifies the connected PostgreSQL login role against
+ * {@link RECOMMENDED_PG_ROLE} (C-02).
+ *
+ * `read_only` constrains what the connector is willing to run; it cannot
+ * constrain what the login role is allowed to do. A `rolsuper` or
+ * `pg_read_server_files` role defeats every control above it, so the role is
+ * the only boundary an operator cannot route around from the wire.
+ *
+ * A violation is a failure, not a warning: the operator running `doctor` is
+ * exactly the person who needs to be told. A database that cannot be reached
+ * cannot clear the role, so it is reported as a warning naming what was not
+ * checked — never as a pass.
+ */
+export declare function checkPgRoleLeastPrivilege(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkNodeVersion(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function checkPidFile(ctx: DoctorContext): Promise<DoctorCheck>;
+export declare function runAllChecks(ctx: DoctorContext): Promise<DoctorCheck[]>;
+//# sourceMappingURL=checks.d.ts.map

package/dist/types/cli/doctor/checks.d.ts.map

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

package/dist/types/cli/doctor/fixes.d.ts

@@ -0,0 +1,9 @@
+import { DoctorContext } from './checks';
+export interface FixResult {
+    name: string;
+    applied: boolean;
+    detail: string;
+}
+/** Run all self-repair fixes in a safe order. */
+export declare function runAllFixes(ctx: DoctorContext): Promise<FixResult[]>;
+//# sourceMappingURL=fixes.d.ts.map

package/dist/types/cli/doctor/fixes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixes.d.ts","sourceRoot":"","sources":["../../../../src/cli/doctor/fixes.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAA0D,MAAM,UAAU,CAAC;AAEjG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAyJD,iDAAiD;AACjD,wBAAsB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAO1E"}

package/dist/types/cli/doctor/index.d.ts

@@ -0,0 +1,7 @@
+export { checkSwAgentDirExists, checkMachineConfigValid, checkTokenFormat, checkDatabasesConfigValid, checkConfigFilePermissions, inspectConfigFileModes, checkDatabasesReachable, checkAuditDirWritable, checkAuditChain, ensureAuditDirForDoctor, checkPgRoleLeastPrivilege, checkDiskSpace, checkNodeVersion, checkPidFile, runAllChecks, } from './checks';
+export type { DoctorCheck, DoctorContext, ConfigFileMode } from './checks';
+export { SECURE_CONFIG_FILES, SECURE_CONFIG_MODE } from './checks';
+export { PG_ROLE_CHECK_NAME } from './checks';
+export type { FixResult } from './fixes';
+export { runAllFixes } from './fixes';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cli/doctor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/doctor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AA4NA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C1D"}

package/dist/types/cli/interactive.d.ts

@@ -0,0 +1,8 @@
+export declare const PALETTE_ITEMS: {
+    command: string;
+    desc: string;
+    category: "Agent" | "Databases" | "Projects" | "Setup" | "Ops";
+}[];
+export declare function dispatchCommand(input: string): Promise<'continue' | 'exit'>;
+export declare function startInteractive(): Promise<number>;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/types/cli/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../../src/cli/interactive.ts"],"names":[],"mappings":"AAwOA,eAAO,MAAM,aAAa;;;;GAIvB,CAAC;AA+DJ,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,CA4DjF;AAwYD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAGxD"}

package/dist/types/cli/logs/format.d.ts

@@ -0,0 +1,13 @@
+import { AuditEvent } from '../../audit/types';
+export declare function relativeTime(iso: string): string;
+export declare const DECISION_COLOR: Record<string, (s: string) => string>;
+export declare const OUTCOME_COLOR: Record<string, (s: string) => string>;
+export declare function renderLogTable(events: AuditEvent[], maxWidth?: number): string;
+export declare function formatEventRow(event: AuditEvent): string;
+export declare function formatTableHeader(): string;
+export declare function formatEventJson(event: AuditEvent): string;
+/**
+ * Formats a detailed modal card for inspecting a single audit event without truncating SQL.
+ */
+export declare function renderEventDetailLines(event: AuditEvent, width: number): string[];
+//# sourceMappingURL=format.d.ts.map

package/dist/types/cli/logs/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/cli/logs/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAO/C,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAOhE,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAK/D,CAAC;AAEF,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,QAAQ,SAAsB,GAAG,MAAM,CAyC3F;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAaxD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA2EjF"}

package/dist/types/cli/logs/index.d.ts

@@ -0,0 +1,3 @@
+export { formatEventRow, formatEventJson, formatTableHeader, renderLogTable, renderEventDetailLines } from './format';
+export { InteractiveLogViewer, startLogViewer } from './viewer';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cli/logs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACtH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/cli/logs/viewer.d.ts

@@ -0,0 +1,41 @@
+import { AuditLogFilter } from '../../audit/files';
+interface ViewerOptions {
+    auditDir: string;
+    initialFilter?: AuditLogFilter;
+}
+export declare class InteractiveLogViewer {
+    private auditDir;
+    private filter;
+    private events;
+    private selectedIndex;
+    private scrollOffset;
+    private isRunning;
+    private isSearching;
+    private searchBuffer;
+    private modalEvent;
+    private modalScroll;
+    private renderedLines;
+    private resizeTimer;
+    private resolve;
+    private readonly onDataBound;
+    private readonly onResizeBound;
+    constructor(opts: ViewerOptions);
+    run(): Promise<void>;
+    private reloadEvents;
+    private onResize;
+    private onKey;
+    private handleToken;
+    private moveSelection;
+    private adjustScroll;
+    private visibleRowCount;
+    private render;
+    private renderHeader;
+    private renderTableHeader;
+    private renderTableRows;
+    private renderFooter;
+    private clearRenderedBlock;
+    private shutdown;
+}
+export declare function startLogViewer(opts: ViewerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=viewer.d.ts.map

package/dist/types/cli/logs/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../../../../src/cli/logs/viewer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AAiBpE,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,WAAW,CAAK;IAExB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,OAAO,CAAc;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;gBAE9C,IAAI,EAAE,aAAa;IAYzB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAyBZ,YAAY;IAS1B,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,WAAW;IAwJnB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,MAAM;IA4Bd,OAAO,CAAC,YAAY;IA2BpB,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,eAAe;IAmDvB,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,QAAQ;CAejB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE"}

package/dist/types/cli/ops/operation-logger.d.ts

@@ -0,0 +1,63 @@
+export type OpStatus = 'started' | 'ok' | 'error';
+export interface OperationEvent {
+    ts: string;
+    op: string;
+    status: OpStatus;
+    target?: string;
+    duration_ms?: number;
+    error?: string;
+    agent_id?: string;
+}
+/**
+ * Operation logger — a local + cloud record of CLI/lifecycle operations, with
+ * two sinks available to any caller:
+ *
+ *   1. Local: `~/.sw-agent/operations.jsonl` (synchronous append, 0o600).
+ *   2. Cloud: POST /api/agent/operations/ingest (best-effort, batched, only
+ *      once {@link initOperationLogger} has attached a client).
+ *
+ * **Nothing in this repository emits an operation yet.** `logOperation()` and
+ * `withOperation()` have no callers outside this module, so `operations.jsonl` is
+ * not written and no ingest request is ever made — only the daemon calls
+ * {@link initOperationLogger}, which attaches the client and sets `agentId`.
+ *
+ * That is stated here rather than implied by a comment claiming that init, db
+ * add/remove, agent start/stop and config changes are recorded, because the old
+ * header asserted behaviour the code did not have (audit finding M-23). Wiring it
+ * up is a deliberate step at real lifecycle points in `src/cli/commands/*` and
+ * `src/cli/daemon/runtime.ts`; do not infer from this file that those points
+ * exist. Until then, treat this as an available mechanism, not an active record.
+ */
+export declare function initOperationLogger(opts: {
+    enabled: boolean;
+    cloudUrl?: string;
+    token?: string;
+    agentId?: string;
+}): void;
+/** Path to the local operations log. */
+export declare function getOperationsPath(): string;
+/**
+ * Record an operation event to local + cloud. Never throws.
+ *
+ * No caller reaches this today (see the module header); it is the entry point a
+ * lifecycle call site would use.
+ */
+export declare function logOperation(event: OperationEvent): void;
+/** Flush + close the cloud client. Call on daemon/REPL shutdown. */
+export declare function shutdownOperationLogger(): Promise<void>;
+/**
+ * Wrap an async operation so it emits `started` and `ok`/`error` events
+ * automatically. Returns whatever the wrapped function returns (or rethrows
+ * after logging the error).
+ *
+ * No caller reaches this today (see the module header).
+ */
+export declare function withOperation<T>(op: string, target: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * Read recent operation events from the local log, newest last.
+ *
+ * Returns an empty list while nothing emits operations: the file does not exist
+ * until `logOperation()` runs at least once.
+ */
+export declare function readRecentOperations(limit: number): Promise<OperationEvent[]>;
+//# sourceMappingURL=operation-logger.d.ts.map

package/dist/types/cli/ops/operation-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-logger.d.ts","sourceRoot":"","sources":["../../../../src/cli/ops/operation-logger.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAiBP;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAgBxD;AAED,oEAAoE;AACpE,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK7D;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA0BZ;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAgBnF"}