@agentxm/workspace-operations 0.28.4-bootstrap.0

package/dist/src/plan/plan-execution.js

@@ -0,0 +1,117 @@
+export const previewPlanExecution = { request: { mode: "preview" } };
+export const applyPlanExecution = (options) => ({
+    request: {
+        mode: "apply",
+        confirmableRiskApproval: options.approval,
+        acceptedPolicies: options.acceptedPolicies ?? new Set(),
+    },
+    approvalRecovery: options.recovery,
+    ...(options.configuredAgentOperations === undefined
+        ? {}
+        : { configuredAgentOperations: options.configuredAgentOperations }),
+});
+const emptyRecovery = { command: [], arguments: [] };
+export const preapprovedPlanExecution = applyPlanExecution({
+    approval: "preapproved",
+    recovery: emptyRecovery,
+});
+export const promptablePlanExecution = (recovery, acceptedPolicies) => applyPlanExecution({
+    approval: "prompt-if-interactive",
+    ...(acceptedPolicies === undefined ? {} : { acceptedPolicies }),
+    recovery,
+});
+export const publicRecoveryValue = (value) => ({
+    _tag: "Public",
+    value,
+});
+export const protectedRecoveryValue = () => ({ _tag: "Protected" });
+export const unclassifiedRecoveryValue = () => ({
+    _tag: "Unclassified",
+});
+export const credentialFreeLocatorRecoveryValue = (value) => {
+    try {
+        const parsed = new URL(value);
+        const hasSensitiveQuery = [...parsed.searchParams.keys()].some((key) => /(?:auth|key|password|secret|signature|token)/i.test(key));
+        return parsed.username.length === 0 && parsed.password.length === 0 && !hasSensitiveQuery
+            ? publicRecoveryValue(value)
+            : protectedRecoveryValue();
+    }
+    catch {
+        return publicRecoveryValue(value);
+    }
+};
+export const recoveryOption = (flag, value) => ({ _tag: "Option", flag, value });
+export const recoveryPositional = (value) => ({ _tag: "Positional", value });
+export const recoverySwitch = (flag, enabled) => ({
+    _tag: "Switch",
+    flag,
+    enabled,
+});
+const safeShellToken = /^[A-Za-z0-9_@%+=:,./^-]+$/;
+const quoteShellToken = (value) => value.length > 0 && safeShellToken.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+const isReplayable = (argument) => argument._tag === "Switch" ||
+    (argument.value._tag === "Public" && !/[()]/.test(argument.value.value));
+const renderValue = (value) => value._tag === "Public" && !/[()]/.test(value.value) ? quoteShellToken(value.value) : undefined;
+export const renderConfirmationRecoveryCommand = (recovery, options = {}) => {
+    if (recovery.command.length === 0 || !recovery.arguments.every(isReplayable))
+        return undefined;
+    const optionTokens = recovery.arguments.flatMap((argument) => {
+        switch (argument._tag) {
+            case "Switch":
+                return argument.enabled && argument.flag !== "--preview" && argument.flag !== "--yes"
+                    ? [argument.flag]
+                    : [];
+            case "Option": {
+                if (argument.flag === "--preview" || argument.flag === "--yes")
+                    return [];
+                const value = renderValue(argument.value);
+                return value === undefined ? [] : [argument.flag, value];
+            }
+            case "Positional":
+                return [];
+        }
+    });
+    const positionalValues = recovery.arguments.flatMap((argument) => {
+        if (argument._tag !== "Positional")
+            return [];
+        const value = renderValue(argument.value);
+        return value === undefined ? [] : [value];
+    });
+    const needsOptionTerminator = recovery.arguments.some((argument) => argument._tag === "Positional" &&
+        argument.value._tag === "Public" &&
+        argument.value.value.startsWith("-"));
+    const tokens = [
+        "axm",
+        ...recovery.command,
+        ...optionTokens,
+        ...(options.includeYes === false ? [] : ["--yes"]),
+        ...(options.additionalSwitches ?? []),
+        ...(needsOptionTerminator ? ["--"] : []),
+        ...positionalValues,
+    ];
+    return tokens.join(" ");
+};
+export const namedPolicyRecoverySuggestions = (recovery, requiredFlags) => {
+    const command = renderConfirmationRecoveryCommand(recovery, {
+        includeYes: false,
+        additionalSwitches: requiredFlags,
+    });
+    return command === undefined
+        ? [
+            {
+                description: `Rerun the original invocation with ${requiredFlags.join(" ")}; a retry command is unavailable because it contains protected or unclassified values.`,
+            },
+        ]
+        : [{ description: "Retry with the required policy override", cmd: command }];
+};
+export const confirmationRecoverySuggestions = (recovery) => {
+    const command = renderConfirmationRecoveryCommand(recovery);
+    return command === undefined
+        ? [
+            {
+                description: "Rerun the original invocation with --yes; a retry command is unavailable because it contains protected or unclassified values.",
+            },
+        ]
+        : [{ description: "Retry with explicit confirmation", cmd: command }];
+};
+//# sourceMappingURL=plan-execution.js.map

package/dist/src/plan/plan.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Plan types for workspace operations.
+ *
+ * Uses a readiness-based model where each step carries its own `run` effect
+ * (for ready/warn steps) or an error message (for error steps). A plan retains
+ * the environment required by its executable steps so callers can compose
+ * dependencies once at the command boundary.
+ *
+ * This module is the stable kernel home for the plan-pipeline primitives. It
+ * is imported by the CLI, the lint module, and any shared-kernel consumer that
+ * composes workspace Operations. The registry Worker SHALL NOT import it —
+ * publish never applies fixes, so the plan pipeline tree-shakes out of the
+ * Worker bundle.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { type StepFailure } from "./errors.js";
+import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { ArtifactChange } from "@agentxm/workspace-state";
+import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";
+import type { DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
+import type { ReleaseAgeOperationEvidence } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+export declare const PlanPolicyIds: readonly ["ignore-version-constraints", "accept-warnings"];
+export declare const PlanPolicyIdSchema: Schema.Literals<readonly ["ignore-version-constraints", "accept-warnings"]>;
+export type PlanPolicyId = typeof PlanPolicyIdSchema.Type;
+/**
+ * Bounded blocking reason classes. Prose never carries a blocking reason on
+ * its own; every blocked unit or operation names one of these classes.
+ */
+export declare const BlockingClassSchema: Schema.Literals<readonly ["approval-required", "override-required", "precondition-unmet", "dependency-failed", "dependency-cycle", "stale-candidate", "policy-excluded", "resource-conflict", "external-blocked", "operation-aborted"]>;
+export type BlockingClass = typeof BlockingClassSchema.Type;
+/** Typed blocking carried by a unit result that did not proceed. */
+export interface UnitBlocking {
+    readonly class: BlockingClass;
+    /** Machine-readable reference to the blocking unit or condition. */
+    readonly reference?: string;
+}
+export declare const PlanRiskConditionSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly level: Schema.Literal<"confirmable">;
+    readonly id: Schema.String;
+    readonly detail: Schema.String;
+}>, Schema.Struct<{
+    readonly level: Schema.Literal<"override-required">;
+    readonly id: Schema.String;
+    readonly policy: Schema.Literals<readonly ["ignore-version-constraints", "accept-warnings"]>;
+    readonly requiredFlag: Schema.String;
+    readonly detail: Schema.String;
+}>, Schema.Struct<{
+    readonly level: Schema.Literal<"blocked">;
+    readonly id: Schema.String;
+    readonly detail: Schema.String;
+    readonly errorCode: Schema.Literals<readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"]>;
+}>]>;
+export type PlanRiskCondition = typeof PlanRiskConditionSchema.Type;
+/**
+ * Generic operation type used by all extension operation handlers.
+ * Each operation is identified by a string name and carries typed args.
+ */
+export interface Operation<TName extends string, TArgs> {
+    readonly name: TName;
+    readonly args: TArgs;
+}
+export declare const ArtifactMechanismSchema: Schema.Literals<readonly ["symlink", "copy"]>;
+export type ArtifactMechanism = typeof ArtifactMechanismSchema.Type;
+export interface JobStepArtifact {
+    readonly path: string;
+    readonly scope: "project" | "user";
+    readonly agents?: ReadonlyArray<string>;
+    readonly version?: string;
+    readonly change: ArtifactChange;
+    readonly mechanism?: ArtifactMechanism;
+    readonly previousVersion?: string;
+    readonly fileCount?: number;
+    readonly targets?: ReadonlyArray<JobStepArtifactTarget>;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly source?: JobStepArtifactSource;
+    readonly managedRegions?: ReadonlyArray<JobStepManagedRegion>;
+    /** Registry lifecycle evidence captured when the candidate was resolved. */
+    readonly registryLifecycle?: {
+        readonly deprecation: DeprecationView;
+    };
+}
+export interface JobStepManagedRegion {
+    readonly unitId: string;
+    readonly path: string;
+    readonly owner: string;
+}
+export interface JobStepArtifactTarget {
+    readonly path: string;
+    readonly change: ArtifactChange;
+    readonly agentIds?: ReadonlyArray<string>;
+}
+export interface JobStepArtifactSource {
+    readonly type: string;
+    readonly origin: string;
+    readonly ref?: string;
+    readonly directory?: string;
+    readonly gitTreeHash?: string;
+}
+export interface RegistryLifecycleEvidence {
+    readonly deprecation: DeprecationView;
+}
+export type JobStepResult<Output = never> = {
+    readonly result: "success";
+    readonly message: string;
+    /** `skipped`: deliberately not attempted per policy; `unchanged`: evaluated, nothing to do. */
+    readonly disposition?: "skipped" | "unchanged";
+    readonly warnings?: ReadonlyArray<string>;
+    readonly links?: {
+        readonly html: string;
+    };
+    readonly artifact?: JobStepArtifact;
+    readonly output?: Output;
+} | {
+    readonly result: "error";
+    readonly message: string;
+    readonly error: StepFailure;
+    /** Present when the unit was prevented rather than failing on its own. */
+    readonly blocking?: UnitBlocking;
+};
+export interface ReadyJobStep<Requirements = never, Output = never> {
+    readonly key?: string;
+    readonly dependsOn?: ReadonlyArray<string>;
+    readonly readiness: "ready";
+    readonly label: string;
+    readonly message?: string;
+    readonly artifact?: JobStepArtifact;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly registryLifecycle?: RegistryLifecycleEvidence;
+    readonly run: Effect.Effect<JobStepResult<Output>, StepFailure, Requirements>;
+}
+export interface WarnJobStep<Requirements = never, Output = never> {
+    readonly key?: string;
+    readonly dependsOn?: ReadonlyArray<string>;
+    readonly readiness: "warn";
+    readonly warnMessage: string;
+    readonly label: string;
+    readonly artifact?: JobStepArtifact;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly registryLifecycle?: RegistryLifecycleEvidence;
+    readonly run: Effect.Effect<JobStepResult<Output>, StepFailure, Requirements>;
+}
+export interface ErrorJobStep {
+    readonly key?: string;
+    readonly dependsOn?: ReadonlyArray<string>;
+    readonly readiness: "error";
+    readonly errorMessage: string;
+    readonly label: string;
+    readonly artifact?: JobStepArtifact;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly registryLifecycle?: RegistryLifecycleEvidence;
+    /** Semantic blockers already represented in Plan.riskConditions. */
+    readonly blockingConditionIds?: ReadonlyArray<string>;
+}
+export type PlannedJobStep<Requirements = never, Output = never> = ReadyJobStep<Requirements, Output> | WarnJobStep<Requirements, Output> | ErrorJobStep;
+export interface CompletedJobStep<Output = never> {
+    readonly key?: string;
+    readonly label: string;
+    readonly blockedBy?: ReadonlyArray<string>;
+    readonly registryLifecycle?: RegistryLifecycleEvidence;
+    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
+    readonly result: JobStepResult<Output>;
+}
+export type JobExecutionPolicy = "fail-fast" | "best-effort";
+export interface Job<Requirements = never, Output = never> {
+    readonly steps: ReadonlyArray<PlannedJobStep<Requirements, Output>>;
+    readonly concurrency: "unbounded" | number;
+    /**
+     * Defaults to ordered fail-fast execution. Use `best-effort` only when every
+     * sibling step is independent; a failure still blocks subsequent jobs.
+     */
+    readonly executionPolicy?: JobExecutionPolicy;
+}
+/**
+ * Typed render vocabulary a planner declares for its operation; replaces
+ * verb and subject inference from plan names.
+ */
+export interface OperationPresentation {
+    readonly verb: {
+        /** e.g. "update" */
+        readonly imperative: string;
+        /** e.g. "Updated" */
+        readonly past: string;
+        /** e.g. "Updating" */
+        readonly gerund: string;
+    };
+    readonly subject: {
+        readonly singular: string;
+        readonly plural: string;
+    };
+}
+/** Presentation for an operation on one extension type (or extensions generally). */
+export declare const operationPresentation: (verb: OperationPresentation["verb"], type?: ExtensionType) => OperationPresentation;
+/** Fallback vocabulary for planners that declare no presentation. */
+export declare const defaultOperationPresentation: OperationPresentation;
+export declare const presentationOf: (plan: {
+    readonly presentation?: OperationPresentation;
+}) => OperationPresentation;
+export declare const OperationPreconditionSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly label: Schema.String;
+    readonly status: Schema.Literals<readonly ["met", "unmet"]>;
+    readonly detail: Schema.optional<Schema.String>;
+    readonly blockedOn: Schema.optional<Schema.Literal<"human">>;
+    readonly command: Schema.optional<Schema.String>;
+}>;
+export type OperationPrecondition = typeof OperationPreconditionSchema.Type;
+export interface Plan<Requirements = never, Output = never> {
+    readonly _tag: "Plan";
+    readonly name: string;
+    readonly description: Option.Option<string>;
+    readonly jobs: ReadonlyArray<Job<Requirements, Output>>;
+    readonly releaseAge?: ReleaseAgeOperationEvidence;
+    readonly preconditions?: ReadonlyArray<OperationPrecondition>;
+    /** Typed render vocabulary for this operation's human output. */
+    readonly presentation?: OperationPresentation;
+    /** Semantic conditions evaluated by the shared execution-policy boundary. */
+    readonly riskConditions?: ReadonlyArray<PlanRiskCondition>;
+    /** Recovery specific to an operation that cannot currently be applied. */
+    readonly failureSuggestions?: ReadonlyArray<SuggestedAction>;
+    /** Persisted inputs outside workspace state that materially determine this plan. */
+    readonly materialPaths?: ReadonlyArray<string>;
+    /** Local plans roll back candidate-wide; remote effects report truthful partial outcomes. */
+    readonly executionCapabilities?: {
+        readonly rollback: "local-atomic" | "non-rollbackable";
+    };
+}
+export interface ExecutedJob<Output = never> {
+    readonly steps: ReadonlyArray<CompletedJobStep<Output>>;
+    readonly concurrency: "unbounded" | number;
+    readonly executionPolicy?: JobExecutionPolicy;
+}
+export interface ExecutedPlan<Output = never> {
+    readonly _tag: "ExecutedPlan";
+    readonly name: string;
+    readonly description: Option.Option<string>;
+    readonly jobs: ReadonlyArray<ExecutedJob<Output>>;
+    readonly releaseAge?: ReleaseAgeOperationEvidence;
+    readonly preconditions?: ReadonlyArray<OperationPrecondition>;
+    readonly riskConditions?: ReadonlyArray<PlanRiskCondition>;
+    readonly candidateId?: string;
+}
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/plan/plan.js

@@ -0,0 +1,95 @@
+/**
+ * Plan types for workspace operations.
+ *
+ * Uses a readiness-based model where each step carries its own `run` effect
+ * (for ready/warn steps) or an error message (for error steps). A plan retains
+ * the environment required by its executable steps so callers can compose
+ * dependencies once at the command boundary.
+ *
+ * This module is the stable kernel home for the plan-pipeline primitives. It
+ * is imported by the CLI, the lint module, and any shared-kernel consumer that
+ * composes workspace Operations. The registry Worker SHALL NOT import it —
+ * publish never applies fixes, so the plan pipeline tree-shakes out of the
+ * Worker bundle.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Schema from "effect/Schema";
+import { OperationErrorCategorySchema } from "./errors.js";
+import { EXTENSION_TYPE_TABLE, } from "@agentxm/extension-model/unstable/extensions/common";
+export const PlanPolicyIds = ["ignore-version-constraints", "accept-warnings"];
+export const PlanPolicyIdSchema = Schema.Literals(PlanPolicyIds);
+/**
+ * Bounded blocking reason classes. Prose never carries a blocking reason on
+ * its own; every blocked unit or operation names one of these classes.
+ */
+export const BlockingClassSchema = Schema.Literals([
+    "approval-required",
+    "override-required",
+    "precondition-unmet",
+    "dependency-failed",
+    "dependency-cycle",
+    "stale-candidate",
+    "policy-excluded",
+    "resource-conflict",
+    "external-blocked",
+    "operation-aborted",
+]).annotate({
+    identifier: "BlockingClass",
+    title: "Blocking Class",
+    description: "Bounded reason class for work that did not proceed.",
+});
+export const PlanRiskConditionSchema = Schema.Union([
+    Schema.Struct({
+        level: Schema.Literal("confirmable"),
+        id: Schema.String,
+        detail: Schema.String,
+    }),
+    Schema.Struct({
+        level: Schema.Literal("override-required"),
+        id: Schema.String,
+        policy: PlanPolicyIdSchema,
+        requiredFlag: Schema.String,
+        detail: Schema.String,
+    }),
+    Schema.Struct({
+        level: Schema.Literal("blocked"),
+        id: Schema.String,
+        detail: Schema.String,
+        errorCode: OperationErrorCategorySchema,
+    }),
+]);
+// -----------------------------------------------------------------------------
+// Step result types
+// -----------------------------------------------------------------------------
+export const ArtifactMechanismSchema = Schema.Literals(["symlink", "copy"]);
+/** Presentation for an operation on one extension type (or extensions generally). */
+export const operationPresentation = (verb, type) => ({
+    verb,
+    subject: type === undefined
+        ? { singular: "extension", plural: "extensions" }
+        : {
+            singular: EXTENSION_TYPE_TABLE[type].sentenceLabel,
+            plural: EXTENSION_TYPE_TABLE[type].pluralSentenceLabel,
+        },
+});
+/** Fallback vocabulary for planners that declare no presentation. */
+export const defaultOperationPresentation = {
+    verb: { imperative: "apply", past: "Applied", gerund: "Applying" },
+    subject: { singular: "change", plural: "changes" },
+};
+export const presentationOf = (plan) => plan.presentation ?? defaultOperationPresentation;
+export const OperationPreconditionSchema = Schema.Struct({
+    id: Schema.String,
+    label: Schema.String,
+    status: Schema.Literals(["met", "unmet"]),
+    detail: Schema.optional(Schema.String),
+    blockedOn: Schema.optional(Schema.Literal("human")),
+    command: Schema.optional(Schema.String),
+}).annotate({
+    identifier: "OperationPrecondition",
+    title: "Operation Precondition",
+    description: "A condition that must be satisfied before an operation can apply.",
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/plan/resolve-plan-interaction.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Plan-resolution interaction port.
+ *
+ * `previewOrApplyPlan` presents candidates, reports progress, and obtains the
+ * apply confirmation exclusively through this service. The CLI runtime
+ * provides the renderer- and prompt-backed implementation; wording, verbosity
+ * gating, and progress presentation belong to that implementation, never to
+ * the kernel.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as ServiceMap from "effect/Context";
+import type { PlanInteractionFailed } from "./errors.js";
+import type { ConfirmationRecovery } from "./plan-execution.js";
+import type { Plan } from "./plan.js";
+/**
+ * Outcome of the apply confirmation. `cancelled` is the typed successor of a
+ * caught prompt cancellation at the CLI implementation; the kernel treats it
+ * as declined today, but the distinction is preserved for resolutions.
+ */
+export type ApplyConfirmation = "approved" | "declined" | "cancelled";
+export interface ResolvePlanInteractionService {
+    /** Whether an interactive confirmation can be obtained. */
+    readonly isConfirmationAvailable: Effect.Effect<boolean>;
+    readonly confirmApplyChanges: (recovery: ConfirmationRecovery) => Effect.Effect<ApplyConfirmation, PlanInteractionFailed>;
+    /**
+     * Present the immutable candidate. The implementation owns the
+     * verbosity/quiet/mode gate and all wording; the kernel calls this
+     * unconditionally.
+     */
+    readonly presentPlan: (plan: Plan<unknown, unknown>, options: {
+        readonly mode: "preview" | "apply";
+    }) => Effect.Effect<void>;
+    /** Progress envelope for lockfile reconciliation. */
+    readonly withPlanningProgress: <A, E, R>(planName: string, run: () => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Progress envelope for apply. The implementation subscribes to the
+     * operation lifecycle stream itself (`plan/operation-events`) and maps unit
+     * and restoration events to progress updates.
+     */
+    readonly withApplyProgress: <A, E, R>(planName: string, run: () => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /** Transition-lock contention notice. */
+    readonly noteTransitionWait: (holder: Option.Option<{
+        readonly command: string;
+        readonly pid: number;
+    }>) => Effect.Effect<void>;
+}
+declare const ResolvePlanInteraction_base: ServiceMap.ServiceClass<ResolvePlanInteraction, "@agentxm/workspace-operations/plan/resolve-plan-interaction/ResolvePlanInteraction", ResolvePlanInteractionService>;
+export declare class ResolvePlanInteraction extends ResolvePlanInteraction_base {
+}
+export interface ResolvePlanInteractionTestState {
+    readonly confirmApplyChangesCalls: Array<ConfirmationRecovery>;
+    readonly presentPlanCalls: Array<{
+        readonly planName: string;
+        readonly mode: "preview" | "apply";
+    }>;
+    readonly planningProgress: Array<string>;
+    readonly applyProgress: Array<string>;
+    transitionWaits: number;
+}
+export declare const ResolvePlanInteractionTest: (overrides?: {
+    readonly isConfirmationAvailable?: boolean;
+    readonly confirmApplyChanges?: (recovery: ConfirmationRecovery) => Effect.Effect<ApplyConfirmation, PlanInteractionFailed>;
+    readonly presentPlan?: (plan: Plan<unknown, unknown>, options: {
+        readonly mode: "preview" | "apply";
+    }) => Effect.Effect<void>;
+    readonly noteTransitionWait?: (holder: Option.Option<{
+        readonly command: string;
+        readonly pid: number;
+    }>) => Effect.Effect<void>;
+}) => {
+    layer: Layer.Layer<ResolvePlanInteraction, never, never>;
+    state: ResolvePlanInteractionTestState;
+};
+export {};
+//# sourceMappingURL=resolve-plan-interaction.d.ts.map

package/dist/src/plan/resolve-plan-interaction.js

@@ -0,0 +1,52 @@
+/**
+ * Plan-resolution interaction port.
+ *
+ * `previewOrApplyPlan` presents candidates, reports progress, and obtains the
+ * apply confirmation exclusively through this service. The CLI runtime
+ * provides the renderer- and prompt-backed implementation; wording, verbosity
+ * gating, and progress presentation belong to that implementation, never to
+ * the kernel.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as ServiceMap from "effect/Context";
+export class ResolvePlanInteraction extends ServiceMap.Service()("@agentxm/workspace-operations/plan/resolve-plan-interaction/ResolvePlanInteraction") {
+}
+export const ResolvePlanInteractionTest = (overrides) => {
+    const state = {
+        confirmApplyChangesCalls: [],
+        presentPlanCalls: [],
+        planningProgress: [],
+        applyProgress: [],
+        transitionWaits: 0,
+    };
+    const layer = Layer.succeed(ResolvePlanInteraction, {
+        isConfirmationAvailable: Effect.succeed(overrides?.isConfirmationAvailable ?? false),
+        confirmApplyChanges: (recovery) => Effect.gen(function* () {
+            state.confirmApplyChangesCalls.push(recovery);
+            return yield* overrides?.confirmApplyChanges?.(recovery) ??
+                Effect.succeed("approved");
+        }),
+        presentPlan: (plan, options) => Effect.gen(function* () {
+            state.presentPlanCalls.push({ planName: plan.name, mode: options.mode });
+            yield* overrides?.presentPlan?.(plan, options) ?? Effect.void;
+        }),
+        withPlanningProgress: (planName, run) => Effect.suspend(() => {
+            state.planningProgress.push(planName);
+            return run();
+        }),
+        withApplyProgress: (planName, run) => Effect.suspend(() => {
+            state.applyProgress.push(planName);
+            return run();
+        }),
+        noteTransitionWait: (holder) => Effect.gen(function* () {
+            state.transitionWaits += 1;
+            yield* overrides?.noteTransitionWait?.(holder) ?? Effect.void;
+        }),
+    });
+    return { layer, state };
+};
+//# sourceMappingURL=resolve-plan-interaction.js.map

package/dist/src/plan/resolve-plan.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Plan preview/apply function.
+ *
+ * Orchestrates `augmentPlanWithReconciliation`, `scanPlanReadiness`,
+ * and `applyPlan` with the `ResolvePlanInteraction` port, and produces
+ * one `OperationResolution` at every termination path. Channels project the
+ * returned resolution; presentation and prompting live behind the port, and
+ * per-type outcome refinement behind the optional
+ * `ConfiguredAgentOutcomesProvider` port.
+ *
+ * This is a free function, not a method on WorkspaceMutationsService.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { ApprovalRecoveryMissing, StepFailure } from "./errors.js";
+import { type ExecutionCandidate } from "./execution-candidate.js";
+import type { Plan } from "./plan.js";
+import { type OperationResolution } from "./operation-resolution.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { ResolvePlanInteraction } from "./resolve-plan-interaction.js";
+import { type PlanExecution } from "./plan-execution.js";
+/**
+ * Preview or apply (display, confirm, and execute) a plan using the workspace read model.
+ *
+ * Steps:
+ * 1. Augment plan with lockfile reconciliation if needed
+ * 2. Scan for errors/warnings
+ * 3. Construct and display the exact candidate
+ * 4. Fail closed on blockers and missing named policies
+ * 5. Preview or approve confirmable semantic risk
+ * 6. Revalidate and apply the same candidate
+ *
+ * Every termination path resolves to one `OperationResolution`.
+ */
+export declare const previewOrApplyPlan: <Requirements, Output>(plan: Plan<Requirements, Output>, options: {
+    execution: PlanExecution;
+    beforeApply?: (candidate: ExecutionCandidate<Requirements, Output>) => Effect.Effect<void, StepFailure, Requirements>;
+}) => Effect.Effect<OperationResolution<Output>, import("./errors.js").CandidateFingerprintFailed | ApprovalRecoveryMissing | import("./errors.js").PlanInteractionFailed | import("@agentxm/workspace-state").WorkspaceTransitionAcquireFailure | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").WorkspaceSettingsReadFailure, Path.Path | FileSystem.FileSystem | ResolvePlanInteraction | WorkspaceMutations | Exclude<Requirements, import("effect/Scope").Scope>>;
+//# sourceMappingURL=resolve-plan.d.ts.map