@databricks/appkit 0.19.1 → 0.20.1

package/CLAUDE.md

@@ -46,7 +46,7 @@ npx @databricks/appkit docs <query>
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
 - [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
-- [Lakebase plugin](./docs/plugins/lakebase.md): Currently, the Lakebase plugin currently requires a one-time manual setup to connect your Databricks App with your Lakebase database. An automated setup process is planned for an upcoming future release.
+- [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.19.1";
+var version = "0.20.1";
 
 //#endregion
 export { name, version };

package/dist/cache/storage/defaults.js

@@ -3,6 +3,7 @@
 const inMemoryStorageDefaults = { maxSize: 1e3 };
 /** Default configuration for Lakebase storage */
 const lakebaseStorageDefaults = {
+	schemaName: "appkit",
 	tableName: "appkit_cache_entries",
 	maxBytes: 256 * 1024 * 1024,
 	maxEntryBytes: 10 * 1024 * 1024,

package/dist/cache/storage/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","names":[],"sources":["../../../src/cache/storage/defaults.ts"],"sourcesContent":["/** Default configuration for in-memory storage */\nexport const inMemoryStorageDefaults = {\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n};\n\n/** Default configuration for Lakebase storage */\nexport const lakebaseStorageDefaults = {\n  /** Table name for the cache */\n  tableName: \"appkit_cache_entries\",\n  /** Maximum number of bytes in the cache */\n  maxBytes: 256 * 1024 * 1024, // 256MB\n  /** Maximum number of bytes per entry in the cache */\n  maxEntryBytes: 10 * 1024 * 1024, // 10MB\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n  /** Number of entries to evict when cache is full */\n  evictionBatchSize: 100,\n  /** Probability (0-1) of checking total bytes on each write operation */\n  evictionCheckProbability: 0.1,\n};\n"],"mappings":";;AACA,MAAa,0BAA0B,EAErC,SAAS,KACV;;AAGD,MAAa,0BAA0B;CAErC,WAAW;CAEX,UAAU,MAAM,OAAO;CAEvB,eAAe,KAAK,OAAO;CAE3B,SAAS;CAET,mBAAmB;CAEnB,0BAA0B;CAC3B"}
+{"version":3,"file":"defaults.js","names":[],"sources":["../../../src/cache/storage/defaults.ts"],"sourcesContent":["/** Default configuration for in-memory storage */\nexport const inMemoryStorageDefaults = {\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n};\n\n/** Default configuration for Lakebase storage */\nexport const lakebaseStorageDefaults = {\n  /** Schema name for the cache tables */\n  schemaName: \"appkit\",\n  /** Table name for the cache */\n  tableName: \"appkit_cache_entries\",\n  /** Maximum number of bytes in the cache */\n  maxBytes: 256 * 1024 * 1024, // 256MB\n  /** Maximum number of bytes per entry in the cache */\n  maxEntryBytes: 10 * 1024 * 1024, // 10MB\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n  /** Number of entries to evict when cache is full */\n  evictionBatchSize: 100,\n  /** Probability (0-1) of checking total bytes on each write operation */\n  evictionCheckProbability: 0.1,\n};\n"],"mappings":";;AACA,MAAa,0BAA0B,EAErC,SAAS,KACV;;AAGD,MAAa,0BAA0B;CAErC,YAAY;CAEZ,WAAW;CAEX,UAAU,MAAM,OAAO;CAEvB,eAAe,KAAK,OAAO;CAE3B,SAAS;CAET,mBAAmB;CAEnB,0BAA0B;CAC3B"}

package/dist/cache/storage/persistent.js

@@ -25,7 +25,9 @@ const logger = createLogger("cache:persistent");
 */
 var PersistentStorage = class {
 	pool;
+	schemaName;
 	tableName;
+	qualifiedTableName;
 	maxBytes;
 	maxEntryBytes;
 	evictionBatchSize;
@@ -37,7 +39,9 @@ var PersistentStorage = class {
 		this.maxEntryBytes = config.maxEntryBytes ?? lakebaseStorageDefaults.maxEntryBytes;
 		this.evictionBatchSize = lakebaseStorageDefaults.evictionBatchSize;
 		this.evictionCheckProbability = config.evictionCheckProbability ?? lakebaseStorageDefaults.evictionCheckProbability;
+		this.schemaName = lakebaseStorageDefaults.schemaName;
 		this.tableName = lakebaseStorageDefaults.tableName;
+		this.qualifiedTableName = `${this.schemaName}.${this.tableName}`;
 		this.initialized = false;
 	}
 	/** Initialize the persistent storage and run migrations if necessary */
@@ -59,10 +63,10 @@ var PersistentStorage = class {
 	async get(key) {
 		await this.ensureInitialized();
 		const keyHash = this.hashKey(key);
-		const result = await this.pool.query(`SELECT value, expiry FROM ${this.tableName} WHERE key_hash = $1`, [keyHash]);
+		const result = await this.pool.query(`SELECT value, expiry FROM ${this.qualifiedTableName} WHERE key_hash = $1`, [keyHash]);
 		if (result.rows.length === 0) return null;
 		const entry = result.rows[0];
-		this.pool.query(`UPDATE ${this.tableName} SET last_accessed = NOW() WHERE key_hash = $1`, [keyHash]).catch(() => {
+		this.pool.query(`UPDATE ${this.qualifiedTableName} SET last_accessed = NOW() WHERE key_hash = $1`, [keyHash]).catch(() => {
 			logger.debug("Error updating last_accessed time for key: %s", key);
 		});
 		return {
@@ -86,7 +90,7 @@ var PersistentStorage = class {
 		if (Math.random() < this.evictionCheckProbability) {
 			if (await this.totalBytes() + byteSize > this.maxBytes) await this.evictBySize(byteSize);
 		}
-		await this.pool.query(`INSERT INTO ${this.tableName} (key_hash, key, value, byte_size, expiry, created_at, last_accessed)
+		await this.pool.query(`INSERT INTO ${this.qualifiedTableName} (key_hash, key, value, byte_size, expiry, created_at, last_accessed)
       VALUES ($1, $2, $3, $4, $5, NOW(), NOW())
       ON CONFLICT (key_hash)
       DO UPDATE SET value = $3, byte_size = $4, expiry = $5, last_accessed = NOW()
@@ -106,12 +110,12 @@ var PersistentStorage = class {
 	async delete(key) {
 		await this.ensureInitialized();
 		const keyHash = this.hashKey(key);
-		await this.pool.query(`DELETE FROM ${this.tableName} WHERE key_hash = $1`, [keyHash]);
+		await this.pool.query(`DELETE FROM ${this.qualifiedTableName} WHERE key_hash = $1`, [keyHash]);
 	}
 	/** Clear the persistent storage */
 	async clear() {
 		await this.ensureInitialized();
-		await this.pool.query(`TRUNCATE TABLE ${this.tableName}`);
+		await this.pool.query(`TRUNCATE TABLE ${this.qualifiedTableName}`);
 	}
 	/**
 	* Check if a value exists in the persistent storage
@@ -121,7 +125,7 @@ var PersistentStorage = class {
 	async has(key) {
 		await this.ensureInitialized();
 		const keyHash = this.hashKey(key);
-		return (await this.pool.query(`SELECT EXISTS(SELECT 1 FROM ${this.tableName} WHERE key_hash = $1) as exists`, [keyHash])).rows[0]?.exists ?? false;
+		return (await this.pool.query(`SELECT EXISTS(SELECT 1 FROM ${this.qualifiedTableName} WHERE key_hash = $1) as exists`, [keyHash])).rows[0]?.exists ?? false;
 	}
 	/**
 	* Get the size of the persistent storage
@@ -129,13 +133,13 @@ var PersistentStorage = class {
 	*/
 	async size() {
 		await this.ensureInitialized();
-		const result = await this.pool.query(`SELECT COUNT(*) as count FROM ${this.tableName}`);
+		const result = await this.pool.query(`SELECT COUNT(*) as count FROM ${this.qualifiedTableName}`);
 		return parseInt(result.rows[0]?.count ?? "0", 10);
 	}
 	/** Get the total number of bytes in the persistent storage */
 	async totalBytes() {
 		await this.ensureInitialized();
-		const result = await this.pool.query(`SELECT COALESCE(SUM(byte_size), 0) as total FROM ${this.tableName}`);
+		const result = await this.pool.query(`SELECT COALESCE(SUM(byte_size), 0) as total FROM ${this.qualifiedTableName}`);
 		return parseInt(result.rows[0]?.total ?? "0", 10);
 	}
 	/**
@@ -167,7 +171,7 @@ var PersistentStorage = class {
 	*/
 	async cleanupExpired() {
 		await this.ensureInitialized();
-		const result = await this.pool.query(`WITH deleted as (DELETE FROM ${this.tableName} WHERE expiry < $1 RETURNING *) SELECT COUNT(*) as count FROM deleted`, [Date.now()]);
+		const result = await this.pool.query(`WITH deleted as (DELETE FROM ${this.qualifiedTableName} WHERE expiry < $1 RETURNING *) SELECT COUNT(*) as count FROM deleted`, [Date.now()]);
 		return parseInt(result.rows[0]?.count ?? "0", 10);
 	}
 	/** Evict entries from the persistent storage by size */
@@ -175,8 +179,8 @@ var PersistentStorage = class {
 		if (await this.cleanupExpired() > 0) {
 			if (await this.totalBytes() + requiredBytes <= this.maxBytes) return;
 		}
-		await this.pool.query(`DELETE FROM ${this.tableName} WHERE key_hash IN
-      (SELECT key_hash FROM ${this.tableName} ORDER BY last_accessed ASC LIMIT $1)`, [this.evictionBatchSize]);
+		await this.pool.query(`DELETE FROM ${this.qualifiedTableName} WHERE key_hash IN
+      (SELECT key_hash FROM ${this.qualifiedTableName} ORDER BY last_accessed ASC LIMIT $1)`, [this.evictionBatchSize]);
 	}
 	/** Ensure the persistent storage is initialized */
 	async ensureInitialized() {
@@ -197,9 +201,14 @@ var PersistentStorage = class {
 	}
 	/** Run migrations for the persistent storage */
 	async runMigrations() {
-		try {
-			await this.pool.query(`
-            CREATE TABLE IF NOT EXISTS ${this.tableName} (
+		const steps = [
+			{
+				name: "create schema",
+				query: `CREATE SCHEMA IF NOT EXISTS ${this.schemaName}`
+			},
+			{
+				name: "create table",
+				query: `CREATE TABLE IF NOT EXISTS ${this.qualifiedTableName} (
                 id BIGSERIAL PRIMARY KEY,
                 key_hash BIGINT NOT NULL,
                 key BYTEA NOT NULL,
@@ -208,14 +217,29 @@ var PersistentStorage = class {
                 expiry BIGINT NOT NULL,
                 created_at TIMESTAMP NOT NULL DEFAULT NOW(),
                 last_accessed TIMESTAMP NOT NULL DEFAULT NOW()
-            )
-            `);
-			await this.pool.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.tableName}_key_hash ON ${this.tableName} (key_hash);`);
-			await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_expiry ON ${this.tableName} (expiry); `);
-			await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_last_accessed ON ${this.tableName} (last_accessed); `);
-			await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_byte_size ON ${this.tableName} (byte_size); `);
+            )`
+			},
+			{
+				name: "create index (key_hash)",
+				query: `CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.tableName}_key_hash ON ${this.qualifiedTableName} (key_hash)`
+			},
+			{
+				name: "create index (expiry)",
+				query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_expiry ON ${this.qualifiedTableName} (expiry)`
+			},
+			{
+				name: "create index (last_accessed)",
+				query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_last_accessed ON ${this.qualifiedTableName} (last_accessed)`
+			},
+			{
+				name: "create index (byte_size)",
+				query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_byte_size ON ${this.qualifiedTableName} (byte_size)`
+			}
+		];
+		for (const step of steps) try {
+			await this.pool.query(step.query);
 		} catch (error) {
-			logger.error("Error in running migrations for persistent storage: %O", error);
+			logger.error("Migration step '%s' failed: %O", step.name, error);
 			throw InitializationError.migrationFailed(error);
 		}
 	}

package/dist/cache/storage/persistent.js.map

@@ -1 +1 @@
-{"version":3,"file":"persistent.js","names":[],"sources":["../../../src/cache/storage/persistent.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type pg from \"pg\";\nimport type { CacheConfig, CacheEntry, CacheStorage } from \"shared\";\nimport { InitializationError, ValidationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { lakebaseStorageDefaults } from \"./defaults\";\n\nconst logger = createLogger(\"cache:persistent\");\n\n/**\n * Persistent cache storage implementation. Uses a least recently used (LRU) eviction policy\n * to manage memory usage and ensure efficient cache operations.\n *\n * @example\n * const pool = createLakebasePool({ workspaceClient });\n * const persistentStorage = new PersistentStorage(config, pool);\n * await persistentStorage.initialize();\n * await persistentStorage.get(\"my-key\");\n * await persistentStorage.set(\"my-key\", \"my-value\");\n * await persistentStorage.delete(\"my-key\");\n * await persistentStorage.clear();\n * await persistentStorage.has(\"my-key\");\n *\n */\nexport class PersistentStorage implements CacheStorage {\n  private readonly pool: pg.Pool;\n  private readonly tableName: string;\n  private readonly maxBytes: number;\n  private readonly maxEntryBytes: number;\n  private readonly evictionBatchSize: number;\n  private readonly evictionCheckProbability: number;\n  private initialized: boolean;\n\n  constructor(config: CacheConfig, pool: pg.Pool) {\n    this.pool = pool;\n    this.maxBytes = config.maxBytes ?? lakebaseStorageDefaults.maxBytes;\n    this.maxEntryBytes =\n      config.maxEntryBytes ?? lakebaseStorageDefaults.maxEntryBytes;\n    this.evictionBatchSize = lakebaseStorageDefaults.evictionBatchSize;\n    this.evictionCheckProbability =\n      config.evictionCheckProbability ??\n      lakebaseStorageDefaults.evictionCheckProbability;\n    this.tableName = lakebaseStorageDefaults.tableName; // hardcoded, safe for now\n    this.initialized = false;\n  }\n\n  /** Initialize the persistent storage and run migrations if necessary */\n  async initialize(): Promise<void> {\n    if (this.initialized) return;\n\n    try {\n      await this.runMigrations();\n      this.initialized = true;\n    } catch (error) {\n      logger.error(\"Error in persistent storage initialization: %O\", error);\n      throw error;\n    }\n  }\n\n  /**\n   * Get a cached value from the persistent storage\n   * @param key - Cache key\n   * @returns Promise of the cached value or null if not found\n   */\n  async get<T>(key: string): Promise<CacheEntry<T> | null> {\n    await this.ensureInitialized();\n\n    const keyHash = this.hashKey(key);\n\n    const result = await this.pool.query<{\n      value: Buffer;\n      expiry: string;\n    }>(`SELECT value, expiry FROM ${this.tableName} WHERE key_hash = $1`, [\n      keyHash,\n    ]);\n\n    if (result.rows.length === 0) return null;\n\n    const entry = result.rows[0];\n\n    // fire-and-forget update\n    this.pool\n      .query(\n        `UPDATE ${this.tableName} SET last_accessed = NOW() WHERE key_hash = $1`,\n        [keyHash],\n      )\n      .catch(() => {\n        logger.debug(\"Error updating last_accessed time for key: %s\", key);\n      });\n\n    return {\n      value: this.deserializeValue<T>(entry.value),\n      expiry: Number(entry.expiry),\n    };\n  }\n\n  /**\n   * Set a value in the persistent storage\n   * @param key - Cache key\n   * @param entry - Cache entry\n   * @returns Promise of the result\n   */\n  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {\n    await this.ensureInitialized();\n\n    const keyHash = this.hashKey(key);\n    const keyBytes = Buffer.from(key, \"utf-8\");\n    const valueBytes = this.serializeValue(entry.value);\n    const byteSize = keyBytes.length + valueBytes.length;\n\n    if (byteSize > this.maxEntryBytes) {\n      throw ValidationError.invalidValue(\n        \"cache entry size\",\n        byteSize,\n        `maximum ${this.maxEntryBytes} bytes`,\n      );\n    }\n\n    // probabilistic eviction check\n    if (Math.random() < this.evictionCheckProbability) {\n      const totalBytes = await this.totalBytes();\n      if (totalBytes + byteSize > this.maxBytes) {\n        await this.evictBySize(byteSize);\n      }\n    }\n\n    await this.pool.query(\n      `INSERT INTO ${this.tableName} (key_hash, key, value, byte_size, expiry, created_at, last_accessed)\n      VALUES ($1, $2, $3, $4, $5, NOW(), NOW())\n      ON CONFLICT (key_hash)\n      DO UPDATE SET value = $3, byte_size = $4, expiry = $5, last_accessed = NOW()\n      `,\n      [keyHash, keyBytes, valueBytes, byteSize, entry.expiry],\n    );\n  }\n\n  /**\n   * Delete a value from the persistent storage\n   * @param key - Cache key\n   * @returns Promise of the result\n   */\n  async delete(key: string): Promise<void> {\n    await this.ensureInitialized();\n    const keyHash = this.hashKey(key);\n    await this.pool.query(`DELETE FROM ${this.tableName} WHERE key_hash = $1`, [\n      keyHash,\n    ]);\n  }\n\n  /** Clear the persistent storage */\n  async clear(): Promise<void> {\n    await this.ensureInitialized();\n    await this.pool.query(`TRUNCATE TABLE ${this.tableName}`);\n  }\n\n  /**\n   * Check if a value exists in the persistent storage\n   * @param key - Cache key\n   * @returns Promise of true if the value exists, false otherwise\n   */\n  async has(key: string): Promise<boolean> {\n    await this.ensureInitialized();\n    const keyHash = this.hashKey(key);\n\n    const result = await this.pool.query<{ exists: boolean }>(\n      `SELECT EXISTS(SELECT 1 FROM ${this.tableName} WHERE key_hash = $1) as exists`,\n      [keyHash],\n    );\n\n    return result.rows[0]?.exists ?? false;\n  }\n\n  /**\n   * Get the size of the persistent storage\n   * @returns Promise of the size of the storage\n   */\n  async size(): Promise<number> {\n    await this.ensureInitialized();\n\n    const result = await this.pool.query<{ count: string }>(\n      `SELECT COUNT(*) as count FROM ${this.tableName}`,\n    );\n    return parseInt(result.rows[0]?.count ?? \"0\", 10);\n  }\n\n  /** Get the total number of bytes in the persistent storage */\n  async totalBytes(): Promise<number> {\n    await this.ensureInitialized();\n\n    const result = await this.pool.query<{ total: string }>(\n      `SELECT COALESCE(SUM(byte_size), 0) as total FROM ${this.tableName}`,\n    );\n    return parseInt(result.rows[0]?.total ?? \"0\", 10);\n  }\n\n  /**\n   * Check if the persistent storage is persistent\n   * @returns true if the storage is persistent, false otherwise\n   */\n  isPersistent(): boolean {\n    return true;\n  }\n\n  /**\n   * Check if the persistent storage is healthy\n   * @returns Promise of true if the storage is healthy, false otherwise\n   */\n  async healthCheck(): Promise<boolean> {\n    try {\n      await this.pool.query(\"SELECT 1\");\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /** Close the persistent storage */\n  async close(): Promise<void> {\n    await this.pool.end();\n  }\n\n  /**\n   * Cleanup expired entries from the persistent storage\n   * @returns Promise of the number of expired entries\n   */\n  async cleanupExpired(): Promise<number> {\n    await this.ensureInitialized();\n    const result = await this.pool.query<{ count: string }>(\n      `WITH deleted as (DELETE FROM ${this.tableName} WHERE expiry < $1 RETURNING *) SELECT COUNT(*) as count FROM deleted`,\n      [Date.now()],\n    );\n    return parseInt(result.rows[0]?.count ?? \"0\", 10);\n  }\n\n  /** Evict entries from the persistent storage by size */\n  private async evictBySize(requiredBytes: number): Promise<void> {\n    const freedByExpiry = await this.cleanupExpired();\n    if (freedByExpiry > 0) {\n      const currentBytes = await this.totalBytes();\n      if (currentBytes + requiredBytes <= this.maxBytes) {\n        return;\n      }\n    }\n\n    await this.pool.query(\n      `DELETE FROM ${this.tableName} WHERE key_hash IN\n      (SELECT key_hash FROM ${this.tableName} ORDER BY last_accessed ASC LIMIT $1)`,\n      [this.evictionBatchSize],\n    );\n  }\n\n  /** Ensure the persistent storage is initialized */\n  private async ensureInitialized(): Promise<void> {\n    if (!this.initialized) {\n      await this.initialize();\n    }\n  }\n\n  /** Generate a 64-bit hash for the cache key using SHA256 */\n  private hashKey(key: string): bigint {\n    if (!key) throw ValidationError.missingField(\"key\");\n    const hash = createHash(\"sha256\").update(key).digest();\n    return hash.readBigInt64BE(0);\n  }\n\n  /** Serialize a value to a buffer */\n  private serializeValue<T>(value: T): Buffer {\n    return Buffer.from(JSON.stringify(value), \"utf-8\");\n  }\n\n  /** Deserialize a value from a buffer */\n  private deserializeValue<T>(buffer: Buffer): T {\n    return JSON.parse(buffer.toString(\"utf-8\")) as T;\n  }\n\n  /** Run migrations for the persistent storage */\n  private async runMigrations(): Promise<void> {\n    try {\n      await this.pool.query(`\n            CREATE TABLE IF NOT EXISTS ${this.tableName} (\n                id BIGSERIAL PRIMARY KEY,\n                key_hash BIGINT NOT NULL,\n                key BYTEA NOT NULL,\n                value BYTEA NOT NULL,\n                byte_size INTEGER NOT NULL,\n                expiry BIGINT NOT NULL,\n                created_at TIMESTAMP NOT NULL DEFAULT NOW(),\n                last_accessed TIMESTAMP NOT NULL DEFAULT NOW()\n            )\n            `);\n\n      // unique index on key_hash for fast lookups\n      await this.pool.query(\n        `CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.tableName}_key_hash ON ${this.tableName} (key_hash);`,\n      );\n\n      // index on expiry for cleanup queries\n      await this.pool.query(\n        `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_expiry ON ${this.tableName} (expiry); `,\n      );\n\n      // index on last_accessed for LRU eviction\n      await this.pool.query(\n        `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_last_accessed ON ${this.tableName} (last_accessed); `,\n      );\n\n      // index on byte_size for monitoring\n      await this.pool.query(\n        `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_byte_size ON ${this.tableName} (byte_size); `,\n      );\n    } catch (error) {\n      logger.error(\n        \"Error in running migrations for persistent storage: %O\",\n        error,\n      );\n      throw InitializationError.migrationFailed(error as Error);\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"persistent.js","names":[],"sources":["../../../src/cache/storage/persistent.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type pg from \"pg\";\nimport type { CacheConfig, CacheEntry, CacheStorage } from \"shared\";\nimport { InitializationError, ValidationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { lakebaseStorageDefaults } from \"./defaults\";\n\nconst logger = createLogger(\"cache:persistent\");\n\n/**\n * Persistent cache storage implementation. Uses a least recently used (LRU) eviction policy\n * to manage memory usage and ensure efficient cache operations.\n *\n * @example\n * const pool = createLakebasePool({ workspaceClient });\n * const persistentStorage = new PersistentStorage(config, pool);\n * await persistentStorage.initialize();\n * await persistentStorage.get(\"my-key\");\n * await persistentStorage.set(\"my-key\", \"my-value\");\n * await persistentStorage.delete(\"my-key\");\n * await persistentStorage.clear();\n * await persistentStorage.has(\"my-key\");\n *\n */\nexport class PersistentStorage implements CacheStorage {\n  private readonly pool: pg.Pool;\n  private readonly schemaName: string;\n  private readonly tableName: string;\n  private readonly qualifiedTableName: string;\n  private readonly maxBytes: number;\n  private readonly maxEntryBytes: number;\n  private readonly evictionBatchSize: number;\n  private readonly evictionCheckProbability: number;\n  private initialized: boolean;\n\n  constructor(config: CacheConfig, pool: pg.Pool) {\n    this.pool = pool;\n    this.maxBytes = config.maxBytes ?? lakebaseStorageDefaults.maxBytes;\n    this.maxEntryBytes =\n      config.maxEntryBytes ?? lakebaseStorageDefaults.maxEntryBytes;\n    this.evictionBatchSize = lakebaseStorageDefaults.evictionBatchSize;\n    this.evictionCheckProbability =\n      config.evictionCheckProbability ??\n      lakebaseStorageDefaults.evictionCheckProbability;\n    this.schemaName = lakebaseStorageDefaults.schemaName;\n    this.tableName = lakebaseStorageDefaults.tableName;\n    this.qualifiedTableName = `${this.schemaName}.${this.tableName}`;\n    this.initialized = false;\n  }\n\n  /** Initialize the persistent storage and run migrations if necessary */\n  async initialize(): Promise<void> {\n    if (this.initialized) return;\n\n    try {\n      await this.runMigrations();\n      this.initialized = true;\n    } catch (error) {\n      logger.error(\"Error in persistent storage initialization: %O\", error);\n      throw error;\n    }\n  }\n\n  /**\n   * Get a cached value from the persistent storage\n   * @param key - Cache key\n   * @returns Promise of the cached value or null if not found\n   */\n  async get<T>(key: string): Promise<CacheEntry<T> | null> {\n    await this.ensureInitialized();\n\n    const keyHash = this.hashKey(key);\n\n    const result = await this.pool.query<{\n      value: Buffer;\n      expiry: string;\n    }>(\n      `SELECT value, expiry FROM ${this.qualifiedTableName} WHERE key_hash = $1`,\n      [keyHash],\n    );\n\n    if (result.rows.length === 0) return null;\n\n    const entry = result.rows[0];\n\n    // fire-and-forget update\n    this.pool\n      .query(\n        `UPDATE ${this.qualifiedTableName} SET last_accessed = NOW() WHERE key_hash = $1`,\n        [keyHash],\n      )\n      .catch(() => {\n        logger.debug(\"Error updating last_accessed time for key: %s\", key);\n      });\n\n    return {\n      value: this.deserializeValue<T>(entry.value),\n      expiry: Number(entry.expiry),\n    };\n  }\n\n  /**\n   * Set a value in the persistent storage\n   * @param key - Cache key\n   * @param entry - Cache entry\n   * @returns Promise of the result\n   */\n  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {\n    await this.ensureInitialized();\n\n    const keyHash = this.hashKey(key);\n    const keyBytes = Buffer.from(key, \"utf-8\");\n    const valueBytes = this.serializeValue(entry.value);\n    const byteSize = keyBytes.length + valueBytes.length;\n\n    if (byteSize > this.maxEntryBytes) {\n      throw ValidationError.invalidValue(\n        \"cache entry size\",\n        byteSize,\n        `maximum ${this.maxEntryBytes} bytes`,\n      );\n    }\n\n    // probabilistic eviction check\n    if (Math.random() < this.evictionCheckProbability) {\n      const totalBytes = await this.totalBytes();\n      if (totalBytes + byteSize > this.maxBytes) {\n        await this.evictBySize(byteSize);\n      }\n    }\n\n    await this.pool.query(\n      `INSERT INTO ${this.qualifiedTableName} (key_hash, key, value, byte_size, expiry, created_at, last_accessed)\n      VALUES ($1, $2, $3, $4, $5, NOW(), NOW())\n      ON CONFLICT (key_hash)\n      DO UPDATE SET value = $3, byte_size = $4, expiry = $5, last_accessed = NOW()\n      `,\n      [keyHash, keyBytes, valueBytes, byteSize, entry.expiry],\n    );\n  }\n\n  /**\n   * Delete a value from the persistent storage\n   * @param key - Cache key\n   * @returns Promise of the result\n   */\n  async delete(key: string): Promise<void> {\n    await this.ensureInitialized();\n    const keyHash = this.hashKey(key);\n    await this.pool.query(\n      `DELETE FROM ${this.qualifiedTableName} WHERE key_hash = $1`,\n      [keyHash],\n    );\n  }\n\n  /** Clear the persistent storage */\n  async clear(): Promise<void> {\n    await this.ensureInitialized();\n    await this.pool.query(`TRUNCATE TABLE ${this.qualifiedTableName}`);\n  }\n\n  /**\n   * Check if a value exists in the persistent storage\n   * @param key - Cache key\n   * @returns Promise of true if the value exists, false otherwise\n   */\n  async has(key: string): Promise<boolean> {\n    await this.ensureInitialized();\n    const keyHash = this.hashKey(key);\n\n    const result = await this.pool.query<{ exists: boolean }>(\n      `SELECT EXISTS(SELECT 1 FROM ${this.qualifiedTableName} WHERE key_hash = $1) as exists`,\n      [keyHash],\n    );\n\n    return result.rows[0]?.exists ?? false;\n  }\n\n  /**\n   * Get the size of the persistent storage\n   * @returns Promise of the size of the storage\n   */\n  async size(): Promise<number> {\n    await this.ensureInitialized();\n\n    const result = await this.pool.query<{ count: string }>(\n      `SELECT COUNT(*) as count FROM ${this.qualifiedTableName}`,\n    );\n    return parseInt(result.rows[0]?.count ?? \"0\", 10);\n  }\n\n  /** Get the total number of bytes in the persistent storage */\n  async totalBytes(): Promise<number> {\n    await this.ensureInitialized();\n\n    const result = await this.pool.query<{ total: string }>(\n      `SELECT COALESCE(SUM(byte_size), 0) as total FROM ${this.qualifiedTableName}`,\n    );\n    return parseInt(result.rows[0]?.total ?? \"0\", 10);\n  }\n\n  /**\n   * Check if the persistent storage is persistent\n   * @returns true if the storage is persistent, false otherwise\n   */\n  isPersistent(): boolean {\n    return true;\n  }\n\n  /**\n   * Check if the persistent storage is healthy\n   * @returns Promise of true if the storage is healthy, false otherwise\n   */\n  async healthCheck(): Promise<boolean> {\n    try {\n      await this.pool.query(\"SELECT 1\");\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /** Close the persistent storage */\n  async close(): Promise<void> {\n    await this.pool.end();\n  }\n\n  /**\n   * Cleanup expired entries from the persistent storage\n   * @returns Promise of the number of expired entries\n   */\n  async cleanupExpired(): Promise<number> {\n    await this.ensureInitialized();\n    const result = await this.pool.query<{ count: string }>(\n      `WITH deleted as (DELETE FROM ${this.qualifiedTableName} WHERE expiry < $1 RETURNING *) SELECT COUNT(*) as count FROM deleted`,\n      [Date.now()],\n    );\n    return parseInt(result.rows[0]?.count ?? \"0\", 10);\n  }\n\n  /** Evict entries from the persistent storage by size */\n  private async evictBySize(requiredBytes: number): Promise<void> {\n    const freedByExpiry = await this.cleanupExpired();\n    if (freedByExpiry > 0) {\n      const currentBytes = await this.totalBytes();\n      if (currentBytes + requiredBytes <= this.maxBytes) {\n        return;\n      }\n    }\n\n    await this.pool.query(\n      `DELETE FROM ${this.qualifiedTableName} WHERE key_hash IN\n      (SELECT key_hash FROM ${this.qualifiedTableName} ORDER BY last_accessed ASC LIMIT $1)`,\n      [this.evictionBatchSize],\n    );\n  }\n\n  /** Ensure the persistent storage is initialized */\n  private async ensureInitialized(): Promise<void> {\n    if (!this.initialized) {\n      await this.initialize();\n    }\n  }\n\n  /** Generate a 64-bit hash for the cache key using SHA256 */\n  private hashKey(key: string): bigint {\n    if (!key) throw ValidationError.missingField(\"key\");\n    const hash = createHash(\"sha256\").update(key).digest();\n    return hash.readBigInt64BE(0);\n  }\n\n  /** Serialize a value to a buffer */\n  private serializeValue<T>(value: T): Buffer {\n    return Buffer.from(JSON.stringify(value), \"utf-8\");\n  }\n\n  /** Deserialize a value from a buffer */\n  private deserializeValue<T>(buffer: Buffer): T {\n    return JSON.parse(buffer.toString(\"utf-8\")) as T;\n  }\n\n  /** Run migrations for the persistent storage */\n  private async runMigrations(): Promise<void> {\n    const steps = [\n      {\n        name: \"create schema\",\n        query: `CREATE SCHEMA IF NOT EXISTS ${this.schemaName}`,\n      },\n      {\n        name: \"create table\",\n        query: `CREATE TABLE IF NOT EXISTS ${this.qualifiedTableName} (\n                id BIGSERIAL PRIMARY KEY,\n                key_hash BIGINT NOT NULL,\n                key BYTEA NOT NULL,\n                value BYTEA NOT NULL,\n                byte_size INTEGER NOT NULL,\n                expiry BIGINT NOT NULL,\n                created_at TIMESTAMP NOT NULL DEFAULT NOW(),\n                last_accessed TIMESTAMP NOT NULL DEFAULT NOW()\n            )`,\n      },\n      {\n        name: \"create index (key_hash)\",\n        query: `CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.tableName}_key_hash ON ${this.qualifiedTableName} (key_hash)`,\n      },\n      {\n        name: \"create index (expiry)\",\n        query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_expiry ON ${this.qualifiedTableName} (expiry)`,\n      },\n      {\n        name: \"create index (last_accessed)\",\n        query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_last_accessed ON ${this.qualifiedTableName} (last_accessed)`,\n      },\n      {\n        name: \"create index (byte_size)\",\n        query: `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_byte_size ON ${this.qualifiedTableName} (byte_size)`,\n      },\n    ];\n\n    for (const step of steps) {\n      try {\n        await this.pool.query(step.query);\n      } catch (error) {\n        logger.error(\"Migration step '%s' failed: %O\", step.name, error);\n        throw InitializationError.migrationFailed(error as Error);\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/plugins/lakebase/manifest.js

@@ -4,10 +4,56 @@ var manifest_default = {
 	name: "lakebase",
 	displayName: "Lakebase",
 	description: "SQL query execution against Databricks Lakebase Autoscaling",
-	onSetupMessage: "Configure environment variables before running or deploying the app.\nSee: https://databricks.github.io/appkit/docs/plugins/lakebase",
 	hidden: false,
 	resources: {
-		"required": [],
+		"required": [{
+			"type": "postgres",
+			"alias": "Postgres",
+			"resourceKey": "postgres",
+			"description": "Lakebase Postgres database for persistent storage",
+			"permission": "CAN_CONNECT_AND_CREATE",
+			"fields": {
+				"branch": {
+					"description": "Full Lakebase Postgres branch resource name. Obtain by running `databricks postgres list-branches projects/{project-id}`, select the desired item from the output array and use its .name value.",
+					"examples": ["projects/{project-id}/branches/{branch-id}"]
+				},
+				"database": {
+					"description": "Full Lakebase Postgres database resource name. Obtain by running `databricks postgres list-databases {branch-name}`, select the desired item from the output array and use its .name value. Requires the branch resource name.",
+					"examples": ["projects/{project-id}/branches/{branch-id}/databases/{database-id}"]
+				},
+				"host": {
+					"env": "PGHOST",
+					"localOnly": true,
+					"resolve": "postgres:host",
+					"description": "Postgres host for local development. Auto-injected by the platform at deploy time."
+				},
+				"databaseName": {
+					"env": "PGDATABASE",
+					"localOnly": true,
+					"resolve": "postgres:databaseName",
+					"description": "Postgres database name for local development. Auto-injected by the platform at deploy time."
+				},
+				"endpointPath": {
+					"env": "LAKEBASE_ENDPOINT",
+					"bundleIgnore": true,
+					"resolve": "postgres:endpointPath",
+					"description": "Lakebase endpoint resource name. Auto-injected at runtime via app.yaml valueFrom: postgres. For local development, obtain by running `databricks postgres list-endpoints {branch-name}`, select the desired item from the output array and use its .name value.",
+					"examples": ["projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}"]
+				},
+				"port": {
+					"env": "PGPORT",
+					"localOnly": true,
+					"value": "5432",
+					"description": "Postgres port. Auto-injected by the platform at deploy time."
+				},
+				"sslmode": {
+					"env": "PGSSLMODE",
+					"localOnly": true,
+					"value": "require",
+					"description": "Postgres SSL mode. Auto-injected by the platform at deploy time."
+				}
+			}
+		}],
 		"optional": []
 	}
 };

package/dist/registry/resource-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-registry.d.ts","names":[],"sources":["../../src/registry/resource-registry.ts"],"mappings":";;;;;;;;;cAqDa,gBAAA;EAAA,QACH,SAAA;EAgYsC;;;;;;;;;;;;EAlXvC,QAAA,CAAS,MAAA,UAAgB,QAAA,EAAU,mBAAA;EAiKnC;;;;;;;EAtIA,gBAAA,CACL,UAAA,EAAY,UAAA,CAAW,iBAAA;EAyKlB;;;;EAAA,QAjIC,cAAA;EAqJD;;;;;;EAxDA,MAAA,CAAA,GAAU,aAAA;EA4L6B;;;;;;;EAjLvC,GAAA,CAAI,IAAA,UAAc,WAAA,WAAsB,aAAA;;;;;EAQxC,KAAA,CAAA;;;;EAOA,IAAA,CAAA;;;;;;;EAUA,WAAA,CAAY,UAAA,WAAqB,aAAA;;;;;;EAWjC,WAAA,CAAA,GAAe,aAAA;;;;;;EASf,WAAA,CAAA,GAAe,aAAA;;;;;;;;;;;;;;;;;;;;;;EAyBf,QAAA,CAAA,GAAY,gBAAA;;;;;;;;;;;;EA8DZ,iBAAA,CAAA,GAAqB,gBAAA;;;;;;;SA6Cd,sBAAA,CAAuB,OAAA,EAAS,aAAA;;;;;;;;SAqBhC,sBAAA,CAAuB,OAAA,EAAS,aAAA;AAAA"}
+{"version":3,"file":"resource-registry.d.ts","names":[],"sources":["../../src/registry/resource-registry.ts"],"mappings":";;;;;;;;;cAqDa,gBAAA;EAAA,QACH,SAAA;EAiYsC;;;;;;;;;;;;EAnXvC,QAAA,CAAS,MAAA,UAAgB,QAAA,EAAU,mBAAA;EAiKnC;;;;;;;EAtIA,gBAAA,CACL,UAAA,EAAY,UAAA,CAAW,iBAAA;EAyKlB;;;;EAAA,QAjIC,cAAA;EAqJD;;;;;;EAxDA,MAAA,CAAA,GAAU,aAAA;EA6L6B;;;;;;;EAlLvC,GAAA,CAAI,IAAA,UAAc,WAAA,WAAsB,aAAA;;;;;EAQxC,KAAA,CAAA;;;;EAOA,IAAA,CAAA;;;;;;;EAUA,WAAA,CAAY,UAAA,WAAqB,aAAA;;;;;;EAWjC,WAAA,CAAA,GAAe,aAAA;;;;;;EASf,WAAA,CAAA,GAAe,aAAA;;;;;;;;;;;;;;;;;;;;;;EAyBf,QAAA,CAAA,GAAY,gBAAA;;;;;;;;;;;;EA+DZ,iBAAA,CAAA,GAAqB,gBAAA;;;;;;;SA6Cd,sBAAA,CAAuB,OAAA,EAAS,aAAA;;;;;;;;SAqBhC,sBAAA,CAAuB,OAAA,EAAS,aAAA;AAAA"}

package/dist/registry/resource-registry.js

@@ -203,6 +203,7 @@ var ResourceRegistry = class ResourceRegistry {
 			const values = {};
 			let allSet = true;
 			for (const [fieldName, fieldDef] of Object.entries(entry.fields)) {
+				if (!fieldDef.env) continue;
 				const val = process.env[fieldDef.env];
 				if (val !== void 0 && val !== "") values[fieldName] = val;
 				else allSet = false;

package/dist/registry/resource-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-registry.js","names":[],"sources":["../../src/registry/resource-registry.ts"],"sourcesContent":["/**\n * Resource Registry\n *\n * Central registry that tracks all resource requirements across all plugins.\n * Provides visibility into Databricks resources needed by the application\n * and handles deduplication when multiple plugins require the same resource\n * (dedup key: type + resourceKey).\n *\n * Use `new ResourceRegistry()` for instance-scoped usage (e.g. createApp).\n * getInstance() / resetInstance() remain for backward compatibility in tests.\n */\n\nimport type { BasePluginConfig, PluginConstructor, PluginData } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { getPluginManifest } from \"./manifest-loader\";\nimport type {\n  ResourceEntry,\n  ResourcePermission,\n  ResourceRequirement,\n  ValidationResult,\n} from \"./types\";\nimport { PERMISSION_HIERARCHY_BY_TYPE, type ResourceType } from \"./types\";\n\nconst logger = createLogger(\"resource-registry\");\n\n/**\n * Dedup key for registry: type + resourceKey (machine-stable).\n * alias is for UI/display only.\n */\nfunction getDedupKey(type: string, resourceKey: string): string {\n  return `${type}:${resourceKey}`;\n}\n\n/**\n * Returns the most permissive permission for a given resource type.\n * Uses per-type hierarchy; unknown permissions are treated as least permissive.\n */\nfunction getMostPermissivePermission(\n  resourceType: ResourceType,\n  p1: ResourcePermission,\n  p2: ResourcePermission,\n): ResourcePermission {\n  const hierarchy = PERMISSION_HIERARCHY_BY_TYPE[resourceType as ResourceType];\n  const index1 = hierarchy?.indexOf(p1) ?? -1;\n  const index2 = hierarchy?.indexOf(p2) ?? -1;\n  return index1 > index2 ? p1 : p2;\n}\n\n/**\n * Central registry for tracking plugin resource requirements.\n * Deduplication uses type + resourceKey (machine-stable); alias is for display only.\n */\nexport class ResourceRegistry {\n  private resources: Map<string, ResourceEntry> = new Map();\n\n  /**\n   * Registers a resource requirement for a plugin.\n   * If a resource with the same type+resourceKey already exists, merges them:\n   * - Combines plugin names (comma-separated)\n   * - Uses the most permissive permission (per-type hierarchy)\n   * - Marks as required if any plugin requires it\n   * - Combines descriptions if they differ\n   * - Merges fields; warns when same field name uses different env vars\n   *\n   * @param plugin - Name of the plugin registering the resource\n   * @param resource - Resource requirement specification\n   */\n  public register(plugin: string, resource: ResourceRequirement): void {\n    const key = getDedupKey(resource.type, resource.resourceKey);\n    const existing = this.resources.get(key);\n\n    if (existing) {\n      // Merge with existing resource\n      const merged = this.mergeResources(existing, plugin, resource);\n      this.resources.set(key, merged);\n    } else {\n      // Create new resource entry with permission source tracking\n      const entry: ResourceEntry = {\n        ...resource,\n        plugin,\n        resolved: false,\n        permissionSources: { [plugin]: resource.permission },\n      };\n      this.resources.set(key, entry);\n    }\n  }\n\n  /**\n   * Collects and registers resource requirements from an array of plugins.\n   * For each plugin, loads its manifest (required) and runtime resource requirements.\n   *\n   * @param rawPlugins - Array of plugin data entries from createApp configuration\n   * @throws {ConfigurationError} If any plugin is missing a manifest or manifest is invalid\n   */\n  public collectResources(\n    rawPlugins: PluginData<PluginConstructor, unknown, string>[],\n  ): void {\n    for (const pluginData of rawPlugins) {\n      if (!pluginData?.plugin) continue;\n\n      const pluginName = pluginData.name;\n      const manifest = getPluginManifest(pluginData.plugin);\n\n      // Register required resources\n      for (const resource of manifest.resources.required) {\n        this.register(pluginName, { ...resource, required: true });\n      }\n\n      // Register optional resources\n      for (const resource of manifest.resources.optional || []) {\n        this.register(pluginName, { ...resource, required: false });\n      }\n\n      // Check for runtime resource requirements\n      if (typeof pluginData.plugin.getResourceRequirements === \"function\") {\n        const runtimeResources = pluginData.plugin.getResourceRequirements(\n          pluginData.config as BasePluginConfig,\n        );\n        for (const resource of runtimeResources) {\n          this.register(pluginName, resource as ResourceRequirement);\n        }\n      }\n\n      logger.debug(\n        \"Collected resources from plugin %s: %d total\",\n        pluginName,\n        this.getByPlugin(pluginName).length,\n      );\n    }\n  }\n\n  /**\n   * Merges a new resource requirement with an existing entry.\n   * Applies intelligent merging logic for conflicting properties.\n   */\n  private mergeResources(\n    existing: ResourceEntry,\n    newPlugin: string,\n    newResource: ResourceRequirement,\n  ): ResourceEntry {\n    // Combine plugin names if not already included\n    const plugins = existing.plugin.split(\", \");\n    if (!plugins.includes(newPlugin)) {\n      plugins.push(newPlugin);\n    }\n\n    // Track per-plugin permission sources\n    const permissionSources: Record<string, ResourcePermission> = {\n      ...(existing.permissionSources ?? {}),\n      [newPlugin]: newResource.permission,\n    };\n\n    // Use the most permissive permission for this resource type; warn when escalating\n    const permission = getMostPermissivePermission(\n      existing.type as ResourceType,\n      existing.permission,\n      newResource.permission,\n    );\n\n    if (permission !== existing.permission) {\n      logger.warn(\n        'Resource %s:%s permission escalated from \"%s\" to \"%s\" due to plugin \"%s\" ' +\n          \"(previously requested by: %s). Review plugin permissions to ensure least-privilege.\",\n        existing.type,\n        existing.resourceKey,\n        existing.permission,\n        permission,\n        newPlugin,\n        existing.plugin,\n      );\n    }\n\n    // Mark as required if any plugin requires it\n    const required = existing.required || newResource.required;\n\n    // Combine descriptions if they differ\n    let description = existing.description;\n    if (\n      newResource.description &&\n      newResource.description !== existing.description\n    ) {\n      if (!existing.description.includes(newResource.description)) {\n        description = `${existing.description}; ${newResource.description}`;\n      }\n    }\n\n    // Merge fields: union of field names; warn when same field name uses different env\n    const fields = { ...(existing.fields ?? {}) };\n    for (const [fieldName, newField] of Object.entries(\n      newResource.fields ?? {},\n    )) {\n      const existingField = fields[fieldName];\n      if (existingField) {\n        if (existingField.env !== newField.env) {\n          logger.warn(\n            'Resource %s:%s field \"%s\": conflicting env vars \"%s\" (from %s) vs \"%s\" (from %s). Using first.',\n            existing.type,\n            existing.resourceKey,\n            fieldName,\n            existingField.env,\n            existing.plugin,\n            newField.env,\n            newPlugin,\n          );\n        }\n        // keep existing\n      } else {\n        fields[fieldName] = newField;\n      }\n    }\n\n    return {\n      ...existing,\n      plugin: plugins.join(\", \"),\n      permission,\n      permissionSources,\n      required,\n      description,\n      fields,\n    };\n  }\n\n  /**\n   * Retrieves all registered resources.\n   * Returns a copy of the array to prevent external mutations.\n   *\n   * @returns Array of all registered resource entries\n   */\n  public getAll(): ResourceEntry[] {\n    return Array.from(this.resources.values());\n  }\n\n  /**\n   * Gets a specific resource by type and resourceKey (dedup key).\n   *\n   * @param type - Resource type\n   * @param resourceKey - Stable machine key (not alias; alias is for display only)\n   * @returns The resource entry if found, undefined otherwise\n   */\n  public get(type: string, resourceKey: string): ResourceEntry | undefined {\n    return this.resources.get(getDedupKey(type, resourceKey));\n  }\n\n  /**\n   * Clears all registered resources.\n   * Useful for testing or when rebuilding the registry.\n   */\n  public clear(): void {\n    this.resources.clear();\n  }\n\n  /**\n   * Returns the number of registered resources.\n   */\n  public size(): number {\n    return this.resources.size;\n  }\n\n  /**\n   * Gets all resources required by a specific plugin.\n   *\n   * @param pluginName - Name of the plugin\n   * @returns Array of resources where the plugin is listed as a requester\n   */\n  public getByPlugin(pluginName: string): ResourceEntry[] {\n    return this.getAll().filter((entry) =>\n      entry.plugin.split(\", \").includes(pluginName),\n    );\n  }\n\n  /**\n   * Gets all required resources (where required=true).\n   *\n   * @returns Array of required resource entries\n   */\n  public getRequired(): ResourceEntry[] {\n    return this.getAll().filter((entry) => entry.required);\n  }\n\n  /**\n   * Gets all optional resources (where required=false).\n   *\n   * @returns Array of optional resource entries\n   */\n  public getOptional(): ResourceEntry[] {\n    return this.getAll().filter((entry) => !entry.required);\n  }\n\n  /**\n   * Validates all registered resources against the environment.\n   *\n   * Checks each resource's field environment variables to determine if it's resolved.\n   * Updates the `resolved` and `values` fields on each resource entry.\n   *\n   * Only required resources affect the `valid` status - optional resources\n   * are checked but don't cause validation failure.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   *\n   * @example\n   * ```typescript\n   * const registry = ResourceRegistry.getInstance();\n   * const result = registry.validate();\n   *\n   * if (!result.valid) {\n   *   console.error(\"Missing resources:\", result.missing.map(r => Object.values(r.fields).map(f => f.env)));\n   * }\n   * ```\n   */\n  public validate(): ValidationResult {\n    const missing: ResourceEntry[] = [];\n\n    for (const entry of this.resources.values()) {\n      const values: Record<string, string> = {};\n      let allSet = true;\n      for (const [fieldName, fieldDef] of Object.entries(entry.fields)) {\n        const val = process.env[fieldDef.env];\n        if (val !== undefined && val !== \"\") {\n          values[fieldName] = val;\n        } else {\n          allSet = false;\n        }\n      }\n      if (allSet) {\n        entry.resolved = true;\n        entry.values = values;\n        logger.debug(\n          \"Resource %s:%s resolved from fields\",\n          entry.type,\n          entry.alias,\n        );\n      } else {\n        entry.resolved = false;\n        entry.values = Object.keys(values).length > 0 ? values : undefined;\n        if (entry.required) {\n          missing.push(entry);\n          logger.debug(\n            \"Required resource %s:%s missing (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        } else {\n          logger.debug(\n            \"Optional resource %s:%s not configured (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        }\n      }\n    }\n\n    return {\n      valid: missing.length === 0,\n      missing,\n      all: this.getAll(),\n    };\n  }\n\n  /**\n   * Validates all registered resources and enforces the result.\n   *\n   * - In production: throws a {@link ConfigurationError} if any required resources are missing.\n   * - In development (`NODE_ENV=development`): logs a warning but continues, unless\n   *   `APPKIT_STRICT_VALIDATION=true` is set, in which case throws like production.\n   * - When all resources are valid: logs a debug message with the count.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   * @throws {ConfigurationError} In production when required resources are missing, or in dev when APPKIT_STRICT_VALIDATION=true\n   */\n  public enforceValidation(): ValidationResult {\n    const validation = this.validate();\n    const isDevelopment = process.env.NODE_ENV === \"development\";\n    const strictValidation =\n      process.env.APPKIT_STRICT_VALIDATION === \"true\" ||\n      process.env.APPKIT_STRICT_VALIDATION === \"1\";\n\n    if (!validation.valid) {\n      const errorMessage = ResourceRegistry.formatMissingResources(\n        validation.missing,\n      );\n\n      const shouldThrow = !isDevelopment || strictValidation;\n\n      if (shouldThrow) {\n        throw new ConfigurationError(errorMessage, {\n          context: {\n            missingResources: validation.missing.map((r) => ({\n              type: r.type,\n              alias: r.alias,\n              plugin: r.plugin,\n              envVars: Object.values(r.fields).map((f) => f.env),\n            })),\n          },\n        });\n      }\n\n      // Dev mode without strict: use a visually prominent box so the warning can't be missed\n      const banner = ResourceRegistry.formatDevWarningBanner(\n        validation.missing,\n      );\n      logger.warn(\"\\n%s\", banner);\n    } else if (this.size() > 0) {\n      logger.debug(\"All %d resources validated successfully\", this.size());\n    }\n\n    return validation;\n  }\n\n  /**\n   * Formats missing resources into a human-readable error message.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted error message string\n   */\n  public static formatMissingResources(missing: ResourceEntry[]): string {\n    if (missing.length === 0) {\n      return \"No missing resources\";\n    }\n\n    const lines = missing.map((entry) => {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      const envHint = ` (set ${envVars.join(\", \")})`;\n      return `  - ${entry.type}:${entry.alias} [${entry.plugin}]${envHint}`;\n    });\n\n    return `Missing required resources:\\n${lines.join(\"\\n\")}`;\n  }\n\n  /**\n   * Formats a highly visible warning banner for dev-mode missing resources.\n   * Uses box drawing to ensure the message is impossible to miss in scrolling logs.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted banner string\n   */\n  public static formatDevWarningBanner(missing: ResourceEntry[]): string {\n    const contentLines: string[] = [\n      \"MISSING REQUIRED RESOURCES (dev mode — would fail in production)\",\n      \"\",\n    ];\n\n    for (const entry of missing) {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      contentLines.push(\n        `  ${entry.type}:${entry.alias}  (plugin: ${entry.plugin})`,\n      );\n      contentLines.push(`    Set: ${envVars.join(\", \")}`);\n    }\n\n    contentLines.push(\"\");\n    contentLines.push(\n      \"Add these to your .env file or environment to suppress this warning.\",\n    );\n\n    const maxLen = Math.max(...contentLines.map((l) => l.length));\n    const border = \"=\".repeat(maxLen + 4);\n\n    const boxed = contentLines.map((line) => `| ${line.padEnd(maxLen)} |`);\n\n    return [border, ...boxed, border].join(\"\\n\");\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"resource-registry.js","names":[],"sources":["../../src/registry/resource-registry.ts"],"sourcesContent":["/**\n * Resource Registry\n *\n * Central registry that tracks all resource requirements across all plugins.\n * Provides visibility into Databricks resources needed by the application\n * and handles deduplication when multiple plugins require the same resource\n * (dedup key: type + resourceKey).\n *\n * Use `new ResourceRegistry()` for instance-scoped usage (e.g. createApp).\n * getInstance() / resetInstance() remain for backward compatibility in tests.\n */\n\nimport type { BasePluginConfig, PluginConstructor, PluginData } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { getPluginManifest } from \"./manifest-loader\";\nimport type {\n  ResourceEntry,\n  ResourcePermission,\n  ResourceRequirement,\n  ValidationResult,\n} from \"./types\";\nimport { PERMISSION_HIERARCHY_BY_TYPE, type ResourceType } from \"./types\";\n\nconst logger = createLogger(\"resource-registry\");\n\n/**\n * Dedup key for registry: type + resourceKey (machine-stable).\n * alias is for UI/display only.\n */\nfunction getDedupKey(type: string, resourceKey: string): string {\n  return `${type}:${resourceKey}`;\n}\n\n/**\n * Returns the most permissive permission for a given resource type.\n * Uses per-type hierarchy; unknown permissions are treated as least permissive.\n */\nfunction getMostPermissivePermission(\n  resourceType: ResourceType,\n  p1: ResourcePermission,\n  p2: ResourcePermission,\n): ResourcePermission {\n  const hierarchy = PERMISSION_HIERARCHY_BY_TYPE[resourceType as ResourceType];\n  const index1 = hierarchy?.indexOf(p1) ?? -1;\n  const index2 = hierarchy?.indexOf(p2) ?? -1;\n  return index1 > index2 ? p1 : p2;\n}\n\n/**\n * Central registry for tracking plugin resource requirements.\n * Deduplication uses type + resourceKey (machine-stable); alias is for display only.\n */\nexport class ResourceRegistry {\n  private resources: Map<string, ResourceEntry> = new Map();\n\n  /**\n   * Registers a resource requirement for a plugin.\n   * If a resource with the same type+resourceKey already exists, merges them:\n   * - Combines plugin names (comma-separated)\n   * - Uses the most permissive permission (per-type hierarchy)\n   * - Marks as required if any plugin requires it\n   * - Combines descriptions if they differ\n   * - Merges fields; warns when same field name uses different env vars\n   *\n   * @param plugin - Name of the plugin registering the resource\n   * @param resource - Resource requirement specification\n   */\n  public register(plugin: string, resource: ResourceRequirement): void {\n    const key = getDedupKey(resource.type, resource.resourceKey);\n    const existing = this.resources.get(key);\n\n    if (existing) {\n      // Merge with existing resource\n      const merged = this.mergeResources(existing, plugin, resource);\n      this.resources.set(key, merged);\n    } else {\n      // Create new resource entry with permission source tracking\n      const entry: ResourceEntry = {\n        ...resource,\n        plugin,\n        resolved: false,\n        permissionSources: { [plugin]: resource.permission },\n      };\n      this.resources.set(key, entry);\n    }\n  }\n\n  /**\n   * Collects and registers resource requirements from an array of plugins.\n   * For each plugin, loads its manifest (required) and runtime resource requirements.\n   *\n   * @param rawPlugins - Array of plugin data entries from createApp configuration\n   * @throws {ConfigurationError} If any plugin is missing a manifest or manifest is invalid\n   */\n  public collectResources(\n    rawPlugins: PluginData<PluginConstructor, unknown, string>[],\n  ): void {\n    for (const pluginData of rawPlugins) {\n      if (!pluginData?.plugin) continue;\n\n      const pluginName = pluginData.name;\n      const manifest = getPluginManifest(pluginData.plugin);\n\n      // Register required resources\n      for (const resource of manifest.resources.required) {\n        this.register(pluginName, { ...resource, required: true });\n      }\n\n      // Register optional resources\n      for (const resource of manifest.resources.optional || []) {\n        this.register(pluginName, { ...resource, required: false });\n      }\n\n      // Check for runtime resource requirements\n      if (typeof pluginData.plugin.getResourceRequirements === \"function\") {\n        const runtimeResources = pluginData.plugin.getResourceRequirements(\n          pluginData.config as BasePluginConfig,\n        );\n        for (const resource of runtimeResources) {\n          this.register(pluginName, resource as ResourceRequirement);\n        }\n      }\n\n      logger.debug(\n        \"Collected resources from plugin %s: %d total\",\n        pluginName,\n        this.getByPlugin(pluginName).length,\n      );\n    }\n  }\n\n  /**\n   * Merges a new resource requirement with an existing entry.\n   * Applies intelligent merging logic for conflicting properties.\n   */\n  private mergeResources(\n    existing: ResourceEntry,\n    newPlugin: string,\n    newResource: ResourceRequirement,\n  ): ResourceEntry {\n    // Combine plugin names if not already included\n    const plugins = existing.plugin.split(\", \");\n    if (!plugins.includes(newPlugin)) {\n      plugins.push(newPlugin);\n    }\n\n    // Track per-plugin permission sources\n    const permissionSources: Record<string, ResourcePermission> = {\n      ...(existing.permissionSources ?? {}),\n      [newPlugin]: newResource.permission,\n    };\n\n    // Use the most permissive permission for this resource type; warn when escalating\n    const permission = getMostPermissivePermission(\n      existing.type as ResourceType,\n      existing.permission,\n      newResource.permission,\n    );\n\n    if (permission !== existing.permission) {\n      logger.warn(\n        'Resource %s:%s permission escalated from \"%s\" to \"%s\" due to plugin \"%s\" ' +\n          \"(previously requested by: %s). Review plugin permissions to ensure least-privilege.\",\n        existing.type,\n        existing.resourceKey,\n        existing.permission,\n        permission,\n        newPlugin,\n        existing.plugin,\n      );\n    }\n\n    // Mark as required if any plugin requires it\n    const required = existing.required || newResource.required;\n\n    // Combine descriptions if they differ\n    let description = existing.description;\n    if (\n      newResource.description &&\n      newResource.description !== existing.description\n    ) {\n      if (!existing.description.includes(newResource.description)) {\n        description = `${existing.description}; ${newResource.description}`;\n      }\n    }\n\n    // Merge fields: union of field names; warn when same field name uses different env\n    const fields = { ...(existing.fields ?? {}) };\n    for (const [fieldName, newField] of Object.entries(\n      newResource.fields ?? {},\n    )) {\n      const existingField = fields[fieldName];\n      if (existingField) {\n        if (existingField.env !== newField.env) {\n          logger.warn(\n            'Resource %s:%s field \"%s\": conflicting env vars \"%s\" (from %s) vs \"%s\" (from %s). Using first.',\n            existing.type,\n            existing.resourceKey,\n            fieldName,\n            existingField.env,\n            existing.plugin,\n            newField.env,\n            newPlugin,\n          );\n        }\n        // keep existing\n      } else {\n        fields[fieldName] = newField;\n      }\n    }\n\n    return {\n      ...existing,\n      plugin: plugins.join(\", \"),\n      permission,\n      permissionSources,\n      required,\n      description,\n      fields,\n    };\n  }\n\n  /**\n   * Retrieves all registered resources.\n   * Returns a copy of the array to prevent external mutations.\n   *\n   * @returns Array of all registered resource entries\n   */\n  public getAll(): ResourceEntry[] {\n    return Array.from(this.resources.values());\n  }\n\n  /**\n   * Gets a specific resource by type and resourceKey (dedup key).\n   *\n   * @param type - Resource type\n   * @param resourceKey - Stable machine key (not alias; alias is for display only)\n   * @returns The resource entry if found, undefined otherwise\n   */\n  public get(type: string, resourceKey: string): ResourceEntry | undefined {\n    return this.resources.get(getDedupKey(type, resourceKey));\n  }\n\n  /**\n   * Clears all registered resources.\n   * Useful for testing or when rebuilding the registry.\n   */\n  public clear(): void {\n    this.resources.clear();\n  }\n\n  /**\n   * Returns the number of registered resources.\n   */\n  public size(): number {\n    return this.resources.size;\n  }\n\n  /**\n   * Gets all resources required by a specific plugin.\n   *\n   * @param pluginName - Name of the plugin\n   * @returns Array of resources where the plugin is listed as a requester\n   */\n  public getByPlugin(pluginName: string): ResourceEntry[] {\n    return this.getAll().filter((entry) =>\n      entry.plugin.split(\", \").includes(pluginName),\n    );\n  }\n\n  /**\n   * Gets all required resources (where required=true).\n   *\n   * @returns Array of required resource entries\n   */\n  public getRequired(): ResourceEntry[] {\n    return this.getAll().filter((entry) => entry.required);\n  }\n\n  /**\n   * Gets all optional resources (where required=false).\n   *\n   * @returns Array of optional resource entries\n   */\n  public getOptional(): ResourceEntry[] {\n    return this.getAll().filter((entry) => !entry.required);\n  }\n\n  /**\n   * Validates all registered resources against the environment.\n   *\n   * Checks each resource's field environment variables to determine if it's resolved.\n   * Updates the `resolved` and `values` fields on each resource entry.\n   *\n   * Only required resources affect the `valid` status - optional resources\n   * are checked but don't cause validation failure.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   *\n   * @example\n   * ```typescript\n   * const registry = ResourceRegistry.getInstance();\n   * const result = registry.validate();\n   *\n   * if (!result.valid) {\n   *   console.error(\"Missing resources:\", result.missing.map(r => Object.values(r.fields).map(f => f.env)));\n   * }\n   * ```\n   */\n  public validate(): ValidationResult {\n    const missing: ResourceEntry[] = [];\n\n    for (const entry of this.resources.values()) {\n      const values: Record<string, string> = {};\n      let allSet = true;\n      for (const [fieldName, fieldDef] of Object.entries(entry.fields)) {\n        if (!fieldDef.env) continue;\n        const val = process.env[fieldDef.env];\n        if (val !== undefined && val !== \"\") {\n          values[fieldName] = val;\n        } else {\n          allSet = false;\n        }\n      }\n      if (allSet) {\n        entry.resolved = true;\n        entry.values = values;\n        logger.debug(\n          \"Resource %s:%s resolved from fields\",\n          entry.type,\n          entry.alias,\n        );\n      } else {\n        entry.resolved = false;\n        entry.values = Object.keys(values).length > 0 ? values : undefined;\n        if (entry.required) {\n          missing.push(entry);\n          logger.debug(\n            \"Required resource %s:%s missing (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        } else {\n          logger.debug(\n            \"Optional resource %s:%s not configured (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        }\n      }\n    }\n\n    return {\n      valid: missing.length === 0,\n      missing,\n      all: this.getAll(),\n    };\n  }\n\n  /**\n   * Validates all registered resources and enforces the result.\n   *\n   * - In production: throws a {@link ConfigurationError} if any required resources are missing.\n   * - In development (`NODE_ENV=development`): logs a warning but continues, unless\n   *   `APPKIT_STRICT_VALIDATION=true` is set, in which case throws like production.\n   * - When all resources are valid: logs a debug message with the count.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   * @throws {ConfigurationError} In production when required resources are missing, or in dev when APPKIT_STRICT_VALIDATION=true\n   */\n  public enforceValidation(): ValidationResult {\n    const validation = this.validate();\n    const isDevelopment = process.env.NODE_ENV === \"development\";\n    const strictValidation =\n      process.env.APPKIT_STRICT_VALIDATION === \"true\" ||\n      process.env.APPKIT_STRICT_VALIDATION === \"1\";\n\n    if (!validation.valid) {\n      const errorMessage = ResourceRegistry.formatMissingResources(\n        validation.missing,\n      );\n\n      const shouldThrow = !isDevelopment || strictValidation;\n\n      if (shouldThrow) {\n        throw new ConfigurationError(errorMessage, {\n          context: {\n            missingResources: validation.missing.map((r) => ({\n              type: r.type,\n              alias: r.alias,\n              plugin: r.plugin,\n              envVars: Object.values(r.fields).map((f) => f.env),\n            })),\n          },\n        });\n      }\n\n      // Dev mode without strict: use a visually prominent box so the warning can't be missed\n      const banner = ResourceRegistry.formatDevWarningBanner(\n        validation.missing,\n      );\n      logger.warn(\"\\n%s\", banner);\n    } else if (this.size() > 0) {\n      logger.debug(\"All %d resources validated successfully\", this.size());\n    }\n\n    return validation;\n  }\n\n  /**\n   * Formats missing resources into a human-readable error message.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted error message string\n   */\n  public static formatMissingResources(missing: ResourceEntry[]): string {\n    if (missing.length === 0) {\n      return \"No missing resources\";\n    }\n\n    const lines = missing.map((entry) => {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      const envHint = ` (set ${envVars.join(\", \")})`;\n      return `  - ${entry.type}:${entry.alias} [${entry.plugin}]${envHint}`;\n    });\n\n    return `Missing required resources:\\n${lines.join(\"\\n\")}`;\n  }\n\n  /**\n   * Formats a highly visible warning banner for dev-mode missing resources.\n   * Uses box drawing to ensure the message is impossible to miss in scrolling logs.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted banner string\n   */\n  public static formatDevWarningBanner(missing: ResourceEntry[]): string {\n    const contentLines: string[] = [\n      \"MISSING REQUIRED RESOURCES (dev mode — would fail in production)\",\n      \"\",\n    ];\n\n    for (const entry of missing) {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      contentLines.push(\n        `  ${entry.type}:${entry.alias}  (plugin: ${entry.plugin})`,\n      );\n      contentLines.push(`    Set: ${envVars.join(\", \")}`);\n    }\n\n    contentLines.push(\"\");\n    contentLines.push(\n      \"Add these to your .env file or environment to suppress this warning.\",\n    );\n\n    const maxLen = Math.max(...contentLines.map((l) => l.length));\n    const border = \"=\".repeat(maxLen + 4);\n\n    const boxed = contentLines.map((line) => `| ${line.padEnd(maxLen)} |`);\n\n    return [border, ...boxed, border].join(\"\\n\");\n  }\n}\n"],"mappings":"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"}

package/dist/registry/types.d.ts

@@ -8,9 +8,19 @@ import { JSONSchema7 } from "json-schema";
  */
 interface ResourceFieldEntry {
   /** Environment variable name for this field */
-  env: string;
+  env?: string;
   /** Human-readable description for this field */
   description?: string;
+  /** When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation. */
+  bundleIgnore?: boolean;
+  /** Example values showing the expected format for this field */
+  examples?: string[];
+  /** When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time. */
+  localOnly?: boolean;
+  /** Static value for this field. Used when no prompted or resolved value exists. */
+  value?: string;
+  /** Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow. */
+  resolve?: string;
 }
 /**
  * Declares a resource requirement for a plugin.

package/dist/registry/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/registry/types.ts"],"mappings":";;;;;;;;UA0DiB,kBAAA;EA+BD;EA7Bd,GAAA;EAWM;EATN,WAAA;AAAA;;;;;UAOe,mBAAA;EAoBQ;EAlBvB,IAAA,EAAM,YAAA;EAqBE;EAlBR,KAAA;EAyBe;EAtBf,WAAA;;EAGA,WAAA;EAkCmC;EA/BnC,UAAA,EAAY,kBAAA;EAgByB;;;;EAVrC,MAAA,EAAQ,MAAA,SAAe,kBAAA;EAevB;EAZA,QAAA;AAAA;;;;;UAOe,aAAA,SAAsB,mBAAA;EAqBtB;EAnBf,MAAA;;EAGA,QAAA;EAkBA;EAfA,MAAA,GAAS,MAAA;EAkBA;;;;;EAXT,iBAAA,GAAoB,MAAA,SAAe,kBAAA;AAAA;;;;UAMpB,gBAAA;EAyBc;EAvB7B,KAAA;EAyBM;EAtBN,OAAA,EAAS,aAAA;EAmCG;EAhCZ,GAAA,EAAK,aAAA;AAAA;;;;;;;KAWK,YAAA,GAAe,WAAA;;;;;UAMV,cAAA;EAkBH;EAhBZ,IAAA,EAAM,KAAA;EAuBN;EApBA,WAAA;EAqBU;EAlBV,WAAA;EA6BA;;;EAxBA,SAAA;IA4BA,kEA1BE,QAAA,EAAU,IAAA,CAAK,mBAAA,iBA0BV;IAvBL,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;;;;;EAOjB,MAAA;IACE,MAAA,EAAQ,YAAA;EAAA;;;;EAMV,MAAA;;;;EAKA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/registry/types.ts"],"mappings":";;;;;;;;UA0DiB,kBAAA;EAqBA;EAnBf,GAAA;;EAEA,WAAA;EA+BY;EA7BZ,YAAA;EAmCQ;EAjCR,QAAA;EAiCc;EA/Bd,SAAA;EAaM;EAXN,KAAA;EAiBA;EAfA,OAAA;AAAA;;;;;UAOe,mBAAA;EAuBP;EArBR,IAAA,EAAM,YAAA;EA4BS;EAzBf,KAAA;;EAGA,WAAA;EAqCmC;EAlCnC,WAAA;EAmBqC;EAhBrC,UAAA,EAAY,kBAAA;EAgB4C;;;;EAVxD,MAAA,EAAQ,MAAA,SAAe,kBAAA;EAkBd;EAfT,QAAA;AAAA;;;;AA4BF;UArBiB,aAAA,SAAsB,mBAAA;;EAErC,MAAA;EAqBA;EAlBA,QAAA;EAqBS;EAlBT,MAAA,GAAS,MAAA;EAqBJ;;;AAWP;;EAzBE,iBAAA,GAAoB,MAAA,SAAe,kBAAA;AAAA;;AA+BrC;;UAzBiB,gBAAA;EA2BT;EAzBN,KAAA;EAsCY;EAnCZ,OAAA,EAAS,aAAA;EAsCG;EAnCZ,GAAA,EAAK,aAAA;AAAA;;;;;;;KAWK,YAAA,GAAe,WAAA;;;;;UAMV,cAAA;EAyBf;EAvBA,IAAA,EAAM,KAAA;EAwBI;EArBV,WAAA;EAgCA;EA7BA,WAAA;EA+BA;;;EA1BA,SAAA;IA4BO,kEA1BL,QAAA,EAAU,IAAA,CAAK,mBAAA;IAGf,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;;;;;EAOjB,MAAA;IACE,MAAA,EAAQ,YAAA;EAAA;;;;EAMV,MAAA;;;;EAKA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;AAAA"}

package/dist/registry/types.generated.d.ts

@@ -10,6 +10,7 @@ declare enum ResourceType {
   UC_FUNCTION = "uc_function",
   UC_CONNECTION = "uc_connection",
   DATABASE = "database",
+  POSTGRES = "postgres",
   GENIE_SPACE = "genie_space",
   EXPERIMENT = "experiment",
   APP = "app"
@@ -32,6 +33,8 @@ type UcFunctionPermission = "EXECUTE";
 type UcConnectionPermission = "USE_CONNECTION";
 /** Permissions for DATABASE resources */
 type DatabasePermission = "CAN_CONNECT_AND_CREATE";
+/** Permissions for POSTGRES resources */
+type PostgresPermission = "CAN_CONNECT_AND_CREATE";
 /** Permissions for GENIE_SPACE resources */
 type GenieSpacePermission = "CAN_VIEW" | "CAN_RUN" | "CAN_EDIT" | "CAN_MANAGE";
 /** Permissions for EXPERIMENT resources */
@@ -39,7 +42,7 @@ type ExperimentPermission = "CAN_READ" | "CAN_EDIT" | "CAN_MANAGE";
 /** Permissions for APP resources */
 type AppPermission = "CAN_USE";
 /** Union of all possible permission levels across all resource types. */
-type ResourcePermission = SecretPermission | JobPermission | SqlWarehousePermission | ServingEndpointPermission | VolumePermission | VectorSearchIndexPermission | UcFunctionPermission | UcConnectionPermission | DatabasePermission | GenieSpacePermission | ExperimentPermission | AppPermission;
+type ResourcePermission = SecretPermission | JobPermission | SqlWarehousePermission | ServingEndpointPermission | VolumePermission | VectorSearchIndexPermission | UcFunctionPermission | UcConnectionPermission | DatabasePermission | PostgresPermission | GenieSpacePermission | ExperimentPermission | AppPermission;
 //#endregion
 export { AppPermission, DatabasePermission, ExperimentPermission, GenieSpacePermission, JobPermission, ResourcePermission, ResourceType, SecretPermission, ServingEndpointPermission, SqlWarehousePermission, UcConnectionPermission, UcFunctionPermission, VectorSearchIndexPermission, VolumePermission };
 //# sourceMappingURL=types.generated.d.ts.map

package/dist/registry/types.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.generated.d.ts","names":[],"sources":["../../src/registry/types.generated.ts"],"mappings":";;aAIY,YAAA;EACV,MAAA;EACA,GAAA;EACA,aAAA;EACA,gBAAA;EACA,MAAA;EACA,mBAAA;EACA,WAAA;EACA,aAAA;EACA,QAAA;EACA,WAAA;EACA,UAAA;EACA,GAAA;AAAA;;KAOU,gBAAA;;KAGA,aAAA;AAHZ;AAAA,KAMY,sBAAA;;KAGA,yBAAA;;KAGA,gBAAA;;KAGA,2BAAA;;KAGA,oBAAA;AAZZ;AAAA,KAeY,sBAAA;;KAGA,kBAAA;;KAGA,oBAAA;;KAGA,oBAAA;;KAGA,aAAA;AArBZ;AAAA,KAwBY,kBAAA,GACR,gBAAA,GACA,aAAA,GACA,sBAAA,GACA,yBAAA,GACA,gBAAA,GACA,2BAAA,GACA,oBAAA,GACA,sBAAA,GACA,kBAAA,GACA,oBAAA,GACA,oBAAA,GACA,aAAA"}
+{"version":3,"file":"types.generated.d.ts","names":[],"sources":["../../src/registry/types.generated.ts"],"mappings":";;aAIY,YAAA;EACV,MAAA;EACA,GAAA;EACA,aAAA;EACA,gBAAA;EACA,MAAA;EACA,mBAAA;EACA,WAAA;EACA,aAAA;EACA,QAAA;EACA,QAAA;EACA,WAAA;EACA,UAAA;EACA,GAAA;AAAA;;KAOU,gBAAA;;KAGA,aAAA;AAHZ;AAAA,KAMY,sBAAA;;KAGA,yBAAA;;KAGA,gBAAA;;KAGA,2BAAA;;KAGA,oBAAA;AAZZ;AAAA,KAeY,sBAAA;;KAGA,kBAAA;;KAGA,kBAAA;;KAGA,oBAAA;;KAGA,oBAAA;AArBZ;AAAA,KAwBY,aAAA;;KAGA,kBAAA,GACR,gBAAA,GACA,aAAA,GACA,sBAAA,GACA,yBAAA,GACA,gBAAA,GACA,2BAAA,GACA,oBAAA,GACA,sBAAA,GACA,kBAAA,GACA,kBAAA,GACA,oBAAA,GACA,oBAAA,GACA,aAAA"}

package/dist/registry/types.generated.js

@@ -10,6 +10,7 @@ let ResourceType = /* @__PURE__ */ function(ResourceType) {
 	ResourceType["UC_FUNCTION"] = "uc_function";
 	ResourceType["UC_CONNECTION"] = "uc_connection";
 	ResourceType["DATABASE"] = "database";
+	ResourceType["POSTGRES"] = "postgres";
 	ResourceType["GENIE_SPACE"] = "genie_space";
 	ResourceType["EXPERIMENT"] = "experiment";
 	ResourceType["APP"] = "app";
@@ -38,6 +39,7 @@ const PERMISSION_HIERARCHY_BY_TYPE = {
 	[ResourceType.UC_FUNCTION]: ["EXECUTE"],
 	[ResourceType.UC_CONNECTION]: ["USE_CONNECTION"],
 	[ResourceType.DATABASE]: ["CAN_CONNECT_AND_CREATE"],
+	[ResourceType.POSTGRES]: ["CAN_CONNECT_AND_CREATE"],
 	[ResourceType.GENIE_SPACE]: [
 		"CAN_VIEW",
 		"CAN_RUN",

package/dist/registry/types.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.generated.js","names":[],"sources":["../../src/registry/types.generated.ts"],"sourcesContent":["// AUTO-GENERATED from packages/shared/src/schemas/plugin-manifest.schema.json\n// Do not edit. Run: pnpm exec tsx tools/generate-registry-types.ts\n\n/** Resource types from schema $defs.resourceType.enum */\nexport enum ResourceType {\n  SECRET = \"secret\",\n  JOB = \"job\",\n  SQL_WAREHOUSE = \"sql_warehouse\",\n  SERVING_ENDPOINT = \"serving_endpoint\",\n  VOLUME = \"volume\",\n  VECTOR_SEARCH_INDEX = \"vector_search_index\",\n  UC_FUNCTION = \"uc_function\",\n  UC_CONNECTION = \"uc_connection\",\n  DATABASE = \"database\",\n  GENIE_SPACE = \"genie_space\",\n  EXPERIMENT = \"experiment\",\n  APP = \"app\",\n}\n\n// ============================================================================\n// Permissions per resource type (from schema permission $defs)\n// ============================================================================\n/** Permissions for SECRET resources */\nexport type SecretPermission = \"READ\" | \"WRITE\" | \"MANAGE\";\n\n/** Permissions for JOB resources */\nexport type JobPermission = \"CAN_VIEW\" | \"CAN_MANAGE_RUN\" | \"CAN_MANAGE\";\n\n/** Permissions for SQL_WAREHOUSE resources */\nexport type SqlWarehousePermission = \"CAN_USE\" | \"CAN_MANAGE\";\n\n/** Permissions for SERVING_ENDPOINT resources */\nexport type ServingEndpointPermission = \"CAN_VIEW\" | \"CAN_QUERY\" | \"CAN_MANAGE\";\n\n/** Permissions for VOLUME resources */\nexport type VolumePermission = \"READ_VOLUME\" | \"WRITE_VOLUME\";\n\n/** Permissions for VECTOR_SEARCH_INDEX resources */\nexport type VectorSearchIndexPermission = \"SELECT\";\n\n/** Permissions for UC_FUNCTION resources */\nexport type UcFunctionPermission = \"EXECUTE\";\n\n/** Permissions for UC_CONNECTION resources */\nexport type UcConnectionPermission = \"USE_CONNECTION\";\n\n/** Permissions for DATABASE resources */\nexport type DatabasePermission = \"CAN_CONNECT_AND_CREATE\";\n\n/** Permissions for GENIE_SPACE resources */\nexport type GenieSpacePermission = \"CAN_VIEW\" | \"CAN_RUN\" | \"CAN_EDIT\" | \"CAN_MANAGE\";\n\n/** Permissions for EXPERIMENT resources */\nexport type ExperimentPermission = \"CAN_READ\" | \"CAN_EDIT\" | \"CAN_MANAGE\";\n\n/** Permissions for APP resources */\nexport type AppPermission = \"CAN_USE\";\n\n/** Union of all possible permission levels across all resource types. */\nexport type ResourcePermission =\n  | SecretPermission\n  | JobPermission\n  | SqlWarehousePermission\n  | ServingEndpointPermission\n  | VolumePermission\n  | VectorSearchIndexPermission\n  | UcFunctionPermission\n  | UcConnectionPermission\n  | DatabasePermission\n  | GenieSpacePermission\n  | ExperimentPermission\n  | AppPermission;\n\n/** Permission hierarchy per resource type (weakest to strongest). Schema enum order. */\nexport const PERMISSION_HIERARCHY_BY_TYPE: Record<ResourceType, readonly ResourcePermission[]> = {\n  [ResourceType.SECRET]: [\"READ\", \"WRITE\", \"MANAGE\"],\n  [ResourceType.JOB]: [\"CAN_VIEW\", \"CAN_MANAGE_RUN\", \"CAN_MANAGE\"],\n  [ResourceType.SQL_WAREHOUSE]: [\"CAN_USE\", \"CAN_MANAGE\"],\n  [ResourceType.SERVING_ENDPOINT]: [\"CAN_VIEW\", \"CAN_QUERY\", \"CAN_MANAGE\"],\n  [ResourceType.VOLUME]: [\"READ_VOLUME\", \"WRITE_VOLUME\"],\n  [ResourceType.VECTOR_SEARCH_INDEX]: [\"SELECT\"],\n  [ResourceType.UC_FUNCTION]: [\"EXECUTE\"],\n  [ResourceType.UC_CONNECTION]: [\"USE_CONNECTION\"],\n  [ResourceType.DATABASE]: [\"CAN_CONNECT_AND_CREATE\"],\n  [ResourceType.GENIE_SPACE]: [\"CAN_VIEW\", \"CAN_RUN\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.EXPERIMENT]: [\"CAN_READ\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.APP]: [\"CAN_USE\"],\n} as const;\n\n/** Set of valid permissions per type (for validation). */\nexport const PERMISSIONS_BY_TYPE: Record<ResourceType, readonly ResourcePermission[]> = PERMISSION_HIERARCHY_BY_TYPE;\n"],"mappings":";;AAIA,IAAY,sDAAL;AACL;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;AA0DF,MAAa,+BAAoF;EAC9F,aAAa,SAAS;EAAC;EAAQ;EAAS;EAAS;EACjD,aAAa,MAAM;EAAC;EAAY;EAAkB;EAAa;EAC/D,aAAa,gBAAgB,CAAC,WAAW,aAAa;EACtD,aAAa,mBAAmB;EAAC;EAAY;EAAa;EAAa;EACvE,aAAa,SAAS,CAAC,eAAe,eAAe;EACrD,aAAa,sBAAsB,CAAC,SAAS;EAC7C,aAAa,cAAc,CAAC,UAAU;EACtC,aAAa,gBAAgB,CAAC,iBAAiB;EAC/C,aAAa,WAAW,CAAC,yBAAyB;EAClD,aAAa,cAAc;EAAC;EAAY;EAAW;EAAY;EAAa;EAC5E,aAAa,aAAa;EAAC;EAAY;EAAY;EAAa;EAChE,aAAa,MAAM,CAAC,UAAU;CAChC;;AAGD,MAAa,sBAA2E"}
+{"version":3,"file":"types.generated.js","names":[],"sources":["../../src/registry/types.generated.ts"],"sourcesContent":["// AUTO-GENERATED from packages/shared/src/schemas/plugin-manifest.schema.json\n// Do not edit. Run: pnpm exec tsx tools/generate-registry-types.ts\n\n/** Resource types from schema $defs.resourceType.enum */\nexport enum ResourceType {\n  SECRET = \"secret\",\n  JOB = \"job\",\n  SQL_WAREHOUSE = \"sql_warehouse\",\n  SERVING_ENDPOINT = \"serving_endpoint\",\n  VOLUME = \"volume\",\n  VECTOR_SEARCH_INDEX = \"vector_search_index\",\n  UC_FUNCTION = \"uc_function\",\n  UC_CONNECTION = \"uc_connection\",\n  DATABASE = \"database\",\n  POSTGRES = \"postgres\",\n  GENIE_SPACE = \"genie_space\",\n  EXPERIMENT = \"experiment\",\n  APP = \"app\",\n}\n\n// ============================================================================\n// Permissions per resource type (from schema permission $defs)\n// ============================================================================\n/** Permissions for SECRET resources */\nexport type SecretPermission = \"READ\" | \"WRITE\" | \"MANAGE\";\n\n/** Permissions for JOB resources */\nexport type JobPermission = \"CAN_VIEW\" | \"CAN_MANAGE_RUN\" | \"CAN_MANAGE\";\n\n/** Permissions for SQL_WAREHOUSE resources */\nexport type SqlWarehousePermission = \"CAN_USE\" | \"CAN_MANAGE\";\n\n/** Permissions for SERVING_ENDPOINT resources */\nexport type ServingEndpointPermission = \"CAN_VIEW\" | \"CAN_QUERY\" | \"CAN_MANAGE\";\n\n/** Permissions for VOLUME resources */\nexport type VolumePermission = \"READ_VOLUME\" | \"WRITE_VOLUME\";\n\n/** Permissions for VECTOR_SEARCH_INDEX resources */\nexport type VectorSearchIndexPermission = \"SELECT\";\n\n/** Permissions for UC_FUNCTION resources */\nexport type UcFunctionPermission = \"EXECUTE\";\n\n/** Permissions for UC_CONNECTION resources */\nexport type UcConnectionPermission = \"USE_CONNECTION\";\n\n/** Permissions for DATABASE resources */\nexport type DatabasePermission = \"CAN_CONNECT_AND_CREATE\";\n\n/** Permissions for POSTGRES resources */\nexport type PostgresPermission = \"CAN_CONNECT_AND_CREATE\";\n\n/** Permissions for GENIE_SPACE resources */\nexport type GenieSpacePermission = \"CAN_VIEW\" | \"CAN_RUN\" | \"CAN_EDIT\" | \"CAN_MANAGE\";\n\n/** Permissions for EXPERIMENT resources */\nexport type ExperimentPermission = \"CAN_READ\" | \"CAN_EDIT\" | \"CAN_MANAGE\";\n\n/** Permissions for APP resources */\nexport type AppPermission = \"CAN_USE\";\n\n/** Union of all possible permission levels across all resource types. */\nexport type ResourcePermission =\n  | SecretPermission\n  | JobPermission\n  | SqlWarehousePermission\n  | ServingEndpointPermission\n  | VolumePermission\n  | VectorSearchIndexPermission\n  | UcFunctionPermission\n  | UcConnectionPermission\n  | DatabasePermission\n  | PostgresPermission\n  | GenieSpacePermission\n  | ExperimentPermission\n  | AppPermission;\n\n/** Permission hierarchy per resource type (weakest to strongest). Schema enum order. */\nexport const PERMISSION_HIERARCHY_BY_TYPE: Record<ResourceType, readonly ResourcePermission[]> = {\n  [ResourceType.SECRET]: [\"READ\", \"WRITE\", \"MANAGE\"],\n  [ResourceType.JOB]: [\"CAN_VIEW\", \"CAN_MANAGE_RUN\", \"CAN_MANAGE\"],\n  [ResourceType.SQL_WAREHOUSE]: [\"CAN_USE\", \"CAN_MANAGE\"],\n  [ResourceType.SERVING_ENDPOINT]: [\"CAN_VIEW\", \"CAN_QUERY\", \"CAN_MANAGE\"],\n  [ResourceType.VOLUME]: [\"READ_VOLUME\", \"WRITE_VOLUME\"],\n  [ResourceType.VECTOR_SEARCH_INDEX]: [\"SELECT\"],\n  [ResourceType.UC_FUNCTION]: [\"EXECUTE\"],\n  [ResourceType.UC_CONNECTION]: [\"USE_CONNECTION\"],\n  [ResourceType.DATABASE]: [\"CAN_CONNECT_AND_CREATE\"],\n  [ResourceType.POSTGRES]: [\"CAN_CONNECT_AND_CREATE\"],\n  [ResourceType.GENIE_SPACE]: [\"CAN_VIEW\", \"CAN_RUN\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.EXPERIMENT]: [\"CAN_READ\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.APP]: [\"CAN_USE\"],\n} as const;\n\n/** Set of valid permissions per type (for validation). */\nexport const PERMISSIONS_BY_TYPE: Record<ResourceType, readonly ResourcePermission[]> = PERMISSION_HIERARCHY_BY_TYPE;\n"],"mappings":";;AAIA,IAAY,sDAAL;AACL;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;AA8DF,MAAa,+BAAoF;EAC9F,aAAa,SAAS;EAAC;EAAQ;EAAS;EAAS;EACjD,aAAa,MAAM;EAAC;EAAY;EAAkB;EAAa;EAC/D,aAAa,gBAAgB,CAAC,WAAW,aAAa;EACtD,aAAa,mBAAmB;EAAC;EAAY;EAAa;EAAa;EACvE,aAAa,SAAS,CAAC,eAAe,eAAe;EACrD,aAAa,sBAAsB,CAAC,SAAS;EAC7C,aAAa,cAAc,CAAC,UAAU;EACtC,aAAa,gBAAgB,CAAC,iBAAiB;EAC/C,aAAa,WAAW,CAAC,yBAAyB;EAClD,aAAa,WAAW,CAAC,yBAAyB;EAClD,aAAa,cAAc;EAAC;EAAY;EAAW;EAAY;EAAa;EAC5E,aAAa,aAAa;EAAC;EAAY;EAAY;EAAa;EAChE,aAAa,MAAM,CAAC,UAAU;CAChC;;AAGD,MAAa,sBAA2E"}

package/dist/registry/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/registry/types.ts"],"sourcesContent":["/**\n * Resource Registry Type System\n *\n * This module defines the type system for the AppKit Resource Registry,\n * which enables plugins to declare their Databricks resource requirements\n * in a machine-readable format.\n *\n * Resource types and permissions are generated from plugin-manifest.schema.json\n * (see types.generated.ts). Hand-written interfaces below define the registry API.\n */\n\n// Re-export generated registry types (enum + const must be value exports for runtime)\nimport {\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  type ResourcePermission,\n  ResourceType,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n} from \"./types.generated\";\n\nexport {\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  ResourceType,\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  type ResourcePermission,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n};\n\n// ============================================================================\n// Hand-written interfaces (not in JSON schema)\n// ============================================================================\n\n/**\n * Defines a single field for a resource. Each field has its own environment variable and optional description.\n * Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).\n */\nexport interface ResourceFieldEntry {\n  /** Environment variable name for this field */\n  env: string;\n  /** Human-readable description for this field */\n  description?: string;\n}\n\n/**\n * Declares a resource requirement for a plugin.\n * Can be defined statically in a manifest or dynamically via getResourceRequirements().\n */\nexport interface ResourceRequirement {\n  /** Type of Databricks resource required */\n  type: ResourceType;\n\n  /** Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display. */\n  alias: string;\n\n  /** Stable key for machine use (env naming, composite keys, app.yaml). Required. */\n  resourceKey: string;\n\n  /** Human-readable description of why this resource is needed */\n  description: string;\n\n  /** Required permission level for the resource */\n  permission: ResourcePermission;\n\n  /**\n   * Map of field name to env and optional description.\n   * Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.\n   */\n  fields: Record<string, ResourceFieldEntry>;\n\n  /** Whether this resource is required (true) or optional (false) */\n  required: boolean;\n}\n\n/**\n * Internal representation of a resource in the registry.\n * Extends ResourceRequirement with resolution state and plugin ownership.\n */\nexport interface ResourceEntry extends ResourceRequirement {\n  /** Plugin(s) that require this resource (comma-separated if multiple) */\n  plugin: string;\n\n  /** Whether the resource has been resolved (all field env vars set) */\n  resolved: boolean;\n\n  /** Resolved value per field name. Populated by validate() when all field env vars are set. */\n  values?: Record<string, string>;\n\n  /**\n   * Per-plugin permission tracking.\n   * Maps plugin name to the permission it originally requested.\n   * Populated when multiple plugins share the same resource.\n   */\n  permissionSources?: Record<string, ResourcePermission>;\n}\n\n/**\n * Result of validating all registered resources against the environment.\n */\nexport interface ValidationResult {\n  /** Whether all required resources are available */\n  valid: boolean;\n\n  /** List of missing required resources */\n  missing: ResourceEntry[];\n\n  /** Complete list of all registered resources (required and optional) */\n  all: ResourceEntry[];\n}\n\nimport type { JSONSchema7 } from \"json-schema\";\n\n/**\n * Configuration schema definition for plugin config.\n * Re-exported from the standard JSON Schema Draft 7 types.\n *\n * @see {@link https://json-schema.org/draft-07/json-schema-release-notes | JSON Schema Draft 7}\n */\nexport type ConfigSchema = JSONSchema7;\n\n/**\n * Plugin manifest that declares metadata and resource requirements.\n * Attached to plugin classes as a static property.\n */\nexport interface PluginManifest<TName extends string = string> {\n  /** Plugin identifier — the single source of truth for the plugin's name */\n  name: TName;\n\n  /** Human-readable display name for UI/CLI */\n  displayName: string;\n\n  /** Brief description of what the plugin does */\n  description: string;\n\n  /**\n   * Resource requirements declaration\n   */\n  resources: {\n    /** Resources that must be available for the plugin to function */\n    required: Omit<ResourceRequirement, \"required\">[];\n\n    /** Resources that enhance functionality but are not mandatory */\n    optional: Omit<ResourceRequirement, \"required\">[];\n  };\n\n  /**\n   * Configuration schema for the plugin.\n   * Defines the shape and validation rules for plugin config.\n   */\n  config?: {\n    schema: ConfigSchema;\n  };\n\n  /**\n   * When true, excluded from the template plugins manifest during sync.\n   */\n  hidden?: boolean;\n\n  /**\n   * Optional metadata for community plugins\n   */\n  author?: string;\n  version?: string;\n  repository?: string;\n  keywords?: string[];\n  license?: string;\n}\n"],"mappings":""}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/registry/types.ts"],"sourcesContent":["/**\n * Resource Registry Type System\n *\n * This module defines the type system for the AppKit Resource Registry,\n * which enables plugins to declare their Databricks resource requirements\n * in a machine-readable format.\n *\n * Resource types and permissions are generated from plugin-manifest.schema.json\n * (see types.generated.ts). Hand-written interfaces below define the registry API.\n */\n\n// Re-export generated registry types (enum + const must be value exports for runtime)\nimport {\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  type ResourcePermission,\n  ResourceType,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n} from \"./types.generated\";\n\nexport {\n  PERMISSION_HIERARCHY_BY_TYPE,\n  PERMISSIONS_BY_TYPE,\n  ResourceType,\n  type AppPermission,\n  type DatabasePermission,\n  type ExperimentPermission,\n  type GenieSpacePermission,\n  type JobPermission,\n  type ResourcePermission,\n  type SecretPermission,\n  type ServingEndpointPermission,\n  type SqlWarehousePermission,\n  type UcConnectionPermission,\n  type UcFunctionPermission,\n  type VectorSearchIndexPermission,\n  type VolumePermission,\n};\n\n// ============================================================================\n// Hand-written interfaces (not in JSON schema)\n// ============================================================================\n\n/**\n * Defines a single field for a resource. Each field has its own environment variable and optional description.\n * Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).\n */\nexport interface ResourceFieldEntry {\n  /** Environment variable name for this field */\n  env?: string;\n  /** Human-readable description for this field */\n  description?: string;\n  /** When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation. */\n  bundleIgnore?: boolean;\n  /** Example values showing the expected format for this field */\n  examples?: string[];\n  /** When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time. */\n  localOnly?: boolean;\n  /** Static value for this field. Used when no prompted or resolved value exists. */\n  value?: string;\n  /** Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow. */\n  resolve?: string;\n}\n\n/**\n * Declares a resource requirement for a plugin.\n * Can be defined statically in a manifest or dynamically via getResourceRequirements().\n */\nexport interface ResourceRequirement {\n  /** Type of Databricks resource required */\n  type: ResourceType;\n\n  /** Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display. */\n  alias: string;\n\n  /** Stable key for machine use (env naming, composite keys, app.yaml). Required. */\n  resourceKey: string;\n\n  /** Human-readable description of why this resource is needed */\n  description: string;\n\n  /** Required permission level for the resource */\n  permission: ResourcePermission;\n\n  /**\n   * Map of field name to env and optional description.\n   * Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.\n   */\n  fields: Record<string, ResourceFieldEntry>;\n\n  /** Whether this resource is required (true) or optional (false) */\n  required: boolean;\n}\n\n/**\n * Internal representation of a resource in the registry.\n * Extends ResourceRequirement with resolution state and plugin ownership.\n */\nexport interface ResourceEntry extends ResourceRequirement {\n  /** Plugin(s) that require this resource (comma-separated if multiple) */\n  plugin: string;\n\n  /** Whether the resource has been resolved (all field env vars set) */\n  resolved: boolean;\n\n  /** Resolved value per field name. Populated by validate() when all field env vars are set. */\n  values?: Record<string, string>;\n\n  /**\n   * Per-plugin permission tracking.\n   * Maps plugin name to the permission it originally requested.\n   * Populated when multiple plugins share the same resource.\n   */\n  permissionSources?: Record<string, ResourcePermission>;\n}\n\n/**\n * Result of validating all registered resources against the environment.\n */\nexport interface ValidationResult {\n  /** Whether all required resources are available */\n  valid: boolean;\n\n  /** List of missing required resources */\n  missing: ResourceEntry[];\n\n  /** Complete list of all registered resources (required and optional) */\n  all: ResourceEntry[];\n}\n\nimport type { JSONSchema7 } from \"json-schema\";\n\n/**\n * Configuration schema definition for plugin config.\n * Re-exported from the standard JSON Schema Draft 7 types.\n *\n * @see {@link https://json-schema.org/draft-07/json-schema-release-notes | JSON Schema Draft 7}\n */\nexport type ConfigSchema = JSONSchema7;\n\n/**\n * Plugin manifest that declares metadata and resource requirements.\n * Attached to plugin classes as a static property.\n */\nexport interface PluginManifest<TName extends string = string> {\n  /** Plugin identifier — the single source of truth for the plugin's name */\n  name: TName;\n\n  /** Human-readable display name for UI/CLI */\n  displayName: string;\n\n  /** Brief description of what the plugin does */\n  description: string;\n\n  /**\n   * Resource requirements declaration\n   */\n  resources: {\n    /** Resources that must be available for the plugin to function */\n    required: Omit<ResourceRequirement, \"required\">[];\n\n    /** Resources that enhance functionality but are not mandatory */\n    optional: Omit<ResourceRequirement, \"required\">[];\n  };\n\n  /**\n   * Configuration schema for the plugin.\n   * Defines the shape and validation rules for plugin config.\n   */\n  config?: {\n    schema: ConfigSchema;\n  };\n\n  /**\n   * When true, excluded from the template plugins manifest during sync.\n   */\n  hidden?: boolean;\n\n  /**\n   * Optional metadata for community plugins\n   */\n  author?: string;\n  version?: string;\n  repository?: string;\n  keywords?: string[];\n  license?: string;\n}\n"],"mappings":""}

package/dist/schemas/plugin-manifest.schema.json

@@ -111,6 +111,7 @@
         "uc_function",
         "uc_connection",
         "database",
+        "postgres",
         "genie_space",
         "experiment",
         "app"
@@ -162,6 +163,11 @@
       "enum": ["CAN_CONNECT_AND_CREATE"],
       "description": "Permission for database resources"
     },
+    "postgresPermission": {
+      "type": "string",
+      "enum": ["CAN_CONNECT_AND_CREATE"],
+      "description": "Permission for Postgres resources"
+    },
     "genieSpacePermission": {
       "type": "string",
       "enum": ["CAN_VIEW", "CAN_RUN", "CAN_EDIT", "CAN_MANAGE"],
@@ -179,7 +185,6 @@
     },
     "resourceFieldEntry": {
       "type": "object",
-      "required": ["env"],
       "properties": {
         "env": {
           "type": "string",
@@ -190,20 +195,37 @@
         "description": {
           "type": "string",
           "description": "Human-readable description for this field"
+        },
+        "bundleIgnore": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation."
+        },
+        "examples": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Example values showing the expected format for this field"
+        },
+        "localOnly": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time."
+        },
+        "value": {
+          "type": "string",
+          "description": "Static value for this field. Used when no prompted or resolved value exists."
+        },
+        "resolve": {
+          "type": "string",
+          "pattern": "^[a-z_]+:[a-zA-Z]+$",
+          "description": "Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow."
         }
       },
       "additionalProperties": false
     },
     "resourceRequirement": {
       "type": "object",
-      "required": [
-        "type",
-        "alias",
-        "resourceKey",
-        "description",
-        "permission",
-        "fields"
-      ],
+      "required": ["type", "alias", "resourceKey", "description", "permission"],
       "properties": {
         "type": {
           "$ref": "#/$defs/resourceType"
@@ -337,6 +359,17 @@
             }
           }
         },
+        {
+          "if": {
+            "properties": { "type": { "const": "postgres" } },
+            "required": ["type"]
+          },
+          "then": {
+            "properties": {
+              "permission": { "$ref": "#/$defs/postgresPermission" }
+            }
+          }
+        },
         {
           "if": {
             "properties": { "type": { "const": "genie_space" } },

package/dist/shared/src/plugin.d.ts

@@ -74,9 +74,19 @@ interface PluginManifest<TName extends string = string> {
  */
 interface ResourceFieldEntry {
   /** Environment variable name for this field */
-  env: string;
+  env?: string;
   /** Human-readable description for this field */
   description?: string;
+  /** When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation. */
+  bundleIgnore?: boolean;
+  /** Example values showing the expected format for this field */
+  examples?: string[];
+  /** When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time. */
+  localOnly?: boolean;
+  /** Static value for this field. Used when no prompted or resolved value exists. */
+  value?: string;
+  /** Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow. */
+  resolve?: string;
 }
 /**
  * Resource requirement declaration (imported from registry types).

package/dist/shared/src/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../shared/src/plugin.ts"],"mappings":";;;;;UAIiB,UAAA;EACf,IAAA;EAEA,qBAAA;EAEA,KAAA,IAAS,OAAA;EAET,YAAA,CAAa,MAAA,EAAQ,OAAA,CAAQ,MAAA;EAE7B,YAAA,IAAgB,iBAAA;EAEhB,uBAAA,KAA4B,WAAA;EAE5B,OAAA;AAAA;;UAIe,gBAAA;EACf,IAAA;EACA,IAAA;EAAA,CAEC,GAAA;EAMD,SAAA,GAAY,gBAAA;AAAA;AAAA,KAGF,gBAAA;EAGN,MAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAQM,WAAA;;;;;KAMA,iBAAA,KACN,gBAAA,YACM,UAAA,GAAa,UAAA,UAEvB,MAAA,EAAQ,CAAA,KACL,CAAA;EACH,cAAA,GAAiB,MAAA;EACjB,KAAA,GAAQ,WAAA;EA7BI;;;AAGd;EA+BE,QAAA,EAAU,cAAA;;;;;EAKV,uBAAA,EAAyB,MAAA,EAAQ,CAAA,GAAI,mBAAA;AAAA;;AAvBvC;;;UA8BiB,cAAA;EACf,IAAA,EAAM,KAAA;EACN,WAAA;EACA,WAAA;EACA,SAAA;IACE,QAAA,EAAU,IAAA,CAAK,mBAAA;IACf,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;EAEjB,MAAA;IACE,MAAA,EAAQ,WAAA;EAAA;EAEV,cAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;AAAA;;;;;;;UASe,kBAAA;EA5CE;EA8CjB,GAAA;EA7CQ;EA+CR,WAAA;AAAA;;;;;UAOe,mBAAA;EACf,IAAA;EACA,KAAA;EAvC6B;EAyC7B,WAAA;EACA,WAAA;EACA,UAAA;EAtCY;;;;EA2CZ,MAAA,EAAQ,MAAA,SAAe,kBAAA;EACvB,QAAA;AAAA;;;;;;KAoCU,aAAA,WAAwB,UAAA,IAClC,CAAA,sCAAqC,CAAA,GAAI,MAAA;AA5D3C;;;;;AAWA;;AAXA,KAqEY,UAAA,QAAkB,GAAA,cAAgB,IAAA,mBAC1C,GAAA,GACA,GAAA;EAjDY;;;;;EAuDV,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,GAAA;AAAA;;;;;;AAlBpC;;;KA6BY,SAAA,oBACS,UAAA,CAAW,iBAAA,gCAExB,CAAA,YAAa,CAAA,WAAY,UAAA,CAC7B,aAAA,CAAc,YAAA,CAAa,CAAA;AAAA,KAInB,UAAA;EAAwB,MAAA,EAAQ,CAAA;EAAG,MAAA,EAAQ,CAAA;EAAG,IAAA,EAAM,CAAA;AAAA;AAAA,KACpD,QAAA,4BACV,MAAA,GAAS,CAAA,KACN,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGV,UAAA,GAAa,OAAA,CAAQ,MAAA;AAAA,KACrB,YAAA,GAAe,OAAA,CAAQ,QAAA;AAAA,KACvB,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA,KAEtB,UAAA;AAAA,KAEA,WAAA;EAvCU,+DAyCpB,IAAA;EACA,MAAA,EAAQ,UAAA;EACR,IAAA;EACA,OAAA,GAAU,GAAA,EAAK,WAAA,EAAa,GAAA,EAAK,YAAA,KAAiB,OAAA,QApChB;EAsClC,eAAA;AAAA;;KAIU,iBAAA,GAAoB,MAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../shared/src/plugin.ts"],"mappings":";;;;;UAIiB,UAAA;EACf,IAAA;EAEA,qBAAA;EAEA,KAAA,IAAS,OAAA;EAET,YAAA,CAAa,MAAA,EAAQ,OAAA,CAAQ,MAAA;EAE7B,YAAA,IAAgB,iBAAA;EAEhB,uBAAA,KAA4B,WAAA;EAE5B,OAAA;AAAA;;UAIe,gBAAA;EACf,IAAA;EACA,IAAA;EAAA,CAEC,GAAA;EAMD,SAAA,GAAY,gBAAA;AAAA;AAAA,KAGF,gBAAA;EAGN,MAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAQM,WAAA;;;;;KAMA,iBAAA,KACN,gBAAA,YACM,UAAA,GAAa,UAAA,UAEvB,MAAA,EAAQ,CAAA,KACL,CAAA;EACH,cAAA,GAAiB,MAAA;EACjB,KAAA,GAAQ,WAAA;EA7BI;;;AAGd;EA+BE,QAAA,EAAU,cAAA;;;;;EAKV,uBAAA,EAAyB,MAAA,EAAQ,CAAA,GAAI,mBAAA;AAAA;;AAvBvC;;;UA8BiB,cAAA;EACf,IAAA,EAAM,KAAA;EACN,WAAA;EACA,WAAA;EACA,SAAA;IACE,QAAA,EAAU,IAAA,CAAK,mBAAA;IACf,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;EAEjB,MAAA;IACE,MAAA,EAAQ,WAAA;EAAA;EAEV,cAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;AAAA;;;;;;;UASe,kBAAA;EA5CE;EA8CjB,GAAA;EA7CQ;EA+CR,WAAA;EA1CU;EA4CV,YAAA;EAvCiC;EAyCjC,QAAA;EAzCqC;EA2CrC,SAAA;EA3CwD;EA6CxD,KAAA;EAtC6B;EAwC7B,OAAA;AAAA;;;;;UAOe,mBAAA;EACf,IAAA;EACA,KAAA;EAjD8B;EAmD9B,WAAA;EACA,WAAA;EACA,UAAA;EAlDA;;;;EAuDA,MAAA,EAAQ,MAAA,SAAe,kBAAA;EACvB,QAAA;AAAA;;;;;;KAoCU,aAAA,WAAwB,UAAA,IAClC,CAAA,sCAAqC,CAAA,GAAI,MAAA;;;;AAjD3C;;;;KA0DY,UAAA,QAAkB,GAAA,cAAgB,IAAA,mBAC1C,GAAA,GACA,GAAA;EA1DF;;;;;EAgEI,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,GAAA;AAAA;;;;AAlBpC;;;;;KA6BY,SAAA,oBACS,UAAA,CAAW,iBAAA,gCAExB,CAAA,YAAa,CAAA,WAAY,UAAA,CAC7B,aAAA,CAAc,YAAA,CAAa,CAAA;AAAA,KAInB,UAAA;EAAwB,MAAA,EAAQ,CAAA;EAAG,MAAA,EAAQ,CAAA;EAAG,IAAA,EAAM,CAAA;AAAA;AAAA,KACpD,QAAA,4BACV,MAAA,GAAS,CAAA,KACN,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGV,UAAA,GAAa,OAAA,CAAQ,MAAA;AAAA,KACrB,YAAA,GAAe,OAAA,CAAQ,QAAA;AAAA,KACvB,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA,KAEtB,UAAA;AAAA,KAEA,WAAA;EAtCR,+DAwCF,IAAA;EACA,MAAA,EAAQ,UAAA;EACR,IAAA;EACA,OAAA,GAAU,GAAA,EAAK,WAAA,EAAa,GAAA,EAAK,YAAA,KAAiB,OAAA,QApCb;EAsCrC,eAAA;AAAA;;KAIU,iBAAA,GAAoB,MAAA"}

package/docs/api/appkit/Enumeration.ResourceType.md

@@ -49,6 +49,15 @@ JOB: "job";
 
 ***
 
+### POSTGRES[​](#postgres "Direct link to POSTGRES")
+
+```ts
+POSTGRES: "postgres";
+
+```
+
+***
+
 ### SECRET[​](#secret "Direct link to SECRET")
 
 ```ts

package/docs/api/appkit/Interface.ResourceFieldEntry.md

@@ -4,6 +4,17 @@ Defines a single field for a resource. Each field has its own environment variab
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### bundleIgnore?[​](#bundleignore "Direct link to bundleIgnore?")
+
+```ts
+optional bundleIgnore: boolean;
+
+```
+
+When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation.
+
+***
+
 ### description?[​](#description "Direct link to description?")
 
 ```ts
@@ -15,11 +26,55 @@ Human-readable description for this field
 
 ***
 
-### env[​](#env "Direct link to env")
+### env?[​](#env "Direct link to env?")
 
 ```ts
-env: string;
+optional env: string;
 
 ```
 
 Environment variable name for this field
+
+***
+
+### examples?[​](#examples "Direct link to examples?")
+
+```ts
+optional examples: string[];
+
+```
+
+Example values showing the expected format for this field
+
+***
+
+### localOnly?[​](#localonly "Direct link to localOnly?")
+
+```ts
+optional localOnly: boolean;
+
+```
+
+When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time.
+
+***
+
+### resolve?[​](#resolve "Direct link to resolve?")
+
+```ts
+optional resolve: string;
+
+```
+
+Named resolver prefixed by resource type (e.g., 'postgres<!-- -->:host<!-- -->'). The CLI resolves this value during the init prompt flow.
+
+***
+
+### value?[​](#value "Direct link to value?")
+
+```ts
+optional value: string;
+
+```
+
+Static value for this field. Used when no prompted or resolved value exists.

package/docs/api/appkit/TypeAlias.ResourcePermission.md

@@ -11,6 +11,7 @@ type ResourcePermission =
   | UcFunctionPermission
   | UcConnectionPermission
   | DatabasePermission
+  | PostgresPermission
   | GenieSpacePermission
   | ExperimentPermission
   | AppPermission;

package/docs/plugins/lakebase.md

@@ -1,9 +1,5 @@
 # Lakebase plugin
 
-info
-
-Currently, the Lakebase plugin currently requires a one-time manual setup to connect your Databricks App with your Lakebase database. An automated setup process is planned for an upcoming future release.
-
 Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 
 **Key features:**
@@ -12,90 +8,24 @@ Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with a
 * Automatic OAuth token refresh (1-hour tokens, 2-minute refresh buffer)
 * Token caching to minimize API calls
 * Built-in OpenTelemetry instrumentation (query duration, pool connections, token refresh)
+* AppKit logger configured by default for query and connection events
 
-## Setting up Lakebase[​](#setting-up-lakebase "Direct link to Setting up Lakebase")
-
-Before using the plugin, you need to connect your Databricks App's service principal to your Lakebase database.
-
-### 1. Find your app's service principal[​](#1-find-your-apps-service-principal "Direct link to 1. Find your app's service principal")
-
-Create a Databricks App from the UI (`Compute > Apps > Create App > Create a custom app`). Navigate to the **Environment** tab and note the `DATABRICKS_CLIENT_ID` value — this is the service principal that will connect to your Lakebase database.
-
-![App environment tab](/appkit/assets/images/step-1-073320f925a3961838afa0842c727307.png)
-
-### 2. Find your Project ID and Branch ID[​](#2-find-your-project-id-and-branch-id "Direct link to 2. Find your Project ID and Branch ID")
+## Getting started with the Lakebase[​](#getting-started-with-the-lakebase "Direct link to Getting started with the Lakebase")
 
-Create a new Lakebase Postgres Autoscaling project. Navigate to your Lakebase project's branch details and switch to the **Compute** tab. Note the **Project ID** and **Branch ID** from the URL.
+The easiest way to get started with the Lakebase plugin is to use the Databricks CLI to create a new Databricks app with AppKit installed and the Lakebase plugin.
 
-![Branch details](/appkit/assets/images/step-2-25954a56aecd4dafe4966f7cecc6e8f4.png)
+### Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
-### 3. Find your endpoint[​](#3-find-your-endpoint "Direct link to 3. Find your endpoint")
+* [Node.js](https://nodejs.org) v22+ environment with `npm`
+* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
-Use the Databricks CLI to list endpoints for the branch. Note the `name` field from the output — this is your `LAKEBASE_ENDPOINT` value.
+### Steps[​](#steps "Direct link to Steps")
 
-```bash
-databricks postgres list-endpoints projects/{project-id}/branches/{branch-id}
-
-```
-
-Example output:
-
-```json
-[
-  {
-    "create_time": "2026-02-19T12:13:02Z",
-    "name": "projects/{project-id}/branches/{branch-id}/endpoints/primary"
-  }
-]
-
-```
-
-### 4. Get connection parameters[​](#4-get-connection-parameters "Direct link to 4. Get connection parameters")
-
-Click the **Connect** button on your Lakebase branch and copy the `PGHOST` and `PGDATABASE` values for later.
-
-![Connect dialog](/appkit/assets/images/step-4-78b906d125c2c130f6e14984a9f89a62.png)
-
-### 5. Grant access to the service principal[​](#5-grant-access-to-the-service-principal "Direct link to 5. Grant access to the service principal")
-
-Navigate to the **SQL Editor** tab on your Lakebase branch. Run the following SQL against the `databricks_postgres` database, replacing the service principal ID in the `DECLARE` block with the `DATABRICKS_CLIENT_ID` value from step 1:
-
-```sql
-CREATE EXTENSION IF NOT EXISTS databricks_auth;
-
-DO $$
-DECLARE
-  sp TEXT := 'your-service-principal-id';  -- Replace with DATABRICKS_CLIENT_ID from Step 1
-BEGIN
-  -- Create service principal role
-  PERFORM databricks_create_role(sp, 'SERVICE_PRINCIPAL');
-
-  -- Connection and schema access
-  EXECUTE format('GRANT CONNECT ON DATABASE "databricks_postgres" TO %I', sp);
-  EXECUTE format('GRANT ALL ON SCHEMA public TO %I', sp);
-
-  -- Privileges on existing objects
-  EXECUTE format('GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO %I', sp);
-  EXECUTE format('GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO %I', sp);
-  EXECUTE format('GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO %I', sp);
-  EXECUTE format('GRANT ALL PRIVILEGES ON ALL PROCEDURES IN SCHEMA public TO %I', sp);
-
-  -- Default privileges on future objects you create
-  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO %I', sp);
-  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO %I', sp);
-  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON FUNCTIONS TO %I', sp);
-  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON ROUTINES TO %I', sp);
-END $$;
-
-```
-
-![SQL Editor](/appkit/assets/images/step-5-38bdf3e3ac8aadf2c0cd57aa5f0ba090.png)
-
-### 6. Verify the role[​](#6-verify-the-role "Direct link to 6. Verify the role")
-
-Navigate to the **Roles & Databases** tab and confirm the role is visible. You may need to fully refresh the page.
-
-![Roles \& Databases tab](/appkit/assets/images/step-6-edbb462e89a66c46d58424768c163e4e.png)
+1. Firstly, create a new Lakebase Postgres Autoscaling project according to the [Get started documentation](https://docs.databricks.com/aws/en/oltp/projects/get-started).
+2. To add the Lakebase plugin to your project, run the `databricks apps init` command and interactively select the **Lakebase** plugin. The CLI will guide you through picking a Lakebase project, branch, and database.
+   <!-- -->
+   * When asked, select **Yes** to deploy the app to Databricks Apps right after its creation.
 
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
 
@@ -108,34 +38,6 @@ await createApp({
 
 ```
 
-## Environment variables[​](#environment-variables "Direct link to Environment variables")
-
-The required environment variables:
-
-| Variable            | Description                                                             |
-| ------------------- | ----------------------------------------------------------------------- |
-| `PGHOST`            | Lakebase host                                                           |
-| `PGDATABASE`        | Database name                                                           |
-| `LAKEBASE_ENDPOINT` | Endpoint resource path (e.g. `projects/.../branches/.../endpoints/...`) |
-| `PGSSLMODE`         | TLS mode — set to `require`                                             |
-
-Ensure that those environment variables are set both for local development (`.env` file) and for deployment (`app.yaml` file):
-
-```yaml
-env:
-  - name: LAKEBASE_ENDPOINT
-    value: projects/{project-id}/branches/{branch-id}/endpoints/primary
-  - name: PGHOST
-    value: {your-lakebase-host}
-  - name: PGDATABASE
-    value: databricks_postgres
-  - name: PGSSLMODE
-    value: require
-
-```
-
-For the full configuration reference (SSL, pool size, timeouts, logging, ORM examples), see the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md).
-
 ## Accessing the pool[​](#accessing-the-pool "Direct link to Accessing the pool")
 
 After initialization, access Lakebase through the `AppKit.lakebase` object:
@@ -145,9 +47,17 @@ const AppKit = await createApp({
   plugins: [server(), lakebase()],
 });
 
-// Direct query (parameterized)
+await AppKit.lakebase.query(`CREATE SCHEMA IF NOT EXISTS app`);
+
+await AppKit.lakebase.query(`CREATE TABLE IF NOT EXISTS app.orders (
+  id SERIAL PRIMARY KEY,
+  user_id VARCHAR(255) NOT NULL,
+  amount DECIMAL(10, 2) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)`);
+
 const result = await AppKit.lakebase.query(
-  "SELECT * FROM orders WHERE user_id = $1",
+  "SELECT * FROM app.orders WHERE user_id = $1",
   [userId],
 );
 
@@ -160,7 +70,33 @@ const pgConfig = AppKit.lakebase.getPgConfig();    // pg.PoolConfig
 
 ```
 
-## Configuration options[​](#configuration-options "Direct link to Configuration options")
+## Configuration[​](#configuration "Direct link to Configuration")
+
+### Environment variables[​](#environment-variables "Direct link to Environment variables")
+
+The required environment variables are:
+
+| Variable            | Description                                                                                          |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `LAKEBASE_ENDPOINT` | Endpoint resource path (e.g. `projects/.../branches/.../endpoints/...`)                              |
+| `PGHOST`            | Lakebase host (auto-injected in production by the `postgres` Databricks Apps resource)               |
+| `PGDATABASE`        | Database name (auto-injected in production by the `postgres` Databricks Apps resource)               |
+| `PGSSLMODE`         | TLS mode - set to `require` (auto-injected in production by the `postgres` Databricks Apps resource) |
+
+When deployed to Databricks Apps with a `postgres` database resource configured, `PGHOST`, `PGDATABASE`, `PGSSLMODE`, `PGUSER`, `PGPORT`, and `PGAPPNAME` are automatically injected by the platform. Only `LAKEBASE_ENDPOINT` must be set explicitly:
+
+```yaml
+env:
+  - name: LAKEBASE_ENDPOINT
+    valueFrom: postgres
+
+```
+
+For local development, the `.env` file is automatically generated by `databricks apps init` with the correct values for your Lakebase project.
+
+For the full configuration reference (SSL, pool size, timeouts, logging, ORM examples), see the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md).
+
+### Pool configuration[​](#pool-configuration "Direct link to Pool configuration")
 
 Pass a `pool` object to override any defaults:
 
@@ -178,3 +114,74 @@ await createApp({
 });
 
 ```
+
+## Database Permissions[​](#database-permissions "Direct link to Database Permissions")
+
+When you create the app with the Lakebase resource using the [Getting started](#getting-started-with-the-lakebase) guide, the Service Principal is automatically granted `CONNECT_AND_CREATE` permission on the `postgres` resource. This lets the Service Principal connect to the database and create new objects, but **not access any existing schemas or tables.**
+
+### Local development[​](#local-development "Direct link to Local development")
+
+To develop locally against a deployed Lakebase database:
+
+1. **Deploy the app first.** The Service Principal creates the database schema and tables on first deploy. Apps generated from `databricks apps init` handle this automatically - they check if tables exist on startup and skip creation if they do.
+
+2. **Grant `databricks_superuser` via the Lakebase UI:**
+
+   1. Open the Lakebase Autoscaling UI and navigate to your project's **Branch Overview** page.
+   2. Click **Add role** (or **Edit role** if your OAuth role already exists).
+   3. Select your Databricks identity as the principal and check the **`databricks_superuser`** system role.
+
+3. **Run locally** - your Databricks user identity (email) is used for OAuth authentication. The `databricks_superuser` role gives full **DML access** (read/write data) but **not DDL** (creating schemas or tables) - that's why deploying first matters (see note below).
+
+For other users, use the same **Add role** flow in the Lakebase UI to create an OAuth role with `databricks_superuser` for each user.
+
+tip
+
+[Postgres password authentication](https://docs.databricks.com/aws/en/oltp/projects/authentication#overview) is a simpler alternative that avoids OAuth role permission complexity. However, it requires you to set up a password for the user in the **Branch Overview** page in the Lakebase Autoscaling UI.
+
+Why deploy first?
+
+When the app is deployed, the Service Principal creates schemas and tables and becomes their owner. A `databricks_superuser` has full **DML access** (SELECT, INSERT, UPDATE, DELETE) to these objects, but **cannot run DDL** (CREATE SCHEMA, CREATE TABLE) on schemas owned by the Service Principal. Deploying first ensures all objects exist before local development begins.
+
+### Fine-grained permissions[​](#fine-grained-permissions "Direct link to Fine-grained permissions")
+
+For most use cases, `databricks_superuser` is sufficient. If you need schema-level grants instead, refer to the official documentation:
+
+* [Manage database permissions](https://docs.databricks.com/aws/en/oltp/projects/manage-roles-permissions)
+* [Postgres roles](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles)
+
+SQL script for fine-grained grants
+
+Deploy and run the app at least once before executing these grants so the Service Principal initializes the database schema first.
+
+Replace `subject` with the user email and `schema` with your schema name:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS databricks_auth;
+
+DO $$
+DECLARE
+  subject TEXT := 'your-subject';  -- User email like name@databricks.com
+  schema TEXT := 'your_schema'; -- Replace 'your_schema' with your schema name
+BEGIN
+  -- Create OAuth role for the Databricks identity
+  PERFORM databricks_create_role(subject, 'USER');
+
+  -- Connection and schema access
+  EXECUTE format('GRANT CONNECT ON DATABASE "databricks_postgres" TO %I', subject);
+  EXECUTE format('GRANT ALL ON SCHEMA %s TO %I', schema, subject);
+
+  -- Privileges on existing objects
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA %s TO %I', schema, subject);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA %s TO %I', schema, subject);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA %s TO %I', schema, subject);
+  EXECUTE format('GRANT ALL PRIVILEGES ON ALL PROCEDURES IN SCHEMA %s TO %I', schema, subject);
+
+  -- Default privileges on future objects
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA %s GRANT ALL ON TABLES TO %I', schema, subject);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA %s GRANT ALL ON SEQUENCES TO %I', schema, subject);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA %s GRANT ALL ON FUNCTIONS TO %I', schema, subject);
+  EXECUTE format('ALTER DEFAULT PRIVILEGES IN SCHEMA %s GRANT ALL ON ROUTINES TO %I', schema, subject);
+END $$;
+
+```

package/llms.txt

@@ -46,7 +46,7 @@ npx @databricks/appkit docs <query>
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
 - [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
-- [Lakebase plugin](./docs/plugins/lakebase.md): Currently, the Lakebase plugin currently requires a one-time manual setup to connect your Databricks App with your Lakebase database. An automated setup process is planned for an upcoming future release.
+- [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",