@skaile/workspaces 0.8.5

package/dist/library/src/local/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../library/src/local/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBpB,CAAC;AAMH;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB3B,CAAC;AAMH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASpB,CAAC;AAMH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMxB,CAAC"}

package/dist/library/src/local/sidecar-git.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Sidecar git helper — manages the single shared git repo at
+ * `~/.skaile/sources/` (PR-3 § D.5).
+ *
+ * Each sidecar lives in its own subdirectory under `<rootDir>`. All sidecars
+ * share one `.git/` so users can push the entire root to a personal remote
+ * (e.g. their own `dotfiles` repo) without juggling N repos.
+ *
+ * `ensureInitialized()` is idempotent — safe to call on every command. The
+ * helper applies a fallback `user.name` / `user.email` only when the global
+ * git config is missing those keys, so it never overrides a user's own
+ * identity.
+ *
+ * Mutating commands (`commit()`) are no-ops when `skip: true` is passed; this
+ * is how the CLI's `--no-commit` flag flows through.
+ *
+ * Shells out to the system `git` binary via `child_process` — keeps the
+ * dependency surface minimal and matches the rest of the agent-framework's
+ * pattern (no `simple-git` / `isomorphic-git`).
+ *
+ * @docLink packages/library/concepts#sidecar-git
+ */
+/**
+ * Result of a raw `git` invocation via {@link SidecarGit.runRaw}.
+ *
+ * @docLink packages/library/concepts#sidecar-git
+ */
+export interface GitInvocationResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Options accepted by {@link SidecarGit.commit}.
+ */
+export interface SidecarCommitOptions {
+    /** Skip the commit entirely. Used by the CLI's `--no-commit` flag. */
+    skip?: boolean;
+}
+/**
+ * Git operations over the shared sidecar root.
+ *
+ * One instance per CLI invocation is the typical pattern; the helper is
+ * stateless beyond the `rootDir`.
+ *
+ * @docLink packages/library/concepts#sidecar-git
+ */
+export declare class SidecarGit {
+    readonly rootDir: string;
+    constructor(rootDir: string);
+    /**
+     * Initialize the sidecar root if it doesn't yet exist.
+     *
+     * Steps (idempotent — each is a no-op when already present):
+     *   1. `mkdir -p <rootDir>`
+     *   2. `git init -b main <rootDir>` if `<rootDir>/.git` is missing
+     *   3. Write `.gitattributes` (`* text=auto eol=lf`) if missing
+     *   4. Write `README.md` if missing
+     *   5. Apply fallback `user.name` / `user.email` to the repo config if
+     *      the global config is missing them
+     *   6. Create the seed commit (`chore: initialize sidecar manifests`) if
+     *      the repo has no commits yet
+     *
+     * Subsequent calls don't reset config, so a user who overrode the
+     * identity manually keeps their override.
+     *
+     * @docLink packages/library/concepts#sidecar-git
+     */
+    ensureInitialized(): Promise<void>;
+    /**
+     * Stage everything under `<rootDir>/<slug>/` and create a commit.
+     *
+     * Idempotent: if there are no staged changes after `git add`, the commit
+     * is skipped (and resolves successfully — a no-op is fine).
+     *
+     * @param slug - Sidecar slug (subdirectory name)
+     * @param message - Commit message (conventional-commits style preferred;
+     *   the CLI uses `feat(<slug>): create sidecar...`, `chore(<slug>): ...`)
+     * @param opts - `{ skip: true }` short-circuits without staging or committing
+     */
+    commit(slug: string, message: string, opts?: SidecarCommitOptions): Promise<void>;
+    /**
+     * Check whether the sidecar repo has uncommitted changes.
+     *
+     * @returns `true` when `git status --porcelain` has any output.
+     */
+    hasChanges(): Promise<boolean>;
+    /**
+     * Run an arbitrary `git -C <rootDir> <args>` invocation and return the
+     * captured stdout/stderr + exit code.
+     *
+     * Used by `skaile source sidecar git -- <args>` so users don't have to
+     * `cd ~/.skaile/sources` to operate the repo manually.
+     *
+     * @param args - Git arguments (no leading `git` token)
+     * @returns Combined output + exit code; never throws on non-zero exit
+     * @docLink packages/library/concepts#sidecar-git
+     */
+    runRaw(args: string[]): Promise<GitInvocationResult>;
+    private spawn;
+    private hasGlobalGitConfig;
+    private hasAnyCommit;
+}
+//# sourceMappingURL=sidecar-git.d.ts.map

package/dist/library/src/local/sidecar-git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-git.d.ts","sourceRoot":"","sources":["../../../../library/src/local/sidecar-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiCD;;;;;;;GAOG;AACH,qBAAa,UAAU;aACO,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;IAE3C;;;;;;;;;;;;;;;;;OAiBG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCxC;;;;;;;;;;OAUG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BvF;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAKpC;;;;;;;;;;OAUG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM1D,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,YAAY;CAIrB"}

package/dist/library/src/local/sidecar-paths.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Sidecar path resolver — locations under `~/.skaile/sources/` (PR-3 § D.1).
+ *
+ * `~/.skaile/sources/` is a single git repo containing one subdirectory per
+ * registered sidecar. Each subdirectory carries the local-overlay manifest
+ * (`.skaile-source.yaml`), a provenance README, and a lock file.
+ *
+ * Path resolution honors the `SKAILE_HOME` env var (defaults to `~/.skaile`)
+ * mirroring the style used by `SKAILE_LIBRARY_DIR` (which already overrides
+ * the library subdirectory). Setting `SKAILE_HOME` is the recommended hook
+ * for test isolation: a single env var moves the sidecar root, the library
+ * dir (when not separately overridden), and the catalog cache together.
+ *
+ * @docLink packages/library/concepts#sidecar-paths
+ */
+import type { SourceConfig } from "@skaile/workspaces/discovery";
+/**
+ * Resolved sidecar paths for a given slug. All paths are absolute.
+ *
+ * @docLink packages/library/concepts#sidecar-paths
+ */
+export interface SidecarPaths {
+    /** Root sidecar directory, `~/.skaile/sources` (or `$SKAILE_HOME/sources`). */
+    rootDir: string;
+    /** Per-source sidecar dir: `<rootDir>/<slug>`. */
+    sidecarDir: string;
+    /** Manifest file: `<sidecarDir>/.skaile-source.yaml`. */
+    manifestFile: string;
+    /** Provenance README: `<sidecarDir>/README.md`. */
+    readmeFile: string;
+    /** Lock file: `<sidecarDir>/.skaile-source.lock.json`. */
+    lockFile: string;
+}
+/**
+ * Resolve the absolute path to the sidecar root directory.
+ *
+ * Resolution order:
+ *   1. `$SKAILE_HOME/sources` if `SKAILE_HOME` is set
+ *   2. `~/.skaile/sources` (default)
+ *
+ * Does **not** create the directory — callers (e.g. `SidecarGit.ensureInitialized`)
+ * are responsible for materialising it.
+ *
+ * @returns Absolute path to `~/.skaile/sources` (or env override)
+ * @docLink packages/library/concepts#sidecar-paths
+ */
+export declare function getSidecarRoot(): string;
+/**
+ * Resolve all sidecar paths for a given slug.
+ *
+ * @param slug - Sidecar slug (subdirectory name under `~/.skaile/sources/`)
+ * @returns Bundle of all relevant absolute paths
+ * @docLink packages/library/concepts#sidecar-paths
+ */
+export declare function resolveSidecarPaths(slug: string): SidecarPaths;
+/**
+ * Derive a sidecar slug from a source config + source path, applying
+ * collision resolution against the set of slugs already in use.
+ *
+ * Derivation order (per PR-3 § D.1):
+ *   1. `name:` field of the upstream `.skaile-source.yaml` (if non-empty)
+ *   2. `path.basename(sourcePath)` (fallback)
+ *
+ * Collision suffix: `-2`, `-3`, ... appended until unique against
+ * `existingSlugs`.
+ *
+ * Empty/dot/segmented basenames fall through to `unnamed-source`.
+ *
+ * @param sourceConfig - Validated source config (may be `undefined`)
+ * @param sourcePath - Filesystem path of the source repo
+ * @param existingSlugs - Slugs already in use under the sidecar root
+ * @returns A unique, slugified directory name
+ * @docLink packages/library/concepts#derive-slug
+ */
+export declare function deriveSlug(sourceConfig: SourceConfig | undefined | null, sourcePath: string, existingSlugs: Iterable<string>): string;
+/**
+ * List the slugs currently present on disk under {@link getSidecarRoot}.
+ *
+ * Returns an empty array when the root directory doesn't exist yet (first
+ * sidecar). Non-directory entries (e.g. the root `README.md`,
+ * `.gitattributes`) are filtered out.
+ *
+ * @returns Lexically sorted list of slug directory names
+ * @docLink packages/library/concepts#sidecar-paths
+ */
+export declare function listSidecarSlugsOnDisk(): string[];
+//# sourceMappingURL=sidecar-paths.d.ts.map

package/dist/library/src/local/sidecar-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-paths.d.ts","sourceRoot":"","sources":["../../../../library/src/local/sidecar-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAMjE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAU9D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,EAC7C,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC9B,MAAM,CAoBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAUjD"}

package/dist/library/src/local/user-library-manager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * UserLibraryManager — CRUD for the `libraries` table plus driver dispatch.
+ *
+ * Wraps a LocalLibrary handle (sharing its db) and exposes the user-facing
+ * library lifecycle: add / list / get / setDefault / rename / update /
+ * remove. Also owns ensurePersonalLibrary() — the silent auto-init on first
+ * `skaile asset migrate`.
+ *
+ * @docLink packages/library/concepts#user-library-manager
+ */
+import type { LibrarySyncDriver } from "../sync/driver.js";
+import { type AddLibraryInput, type LibraryBackend, type UpdateLibraryInput, type UserLibrary } from "../user-library.js";
+import type { LocalLibrary } from "./library.js";
+export declare class UserLibraryManager {
+    private readonly lib;
+    private readonly localDrv;
+    private readonly gitDrv;
+    private readonly storeDrv;
+    constructor(lib: LocalLibrary);
+    /** Resolve the sync driver for a given backend. */
+    driverFor(backend: LibraryBackend): LibrarySyncDriver;
+    addLibrary(input: AddLibraryInput): Promise<UserLibrary>;
+    listLibraries(): Promise<UserLibrary[]>;
+    getLibrary(nameOrId: string): Promise<UserLibrary | null>;
+    requireLibrary(nameOrId: string): Promise<UserLibrary>;
+    updateLibrary(nameOrId: string, patch: UpdateLibraryInput): Promise<UserLibrary>;
+    setDefault(nameOrId: string): Promise<UserLibrary>;
+    removeLibrary(nameOrId: string, opts?: {
+        purge?: boolean;
+    }): Promise<void>;
+    /**
+     * Idempotently ensure a `personal` library exists at `<librariesDir>/personal`.
+     * Created silently — one stderr line — on first call when no writable default
+     * exists. Returns the library row and a `created` flag.
+     */
+    ensurePersonalLibrary(librariesDir: string): Promise<{
+        library: UserLibrary;
+        created: boolean;
+    }>;
+}
+//# sourceMappingURL=user-library-manager.d.ts.map

package/dist/library/src/local/user-library-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-library-manager.d.ts","sourceRoot":"","sources":["../../../../library/src/local/user-library-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,OAAO,EACL,KAAK,eAAe,EAGpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA2BjD,qBAAa,kBAAkB;IAKjB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAErB,GAAG,EAAE,YAAY;IAE9C,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB;IAW/C,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAkCxD,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAMvC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAazD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAMtD,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAmBhF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYlD,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IASpF;;;;OAIG;IACG,qBAAqB,CACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CA2BvD"}

package/dist/library/src/migration.d.ts

@@ -0,0 +1,38 @@
+/**
+ * v1 -> v2 skaile.yaml migration utility.
+ *
+ * Detects a v1 workspace config (no `version` field) and upgrades it to v2.
+ * The upgrade is non-destructive: all existing v1 fields are preserved and
+ * the only structural change is adding `version: 2`.
+ *
+ * @docLink packages/library/api-reference#migration
+ */
+/**
+ * Result returned by {@link migrateWorkspaceConfig}.
+ *
+ * @docLink packages/library/api-reference#migration
+ */
+export interface MigrationResult {
+    /** Whether the file was actually modified (false in dry-run or already v2). */
+    migrated: boolean;
+    /** Detected version after migration (or current version if no migration). */
+    version: 1 | 2;
+    /** Human-readable warnings about v1 patterns that need manual attention. */
+    warnings: string[];
+}
+/**
+ * Check if a workspace config needs migration and optionally perform it.
+ *
+ * The upgrade preserves all existing YAML content (including comments) and
+ * inserts `version: 2` at the top of the document.
+ *
+ * @param dir - Directory containing skaile.yaml.
+ * @param opts - `dryRun` to check without writing; `filename` to override the default filename.
+ * @returns Migration result with `migrated` flag and any v1-pattern warnings.
+ * @docLink packages/library/api-reference#migration
+ */
+export declare function migrateWorkspaceConfig(dir: string, opts?: {
+    dryRun?: boolean;
+    filename?: string;
+}): MigrationResult;
+//# sourceMappingURL=migration.d.ts.map

package/dist/library/src/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../library/src/migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,eAAe,CA6DjB"}

package/dist/library/src/pin-resolver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Version pin resolver.
+ *
+ * Resolves a version pin expression (^1.4, ~1.4, 1.4.x, latest, exact:1.4.2)
+ * against a set of available versions. Ties broken by highest semver.
+ *
+ * @docLink packages/library/api-reference#pin-resolver
+ */
+/**
+ * A version pin expression string.
+ *
+ * Supported formats: `exact:X.Y.Z`, `X.Y.Z` (bare), `^X.Y`, `~X.Y`, `X.Y.x`, `latest`.
+ *
+ * @docLink packages/library/api-reference#pin-resolver
+ */
+export type PinExpression = string;
+/**
+ * Result of a successful {@link resolvePin} call.
+ *
+ * @docLink packages/library/api-reference#pin-resolver
+ */
+export interface ResolveResult {
+    /** The matched version string. */
+    version: string;
+    /** How the match was made. */
+    match: "exact" | "range" | "latest";
+}
+/**
+ * Resolve a version pin expression against available versions.
+ *
+ * Supported pin formats:
+ *   - `exact:1.4.2`      — exact match only
+ *   - `1.4.2`            — exact match (bare version)
+ *   - `^1.4` or `^1.4.0` — caret range (>=1.4.0, <2.0.0)
+ *   - `~1.4` or `~1.4.0` — tilde range (>=1.4.0, <1.5.0)
+ *   - `1.4.x`            — same as ~1.4 (patch-level)
+ *   - `latest`           — highest available version
+ *
+ * @param pin - The pin expression string.
+ * @param availableVersions - All available version strings to match against.
+ * @returns The best matching version (highest within range), or null if no match.
+ * @docLink packages/library/api-reference#pin-resolver
+ */
+export declare function resolvePin(pin: PinExpression, availableVersions: string[]): ResolveResult | null;
+//# sourceMappingURL=pin-resolver.d.ts.map

package/dist/library/src/pin-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-resolver.d.ts","sourceRoot":"","sources":["../../../library/src/pin-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;CACrC;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,aAAa,GAAG,IAAI,CAwEhG"}

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

@@ -0,0 +1,105 @@
+/**
+ * applyPreset — the main orchestrator for preset application.
+ *
+ * Given a preset ref and user inputs, this function:
+ *   1. Parses the preset manifest
+ *   2. Validates all placeholder inputs
+ *   3. Resolves each item ref (asset, library-instance, nested-preset, cross-item)
+ *   4. Interpolates config and secrets
+ *   5. Creates Instances in the Library
+ *   6. Subscribes the workspace to created Instances
+ *   7. Stores secrets via SecretsRouter
+ *   8. Returns the apply result
+ *
+ * Nesting: nested preset refs are recursively applied (max depth 3).
+ * Outer-wins: outer preset's inputs override nested preset's defaults.
+ *
+ * NOTE: The `composes` field on preset items is validated at parse-time
+ * (cross-item refs resolve to declared IDs) but NOT interpreted at apply-time.
+ * Composition (e.g. attaching skills/connectors to an agent item) is a Phase 2
+ * concern — Task 1.7 will wire the composes declarations into the Instance's
+ * config as part of the agent binding step.
+ *
+ * @docLink packages/library/concepts#preset-application
+ */
+import type { PresetManifest } from "@skaile/workspaces/types/manifests";
+import type { SecretsRouter } from "@skaile/workspaces/secrets";
+import type { ILibrary, Instance, Subscription, PinPolicy } from "../library.js";
+/**
+ * Options for {@link applyPreset}.
+ *
+ * @docLink packages/library/concepts#preset-application
+ */
+export interface ApplyOpts {
+    /** The library for instance creation and subscription. */
+    library: ILibrary;
+    /** Workspace ID for subscription creation. */
+    workspaceId: string;
+    /** Pin policy for created instances (default: "minor-track"). */
+    pinPolicy?: PinPolicy;
+    /** SecretsRouter for secret storage. */
+    secretsRouter?: SecretsRouter;
+    /** Set of known preset refs (for nested detection). */
+    knownPresetRefs?: Set<string>;
+    /** Loader function for nested presets (given a ref, return manifest data). */
+    loadPreset?: (ref: string) => Promise<Record<string, unknown> | null>;
+    /** Current nesting depth (internal, used for recursion). */
+    _depth?: number;
+    /** Creator identity for audit trail. */
+    createdBy?: string;
+}
+/**
+ * Aggregated result of a {@link applyPreset} call.
+ *
+ * @docLink packages/library/concepts#preset-application
+ */
+export interface ApplyResult {
+    /** All instances created during this apply (including nested). */
+    instances: Instance[];
+    /** All subscriptions created during this apply. */
+    subscriptions: Subscription[];
+    /** Errors encountered (non-fatal — partial apply). */
+    errors: string[];
+}
+/**
+ * Per-item result used internally during preset application.
+ *
+ * @docLink packages/library/concepts#preset-application
+ */
+export interface ApplyItemResult {
+    /** Instances created for this item. */
+    instances: Instance[];
+    /** Subscriptions created for this item. */
+    subscriptions: Subscription[];
+    /** Non-fatal errors for this item. */
+    errors: string[];
+}
+/**
+ * Apply a parsed preset manifest.
+ *
+ * This is the primary entry point for CLI and platform consumers.
+ * It handles: validation → resolve → interpolate → create instances →
+ * subscribe → store secrets.
+ *
+ * @param presetRef - Canonical ref of the preset being applied.
+ * @param manifest - The validated preset manifest (already parsed).
+ * @param inputs - User-provided placeholder values (key to value).
+ * @param opts - Apply options (library, workspace, secrets, nesting context).
+ * @returns Aggregated apply result.
+ * @docLink packages/library/concepts#preset-application
+ */
+export declare function applyPreset(presetRef: string, manifest: PresetManifest, inputs: Record<string, unknown>, opts: ApplyOpts): Promise<ApplyResult>;
+/**
+ * Apply a preset from raw YAML data.
+ *
+ * Convenience wrapper that parses first, then applies.
+ *
+ * @param presetRef - Canonical ref of the preset.
+ * @param data - Raw parsed YAML object (pre-read from disk).
+ * @param inputs - User-provided placeholder values.
+ * @param opts - Apply options.
+ * @returns Aggregated apply result, with parse errors in `errors` if parse fails.
+ * @docLink packages/library/concepts#preset-application
+ */
+export declare function applyPresetFromData(presetRef: string, data: unknown, inputs: Record<string, unknown>, opts: ApplyOpts): Promise<ApplyResult>;
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,oCAAoC,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAUjF;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,OAAO,EAAE,QAAQ,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wCAAwC;IACxC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,uDAAuD;IACvD,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACtE,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,mDAAmD;IACnD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,2CAA2C;IAC3C,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,WAAW,CAAC,CAUtB"}

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

@@ -0,0 +1,13 @@
+export { parsePreset, parsePresetYaml, detectNestedPresetRefs, validateNestingDepth, } from "./parse.js";
+export type { ParseResult } from "./parse.js";
+export { classifyRef, extractLibraryInstanceId, resolveItem, resolveAllItems, } from "./resolve-item.js";
+export type { ItemRefKind, ResolvedAssetItem, ResolvedLibraryItem, ResolvedNestedPresetItem, ResolvedCrossItemRef, ResolvedItem, } from "./resolve-item.js";
+export { validatePlaceholder, validateAllPlaceholders, queryInstancePickerChoices, getDefaultValue, isSecretPlaceholder, } from "./placeholders.js";
+export type { PlaceholderValidationResult, InstancePickerOptions, InstancePickerChoice, } from "./placeholders.js";
+export { interpolate, storeSecrets, hasInterpolationTokens, extractReferencedKeys, InterpolationError, } from "./interpolate.js";
+export type { InterpolationContext, InterpolationResult, } from "./interpolate.js";
+export { applyPreset, applyPresetFromData } from "./apply.js";
+export type { ApplyOpts, ApplyResult, ApplyItemResult, } from "./apply.js";
+export { detectChanges, evaluateUpgrade, applyNonStructuralUpgrade, } from "./upgrade.js";
+export type { ChangeKind, PresetDiff, UpgradeResult } from "./upgrade.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,WAAW,EACX,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC9D,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,109 @@
+/**
+ * Two-namespace interpolation for preset item config.
+ *
+ * Syntax:
+ *   - `${INPUT:KEY}` — placeholder value inlined into Instance.config
+ *   - `${SECRET:KEY}` — stored as credential_ref in Instance; value is handed
+ *     to SecretsRouter.setSecret separately
+ *
+ * The `materialize` map on a preset item defines how placeholder values fold
+ * into the Instance config JSON. Each key is a dotted config path; each value
+ * is a template string that may contain ${INPUT:KEY} or ${SECRET:KEY} tokens.
+ *
+ * Constraints:
+ *   - `${SECRET:KEY}` MUST be the sole token in a template (no mixing with
+ *     INPUT or literal text). Mixed templates would embed non-secret data
+ *     into the stored secret, breaking update semantics.
+ *   - All referenced keys MUST exist in the context. Missing keys throw
+ *     InterpolationError rather than silently producing empty strings.
+ *
+ * Example:
+ * ```yaml
+ * materialize:
+ *   host: "${INPUT:HOST}"
+ *   port: "${INPUT:PORT}"
+ *   credentials.api_key: "${SECRET:API_KEY}"
+ * ```
+ *
+ * @docLink packages/library/concepts#interpolation
+ */
+import type { SecretsRouter } from "@skaile/workspaces/secrets";
+/**
+ * Runtime context passed to {@link interpolate} containing resolved placeholder values.
+ *
+ * @docLink packages/library/concepts#interpolation
+ */
+export interface InterpolationContext {
+    /** Validated placeholder values (key to value). */
+    inputs: Record<string, unknown>;
+    /** Secret values (key to plaintext value) to be stored via SecretsRouter. */
+    secrets: Record<string, string>;
+}
+/**
+ * Result produced by {@link interpolate}.
+ *
+ * @docLink packages/library/concepts#interpolation
+ */
+export interface InterpolationResult {
+    /** The materialized config to set on the Instance. */
+    config: Record<string, unknown>;
+    /** Credential ref to set on the Instance (if any secret placeholders used). */
+    credentialRef?: string;
+    /** Secret entries that need to be stored (ref to plaintext value). */
+    secretsToStore: Array<{
+        ref: string;
+        value: string;
+    }>;
+}
+/**
+ * Thrown when a template references a missing key or mixes `${SECRET:...}` with other tokens.
+ *
+ * @docLink packages/library/concepts#interpolation
+ */
+export declare class InterpolationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Interpolate a materialize map with placeholder values.
+ *
+ * @param materialize - Map of dotted config paths to template strings.
+ * @param baseConfig - Pre-existing item config (author-prefilled values).
+ * @param context - Validated input values and secret values.
+ * @param credentialRefPrefix - Prefix for generated credential refs.
+ * @returns Interpolated config and secrets to store.
+ * @throws {InterpolationError} if a referenced key is missing or a SECRET token
+ *   is mixed with other tokens in the same template.
+ * @docLink packages/library/concepts#interpolation
+ */
+export declare function interpolate(materialize: Record<string, string> | undefined, baseConfig: Record<string, unknown> | undefined, context: InterpolationContext, credentialRefPrefix: string): InterpolationResult;
+/**
+ * Store interpolated secrets via the SecretsRouter.
+ *
+ * @param router - The SecretsRouter instance.
+ * @param secretsToStore - Array of `{ref, value}` pairs from {@link InterpolationResult}.
+ * @docLink packages/library/concepts#interpolation
+ */
+export declare function storeSecrets(router: SecretsRouter, secretsToStore: Array<{
+    ref: string;
+    value: string;
+}>): Promise<void>;
+/**
+ * Check if a template string contains any interpolation tokens (`${INPUT:...}` or `${SECRET:...}`).
+ *
+ * @param template - The template string to inspect.
+ * @returns `true` if at least one token is present.
+ * @docLink packages/library/concepts#interpolation
+ */
+export declare function hasInterpolationTokens(template: string): boolean;
+/**
+ * Extract all placeholder keys referenced in a materialize map.
+ *
+ * @param materialize - Map of dotted config paths to template strings.
+ * @returns Sets of unique `INPUT` and `SECRET` key names referenced across all templates.
+ * @docLink packages/library/concepts#interpolation
+ */
+export declare function extractReferencedKeys(materialize: Record<string, string>): {
+    inputKeys: string[];
+    secretKeys: string[];
+};
+//# sourceMappingURL=interpolate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/interpolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAMhE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,cAAc,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC/C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC/C,OAAO,EAAE,oBAAoB,EAC7B,mBAAmB,EAAE,MAAM,GAC1B,mBAAmB,CAuCrB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;IAC1E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAeA"}

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

@@ -0,0 +1,65 @@
+/**
+ * Preset parser — validates *.preset.yaml content against the PresetManifestSchema.
+ *
+ * Also performs structural validation beyond what zod alone covers:
+ *   - Unique item IDs within the preset
+ *   - Cycle detection for nested preset refs (max depth 3)
+ *   - Cross-item refs (#item-id) resolve to declared items
+ *
+ * @docLink packages/library/concepts#preset-parsing
+ */
+import { type PresetManifest } from "@skaile/workspaces/types/manifests";
+/**
+ * Result of parsing and validating a preset manifest.
+ *
+ * When `ok` is false, `errors` contains human-readable messages.
+ * `preset` may still be set on partial success (structural errors after Zod passes).
+ *
+ * @docLink packages/library/concepts#preset-parsing
+ */
+export interface ParseResult {
+    /** Whether the preset passed all validation checks. */
+    ok: boolean;
+    /** The validated preset manifest (set even on structural errors after Zod passes). */
+    preset?: PresetManifest;
+    /** Validation error messages. */
+    errors: string[];
+}
+/**
+ * Parse and validate a preset manifest object.
+ *
+ * @param data - Raw parsed YAML content (from `yaml` or similar).
+ * @returns ParseResult with validated preset or error messages.
+ * @docLink packages/library/concepts#preset-parsing
+ */
+export declare function parsePreset(data: unknown): ParseResult;
+/**
+ * Parse preset from a raw YAML string.
+ *
+ * @param yamlContent - Raw YAML string content of a `*.preset.yaml` file.
+ * @returns ParseResult — includes a YAML parse error in `errors` if the string is malformed.
+ * @docLink packages/library/concepts#preset-parsing
+ */
+export declare function parsePresetYaml(yamlContent: string): ParseResult;
+/**
+ * Detect nested preset refs within a preset's items.
+ *
+ * A ref is classified as a nested preset if it appears in `knownPresetRefs`.
+ * Refs starting with `library://` or `#` are always skipped.
+ *
+ * @param preset - Validated preset manifest.
+ * @param knownPresetRefs - Optional set of refs known to be presets.
+ * @returns Array of refs that are nested presets.
+ * @docLink packages/library/concepts#preset-parsing
+ */
+export declare function detectNestedPresetRefs(preset: PresetManifest, knownPresetRefs?: Set<string>): string[];
+/**
+ * Validate nesting depth. Max depth is 3.
+ *
+ * @param presetRef - The ref of the preset being validated.
+ * @param currentDepth - Current nesting depth (0 = top-level).
+ * @returns Error message string if depth exceeded, undefined otherwise.
+ * @docLink packages/library/concepts#preset-parsing
+ */
+export declare function validateNestingDepth(presetRef: string, currentDepth: number): string | undefined;
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../library/src/preset/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAM/F;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,EAAE,EAAE,OAAO,CAAC;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CA0EtD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAWhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,MAAM,EAAE,CAYV;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMhG"}