@skaile/workspaces 6.14.0 → 6.16.0

package/dist/asset-manager/src/read/diff.d.ts

@@ -0,0 +1,109 @@
+import { type AgentInstanceConfig, type AssetRef } from "@skaile/workspaces/core";
+import { AmReadOutdated } from "./outdated.js";
+/**
+ * Replace the `diff -u` timestamps of the `---` / `+++` header lines with a label of the side
+ * (`--- <file> (deployed)`, `+++ <file> (library)`). A file that is missing on one side shows
+ * the epoch there (`1970-01-01`), which says nothing a reader wants (p1693).
+ */
+export declare function labelDiffHeaders(diff: string, from: string, to: string): string;
+/**
+ * Outcome of `AssetManager.diff()` — distinguishes an unknown ref from a real
+ * "no differences" so callers never conflate the two.
+ *
+ * - `not-found` — the ref resolves to no asset (source, store or library).
+ * - `not-deployed` — the asset resolves, but there is no deployed copy to compare.
+ * - `identical` — the deployed copy matches the source.
+ * - `differs` — the deployed copy differs; `diff` carries the unified diff. `fileSetDiffers` is
+ *   set when a file is missing from the deployed copy or one is not part of the asset (an
+ *   `mcp-server` payload): that is a state problem as for a skill, so `diff` lists it and exits 1.
+ * - `no-files` — the asset kind has no files of its own (a preset: its items are the assets to
+ *   compare) and the lock records it.
+ *
+ * @docLink packages/asset-manager/concepts#asset-manager
+ */
+export type DiffResult = {
+    status: "not-found";
+} | {
+    status: "not-deployed";
+} | {
+    status: "identical";
+} | {
+    status: "no-files";
+} | {
+    status: "differs";
+    diff: string;
+    fileSetDiffers?: true;
+};
+/** Diff and patch*. One layer of the `AssetManager` class chain (see `asset-manager/CLAUDE.md`). */
+export declare abstract class AmReadDiff extends AmReadOutdated {
+    /**
+     * {@link AssetManager.diff} for a locked source or store asset whose bytes are not on disk:
+     * the deployed copy against the per-file hashes the lock records. No text to show without the
+     * locked bytes, so an edited file is named and the way to fetch them is. `null` when the lock
+     * has no such entry or the kind is rendered (an agent), not copied.
+     */
+    protected diffAgainstLock(want: AssetRef): Promise<DiffResult | null>;
+    /**
+     * Produce a unified diff from the deployed asset to its catalog source: `-` lines
+     * are in the deployed copy only (local edits `update` would overwrite), `+` lines
+     * are in the source only (what `update` would add).
+     *
+     * Useful for detecting manual edits to deployed files or seeing what an upstream
+     * change would bring in; also for verifying that a patch
+     * was applied correctly.
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     * @returns A {@link DiffResult}: `not-found` (unknown ref), `not-deployed`,
+     *   `identical`, or `differs` with the unified diff.
+     * @throws When `diff(1)` itself fails (exit status other than 0/1).
+     */
+    diff(ref: string): Promise<DiffResult>;
+    /**
+     * The agent instances of `skaile.yaml` whose `ref` names `want` (an `agent:` ref, matched on
+     * name and, when both name one, publisher) and bind to an agent definition directory.
+     */
+    protected instancesBoundTo(want: AssetRef): Array<{
+        id: string;
+        srcDir: string;
+        config: AgentInstanceConfig;
+    }>;
+    /**
+     * Extract a deployed asset into a patch working directory for editing.
+     *
+     * Copies the deployed asset to `.skaile/patches/<kind>-<name>/` so changes
+     * can be made there and then committed as a patch file via `patchCommit`.
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     * @returns Absolute path to the patch working directory.
+     * @throws When the asset cannot be found in the catalog.
+     */
+    patch(ref: string): Promise<string>;
+    /**
+     * Generate a `.patch` file from changes made in the patch working directory.
+     *
+     * Diffs the patch working directory against the original catalog source and
+     * writes the result to `.skaile/patches/<kind>-<name>.patch`.
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     * @returns Absolute path to the generated `.patch` file.
+     * @throws When the patch working directory does not exist or no differences are found.
+     */
+    patchCommit(ref: string): Promise<string>;
+    /**
+     * Apply the committed patch file to the repository clone and open a contribution branch.
+     *
+     * Applies `.skaile/patches/<kind>-<name>.patch` to the repository clone, creates a
+     * `patch/<kind>-<name>` branch, and stages a commit — ready to push via `contribPush`.
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     * @throws When the asset is not found, has no repository, or the patch file is missing.
+     */
+    patchSubmit(ref: string): Promise<void>;
+    /**
+     * Delete the patch working directory and patch file for an asset.
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     */
+    patchRemove(ref: string): void;
+}
+//# sourceMappingURL=diff.d.ts.map

package/dist/asset-manager/src/read/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../../asset-manager/src/read/diff.ts"],"names":[],"mappings":"AAGA,OAAO,EAUL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE/D,oGAAoG;AACpG,8BAAsB,UAAW,SAAQ,cAAc;IACrD;;;;;OAKG;cACa,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA+B3E;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA2G5C;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CACxB,IAAI,EAAE,QAAQ,GACb,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAC;IA2BrE;;;;;;;;;OASG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMzC;;;;;;;;;OASG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB/C;;;;;;;;OAQG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB7C;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAW/B"}

package/dist/asset-manager/src/read/doctor.d.ts

@@ -0,0 +1,116 @@
+import { type CatalogEntry, type LockFile } from "@skaile/workspaces/core";
+import type { DepIssue, LockGap } from "../shared/types.js";
+import { AmReadGaps } from "./gaps.js";
+/**
+ * The project's state as {@link AssetManager.projectState} computes it: the one verdict
+ * `check`, `doctor`, `outdated`, `diff` and `install --locked` share.
+ *
+ * @docLink packages/asset-manager/concepts#asset-manager
+ */
+export interface ProjectState {
+    /** Every problem, one {@link LockGap} each; empty when the project is as declared and locked. */
+    gaps: LockGap[];
+    /** What {@link AssetManager.doctor} found: the unmet requirements (a `doctor` table row each) and the locked assets nothing provides. */
+    requirements: DepIssue[];
+}
+/** Doctor and projectState. One layer of the `AssetManager` class chain (see `asset-manager/CLAUDE.md`). */
+export declare abstract class AmReadDoctor extends AmReadGaps {
+    /**
+     * Scan deployed assets for unsatisfied transitive dependencies.
+     *
+     * For each deployed asset, checks that all entries in its `requires` list are
+     * also deployed. Returns a list of issues with a flag indicating whether the
+     * missing dependency can be resolved from a configured repository or library.
+     *
+     * A deployed asset is looked up by its publisher-qualified identity taken from
+     * the lock key (`kind:@pub/name`), so library and source assets resolve alike.
+     * A lock-managed asset that no source or library can be found for is reported
+     * as an issue with `unresolved: true` (its `requires` cannot be verified);
+     * unmanaged deployed files carry no declared origin and are skipped.
+     *
+     * @returns Array of {@link DepIssue} objects. An empty array means the workspace is healthy.
+     */
+    doctor(): Promise<DepIssue[]>;
+    /**
+     * The project's state as one verdict: every way the project differs from what it
+     * declares and locks. `skaile check`, `skaile doctor`, `skaile outdated`, `skaile diff`
+     * and `skaile install --locked` all take their verdict and exit code from this one list,
+     * so one situation reads the same in all five.
+     *
+     * - `declared` — a `skaile.yaml` dependency with no lock entry (library or source gone,
+     *   unresolvable ref, never installed);
+     * - `invalid` — a `dependencies:` entry that is not a parseable ref;
+     * - `drift` — a locked asset whose deployed files are missing;
+     * - `pin` — a declared `#pin` that no lock entry for that asset satisfies;
+     * - `requires` — a deployed asset's `requires` (or a declared preset's item) that is not
+     *   deployed (so not locked either);
+     * - `unresolved` — a lock-managed deployed asset that no source or library holds any more;
+     * - `library` — a locked library asset whose library is not registered (renamed or
+     *   removed) or no longer holds it, while another library holds it now;
+     * - `incomplete` — a deployed library asset that lacks files of its library entry;
+     * - `content` — a locked library asset whose files in the library changed since the lock
+     *   (or whose lock hash predates the one shared asset hash); `skaile install` re-locks it;
+     * - `agent` — an `agents.<id>.ref` (or `agent.definition`) that binds to no agent.
+     *
+     * An asset appears once for what the lock says about it (`unresolved`, else `library`,
+     * else `drift`). A declared ref no registered library or source holds names
+     * `skaile library init` / `skaile remove`, never `skaile install`: `install` has nothing
+     * to resolve it from.
+     *
+     * Project mode only: a global manager (`global: true`) has no gaps. A project without
+     * `skaile.yaml` has no declared set, so only the lock and deployed-asset gaps can appear.
+     *
+     * @returns The {@link ProjectState}; `gaps` is empty when the project is as declared and locked.
+     */
+    projectState(): Promise<ProjectState>;
+    /**
+     * The first `../` compose folder of the locked library agent `kind:name` whose library copy
+     * changed since the lock, or `undefined` (project scope only). `install --locked` cannot
+     * restore such an agent; `update` moves the lock to the library's copy.
+     */
+    protected lockedComposeDrift(lock: LockFile, kind: string, name: string): Promise<string | undefined>;
+    /**
+     * The `check`, `doctor` and `add` lines for an agent instance whose agent names an `extends`
+     * parent that its folder does not hold: the instance is rendered without the parent's
+     * settings. Not a gap (nothing fails, the publisher has to ship the parent), so a `!` line.
+     * Read from the project's cached agent source on every call, so nothing records that it was
+     * said: the line is a fact of the project and goes once the parent is there. Empty in global
+     * mode.
+     *
+     * @param onlyAgent - Only the instances that bind this agent (`add` names the one it added).
+     */
+    missingParentNotices(onlyAgent?: string): string[];
+    /**
+     * The agent instances whose `ref` binds to no agent and that the install about to run does not
+     * deploy (`entries`), worded as `renderAgentInstances` words them (`errors`, and the resolver's
+     * own text in `details` for `--verbose`). The install cannot fix them, and its instance render
+     * after the deploy would end the run `Failed` having rewritten files. A ref the `entries` hold
+     * binds once they are deployed, so it is no cause.
+     */
+    protected unboundInstanceErrors(entries: readonly CatalogEntry[]): Promise<{
+        errors: string[];
+        details: string[];
+    }>;
+    /**
+     * Why the `agent:` ref of agent instance `id` binds to nothing, as the phrase that follows
+     * the ref in a {@link LockGap}; see {@link AssetManager.unboundAgentAdvice}.
+     */
+    protected unboundAgentReason(id: string, ref: string): Promise<string>;
+    /**
+     * What is wrong with an `agent:` ref bound by an agent instance and what to do (`lead`, then
+     * `advice`). `skaile add` is named only when a registered library or source holds the agent
+     * and `add` takes the ref (it needs a publisher); otherwise the user registers the library
+     * that holds it, writes the publisher, or drops the binding.
+     */
+    protected unboundAgentAdvice(ref: string): Promise<{
+        lead: string;
+        advice: string;
+    }>;
+    /**
+     * Whether the library a locked agent names is here and holds the agent, or the agent comes
+     * from a source or store: `install --locked` restores it, so its missing cache is no fault of
+     * the library.
+     */
+    protected lockedAgentLibraryHolds(lockKey: string): Promise<boolean>;
+}
+//# sourceMappingURL=doctor.d.ts.map

package/dist/asset-manager/src/read/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../../asset-manager/src/read/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,EAcL,KAAK,YAAY,EACjB,KAAK,QAAQ,EAEd,MAAM,yBAAyB,CAAC;AAiBjC,OAAO,KAAK,EAAE,QAAQ,EAAwB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAYvC;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iGAAiG;IACjG,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,yIAAyI;IACzI,YAAY,EAAE,QAAQ,EAAE,CAAC;CAC1B;AAED,4GAA4G;AAC5G,8BAAsB,YAAa,SAAQ,UAAU;IAGnD;;;;;;;;;;;;;;OAcG;IACG,MAAM,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAyHnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;IA8R3C;;;;OAIG;cACa,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAa9B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IASlD;;;;;;OAMG;cACa,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAwBnD;;;OAGG;cACa,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK5E;;;;;OAKG;cACa,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA6F1F;;;;OAIG;cACa,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAe3E"}

package/dist/asset-manager/src/read/gaps.d.ts

@@ -0,0 +1,120 @@
+import { buildProvenanceIndex, type AssetRef, type LockFile, type StoreEntry } from "@skaile/workspaces/core";
+import type { DepIssue, LockGap } from "../shared/types.js";
+import { AmReadDiff } from "./diff.js";
+/** Lock gaps and declared gaps. One layer of the `AssetManager` class chain (see `asset-manager/CLAUDE.md`). */
+export declare abstract class AmReadGaps extends AmReadDiff {
+    /** @deprecated Use `(await projectState()).gaps`; removed in the next major. */
+    lockGaps(): Promise<LockGap[]>;
+    /**
+     * The {@link ProjectState} gaps that name `ref`: as the gap's own ref, or as the asset
+     * whose requirement is unmet. A ref without a publisher matches any publisher.
+     *
+     * @param ref - Asset ref in `kind:name` or `kind:@publisher/name` form.
+     */
+    gapsOf(ref: string): Promise<LockGap[]>;
+    /**
+     * The {@link ProjectState} gaps of everything `ref` requires, transitively: what `check`
+     * says about the requirements of `ref`, so a command that answers for one asset (`diff`)
+     * does not call it fine while a requirement of it is broken. The requirements are read from
+     * the deployed copies (the lock records no edges), the way `remove` and `install` read them
+     * when no library holds the asset any more. The gaps of `ref` itself are not included
+     * ({@link gapsOf}).
+     *
+     * @param ref - Asset ref in `kind:name` or `kind:@publisher/name` form.
+     */
+    requirementGapsOf(ref: string): Promise<LockGap[]>;
+    /**
+     * Locked library assets whose library cannot supply them: the library is not registered
+     * (renamed or removed) or no longer holds the asset. Another library holding it makes the
+     * gap fixable by `skaile install` (it re-locks); otherwise the user registers the library
+     * again or drops the dependency.
+     *
+     * @param named - `kind:name` identities already reported; they are skipped.
+     */
+    protected libraryOriginGaps(named: ReadonlySet<string>): Promise<LockGap[]>;
+    /**
+     * The locked source assets whose source is no longer in `skaile.yaml` `sources:` (`source
+     * remove`, a hand edit), keyed by lock key. ONE sentence for it: `check`, `doctor`, `outdated`,
+     * `install`, `install --locked` and `update` all say it (p1062), and none re-clones the source.
+     * A GitHub lock entry that no source declares counts as store-supplied only when a store
+     * lists the ref (OQ3): a configured store alone proves nothing, as it may never have held
+     * the asset. `check`, `doctor` and `outdated` read the store's cached catalog and never touch
+     * the network; `install` and `update` (`online`) ask the store itself.
+     *
+     * @param inScope - Only these lock keys count (`install` prunes an undeclared entry as usual).
+     * @param online - Ask the stores when the cached catalog does not list the ref.
+     */
+    protected orphanedSourceGaps(inScope?: ReadonlySet<string>, online?: boolean): Promise<Map<string, LockGap>>;
+    /**
+     * `true` when one of `stores` lists `ref` (a canonical lock key): its cached catalog holds it
+     * or, with `online`, the store answers for it. An injected store fetcher is the store client
+     * itself, so it is asked either way. A store an online install cannot ask (unreachable,
+     * air-gapped, `--no-catalog`) may hold the ref; `check` never asks, so a store lists only what
+     * its cached catalog holds.
+     */
+    protected storeListsRef(stores: readonly StoreEntry[], ref: string, online: boolean, lockedRef?: string): Promise<boolean>;
+    /**
+     * Locked source assets whose source cannot supply them any more: the source is no longer in
+     * `skaile.yaml` `sources:` (`source remove`, a hand edit), or it is there but now publishes
+     * the asset under another publisher (`source add <url> --publisher`). `skaile install` has
+     * nothing to restore them from, so the fix is manual. A source of a store-resolved lock entry
+     * is not told apart from one, so no source is called missing while a `stores:` entry exists.
+     *
+     * @param named - `kind:name` identities already reported; they are skipped.
+     * @param index - What the registered sources publish today.
+     */
+    protected sourceOriginGaps(named: ReadonlySet<string>, index: Awaited<ReturnType<typeof buildProvenanceIndex>>): Promise<LockGap[]>;
+    /**
+     * The locked assets that come from the source `url` (a `sources:` entry): canonical refs,
+     * `kind:@publisher/name`. `skaile source remove` refuses while this list is not empty.
+     */
+    lockedFromSource(url: string): string[];
+    /**
+     * The `skaile.yaml` side of {@link AssetManager.projectState}: declared refs that do not
+     * parse, never resolved into the lock, are not materialized, or contradict a `#pin`.
+     * A project with no (or an unreadable) `skaile.yaml` has no declared set to reconcile.
+     *
+     * @param requirements - What {@link AssetManager.doctor} found; a declared preset whose
+     *   items it already named needs no second line.
+     * @param named - `kind:name` identities already reported; a declared asset among them
+     *   needs no `drift` line.
+     */
+    protected declaredGaps(requirements: readonly DepIssue[], named: ReadonlySet<string>): Promise<LockGap[]>;
+    /** Whether the lock's `presets` slice records `want` (kind, name and, when both carry one, publisher). */
+    protected presetRecorded(want: AssetRef): boolean;
+    /**
+     * The first requirement, direct or transitive, of the declared `ref` that no local source or
+     * library holds and that nothing in the project already provides — the case `install` ends
+     * with `Missing: … nothing was installed`. `undefined` when every requirement is held, when a
+     * store is declared (it may hold the requirement and a check never goes to the network), or
+     * when `ref` itself resolves to nothing.
+     */
+    protected unmetRequirementOf(ref: string): Promise<string | undefined>;
+    /**
+     * Whether `skaile install` can resolve a declared ref: a source or library holds it, or the
+     * project declares a store that may. The global catalog is not asked: a check never goes
+     * to the network.
+     */
+    protected declaredRefResolvable(ref: string): Promise<boolean>;
+    /**
+     * Items of each declared `preset:` dependency that the lock does not cover.
+     *
+     * A preset is never locked itself; the lock lists only its expanded items, so an
+     * item missing from the lock never resolved (or was declared after the last
+     * install). Presets are read from the local sources and libraries (nested presets
+     * followed); one only a store holds cannot be read without the network and
+     * reports no gaps. Without a lock nothing is reported: `list` and `check` already
+     * show a never-installed declaration as `declared`.
+     *
+     * @param declared - The `dependencies:` refs as written in `skaile.yaml`.
+     * @param lock - The current lock, or `null` when none exists.
+     * @returns Declared preset ref → its uncovered items; `resolvable` is `true` when a
+     *   local source or library offers the item (so `skaile install` can fix it).
+     *   Presets without gaps are absent.
+     */
+    protected declaredPresetGaps(declared: readonly string[], lock: LockFile | null): Promise<Map<string, Array<{
+        ref: string;
+        resolvable: boolean;
+    }>>>;
+}
+//# sourceMappingURL=gaps.d.ts.map

package/dist/asset-manager/src/read/gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../../../asset-manager/src/read/gaps.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,oBAAoB,EAQpB,KAAK,QAAQ,EAGb,KAAK,QAAQ,EAGb,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAoBjC,OAAO,KAAK,EAAiB,QAAQ,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAmBvC,gHAAgH;AAChH,8BAAsB,UAAW,SAAQ,UAAU;IACjD,gFAAgF;IAC1E,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIpC;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAiB7C;;;;;;;;;OASG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA+CxD;;;;;;;OAOG;cACa,iBAAiB,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAqFjF;;;;;;;;;;;OAWG;cACa,kBAAkB,CAChC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,MAAM,UAAQ,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAqDhC;;;;;;OAMG;cACa,aAAa,CAC3B,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IA8BnB;;;;;;;;;OASG;cACa,gBAAgB,CAC9B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,GACtD,OAAO,CAAC,OAAO,EAAE,CAAC;IA8BrB;;;OAGG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAWvC;;;;;;;;;OASG;cACa,YAAY,CAC1B,YAAY,EAAE,SAAS,QAAQ,EAAE,EACjC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,OAAO,CAAC,OAAO,EAAE,CAAC;IAgHrB,0GAA0G;IAC1G,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;IAYjD;;;;;;OAMG;cACa,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IA+B5E;;;;OAIG;cACa,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpE;;;;;;;;;;;;;;;OAeG;cACa,kBAAkB,CAChC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,EAAE,QAAQ,GAAG,IAAI,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;CAgErE"}

package/dist/asset-manager/src/read/graph.d.ts

@@ -0,0 +1,69 @@
+import { type AssetRef, type LockFile } from "@skaile/workspaces/core";
+import { AmInstall } from "../install/install.js";
+/**
+ * A node in the resolved dependency tree (returned by `AssetManager.tree()`).
+ *
+ * @docLink packages/asset-manager/concepts#asset-manager
+ */
+export interface DependencyNode {
+    /** Lock key (`kind:@publisher/name#version`), or `"project"` for the root node. */
+    ref: string;
+    /** Assets this node requires, nested under it. */
+    children: DependencyNode[];
+}
+/** Tree and why. One layer of the `AssetManager` class chain (see `asset-manager/CLAUDE.md`). */
+export declare abstract class AmReadGraph extends AmInstall {
+    /**
+     * Requirement graph of the locked assets, for {@link tree} / {@link why} / removal pruning.
+     *
+     * The lock records no edges, so they are rebuilt from each locked asset's own
+     * declaration (`requires`, manifest `dependencies`, a preset's items) — the same
+     * source the install walk reads, via {@link info}. An asset that no source or
+     * library can be found for has no known requirements. Nodes are lock keys, plus
+     * each declared `preset:` that the lock does not carry (a preset is expanded at
+     * install, never locked), keyed by its declared ref.
+     *
+     * @returns `requires` (node → the lock keys it requires), `roots` (nodes
+     *   `skaile.yaml` declares) and `findKey` (a ref → its lock key, version-agnostic).
+     */
+    protected lockedGraph(lock: LockFile): Promise<{
+        requires: Map<string, string[]>;
+        roots: string[];
+        findKey: (ref: string) => string | undefined;
+    }>;
+    /**
+     * Build the resolved dependency tree from the lock file.
+     *
+     * Required assets nest under the asset that requires them (see {@link lockedGraph});
+     * an asset required by several parents appears under each, and a dependency cycle
+     * is cut where it would repeat.
+     *
+     * @returns Root {@link DependencyNode} with `ref === "project"` whose children
+     *   are the directly-declared assets, followed by locked assets nothing requires,
+     *   each with the assets it requires as children.
+     *   Returns a single node with `ref === "(no lock file)"` when no lock exists.
+     */
+    tree(): Promise<DependencyNode>;
+    /**
+     * Explain why an asset is installed by tracing its dependency chain.
+     *
+     * The chain is read from the requirement graph ({@link lockedGraph}): the asset,
+     * then the asset that requires it, and so on up to a dependency `skaile.yaml`
+     * declares (the shortest such path; cycles are not followed twice).
+     *
+     * @param ref - Asset ref in `kind:name` form.
+     * @returns Chain of refs from the asset back to `"direct (skaile.yaml)"`; an asset
+     *   no declared dependency reaches ends in `"not required by a declared dependency"`
+     *   instead. `[]` when the asset is not in the lock file.
+     */
+    why(ref: string): Promise<string[]>;
+    /**
+     * The {@link AssetManager.why} chain of a preset. A preset is never a lock asset: its record
+     * is the lock's `presets` slice. Declared in `skaile.yaml` it is `direct`; one only a declared
+     * preset nests is traced through the presets that list it.
+     *
+     * @returns `[]` when the lock does not record the preset.
+     */
+    protected whyPreset(lock: LockFile, asked: AssetRef): Promise<string[]>;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/asset-manager/src/read/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../../asset-manager/src/read/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQlD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,iGAAiG;AACjG,8BAAsB,WAAY,SAAQ,SAAS;IACjD;;;;;;;;;;;;OAYG;cACa,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QACnD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAChC,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;KAC9C,CAAC;IA8DF;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;IA+BrC;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmDzC;;;;;;OAMG;cACa,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAkD9E"}

package/dist/asset-manager/src/read/outdated.d.ts

@@ -0,0 +1,152 @@
+import { type AssetRef, type LockEntry, type LockFile } from "@skaile/workspaces/core";
+import { type DeployableEntry } from "../installer.js";
+import { AmReadGraph } from "./graph.js";
+/**
+ * An installed asset whose source repository is behind the remote.
+ *
+ * @docLink packages/asset-manager/concepts#asset-manager
+ */
+export interface OutdatedEntry {
+    /** Asset kind (`skill`, `agent`, `prompt`, `flow`, `contract`). */
+    kind: string;
+    /** Asset name as registered in the catalog. */
+    name: string;
+    /** Repository that provides this asset. */
+    publisher: string;
+    /** Version string recorded in the lock file at install time. */
+    currentVersion: string;
+    /** Number of commits the local repository is behind the remote (always 0 for a library asset). */
+    behind: number;
+    /** Library-origin asset only: the version the library index now offers (newer than `currentVersion`). */
+    latestVersion?: string;
+    /** Library-origin asset only: name of the library the asset was locked from. */
+    library?: string;
+    /**
+     * Set when the locked asset cannot be checked or is not in place: its library is
+     * not registered (renamed or removed), its deployed copy is gone, or the lock does not
+     * cover it ({@link AssetManager.projectState}). Such a row has no `latestVersion`.
+     */
+    problem?: string;
+    /**
+     * Library-origin asset only: the library's files on disk differ from the content
+     * hash recorded in the lock at the same version (edited in place, no version bump).
+     * `skaile update` re-locks and re-deploys them; `install` keeps the lock (OQ13).
+     */
+    contentChanged?: boolean;
+    /**
+     * Library-origin asset only: the library now holds this OLDER version than the lock. `install`
+     * keeps the lock and the deployed copy; only `update` moves it back (`replaced X → Y`).
+     */
+    libraryOlder?: string;
+    /**
+     * Library-origin asset only: the library `update` would re-lock the asset from, when it is
+     * not the one the lock names (`library`), e.g. after `skaile library default <other>`.
+     */
+    movesTo?: string;
+    /**
+     * Source asset only: the version the next `install` or `update` locks it under, when that
+     * is not the locked key. A `0.0.0-sha.<commit>` key whose file now declares a version is
+     * re-keyed (`0.0.0-sha.7de3555 → 0.2.0`, p914).
+     */
+    rekeyTo?: string;
+    /**
+     * Set when the row only reports a newer version than the `#version` pin of the asset's ref
+     * in `skaile.yaml` (`latestVersion`). The pin is deliberate: `update` leaves it and `outdated`
+     * does not fail on it.
+     */
+    pinned?: boolean;
+    /**
+     * Set on a `problem` row whose cause `skaile install` cannot fix: the asset's library is
+     * gone or its publisher changed, so the ref resolves nowhere. `problem` names what to
+     * change instead (`skaile library init …`, the ref under its new publisher).
+     */
+    manualFix?: true;
+}
+/** Outdated. One layer of the `AssetManager` class chain (see `asset-manager/CLAUDE.md`). */
+export declare abstract class AmReadOutdated extends AmReadGraph {
+    /**
+     * List installed assets that have a newer upstream available.
+     *
+     * Two kinds of staleness are reported:
+     * - **Source assets** — only remote repositories (not local paths) are checked;
+     *   `behind` counts the commits the clone is missing from the remote plus the
+     *   commits the clone moved past the locked commit (`source sync` after `add`).
+     * - **Library assets** — a library-origin lock entry whose library files on disk
+     *   (not the index, which lags until `skaile library index`) hold a newer version
+     *   than the locked one (`latestVersion`, `library` set), or the same version with
+     *   different bytes (`contentChanged`). `behind` is 0.
+     * - **Project state** — every {@link AssetManager.projectState} gap (an unregistered or
+     *   renamed library, a missing deployed copy, a declared dependency or a deployed asset's
+     *   `requires` with no lock entry, a lock that contradicts a `skaile.yaml` pin) as a
+     *   `problem` row, so `outdated` lists what `check`, `doctor` and `install --locked` fail
+     *   on. An asset that also has a version row is listed once, with that row.
+     *
+     * @returns Array of {@link OutdatedEntry} objects.
+     */
+    outdated(): Promise<OutdatedEntry[]>;
+    /**
+     * The `#pin` of every publisher-qualified `skaile.yaml` dependency, keyed `kind:publisher/name`
+     * (no scope sigil). `update` honours it, so `outdated` must not list a move it keeps.
+     */
+    protected declaredPinsByIdentity(): Map<string, string>;
+    /**
+     * List a locked asset whose `skaile.yaml` ref carries a `#version` pin while a source, a
+     * library or a store holds a newer one: `locked 0.7.0 -> 0.9.0 (pinned)`. The pin is the
+     * user's choice, so the row only informs (`pinned`): `update` leaves it, `outdated` does not
+     * fail on it (OQ13, p1291). An asset already listed keeps its own row.
+     */
+    protected addPinnedRows(lock: LockFile, rows: OutdatedEntry[]): Promise<void>;
+    /**
+     * Ask the stores about every locked asset whose lock entry says `origin: store`, and record
+     * those no store could be asked about (the URL did not answer, or the client is air-gapped)
+     * for {@link takeStoreNotChecked}. `outdated` runs it, and so do `check` and `doctor`, which
+     * otherwise never ask a store: without it a dead store reads as "everything is fine".
+     * A store that answers, and a client that skips the store on purpose
+     * (`catalogUrl: ''`, `--no-catalog`), record nothing. A ref already recorded is not asked again.
+     */
+    probeStoreOrigins(): Promise<void>;
+    /**
+     * List a source asset locked under a `0.0.0-sha.<commit>` key whose file now declares a
+     * version: the next `install` or `update` re-keys it (`replaced 0.0.0-sha.7de3555 → 0.2.0`),
+     * so `outdated` lists it as `re-key (…)` instead of saying everything is up to date (p914).
+     * An asset already listed (behind its remote) gets the target on that row.
+     */
+    protected addRekeyRows(lock: LockFile, rows: OutdatedEntry[]): Promise<void>;
+    /**
+     * List a locked library asset that `update` would move to another library (a default-library
+     * switch, a library that now holds a newer version) as `library → movesTo`, so `outdated`
+     * does not say "up to date" and `update` then re-locks it announced only after the fact.
+     * The resolution is the one `update` runs ({@link lockedPreference}); an asset already listed
+     * with a version row gets the target library on that row.
+     */
+    protected addLibraryMoves(libraryAssets: Array<[string, LockEntry]>, rows: OutdatedEntry[]): Promise<void>;
+    /**
+     * Add one `problem` row per {@link AssetManager.projectState} gap whose asset is not
+     * listed yet, so `outdated` lists the same assets `check`, `doctor` and `install --locked`
+     * fail on. An asset that is behind its source and also broken is listed once, with its
+     * version row.
+     */
+    protected addLockGapRows(rows: OutdatedEntry[]): Promise<OutdatedEntry[]>;
+    /**
+     * The deploy entry of a library-origin asset from the library its lock entry records,
+     * at the locked version when that library still holds it (else its newest). Other
+     * libraries holding the same ref are not consulted: the lock already chose.
+     *
+     * @param want - Kind, name and optional publisher of the asset.
+     * @returns `null` when the lock has no library-origin entry for it, or the recorded
+     *   library is gone or no longer holds it (callers fall back to a general lookup).
+     */
+    protected lockedLibraryEntry(want: AssetRef): Promise<DeployableEntry | null>;
+    /**
+     * The deploy entry of a source- or store-origin asset, carrying the file set its lock entry
+     * lists (so a missing or edited helper shows in `diff`, not only the manifest). A source asset
+     * reads from its clone; a store asset from the bytes `add`/`install` staged in the project
+     * store cache. `null` when the lock has no such entry or its bytes are not on disk.
+     *
+     * @param want - Kind, name and optional publisher of the asset.
+     */
+    protected lockedSourceEntry(want: AssetRef): DeployableEntry | null;
+    /** Whether the lock holds `want` as a store asset (`origin: store`, no library). */
+    protected isStorePinnedRef(want: AssetRef): boolean;
+}
+//# sourceMappingURL=outdated.d.ts.map

package/dist/asset-manager/src/read/outdated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outdated.d.ts","sourceRoot":"","sources":["../../../../asset-manager/src/read/outdated.ts"],"names":[],"mappings":"AAGA,OAAO,EAWL,KAAK,QAAQ,EAEb,KAAK,SAAS,EACd,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAK5E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAyEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,6FAA6F;AAC7F,8BAAsB,cAAe,SAAQ,WAAW;IACtD;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAgP1C;;;OAGG;IACH,SAAS,CAAC,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAevD;;;;;OAKG;cACa,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiEnF;;;;;;;OAOG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCxC;;;;;OAKG;cACa,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0ClF;;;;;;OAMG;cACa,eAAe,CAC7B,aAAa,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EACzC,IAAI,EAAE,aAAa,EAAE,GACpB,OAAO,CAAC,IAAI,CAAC;IAwDhB;;;;;OAKG;cACa,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoB/E;;;;;;;;OAQG;cACa,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IA0BnF;;;;;;;OAOG;IACH,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,IAAI;IAwBnE,oFAAoF;IACpF,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;CAYpD"}