/**
 * Shared extension operation workflows — install and uninstall operation builders.
 *
 * @experimental This API is unstable and may change without notice.
 * @packageDocumentation
 */
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import { type AppError } from "../app-error/index.js";
import type { JobStepArtifact, PlannedJobStep } from "../plan/plan.js";
import type { ExtensionRef } from "./refs.js";
import type { PackageUrlParts } from "../packaging/package-url.js";
import type { ExtensionManager, ExtensionTarget, ExtensionTargetFor } from "../workspace/service-interface.js";
/**
 * Derive an ExtensionTarget from an ExtensionRef.
 *
 * Pack targets include owner; leaf-extension targets are name-only.
 */
export declare const targetFromRef: (ref: ExtensionRef) => ExtensionTarget;
export declare const extensionRefLifecycleWarnings: (ref: ExtensionRef) => ReadonlyArray<string>;
export declare const extensionRefRegistryLifecycle: (ref: ExtensionRef) => {
    deprecation: {
        readonly message: string;
        readonly deprecatedAt: import("effect/DateTime").Utc;
        readonly replacement?: {
            readonly status: "available";
            readonly fqn: string;
        } | {
            readonly status: "unavailable";
            readonly fqn?: string | undefined;
        } | undefined;
    } | {
        readonly replacement: {
            readonly status: "available";
            readonly fqn: string;
        } | {
            readonly status: "unavailable";
            readonly fqn?: string | undefined;
        };
        readonly deprecatedAt: import("effect/DateTime").Utc;
        readonly message?: string | undefined;
    };
} | undefined;
/**
 * Produce a display label from an ExtensionTarget.
 *
 * Pack targets render as `owner/name`; others render as `name`.
 */
export declare const toLabel: (target: ExtensionTarget) => string;
/**
 * Produce a stable step identity key from an ExtensionTarget.
 *
 * This is internal plan identity, not display text.
 */
export declare const toStepKey: (target: ExtensionTarget) => string;
/**
 * Format a single PackageUrlParts as a compact display string.
 *
 * Examples: `pkg:npm/react`, `pkg:npm/@angular/core@18.0.0`
 */
export declare const formatPackageUrlParts: (parts: PackageUrlParts) => string;
/**
 * Build a display label with optional packages suffix.
 *
 * When packages is non-empty, appends them parenthesized:
 *   `code-review (pkg:npm/react, pkg:npm/typescript)`
 */
export declare const toLabelWithCompanions: (target: ExtensionTarget, packages: ReadonlyArray<PackageUrlParts>) => string;
/**
 * Cross-cutting uninstall dependency-retention policy.
 *
 * Captured from workspace service at plan-build time and passed to
 * runUninstallOperation. All methods have `R = never`.
 */
export interface UninstallRetentionPolicy {
    readonly isRequiredByInstalledPack: (args: {
        readonly target: ExtensionTarget;
    }) => Effect.Effect<boolean, AppError, never>;
}
export interface InstallOperationArgs<TRef extends ExtensionRef> {
    readonly ref: TRef;
    readonly versionRange: Option.Option<string>;
    /** When true, re-materialize unconditionally (repair path for forced reinstalls). */
    readonly force?: boolean;
    /** When true, skip writing to settings (e.g. pack dependency installs). */
    readonly skipSettings?: boolean;
    /**
     * When true, skip the trailing shared-projection reconcile (e.g. pack
     * dependency steps, whose closure runs one projection write at the end).
     */
    readonly skipProjections?: boolean;
    /**
     * Defer the manager-wide observable check to an enclosing semantic closure.
     * Pack member transitions use this while other configured Packs are still
     * incomplete; the enclosing Pack graph validates every accepted canonical
     * package and its scoped desired-state postcondition before committing.
     */
    readonly deferObservableValidation?: boolean;
    /** Optional pre-install state probe for artifact change labels. */
    readonly installedBefore?: Effect.Effect<boolean, AppError, never>;
    /** Optional presenter metadata computed after materialization/settings writes. */
    readonly buildArtifact?: (args: {
        readonly installedBefore: boolean;
    }) => Effect.Effect<JobStepArtifact, AppError, never>;
    /** Optional outcome message for type-specific install presenters. */
    readonly message?: string;
    /** Explicit destructive source-authority transition used only by demotion. */
    readonly allowWorkspaceReplacement?: boolean;
}
export interface NewExtensionOperationArgs<TRef extends ExtensionRef> extends Omit<InstallOperationArgs<TRef>, "force" | "allowWorkspaceReplacement"> {
    readonly target: ExtensionTargetFor<TRef>;
    /** Read-only artifact forecast rendered by preview before any mutation occurs. */
    readonly plannedArtifact?: JobStepArtifact;
    /** Collision checks repeated under the workspace transaction lock before the first write. */
    readonly preflight?: Effect.Effect<void, AppError, never>;
    readonly scaffold: Effect.Effect<unknown, AppError, never>;
    readonly markAuthored: Effect.Effect<void, AppError, never>;
    readonly message: string;
    readonly label?: string;
}
export interface AuthoredExtensionOperationArgs<TRef extends ExtensionRef> extends Omit<NewExtensionOperationArgs<TRef>, "ref"> {
    /** Canonical workspace package path protected by the transaction snapshot. */
    readonly location: string;
    /** Additional files that the authored transition may update transactionally. */
    readonly transactionTargets?: ReadonlyArray<string>;
    /** Whether the new authored extension should remain materialized after creation. */
    readonly enabled?: boolean;
    /** Commit the caller's final desired-state shape after canonical resolution. */
    readonly finalizeAuthored?: Effect.Effect<void, AppError, never>;
    /** Type-specific projection path for authored packages with specialized installers. */
    readonly materializeInstall?: (ref: TRef) => Effect.Effect<void, AppError, never>;
    /**
     * Project and then deactivate a disabled target when adopting a native
     * configuration requires the projection writer to perform the transition.
     */
    readonly materializeWhenDisabled?: boolean;
    /**
     * Skip the global materializability preflight when replacing an explicitly
     * selected native/configured source with a new workspace-authored package.
     */
    readonly allowConfiguredSourceTransition?: boolean;
}
/**
 * Build a PlannedJobStep for an install operation.
 *
 * The step captures the manager and args in its `run` closure so execution
 * requires no runtime service resolution (`R = never`).
 */
export declare const buildInstallOperation: <TRef extends ExtensionRef>(manager: ExtensionManager<TRef>, args: InstallOperationArgs<TRef>) => PlannedJobStep;
/**
 * Build a PlannedJobStep for `new` commands.
 *
 * A read-only preflight runs first. The transaction then snapshots the source
 * path, scaffolds it, seeds desired state, resolves the canonical package, and
 * materializes projections before validating the authored postcondition.
 */
export declare const buildAuthoredExtensionStep: <TRef extends ExtensionRef>(manager: ExtensionManager<TRef>, args: AuthoredExtensionOperationArgs<TRef>) => PlannedJobStep;
/**
 * Build a PlannedJobStep for existing `new` commands.
 *
 * New commands remain enabled by default while sharing the authored-package
 * transaction used by fork and native import.
 */
export declare const buildNewExtensionStep: <TRef extends ExtensionRef>(manager: ExtensionManager<TRef>, args: NewExtensionOperationArgs<TRef>) => PlannedJobStep;
export interface MaterializeOperationArgs<TRef extends ExtensionRef> {
    readonly ref: TRef;
    /** Optional transition-rich label used by reconciliation previews. */
    readonly label?: string;
    /** Explicitly permit a workspace-authored relocation during reconciliation. */
    readonly allowWorkspaceSourceTransition?: boolean;
    /** Reacquire canonical content before projecting it. */
    readonly force?: boolean;
    readonly buildArtifact?: () => Effect.Effect<JobStepArtifact, AppError, never>;
    readonly message?: string;
}
export declare const buildMaterializeOperation: <TRef extends ExtensionRef>(manager: ExtensionManager<TRef>, args: MaterializeOperationArgs<TRef>) => PlannedJobStep;
export interface UninstallOperationArgs<TRef extends ExtensionRef> {
    readonly target: ExtensionTargetFor<TRef>;
    /**
     * When true, skip the trailing shared-projection reconcile (e.g. pack
     * dependency steps, whose closure runs one projection write at the end).
     */
    readonly skipProjections?: boolean;
}
/**
 * Build a PlannedJobStep for an uninstall operation.
 *
 * The step captures the manager, retention policy, and target in its `run`
 * closure so execution requires no runtime service resolution (`R = never`).
 */
export declare const buildUninstallOperation: <TRef extends ExtensionRef>(manager: ExtensionManager<TRef>, retentionPolicy: UninstallRetentionPolicy, args: UninstallOperationArgs<TRef>) => PlannedJobStep;
//# sourceMappingURL=operations.d.ts.map