@cairn-tool/cairn 2.0.0

package/dist/agent/install/index.d.ts

@@ -0,0 +1,211 @@
+import type { AgentBundle, AgentDiagnostic, AgentProfile, AgentTarget, Artifact } from "../types.js";
+import type { InstallLayout, InstallLocation } from "../targets/index.js";
+export declare const INSTALL_MANIFEST = ".cairn-install.json";
+/** The pre-rename manifest, still read so existing installs stay removable. */
+export declare const LEGACY_INSTALL_MANIFEST = ".claude-cli-install.json";
+/**
+ * The manifest file in `destination`, preferring the current name.
+ *
+ * Only the paths this module reads off *disk* go through here. Comparisons
+ * against `artifact.path` elsewhere in this file stay exact equality against
+ * `INSTALL_MANIFEST` on purpose: those artifacts come from a plan this run just
+ * built, which never emits the legacy name.
+ */
+export declare function installManifestIn(destination: string): string | undefined;
+export declare const INSTALL_CACHE = ".install";
+export declare const INSTALL_SCOPES: readonly ["user", "project"];
+export type InstallScope = (typeof INSTALL_SCOPES)[number];
+export type InstallMode = "copy" | "link";
+export interface InstallEntry {
+    name: string;
+    version: string;
+    target: AgentTarget;
+    profile: AgentProfile;
+    scope: InstallScope;
+    layout: InstallLayout;
+    mode: InstallMode;
+    destination: string;
+    registered: boolean;
+    files: number;
+}
+export interface InstallReport {
+    installs: InstallEntry[];
+}
+export interface InstallInventoryEntry {
+    path: string;
+    mode: string;
+    sha256: string;
+}
+export interface InstallRegistration {
+    file: string;
+    marketplaceKey: string;
+    /** The single plugin key a bundle install enables. */
+    pluginKey?: string;
+    /**
+     * Every plugin key a collection install enables. A collection registers one
+     * marketplace offering many plugins, so it has no single primary key.
+     */
+    pluginKeys?: string[];
+}
+/**
+ * The plugin keys a registration activates, whichever spelling recorded them.
+ * A manifest written before collections carries only `pluginKey`.
+ */
+export declare function registeredPluginKeys(registration: InstallRegistration): string[];
+export interface InstallManifest {
+    generator: {
+        name: string;
+        version: string;
+    };
+    /**
+     * What was installed here: a single bundle, or a collection of them. Absent
+     * means `"bundle"`, so every manifest written before collections still parses.
+     */
+    kind?: "bundle" | "collection";
+    /**
+     * The installed unit's identity — a bundle's, or a collection's. Uninstall,
+     * the occupied-destination check, and `agent installed` all key off this, so
+     * a collection reuses it rather than adding a parallel field they would have
+     * to learn about.
+     */
+    bundle: {
+        name: string;
+        version: string;
+    };
+    /** The plugins a collection install placed. Absent for a single bundle. */
+    collection?: {
+        plugins: Array<{
+            name: string;
+            version: string;
+        }>;
+    };
+    target: AgentTarget;
+    profile: AgentProfile;
+    scope: InstallScope;
+    layout: InstallLayout;
+    mode: InstallMode;
+    destination: string;
+    files: InstallInventoryEntry[];
+    materialized?: string;
+    registration?: InstallRegistration;
+}
+export interface InstallContext {
+    home?: string;
+    cwd?: string;
+}
+export interface ResolvedInstall {
+    location: InstallLocation;
+    locationRoot: string;
+    destination: string;
+}
+export interface InstallPlan {
+    /**
+     * The bundle a single-bundle install renders. Absent for a collection, which
+     * installs many; nothing reads it, so a collection is not made to invent one.
+     */
+    bundle?: AgentBundle;
+    target: AgentTarget;
+    profile: AgentProfile;
+    scope: InstallScope;
+    layout: InstallLayout;
+    mode: InstallMode;
+    destination: string;
+    artifacts: Artifact[];
+    manifest: InstallManifest;
+    diagnostics: AgentDiagnostic[];
+    register: boolean;
+    settings?: InstallRegistration;
+}
+export declare function resolveScope(value: string | undefined, fallback?: InstallScope): InstallScope;
+/**
+ * Expands a profile install root. `~` is the caller's home, `.` is `cwd`, and
+ * anything else is resolved against `cwd`.
+ */
+export declare function expandInstallRoot(root: string, context?: InstallContext): string;
+export declare function locationFor(target: AgentTarget, scope: InstallScope): InstallLocation | null;
+/**
+ * True when `relative` would land outside `root`. Lexical: a `..` segment or an
+ * absolute path is enough, matching the overlay boundary.
+ */
+export declare function pathEscapesRoot(root: string, relative: string): boolean;
+export declare function readInstallManifest(destination: string): InstallManifest | "missing" | "malformed";
+export declare function resolveInstallDestination(target: AgentTarget, scope: InstallScope, name: string, options?: {
+    into?: string;
+} & InstallContext): ResolvedInstall | AgentDiagnostic;
+export declare function installIsCurrent(plan: InstallPlan): boolean;
+/**
+ * Plans an install: renders and packages in memory, resolves the destination
+ * from profile data, and records AB8xx findings. Nothing is written.
+ */
+export declare function planInstall(bundle: AgentBundle, target: AgentTarget, options: {
+    scope?: string;
+    into?: string;
+    profile?: string;
+    link?: boolean;
+    register?: boolean;
+    force?: boolean;
+} & InstallContext): InstallPlan;
+/** What a collection places at one destination. */
+export interface CollectionInstall {
+    /** The collection's name; also the marketplace key hosts index by. */
+    name: string;
+    version: string;
+    target: AgentTarget;
+    /**
+     * Destination-relative artifacts: the aggregated catalog plus one directory
+     * per plugin. Already stripped of the `<target>/` prefix the build uses.
+     */
+    artifacts: Artifact[];
+    plugins: Array<{
+        name: string;
+        version: string;
+    }>;
+}
+/**
+ * Plans an install of a whole collection into one host marketplace.
+ *
+ * The difference from {@link planInstall} is entirely in the registration:
+ * a bundle install keys `extraKnownMarketplaces` on the bundle name and enables
+ * one plugin, so installing five bundles yields five marketplaces. A collection
+ * keys it on the collection name once and enables every plugin under it, which
+ * is the shape a host actually offers to a user.
+ *
+ * Everything else — the occupied check, the manifest, the inventory, uninstall —
+ * is shared, because the manifest's `bundle` field records the installed unit's
+ * identity and a collection simply puts its own there.
+ */
+export declare function planCollectionInstall(collection: CollectionInstall, options?: {
+    scope?: InstallScope;
+    into?: string;
+    link?: boolean;
+    force?: boolean;
+    register?: boolean;
+    /** Where a `--link` install materializes; required when `link` is set. */
+    materializeInto?: string;
+} & InstallContext): InstallPlan;
+/** Writes a planned install. Caller must have already decided the run is not blocked. */
+export declare function commitInstall(plan: InstallPlan): void;
+export declare function planToEntry(plan: InstallPlan): InstallEntry;
+export interface UninstallPlan {
+    name: string;
+    target: AgentTarget;
+    destination: string;
+    manifest: InstallManifest | null;
+    diagnostics: AgentDiagnostic[];
+    missing: boolean;
+}
+/**
+ * Locates a named install. `--scope` is optional: when omitted, both scopes
+ * are searched and two matches is an error rather than a guess.
+ */
+export declare function planUninstall(name: string, target: AgentTarget, options: {
+    scope?: string;
+    into?: string;
+} & InstallContext): UninstallPlan;
+export declare function missingInstallDiagnostic(name: string, target: AgentTarget, destination: string): AgentDiagnostic;
+export declare function commitUninstall(plan: UninstallPlan): void;
+/** Lists installs found at the roots the target profiles declare. */
+export declare function listInstalled(targets: AgentTarget[], options?: {
+    scope?: string;
+    into?: string;
+} & InstallContext): InstallEntry[];