kanban-lite 1.2.2 → 1.2.4

package/dist/sdk/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';
@@ -46,6 +46,9 @@ export interface AuthStatus {
      */
     policyEnabled: boolean;
 }
+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.
  *
@@ -535,6 +538,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 */
@@ -969,21 +989,17 @@ export declare class KanbanSDK {
      */
     submitForm(input: SubmitFormInput): Promise<SubmitFormResult>;
     /**
-     * Triggers a named action for a card by POSTing to the global `actionWebhookUrl`
-     * configured in `.kanban.json`.
+     * Triggers a named action for a card.
      *
-     * The payload sent to the webhook is:
-     * ```json
-     * { "action": "retry", "board": "default", "list": "in-progress", "card": { ...sanitizedCard } }
-     * ```
+     * Validates the card, appends an activity log entry, and emits the
+     * `card.action.triggered` after-event so registered webhooks receive
+     * the action payload automatically.
      *
      * @param cardId - The ID of the card to trigger the action for.
      * @param action - The action name string (e.g. `'retry'`, `'sendEmail'`).
      * @param boardId - Optional board ID. Defaults to the workspace's default board.
-     * @returns A promise resolving when the webhook responds with 2xx.
-     * @throws {Error} If no `actionWebhookUrl` is configured in `.kanban.json`.
+     * @returns A promise that resolves when the action has been processed.
      * @throws {Error} If the card is not found.
-     * @throws {Error} If the webhook responds with a non-2xx status.
      *
      * @example
      * ```ts
@@ -1775,3 +1791,4 @@ export declare class KanbanSDK {
      */
     updateWebhook(id: string, updates: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'active'>>): Promise<Webhook | null>;
 }
+export {};

package/dist/sdk/sdk/modules/cards.d.ts

@@ -52,13 +52,22 @@ export declare function updateCard(ctx: SDKContext, { cardId, updates, boardId }
     boardId?: string;
 }): Promise<Card>;
 /**
- * Triggers a named action for a card by POSTing to the global `actionWebhookUrl`.
+ * Triggers a named action for a card.
+ *
+ * Validates the card exists, appends an activity log entry, and returns the
+ * action payload. Webhook delivery is handled by the webhook plugin via the
+ * `card.action.triggered` after-event emitted by {@link KanbanSDK.triggerAction}.
  */
 export declare function triggerAction(ctx: SDKContext, { cardId, action, boardId }: {
     cardId: string;
     action: string;
     boardId?: string;
-}): Promise<void>;
+}): Promise<{
+    action: string;
+    board: string;
+    list: string;
+    card: Omit<Card, 'filePath'>;
+}>;
 /**
  * Validates and persists a card form submission, then emits `form.submit`.
  */

package/dist/sdk/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/dist/sdk/sdk/types.d.ts

@@ -1,5 +1,6 @@
 import type { Card, CardFormAttachment, CardFormDataMap, Priority, ResolvedFormDescriptor } from '../shared/types';
-import type { CapabilitySelections, Webhook } from '../shared/config';
+import type { CapabilitySelections } from '../shared/config';
+import type { KanbanSDK } from './KanbanSDK';
 import type { StorageEngine, StorageEngineType } from './plugins/types';
 import type { CardStateCursor } from './plugins';
 export type { StorageEngine, StorageEngineType } from './plugins/types';
@@ -58,7 +59,7 @@ export type SDKBeforeEventType = 'card.create' | 'card.update' | 'card.move' | '
  *
  * @see AfterEventPayload for the payload envelope passed to after-event listeners.
  */
-export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
+export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'card.action.triggered' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
 /**
  * Union of all SDK event types (before-events and after-events).
  *
@@ -489,29 +490,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.
@@ -524,10 +507,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/dist/sdk/shared/config.d.ts

@@ -171,7 +171,10 @@ export interface KanbanConfig {
     webhooks?: Webhook[];
     /** Label definitions keyed by label name, with color and optional group. */
     labels?: Record<string, LabelDefinition>;
-    /** Optional URL to POST to when a card action is triggered. */
+    /**
+     * @deprecated Removed in favour of the webhook plugin. Register a webhook
+     * for the `card.action.triggered` event instead.
+     */
     actionWebhookUrl?: string;
     /**
      * Global auto-increment card ID counter shared across all boards.
@@ -255,6 +258,13 @@ export interface KanbanConfig {
     customHeadHtml?: string;
     /** Path to an HTML file (relative to workspace root) whose content is injected into the standalone board's `<head>` element. Takes precedence over `customHeadHtml`. */
     customHeadHtmlFile?: string;
+    /**
+     * Optional URL base path prefix for subfolder reverse-proxy deployments
+     * (e.g. `'/kanban'`). Must start with `/` and have no trailing slash.
+     * When set, all asset URLs, the WebSocket endpoint, and API routes are
+     * served under this prefix. Only applies to the standalone server.
+     */
+    basePath?: string;
 }
 /**
  * Default configuration used when no `.kanban.json` file exists or when
@@ -282,6 +292,12 @@ export declare function configPath(workspaceRoot: string): string;
  * returns the default config. If the file contains a v1 config, it is
  * automatically migrated to v2 format and persisted back to disk.
  *
+ * Any `${VAR_NAME}` placeholders found in string values are resolved against
+ * `process.env` before the config is returned. If a referenced environment
+ * variable is not set the process will throw a descriptive error rather than
+ * silently falling back to defaults, because an unresolved secret is never a
+ * safe default.
+ *
  * @param workspaceRoot - Absolute path to the workspace root directory.
  * @returns The parsed (and possibly migrated) kanban configuration.
  *