@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/configured-agent-outcomes-provider.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Configured-agent-outcomes provider port.
+ *
+ * The plan pipeline reports per-agent lifecycle outcomes against the generic
+ * `configuredAgentLifecycleOutcomes` derivation. A per-type manager may know
+ * the effective outcomes more precisely (today the hook manager reads agent
+ * hook surfaces directly), so the state layer declares only this optional
+ * port keyed by extension type; the application composes the implementations.
+ * An absent provider — or an absent entry for a type — degrades to the
+ * generic derivation, matching the plan pipeline's existing fallback.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/Context";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+import type { ConfiguredAgentOutcome } from "./configured-agent-outcome.js";
+/**
+ * Failure category vocabulary for a provider failure. The literals are the
+ * same strings as the plan pipeline's `OperationErrorCategory` and the CLI's
+ * `AppErrorCode`; the conversion sites in those packages assert the parity at
+ * compile time by assigning this type to theirs.
+ */
+export type ConfiguredAgentOutcomesFailureCategory = "issues" | "usage" | "not_found" | "auth" | "forbidden" | "conflict" | "rate_limit" | "network" | "validation" | "internal" | "unavailable" | "quota" | "auth_required" | "auth_expired" | "auth_denied" | "timeout";
+declare const ConfiguredAgentOutcomesUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ConfiguredAgentOutcomesUnavailable";
+} & Readonly<A>;
+/**
+ * A provider could not produce its outcomes. The implementation owns the
+ * category and wording at construction; consumers transport the failure into
+ * their own reporting envelope without re-rendering it.
+ */
+export declare class ConfiguredAgentOutcomesUnavailable extends ConfiguredAgentOutcomesUnavailable_base<{
+    readonly category: ConfiguredAgentOutcomesFailureCategory;
+    readonly detail: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+/** Effective outcomes for one extension type in the projected or current state. */
+export type ConfiguredAgentOutcomesForState = (state: "projected" | "current") => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ConfiguredAgentOutcomesUnavailable>;
+export interface ConfiguredAgentOutcomesProviderService {
+    readonly byExtensionType: Partial<Record<ExtensionType, ConfiguredAgentOutcomesForState>>;
+}
+declare const ConfiguredAgentOutcomesProvider_base: ServiceMap.ServiceClass<ConfiguredAgentOutcomesProvider, "@agentxm/workspace-state/workspace/configured-agent-outcomes-provider/ConfiguredAgentOutcomesProvider", ConfiguredAgentOutcomesProviderService>;
+export declare class ConfiguredAgentOutcomesProvider extends ConfiguredAgentOutcomesProvider_base {
+}
+export {};
+//# sourceMappingURL=configured-agent-outcomes-provider.d.ts.map

package/dist/src/workspace/configured-agent-outcomes-provider.js

@@ -0,0 +1,26 @@
+/**
+ * Configured-agent-outcomes provider port.
+ *
+ * The plan pipeline reports per-agent lifecycle outcomes against the generic
+ * `configuredAgentLifecycleOutcomes` derivation. A per-type manager may know
+ * the effective outcomes more precisely (today the hook manager reads agent
+ * hook surfaces directly), so the state layer declares only this optional
+ * port keyed by extension type; the application composes the implementations.
+ * An absent provider — or an absent entry for a type — degrades to the
+ * generic derivation, matching the plan pipeline's existing fallback.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/Context";
+/**
+ * A provider could not produce its outcomes. The implementation owns the
+ * category and wording at construction; consumers transport the failure into
+ * their own reporting envelope without re-rendering it.
+ */
+export class ConfiguredAgentOutcomesUnavailable extends Data.TaggedError("ConfiguredAgentOutcomesUnavailable") {
+}
+export class ConfiguredAgentOutcomesProvider extends ServiceMap.Service()("@agentxm/workspace-state/workspace/configured-agent-outcomes-provider/ConfiguredAgentOutcomesProvider") {
+}
+//# sourceMappingURL=configured-agent-outcomes-provider.js.map

package/dist/src/workspace/configured-agent-outcomes.d.ts

@@ -0,0 +1,48 @@
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { ConfiguredAgentOutcome } from "./configured-agent-outcome.js";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+export type ConfiguredAgentLifecycleState = "projected" | "current";
+/**
+ * Exhaustive policy for interpreting configured agents for every extension
+ * type. A new type cannot compile until its configured-agent semantics exist.
+ */
+export declare const EXTENSION_CONFIGURED_AGENT_POLICY: {
+    readonly skill: {
+        readonly kind: "per-agent";
+    };
+    readonly "mcp-server": {
+        readonly kind: "per-agent";
+    };
+    readonly subagent: {
+        readonly kind: "per-agent";
+    };
+    readonly rule: {
+        readonly kind: "workspace-capability";
+    };
+    readonly hook: {
+        readonly kind: "per-agent";
+    };
+    readonly knowledge: {
+        readonly kind: "not-applicable";
+        readonly reasonCode: "workspace-owned";
+        readonly reason: "Knowledge bundles are workspace-owned and have no per-agent projection.";
+    };
+    readonly pack: {
+        readonly kind: "not-applicable";
+        readonly reasonCode: "container-owned";
+        readonly reason: "Packs are lifecycle containers; their members own projection outcomes.";
+    };
+};
+/** Derive stable configured-agent lifecycle outcomes from canonical capability facts. */
+export declare const configuredAgentLifecycleOutcomes: (args: {
+    readonly type: ExtensionType;
+    readonly name: string;
+    readonly agentIds: ReadonlyArray<string>;
+    readonly scope: WorkspaceScope;
+    readonly state: ConfiguredAgentLifecycleState;
+    readonly targetState: "enabled" | "disabled" | "absent";
+    readonly installed: boolean;
+    readonly observedAgentIds?: ReadonlyArray<string>;
+    readonly applicableAgentIds?: ReadonlyArray<string>;
+}) => ReadonlyArray<ConfiguredAgentOutcome>;
+//# sourceMappingURL=configured-agent-outcomes.d.ts.map

package/dist/src/workspace/configured-agent-outcomes.js

@@ -0,0 +1,113 @@
+import { setupScopeSupportOutcomes } from "./setup-scope-support.js";
+/**
+ * Exhaustive policy for interpreting configured agents for every extension
+ * type. A new type cannot compile until its configured-agent semantics exist.
+ */
+export const EXTENSION_CONFIGURED_AGENT_POLICY = {
+    skill: { kind: "per-agent" },
+    "mcp-server": { kind: "per-agent" },
+    subagent: { kind: "per-agent" },
+    rule: { kind: "workspace-capability" },
+    hook: { kind: "per-agent" },
+    knowledge: {
+        kind: "not-applicable",
+        reasonCode: "workspace-owned",
+        reason: "Knowledge bundles are workspace-owned and have no per-agent projection.",
+    },
+    pack: {
+        kind: "not-applicable",
+        reasonCode: "container-owned",
+        reason: "Packs are lifecycle containers; their members own projection outcomes.",
+    },
+};
+const unsupportedOutcome = (args) => ({
+    extensionType: args.type,
+    name: args.name,
+    agentId: args.agentId,
+    outcome: "unsupported",
+    reasonCode: args.reasonCode,
+    reason: args.reason,
+});
+/** Derive stable configured-agent lifecycle outcomes from canonical capability facts. */
+export const configuredAgentLifecycleOutcomes = (args) => {
+    const policy = EXTENSION_CONFIGURED_AGENT_POLICY[args.type];
+    const observed = new Set(args.observedAgentIds ?? []);
+    const applicable = args.applicableAgentIds === undefined ? undefined : new Set(args.applicableAgentIds);
+    if (policy.kind === "not-applicable") {
+        return args.agentIds.map((agentId) => ({
+            extensionType: args.type,
+            name: args.name,
+            agentId,
+            outcome: "not-applicable",
+            reasonCode: policy.reasonCode,
+            reason: policy.reason,
+        }));
+    }
+    const supportByAgent = new Map(setupScopeSupportOutcomes(args.type, args.agentIds, args.scope).flatMap((outcome) => outcome.agentId === undefined ? [] : [[outcome.agentId, outcome]]));
+    return args.agentIds.map((agentId) => {
+        if (args.targetState !== "enabled") {
+            return {
+                extensionType: args.type,
+                name: args.name,
+                agentId,
+                outcome: "not-applicable",
+                reasonCode: args.targetState === "absent" ? "extension-absent" : "extension-disabled",
+                reason: args.targetState === "absent"
+                    ? "The extension is absent, so no agent projection is expected."
+                    : "The extension is disabled, so no agent projection is expected.",
+            };
+        }
+        if (applicable !== undefined && !applicable.has(agentId)) {
+            return {
+                extensionType: args.type,
+                name: args.name,
+                agentId,
+                outcome: "not-applicable",
+                reasonCode: "target-policy-excluded",
+                reason: `${agentId} is excluded by the extension target policy.`,
+            };
+        }
+        const support = supportByAgent.get(agentId);
+        if (support === undefined) {
+            return unsupportedOutcome({
+                type: args.type,
+                name: args.name,
+                agentId,
+                reasonCode: "unknown-agent",
+                reason: `${agentId} is not present in the coding-agent capability catalog.`,
+            });
+        }
+        if (support.status !== "supported") {
+            return unsupportedOutcome({
+                type: args.type,
+                name: args.name,
+                agentId,
+                reasonCode: support.reasonCode,
+                reason: support.reason,
+            });
+        }
+        const workspaceProjection = policy.kind === "workspace-capability";
+        if (args.state === "current" &&
+            (!args.installed || (!workspaceProjection && !observed.has(agentId)))) {
+            return {
+                extensionType: args.type,
+                name: args.name,
+                agentId,
+                outcome: "failed",
+                reasonCode: args.installed ? "projection-missing" : "extension-missing",
+                reason: args.installed
+                    ? `The expected ${agentId} projection is missing.`
+                    : "The configured extension is not installed.",
+            };
+        }
+        return {
+            extensionType: args.type,
+            name: args.name,
+            agentId,
+            outcome: args.state,
+            reasonCode: "supported",
+            reason: support.reason,
+        };
+    });
+};
+//# sourceMappingURL=configured-agent-outcomes.js.map

package/dist/src/workspace/configured-entry-resolution/types.d.ts

@@ -0,0 +1,32 @@
+import type * as Option from "effect/Option";
+import type { HookExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
+import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import type { NamedRegistryResolution } from "@agentxm/extension-model/unstable/sources/source-host-provider";
+import type { ReleaseAgeBypassRecord, ReleaseAgeHoldbackRecord } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+export type ConfiguredEntryFailureReason = "entry-malformed" | "source-not-found" | "source-multiple-matches" | "source-resolution-failed" | "source-timeout";
+export interface ResolvedConfiguredEntry<TRef> {
+    readonly ref: TRef;
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly releaseAge?: {
+        readonly holdbacks: ReadonlyArray<ReleaseAgeHoldbackRecord>;
+        readonly bypasses: ReadonlyArray<ReleaseAgeBypassRecord>;
+    };
+}
+export type ResolvedConfiguredSkill = ResolvedConfiguredEntry<SkillExtensionRef>;
+export type ResolvedConfiguredSubagent = ResolvedConfiguredEntry<SubagentExtensionRef>;
+export type ResolvedConfiguredRule = ResolvedConfiguredEntry<RuleExtensionRef>;
+export type ResolvedConfiguredHook = ResolvedConfiguredEntry<HookExtensionRef>;
+export type ResolvedConfiguredKnowledge = ResolvedConfiguredEntry<KnowledgeExtensionRef>;
+export type ResolvedConfiguredMcpServer = ResolvedConfiguredEntry<McpServerExtensionRef>;
+export type ResolvedConfiguredPack = ResolvedConfiguredEntry<PackRef>;
+export type ConfiguredRegistryResolution = NamedRegistryResolution & {
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly acceptedVersion?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/workspace/configured-entry-resolution/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/workspace/configured-entry-resolution/workspace-ref.d.ts

@@ -0,0 +1,32 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { type ExtensionName } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { WorkspaceSourceInvalid, type PackageContentHashFailed } from "../errors.js";
+import type { PathTraversalDetected } from "../../utils/path-safety.js";
+import type { WorkspaceHookRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
+import type { WorkspaceKnowledgeRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { WorkspaceMcpServerRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { WorkspacePackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { WorkspaceRuleRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { WorkspaceSkillRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { WorkspaceSubagentRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import type { WorkspaceLayout } from "../layout.js";
+type WorkspaceExtensionRef = WorkspaceSkillRef | WorkspaceMcpServerRef | WorkspaceSubagentRef | WorkspaceRuleRef | WorkspaceHookRef | WorkspaceKnowledgeRef | WorkspacePackRef;
+export declare const resolveWorkspaceExtensionRef: (args: {
+    readonly settingsName: string;
+    readonly source: string;
+    readonly expectedType: ExtensionType;
+    readonly layout: WorkspaceLayout;
+    readonly scope: WorkspaceScope;
+    readonly staticPackage?: {
+        readonly owner: Handle;
+        readonly name: ExtensionName;
+        readonly root: string;
+    };
+}) => Effect.Effect<WorkspaceExtensionRef, WorkspaceSourceInvalid | PathTraversalDetected | PackageContentHashFailed, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=workspace-ref.d.ts.map

package/dist/src/workspace/configured-entry-resolution/workspace-ref.js

@@ -0,0 +1,176 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions/common";
+import { computePackageContentHash } from "../package-hash.js";
+import { WorkspaceSourceInvalid } from "../errors.js";
+import { validatePathSafety } from "../../utils/path-safety.js";
+import { HookManifestSchema, HOOK_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { KnowledgeManifestSchema, KNOWLEDGE_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/knowledge/manifest-schema";
+import { McpServerManifestSchema, MCP_SERVER_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
+import { PackManifestSchema, PACK_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { RuleManifestSchema, RULE_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/rules/manifest-schema";
+import { SkillManifestSchema, MANIFEST_FILENAME as SKILL_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { SubagentManifestSchema, MANIFEST_FILENAME as SUBAGENT_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/subagents/manifest-schema";
+const WorkspaceManifestSchema = Schema.Union([
+    SkillManifestSchema,
+    McpServerManifestSchema,
+    SubagentManifestSchema,
+    RuleManifestSchema,
+    HookManifestSchema,
+    KnowledgeManifestSchema,
+    PackManifestSchema,
+]);
+const manifestFilename = (type) => {
+    switch (type) {
+        case "skill":
+            return SKILL_MANIFEST_FILENAME;
+        case "mcp-server":
+            return MCP_SERVER_MANIFEST_FILENAME;
+        case "subagent":
+            return SUBAGENT_MANIFEST_FILENAME;
+        case "rule":
+            return RULE_MANIFEST_FILENAME;
+        case "hook":
+            return HOOK_MANIFEST_FILENAME;
+        case "knowledge":
+            return KNOWLEDGE_MANIFEST_FILENAME;
+        case "pack":
+            return PACK_MANIFEST_FILENAME;
+    }
+};
+const pluralType = (type) => {
+    switch (type) {
+        case "skill":
+            return "skills";
+        case "mcp-server":
+            return "mcps";
+        case "subagent":
+            return "subagents";
+        case "rule":
+            return "rules";
+        case "hook":
+            return "hooks";
+        case "knowledge":
+            return "knowledge";
+        case "pack":
+            return "packs";
+    }
+};
+const workspaceSourceError = (source, detail, cause) => new WorkspaceSourceInvalid({ source, detail, ...(cause === undefined ? {} : { cause }) });
+export const resolveWorkspaceExtensionRef = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    if (args.source !== "workspace") {
+        return yield* workspaceSourceError(args.source, 'expected the compact selector "workspace"');
+    }
+    if (args.layout.scope === "user" && args.staticPackage === undefined) {
+        return yield* workspaceSourceError(args.source, "user workspaces do not support workspace-authored packages");
+    }
+    const owner = args.staticPackage?.owner ?? args.layout.owner;
+    if (owner === undefined) {
+        return yield* workspaceSourceError(args.source, "the workspace settings do not declare an owner");
+    }
+    const source = {
+        type: "workspace",
+        owner,
+        extensionType: args.expectedType,
+        name: args.staticPackage?.name ?? decodeExtensionNameSync(args.settingsName),
+    };
+    const canonicalRoot = args.layout.scope === "project"
+        ? args.layout.authoredRoot(args.expectedType)
+        : path.join(args.layout.acquiredRoot, owner, pluralType(args.expectedType));
+    const packageDir = args.staticPackage?.root ?? path.join(canonicalRoot, source.name);
+    const containmentRoot = args.layout.scope === "project" ? args.layout.projectRoot : args.layout.workspaceRoot;
+    yield* validatePathSafety(path, containmentRoot, packageDir);
+    const packageExists = yield* fs
+        .exists(packageDir)
+        .pipe(Effect.mapError((cause) => workspaceSourceError(args.source, "the canonical package could not be inspected", cause)));
+    if (!packageExists) {
+        return yield* workspaceSourceError(args.source, `the canonical package is missing at ${packageDir}`);
+    }
+    const manifestPath = path.join(packageDir, manifestFilename(args.expectedType));
+    const rawManifest = yield* fs
+        .readFileString(manifestPath)
+        .pipe(Effect.mapError((cause) => workspaceSourceError(args.source, `the expected manifest is missing at ${manifestPath}`, cause)));
+    const json = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))(rawManifest).pipe(Effect.mapError((cause) => workspaceSourceError(args.source, `the manifest at ${manifestPath} is not valid JSON`, cause)));
+    const manifest = yield* Schema.decodeUnknownEffect(WorkspaceManifestSchema)(json).pipe(Effect.mapError((cause) => workspaceSourceError(args.source, `the manifest at ${manifestPath} is invalid`, cause)));
+    if (manifest.type !== args.expectedType ||
+        manifest.owner !== source.owner ||
+        manifest.name !== source.name) {
+        return yield* workspaceSourceError(args.source, `manifest identity ${manifest.owner}/${manifest.type}/${manifest.name} does not match the locator`);
+    }
+    const sourceHash = yield* computePackageContentHash(packageDir);
+    const details = {
+        source,
+        owner: source.owner,
+        name: source.name,
+        version: manifest.version,
+        scope: args.scope,
+        location: packageDir,
+        sourceHash,
+    };
+    switch (manifest.type) {
+        case "skill":
+            return {
+                type: "skill",
+                refType: "workspace",
+                ...details,
+                skill: {
+                    name: manifest.name,
+                    description: Option.fromUndefinedOr(manifest.description),
+                    metadata: Option.none(),
+                },
+            };
+        case "mcp-server":
+            return {
+                type: "mcp-server",
+                refType: "workspace",
+                ...details,
+                server: { name: manifest.name },
+            };
+        case "subagent":
+            return {
+                type: "subagent",
+                refType: "workspace",
+                ...details,
+                subagent: {
+                    name: manifest.name,
+                    description: Option.fromUndefinedOr(manifest.description),
+                },
+                ...(manifest.fallback === undefined ? {} : { fallback: manifest.fallback }),
+            };
+        case "rule":
+            return {
+                type: "rule",
+                refType: "workspace",
+                ...details,
+                rule: { name: manifest.name },
+            };
+        case "hook":
+            return {
+                type: "hook",
+                refType: "workspace",
+                ...details,
+                hook: { name: manifest.name },
+                ...(manifest.fallback === undefined ? {} : { fallback: manifest.fallback }),
+            };
+        case "knowledge":
+            return {
+                type: "knowledge",
+                refType: "workspace",
+                ...details,
+                knowledge: { name: manifest.name },
+            };
+        case "pack":
+            return {
+                type: "pack",
+                refType: "workspace",
+                ...details,
+                pack: { name: manifest.name, dependencies: manifest.dependencies },
+            };
+    }
+});
+//# sourceMappingURL=workspace-ref.js.map

package/dist/src/workspace/constants.d.ts

@@ -0,0 +1,6 @@
+/** Canonical AXM application-home and workspace names. */
+export declare const AXM_DIR_NAME = ".axm";
+export declare const USER_WORKSPACE_DIRECTORY = "workspace";
+export declare const LOCK_FILENAME = "axm-lock.yaml";
+export declare const ACQUIRED_EXTENSIONS_DIR = "agent_extensions";
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/workspace/constants.js

@@ -0,0 +1,6 @@
+/** Canonical AXM application-home and workspace names. */
+export const AXM_DIR_NAME = ".axm";
+export const USER_WORKSPACE_DIRECTORY = "workspace";
+export const LOCK_FILENAME = "axm-lock.yaml";
+export const ACQUIRED_EXTENSIONS_DIR = "agent_extensions";
+//# sourceMappingURL=constants.js.map

package/dist/src/workspace/create-symlink.d.ts

@@ -0,0 +1,26 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { SymlinkCreationError } from "./errors.js";
+/**
+ * Result of a createSymlink operation.
+ *
+ * - `"created"` — new symlink was created
+ * - `"replaced"` — existing wrong symlink/directory was replaced
+ * - `"no-op"` — existing symlink already points to the correct target
+ * - `"skipped"` — self-reference detected (link and target resolve to same path)
+ */
+export type SymlinkResult = "created" | "replaced" | "no-op" | "skipped";
+/**
+ * Creates a relative symlink from `link` to `target`, handling the full
+ * symlink lifecycle: self-reference detection, existing link inspection,
+ * ELOOP recovery, directory replacement, and parent directory creation.
+ *
+ * Relative paths are computed using resolved parent directories to handle
+ * cases where parent directories are themselves symlinks.
+ */
+export declare const createSymlink: (opts: {
+    readonly target: string;
+    readonly link: string;
+}) => Effect.Effect<"skipped" | "created" | "replaced" | "no-op", import("./transaction.js").WorkspaceSnapshotError | SymlinkCreationError, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=create-symlink.d.ts.map

package/dist/src/workspace/create-symlink.js

@@ -0,0 +1,87 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SymlinkCreationError } from "./errors.js";
+import { protectCreatedAncestors, protectWorkspacePath } from "./transaction.js";
+import { recordFootprint } from "./footprint-recorder.js";
+import { resolveParentSymlinks } from "../utils/resolve-parent-symlinks.js";
+/**
+ * Creates a relative symlink from `link` to `target`, handling the full
+ * symlink lifecycle: self-reference detection, existing link inspection,
+ * ELOOP recovery, directory replacement, and parent directory creation.
+ *
+ * Relative paths are computed using resolved parent directories to handle
+ * cases where parent directories are themselves symlinks.
+ */
+export const createSymlink = (opts) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const p = yield* Path.Path;
+    // Resolve both paths through parent symlinks for accurate comparison
+    const resolvedTarget = yield* resolveParentSymlinks(opts.target).pipe(Effect.mapError((cause) => new SymlinkCreationError({ path: opts.target, step: "resolve-target", cause })));
+    const resolvedLink = yield* resolveParentSymlinks(opts.link).pipe(
+    // Link parent may not exist yet — fall back to the raw path
+    Effect.catch(() => Effect.succeed(opts.link)));
+    // Self-reference detection: skip if both resolve to the same location
+    if (resolvedTarget === resolvedLink) {
+        return "skipped";
+    }
+    // Compute relative path from resolved parent dirs
+    const resolvedLinkParent = p.dirname(resolvedLink);
+    const relTarget = p.relative(resolvedLinkParent, resolvedTarget);
+    // Check what currently exists at the link path
+    const existingResult = yield* inspectExisting(fs, p, opts.link, resolvedTarget);
+    if (existingResult === "no-op")
+        return "no-op";
+    yield* protectWorkspacePath(opts.link);
+    // If something exists that needs replacing, remove it
+    if (existingResult === "replace") {
+        yield* fs
+            .remove(opts.link, { recursive: true })
+            .pipe(Effect.mapError((cause) => new SymlinkCreationError({ path: opts.link, step: "remove-existing", cause })));
+    }
+    // Create parent directories
+    const linkParent = p.dirname(opts.link);
+    yield* protectCreatedAncestors(fs, p, linkParent);
+    yield* fs
+        .makeDirectory(linkParent, { recursive: true })
+        .pipe(Effect.mapError((cause) => new SymlinkCreationError({ path: linkParent, step: "mkdir-parent", cause })));
+    // Create the symlink
+    yield* fs
+        .symlink(relTarget, opts.link)
+        .pipe(Effect.mapError((cause) => new SymlinkCreationError({ path: opts.link, step: "symlink", cause })));
+    yield* recordFootprint({
+        path: opts.link,
+        change: existingResult === "replace" ? "modified" : "created",
+    });
+    return existingResult === "replace" ? "replaced" : "created";
+});
+/**
+ * Inspect what exists at the link path.
+ *
+ * Uses readLink to detect symlinks (since Effect's FileSystem.stat always
+ * follows symlinks — there is no lstat equivalent). Falls back to stat
+ * for non-symlink entries.
+ */
+const inspectExisting = (fs, p, linkPath, resolvedAbsTarget) => Effect.gen(function* () {
+    // Try readLink first — succeeds only if linkPath is a symlink
+    const linkTarget = yield* fs.readLink(linkPath).pipe(Effect.option);
+    if (Option.isSome(linkTarget)) {
+        // It's a symlink — check if it points to the correct target
+        const linkParent = p.dirname(linkPath);
+        const currentAbsTarget = p.resolve(linkParent, linkTarget.value);
+        // Resolve through realpath for cases where parent dirs are symlinks
+        const resolvedCurrentTarget = yield* fs
+            .realPath(currentAbsTarget)
+            .pipe(Effect.catch(() => Effect.succeed(currentAbsTarget)));
+        if (resolvedCurrentTarget === resolvedAbsTarget)
+            return "no-op";
+        return "replace";
+    }
+    // Not a symlink — check if anything else exists (directory, file)
+    const stat = yield* fs.stat(linkPath).pipe(Effect.option);
+    if (Option.isSome(stat))
+        return "replace";
+    return "create";
+});
+//# sourceMappingURL=create-symlink.js.map

package/dist/src/workspace/desired-pack-lock.d.ts

@@ -0,0 +1,18 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { Lockfile } from "../lockfile/schema.js";
+import { type DesiredStateGraph } from "./desired-state-graph.js";
+import type { WorkspaceLayout } from "./layout.js";
+interface ValidateDesiredPackLockArgs {
+    readonly graph: DesiredStateGraph;
+    readonly lockfile: Lockfile;
+    readonly layout: WorkspaceLayout;
+}
+/**
+ * Authorize enabled external Pack manifests against their accepted lock row.
+ * Workspace-authored Pack manifests are desired authority and need no lock row.
+ */
+export declare const validateDesiredPackLock: ({ graph, lockfile, layout, }: ValidateDesiredPackLockArgs) => Effect.Effect<DesiredStateGraph, never, FileSystem.FileSystem | Path.Path>;
+export {};
+//# sourceMappingURL=desired-pack-lock.d.ts.map