@agentxm/extension-materialization 0.29.2 → 0.30.1

package/dist/src/extensions/operations.d.ts

@@ -1,252 +0,0 @@
-/**
- * Shared extension closure recipes — install, materialize, uninstall, and the
- * authored-package transition.
- *
- * A recipe composes one manager's contract into one plan step. Requirements
- * stay explicit: the step declares the manager's `R` plus the transaction
- * scope its closure runs in, and the command boundary composes them once. The
- * facts a materialization observed travel from `materializeInstall` to the
- * settings and lockfile writes and to the step's artifact as values.
- *
- * @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 * as FileSystem from "effect/FileSystem";
-import type * as Path from "effect/Path";
-import type { ExtensionManager, MaterializationFacts } from "../manager-contract.js";
-import type { ExtensionManagerFailure } from "../errors.js";
-import type { StepFailure } from "@agentxm/workspace-operations";
-import type { JobStepArtifact, PlannedJobStep } from "@agentxm/workspace-operations";
-import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
-import type { PackageUrlParts } from "@agentxm/extension-model/unstable/packaging/package-url";
-import type { ExtensionTarget, ExtensionTargetFor } from "@agentxm/workspace-state";
-import type { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
-/**
- * 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 deprecatedAt: import("effect/DateTime").Utc;
-        readonly replacement: {
-            readonly status: "available";
-            readonly fqn: string;
-        } | {
-            readonly status: "unavailable";
-            readonly fqn?: string | undefined;
-        };
-        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: whether an installed
- * Pack still requires the target's package.
- */
-export interface UninstallRetentionPolicy<F = never, R = never> {
-    readonly isRequiredByInstalledPack: (args: {
-        readonly target: ExtensionTarget;
-    }) => Effect.Effect<boolean, CallerStepFailure<F>, R>;
-}
-/**
- * Failure channel for a recipe's typed inputs: the manager failures the recipe
- * itself can surface plus whatever failure family the calling feature supplies
- * through `F`. Nothing in this channel is `unknown`.
- */
-export type CallerStepFailure<F = never> = ExtensionManagerFailure | F;
-/**
- * The one conversion from a recipe's typed failure union into the serialized
- * plan-step vocabulary. Categories and wording are the boundary's, so machine
- * output does not depend on which side of the seam rendered the failure; the
- * recipe applies it once, at the edge of the step.
- */
-export interface StepFailureAdapter<F = never> {
-    readonly toStepFailure: (failure: CallerStepFailure<F>) => StepFailure;
-}
-/**
- * What every recipe adds on top of its manager's own requirements: the
- * transaction scope its closure opens, and the platform that scope reads and
- * writes through.
- */
-export type RecipeRequirements = WorkspaceTransactionScope | FileSystem.FileSystem | Path.Path;
-export interface InstallOperationArgs<TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never> extends StepFailureAdapter<F> {
-    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, CallerStepFailure<F>, R>;
-    /** Optional presenter metadata computed after materialization/settings writes. */
-    readonly buildArtifact?: (args: {
-        readonly installedBefore: boolean;
-        readonly materialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<JobStepArtifact, CallerStepFailure<F>, R>;
-    /** 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, TMaterialization extends MaterializationFacts, F = never, R = never> extends Omit<InstallOperationArgs<TRef, TMaterialization, F, R>, "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, CallerStepFailure<F>, R>;
-    readonly scaffold: Effect.Effect<unknown, CallerStepFailure<F>, R>;
-    readonly markAuthored: Effect.Effect<void, CallerStepFailure<F>, R>;
-    readonly message: string;
-    readonly label?: string;
-}
-export interface AuthoredExtensionOperationArgs<TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never> extends Omit<NewExtensionOperationArgs<TRef, TMaterialization, F, R>, "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, CallerStepFailure<F>, R>;
-    /** Type-specific projection path for authored packages with specialized installers. */
-    readonly materializeInstall?: (ref: TRef) => Effect.Effect<Option.Option<TMaterialization>, CallerStepFailure<F>, R>;
-    /**
-     * 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 keeps the manager's requirements and the transaction scope in its
- * `run` effect; the command boundary composes them once.
- */
-export declare const buildInstallOperation: <TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never>(manager: ExtensionManager<TRef, TMaterialization, R>, args: InstallOperationArgs<TRef, TMaterialization, F, R>) => PlannedJobStep<R | RecipeRequirements>;
-/**
- * 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, TMaterialization extends MaterializationFacts, F = never, R = never>(manager: ExtensionManager<TRef, TMaterialization, R>, args: AuthoredExtensionOperationArgs<TRef, TMaterialization, F, R>) => PlannedJobStep<R | RecipeRequirements>;
-/**
- * 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, TMaterialization extends MaterializationFacts, F = never, R = never>(manager: ExtensionManager<TRef, TMaterialization, R>, args: NewExtensionOperationArgs<TRef, TMaterialization, F, R>) => PlannedJobStep<R | RecipeRequirements>;
-export interface MaterializeOperationArgs<TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never> extends StepFailureAdapter<F> {
-    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;
-    /** Verify realized content inside the transaction before recording its resolution. */
-    readonly validateMaterialized?: (args: {
-        readonly materialization: TMaterialization;
-    }) => Effect.Effect<void, CallerStepFailure<F>, R>;
-    readonly buildArtifact?: (args: {
-        readonly materialization: TMaterialization;
-    }) => Effect.Effect<JobStepArtifact, CallerStepFailure<F>, R>;
-    readonly message?: string;
-}
-export declare const buildMaterializeOperation: <TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never>(manager: ExtensionManager<TRef, TMaterialization, R>, args: MaterializeOperationArgs<TRef, TMaterialization, F, R>) => PlannedJobStep<R | RecipeRequirements>;
-export interface UninstallOperationArgs<TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never> extends StepFailureAdapter<F> {
-    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;
-    /**
-     * Declares that the target's canonical package could not be read. Uninstall
-     * then removes the target's configuration and accepted resolution only, and
-     * preserves canonical content it cannot verify.
-     */
-    readonly retirement?: UnreadablePackageRetirement;
-    /** Presenter metadata computed from what the removal settled and withdrew. */
-    readonly buildArtifact?: (args: {
-        readonly settlement: UninstallSettlement;
-        readonly unmaterialization: Option.Option<TMaterialization>;
-    }) => Effect.Effect<JobStepArtifact, CallerStepFailure<F>, R>;
-}
-/** Why an uninstall target's canonical package could not be read. */
-export interface UnreadablePackageRetirement {
-    /** Workspace path where the unreadable manifest was looked for. */
-    readonly manifestPath: string;
-    readonly reason: "missing" | "invalid";
-}
-/** What an uninstall settled: the declaration, and the canonical content. */
-export interface UninstallSettlement {
-    readonly declaration: "removed" | "absent";
-    readonly canonical: "removed" | "absent" | "retained-by-pack" | "preserved-authored" | "preserved-unowned" | "preserved-unreadable";
-}
-/**
- * Build a PlannedJobStep for an uninstall operation.
- *
- * The step keeps the manager's requirements and the transaction scope in its
- * `run` effect; the command boundary composes them once.
- */
-export declare const buildUninstallOperation: <TRef extends ExtensionRef, TMaterialization extends MaterializationFacts, F = never, R = never>(manager: ExtensionManager<TRef, TMaterialization, R>, retentionPolicy: UninstallRetentionPolicy<F, R>, args: UninstallOperationArgs<TRef, TMaterialization, F, R>) => PlannedJobStep<R | RecipeRequirements>;
-//# sourceMappingURL=operations.d.ts.map