@nightowlsdev/storage-supabase 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,165 @@
+import { AgentVersion, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
+import { Pool } from 'pg';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { PostgresStore, PgVector } from '@mastra/pg';
+
+interface SupabaseStorageOpts {
+    url: string;
+    secretKey: string;
+    /** Direct/Session Postgres URL (port 5432). REQUIRED — pg/Mastra need the non-pooler port. */
+    dbUrl: string;
+    max?: number;
+    /** Postgres SSL. Default for a remote dbUrl is `true` (verify the server cert). Explicit override honored.
+     *  Localhost stays unencrypted (undefined). Pass `{ rejectUnauthorized: false }` only to opt out of verification. */
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+    };
+}
+interface Ctx$1 {
+    pool: Pool;
+    sb: SupabaseClient;
+}
+
+declare function createMastraPgStore(opts: {
+    dbUrl: string;
+    disableInit?: boolean;
+}): PostgresStore;
+/** Mastra PgVector over the `nightowls` schema — backs semantic recall. The pgvector EXTENSION is enabled by
+ *  the packaged 0004 migration; PgVector auto-creates its index table on first recall (spike-verified). */
+declare function createMastraVectorStore(opts: {
+    dbUrl: string;
+}): PgVector;
+
+/** The shape callers pass — `version` is derived, not supplied. */
+type PublishAgentDef = Omit<AgentVersion, "version"> & {
+    tenantId: string;
+    actor?: string;
+    version?: number;
+};
+/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (not in the core interface).
+ *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`. */
+declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<void>;
+/** One row of an agent's version history (for rollback UX). */
+interface AgentVersionInfo {
+    version: number;
+    role: string;
+    modelId: string;
+    status: string;
+    isCurrent: boolean;
+}
+/** List an agent's versions (oldest→newest), flagging the current head. Tenant-scoped. Read-only — use it to
+ *  pick a `toVersion` for `rollbackAgentVersion`. Returns [] for an unknown agent. */
+declare function listAgentVersions(ctx: Ctx$1, tenantId: string, slug: string): Promise<AgentVersionInfo[]>;
+/**
+ * Roll an agent back to a prior version's content (R13). APPEND-ONLY: this republishes the target version's
+ * content as a NEW head (max+1) rather than moving the pointer backward — so history always moves forward (like
+ * `git revert`) and the version counter never collides. Audited as `action='rollback'` with `restoredFrom`.
+ * Throws if `toVersion` doesn't exist for this tenant/slug. NOTIFYs the R12 cache invalidation. Returns the new
+ * version number + the source it was restored from.
+ */
+declare function rollbackAgentVersion(ctx: Ctx$1, args: {
+    tenantId: string;
+    slug: string;
+    toVersion: number;
+    actor?: string;
+}): Promise<{
+    version: number;
+    restoredFrom: number;
+}>;
+
+/** A single Night Owls migration: a stable `version`, a human `name`, and fully-qualified `nightowls.*` SQL.
+ *  Night Owls contributes these to the host's `supabase/migrations/` (via `owl install`/`db eject`);
+ *  the host applies them with its own tooling — Night Owls never runs DDL itself. */
+interface Migration {
+    version: string;
+    name: string;
+    sql: string;
+}
+declare const MIGRATIONS: Migration[];
+
+/**
+ * The Night Owls adapter plugin manifest. `@nightowlsdev/cli` discovers this from the host's installed
+ * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
+ *  - `migrations` → ejected into the host's `supabase/migrations/` at install (the user applies them
+ *                   with their own tooling, e.g. `supabase db push` — Night Owls never runs DDL itself),
+ *  - `env`        → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`     → the `import` + wiring `snippet` inserted at the `// nightowls:storage` marker,
+ *  - `init`       → a print-only hook run after the wiring (it NEVER applies DDL),
+ *  - `commands`   → `owl storage-supabase <cmd>` subcommands (e.g. `info` — pure, no DB/network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "storage-supabase";
+    readonly version: "0.0.0";
+    readonly kind: "storage";
+    readonly pkg: "@nightowlsdev/storage-supabase";
+    readonly description: "Supabase Postgres storage + the nightowls schema (migrations, Realtime, RLS).";
+    readonly migrations: Migration[];
+    readonly env: readonly [{
+        readonly key: "SUPABASE_URL";
+        readonly example: "http://127.0.0.1:54321";
+        readonly comment: "Supabase project URL";
+    }, {
+        readonly key: "SUPABASE_SECRET_KEY";
+        readonly example: "";
+        readonly comment: "service_role/secret — server storage adapter ONLY (never in the browser)";
+    }, {
+        readonly key: "DATABASE_URL";
+        readonly example: "postgresql://postgres:postgres@127.0.0.1:5432/postgres";
+        readonly comment: "Session/Direct port 5432 — NOT 6543 (nightowls migrations + the pg pool)";
+    }, {
+        readonly key: "SUPABASE_ANON_KEY";
+        readonly example: "";
+        readonly comment: "publishable/anon — browser auth + Realtime ONLY";
+    }];
+    readonly config: {
+        readonly import: "import { createSupabaseStorage } from '@nightowlsdev/storage-supabase';";
+        readonly snippet: "storage = createSupabaseStorage({ url: env.SUPABASE_URL, secretKey: env.SUPABASE_SECRET_KEY, dbUrl: env.DATABASE_URL });";
+        readonly marker: "storage";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the nightowls migrations and env this adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface PostgresFloorOpts {
+    /** Stale-lock reclaim window — a held lock older than this is stealable (a crashed holder). Default 180_000. */
+    maxHoldMs?: number;
+    /** Poll interval while queued for the floor. Default 250. */
+    pollMs?: number;
+}
+/** A cross-instance {@link ContainerFloor} backed by Postgres (E3). Mutual exclusion is guaranteed by the
+ *  `floor_lock` primary key; FIFO order by `floor_waiter.enqueued_at` (millisecond-truncated so the JS-Date
+ *  precision a node-pg param carries matches the stored value, with `run_id` breaking ms ties → a total order);
+ *  waiter liveness by a `last_seen` HEARTBEAT touched on every poll (so a legitimately deep waiter — which can
+ *  wait many×maxHold behind others — is never mistaken for a crashed orphan, while a dead waiter still clears
+ *  within seconds). Wire it for serverless:
+ *  `new SwarmEngine({ …, floor: createPostgresFloor(storage.ctx.pool) })`. */
+declare function createPostgresFloor(pool: Pool, opts?: PostgresFloorOpts): ContainerFloor;
+
+/** The Supabase StorageAdapter plus a typed internal handle (`ctx`) so management helpers
+ *  like `publishAgentVersion` can reuse the same pg pool without any `as any` coupling. */
+interface SupabaseStorage extends StorageAdapter {
+    /** Internal pg pool + supabase-js client. Pass to `publishAgentVersion(storage.ctx, def)`. */
+    readonly ctx: Ctx$1;
+    close(): Promise<void>;
+}
+declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
+
+export { type AgentVersionInfo, type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import { AgentVersion, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
+import { Pool } from 'pg';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { PostgresStore, PgVector } from '@mastra/pg';
+
+interface SupabaseStorageOpts {
+    url: string;
+    secretKey: string;
+    /** Direct/Session Postgres URL (port 5432). REQUIRED — pg/Mastra need the non-pooler port. */
+    dbUrl: string;
+    max?: number;
+    /** Postgres SSL. Default for a remote dbUrl is `true` (verify the server cert). Explicit override honored.
+     *  Localhost stays unencrypted (undefined). Pass `{ rejectUnauthorized: false }` only to opt out of verification. */
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+    };
+}
+interface Ctx$1 {
+    pool: Pool;
+    sb: SupabaseClient;
+}
+
+declare function createMastraPgStore(opts: {
+    dbUrl: string;
+    disableInit?: boolean;
+}): PostgresStore;
+/** Mastra PgVector over the `nightowls` schema — backs semantic recall. The pgvector EXTENSION is enabled by
+ *  the packaged 0004 migration; PgVector auto-creates its index table on first recall (spike-verified). */
+declare function createMastraVectorStore(opts: {
+    dbUrl: string;
+}): PgVector;
+
+/** The shape callers pass — `version` is derived, not supplied. */
+type PublishAgentDef = Omit<AgentVersion, "version"> & {
+    tenantId: string;
+    actor?: string;
+    version?: number;
+};
+/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (not in the core interface).
+ *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`. */
+declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<void>;
+/** One row of an agent's version history (for rollback UX). */
+interface AgentVersionInfo {
+    version: number;
+    role: string;
+    modelId: string;
+    status: string;
+    isCurrent: boolean;
+}
+/** List an agent's versions (oldest→newest), flagging the current head. Tenant-scoped. Read-only — use it to
+ *  pick a `toVersion` for `rollbackAgentVersion`. Returns [] for an unknown agent. */
+declare function listAgentVersions(ctx: Ctx$1, tenantId: string, slug: string): Promise<AgentVersionInfo[]>;
+/**
+ * Roll an agent back to a prior version's content (R13). APPEND-ONLY: this republishes the target version's
+ * content as a NEW head (max+1) rather than moving the pointer backward — so history always moves forward (like
+ * `git revert`) and the version counter never collides. Audited as `action='rollback'` with `restoredFrom`.
+ * Throws if `toVersion` doesn't exist for this tenant/slug. NOTIFYs the R12 cache invalidation. Returns the new
+ * version number + the source it was restored from.
+ */
+declare function rollbackAgentVersion(ctx: Ctx$1, args: {
+    tenantId: string;
+    slug: string;
+    toVersion: number;
+    actor?: string;
+}): Promise<{
+    version: number;
+    restoredFrom: number;
+}>;
+
+/** A single Night Owls migration: a stable `version`, a human `name`, and fully-qualified `nightowls.*` SQL.
+ *  Night Owls contributes these to the host's `supabase/migrations/` (via `owl install`/`db eject`);
+ *  the host applies them with its own tooling — Night Owls never runs DDL itself. */
+interface Migration {
+    version: string;
+    name: string;
+    sql: string;
+}
+declare const MIGRATIONS: Migration[];
+
+/**
+ * The Night Owls adapter plugin manifest. `@nightowlsdev/cli` discovers this from the host's installed
+ * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
+ *  - `migrations` → ejected into the host's `supabase/migrations/` at install (the user applies them
+ *                   with their own tooling, e.g. `supabase db push` — Night Owls never runs DDL itself),
+ *  - `env`        → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`     → the `import` + wiring `snippet` inserted at the `// nightowls:storage` marker,
+ *  - `init`       → a print-only hook run after the wiring (it NEVER applies DDL),
+ *  - `commands`   → `owl storage-supabase <cmd>` subcommands (e.g. `info` — pure, no DB/network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "storage-supabase";
+    readonly version: "0.0.0";
+    readonly kind: "storage";
+    readonly pkg: "@nightowlsdev/storage-supabase";
+    readonly description: "Supabase Postgres storage + the nightowls schema (migrations, Realtime, RLS).";
+    readonly migrations: Migration[];
+    readonly env: readonly [{
+        readonly key: "SUPABASE_URL";
+        readonly example: "http://127.0.0.1:54321";
+        readonly comment: "Supabase project URL";
+    }, {
+        readonly key: "SUPABASE_SECRET_KEY";
+        readonly example: "";
+        readonly comment: "service_role/secret — server storage adapter ONLY (never in the browser)";
+    }, {
+        readonly key: "DATABASE_URL";
+        readonly example: "postgresql://postgres:postgres@127.0.0.1:5432/postgres";
+        readonly comment: "Session/Direct port 5432 — NOT 6543 (nightowls migrations + the pg pool)";
+    }, {
+        readonly key: "SUPABASE_ANON_KEY";
+        readonly example: "";
+        readonly comment: "publishable/anon — browser auth + Realtime ONLY";
+    }];
+    readonly config: {
+        readonly import: "import { createSupabaseStorage } from '@nightowlsdev/storage-supabase';";
+        readonly snippet: "storage = createSupabaseStorage({ url: env.SUPABASE_URL, secretKey: env.SUPABASE_SECRET_KEY, dbUrl: env.DATABASE_URL });";
+        readonly marker: "storage";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the nightowls migrations and env this adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface PostgresFloorOpts {
+    /** Stale-lock reclaim window — a held lock older than this is stealable (a crashed holder). Default 180_000. */
+    maxHoldMs?: number;
+    /** Poll interval while queued for the floor. Default 250. */
+    pollMs?: number;
+}
+/** A cross-instance {@link ContainerFloor} backed by Postgres (E3). Mutual exclusion is guaranteed by the
+ *  `floor_lock` primary key; FIFO order by `floor_waiter.enqueued_at` (millisecond-truncated so the JS-Date
+ *  precision a node-pg param carries matches the stored value, with `run_id` breaking ms ties → a total order);
+ *  waiter liveness by a `last_seen` HEARTBEAT touched on every poll (so a legitimately deep waiter — which can
+ *  wait many×maxHold behind others — is never mistaken for a crashed orphan, while a dead waiter still clears
+ *  within seconds). Wire it for serverless:
+ *  `new SwarmEngine({ …, floor: createPostgresFloor(storage.ctx.pool) })`. */
+declare function createPostgresFloor(pool: Pool, opts?: PostgresFloorOpts): ContainerFloor;
+
+/** The Supabase StorageAdapter plus a typed internal handle (`ctx`) so management helpers
+ *  like `publishAgentVersion` can reuse the same pg pool without any `as any` coupling. */
+interface SupabaseStorage extends StorageAdapter {
+    /** Internal pg pool + supabase-js client. Pass to `publishAgentVersion(storage.ctx, def)`. */
+    readonly ctx: Ctx$1;
+    close(): Promise<void>;
+}
+declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
+
+export { type AgentVersionInfo, type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion };