@agentxm/workspace-configuration 0.28.12 → 0.28.13

package/dist/src/setup/setup-workspace.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Setting up an AXM workspace: deciding what a setup request would do,
+ * initializing the workspace under one transaction, and reporting exactly
+ * which files the workspace now occupies.
+ *
+ * Two rules decide the shape of this use case. An unattended apply happens
+ * only when the request said so completely — approval, scope, and at least
+ * one agent — because a workspace initialized from guessed defaults is a
+ * workspace nobody chose. And initialization is one transaction: a run that
+ * cannot finish leaves no half-initialized workspace behind.
+ *
+ * The report is the same document whether the request was previewed or
+ * applied, so a preview can be trusted as a description of the apply. It
+ * names the files the workspace occupies rather than the calls that wrote
+ * them, which is why the enumeration lives here beside the code that writes
+ * them rather than in whichever adapter happens to be rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import type { AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import { isGitManaged } from "@agentxm/extension-sources";
+import { CodingAgentRepository, type CodingAgentRepositoryService } from "@agentxm/workspace-projection";
+import { scanAllSubagentFiles, type LocatedWorkspace, type Settings } from "@agentxm/workspace-state";
+import { type WorkspaceRestorationIncomplete, type WorkspaceTransactionFailure } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed } from "../errors.js";
+import { WorkspaceInitializationInteraction } from "./initialization-interaction.js";
+import { bootstrapWorkspace, type SetupAgentCandidate } from "./initialization.js";
+/** Every failure a setup run can settle into. */
+export type SetupWorkspaceFailure = Effect.Error<ReturnType<typeof bootstrapWorkspace>> | WorkspaceTransactionFailure | WorkspaceRestorationIncomplete;
+declare const SetupArtifactTargetSchema: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly change: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+    readonly agentIds: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+export type SetupArtifactTarget = typeof SetupArtifactTargetSchema.Type;
+declare const SetupPlanStepSchema: Schema.Struct<{
+    readonly label: Schema.String;
+    readonly status: Schema.Literals<readonly ["ready", "warning", "error", "applied", "unchanged", "failed", "blocked"]>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly artifact: Schema.optional<Schema.Struct<{
+        readonly path: Schema.optional<Schema.String>;
+        readonly scope: Schema.Literals<readonly ["project", "user"]>;
+        readonly agents: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly version: Schema.optional<Schema.String>;
+        readonly change: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+        readonly previousVersion: Schema.optional<Schema.String>;
+        readonly fileCount: Schema.optional<Schema.Number>;
+        readonly targets: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+            readonly change: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+            readonly agentIds: Schema.optional<Schema.$Array<Schema.String>>;
+        }>>>;
+    }>>;
+}>;
+export type SetupPlanStep = typeof SetupPlanStepSchema.Type;
+/**
+ * How a preview chose the answers an interactive setup would have asked for.
+ */
+declare const SetupPreviewDefaultsSchema: Schema.Struct<{
+    readonly agents: Schema.Literals<readonly ["explicit", "detected", "suggested"]>;
+    readonly instructions: Schema.optional<Schema.Struct<{
+        readonly enabled: Schema.Boolean;
+        readonly fileName: Schema.String;
+    }>>;
+}>;
+type SetupPreviewDefaults = typeof SetupPreviewDefaultsSchema.Type;
+export declare const SetupOutcomeSchema: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["previewed", "cancelled", "applied", "no-op", "failed"]>;
+    readonly planName: Schema.String;
+    readonly planDescription: Schema.optional<Schema.String>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly totalSteps: Schema.Number;
+    readonly readyCount: Schema.Number;
+    readonly warningCount: Schema.Number;
+    readonly errorCount: Schema.Number;
+    readonly appliedCount: Schema.Number;
+    readonly failedCount: Schema.Number;
+    readonly blockedCount: Schema.Number;
+    readonly steps: Schema.$Array<Schema.Struct<{
+        readonly label: Schema.String;
+        readonly status: Schema.Literals<readonly ["ready", "warning", "error", "applied", "unchanged", "failed", "blocked"]>;
+        readonly message: Schema.optional<Schema.String>;
+        readonly artifact: Schema.optional<Schema.Struct<{
+            readonly path: Schema.optional<Schema.String>;
+            readonly scope: Schema.Literals<readonly ["project", "user"]>;
+            readonly agents: Schema.optional<Schema.$Array<Schema.String>>;
+            readonly version: Schema.optional<Schema.String>;
+            readonly change: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+            readonly previousVersion: Schema.optional<Schema.String>;
+            readonly fileCount: Schema.optional<Schema.Number>;
+            readonly targets: Schema.optional<Schema.$Array<Schema.Struct<{
+                readonly path: Schema.String;
+                readonly change: Schema.Literals<readonly ["created", "updated", "unchanged", "removed"]>;
+                readonly agentIds: Schema.optional<Schema.$Array<Schema.String>>;
+            }>>>;
+        }>>;
+    }>>;
+    readonly reason: Schema.optional<Schema.Literal<"approval-required">>;
+    readonly errorCode: Schema.optional<Schema.Literal<"usage">>;
+    readonly status: Schema.Literals<readonly ["initialized", "already-initialized", "preview", "cancelled", "approval-required"]>;
+    readonly changed: Schema.Boolean;
+    readonly defaultSkillInstalled: Schema.Boolean;
+    readonly scope: Schema.String;
+    readonly agents: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+    }>>;
+    readonly agentCandidates: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+        readonly projectDetected: Schema.Boolean;
+        readonly userDetected: Schema.Boolean;
+        readonly state: Schema.Literals<readonly ["selected", "suggested", "available", "retired"]>;
+        readonly selectionReason: Schema.optional<Schema.Literals<readonly ["explicit", "project-detected", "user-detected", "catalog-suggestion"]>>;
+    }>>>;
+    readonly scopeSupport: Schema.$Array<Schema.Struct<{
+        readonly type: Schema.Literals<readonly ("knowledge" | "skill" | "mcp-server" | "subagent" | "rule" | "hook" | "pack")[]>;
+        readonly label: Schema.String;
+        readonly placement: Schema.Literals<readonly ["per-agent", "workspace", "container"]>;
+        readonly outcomes: Schema.$Array<Schema.Struct<{
+            readonly target: Schema.Literals<readonly ["workspace", "container", "agent", "agent-set"]>;
+            readonly agentId: Schema.optional<Schema.String>;
+            readonly agentName: Schema.optional<Schema.String>;
+            readonly status: Schema.Literals<readonly ["supported", "project-only", "unsupported", "refused"]>;
+            readonly reasonCode: Schema.Literals<readonly ["supported", "no-configured-agents", "unknown-agent", "native-capability-unavailable", "axm-capability-unavailable", "project-only", "scope-not-modeled"]>;
+            readonly reason: Schema.String;
+        }>>;
+    }>>;
+    readonly settingsPath: Schema.String;
+    readonly instructions: Schema.optional<Schema.Struct<{
+        readonly enabled: Schema.Boolean;
+        readonly fileName: Schema.optional<Schema.String>;
+        readonly gitignoreAliases: Schema.optional<Schema.Boolean>;
+    }>>;
+    readonly telemetryEnabled: Schema.Boolean;
+    readonly subagentFiles: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly agentId: Schema.String;
+        readonly agentName: Schema.String;
+        readonly subagentDir: Schema.String;
+        readonly files: Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+        }>>;
+    }>>>;
+    readonly previewDefaults: Schema.optional<Schema.Struct<{
+        readonly agents: Schema.Literals<readonly ["explicit", "detected", "suggested"]>;
+        readonly instructions: Schema.optional<Schema.Struct<{
+            readonly enabled: Schema.Boolean;
+            readonly fileName: Schema.String;
+        }>>;
+    }>>;
+}>;
+export type SetupOutcome = typeof SetupOutcomeSchema.Type;
+export interface SetupWorkspaceRequest {
+    readonly scope: WorkspaceScope;
+    /** Whether the person named the scope, rather than taking the default. */
+    readonly scopeExplicit?: boolean;
+    readonly agents?: ReadonlyArray<string>;
+    /** Approve applying the documented candidate without prompting. */
+    readonly yes?: boolean;
+    readonly preview?: boolean;
+    /** No terminal is available to answer a prompt. */
+    readonly nonInteractive: boolean;
+    readonly projectRoot: AbsolutePath;
+    /** Whether telemetry is enabled for this invocation, reported in the outcome. */
+    readonly telemetryEnabled: boolean;
+}
+export interface SetupWorkspaceCandidate {
+    readonly _tag: "SetupWorkspace";
+    readonly request: SetupWorkspaceRequest;
+    /** Whether the authoritative settings file already exists. */
+    readonly settingsExist: boolean;
+    /** Where the settings file lives, whether or not it exists yet. */
+    readonly settingsPath: string;
+    readonly workspaceDir: string;
+}
+/**
+ * An unattended apply that did not say what it wanted. Reported rather than
+ * thrown so the adapter can render the same document shape it renders for
+ * every other setup answer.
+ */
+export interface SetupApprovalRequired {
+    readonly _tag: "ApprovalRequired";
+    readonly outcome: SetupOutcome;
+}
+/**
+ * Settle a setup request.
+ *
+ * An unattended apply into a workspace that has no settings yet must name
+ * every input it depends on. Anything less is refused before a file is
+ * touched, and the refusal names the preview that would show the candidate.
+ */
+export declare const prepareSetupWorkspace: (request: SetupWorkspaceRequest) => Effect.Effect<SetupWorkspaceCandidate | SetupApprovalRequired, WorkspaceConfigurationFailed, FileSystem.FileSystem | Path.Path>;
+/** What the initialization settled, before it is described as an outcome. */
+export interface SetupTransition {
+    readonly settings: Settings;
+    readonly location: LocatedWorkspace;
+    /** The run created the workspace. */
+    readonly initialized: boolean;
+    /** A preview: the run would create the workspace. */
+    readonly wouldInitialize: boolean;
+    /** The person declined the interactive setup. */
+    readonly cancelled: boolean;
+    readonly agentCandidates: ReadonlyArray<SetupAgentCandidate>;
+}
+/**
+ * Initialize the workspace, or resolve what initializing it would do.
+ *
+ * A first-time initialization runs inside a workspace transaction it opens
+ * itself: no workspace exists yet, so there is no located workspace to supply
+ * the transaction scope, and a run that fails halfway must leave the
+ * directory as it found it.
+ */
+export declare const previewOrApplySetupWorkspace: <BundledSkillError = never, BundledSkillRequirements = never>(candidate: SetupWorkspaceCandidate, options?: {
+    /**
+     * The bundled AXM skill installation, planned by the application through
+     * the lifecycle feature. It runs inside the initialization closure, so a
+     * skill that cannot be installed leaves no half-initialized workspace.
+     */
+    readonly bundledSkill?: Effect.Effect<void, BundledSkillError, BundledSkillRequirements>;
+}) => Effect.Effect<SetupTransition, SetupWorkspaceFailure | BundledSkillError, BundledSkillRequirements | FileSystem.FileSystem | Path.Path | WorkspaceInitializationInteraction | CodingAgentRepository>;
+/**
+ * How a preview chose its membership candidate: the explicit request when one
+ * was given, otherwise detection where it produced a strong signal, otherwise
+ * the catalog suggestion set.
+ */
+export declare const previewAgentDefault: (candidates: ReadonlyArray<SetupAgentCandidate>) => SetupPreviewDefaults["agents"];
+/** Every failure describing the settled setup can surface. */
+export type SetupReportFailure = Effect.Error<ReturnType<typeof scanAllSubagentFiles>> | Effect.Error<ReturnType<typeof isGitManaged>> | Effect.Error<ReturnType<Effect.Success<ReturnType<CodingAgentRepositoryService["get"]>>["resolveEffectiveSkillsDir"]>>;
+/** The bundled AXM skill installation the application settled, if it ran. */
+export interface BundledSkillReport {
+    readonly installed: boolean;
+    /** The skill package version the running executable ships. */
+    readonly version: string;
+}
+export interface SetupReportRequest {
+    readonly candidate: SetupWorkspaceCandidate;
+    readonly transition: SetupTransition;
+    readonly bundledSkill: BundledSkillReport;
+}
+/**
+ * Describe the settled setup: which files the workspace now occupies, which
+ * agents it configures, and what the same request would do again.
+ */
+export declare const reportSetupWorkspace: (request: SetupReportRequest) => Effect.Effect<SetupOutcome, SetupReportFailure, FileSystem.FileSystem | Path.Path | CodingAgentRepository>;
+/** The workspace setup use case. */
+export declare const SetupWorkspace: {
+    readonly prepare: (request: SetupWorkspaceRequest) => Effect.Effect<SetupWorkspaceCandidate | SetupApprovalRequired, WorkspaceConfigurationFailed, FileSystem.FileSystem | Path.Path>;
+    readonly previewOrApply: <BundledSkillError = never, BundledSkillRequirements = never>(candidate: SetupWorkspaceCandidate, options?: {
+        /**
+         * The bundled AXM skill installation, planned by the application through
+         * the lifecycle feature. It runs inside the initialization closure, so a
+         * skill that cannot be installed leaves no half-initialized workspace.
+         */
+        readonly bundledSkill?: Effect.Effect<void, BundledSkillError, BundledSkillRequirements>;
+    }) => Effect.Effect<SetupTransition, SetupWorkspaceFailure | BundledSkillError, BundledSkillRequirements | FileSystem.FileSystem | Path.Path | WorkspaceInitializationInteraction | CodingAgentRepository>;
+    readonly report: (request: SetupReportRequest) => Effect.Effect<SetupOutcome, SetupReportFailure, FileSystem.FileSystem | Path.Path | CodingAgentRepository>;
+};
+export {};
+//# sourceMappingURL=setup-workspace.d.ts.map