@skaile/workspaces 0.8.5

package/dist/connectors/src/rclone-config/webdav.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Render an rclone INI config snippet for a single WebDAV remote.
+ *
+ * Pure helper -- no IO, no logging -- so it can be unit-tested by string compare.
+ * The output is the full text for one `[<remoteName>]` section using rclone's
+ * `webdav` backend.
+ *
+ * NOTE: rclone's `pass` field is not plaintext; it must already be passed
+ * through `rclone obscure` by the caller. See the driver's `obscurePassword`
+ * helper for the spawn that produces it.
+ *
+ * Lives in `@skaile/workspaces/connectors/rclone-config` so both consumers can
+ * reach it: the in-container `webdav` mount driver
+ * (`ai-assets-skaile/mounts/webdav/driver.ts`) and the platform-side
+ * `RcloneFleetService` (`platform/backend/libs/session/`) which renders the
+ * same INI on the host before spawning a shared rclone process.
+ */
+/**
+ * Supported WebDAV vendor identifiers for the rclone `webdav` backend.
+ * @docLink packages/connectors/api-reference#web-dav-vendor
+ */
+export type WebDAVVendor = "nextcloud" | "owncloud" | "sharepoint" | "fastmail" | "other";
+/**
+ * Options for `renderWebDAVConfig`. Carries remote name, URL, vendor, and credentials.
+ * @docLink packages/connectors/api-reference#render-web-dav-config-options
+ */
+export interface RenderWebDAVConfigOptions {
+    /** The rclone remote section name (e.g. `skaile-docs`). */
+    remoteName: string;
+    /** Base URL of the WebDAV server. */
+    url: string;
+    /** WebDAV vendor; drives rclone's `vendor =` field. */
+    vendor: WebDAVVendor;
+    /** Basic-auth username. */
+    username?: string | null;
+    /** Already passed through `rclone obscure`. */
+    obscuredPassword?: string | null;
+    /** OAuth bearer token (used instead of basic-auth for SharePoint). */
+    bearerToken?: string | null;
+}
+/**
+ * Render an rclone INI config section for a WebDAV remote. Pure — no IO, no side effects.
+ * The `obscuredPassword` field must already have been processed through `rclone obscure`.
+ * @param opts - Remote name, URL, vendor, and credentials.
+ * @returns Full INI text for one `[<remoteName>]` rclone section.
+ * @docLink packages/connectors/api-reference#render-web-dav-config
+ */
+export declare function renderWebDAVConfig(opts: RenderWebDAVConfigOptions): string;
+//# sourceMappingURL=webdav.d.ts.map

package/dist/connectors/src/rclone-config/webdav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webdav.d.ts","sourceRoot":"","sources":["../../../../connectors/src/rclone-config/webdav.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,MAAM,CAW1E"}

package/dist/connectors/src/rclone-process-manager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * RcloneProcessManager — supervises an rclone FUSE subprocess per mount.
+ *
+ * Responsibilities:
+ *   - Spawn rclone with a per-mount config + cache dir, wait for the FUSE
+ *     mountpoint to appear, then return a handle.
+ *   - Pipe rclone's JSON-formatted log lines into the parent driver's
+ *     {@link Logger} via a child source `${driverName}+rclone`.
+ *   - Coordinate graceful stop (flush → SIGTERM → fusermount fallback).
+ *   - Expose `flush` (POST /vfs/refresh + poll /vfs/stats) and `status`
+ *     (process liveness + cache-dir size).
+ *
+ * Cross-link: see `workspaces/core/CLAUDE.md` § Logging for the
+ * `createLogger` / `LogStore` contract, and
+ * `_devlog/specs/2026-05-01-debug-logging-design.md` for the source taxonomy.
+ */
+import type { Logger } from "@skaile/workspaces/types";
+/**
+ * Spawn-time configuration for a single rclone FUSE mount.
+ * @docLink packages/connectors/api-reference#rclone-spawn-config
+ */
+export interface RcloneSpawnConfig {
+    /** Logical mount id; used as `instance` and as part of the rclone config filename. */
+    mountId: string;
+    /**
+     * Driver name (e.g. "sharepoint", "webdav"); used to derive the rclone
+     * subprocess child logger subkind: `${driverName}+rclone`.
+     */
+    driverName: string;
+    /** Absolute path inside the container where rclone will FUSE-mount. Created if missing. */
+    mountPoint: string;
+    /** Absolute path inside the container for the vfs cache. Created if missing. */
+    cacheDir: string;
+    /** Full INI text for rclone.conf (one [remote] section, named `skaile-<mountId>`). */
+    rcloneConfig: string;
+    /** Remote spec, e.g. `skaile-foo:/Clients/KADK`. */
+    remote: string;
+    /** rclone --vfs-cache-mode value. */
+    vfsCacheMode: "minimal" | "writes" | "full";
+    /** Per-mount cache size cap. Default: '5G'. */
+    cacheMaxSize?: string;
+    /** Per-mount cache age cap. Default: '168h'. */
+    cacheMaxAge?: string;
+    /**
+     * Parent driver Logger — already tagged
+     * `{kind:"mount", subkind:<driver>, instance:<mountId>}` by MountManager.
+     * Used for manager-level events; rclone subprocess events go through the
+     * derived `child({subkind: \`${driverName}+rclone\`})` logger.
+     */
+    log: Logger;
+}
+/**
+ * Handle returned by `RcloneProcessManager.spawn()` once the FUSE mountpoint is confirmed.
+ * @docLink packages/connectors/api-reference#rclone-handle
+ */
+export interface RcloneHandle {
+    /** OS process id of the rclone subprocess. */
+    pid: number;
+    /** Confirmed FUSE mountpoint (echo of input). */
+    mountPoint: string;
+    /** Cache directory (echo of input). */
+    cacheDir: string;
+    /** The local rc API address rclone is bound to, e.g. '127.0.0.1:54321'. */
+    rcAddr: string;
+}
+/**
+ * Manages rclone FUSE subprocesses for mount drivers. Stateless across instances —
+ * the internal handle registry is module-scoped so a fresh `RcloneProcessManager`
+ * can still find handles created by a previous instance.
+ * @docLink packages/connectors/api-reference#rclone-process-manager
+ */
+export declare class RcloneProcessManager {
+    /**
+     * Spawn an rclone FUSE mount. Resolves once the mountpoint is confirmed
+     * present in `/proc/self/mounts`. Throws on timeout, on early exit, or
+     * if invariants are violated.
+     */
+    spawn(config: RcloneSpawnConfig): Promise<RcloneHandle>;
+    /**
+     * Stop an rclone subprocess. Attempts a flush first, then SIGTERM, then
+     * SIGKILL + fusermount3 if `graceMs` elapses without the mountpoint
+     * disappearing.
+     */
+    stop(handle: RcloneHandle, opts?: {
+        graceMs?: number;
+    }): Promise<void>;
+    /**
+     * Force rclone to upload pending writes, then wait until the in-use
+     * counter reaches zero.
+     */
+    flush(handle: RcloneHandle): Promise<void>;
+    /** Liveness + cache-dir size. */
+    status(handle: RcloneHandle): Promise<{
+        alive: boolean;
+        cacheBytes: number;
+    }>;
+}
+/**
+ * @internal
+ * Route a single rclone log line (JSON or raw) to the appropriate Logger
+ * call. Exported for tests; not part of the public API.
+ */
+export declare function _routeRcloneLogLine(line: string, log: Logger): void;
+//# sourceMappingURL=rclone-process-manager.d.ts.map

package/dist/connectors/src/rclone-process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rclone-process-manager.d.ts","sourceRoot":"","sources":["../../../connectors/src/rclone-process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMvD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,YAAY,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAmBD;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;IA6I7D;;;;OAIG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD5E;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BhD,iCAAiC;IAC3B,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CASpF;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CA4CnE"}

package/dist/connectors/src/secrets.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Secret provider abstraction.
+ *
+ * Decouples credential resolution from process.env so secrets can be
+ * provisioned over the transport bridge instead of living in the
+ * container's environment.
+ */
+/**
+ * Read-only secret resolution. Adapters receive this interface.
+ * @docLink packages/connectors/api-reference#secret-provider
+ */
+export interface SecretProvider {
+    /**
+     * Resolve a credential reference.
+     *
+     * @param ref - Credential reference such as "env:GIT_TOKEN",
+     *   "oauth:google:user@example.com", or an inline literal.
+     * @returns The resolved secret value or undefined if not found.
+     */
+    resolve(ref: string): string | undefined;
+    /**
+     * Check whether a reference can be resolved.
+     *
+     * @param ref - Reference to check.
+     * @returns True if resolve(ref) would return a non-undefined value.
+     */
+    has(ref: string): boolean;
+    /**
+     * Return all ref strings this provider can currently resolve.
+     *
+     * @returns All resolvable refs (used by forge UI and ConnectorFieldMissingError).
+     */
+    capabilities(): string[];
+}
+/**
+ * Extends `SecretProvider` with the ability to load secrets at runtime via `provision()`.
+ * @docLink packages/connectors/api-reference#provisionable-secret-provider
+ */
+export interface ProvisionableSecretProvider extends SecretProvider {
+    /** Store a batch of key-value secrets. Keys are bare names (no prefix). */
+    provision(secrets: Record<string, string>): void;
+}
+/**
+ * In-memory secret store. Secrets are provisioned over the transport bridge
+ * and stored in a private Map — never touching the filesystem or process.env.
+ *
+ * Supports ref prefixes:
+ *   `"env:KEY"`   — looks up KEY in the store
+ *   `"vault:KEY"` — looks up KEY in the store (future vault compat)
+ *   (no prefix)   — returned as an inline value (backwards compat for non-chain usages)
+ * @docLink packages/connectors/api-reference#in-memory-secret-provider
+ */
+export declare class InMemorySecretProvider implements ProvisionableSecretProvider {
+    private readonly store;
+    /**
+     * Store a batch of key-value secrets.
+     *
+     * @param secrets - Key-value map of secret names to values. Keys are bare names (no prefix).
+     */
+    provision(secrets: Record<string, string>): void;
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+}
+/**
+ * Delegates to `process.env`. Used in CLI/standalone mode.
+ * Does NOT pass through inline literals — returns `undefined` for any ref
+ * that does not start with `"env:"`. Use `InMemorySecretProvider` for inline
+ * literals in non-chain contexts.
+ * @docLink packages/connectors/api-reference#env-secret-provider
+ */
+export declare class EnvSecretProvider implements SecretProvider {
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+}
+/**
+ * Pre-minted credential entry. Mirrors the discriminated `CredentialMint`
+ * shape from `@skaile/workspaces/types` but redeclared here to keep this package
+ * free of cross-package type dependencies.
+ *
+ * The failure branch carries the platform-side `code` + `message` so the
+ * `MountManager`'s wrapped mediator can surface the real reason instead of
+ * a generic "no pre-mint" placeholder when a mint comes back as `ok: false`.
+ */
+export type PreMintedCredential = {
+    ok: true;
+    token: string;
+    expiresAt: string | null;
+    mintedAt?: string;
+} | {
+    ok: false;
+    code?: "not-configured" | "revoked" | "provider-error" | "backend-error";
+    message?: string;
+};
+/**
+ * Pre-minted credential store. Holds short-lived tokens delivered upfront in
+ * the v3 `session_init` envelope so the runner never has to call back to the
+ * platform during mount setup.
+ *
+ * Resolves refs of the form `mount:<id>` and `connector:<id>`. Returns
+ * `undefined` for any other ref so the chain falls through to the next
+ * provider (`EnvSecretProvider` for `pat:env:NAME`, etc.).
+ *
+ * Tokens can be added/removed at runtime via {@link set} / {@link unset} so
+ * `runner.add_mount` / `runner.add_connector` / `runner.update_credential`
+ * capabilities stay strictly in-process — no round trip to the platform to
+ * mint while the mount is hot-attached.
+ *
+ * For callers that need the full mint metadata (expiry timestamp, mintedAt
+ * audit fields), use {@link mintFor} instead of the bare `resolve`. The
+ * `MountManager` consults this for the `auth: backend` initial-mint path so
+ * the driver retains the original expiry semantics.
+ *
+ * Spec: `_devlog/specs/2026-05-10-deterministic-session-bootstrap.md`.
+ *
+ * @docLink packages/connectors/api-reference#pre-minted-secret-provider
+ */
+export declare class PreMintedSecretProvider implements SecretProvider {
+    private readonly mints;
+    /**
+     * Seed pre-minted credentials from the v3 `session_init.credentials` map.
+     *
+     * Failed mints (`ok: false`) are stored too so callers can distinguish
+     * "not pre-minted" from "pre-minted but failed"; {@link resolve} treats
+     * both as `undefined`.
+     *
+     * @param credentials Optional initial `{ mounts, connectors }` map.
+     */
+    constructor(credentials?: {
+        mounts?: Record<string, PreMintedCredential>;
+        connectors?: Record<string, PreMintedCredential>;
+    });
+    /**
+     * Insert (or replace) a pre-minted credential. Used by
+     * `runner.add_mount` / `runner.add_connector` / `runner.update_credential`
+     * capability handlers when the platform delivers new credentials
+     * mid-session.
+     */
+    set(kind: "mount" | "connector", id: string, mint: PreMintedCredential): void;
+    /**
+     * Remove a stored pre-minted credential. Used by the
+     * `runner.remove_resource` capability handler.
+     */
+    unset(kind: "mount" | "connector", id: string): boolean;
+    /**
+     * Look up the full {@link PreMintedCredential} for a `mount:` /
+     * `connector:` keyed entry. Callers that only need the token use
+     * {@link resolve} via the chain; callers that need expiry / audit
+     * metadata (e.g. MountManager) use this entry point.
+     */
+    mintFor(kind: "mount" | "connector", id: string): PreMintedCredential | undefined;
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+}
+/**
+ * Forge session secret provider. Secrets are provisioned from the Forge settings
+ * panel over the transport bridge. Only handles `"forge:"` prefixed refs — returns
+ * `undefined` for all others.
+ * @docLink packages/connectors/api-reference#forge-secret-provider
+ */
+export declare class ForgeSecretProvider implements ProvisionableSecretProvider {
+    private readonly store;
+    provision(secrets: Record<string, string>): void;
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+}
+/**
+ * Thrown when an OAuth-secured connector field requires user authorization before
+ * it can be resolved. Contains the redirect URL to open in the user's browser.
+ * @docLink packages/connectors/api-reference#o-auth-required-error
+ */
+export declare class OAuthRequiredError extends Error {
+    readonly oauthRef: string;
+    readonly authUrl: string;
+    readonly state: string;
+    /**
+     * @param oauthRef - The 'oauth:<service>:<account>' ref that triggered the error
+     * @param authUrl - Browser URL to open for OAuth authorization
+     * @param state - OAuth state token for CSRF protection and callback correlation
+     */
+    constructor(oauthRef: string, authUrl: string, state: string);
+}
+/**
+ * Shape of an OAuth token bundle stored by `OAuthSecretProvider`.
+ * @docLink packages/connectors/api-reference#o-auth-token-bundle
+ */
+export interface OAuthTokenBundle {
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix timestamp in ms */
+    expiry?: number;
+}
+/**
+ * Return value of `OAuthSecretProvider.initiateFlow()`. Contains the URL and CSRF state token.
+ * @docLink packages/connectors/api-reference#o-auth-flow-request
+ */
+export interface OAuthFlowRequest {
+    authUrl: string;
+    state: string;
+}
+/**
+ * OAuth token provider. Handles `"oauth:<service>:<account>"` refs.
+ * Callers must call `chain.prepareRef()` before `chain.resolve()` for `oauth:` refs.
+ * @docLink packages/connectors/api-reference#o-auth-secret-provider
+ */
+export interface OAuthSecretProvider extends SecretProvider {
+    /**
+     * Ensure the token for this ref is fresh.
+     * Refreshes if expired.
+     * Throws OAuthRequiredError if no token exists and user authorization is needed.
+     */
+    ensureFresh(ref: string): Promise<void>;
+    /** Initiate the OAuth authorization flow. Returns URL to open in the user's browser. */
+    initiateFlow(oauthService: string, account: string): Promise<OAuthFlowRequest>;
+    /** Exchange authorization code for tokens and store the bundle. */
+    completeFlow(state: string, code: string): Promise<void>;
+}
+/**
+ * Abstract base for vault-backed secret providers (1Password, KeePass). Subclasses
+ * implement `prefix` and `loadKeys()`. Locked until `unlock(credential)` is called.
+ * @docLink packages/connectors/api-reference#locked-secret-provider
+ */
+export declare abstract class LockedSecretProvider implements SecretProvider {
+    locked: boolean;
+    protected readonly store: Map<string, string>;
+    abstract readonly prefix: string;
+    unlock(credential: string): Promise<void>;
+    protected abstract loadKeys(credential: string): Promise<void>;
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+}
+/**
+ * Chains multiple `SecretProvider` instances into a single resolver.
+ * - Prefixed refs (`env:`, `forge:`, `op:`, `kp:`, `oauth:`) are routed to the first provider that can resolve them.
+ * - Bare refs waterfall through all providers in order.
+ * - Plain literals in `skaile.yaml` options are NOT passed to the chain; `ConnectorManager` handles them before calling `resolve()`.
+ * @docLink packages/connectors/api-reference#secret-provider-chain
+ */
+export declare class SecretProviderChain implements SecretProvider {
+    private readonly providers;
+    /**
+     * @param providers - Ordered list of providers. For prefixed refs, the first
+     *   provider that can resolve wins. For bare refs, waterfall through all in order.
+     */
+    constructor(providers: SecretProvider[]);
+    resolve(ref: string): string | undefined;
+    has(ref: string): boolean;
+    capabilities(): string[];
+    /** Returns the first provider that can resolve this ref. */
+    providerFor(ref: string): SecretProvider | undefined;
+    /**
+     * Calls ensureFresh(ref) on the owning provider if it implements OAuthSecretProvider.
+     * No-op for providers that don't have ensureFresh().
+     *
+     * @param ref - Must be an "oauth:" prefixed ref for this to have any effect.
+     *   Calls ensureFresh() on the owning OAuthSecretProvider.
+     */
+    prepareRef(ref: string): Promise<void>;
+}
+//# sourceMappingURL=secrets.d.ts.map

package/dist/connectors/src/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../connectors/src/secrets.ts"],"names":[],"mappings":"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"}

package/dist/connectors/src/shared-types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared types used by both mounts and connectors.
+ *
+ * These are the content, options, and infrastructure types that the mount
+ * driver interface and the connector adapter interface both depend on.
+ */
+/**
+ * Content payload returned from and accepted by connector read/write operations.
+ * @docLink packages/connectors/concepts#connector-content
+ */
+export interface ConnectorContent {
+    /** Raw data: UTF-8 string or binary Buffer. */
+    data: string | Buffer;
+    /** Encoding hint for downstream consumers. */
+    encoding?: "utf-8" | "binary";
+    /** MIME type, e.g. `"application/json"` or `"text/plain"`. */
+    contentType?: string;
+    /** Adapter-specific metadata (e.g. ETag, last-modified). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Single entry in a list response from a connector or mount.
+ * @docLink packages/connectors/concepts#connector-entry
+ */
+export interface ConnectorEntry {
+    /** Display name of the entry. */
+    name: string;
+    /** Full path or key used to address this entry. */
+    path: string;
+    /** Entry kind: file-system concept or logical data record. */
+    type: "file" | "directory" | "key" | "row" | "message";
+    /** Size in bytes, when known. */
+    size?: number;
+    /** Last-modified timestamp, when known. */
+    modifiedAt?: Date;
+}
+/**
+ * Single match returned from a search operation.
+ * @docLink packages/connectors/concepts#search-result
+ */
+export interface SearchResult {
+    /** Path or key of the matching entry. */
+    path: string;
+    /** Surrounding text fragment shown to the agent. */
+    snippet?: string;
+    /** Line number of the match (text files). */
+    line?: number;
+    /** Relevance score; higher is more relevant. */
+    score?: number;
+}
+/**
+ * Summary returned after a sync (pull) operation.
+ * @docLink packages/connectors/concepts#sync-result
+ */
+export interface SyncResult {
+    /** Number of files written to the local mount directory. */
+    filesWritten: number;
+    /** Number of local files deleted because they were removed upstream. */
+    filesDeleted: number;
+    /** Total bytes transferred during the sync. */
+    bytesTransferred: number;
+}
+/**
+ * Options for listing entries in a connector or mount.
+ * @docLink packages/connectors/concepts#list-options
+ */
+export interface ListOptions {
+    /** When true, recurse into subdirectories. */
+    recursive?: boolean;
+    /** Glob filter applied server-side when supported by the adapter. */
+    glob?: string;
+    /** Maximum number of entries to return. */
+    limit?: number;
+}
+/**
+ * Options for search operations across a connector or mount.
+ * @docLink packages/connectors/concepts#search-options
+ */
+export interface SearchOptions {
+    /** Treat the query string as a regular expression. */
+    regex?: boolean;
+    /** Case-sensitive matching; defaults to false. */
+    caseSensitive?: boolean;
+    /** Maximum number of results to return. */
+    maxResults?: number;
+}
+/**
+ * Options passed to a sync (pull) operation.
+ * @docLink packages/connectors/concepts#sync-options
+ */
+export interface SyncOptions {
+    strategy?: "full" | "incremental";
+    include?: string[];
+    exclude?: string[];
+    /** Called by the adapter to report sync progress (stubs ready, downloads, etc.). */
+    onSyncStatus?: (status: SyncStatusPayload) => void;
+}
+/**
+ * Progress payload delivered to `SyncOptions.onSyncStatus` during a sync operation.
+ * @docLink packages/connectors/concepts#sync-status-payload
+ */
+export interface SyncStatusPayload {
+    /** Current phase of the sync. */
+    phase: "enumerating" | "stubs_ready" | "downloading" | "initial_sync_complete" | "error";
+    /** Total number of files found in the remote source. */
+    totalFiles: number;
+    /** Number of files fully downloaded so far. */
+    downloadedFiles: number;
+    /** Number of stub (placeholder) files created. */
+    stubFiles: number;
+    /** Human-readable status message. */
+    message: string;
+}
+/**
+ * Self-description of a single adapter operation, used to generate both SDK tools and system prompt docs.
+ * @docLink packages/connectors/concepts#operation-descriptor
+ */
+export interface OperationDescriptor {
+    /** Operation name: "query", "commit", "get", "set", etc. */
+    name: string;
+    /** Human-readable description shown to agents. */
+    description: string;
+    /** Which access level this operation needs. */
+    accessLevel: "read" | "write";
+    /** Argument definitions. */
+    args: ArgumentDescriptor[];
+    /** Usage examples shown in system prompt. */
+    examples?: string[];
+}
+/**
+ * Typed argument declaration within an `OperationDescriptor`.
+ * @docLink packages/connectors/concepts#argument-descriptor
+ */
+export interface ArgumentDescriptor {
+    /** Argument name used as the CLI flag (without `--` prefix). */
+    name: string;
+    /** Human-readable description shown to agents. */
+    description: string;
+    /** JSON-compatible primitive type. */
+    type: "string" | "number" | "boolean" | "json";
+    /** When true, the operation fails if this argument is absent. */
+    required: boolean;
+    /** Default value used when the argument is omitted. */
+    default?: unknown;
+}
+/**
+ * How an adapter detects changes:
+ * - `native`    — OS-level watchers (inotify/FSEvents) or backend-native push (redis keyspace, pg NOTIFY)
+ * - `operation` — change detected from own write()/executeOp() calls (in-process adapters)
+ * - `poll`      — periodic re-list diffing (S3, WebDAV)
+ */
+export type WatchStrategy = "native" | "operation" | "poll";
+/**
+ * Options accepted by `watch()` on both mount drivers and connector adapters.
+ * @docLink packages/connectors/concepts#watch-options
+ */
+export interface WatchOptions {
+    /** Glob patterns to ignore (merged with adapter defaults). */
+    ignored?: string[];
+    /** Debounce interval in ms. Default: 150. */
+    debounceMs?: number;
+}
+/**
+ * Opaque handle returned by `watch()` — close it to stop receiving events.
+ * @docLink packages/connectors/concepts#watch-handle
+ */
+export interface WatchHandle {
+    /** Stop watching and release all OS-level resources. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=shared-types.d.ts.map

package/dist/connectors/src/shared-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-types.d.ts","sourceRoot":"","sources":["../../../connectors/src/shared-types.ts"],"names":[],"mappings":"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"}

package/dist/connectors/src/watcher.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared filesystem watcher factory for mountable adapters.
+ *
+ * Uses chokidar for cross-platform, debounced file watching.
+ *
+ * Automatically reads .gitignore from the watched directory and merges
+ * those patterns into chokidar's ignore list. This prevents scanning
+ * large generated directories (node_modules, dist, .next, etc.) that
+ * most projects already declare as ignored.
+ */
+import type { MountChangeEvent } from "./mount-types.js";
+import type { WatchHandle, WatchOptions } from "./shared-types.js";
+/**
+ * Create a cross-platform filesystem watcher on `rootDir` using chokidar.
+ * Auto-reads `.gitignore` from `rootDir` and merges those patterns into the ignore list.
+ * @param rootDir - Absolute path to the directory to watch.
+ * @param callback - Called with each `MountChangeEvent` (create / edit / delete).
+ * @param options - Debounce interval and additional ignore patterns.
+ * @returns A `WatchHandle` — call `.close()` to stop watching.
+ * @docLink packages/connectors/api-reference#create-fs-watcher
+ */
+export declare function createFsWatcher(rootDir: string, callback: (event: MountChangeEvent) => void, options?: WatchOptions): Promise<WatchHandle>;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/connectors/src/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../connectors/src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA6HnE;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,CA0CtB"}