@skaile/workspaces 0.8.5

package/dist/connectors/src/mount-manager.d.ts

@@ -0,0 +1,147 @@
+/**
+ * MountManager — manages mount lifecycle: mount, sync, watch, unmount, hot-plug.
+ *
+ * Orchestrates `MountDriver` instances resolved from the mount registry.
+ * Each mounted resource is tracked by its declaration ID and can be individually
+ * mounted, unmounted, synced, or watched at any time (hot-plug).
+ *
+ * @docLink packages/connectors/concepts#mount-manager
+ */
+import type { CatalogEntry } from "@skaile/workspaces/core";
+import { type MountChangeEvent, type MountDeclaration, type MountDriver, type MountHandle, type MountInfo, type MountReport, type TokenMediator } from "./mount-types.js";
+import type { PreMintedSecretProvider, SecretProvider } from "./secrets.js";
+import type { SyncOptions, SyncResult, WatchHandle, WatchOptions } from "./shared-types.js";
+interface MountedEntry {
+    driver: MountDriver;
+    handle: MountHandle;
+    declaration: MountDeclaration;
+    watchHandle?: WatchHandle;
+}
+interface LifecycleResult {
+    id: string;
+    ok: boolean;
+    error?: string;
+    detail?: string;
+}
+/**
+ * Manages the full lifecycle of workspace mounts: mounting, unmounting, syncing,
+ * and watching for filesystem changes. Resolves drivers from the registry or catalog.
+ * @docLink packages/connectors/concepts#mount-manager
+ */
+export declare class MountManager {
+    private mounts;
+    readonly workspaceDir: string;
+    private readonly secrets?;
+    private readonly catalogEntries;
+    private readonly tokenMediator?;
+    private readonly preMintedSecrets?;
+    private readonly mgrLog;
+    /**
+     * @param workspaceDir - Working directory for resolving relative mount paths.
+     * @param secretsOrOpts - Optional secret provider, or an options object with
+     *   `secrets` and/or `catalogEntries` and/or `tokenMediator` and/or
+     *   `preMintedSecrets`. The token mediator handles refresh + retry-401
+     *   paths; the pre-minted secret provider answers the initial-mint
+     *   lookup for `auth: backend` mounts without a round trip to the
+     *   platform (since v3 / `session_init`).
+     */
+    constructor(workspaceDir: string, secretsOrOpts?: SecretProvider | {
+        secrets?: SecretProvider;
+        catalogEntries?: CatalogEntry[];
+        tokenMediator?: TokenMediator;
+        preMintedSecrets?: PreMintedSecretProvider;
+    });
+    /**
+     * Wrap the user-supplied {@link TokenMediator} so that `reason: 'initial'`
+     * calls for an `auth: backend` mount first consult the pre-minted
+     * credentials delivered with the v3 `session_init` envelope. Falls back
+     * to the original mediator for refresh / retry-401 paths and for
+     * `reason: 'initial'` lookups that have no pre-minted entry.
+     *
+     * Built once at construction is tempting but the mediator is set on
+     * `this.tokenMediator` after the wrap; building lazily keeps the wrapped
+     * surface symmetric with the underlying field.
+     */
+    private buildWrappedMediator;
+    private resolveDriver;
+    /**
+     * Mount all declared mounts. Continues mounting remaining mounts even when one fails,
+     * so the caller always receives a full report.
+     *
+     * @param declarations - Mount declarations from `skaile.yaml`.
+     * @param options - When `failOnReadWriteError: true`, throws {@link MountStartupError}
+     *   after collecting the full report if any `read-write` mount failed. Read-only
+     *   mount failures never throw — they are tolerated as degraded state.
+     *
+     * @returns MountReport with per-mount success/error/mountPath/access.
+     * @throws {MountStartupError} when `failOnReadWriteError` is true and any RW mount failed.
+     */
+    mountAll(declarations: MountDeclaration[], options?: {
+        failOnReadWriteError?: boolean;
+    }): Promise<MountReport>;
+    /** Unmount all mounts and stop all watchers. Best-effort — ignores unmount errors. */
+    unmountAll(): Promise<void>;
+    /**
+     * Mount a single resource (hot-plug). For local driver with absolute source and no
+     * explicit target, binds directly to the source path.
+     *
+     * @returns The MountHandle with the resolved mountPath.
+     */
+    mount(declaration: MountDeclaration): Promise<MountHandle>;
+    /**
+     * Unmount a single mount by ID and stop its watcher.
+     *
+     * @throws {Error} if the mount is not found
+     */
+    unmount(id: string): Promise<void>;
+    /** Sync all mounted mounts. */
+    syncAll(options?: SyncOptions): Promise<void>;
+    /**
+     * Sync a single mount (pull latest remote state).
+     *
+     * @throws {Error} if the mount is not found
+     */
+    sync(id: string, options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Subscribe to filesystem change events for all mounted mounts.
+     * Respects the watch flag on each declaration (default: watch read-write, skip read-only).
+     * Automatically excludes nested mount paths from parent watchers.
+     */
+    watchAll(callback: (mountId: string, event: MountChangeEvent) => void, options?: WatchOptions): void;
+    /** Stop all active filesystem watchers. */
+    unwatchAll(): Promise<void>;
+    hibernateAll(): Promise<LifecycleResult[]>;
+    closeAll(): Promise<LifecycleResult[]>;
+    private runLifecycleHook;
+    /**
+     * Return the internal MountedEntry entry for a mount.
+     *
+     * @throws {Error} if the mount is not found
+     */
+    get(id: string): MountedEntry;
+    has(id: string): boolean;
+    /**
+     * Return summary info for all currently mounted mounts.
+     *
+     * @returns Array of MountInfo with paths relative to workspaceDir where possible.
+     */
+    listMounts(): MountInfo[];
+    /**
+     * Return the subset of currently mounted mounts whose driver is `git`,
+     * surfacing the fields prompt-builders need (source URL +
+     * `exposeAccessToken` flag) plus the `auth` ref so consumers (the runner's
+     * refresh-flag watcher) can decide whether the mount is eligible for
+     * backend-mediated refresh.
+     *
+     * Used by `buildMountPromptSection` for Tier-1/Tier-2 guidance and by
+     * the runner's wake-mid-401 refresh handler.
+     */
+    listGitMounts(): Array<{
+        id: string;
+        source: string;
+        exposeAccessToken: boolean;
+        auth?: string;
+    }>;
+}
+export {};
+//# sourceMappingURL=mount-manager.d.ts.map

package/dist/connectors/src/mount-manager.d.ts.map

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

package/dist/connectors/src/mount-prompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build a markdown section describing mounted resources for the system prompt.
+ */
+import type { MountManager } from "./mount-manager.js";
+/**
+ * Build a markdown section describing all mounted resources for the agent's system prompt.
+ * Emits a table of mount IDs, drivers, paths, and access levels, plus Tier-1/Tier-2 git auth guidance.
+ * @param manager - The `MountManager` after `mountAll()` has been called.
+ * @returns Markdown string to append to the system prompt, or an empty string when no mounts are active.
+ * @docLink packages/connectors/api-reference#build-mount-prompt-section
+ */
+export declare function buildMountPromptSection(manager: MountManager): string;
+//# sourceMappingURL=mount-prompt.d.ts.map

package/dist/connectors/src/mount-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-prompt.d.ts","sourceRoot":"","sources":["../../../connectors/src/mount-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAgDrE"}

package/dist/connectors/src/mount-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Mount driver registry.
+ *
+ * Built-in mount drivers from `@skaile/base-assets` are pre-registered here
+ * via static ESM imports of their subpath exports so they are bundled into
+ * any `bun --compile`'d agent binary AND any tsup-emitted ESM tarball.
+ * The catalog path in `MountManager.resolveDriver`
+ * (`await import(driverPath)` of raw TS) is a dev-only fallback for
+ * project-local third-party drivers — it cannot work inside a compiled
+ * binary because bun cannot share its bundled symbol graph with
+ * externally-loaded TS files (the import silently hangs while trying to
+ * resolve `@skaile/workspaces/connectors` against an absent `node_modules`).
+ *
+ * **Static import discipline.** Every subpath specifier below must be a
+ * string-literal `from "@skaile/workspaces/base-assets/mounts/<name>"` —
+ * never aliased through a variable. The same rule applies in
+ * `connector-registry.ts`, `connector-tools.ts`, and `bridge/`; indirection
+ * defeats `bun --compile`'s static analysis and silently drops the module
+ * from the binary. Regression test:
+ * `tests/connector-tools-regression.test.ts`.
+ */
+import type { MountDriver, MountDriverFactory } from "./mount-types.js";
+/**
+ * Register a mount driver factory under `name`. Overwrites any existing registration.
+ * @param name - Driver key used in `skaile.yaml` `driver:` fields (e.g. `"git"`, `"s3"`).
+ * @param factory - Factory function that returns a fresh driver instance.
+ * @docLink packages/connectors/api-reference#register-mount-driver
+ */
+export declare function registerMountDriver(name: string, factory: MountDriverFactory): void;
+/**
+ * Get a mount driver by name, calling its factory.
+ * @param name - Driver key (e.g. `"git"`).
+ * @returns A fresh driver instance.
+ * @throws {Error} when no driver is registered under `name`.
+ * @docLink packages/connectors/api-reference#get-mount-driver
+ */
+export declare function getMountDriver(name: string): MountDriver;
+/**
+ * Get a mount driver by name, or return `undefined` if not registered.
+ * @param name - Driver key.
+ * @returns A fresh driver instance or `undefined`.
+ * @docLink packages/connectors/api-reference#try-get-mount-driver
+ */
+export declare function tryGetMountDriver(name: string): MountDriver | undefined;
+/**
+ * Return the names of all currently registered mount drivers.
+ * @returns Array of driver keys (e.g. `["git", "s3", "webdav"]`).
+ * @docLink packages/connectors/api-reference#list-mount-drivers
+ */
+export declare function listMountDrivers(): string[];
+/**
+ * Register every built-in mount driver from `@skaile/base-assets`.
+ *
+ * Factories close over the statically-imported `createDriver` functions
+ * at the top of this file. Both `bun --compile` and tsup follow the
+ * string-literal `import ... from "@skaile/workspaces/base-assets/mounts/..."`
+ * specifiers at build time and bundle the driver plus its transitive
+ * `@skaile/*` deps. This sidesteps the catalog path's runtime TS-import hang.
+ */
+export declare function registerBuiltinMountDrivers(): void;
+//# sourceMappingURL=mount-registry.d.ts.map

package/dist/connectors/src/mount-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-registry.d.ts","sourceRoot":"","sources":["../../../connectors/src/mount-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAWxE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAQxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CASlD"}

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

@@ -0,0 +1,222 @@
+/**
+ * Mount driver infrastructure types.
+ *
+ * Mounts are filesystem projections that project remote content (git repos, S3 buckets,
+ * WebDAV shares, etc.) into a local directory. Agents read and write files directly
+ * through the mount point. The mount driver manages mounting, unmounting, sync,
+ * and optional change watching.
+ *
+ * @docLink packages/connectors/concepts#mount-types
+ */
+import type { SecretProvider } from "./secrets.js";
+import type { SyncOptions, SyncResult, WatchHandle, WatchOptions } from "./shared-types.js";
+/**
+ * Result of a single `TokenMediator` call. Mirrors
+ * `AccessTokenResponseEvent.result` from `@skaile/workspaces/types` so the runner
+ * can pass it straight through.
+ *
+ * @docLink packages/connectors/api-reference#token-mediator
+ */
+export type TokenMediatorResult = {
+    ok: true;
+    /** Access token to use for the next git operation. */
+    token: string;
+    /**
+     * ISO-8601 expiry, or `null` for indefinite tokens (static PATs). Drives
+     * whether the driver schedules a refresh tick.
+     */
+    expiresAt: string | null;
+    /** Optional scope/permissions list, surfaced in audit logs. */
+    scope?: string[];
+} | {
+    ok: false;
+    code: "not-configured" | "revoked" | "provider-error" | "backend-error" | "timeout";
+    /** Human-readable detail, never carries secrets. */
+    message: string;
+};
+/**
+ * Function signature mount drivers use to acquire a fresh access token from
+ * the runner-owned backend mediator. Implemented by the runner: emits a
+ * `request_access_token` command over the transport and resolves with the
+ * matching `access_token_response` payload.
+ *
+ * Drivers MUST treat this as the only token source when the parsed
+ * `MountAuthRef.kind === 'backend'`. Local minting (PAT, OAuth, GitHub App)
+ * has been removed from the runner — provider dispatch lives on the platform.
+ *
+ * @docLink packages/connectors/api-reference#token-mediator
+ */
+export type TokenMediator = (input: {
+    mountId: string;
+    reason: "initial" | "refresh" | "retry-401";
+}) => Promise<TokenMediatorResult>;
+/**
+ * Parsed mount configuration from `skaile.yaml`, passed to `MountDriver.mount()` and managed by `MountManager`.
+ * @docLink packages/connectors/concepts#mount-declaration
+ */
+export interface MountDeclaration {
+    /** Unique identifier for this mount instance. */
+    id: string;
+    /** Driver type: "git", "s3", "webdav", "local", etc. */
+    driver: string;
+    /** Source URL or path (e.g. repo URL, bucket name, host path). */
+    source: string;
+    /** Override mount target directory (default: .mounts/<id>/). */
+    target?: string;
+    /** Access level enforced by the manager. */
+    access: "read-only" | "read-write";
+    /** Credential reference: "env:VAR_NAME" or inline value. */
+    auth?: string;
+    /**
+     * Whether to watch this mount for filesystem changes.
+     * - `true`  - always watch (e.g. SharePoint read-only with background sync)
+     * - `false` - never watch (e.g. large static mount you don't need change events for)
+     * - omitted - auto: watch read-write mounts, skip read-only
+     */
+    watch?: boolean;
+    /**
+     * **Expert-only.** When `true`, the mount manager wires the resolved
+     * credential into the workspace so the agent's interactive `git`/`curl`
+     * tools can authenticate directly against the mount's host. Defaults to
+     * `false` — agents have no credential exposure and rely on driver-managed
+     * pulls/pushes. See the spec at `_devlog/specs/2026-05-05-git-credential-tiers.md`.
+     *
+     * Sensitive: enabling this gives prompt-injected agents direct CLI access
+     * to whatever scope the credential carries. Refresh-capable providers
+     * (OAuth, GitHub App) bound the blast radius via TTL; static PATs do not.
+     */
+    exposeAccessToken?: boolean;
+    /**
+     * Optional override for the access token TTL (seconds). When omitted, the
+     * provider's natural TTL is used (3600s for GitHub App, ~8h for OAuth, N/A
+     * for PAT). Values above the provider's documented maximum are silently
+     * lowered to the cap and a `warning=ttl-capped` log entry is emitted.
+     */
+    accessTokenTTL?: number;
+    /** Driver-specific configuration. */
+    options?: Record<string, unknown>;
+}
+/**
+ * Live state of a mounted resource, returned by `MountDriver.mount()` and held by `MountManager`.
+ * @docLink packages/connectors/concepts#mount-handle
+ */
+export interface MountHandle {
+    /** Mount declaration ID. */
+    readonly id: string;
+    /** Driver name. */
+    readonly driver: string;
+    /** Effective access level. */
+    readonly access: "read-only" | "read-write";
+    /** Absolute path to the mounted directory. */
+    readonly mountPath: string;
+    /** Whether the resource is currently mounted. */
+    mounted: boolean;
+    /** Driver-specific state. Opaque to callers. */
+    state: unknown;
+}
+/**
+ * Filesystem change event emitted by a mount driver's `watch()` implementation.
+ * @docLink packages/connectors/concepts#mount-change-event
+ */
+export interface MountChangeEvent {
+    /** Relative path within the mount. */
+    path: string;
+    /** What happened. */
+    action: "create" | "edit" | "delete" | "conflict";
+    /** What caused the change. */
+    source: "filesystem" | "remote" | "sync";
+}
+/**
+ * Summary of a mounted resource returned by `MountManager.listMounts()`.
+ * @docLink packages/connectors/concepts#mount-info
+ */
+export interface MountInfo {
+    id: string;
+    driver: string;
+    access: "read-only" | "read-write";
+    mountPath: string;
+    /** Whether the resource is currently mounted. */
+    mounted: boolean;
+    /** Source URL or path declared in the mount configuration. */
+    source: string;
+}
+/**
+ * Bulk mount result returned by `MountManager.mountAll()`.
+ * @docLink packages/connectors/concepts#mount-report
+ */
+export interface MountReport {
+    results: Array<{
+        id: string;
+        mounted: boolean;
+        mountPath?: string;
+        error?: string;
+        /** Access level of the declaration; preserved so callers can distinguish RW from RO failures. */
+        access?: "read-only" | "read-write";
+    }>;
+}
+/**
+ * Thrown by `MountManager.mountAll` when at least one read-write mount fails
+ * and `failOnReadWriteError: true` was set. Carries the full `MountReport` so
+ * the caller can inspect successful mounts and read-only failures.
+ * @docLink packages/connectors/concepts#mount-startup-error
+ */
+export declare class MountStartupError extends Error {
+    readonly report: MountReport;
+    readonly failedReadWriteMounts: ReadonlyArray<{
+        id: string;
+        error: string;
+    }>;
+    constructor(message: string, report: MountReport, failedReadWriteMounts: ReadonlyArray<{
+        id: string;
+        error: string;
+    }>);
+}
+/**
+ * Contract for mount driver implementations. Drivers mount remote content
+ * (git repos, S3 buckets, WebDAV shares) into a local directory. Extend
+ * `AbstractMountDriver` for base registration and a default `watch()` no-op.
+ * @docLink packages/connectors/concepts#mount-driver
+ */
+export interface MountDriver {
+    /** Driver type identifier: "git", "s3", "webdav", "local", etc. */
+    readonly name: string;
+    /**
+     * Mount the mount's source content into targetDir and return a handle.
+     * Creates targetDir if it doesn't exist.
+     *
+     * @param declaration - Mount configuration from skaile.yaml
+     * @param targetDir - Absolute path to the directory where content will be mounted
+     * @param secrets - Secret provider for resolving credential references
+     * @param tokenMediator - Optional callback used by `auth: backend` git mounts
+     *   to request short-lived access tokens from the platform's credential
+     *   mediator. Absent in standalone CLI contexts; required for any mount
+     *   declaring `auth: backend`.
+     */
+    mount(declaration: MountDeclaration, targetDir: string, secrets?: SecretProvider, tokenMediator?: TokenMediator): Promise<MountHandle>;
+    /** Unmount and release all resources held by this mount. */
+    unmount(handle: MountHandle): Promise<void>;
+    /** Pull the latest remote state into the mounted directory. */
+    sync(handle: MountHandle, options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Subscribe to filesystem changes within the mount. The mechanism is
+     * driver-specific: OS-level watchers for local/git, periodic diffing for S3/WebDAV.
+     */
+    watch?(handle: MountHandle, callback: (event: MountChangeEvent) => void, options?: WatchOptions): WatchHandle;
+    /**
+     * Called before the container hibernates. Drivers should persist
+     * unsaved state (e.g. git commit + push). Return a detail string
+     * (e.g. commit SHA) or void.
+     */
+    onHibernate?(handle: MountHandle): Promise<string | undefined>;
+    /**
+     * Called when the session is closing. Drivers should finalize work
+     * (e.g. merge branch, push). Return a detail string or void.
+     */
+    onSessionClose?(handle: MountHandle): Promise<string | undefined>;
+}
+/**
+ * Factory function signature used by the mount registry.
+ * @docLink packages/connectors/api-reference#mount-driver-factory
+ */
+export type MountDriverFactory = () => MountDriver;
+//# sourceMappingURL=mount-types.d.ts.map

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

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

package/dist/connectors/src/npm-installer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * NpmInstaller — wraps `bun add` to install peer dependencies for connectors.
+ *
+ * Accepts an injectable `spawn` function so tests can verify calls without
+ * running a real subprocess.
+ */
+/**
+ * Result returned by the injectable `SpawnFn`.
+ * @docLink packages/connectors/api-reference#spawn-result
+ */
+export interface SpawnResult {
+    /** Process exit code. Zero means success. */
+    exitCode: number;
+    /** Combined stdout + stderr output from the subprocess. */
+    output: string;
+}
+/**
+ * Injectable subprocess spawn function used by `installNpmPackages` and test doubles.
+ * @docLink packages/connectors/api-reference#spawn-fn
+ */
+export type SpawnFn = (cmd: string[], opts: {
+    cwd: string;
+}) => Promise<SpawnResult>;
+/**
+ * Options for `installNpmPackages`. Pass a custom `spawn` to test without running real subprocesses.
+ * @docLink packages/connectors/api-reference#install-options
+ */
+export interface InstallOptions {
+    /** Injectable spawn function. Defaults to a real `Bun.spawn` wrapper. */
+    spawn?: SpawnFn;
+}
+/**
+ * Result returned by `installNpmPackages`.
+ * @docLink packages/connectors/api-reference#install-result
+ */
+export interface InstallResult {
+    /** `true` when the subprocess exited with code 0. */
+    success: boolean;
+    /** Combined stdout + stderr from the `bun add` invocation. */
+    output: string;
+}
+/** Default spawn implementation using Bun's subprocess API. */
+export declare function defaultSpawn(cmd: string[], opts: {
+    cwd: string;
+}): Promise<SpawnResult>;
+/**
+ * Install npm packages as optional peer deps using `bun add --optional`.
+ *
+ * @param packages Package names to install (e.g. ["pg", "@types/pg"]).
+ * @param projectDir Absolute path to the project root (where bun.lock lives).
+ * @param opts Injectable options for testing.
+ */
+export declare function installNpmPackages(packages: string[], projectDir: string, opts?: InstallOptions): Promise<InstallResult>;
+/**
+ * Check whether an npm package can be resolved from `projectDir`'s module
+ * graph. Returns true when `require.resolve` finds the package, false on any
+ * resolution failure (missing, broken, etc.). Does not load the module — only
+ * verifies it can be located.
+ *
+ * Use this to decide whether `installNpmPackages` needs to run before a
+ * connector adapter or mount driver tries to `import` its peer dep.
+ */
+export declare function isPackageResolvable(pkg: string, projectDir: string): boolean;
+/**
+ * Filter a list of npm packages down to those that cannot be resolved from
+ * `projectDir`. Convenience for "install only what's missing" call sites.
+ */
+export declare function findMissingPackages(packages: string[], projectDir: string): string[];
+//# sourceMappingURL=npm-installer.d.ts.map

package/dist/connectors/src/npm-installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-installer.d.ts","sourceRoot":"","sources":["../../../connectors/src/npm-installer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+DAA+D;AAC/D,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAY7F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAQ5E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpF"}

package/dist/connectors/src/port-pool.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PortPool — allocates ports from a [min, max] range, checks OS for collisions.
+ */
+/**
+ * Allocates TCP ports from a `[min, max]` range with OS-level collision detection.
+ * Used by service connector adapters (devserver, static-server) to assign local ports.
+ * @docLink packages/connectors/api-reference#port-pool
+ */
+export declare class PortPool {
+    private readonly min;
+    private readonly max;
+    private readonly inUse;
+    constructor(range: [number, number]);
+    /** Allocate the next free port from the range. Checks OS for collisions. */
+    allocate(): Promise<number>;
+    /** Mark a port as in-use (for explicit port args or registered instances). */
+    reserve(port: number): void;
+    /** Return a port to the pool. */
+    release(port: number): void;
+    /** Check if a port is currently tracked as in-use. */
+    isInUse(port: number): boolean;
+    /** Quick TCP connect test — returns true if nothing is listening. */
+    static isPortFree(port: number, host?: string): Promise<boolean>;
+}
+//# sourceMappingURL=port-pool.d.ts.map

package/dist/connectors/src/port-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-pool.d.ts","sourceRoot":"","sources":["../../../connectors/src/port-pool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IAKnC,4EAA4E;IACtE,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAajC,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,iCAAiC;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,sDAAsD;IACtD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,qEAAqE;IACrE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAc,GAAG,OAAO,CAAC,OAAO,CAAC;CAiBtE"}

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

@@ -0,0 +1,8 @@
+/**
+ * rclone INI rendering helpers — pure string-template functions for one
+ * `[remote]` section per backend. Consumed by both the in-container mount
+ * drivers and the platform-side fleet service.
+ */
+export { type RenderOneDriveConfigOptions, renderOneDriveConfig } from "./onedrive.js";
+export { type RenderWebDAVConfigOptions, renderWebDAVConfig, type WebDAVVendor, } from "./webdav.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../connectors/src/rclone-config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EACL,KAAK,yBAAyB,EAC9B,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * Render an rclone INI config snippet for a single OneDrive/SharePoint 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
+ * `onedrive` backend. The OAuth `token` field is a single-line JSON literal as
+ * rclone expects.
+ *
+ * Lives in `@skaile/workspaces/connectors/rclone-config` so both consumers can
+ * reach it: the in-container `sharepoint` mount driver
+ * (`ai-assets-skaile/mounts/sharepoint/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.
+ */
+/**
+ * Options for `renderOneDriveConfig`. Carries OAuth token, drive ID, and optional tenant/client credentials.
+ * @docLink packages/connectors/api-reference#render-one-drive-config-options
+ */
+export interface RenderOneDriveConfigOptions {
+    /** The rclone remote section name (e.g. `skaile-sharepoint`). */
+    remoteName: string;
+    /** Current OAuth access token. */
+    accessToken: string;
+    /** Long-lived refresh token (embedded in the rclone `token` JSON field). */
+    refreshToken?: string | null;
+    /** Expiry of the access token as a Unix timestamp in milliseconds. */
+    expiresAtMs?: number | null;
+    /** Azure tenant ID for MSAL authentication. */
+    tenantId?: string | null;
+    /** OAuth client (application) ID. */
+    clientId?: string | null;
+    /** OAuth client secret. */
+    clientSecret?: string | null;
+    /** OneDrive drive ID (required by the rclone `onedrive` backend). */
+    driveId: string;
+    /** Drive type. Defaults to `"business"`. */
+    driveType?: "business" | "personal" | "documentLibrary";
+}
+/**
+ * Render an rclone INI config section for a OneDrive / SharePoint remote. Pure — no IO, no side effects.
+ * The `token` field is serialised as a single-line JSON literal as rclone expects.
+ * @param opts - Remote name, OAuth token, drive ID, and optional tenant/client credentials.
+ * @returns Full INI text for one `[<remoteName>]` rclone section.
+ * @docLink packages/connectors/api-reference#render-one-drive-config
+ */
+export declare function renderOneDriveConfig(opts: RenderOneDriveConfigOptions): string;
+//# sourceMappingURL=onedrive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onedrive.d.ts","sourceRoot":"","sources":["../../../../connectors/src/rclone-config/onedrive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,iBAAiB,CAAC;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,MAAM,CAqB9E"}