@hasna/loops 0.4.12 → 0.4.14

package/dist/generated/storage-kit/health.d.ts

@@ -0,0 +1,19 @@
+import type { TypedQueryClient } from "./query.js";
+import { type Migration, type MigrationRunnerOptions } from "./migrations.js";
+export interface HealthResult {
+    ok: boolean;
+    /** Round-trip latency of the probe query, in milliseconds. */
+    latencyMs: number;
+    error?: string;
+}
+/** Cheap reachability probe: `SELECT 1`. Never throws — reports `ok: false`. */
+export declare function checkHealth(client: TypedQueryClient): Promise<HealthResult>;
+export interface ReadyResult extends HealthResult {
+    /** Migration ids that are defined but not yet applied. */
+    pendingMigrations: string[];
+}
+/**
+ * Readiness probe: reachable AND fully migrated. Reports `ok: false` with the
+ * list of pending migration ids when the schema is behind.
+ */
+export declare function checkReady(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): Promise<ReadyResult>;

package/dist/generated/storage-kit/index.d.ts

@@ -0,0 +1,7 @@
+export declare const KIT_VERSION = "0.4.0";
+export * from "./mode.js";
+export * from "./tls.js";
+export * from "./query.js";
+export * from "./pool.js";
+export * from "./migrations.js";
+export * from "./health.js";

package/dist/generated/storage-kit/migrations.d.ts

@@ -0,0 +1,47 @@
+import type { TypedQueryClient } from "./query.js";
+/** Default ledger table name. Override per app if a legacy name exists. */
+export declare const DEFAULT_MIGRATION_LEDGER_TABLE = "schema_migrations";
+export interface Migration {
+    readonly id: string;
+    readonly sql: string;
+    readonly checksum: string;
+}
+export type MigrationState = "already_applied" | "pending";
+export interface MigrationPlanItem {
+    readonly migration: Migration;
+    readonly state: MigrationState;
+}
+export interface AppliedMigration {
+    readonly id: string;
+    readonly checksum: string;
+    readonly appliedAt: string;
+}
+export interface MigrationResult {
+    readonly dryRun: boolean;
+    readonly applied: AppliedMigration[];
+    readonly plan: MigrationPlanItem[];
+}
+/** Stable sha256 checksum for a migration's SQL text. */
+export declare function checksumSql(sql: string): string;
+/** Freeze a migration definition, computing its checksum from the SQL. */
+export declare function defineMigration(id: string, sql: string): Migration;
+export interface MigrationRunnerOptions {
+    ledgerTable?: string;
+}
+export declare class MigrationLedger {
+    private readonly client;
+    private readonly migrations;
+    private readonly ledgerTable;
+    constructor(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions);
+    ensureLedger(): Promise<void>;
+    listApplied(): Promise<AppliedMigration[]>;
+    private readApplied;
+    /** Compute the migration plan and guard against drift/downgrade. */
+    private buildPlan;
+    /** Apply all pending migrations. With `dryRun`, report the plan only. */
+    migrate(opts?: {
+        dryRun?: boolean;
+    }): Promise<MigrationResult>;
+}
+/** Convenience: build a ledger and run all pending migrations. */
+export declare function createMigrationLedger(client: TypedQueryClient, migrations: readonly Migration[], options?: MigrationRunnerOptions): MigrationLedger;

package/dist/generated/storage-kit/mode.d.ts

@@ -0,0 +1,47 @@
+export declare const STORAGE_MODES: readonly ["local", "cloud"];
+export type StorageMode = (typeof STORAGE_MODES)[number];
+export declare const DEPRECATED_STORAGE_MODE_ALIASES: readonly ["remote", "hybrid", "self_hosted"];
+export type Env = Record<string, string | undefined>;
+export interface StorageModeNormalization {
+    mode: StorageMode;
+    /** The deprecated alias that was normalized to `cloud`, if any. */
+    deprecatedAlias: string | null;
+}
+/**
+ * Normalize a raw storage-mode string to the `local | cloud` runtime enum.
+ * Accepts deprecated aliases (`remote`, `hybrid`, `self_hosted`) and maps them
+ * to `cloud`. Throws on any other value.
+ */
+export declare function normalizeStorageMode(value: string): StorageModeNormalization;
+/** Upper-snake env token for an app name, e.g. `todos` -> `TODOS`. */
+export declare function envToken(name: string): string;
+export interface StorageEnvKeys {
+    /** `HASNA_<NAME>_STORAGE_MODE` then the optional `<NAME>_STORAGE_MODE` alias. */
+    modeKeys: string[];
+    /** `HASNA_<NAME>_DATABASE_URL` then the optional `<NAME>_DATABASE_URL` alias. */
+    databaseUrlKeys: string[];
+}
+/** Resolve the canonical env-key spec for an app's storage config. */
+export declare function storageEnvKeys(name: string): StorageEnvKeys;
+export interface StorageModeResolution {
+    mode: StorageMode;
+    /** Env key the mode came from, or `"default"`. */
+    source: string;
+    deprecatedAlias: string | null;
+    databaseUrlPresent: boolean;
+    /** Env key the database URL came from, or `null`. */
+    databaseUrlSource: string | null;
+    warning: string | null;
+}
+/**
+ * Resolve an app's storage mode from the environment per the contract env spec.
+ * Precedence: `HASNA_<NAME>_STORAGE_MODE`, then `<NAME>_STORAGE_MODE`, else
+ * `local`. Never reads secret values — only detects DATABASE_URL presence.
+ */
+export declare function resolveStorageMode(name: string, env?: Env): StorageModeResolution;
+/**
+ * Resolve the database URL value for an app, honoring the canonical then alias
+ * env keys. Returns `null` when unset. The caller is responsible for never
+ * logging the returned value.
+ */
+export declare function resolveDatabaseUrl(name: string, env?: Env): string | null;

package/dist/generated/storage-kit/pool.d.ts

@@ -0,0 +1,33 @@
+import type { Pool } from "pg";
+import { type TlsResolveOptions } from "./tls.js";
+import { type PoolQueryClient } from "./query.js";
+export interface CreatePgPoolOptions extends TlsResolveOptions {
+    connectionString: string;
+    /** Max clients in the pool. Defaults to pg's default (10). */
+    max?: number;
+    /** Idle client timeout (ms). */
+    idleTimeoutMillis?: number;
+    /** Connection acquisition timeout (ms). */
+    connectionTimeoutMillis?: number;
+    /** Application name reported to Postgres (shows in pg_stat_activity). */
+    applicationName?: string;
+}
+/** Build a `pg.Pool` with fleet-standard TLS handling. */
+export declare function createPgPool(options: CreatePgPoolOptions): Pool;
+export interface CreateCloudPoolFromEnvOptions extends TlsResolveOptions {
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+    applicationName?: string;
+}
+export interface CloudPoolFromEnv {
+    client: PoolQueryClient;
+    connectionSource: string;
+}
+/**
+ * Resolve mode + database URL from the environment and build a cloud pool.
+ *
+ * Throws when the resolved mode is not `cloud` (PURE REMOTE has no Postgres in
+ * `local` mode) or when the database URL is missing. Never logs the URL.
+ */
+export declare function createCloudPoolFromEnv(appName: string, options?: CreateCloudPoolFromEnvOptions): CloudPoolFromEnv;

package/dist/generated/storage-kit/query.d.ts

@@ -0,0 +1,35 @@
+import type { Pool, QueryResultRow } from "pg";
+export interface QueryResult<T extends QueryResultRow> {
+    rows: T[];
+    rowCount: number;
+}
+/**
+ * Minimal executor contract. `pg.Pool` and `pg.PoolClient` both satisfy the
+ * `query` method; the wrapper builds the rest on top so tests can substitute a
+ * lightweight shim without pulling in a live Postgres.
+ */
+export interface PgExecutor {
+    query<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<{
+        rows: T[];
+        rowCount: number | null;
+    }>;
+}
+export interface TypedQueryClient {
+    query<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<QueryResult<T>>;
+    many<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /** First row or `null`. Restored here after open-knowledge dropped it. */
+    get<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T | null>;
+    /** Exactly one row; throws if zero or more than one row is returned. */
+    one<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T>;
+    execute(sql: string, params?: readonly unknown[]): Promise<void>;
+}
+/** Wrap any `PgExecutor` (a Pool, a PoolClient, or a test shim) with the typed vocabulary. */
+export declare function wrapExecutor(executor: PgExecutor): TypedQueryClient;
+export interface PoolQueryClient extends TypedQueryClient {
+    readonly pool: Pool;
+    /** Run a callback inside a `BEGIN`/`COMMIT` transaction on a dedicated client. */
+    transaction<T>(fn: (client: TypedQueryClient) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Build a `PoolQueryClient` around a live `pg.Pool`. */
+export declare function createQueryClient(pool: Pool): PoolQueryClient;

package/dist/generated/storage-kit/tls.d.ts

@@ -0,0 +1,25 @@
+/** The `ssl` field shape accepted by `pg.Pool` / `pg.Client`. */
+export type PgSslConfig = boolean | {
+    rejectUnauthorized: boolean;
+    ca?: string;
+};
+export interface TlsResolveOptions {
+    /** Inline CA bundle (PEM). Wins over every other CA source. */
+    ca?: string;
+    /** Path to a CA bundle PEM file, e.g. the Amazon RDS global bundle. */
+    caCertPath?: string;
+    /** Environment used to discover PGSSLROOTCERT / NODE_EXTRA_CA_CERTS. */
+    env?: Record<string, string | undefined>;
+}
+export type SslMode = "disable" | "prefer" | "require" | "verify-ca" | "verify-full";
+/**
+ * Extract the effective `sslmode` from a Postgres connection string. Honors the
+ * `sslmode` query param and the legacy `ssl=true` boolean. Returns `disable`
+ * when TLS is not requested.
+ */
+export declare function sslModeFromConnectionString(connectionString: string): SslMode;
+/**
+ * Resolve the `pg` ssl config for a connection string. See the module header
+ * for the full mode table. Returns `undefined` when TLS should be off.
+ */
+export declare function resolveTlsConfig(connectionString: string, options?: TlsResolveOptions): PgSslConfig | undefined;

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { AmbiguousNameError, CodedError, LoopArchivedError, LoopNotFoundError, V
 export type { CatchUpPolicy, CreateLoopInput, ExecutorResult, IntervalAnchor, Loop, LoopRun, LoopStatus, OverlapPolicy, RunStatus, TimeoutMs, CronSchedule, DynamicSchedule, IntervalSchedule, OnceSchedule, ScheduleSpec, AccountRef, AgentAllowlistSpec, AgentConfigIsolation, AgentPermissionMode, AgentPromptSource, AgentProvider, AgentRoutingSpec, AgentSandbox, AgentTarget, AgentTargetBase, AgentWorktreeMode, AgentWorktreeSpec, CommandTarget, ExecutableTarget, ExecutableTargetInput, LoopTarget, LoopTargetInput, PromptFileAgentTarget, RuntimePreflightPolicy, WorkflowTarget, CreateWorkflowInput, WorkflowEvent, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStatus, WorkflowStep, WorkflowStepInput, WorkflowStepRun, WorkflowStepRunStatus, } from "./types.js";
 export { runDoctor } from "./lib/doctor.js";
 export type { DoctorCheck, DoctorReport, DoctorSeverity } from "./lib/doctor.js";
-export { buildHealthReport, classifyRunFailure, expectationForLoop } from "./lib/health.js";
-export type { LoopExpectationResult, LoopsHealthReport, RunFailureClassification, RunFailureSignal, } from "./lib/health.js";
+export { buildHealthReport, buildHealthScan, classifyRunFailure, expectationForLoop, writeHealthScanReports } from "./lib/health.js";
+export type { BuildHealthScanOptions, HealthScanFinding, HealthScanFindingKind, HealthScanFindingSeverity, HealthScanSelfHealAction, HealthScanStatus, LoopExpectationResult, LoopsHealthReport, LoopsHealthScan, RunFailureClassification, RunFailureSignal, WriteHealthScanReportsOptions, } from "./lib/health.js";
 export { computeNextAfter, initialNextRun, nextCronRun, parseCron, parseDuration } from "./lib/recurrence.js";
 export { runLoopNow, tick } from "./lib/scheduler.js";
 export type { ManualRunSource, RunLoopNowDeps, RunLoopNowExecuted, RunLoopNowMode, RunLoopNowResult, RunLoopNowScheduled, } from "./lib/scheduler.js";
@@ -23,7 +23,7 @@ export { Store } from "./lib/store.js";
 export { POSTGRES_MIGRATION_LEDGER_TABLE, POSTGRES_STORAGE_MIGRATIONS, PostgresStorage, SqliteLoopStorage, checksumStorageSql, createPostgresStorage, createSqliteLoopStorage, } from "./lib/storage/index.js";
 export type { AppliedStorageMigration, AuditEventRecord, LoopStorageBackend, LoopStorageContract, LoopStorageMethodName, PostgresQueryExecutor, RunnerLeaseRecord, RunnerLeaseStatus, RunnerMachineRecord, RunnerMachineStatus, SchemaMigrationStorage, StorageMigration, StorageMigrationPlanItem, StorageMigrationResult, } from "./lib/storage/index.js";
 export { LOOP_DEPLOYMENT_MODES, buildDeploymentStatus, deploymentStatusLine, loopControlPlaneConfig, normalizeLoopDeploymentMode, resolveLoopDeploymentMode, } from "./lib/mode.js";
-export type { LoopControlPlaneConfig, LoopDeploymentMode, LoopDeploymentStatus, LoopModeResolution, LoopSourceOfTruth } from "./lib/mode.js";
+export type { LoopControlPlaneConfig, LoopDeploymentMode, LoopDeploymentStatus, LoopModeResolution, LoopRemoteArtifactStore, LoopRemoteSchedulerBackend, LoopRouteAdmissionGate, LoopRouteAdmissionStateStore, LoopSchedulerStateStatus, LoopSourceOfTruth, } from "./lib/mode.js";
 export { executeLoop, executeTarget, preflightTarget } from "./lib/executor.js";
 export { executeLoopTarget, executeWorkflow, preflightWorkflow } from "./lib/workflow-runner.js";
 export { workflowBodyFromJson, workflowExecutionOrder } from "./lib/workflow-spec.js";