@skaile/workspaces 0.53.0 → 1.1.0

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

@@ -1,316 +0,0 @@
-/**
- * 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), `statSize`
- *     (operations/stat → authoritative remote size, backing the read-path
- *     stale-tail gate) 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";
-/** Default rclone `--vfs-write-back` delay; raised from 5s so a rapidly-rewritten file settles before upload (avoids mid-write "sizes differ" aborts). */
-export declare const DEFAULT_VFS_WRITE_BACK = "30s";
-/** Consecutive failed upload retries for one object before a stuck-upload error is surfaced. */
-export declare const DEFAULT_UPLOAD_STUCK_THRESHOLD = 3;
-/**
- * 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;
-    /**
-     * Skip rclone's post-transfer size + checksum verification by appending
-     * `--ignore-size --ignore-checksum`. Default: false (verification on).
-     *
-     * Escape hatch for remotes that mutate uploaded bytes server-side (notably
-     * SharePoint Online normalising LF→CRLF on text/html), which makes the
-     * remote object a different size/hash than the local source. rclone reads
-     * that as `corrupted on transfer`, deletes the upload, and retries forever,
-     * so the file never durably lands. Enabling this trades integrity
-     * verification for sync-ability and must only be set by drivers that have
-     * confirmed the mutation is benign. Off-by-default; wired per-driver, never
-     * globally.
-     */
-    ignoreSizeCheck?: boolean;
-    /**
-     * rclone `--vfs-write-back` delay (e.g. '30s', '1m'). Controls how long a
-     * dirty file sits before rclone starts uploading it. Default:
-     * {@link DEFAULT_VFS_WRITE_BACK}. Raise it when the agent rewrites files
-     * faster than they upload, to avoid mid-write "sizes differ" aborts.
-     */
-    vfsWriteBack?: string;
-    /**
-     * Consecutive upload retries for one object before {@link onUploadStuck}
-     * fires. Default: {@link DEFAULT_UPLOAD_STUCK_THRESHOLD}.
-     */
-    uploadStuckThreshold?: number;
-    /**
-     * Optional hook invoked once per object when its upload has failed
-     * `uploadStuckThreshold` times in a row. spawn() always also logs an
-     * error-level entry through the `${driverName}+rclone` child logger; this
-     * hook lets callers surface the stranded file elsewhere (e.g. a sync event).
-     */
-    onUploadStuck?: (object: string, tries: number) => void;
-    /**
-     * Optional hook invoked when rclone reports an OAuth auth failure (notably
-     * `invalid_client` / `couldn't fetch token`, the symptom of an expired
-     * access token that rclone cannot self-refresh). Wired by the mount driver
-     * to the reactive arm of its token-refresh controller. Fires per matching
-     * log line; the controller dedupes via its in-flight guard + cooldown.
-     */
-    onAuthError?: () => void;
-    /**
-     * Parent driver Logger — already tagged
-     * `{kind:"mount", subkind:<driver>, instance:<mountId>}` by ConnectorManager.
-     * 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 {
-    private readonly now;
-    /**
-     * @param now Injectable clock (ms) used only to timestamp the quarantine dir
-     * on a poisoned-cache reset, so the move-aside name is deterministic in tests.
-     */
-    constructor(now?: () => number);
-    /**
-     * Spawn an rclone FUSE mount with one-shot poisoned-cache recovery. Delegates
-     * to {@link spawnOnce}; if that fails specifically because the persistent VFS
-     * cache was poisoned (a prior container SIGKILLed mid-write left `vfs`/`vfsMeta`
-     * referencing missing backing files), quarantine the cache and retry the mount
-     * exactly once on a clean rebuild from the authoritative remote.
-     *
-     * The retry is single-shot and bounded: if the fresh-cache mount also fails the
-     * cause is connectivity/token (not the cache), so the error propagates without
-     * a second reset — never a reset/respawn loop. A non-poison failure, or a
-     * poison failure with nothing to quarantine, propagates immediately.
-     */
-    spawn(config: RcloneSpawnConfig): Promise<RcloneHandle>;
-    /**
-     * 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. A readiness-timeout accompanied by the
-     * poisoned-cache log signature throws {@link CachePoisonedMountError} so the
-     * public {@link spawn} can apply its quarantine-and-retry recovery.
-     */
-    protected spawnOnce(config: RcloneSpawnConfig): Promise<RcloneHandle>;
-    /**
-     * Stop an rclone subprocess. Attempts a flush first, then SIGTERM, then
-     * SIGKILL + fusermount3 if `graceMs` elapses without the mountpoint
-     * disappearing.
-     *
-     * `graceMs` bounds both the flush stabilization gate and the SIGTERM→SIGKILL
-     * window — it is *not* a single total wall-clock cap: the flush also waits on
-     * rclone's `/vfs/stats` drain (its own 60s ceiling) between the two.
-     */
-    stop(handle: RcloneHandle, opts?: {
-        graceMs?: number;
-    }): Promise<void>;
-    /**
-     * Apply a freshly-rendered rclone INI to a running mount by recycling the
-     * process: flush + stop the current rclone, then re-spawn at the same
-     * mountpoint/cacheDir with the new config. Returns the new handle.
-     *
-     * rclone holds the OAuth token in memory (baked into the config at spawn);
-     * there is no rc command to swap it on a live `onedrive` backend, so a
-     * recycle is the reliable way to apply a refreshed token. The vfs cache dir
-     * is reused, so the remount revalidates rather than re-downloads. During the
-     * brief unmount window the read-only mount-placeholder barrier underneath is
-     * exposed (writes fail with EROFS, not EIO) — see ConnectorManager's
-     * read-only-until-ready guarantee.
-     */
-    reconfigure(handle: RcloneHandle, rcloneConfig: string): Promise<RcloneHandle>;
-    /**
-     * Force rclone to upload pending writes, then wait until the in-use
-     * counter reaches zero.
-     *
-     * Before issuing the refresh it waits for the vfs cache dir to go quiescent
-     * (no write for `stabilityThresholdMs`, bounded by `stabilizeTimeoutMs`) so a
-     * close/hibernate-triggered flush doesn't snapshot a half-written file and
-     * trigger rclone's mid-write "sizes differ" abort. Pass `stabilize: false`
-     * to skip the gate.
-     */
-    flush(handle: RcloneHandle, opts?: {
-        stabilize?: boolean;
-        stabilityThresholdMs?: number;
-        stabilizeTimeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Authoritative remote byte size for a mount-relative path, via rclone's
-     * `operations/stat` rc endpoint. Backs the mount read-path stale-tail gate:
-     * `operations/stat` hits the backend object directly, so it returns the true
-     * remote size even when the VFS cache is serving a non-truncated item (and
-     * `statSync` on the FUSE mount reports the inflated length). Returns `null`
-     * when the handle is unknown, the object is missing / a directory, or the
-     * call fails — the caller then trusts the on-disk bytes.
-     */
-    statSize(handle: RcloneHandle, relPath: string): Promise<number | null>;
-    /** Liveness + cache-dir size. */
-    status(handle: RcloneHandle): Promise<{
-        alive: boolean;
-        cacheBytes: number;
-    }>;
-}
-/**
- * Per-process state threaded through {@link _routeRcloneLogLine} so it can
- * detect a sustained upload failure (the same object failing to upload K times
- * in a row) and surface it exactly once, instead of letting rclone retry
- * silently at INFO level forever.
- */
-export interface RcloneLogRouteContext {
-    /** Consecutive retries for one object before {@link onUploadStuck} fires. */
-    stuckThreshold?: number;
-    /** Objects already alerted on, to fire once and not on every later retry. */
-    alertedObjects?: Set<string>;
-    /** Per-object consecutive `itemNotFound` count; escalates at {@link stuckThreshold}. */
-    itemNotFoundCounts?: Map<string, number>;
-    /** Called the first time an object crosses {@link stuckThreshold}. */
-    onUploadStuck?: (object: string, tries: number) => void;
-    /** Called when a line matches an OAuth auth-failure pattern. */
-    onAuthError?: () => void;
-}
-/**
- * Thrown by {@link RcloneProcessManager.spawnOnce} when a mount-readiness
- * failure was accompanied by the {@link CACHE_POISON_RE} signature, so
- * {@link RcloneProcessManager.spawn} knows the failure is a recoverable
- * poisoned cache (quarantine + single retry) rather than a connectivity/token
- * fault. Its `message` is the full mount-failure detail (including the stderr
- * tail), so surfacing it directly when recovery declines loses no diagnostics.
- */
-export declare class CachePoisonedMountError extends Error {
-    constructor(message: string);
-}
-/**
- * @internal
- * True when an rclone log line carries the poisoned-VFS-cache signature
- * ({@link CACHE_POISON_RE}). Exported for tests; not part of the public API.
- */
-export declare function _isCachePoisonLine(line: string): boolean;
-/**
- * Move a poisoned rclone VFS cache aside so the next spawn rebuilds a clean one
- * from the authoritative remote. Moves `<cacheDir>/vfs` + `<cacheDir>/vfsMeta`
- * (whichever exist) into `<cacheDir>/.corrupt-<ISO>` — a move-aside, never a
- * delete, so any (junk) un-uploaded bytes stay recoverable for forensics. The
- * quarantine dir is nested inside `cacheDir` (not a sibling) so it lives within
- * the per-session cache dir the platform removes wholesale on session close —
- * bounding its lifetime to the session — and rclone only reads its own
- * `vfs`/`vfsMeta` subdirs, so the dotted sibling is inert to the live mount.
- * (A bounded retain-N/reap-after-M GC of repeated resets within one long-lived
- * session is a follow-up; session-close cleanup covers the common case.)
- *
- * Returns the quarantine dir path when anything was moved, else `null` (nothing
- * to quarantine — the failure was not a poisoned cache). `nowMs` is injected for
- * deterministic test timestamps. Exported for tests; not part of the public API.
- */
-export declare function quarantineCacheDir(cacheDir: string, nowMs: number): Promise<string | null>;
-/**
- * @internal
- * Route a single rclone log line (JSON or raw) to the appropriate Logger
- * call. Exported for tests; not part of the public API. When `ctx` is
- * supplied, also tracks consecutive upload failures per object and invokes
- * `ctx.onUploadStuck` once the retry count for an object reaches the threshold.
- */
-export declare function _routeRcloneLogLine(line: string, log: Logger, ctx?: RcloneLogRouteContext): void;
-/**
- * @internal
- * Build the `rclone mount` argv from a spawn config. Extracted from spawn() so
- * the flag wiring (notably `--vfs-write-back` and the conditional
- * `--ignore-size --ignore-checksum`) is unit-testable without actually
- * launching rclone. Exported for tests; not part of the public API.
- */
-export declare function _buildRcloneArgs(config: RcloneSpawnConfig, io: {
-    configPath: string;
-    rcAddr: string;
-}): string[];
-/**
- * @internal
- * Split an rclone mount `remote` (`skaile-<id>:/base/path`) plus a
- * mount-relative path into the `{fs, remote}` pair rclone's `operations/stat`
- * rc command expects: `fs` is the backend root (`skaile-<id>:`) and `remote` is
- * the object path within it. Leading/trailing slashes are normalised away so
- * the join is stable regardless of how either side is slashed. Exported for
- * tests; not part of the public API.
- */
-export declare function _operationsStatTarget(remote: string, relPath: string): {
-    fs: string;
-    remote: string;
-};
-/**
- * Query rclone's `operations/stat` rc endpoint for the authoritative remote
- * size of `relPath` under `remote`. Returns the byte size, or `null` when the
- * object is missing, is a directory, the call fails, or the size is absent.
- *
- * Unlike a `statSync` on the FUSE mount, `operations/stat` resolves the object
- * against the backend directly, so it is not subject to the VFS cache's
- * non-truncated stale tail. Pass `fetchImpl` to test without a live rc server.
- */
-export declare function fetchAuthoritativeSize(rcAddr: string, remote: string, relPath: string, fetchImpl?: typeof fetch): Promise<number | null>;
-/**
- * Poll `dir` until its newest file mtime is at least `thresholdMs` in the past
- * (no write for that long), or `timeoutMs` elapses. Returns true if it went
- * quiescent, false on timeout. An empty/missing dir counts as quiescent.
- */
-export declare function awaitQuiescent(dir: string, opts: {
-    thresholdMs: number;
-    timeoutMs: number;
-    pollMs: number;
-}): Promise<boolean>;
-/**
- * @internal
- * Returns true if a FUSE mount is present at `mountPoint` in the given
- * /proc/self/mounts text. The fstype check (field 3, `fuse.*`) is essential:
- * the deferred-mount barrier leaves a `tmpfs` mounted at the same path, so a
- * path-only match would report the *barrier* as the confirmed mount and mask a
- * dead rclone process. Exported for tests; not part of the public API.
- */
-export declare function _fuseMountPresent(procMountsText: string, mountPoint: string): boolean;
-//# sourceMappingURL=rclone-process-manager.d.ts.map

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

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

package/dist/connectors/src/rclone-token-refresh.d.ts

@@ -1,84 +0,0 @@
-/**
- * Proactive + reactive OAuth token refresh for rclone-backed mounts.
- * See `connectors/CLAUDE.md` § Rclone Process Manager → Token refresh.
- */
-import type { TokenMediator } from "./connector-types.js";
-import type { RcloneHandle } from "./rclone-process-manager.js";
-/**
- * Safety margin between the scheduled refresh and the token's declared expiry.
- * Default 5 minutes: long enough that any in-flight read/write at fire time
- * still has a usable token through the recycle, short enough that a server
- * clock skew of a few seconds does not push the fire-time past expiry. Matches
- * the AI-credential and git-mount refresh leads.
- */
-export declare const PROACTIVE_RCLONE_REFRESH_MARGIN_MS: number;
-/** Default cooldown suppressing reactive triggers right after a refresh. */
-export declare const DEFAULT_REACTIVE_COOLDOWN_MS: number;
-/**
- * Minimal slice of `RcloneProcessManager` the refresh controller needs: swap
- * the live mount onto a freshly-rendered INI (`reconfigure`), and stop a
- * process the controller spawned but can no longer own (`stop`, used to clean
- * up when `disconnect()` races a mid-recycle spawn).
- */
-export interface RcloneReconfigurable {
-    reconfigure(handle: RcloneHandle, rcloneConfig: string): Promise<RcloneHandle>;
-    stop(handle: RcloneHandle): Promise<void>;
-}
-/**
- * Caller-supplied dependencies for {@link createRcloneTokenRefresh}.
- *
- * - `tokenMediator` runs the actual backend mint round-trip.
- * - `renderConfig(token)` re-renders the rclone INI for the freshly-minted
- *   access token (driver-specific: onedrive vs webdav backend shape).
- * - `rclone.reconfigure` recycles the process onto the new INI.
- * - `handleRef.current` is the live rclone handle; the controller updates it
- *   in place on every successful recycle so the driver's `disconnect()` stops
- *   the current process.
- * - `now` / `setTimeoutImpl` / `clearTimeoutImpl` are injected for tests.
- */
-export interface RcloneTokenRefreshDeps {
-    connectorId: string;
-    tokenMediator: TokenMediator;
-    renderConfig: (token: string) => string | Promise<string>;
-    rclone: RcloneReconfigurable;
-    handleRef: {
-        current: RcloneHandle | null;
-    };
-    log: (line: string) => void;
-    now?: () => number;
-    setTimeoutImpl?: (handler: () => void, ms: number) => {
-        unref?: () => void;
-    };
-    clearTimeoutImpl?: (handle: {
-        unref?: () => void;
-    }) => void;
-    marginMs?: number;
-    reactiveCooldownMs?: number;
-}
-export interface RcloneTokenRefreshController {
-    /**
-     * Arm the timer for `expiresAtIso - marginMs`. Cancels any prior pending
-     * fire. `null` / `undefined` / unparseable cancels without re-arming
-     * (static-credential / standalone semantics). A past fire-time refreshes on
-     * the next tick.
-     */
-    schedule(expiresAtIso: string | null | undefined): void;
-    /**
-     * Reactive safety net: invoke when rclone reports an auth failure. Triggers
-     * an immediate refresh unless one is already in flight or the last refresh
-     * was within the cooldown window (prevents a stream of failure lines from
-     * spinning the recycle loop).
-     */
-    onAuthError(): void;
-    /** Cancel any pending fire. Idempotent. */
-    cancel(): void;
-    /** Whether a proactive timer is currently armed. Exposed for tests. */
-    isPending(): boolean;
-}
-/**
- * Build a refresh controller bound to one rclone mount. One controller per
- * connect — the driver constructs it after the initial spawn and disposes it
- * via `cancel()` in `disconnect()`.
- */
-export declare function createRcloneTokenRefresh(deps: RcloneTokenRefreshDeps): RcloneTokenRefreshController;
-//# sourceMappingURL=rclone-token-refresh.d.ts.map

package/dist/connectors/src/rclone-token-refresh.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rclone-token-refresh.d.ts","sourceRoot":"","sources":["../../../connectors/src/rclone-token-refresh.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,QAAgB,CAAC;AAEhE,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,QAAY,CAAC;AAStD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/E,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE;QAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5C,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAC7E,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IACxD;;;;;OAKG;IACH,WAAW,IAAI,IAAI,CAAC;IACpB,2CAA2C;IAC3C,MAAM,IAAI,IAAI,CAAC;IACf,uEAAuE;IACvE,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,sBAAsB,GAC3B,4BAA4B,CA+J9B"}

package/dist/ensure-sources-GJOXWVWO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../cli/src/ensure-sources.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAqBA,SAAS,gBAAgB,GAAA,EAAqB;AAC5C,EAAA,OAAY,IAAA,CAAA,IAAA,CAAK,iBAAA,EAAkB,EAAG,GAAG,CAAA;AAC3C;AASA,SAAS,kBAAA,CAAmB,UAAkB,KAAA,EAAsC;AAClF,EAAA,IAAI;AACF,IAAA,OAAO,mBAAA,CAAoB,IAAA,CAAK,QAAQ,CAAA,CAAE,UAAA,EAAW;AAAA,EACvD,SAAS,GAAA,EAAK;AACZ,IAAA,IAAI,CAAC,KAAA,EAAO;AACV,MAAA,MAAA,CAAO,CAAA,eAAA,EAAkB,QAAQ,CAAA,EAAA,EAAK,GAAA,YAAe,KAAA,GAAQ,IAAI,OAAA,GAAU,MAAA,CAAO,GAAG,CAAC,CAAA,CAAE,CAAA;AAAA,IAC1F;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAMA,SAAS,kBAAA,CAAmB,KAAA,EAAoB,KAAA,EAAgB,MAAA,EAA4B;AAC1F,EAAA,MAAM,GAAA,GAAM,cAAA,CAAe,KAAA,CAAM,GAAG,CAAA;AACpC,EAAA,MAAM,IAAA,GAAO,eAAA,CAAgB,KAAA,CAAM,GAAG,CAAA;AACtC,EAAA,MAAM,IAAA,GAAO,gBAAgB,GAAG,CAAA;AAChC,EAAA,IAAI,UAAA,CAAW,IAAI,CAAA,EAAG;AACpB,IAAA,MAAA,CAAO,MAAA,CAAO,KAAK,IAAI,CAAA;AACvB,IAAA;AAAA,EACF;AACA,EAAA,SAAA,CAAe,aAAQ,IAAI,CAAA,EAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AACjD,EAAA,MAAM,IAAA,GAAO,CAAC,OAAA,EAAS,KAAA,CAAM,KAAK,IAAI,CAAA;AACtC,EAAA,IAAI,KAAA,CAAM,KAAK,IAAA,CAAK,MAAA,CAAO,GAAG,CAAA,EAAG,UAAA,EAAY,MAAM,GAAG,CAAA;AACtD,EAAA,MAAM,KAAA,GAAQ,UAAU,KAAA,EAAO,IAAA,EAAM,EAAE,KAAA,EAAO,KAAA,GAAQ,MAAA,GAAS,SAAA,EAAW,CAAA;AAC1E,EAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AACtB,IAAA,MAAA,CAAO,MAAA,CAAO,KAAK,IAAI,CAAA;AACvB,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,MAAA,CAAO,CAAA,qBAAA,EAAwB,KAAA,CAAM,GAAG,CAAA,CAAE,CAAA;AAAA,IAC5C;AACA,IAAA;AAAA,EACF;AACA,EAAA,MAAA,CAAO,MAAA,CAAO,KAAK,IAAI,CAAA;AACzB;AAGA,SAAS,kBAAkB,MAAA,EAA4B;AACrD,EAAA,KAAA,MAAW,KAAK,MAAA,CAAO,MAAA,EAAQ,KAAA,CAAM,CAAA,eAAA,EAAkB,CAAC,CAAA,EAAA,CAAI,CAAA;AAC5D,EAAA,IAAI,MAAA,CAAO,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG;AAC5B,IAAA,OAAA,CAAQ,yBAAyB,MAAA,CAAO,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,CAAE,CAAA;AAAA,EAC7D;AACF;AAUO,SAAS,mBAAA,CACd,UAAA,EACA,IAAA,GAA4B,EAAC,EACf;AACd,EAAA,MAAM,MAAA,GAAuB,EAAE,MAAA,EAAQ,EAAC,EAAG,QAAQ,EAAC,EAAG,MAAA,EAAQ,EAAC,EAAE;AAClE,EAAA,MAAM,QAAA,GAAgB,IAAA,CAAA,IAAA,CAAK,UAAA,EAAY,aAAa,CAAA;AACpD,EAAA,IAAI,CAAC,UAAA,CAAW,QAAQ,CAAA,EAAG,OAAO,MAAA;AAElC,EAAA,MAAM,KAAA,GAAQ,KAAK,KAAA,IAAS,KAAA;AAC5B,EAAA,MAAM,OAAA,GAAU,kBAAA,CAAmB,QAAA,EAAU,KAAK,CAAA;AAClD,EAAA,IAAI,OAAA,KAAY,MAAM,OAAO,MAAA;AAC7B,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAEjC,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,kBAAA,CAAmB,KAAA,EAAO,OAAO,MAAM,CAAA;AAAA,EACzC;AAEA,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,iBAAA,CAAkB,MAAM,CAAA;AAAA,EAC1B;AAEA,EAAA,OAAO,MAAA;AACT","file":"ensure-sources-GJOXWVWO.js","sourcesContent":["/**\n * ensure-sources.ts — hydrate the `~/.skaile/cache/sources/` clone cache from a\n * project's `skaile.yaml` `sources:` entries.\n *\n * Called by `skaile init` (idempotent: no-op when no sources declared) and\n * `skaile install` so checking out a project pulls its source clones onto\n * the local machine.\n */\n\nimport { spawnSync } from \"node:child_process\";\nimport { existsSync, mkdirSync } from \"node:fs\";\nimport * as path from \"node:path\";\nimport {\n  getGlobalCacheDir,\n  type SourceEntry,\n  sourceCacheKey,\n  sourceShortName,\n  WorkspaceYamlEditor,\n} from \"@skaile/workspaces/core\";\nimport { logErr, logInfo, logOk } from \"./helpers.ts\";\n\nfunction sourceClonePath(key: string): string {\n  return path.join(getGlobalCacheDir(), key);\n}\n\nexport interface EnsureResult {\n  cloned: string[];\n  cached: string[];\n  failed: string[];\n}\n\n/** Load `sources:` from a project's `skaile.yaml`, or `null` when unavailable. */\nfunction loadProjectSources(yamlPath: string, quiet: boolean): SourceEntry[] | null {\n  try {\n    return WorkspaceYamlEditor.load(yamlPath).getSources();\n  } catch (err) {\n    if (!quiet) {\n      logErr(`Could not read ${yamlPath}: ${err instanceof Error ? err.message : String(err)}`);\n    }\n    return null;\n  }\n}\n\n/**\n * Hydrate a single source entry into `result`: skip when already cached,\n * otherwise clone and record success/failure. Mutates `result` in place.\n */\nfunction hydrateSourceEntry(entry: SourceEntry, quiet: boolean, result: EnsureResult): void {\n  const key = sourceCacheKey(entry.url);\n  const slug = sourceShortName(entry.url);\n  const dest = sourceClonePath(key);\n  if (existsSync(dest)) {\n    result.cached.push(slug);\n    return;\n  }\n  mkdirSync(path.dirname(dest), { recursive: true });\n  const args = [\"clone\", entry.url, dest];\n  if (entry.pin) args.splice(1, 0, \"--branch\", entry.pin);\n  const clone = spawnSync(\"git\", args, { stdio: quiet ? \"pipe\" : \"inherit\" });\n  if (clone.status !== 0) {\n    result.failed.push(slug);\n    if (quiet) {\n      logErr(`git clone failed for ${entry.url}`);\n    }\n    return;\n  }\n  result.cloned.push(slug);\n}\n\n/** Log a full-hydrate summary of cloned + reused-cached entries. */\nfunction logHydrateSummary(result: EnsureResult): void {\n  for (const n of result.cloned) logOk(`Cloned source \"${n}\".`);\n  if (result.cached.length > 0) {\n    logInfo(`Reused cached clones: ${result.cached.join(\", \")}`);\n  }\n}\n\n/**\n * Walk `projectDir/skaile.yaml` `sources:` and clone any entries whose\n * clone directory does not yet exist under `~/.skaile/cache/sources/`. Existing\n * clones are left untouched — this is hydration, not sync.\n *\n * Quiet by default: when `quiet: true` the helper only prints failures.\n * On full hydrate (`quiet: false`) it logs each cloned/cached entry.\n */\nexport function ensureSourcesCloned(\n  projectDir: string,\n  opts: { quiet?: boolean } = {},\n): EnsureResult {\n  const result: EnsureResult = { cloned: [], cached: [], failed: [] };\n  const yamlPath = path.join(projectDir, \"skaile.yaml\");\n  if (!existsSync(yamlPath)) return result;\n\n  const quiet = opts.quiet ?? false;\n  const sources = loadProjectSources(yamlPath, quiet);\n  if (sources === null) return result;\n  if (sources.length === 0) return result;\n\n  for (const entry of sources) {\n    hydrateSourceEntry(entry, quiet, result);\n  }\n\n  if (!quiet) {\n    logHydrateSummary(result);\n  }\n\n  return result;\n}\n"]}

package/dist/helpers-F4NZ66VD.js

@@ -1,4 +0,0 @@
-export { KIND_COL_WIDTH, S, colorRef, fitWidth, formatRelativeTime, kindColor, kindColorPad, logErr, logInfo, logOk, logWarn } from './chunk-GYPA2Q7F.js';
-import './chunk-NSBPE2FW.js';
-//# sourceMappingURL=helpers-F4NZ66VD.js.map
-//# sourceMappingURL=helpers-F4NZ66VD.js.map

package/dist/open-library-ERKRGH4B.js

@@ -1,23 +0,0 @@
-export { openCatalogSource, openLibrary, openLibraryManager, resolveCatalogSource } from './chunk-WD2NRI3T.js';
-import './chunk-GYPA2Q7F.js';
-import './chunk-2D5YE3FL.js';
-import './chunk-UTHEIPEY.js';
-import './chunk-JXT46QFC.js';
-import './chunk-UKJMQZV6.js';
-import './chunk-R7FOF242.js';
-import './chunk-SKADPHAM.js';
-import './chunk-3KPNDTMR.js';
-import './chunk-ZAP2BDHG.js';
-import './chunk-W53D5Q52.js';
-import './chunk-NXC6IEL4.js';
-import './chunk-DZCK7GRW.js';
-import './chunk-BQCGFPHW.js';
-import './chunk-GEEW6SY2.js';
-import './chunk-F3HNW354.js';
-import './chunk-MENCWIHW.js';
-import './chunk-K5GBV4SA.js';
-import './chunk-JB35MVBN.js';
-import './chunk-CU5Z7GH3.js';
-import './chunk-NSBPE2FW.js';
-//# sourceMappingURL=open-library-ERKRGH4B.js.map
-//# sourceMappingURL=open-library-ERKRGH4B.js.map