kanban-lite 1.2.3 → 1.2.6

package/src/cli/index.test.ts

@@ -53,6 +53,85 @@ function createCliAuthWorkspace(): { workspaceDir: string; configPath: string; c
   }
 }
 
+function createCliWorkspace(config: Record<string, unknown>): { workspaceDir: string; configPath: string; cleanup: () => void } {
+  const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kanban-cli-plugin-'))
+  fs.mkdirSync(path.join(workspaceDir, '.kanban'), { recursive: true })
+  const configPath = path.join(workspaceDir, '.kanban.json')
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({
+      version: 2,
+      defaultBoard: 'default',
+      kanbanDirectory: '.kanban',
+      boards: {
+        default: {
+          name: 'Default',
+          columns: [{ id: 'backlog', name: 'Backlog' }],
+          nextCardId: 1,
+          defaultStatus: 'backlog',
+          defaultPriority: 'medium',
+        },
+      },
+      ...config,
+    }, null, 2) + '\n',
+    'utf-8',
+  )
+  return {
+    workspaceDir,
+    configPath,
+    cleanup: () => fs.rmSync(workspaceDir, { recursive: true, force: true }),
+  }
+}
+
+function installTempCliPlugin(packageName: string, entrySource: string): () => void {
+  const packageDir = path.join(WORKSPACE_ROOT, 'node_modules', packageName)
+  fs.mkdirSync(packageDir, { recursive: true })
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({ name: packageName, main: 'index.js' }, null, 2),
+    'utf-8',
+  )
+  fs.writeFileSync(path.join(packageDir, 'index.js'), entrySource, 'utf-8')
+  return () => fs.rmSync(packageDir, { recursive: true, force: true })
+}
+
+function createCliSdkProbePackageSource(packageName: string, command: string): string {
+  return [
+    "const fs = require('node:fs')",
+    `const packageName = ${JSON.stringify(packageName)}`,
+    `const command = ${JSON.stringify(command)}`,
+    'module.exports.authIdentityPlugin = {',
+    '  manifest: { id: packageName, provides: [\'auth.identity\'] },',
+    '  async resolveIdentity() { return null },',
+    '}',
+    'module.exports.cliPlugin = {',
+    '  manifest: { id: packageName },',
+    '  command,',
+    '  async run(subArgs, flags, context) {',
+    '    const runWithCliAuthResult = typeof context.runWithCliAuth === \"function\"',
+    '      ? await context.runWithCliAuth(() => Promise.resolve(\"ok\"))',
+    '      : null',
+    '    const payload = {',
+    '      subArgs,',
+    '      hasSdk: !!context.sdk,',
+    '      hasGetConfigSnapshot: typeof context.sdk?.getConfigSnapshot === \"function\",',
+    '      hasGetBoard: typeof context.sdk?.getBoard === "function",',
+    '      hasGetExtension: typeof context.sdk?.getExtension === \"function\",',
+    '      hasWorkspaceRootGetter: typeof context.sdk?.workspaceRoot === \"string\",',
+    '      snapshotDefaultBoard: context.sdk?.getConfigSnapshot?.().defaultBoard ?? null,',
+    '      defaultBoardName: context.sdk?.getBoard?.("default")?.name ?? null,',
+    '      runWithCliAuthResult,',
+    '      workspaceRoot: context.workspaceRoot,',
+    '      flagCount: Object.keys(flags || {}).length,',
+    '    }',
+    '    if (process.env.KANBAN_SDK_PROBE_OUTPUT) {',
+    '      fs.writeFileSync(process.env.KANBAN_SDK_PROBE_OUTPUT, JSON.stringify(payload, null, 2))',
+    '    }',
+    '  },',
+    '}',
+  ].join('\n')
+}
+
 async function createCliCardStateWorkspace(): Promise<{ workspaceDir: string; configPath: string; cardId: string; cleanup: () => void }> {
   const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kanban-cli-card-state-'))
   fs.mkdirSync(path.join(workspaceDir, '.kanban'), { recursive: true })
@@ -733,3 +812,81 @@ describe('Webhook CLI routing — plugin-owned dispatch', () => {
   })
 })
 
+describe('CLI plugin context SDK injection regressions', () => {
+  it('passes the full public SDK to standard CLI plugin commands', async () => {
+    const packageName = `kanban-cli-sdk-probe-${Date.now()}-standard`
+    const cleanupPlugin = installTempCliPlugin(
+      packageName,
+      createCliSdkProbePackageSource(packageName, 'sdk-probe'),
+    )
+    const { workspaceDir, configPath, cleanup } = createCliWorkspace({
+      auth: {
+        'auth.identity': { provider: packageName },
+      },
+    })
+    const markerPath = path.join(workspaceDir, 'sdk-probe-standard.json')
+
+    try {
+      const result = await runCliCommand(['sdk-probe', '--config', configPath], {
+        KANBAN_SDK_PROBE_OUTPUT: markerPath,
+      })
+
+      expect(result.exitCode).toBe(0)
+      const payload = JSON.parse(fs.readFileSync(markerPath, 'utf-8')) as Record<string, unknown>
+      expect(payload).toMatchObject({
+        subArgs: [],
+        hasSdk: true,
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        hasWorkspaceRootGetter: true,
+        snapshotDefaultBoard: 'default',
+        defaultBoardName: 'Default',
+        runWithCliAuthResult: 'ok',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      cleanup()
+      cleanupPlugin()
+    }
+  })
+
+  it('passes the full public SDK through the auth special-case CLI path', async () => {
+    const packageName = `kanban-cli-sdk-probe-${Date.now()}-auth`
+    const cleanupPlugin = installTempCliPlugin(
+      packageName,
+      createCliSdkProbePackageSource(packageName, 'auth'),
+    )
+    const { workspaceDir, configPath, cleanup } = createCliWorkspace({
+      auth: {
+        'auth.identity': { provider: packageName },
+      },
+    })
+    const markerPath = path.join(workspaceDir, 'sdk-probe-auth.json')
+
+    try {
+      const result = await runCliCommand(['auth', 'inspect', '--config', configPath], {
+        KANBAN_SDK_PROBE_OUTPUT: markerPath,
+      })
+
+      expect(result.exitCode).toBe(0)
+      const payload = JSON.parse(fs.readFileSync(markerPath, 'utf-8')) as Record<string, unknown>
+      expect(payload).toMatchObject({
+        subArgs: ['inspect'],
+        hasSdk: true,
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        hasWorkspaceRootGetter: true,
+        snapshotDefaultBoard: 'default',
+        defaultBoardName: 'Default',
+        runWithCliAuthResult: 'ok',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      cleanup()
+      cleanupPlugin()
+    }
+  })
+})
+

package/src/cli/index.ts

@@ -1869,7 +1869,7 @@ async function cmdAuth(sdk: KanbanSDK, positional: string[], flags: Flags, cliPl
   if (sub !== 'status') {
     const authPlugin = findCliPlugin(cliPlugins, 'auth')
     if (authPlugin) {
-      await authPlugin.run(positional, flags, { workspaceRoot })
+      await runCliPlugin(authPlugin, positional, flags, workspaceRoot, sdk)
       return
     }
     console.error(red(`Unknown auth sub-command: ${sub}`))

package/src/mcp-server/index.test.ts

@@ -581,6 +581,82 @@ describe('plugin-owned MCP webhook registration', () => {
     }
   })
 
+  it('keeps widened MCP plugin contexts compatible with full public SDK reads', async () => {
+    const tools: Array<{
+      name: string
+      description: string
+      schema: Record<string, unknown>
+      handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>
+    }> = []
+
+    const server = {
+      tool(
+        name: string,
+        description: string,
+        schema: Record<string, unknown>,
+        handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>,
+      ) {
+        tools.push({ name, description, schema, handler })
+      },
+    }
+
+    const probePlugin = {
+      manifest: { id: 'sdk-seam-probe', provides: ['mcp.tools'] as const },
+      registerTools: (ctx: ReturnType<typeof createMcpPluginContext>) => [{
+        name: 'sdk_snapshot_probe',
+        description: 'Regression probe for widened MCP SDK context.',
+        inputSchema: () => ({}),
+        handler: async () => ({
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              hasGetConfigSnapshot: typeof ctx.sdk.getConfigSnapshot === 'function',
+              hasGetBoard: typeof ctx.sdk.getBoard === 'function',
+              hasGetExtension: typeof ctx.sdk.getExtension === 'function',
+              defaultBoard: ctx.sdk.getConfigSnapshot().defaultBoard,
+              defaultBoardName: ctx.sdk.getBoard('default').name,
+              workspaceRoot: ctx.sdk.workspaceRoot,
+            }),
+          }],
+        }),
+      }],
+    }
+
+    const resolveSpy = vi.spyOn(pluginRegistry, 'resolveMcpPlugins').mockReturnValue([
+      mcpPlugin as never,
+      probePlugin as never,
+    ])
+
+    try {
+      const registered = registerPluginMcpTools(
+        server,
+        {},
+        createMcpPluginContext({
+          sdk,
+          workspaceRoot: workspaceDir,
+          kanbanDir,
+          runWithAuth: (fn) => sdk.runWithAuth({ transport: 'mcp' }, fn),
+        }),
+      )
+
+      expect(registered).toContain('sdk_snapshot_probe')
+      const probeTool = tools.find((tool) => tool.name === 'sdk_snapshot_probe')
+      expect(probeTool).toBeDefined()
+
+      const result = await probeTool!.handler({})
+      expect(JSON.parse(result.content[0].text)).toEqual({
+        hasGetConfigSnapshot: true,
+        hasGetBoard: true,
+        hasGetExtension: true,
+        defaultBoard: 'default',
+        defaultBoardName: 'Default',
+        workspaceRoot: workspaceDir,
+      })
+    } finally {
+      resolveSpy.mockRestore()
+    }
+  })
+
   it('rejects duplicate plugin-owned MCP tool registration for webhook tools', () => {
     const duplicatePlugin = {
       manifest: { id: 'duplicate-webhooks-test', provides: ['mcp.tools'] as const },

package/src/sdk/KanbanSDK.d.ts

@@ -1,6 +1,6 @@
 import type { Comment, Card, KanbanColumn, BoardInfo, LabelDefinition, CardSortOption, LogEntry } from '../shared/types';
 import type { CardDisplaySettings, Priority } from '../shared/types';
-import type { BoardConfig, ResolvedCapabilities, Webhook } from '../shared/config';
+import type { BoardConfig, KanbanConfig, ResolvedCapabilities, Webhook } from '../shared/config';
 import type { CreateCardInput, SDKEvent, SDKEventType, SDKOptions, SubmitFormInput, SubmitFormResult, AuthContext, AuthDecision, SDKBeforeEventType, SDKAfterEventType, CardStateStatus, CardUnreadSummary } from './types';
 import type { EventBusAnyListener, EventBusWaitOptions } from './eventBus';
 import { EventBus } from './eventBus';
@@ -67,6 +67,9 @@ export interface WebhookStatus {
 }
 /** Active card-state provider metadata for diagnostics and host surfaces. */
 export type CardStateRuntimeStatus = CardStateStatus;
+type ReadonlySnapshot<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? readonly ReadonlySnapshot<U>[] : T extends object ? {
+    readonly [K in keyof T]: ReadonlySnapshot<T[K]>;
+} : T;
 /**
  * Optional search and sort inputs for {@link KanbanSDK.listCards}.
  *
@@ -524,6 +527,23 @@ export declare class KanbanSDK {
      * ```
      */
     get workspaceRoot(): string;
+    /**
+     * Returns a cloned read-only snapshot of the current workspace config.
+     *
+     * The returned snapshot is created from a fresh config read and deep-cloned
+     * before being returned, so callers receive an isolated view of the current
+     * `.kanban.json` state rather than a live mutable runtime object. Mutating the
+     * returned snapshot does not update persisted config or affect this SDK instance.
+     *
+     * @returns A cloned read-only snapshot of the current {@link KanbanConfig}.
+     *
+     * @example
+     * ```ts
+     * const config = sdk.getConfigSnapshot()
+     * console.log(config.defaultBoard)
+     * ```
+     */
+    getConfigSnapshot(): ReadonlySnapshot<KanbanConfig>;
     /** @internal */
     _resolveBoardId(boardId?: string): string;
     /** @internal */

package/src/sdk/KanbanSDK.ts

@@ -4,7 +4,7 @@ import type { Comment, Card, KanbanColumn, BoardInfo, LabelDefinition, CardSortO
 import type { CardDisplaySettings, Priority } from '../shared/types'
 import { DELETED_STATUS_ID } from '../shared/types'
 import { readConfig, normalizeStorageCapabilities, normalizeAuthCapabilities, normalizeWebhookCapabilities, normalizeCardStateCapabilities } from '../shared/config'
-import type { BoardConfig, ProviderRef, ResolvedCapabilities, ResolvedWebhookCapabilities, ResolvedCardStateCapabilities, Webhook } from '../shared/config'
+import type { BoardConfig, KanbanConfig, ProviderRef, ResolvedCapabilities, ResolvedWebhookCapabilities, ResolvedCardStateCapabilities, Webhook } from '../shared/config'
 import type { ResolvedAuthCapabilities } from '../shared/config'
 import type { CreateCardInput, SDKEvent, SDKEventHandler, SDKEventType, SDKOptions, SubmitFormInput, SubmitFormResult, AuthContext, AuthDecision, SDKEventListenerPlugin, BeforeEventPayload, AfterEventPayload, SDKBeforeEventType, SDKAfterEventType, CardStateStatus, CardOpenStateValue, CardUnreadSummary } from './types'
 import type { EventBusAnyListener, EventBusWaitOptions } from './eventBus'
@@ -113,6 +113,15 @@ type MethodInput<TMethod> =
     ? TFirst
     : Record<string, unknown>
 
+type ReadonlySnapshot<T> =
+  T extends (...args: never[]) => unknown
+    ? T
+    : T extends readonly (infer U)[]
+      ? readonly ReadonlySnapshot<U>[]
+      : T extends object
+        ? { readonly [K in keyof T]: ReadonlySnapshot<T[K]> }
+        : T
+
 /**
  * Active webhook provider metadata for diagnostics and host surfaces.
  *
@@ -1158,6 +1167,26 @@ export class KanbanSDK {
     return path.dirname(this.kanbanDir)
   }
 
+  /**
+   * Returns a cloned read-only snapshot of the current workspace config.
+   *
+   * The returned snapshot is created from a fresh config read and deep-cloned
+   * before being returned, so callers receive an isolated view of the current
+   * `.kanban.json` state rather than a live mutable runtime object. Mutating the
+   * returned snapshot does not update persisted config or affect this SDK instance.
+   *
+   * @returns A cloned read-only snapshot of the current {@link KanbanConfig}.
+   *
+   * @example
+   * ```ts
+   * const config = sdk.getConfigSnapshot()
+   * console.log(config.defaultBoard)
+   * ```
+   */
+  getConfigSnapshot(): ReadonlySnapshot<KanbanConfig> {
+    return structuredClone(readConfig(this.workspaceRoot)) as ReadonlySnapshot<KanbanConfig>
+  }
+
   // --- Board resolution helpers ---
 
   /** @internal */

package/src/sdk/__tests__/KanbanSDK.test.ts

@@ -155,6 +155,62 @@ describe('KanbanSDK', () => {
     })
   })
 
+  describe('getConfigSnapshot', () => {
+    it('returns an isolated clone that cannot mutate subsequent SDK reads or persisted config', () => {
+      writeWorkspaceConfig(workspaceDir, {
+        defaultBoard: 'default',
+        kanbanDirectory: '.kanban',
+        boards: {
+          default: {
+            name: 'Default',
+            columns: [{ id: 'backlog', name: 'Backlog' }],
+            nextCardId: 1,
+            defaultStatus: 'backlog',
+            defaultPriority: 'medium',
+          },
+        },
+        plugins: {
+          'auth.identity': {
+            provider: 'kl-auth-plugin',
+            options: {
+              users: [{ username: 'alice', password: '$2b$12$existing-hash' }],
+            },
+          },
+        },
+        webhooks: [
+          { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+        ],
+      })
+
+      const firstSnapshot = sdk.getConfigSnapshot() as any
+      firstSnapshot.defaultBoard = 'mutated-board'
+      firstSnapshot.boards.default.name = 'Mutated Board'
+      firstSnapshot.webhooks[0].url = 'https://example.com/mutated'
+      firstSnapshot.plugins['auth.identity'].options.users.push({ username: 'mallory', password: 'bad-hash' })
+
+      const secondSnapshot = sdk.getConfigSnapshot() as any
+      const persisted = JSON.parse(fs.readFileSync(path.join(workspaceDir, '.kanban.json'), 'utf-8')) as any
+
+      expect(secondSnapshot.defaultBoard).toBe('default')
+      expect(secondSnapshot.boards.default.name).toBe('Default')
+      expect(secondSnapshot.webhooks[0].url).toBe('https://example.com/original')
+      expect(secondSnapshot.plugins['auth.identity'].options.users).toEqual([
+        { username: 'alice', password: '$2b$12$existing-hash' },
+      ])
+      expect(sdk.listWebhooks()).toEqual([
+        { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+      ])
+      expect(persisted.defaultBoard).toBe('default')
+      expect(persisted.boards.default.name).toBe('Default')
+      expect(persisted.webhooks).toEqual([
+        { id: 'wh_snapshot', url: 'https://example.com/original', events: ['*'], active: true },
+      ])
+      expect(persisted.plugins['auth.identity'].options.users).toEqual([
+        { username: 'alice', password: '$2b$12$existing-hash' },
+      ])
+    })
+  })
+
   describe('getCardStateStatus', () => {
     it('reports builtin backend status and allows the default actor when auth.identity is noop', () => {
       const status = sdk.getCardStateStatus()
@@ -1080,10 +1136,18 @@ describe('KanbanSDK', () => {
       expect(reloaded?.actions).toBeUndefined()
     })
 
-    it('should throw if no actionWebhookUrl is configured', async () => {
+    it('should append an activity log entry even when no actionWebhookUrl is configured', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# Card', actions: ['retry'] })
-      await expect(sdk.triggerAction(card.id, 'retry')).rejects.toThrow('No action webhook URL configured')
+      await expect(sdk.triggerAction(card.id, 'retry')).resolves.toBeUndefined()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs).toHaveLength(1)
+      expect(logs[0]).toMatchObject({
+        source: 'system',
+        text: 'Action triggered: `retry`',
+        object: { action: 'retry' },
+      })
     })
 
     it('should throw if card not found', async () => {
@@ -1094,45 +1158,36 @@ describe('KanbanSDK', () => {
       await expect(sdk.triggerAction('nonexistent', 'retry')).rejects.toThrow('Card not found')
     })
 
-    it('should POST correct payload to actionWebhookUrl on success', async () => {
+    it('should not call fetch directly; webhook delivery is delegated to plugin after-events', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# My Card', actions: ['retry'] })
 
-      const { readConfig, writeConfig } = await import('../../shared/config')
-      const config = readConfig(sdk.workspaceRoot)
-      writeConfig(sdk.workspaceRoot, { ...config, actionWebhookUrl: 'https://example.com/webhook' })
-
       const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: 'OK' })
       vi.stubGlobal('fetch', mockFetch)
 
       await sdk.triggerAction(card.id, 'retry')
 
-      expect(mockFetch).toHaveBeenCalledOnce()
-      const [url, init] = mockFetch.mock.calls[0]
-      expect(url).toBe('https://example.com/webhook')
-      expect(init.method).toBe('POST')
-      expect(init.headers).toEqual({ 'Content-Type': 'application/json' })
-      const body = JSON.parse(init.body)
-      expect(body.action).toBe('retry')
-      expect(body.board).toBe('default')
-      expect(body.list).toBe(card.status)
-      expect(body.card.id).toBe(card.id)
-      expect(body.card.filePath).toBeUndefined()
+      expect(mockFetch).not.toHaveBeenCalled()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs.at(-1)).toMatchObject({
+        text: 'Action triggered: `retry`',
+        object: { action: 'retry' },
+      })
 
       vi.unstubAllGlobals()
     })
 
-    it('should throw on non-2xx webhook response', async () => {
+    it('should stay side-effect free with respect to direct webhook transport failures', async () => {
       await sdk.init()
       const card = await sdk.createCard({ content: '# My Card', actions: ['retry'] })
 
-      const { readConfig, writeConfig } = await import('../../shared/config')
-      const config = readConfig(sdk.workspaceRoot)
-      writeConfig(sdk.workspaceRoot, { ...config, actionWebhookUrl: 'https://example.com/webhook' })
-
       vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' }))
 
-      await expect(sdk.triggerAction(card.id, 'retry')).rejects.toThrow('Action webhook responded with 500')
+      await expect(sdk.triggerAction(card.id, 'retry')).resolves.toBeUndefined()
+
+      const logs = await sdk.listLogs(card.id)
+      expect(logs.at(-1)?.text).toBe('Action triggered: `retry`')
 
       vi.unstubAllGlobals()
     })

package/src/sdk/plugins/index.d.ts

@@ -337,6 +337,13 @@ export type StandaloneHttpHandler = (request: StandaloneHttpRequestContext) => P
  * resolved the active workspace capability selections.
  */
 export interface StandaloneHttpPluginRegistrationOptions {
+    /**
+     * Active SDK instance backing the standalone runtime, when provided by the host.
+     *
+     * Plugin registration code may use the full public {@link KanbanSDK} surface,
+     * including `getConfigSnapshot()`, when this seam is available.
+     */
+    readonly sdk?: KanbanSDK;
     /** Absolute workspace root containing `.kanban.json`. */
     readonly workspaceRoot: string;
     /** Absolute workspace `.kanban` directory. */

package/src/sdk/plugins/index.ts

@@ -623,6 +623,13 @@ export type StandaloneHttpHandler = (request: StandaloneHttpRequestContext) => P
  * resolved the active workspace capability selections.
  */
 export interface StandaloneHttpPluginRegistrationOptions {
+  /**
+   * Active SDK instance backing the standalone runtime, when provided by the host.
+   *
+   * Plugin registration code may use the full public {@link KanbanSDK} surface,
+   * including `getConfigSnapshot()`, when this seam is available.
+   */
+  readonly sdk?: KanbanSDK
   /** Absolute workspace root containing `.kanban.json`. */
   readonly workspaceRoot: string
   /** Absolute workspace `.kanban` directory. */

package/src/sdk/types.d.ts

@@ -468,29 +468,11 @@ export declare class CardStateError extends Error {
     constructor(code: CardStateErrorCode, message: string);
 }
 /**
- * Minimal SDK webhook facade supplied to CLI plugins via {@link CliPluginContext}.
- *
- * Structural subset of `KanbanSDK`; plugins should use this surface instead of
- * importing `KanbanSDK` directly so they remain decoupled from core internals.
+ * @deprecated Use {@link KanbanSDK}. CLI plugin hosts now advertise the full
+ * public SDK surface, including `getConfigSnapshot()`, instead of a narrowed
+ * webhook-only facade.
  */
-export interface CliPluginSdk {
-    /**
-     * Returns the SDK extension bag contributed by the plugin with the given id,
-     * when the host is backed by a full `KanbanSDK` instance.
-     *
-     * CLI plugins should prefer this extension path when available and fall back
-     * to compatibility methods only when running against older or mocked SDK facades.
-     */
-    getExtension?<T extends Record<string, unknown> = Record<string, unknown>>(id: string): T | undefined;
-    listWebhooks(): Webhook[];
-    createWebhook(input: {
-        url: string;
-        events: string[];
-        secret?: string;
-    }): Promise<Webhook>;
-    updateWebhook(id: string, updates: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'active'>>): Promise<Webhook | null>;
-    deleteWebhook(id: string): Promise<boolean>;
-}
+export type CliPluginSdk = KanbanSDK;
 /**
  * Runtime context supplied to a {@link KanbanCliPlugin} when it is invoked by
  * the `kl` CLI.
@@ -503,10 +485,12 @@ export interface CliPluginContext {
      *
      * Present when the plugin is invoked through the core `kl` CLI.
      * Absent in isolated unit tests or standalone invocations.
-     * Plugins should prefer this over constructing their own SDK so that
-     * SDK-level auth policy is honoured.
+    * Plugins may use the full public {@link KanbanSDK} contract here, including
+    * extension lookup and `getConfigSnapshot()`, instead of relying on older
+    * helper-only SDK facades. Plugins should prefer this over constructing their
+    * own SDK so that SDK-level auth policy is honoured.
      */
-    sdk?: CliPluginSdk;
+    sdk?: KanbanSDK;
     /**
      * Core-owned CLI auth helper.
      *

package/src/sdk/types.ts

@@ -1,5 +1,6 @@
 import type { Card, CardFormAttachment, CardFormDataMap, Priority, ResolvedFormDescriptor } from '../shared/types'
 import type { CapabilitySelections, Webhook } from '../shared/config'
+import type { KanbanSDK } from './KanbanSDK'
 import type { StorageEngine, StorageEngineType } from './plugins/types'
 import type { CardStateCursor } from './plugins'
 
@@ -615,28 +616,11 @@ export class CardStateError extends Error {
 }
 
 /**
- * Minimal SDK webhook facade supplied to CLI plugins via {@link CliPluginContext}.
- *
- * Structural subset of `KanbanSDK`; plugins should use this surface instead of
- * importing `KanbanSDK` directly so they remain decoupled from core internals.
+ * @deprecated Use {@link KanbanSDK}. CLI plugin hosts now advertise the full
+ * public SDK surface, including `getConfigSnapshot()`, instead of a narrowed
+ * webhook-only facade.
  */
-export interface CliPluginSdk {
-  /**
-   * Returns the SDK extension bag contributed by the plugin with the given id,
-   * when the host is backed by a full `KanbanSDK` instance.
-   *
-   * CLI plugins should prefer this extension path when available and fall back
-   * to compatibility methods only when running against older or mocked SDK facades.
-   */
-  getExtension?<T extends Record<string, unknown> = Record<string, unknown>>(id: string): T | undefined
-  listWebhooks(): Webhook[]
-  createWebhook(input: { url: string; events: string[]; secret?: string }): Promise<Webhook>
-  updateWebhook(
-    id: string,
-    updates: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'active'>>,
-  ): Promise<Webhook | null>
-  deleteWebhook(id: string): Promise<boolean>
-}
+export type CliPluginSdk = KanbanSDK
 
 /**
  * Runtime context supplied to a {@link KanbanCliPlugin} when it is invoked by
@@ -650,10 +634,12 @@ export interface CliPluginContext {
    *
    * Present when the plugin is invoked through the core `kl` CLI.
    * Absent in isolated unit tests or standalone invocations.
-   * Plugins should prefer this over constructing their own SDK so that
-   * SDK-level auth policy is honoured.
+   * Plugins may use the full public {@link KanbanSDK} contract here, including
+   * extension lookup and `getConfigSnapshot()`, instead of relying on older
+   * helper-only SDK facades. Plugins should prefer this over constructing their
+   * own SDK so that SDK-level auth policy is honoured.
    */
-  sdk?: CliPluginSdk
+  sdk?: KanbanSDK
   /**
    * Core-owned CLI auth helper.
    *

package/src/shared/config.ts

@@ -482,6 +482,12 @@ function loadDotEnv(dir: string): void {
  * @returns The processed node (same reference for objects/arrays; new primitive for strings).
  */
 function resolveConfigEnvVars(node: unknown, configFileName: string, nodePath = ''): unknown {
+  const isFormDefaultDataPath = /^\.forms\.(?:[^.]+|"[^"]+")\.data(?:$|[.\[])/.test(nodePath)
+
+  if (isFormDefaultDataPath) {
+    return node
+  }
+
   if (typeof node === 'string') {
     return node.replace(/\$\{([^}]+)\}/g, (_match, varName: string) => {
       const envValue = process.env[varName]