@skaile/workspaces 0.8.5

package/dist/library/src/preset/placeholders.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Placeholder type system — validation, defaults, type coercion.
+ *
+ * Supports 8 types: text, multiline, secret, number, boolean, enum, oauth, instance-picker.
+ *
+ * Each type defines:
+ *   - Validation rules
+ *   - Default value handling
+ *   - Coercion from string input (CLI prompting returns strings)
+ *
+ * The `instance-picker` type queries the LocalLibrary for available instances
+ * matching a filter (kind, defRef prefix).
+ *
+ * @docLink packages/library/concepts#placeholder-system
+ */
+import type { Placeholder } from "@skaile/workspaces/types/manifests";
+import type { ILibrary } from "../library.js";
+/**
+ * Result of validating a single placeholder value.
+ *
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export interface PlaceholderValidationResult {
+    /** Whether the value passed validation. */
+    valid: boolean;
+    /** Validation error messages (empty when valid). */
+    errors: string[];
+    /** Coerced value (type-appropriate). */
+    value?: unknown;
+}
+/**
+ * Filter options for the `instance-picker` placeholder type.
+ *
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export interface InstancePickerOptions {
+    /** Filter instances by asset kind. */
+    kind?: string;
+    /** Filter instances by defRef prefix. */
+    defRefPrefix?: string;
+}
+/**
+ * A selectable instance entry returned by {@link queryInstancePickerChoices}.
+ *
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export interface InstancePickerChoice {
+    /** UUID of the selectable instance. */
+    instanceId: string;
+    /** Asset definition ref for the instance. */
+    defRef: string;
+    /** Human-readable display label. */
+    label: string;
+}
+/**
+ * Validate a single placeholder value against its schema.
+ *
+ * @param placeholder - The placeholder definition.
+ * @param value - The user-provided value (may be undefined if optional).
+ * @returns Validation result with coerced value.
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export declare function validatePlaceholder(placeholder: Placeholder, value: unknown): PlaceholderValidationResult;
+/**
+ * Validate all placeholders for an item.
+ *
+ * @param placeholders - Array of placeholder definitions.
+ * @param inputs - Map of key to user-provided value.
+ * @returns Map of key to validated value plus aggregate errors.
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export declare function validateAllPlaceholders(placeholders: Placeholder[], inputs: Record<string, unknown>): {
+    valid: boolean;
+    values: Record<string, unknown>;
+    errors: string[];
+};
+/**
+ * Query available instances for an `instance-picker` placeholder.
+ *
+ * @param library - The library to query.
+ * @param options - Optional filter by kind or defRef prefix.
+ * @returns Available instance choices for display in a CLI prompt.
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export declare function queryInstancePickerChoices(library: ILibrary, options?: InstancePickerOptions): Promise<InstancePickerChoice[]>;
+/**
+ * Get the effective default value for a placeholder.
+ *
+ * @param placeholder - The placeholder definition.
+ * @returns The declared default, or undefined if none.
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export declare function getDefaultValue(placeholder: Placeholder): unknown;
+/**
+ * Check if a placeholder holds a secret value (should be routed through SecretsRouter).
+ *
+ * Returns true for `secret` and `oauth` types.
+ *
+ * @param placeholder - The placeholder definition.
+ * @docLink packages/library/concepts#placeholder-system
+ */
+export declare function isSecretPlaceholder(placeholder: Placeholder): boolean;
+//# sourceMappingURL=placeholders.d.ts.map

package/dist/library/src/preset/placeholders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,eAAe,CAAC;AAM9D;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,OAAO,GACb,2BAA2B,CAkC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,WAAW,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAcvE;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAajC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAErE"}

package/dist/library/src/preset/resolve-item.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Item ref resolver — classifies each preset item's ref and produces an apply plan.
+ *
+ * Three ref types:
+ *   - Asset ref:      `<publisher>/<name>@<version>` → create new Instance + subscribe
+ *   - Library ref:    `library://<tier>/instances/<id>` → reuse existing Instance
+ *   - Nested Preset:  another preset ref → recursively apply
+ *   - Cross-item ref: `#<item-id>` → resolved at apply-time from sibling item results
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+import type { PresetItem } from "@skaile/workspaces/types/manifests";
+import type { Instance, AssetDefinition, ILibrary } from "../library.js";
+/**
+ * Classification of a preset item's ref string.
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export type ItemRefKind = "asset" | "library-instance" | "nested-preset" | "cross-item";
+/**
+ * A resolved preset item whose ref is an asset definition ref.
+ *
+ * At apply-time, a new Instance will be created from `defRef`.
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export interface ResolvedAssetItem {
+    kind: "asset";
+    item: PresetItem;
+    /** The asset definition ref (may include version). */
+    defRef: string;
+    /** Resolved asset definition from library cache (null if not cached). */
+    assetDef: AssetDefinition | null;
+}
+/**
+ * A resolved preset item whose ref is a `library://` URI pointing to an existing Instance.
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export interface ResolvedLibraryItem {
+    kind: "library-instance";
+    item: PresetItem;
+    /** The instance UUID extracted from the library:// URI. */
+    instanceId: string;
+    /** The resolved instance (null if not found). */
+    instance: Instance | null;
+}
+/**
+ * A resolved preset item that recursively refers to another preset.
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export interface ResolvedNestedPresetItem {
+    kind: "nested-preset";
+    item: PresetItem;
+    /** The nested preset ref. */
+    presetRef: string;
+}
+/**
+ * A resolved preset item that is a cross-item reference (`#<item-id>`).
+ *
+ * Resolved at apply-time from sibling item results (items must be ordered).
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export interface ResolvedCrossItemRef {
+    kind: "cross-item";
+    item: PresetItem;
+    /** The target item id (without the # prefix). */
+    targetId: string;
+}
+/**
+ * Discriminated union of all resolved preset item types.
+ *
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export type ResolvedItem = ResolvedAssetItem | ResolvedLibraryItem | ResolvedNestedPresetItem | ResolvedCrossItemRef;
+/**
+ * Classify a single item ref string into its {@link ItemRefKind}.
+ *
+ * Returns `"asset"` by default when the ref doesn't match a known prefix.
+ * The caller (apply.ts) re-classifies based on `knownPresetRefs`.
+ *
+ * @param ref - The raw ref string from a preset item.
+ * @returns The classified kind.
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export declare function classifyRef(ref: string): ItemRefKind;
+/**
+ * Extract the instance UUID from a `library://` URI.
+ *
+ * Format: `library://<tier>/instances/<uuid>` where tier is `personal | team | org`.
+ *
+ * @param ref - The full `library://` URI string.
+ * @returns The UUID string, or null if the URI is malformed.
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export declare function extractLibraryInstanceId(ref: string): string | null;
+/**
+ * Resolve a single preset item against the library.
+ *
+ * @param item - The preset item to resolve.
+ * @param library - The library to look up definitions/instances.
+ * @param knownPresetRefs - Set of refs known to be presets (for nested detection).
+ * @returns A typed {@link ResolvedItem} discriminated by kind.
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export declare function resolveItem(item: PresetItem, library: ILibrary, knownPresetRefs?: Set<string>): Promise<ResolvedItem>;
+/**
+ * Resolve all items in a preset in parallel.
+ *
+ * @param items - Array of preset items to resolve.
+ * @param library - The library to look up definitions/instances.
+ * @param knownPresetRefs - Set of refs known to be presets.
+ * @returns Array of resolved items in the same order as the input.
+ * @docLink packages/library/concepts#preset-item-resolution
+ */
+export declare function resolveAllItems(items: PresetItem[], library: ILibrary, knownPresetRefs?: Set<string>): Promise<ResolvedItem[]>;
+//# sourceMappingURL=resolve-item.d.ts.map

package/dist/library/src/preset/resolve-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-item.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/resolve-item.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMzE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,kBAAkB,GAAG,eAAe,GAAG,YAAY,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,mBAAmB,GACnB,wBAAwB,GACxB,oBAAoB,CAAC;AAMzB;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAOpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,QAAQ,EACjB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,YAAY,CAAC,CA0BvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,EAAE,QAAQ,EACjB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}

package/dist/library/src/preset/upgrade.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Preset upgrade detection — structural vs non-structural changes.
+ *
+ * Non-structural changes (config values, placeholder defaults) propagate
+ * automatically per pin policy. Structural changes (added/removed items,
+ * changed refs) require explicit `skaile preset upgrade`.
+ *
+ * The upgrade detector compares two preset versions and classifies the diff.
+ *
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+import type { PresetManifest, PresetItem } from "@skaile/workspaces/types/manifests";
+/**
+ * Classification of the diff between two preset versions.
+ *
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export type ChangeKind = "structural" | "non-structural";
+/**
+ * Detailed diff between two preset manifest versions.
+ *
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export interface PresetDiff {
+    /** Overall classification — `structural` or `non-structural`. */
+    kind: ChangeKind;
+    /** Items added in the new version (structural). */
+    addedItems: PresetItem[];
+    /** Items removed from the old version (structural). */
+    removedItems: PresetItem[];
+    /** Items with changed refs or placeholder/materialize changes (structural). */
+    changedRefItems: Array<{
+        old: PresetItem;
+        new: PresetItem;
+    }>;
+    /** Items with config-only changes (non-structural, safe to auto-propagate). */
+    configChangedItems: Array<{
+        old: PresetItem;
+        new: PresetItem;
+    }>;
+    /** Human-readable summary string for CLI display. */
+    summary: string;
+}
+/**
+ * Result of {@link evaluateUpgrade} — indicates whether the upgrade can proceed automatically.
+ *
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export interface UpgradeResult {
+    /** Whether upgrade can proceed without user confirmation. */
+    autoUpgradable: boolean;
+    /** The computed diff between old and new. */
+    diff: PresetDiff;
+    /** If structural, the list of actions that require explicit user approval. */
+    requiredActions?: string[];
+}
+/**
+ * Detect changes between two preset versions.
+ *
+ * @param oldManifest - The currently applied preset manifest.
+ * @param newManifest - The new preset manifest to upgrade to.
+ * @returns Classified diff with added/removed/changed item lists.
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export declare function detectChanges(oldManifest: PresetManifest, newManifest: PresetManifest): PresetDiff;
+/**
+ * Determine if a preset upgrade can proceed automatically or needs user confirmation.
+ *
+ * @param oldManifest - Currently applied version.
+ * @param newManifest - Target version.
+ * @returns Upgrade result indicating auto-upgradability and required actions.
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export declare function evaluateUpgrade(oldManifest: PresetManifest, newManifest: PresetManifest): UpgradeResult;
+/**
+ * Apply a non-structural upgrade to existing instances.
+ *
+ * Updates config on existing instances to match the new preset version's
+ * config/materialize/placeholder defaults. Only runs when `evaluateUpgrade`
+ * returns `autoUpgradable: true`.
+ *
+ * @param newManifest - The new preset manifest.
+ * @param existingInstances - Map of item key to instance ID.
+ * @param library - Library instance used to call `updateInstance`.
+ * @returns Count of updated instances and any per-instance errors.
+ * @docLink packages/library/concepts#upgrade-strategies
+ */
+export declare function applyNonStructuralUpgrade(newManifest: PresetManifest, existingInstances: Map<string, string>, library: {
+    updateInstance: (id: string, patch: {
+        config?: Record<string, unknown>;
+    }) => Promise<unknown>;
+}): Promise<{
+    updated: number;
+    errors: string[];
+}>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/library/src/preset/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAMrF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,IAAI,EAAE,UAAU,CAAC;IACjB,mDAAmD;IACnD,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,uDAAuD;IACvD,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,eAAe,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAC7D,+EAA+E;IAC/E,kBAAkB,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAChE,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,IAAI,EAAE,UAAU,CAAC;IACjB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,cAAc,EAC3B,WAAW,EAAE,cAAc,GAC1B,UAAU,CAmEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,cAAc,EAC3B,WAAW,EAAE,cAAc,GAC1B,aAAa,CA2Bf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,cAAc,EAC3B,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE;IACP,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/F,GACA,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwBhD"}

package/dist/library/src/remote/cache.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Filesystem cache for {@link RemoteCatalogSource}.
+ *
+ * Cache layout (default `~/.skaile/catalog-cache/`):
+ *
+ *   <dir>/
+ *     index.json           — JSON map of metadata entries with TTL bookkeeping
+ *     tarballs/<sha>.tgz   — content-addressed tarball blobs (SHA256-verified)
+ *
+ * Two caches live in `index.json`:
+ *
+ * - **resolve cache** — keyed by canonical ref (`<publisher>/<name>@<version>`),
+ *   value is the {@link CatalogAsset} or `null` (negative cache for missing refs)
+ *   plus a `fetchedAt` timestamp.
+ * - **list cache** — keyed by a deterministic stringified filter,
+ *   value is the array of {@link CatalogAsset} plus a `fetchedAt` timestamp.
+ *
+ * Tarball blobs are cached on disk by SHA256; the SHA256 itself acts as the
+ * integrity tag, so no separate TTL is needed — content-addressed blobs never
+ * become stale.
+ *
+ * Concurrency: writes go through atomic temp-file rename to keep readers consistent.
+ * Multiple processes writing to the same cache dir is safe at the per-key level
+ * (last writer wins) but readers may see momentarily stale data — acceptable
+ * for a CLI cache.
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+import type { CatalogAsset, CatalogAssetFilter } from "@skaile/workspaces/plugins";
+/**
+ * One entry in the resolve cache. `value` is `null` to negatively-cache misses.
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export interface ResolveCacheEntry {
+    fetchedAt: number;
+    value: CatalogAsset | null;
+}
+/**
+ * One entry in the list cache. `key` is a stable string derived from the
+ * filter; `items` is the response array.
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export interface ListCacheEntry {
+    fetchedAt: number;
+    items: CatalogAsset[];
+}
+/**
+ * Persisted shape of `index.json`.
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export interface CatalogCacheIndex {
+    /** Schema version — bumped on incompatible layout changes. */
+    version: 1;
+    /** Resolve cache by canonical ref. */
+    resolve: Record<string, ResolveCacheEntry>;
+    /** List cache by filter key. */
+    list: Record<string, ListCacheEntry>;
+}
+/**
+ * Options for {@link CatalogCache}.
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export interface CatalogCacheOptions {
+    /** Cache directory. Default: `~/.skaile/catalog-cache/`. */
+    dir?: string;
+    /** TTL in milliseconds. `0` disables network and forces cache-only reads. */
+    ttlMs: number;
+    /** Override clock for tests. */
+    now?: () => number;
+}
+/**
+ * Filesystem-backed cache for catalog metadata + tarballs.
+ *
+ * Per-key freshness is computed against {@link CatalogCacheOptions.ttlMs}. When
+ * `ttlMs === 0` the cache is treated as **air-gapped** — every entry is
+ * considered valid forever, and the only way to refresh is an explicit
+ * {@link CatalogCache.invalidateAll} call (driven by `skaile update`).
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export declare class CatalogCache {
+    readonly dir: string;
+    private readonly ttlMs;
+    private readonly nowFn;
+    private index;
+    constructor(opts: CatalogCacheOptions);
+    /**
+     * Return a fresh resolve-cache entry for `ref`, or `null` if absent / stale.
+     *
+     * When `ttlMs === 0` (air-gapped), all entries are considered fresh
+     * regardless of `fetchedAt`.
+     */
+    getResolve(ref: string): ResolveCacheEntry | null;
+    /**
+     * Return a stale resolve-cache entry regardless of TTL — for stale-while-revalidate.
+     */
+    getResolveStale(ref: string): ResolveCacheEntry | null;
+    /** Persist a resolve-cache entry (use `null` to negatively cache misses). */
+    setResolve(ref: string, value: CatalogAsset | null): void;
+    /**
+     * Return a fresh list-cache entry for `filter`, or `null` if absent / stale.
+     */
+    getList(filter?: CatalogAssetFilter): ListCacheEntry | null;
+    /** Return a stale list-cache entry regardless of TTL — for stale-while-revalidate. */
+    getListStale(filter?: CatalogAssetFilter): ListCacheEntry | null;
+    /** Persist a list-cache entry. */
+    setList(filter: CatalogAssetFilter | undefined, items: CatalogAsset[]): void;
+    /** Absolute path where a tarball with `sha256` would be cached. */
+    tarballPath(sha256: string): string;
+    /** Read a cached tarball from disk if present, otherwise `null`. */
+    readTarball(sha256: string): Uint8Array | null;
+    /** Persist a tarball blob to disk (atomic write). */
+    writeTarball(sha256: string, bytes: Uint8Array): void;
+    /**
+     * Wipe all cached metadata (resolve + list). Tarballs are content-addressed
+     * and remain valid — they are not invalidated.
+     *
+     * Called by `skaile update`.
+     */
+    invalidateAll(): void;
+    /**
+     * Wipe all cached metadata **and** delete tarball blobs. Used for full reset.
+     */
+    invalidateEverything(): void;
+    /** Return whether `ttlMs` is zero (air-gapped mode). */
+    get airGapped(): boolean;
+    private ensureDir;
+    private indexPath;
+    private loadIndex;
+    private writeIndex;
+}
+/**
+ * Stable string key for a {@link CatalogAssetFilter}. Sorts keys so semantically
+ * equivalent filters share a cache slot.
+ */
+export declare function filterKey(filter?: CatalogAssetFilter): string;
+/**
+ * Compute the SHA-256 digest of `bytes` as a lowercase hex string.
+ *
+ * Used by {@link RemoteCatalogSource.fetchTarball} to verify integrity of
+ * downloaded tarballs (spec invariant: "Hash pinning ... Mismatch = hard fail").
+ *
+ * @docLink packages/library/api-reference#catalog-cache
+ */
+export declare function sha256Hex(bytes: Uint8Array): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/library/src/remote/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../library/src/remote/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAMnF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,OAAO,EAAE,CAAC,CAAC;IACX,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAiBD;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,KAAK,CAAkC;gBAEnC,IAAI,EAAE,mBAAmB;IASrC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IASjD;;OAEG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAKtD,6EAA6E;IAC7E,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAQzD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,cAAc,GAAG,IAAI;IAU3D,sFAAsF;IACtF,YAAY,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,cAAc,GAAG,IAAI;IAMhE,kCAAkC;IAClC,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI;IAS5E,mEAAmE;IACnE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAInC,oEAAoE;IACpE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAM9C,qDAAqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAWrD;;;;;OAKG;IACH,aAAa,IAAI,IAAI;IAMrB;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAQ5B,wDAAwD;IACxD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAID,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,UAAU;CAOnB;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAInD"}

package/dist/library/src/remote/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Remote Catalog client — HTTP `ICatalogSource` implementation backed by the
+ * public skaile.store backend (Phase 2). Plus filesystem cache + air-gapped mode.
+ *
+ * @docLink packages/library/api-reference#remote-catalog-source
+ */
+export { RemoteCatalogSource, TarballHashMismatchError, OfflineError, CatalogHttpError, trpcGetUrl, } from "./remote-catalog-source.js";
+export type { RemoteCatalogSourceOptions, HttpClient, } from "./remote-catalog-source.js";
+export { RestCatalogSource } from "./rest-catalog-source.js";
+export type { RestCatalogSourceOptions } from "./rest-catalog-source.js";
+export { CatalogCache, sha256Hex, filterKey } from "./cache.js";
+export type { CatalogCacheOptions, CatalogCacheIndex, ResolveCacheEntry, ListCacheEntry, } from "./cache.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/library/src/remote/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../library/src/remote/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,0BAA0B,EAC1B,UAAU,GACX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC"}