@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/desired-state-problem-text.js

@@ -0,0 +1,27 @@
+const constraintContributorText = (contributor) => contributor.source === "pack"
+    ? `${contributor.dependingPack ?? "unknown Pack"} range=${contributor.range} location=${contributor.location}`
+    : `settings range=${contributor.range} location=${contributor.location}`;
+/** Sanitized terminal text for one desired-state problem. */
+export const desiredStateProblemText = (problem) => {
+    switch (problem.type) {
+        case "pack-manifest-unavailable":
+            return `${problem.pack}: installed pack manifest is unavailable`;
+        case "pack-manifest-invalid":
+            return `${problem.pack}: installed pack manifest is invalid`;
+        case "pack-identity-mismatch":
+            return `${problem.pack}: ${problem.detail}`;
+        case "pack-resolution-unavailable":
+            return `${problem.pack}: ${problem.detail}`;
+        case "pack-manifest-content-mismatch":
+            return `${problem.pack}: accepted version=${problem.acceptedVersion} content=${problem.acceptedContentIdentity}; observed status=${problem.status}${problem.observedVersion === undefined ? "" : ` version=${problem.observedVersion} content=${problem.observedContentIdentity}`}`;
+        case "projection-collision":
+            return `${problem.extensionType} ${problem.name}: competing identities ${problem.identities.join(", ")}`;
+        case "constraint-conflict":
+            return `${problem.extensionType} ${problem.name}: incompatible constraints ${problem.contributors.map(constraintContributorText).join(", ")}; decision=blocked; reason=no-satisfying-version`;
+        case "workspace-owner-missing":
+            return `${problem.extensionType} ${problem.name}: workspace owner is missing`;
+    }
+};
+/** Stable, sanitized terminal text for a desired-state problem set. */
+export const desiredStateProblemsText = (problems) => problems.map(desiredStateProblemText).join("; ");
+//# sourceMappingURL=desired-state-problem-text.js.map

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

@@ -0,0 +1,184 @@
+/**
+ * Typed failure families for workspace-state operations: layout validation,
+ * initialization gating, facade entry lookups, and managed filesystem
+ * primitives. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+declare const WorkspaceLayoutError_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: "WorkspaceLayoutError";
+} & Readonly<A>;
+/**
+ * Workspace layout configuration or on-disk authored roots are invalid.
+ * `detail` carries the exact fact sentence the validation produced.
+ */
+export declare class WorkspaceLayoutError extends WorkspaceLayoutError_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const WorkspaceNotInitialized_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: "WorkspaceNotInitialized";
+} & Readonly<A>;
+/** The workspace has no settings file; it must be initialized first. */
+export declare class WorkspaceNotInitialized extends WorkspaceNotInitialized_base<{
+    readonly settingsPath: string;
+}> {
+}
+declare const LockedSkillMissing_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: "LockedSkillMissing";
+} & Readonly<A>;
+/** A skill directory was requested but the lockfile holds no entry for it. */
+export declare class LockedSkillMissing extends LockedSkillMissing_base<{
+    readonly name: string;
+}> {
+}
+declare const SettingsEntryMissing_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: "SettingsEntryMissing";
+} & Readonly<A>;
+/** A settings entry update targeted a name that has no configured entry. */
+export declare class SettingsEntryMissing extends SettingsEntryMissing_base<{
+    readonly entryType: "skill" | "mcp-server";
+    readonly name: string;
+}> {
+}
+declare const InvalidAgentId_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: "InvalidAgentId";
+} & Readonly<A>;
+/** The agent ID is not a configurable agent. */
+export declare class InvalidAgentId extends InvalidAgentId_base<{
+    readonly agentId: string;
+    readonly cause: unknown;
+}> {
+}
+declare const DesiredPackGraphIncomplete_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: "DesiredPackGraphIncomplete";
+} & Readonly<A>;
+/** Pack retention cannot be decided because the desired pack graph is incomplete. */
+export declare class DesiredPackGraphIncomplete extends DesiredPackGraphIncomplete_base {
+}
+declare const CanonicalPathRemovalError_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: "CanonicalPathRemovalError";
+} & Readonly<A>;
+/** Removing a canonical extension path failed. */
+export declare class CanonicalPathRemovalError extends CanonicalPathRemovalError_base<{
+    readonly path: string;
+    readonly step: "inspect" | "remove";
+    readonly cause: unknown;
+}> {
+}
+declare const SymlinkCreationError_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: "SymlinkCreationError";
+} & Readonly<A>;
+/**
+ * Creating or replacing a managed symlink failed. `path` carries the fact
+ * each step's message interpolates: the parent directory for `mkdir-parent`,
+ * the link path otherwise (`resolve-target` interpolates nothing).
+ */
+export declare class SymlinkCreationError extends SymlinkCreationError_base<{
+    readonly path: string;
+    readonly step: "resolve-target" | "remove-existing" | "mkdir-parent" | "symlink";
+    readonly cause: unknown;
+}> {
+}
+declare const LockEntrySourceMissing_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: "LockEntrySourceMissing";
+} & Readonly<A>;
+/** A lockfile entry references a source name that is not configured. */
+export declare class LockEntrySourceMissing extends LockEntrySourceMissing_base<{
+    readonly entryType: string;
+    readonly sourceName: string;
+}> {
+}
+declare const LockEntryUrlInvalid_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: "LockEntryUrlInvalid";
+} & Readonly<A>;
+/** A lockfile source URL failed to parse. */
+export declare class LockEntryUrlInvalid extends LockEntryUrlInvalid_base<{
+    readonly value: string;
+}> {
+}
+declare const LockEntryNameInvalid_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: "LockEntryNameInvalid";
+} & Readonly<A>;
+/** A lockfile extension name failed to decode. */
+export declare class LockEntryNameInvalid extends LockEntryNameInvalid_base<{
+    readonly name: string;
+}> {
+}
+declare const LockEntryEndpointConflict_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: "LockEntryEndpointConflict";
+} & Readonly<A>;
+/**
+ * A lockfile entry and the source configuration disagree about a named
+ * source's endpoint. `sourceKind` carries the wording the entry uses:
+ * "Registry" for registry entries, the source type otherwise.
+ */
+export declare class LockEntryEndpointConflict extends LockEntryEndpointConflict_base<{
+    readonly sourceKind: string;
+    readonly sourceName: string;
+    readonly acceptedEndpoint: string;
+    readonly resolvedEndpoint: string;
+}> {
+}
+declare const LockEntrySourceTypeConflict_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: "LockEntrySourceTypeConflict";
+} & Readonly<A>;
+/** Configuration does not resolve a lockfile entry's source name to its type. */
+export declare class LockEntrySourceTypeConflict extends LockEntrySourceTypeConflict_base<{
+    readonly sourceKind: string;
+    readonly sourceName: string;
+}> {
+}
+declare const AcceptedResolutionMissing_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: "AcceptedResolutionMissing";
+} & Readonly<A>;
+/** The accepted lock authority holds no resolution for the requested extension. */
+export declare class AcceptedResolutionMissing extends AcceptedResolutionMissing_base<{
+    readonly label: string;
+    readonly name: string;
+}> {
+}
+declare const InlineExtensionSourceMissing_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: "InlineExtensionSourceMissing";
+} & Readonly<A>;
+/** An inline-configured entry has no package source, so no ref can be resolved. */
+export declare class InlineExtensionSourceMissing extends InlineExtensionSourceMissing_base<{
+    readonly name: string;
+}> {
+}
+declare const SupersededCanonicalRemovalFailed_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: "SupersededCanonicalRemovalFailed";
+} & Readonly<A>;
+/** Removing a superseded canonical package during transition preparation failed. */
+export declare class SupersededCanonicalRemovalFailed extends SupersededCanonicalRemovalFailed_base<{
+    readonly path: string;
+    readonly cause: unknown;
+}> {
+}
+declare const PackageContentHashFailed_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: "PackageContentHashFailed";
+} & Readonly<A>;
+/** Hashing package content for the advisory change marker failed. */
+export declare class PackageContentHashFailed extends PackageContentHashFailed_base<{
+    readonly packageDir: string;
+    readonly cause: unknown;
+}> {
+}
+declare const WorkspaceSourceInvalid_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: "WorkspaceSourceInvalid";
+} & Readonly<A>;
+/**
+ * A configured workspace source failed validation against the canonical
+ * workspace package. `detail` carries the fact sentence the validation
+ * produced; rendering and recovery guidance stay at the boundary.
+ */
+export declare class WorkspaceSourceInvalid extends WorkspaceSourceInvalid_base<{
+    readonly source: string;
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/workspace/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Typed failure families for workspace-state operations: layout validation,
+ * initialization gating, facade entry lookups, and managed filesystem
+ * primitives. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/**
+ * Workspace layout configuration or on-disk authored roots are invalid.
+ * `detail` carries the exact fact sentence the validation produced.
+ */
+export class WorkspaceLayoutError extends Data.TaggedError("WorkspaceLayoutError") {
+}
+/** The workspace has no settings file; it must be initialized first. */
+export class WorkspaceNotInitialized extends Data.TaggedError("WorkspaceNotInitialized") {
+}
+/** A skill directory was requested but the lockfile holds no entry for it. */
+export class LockedSkillMissing extends Data.TaggedError("LockedSkillMissing") {
+}
+/** A settings entry update targeted a name that has no configured entry. */
+export class SettingsEntryMissing extends Data.TaggedError("SettingsEntryMissing") {
+}
+/** The agent ID is not a configurable agent. */
+export class InvalidAgentId extends Data.TaggedError("InvalidAgentId") {
+}
+/** Pack retention cannot be decided because the desired pack graph is incomplete. */
+export class DesiredPackGraphIncomplete extends Data.TaggedError("DesiredPackGraphIncomplete") {
+}
+/** Removing a canonical extension path failed. */
+export class CanonicalPathRemovalError extends Data.TaggedError("CanonicalPathRemovalError") {
+}
+/**
+ * Creating or replacing a managed symlink failed. `path` carries the fact
+ * each step's message interpolates: the parent directory for `mkdir-parent`,
+ * the link path otherwise (`resolve-target` interpolates nothing).
+ */
+export class SymlinkCreationError extends Data.TaggedError("SymlinkCreationError") {
+}
+/** A lockfile entry references a source name that is not configured. */
+export class LockEntrySourceMissing extends Data.TaggedError("LockEntrySourceMissing") {
+}
+/** A lockfile source URL failed to parse. */
+export class LockEntryUrlInvalid extends Data.TaggedError("LockEntryUrlInvalid") {
+}
+/** A lockfile extension name failed to decode. */
+export class LockEntryNameInvalid extends Data.TaggedError("LockEntryNameInvalid") {
+}
+/**
+ * A lockfile entry and the source configuration disagree about a named
+ * source's endpoint. `sourceKind` carries the wording the entry uses:
+ * "Registry" for registry entries, the source type otherwise.
+ */
+export class LockEntryEndpointConflict extends Data.TaggedError("LockEntryEndpointConflict") {
+}
+/** Configuration does not resolve a lockfile entry's source name to its type. */
+export class LockEntrySourceTypeConflict extends Data.TaggedError("LockEntrySourceTypeConflict") {
+}
+/** The accepted lock authority holds no resolution for the requested extension. */
+export class AcceptedResolutionMissing extends Data.TaggedError("AcceptedResolutionMissing") {
+}
+/** An inline-configured entry has no package source, so no ref can be resolved. */
+export class InlineExtensionSourceMissing extends Data.TaggedError("InlineExtensionSourceMissing") {
+}
+/** Removing a superseded canonical package during transition preparation failed. */
+export class SupersededCanonicalRemovalFailed extends Data.TaggedError("SupersededCanonicalRemovalFailed") {
+}
+/** Hashing package content for the advisory change marker failed. */
+export class PackageContentHashFailed extends Data.TaggedError("PackageContentHashFailed") {
+}
+/**
+ * A configured workspace source failed validation against the canonical
+ * workspace package. `detail` carries the fact sentence the validation
+ * produced; rendering and recovery guidance stay at the boundary.
+ */
+export class WorkspaceSourceInvalid extends Data.TaggedError("WorkspaceSourceInvalid") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/workspace/extension-name.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure extension-name vocabulary.
+ *
+ * Deterministic naming helpers shared by every extension type: sanitizing an
+ * extension name into a safe on-disk directory name and normalizing a
+ * human-authored label into a valid AXM extension name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { type ExtensionName } from "@agentxm/extension-model/unstable/extensions/common";
+/**
+ * Sanitizes an extension name into a safe on-disk directory name.
+ *
+ * Transformation pipeline:
+ * 1. Convert to lowercase
+ * 2. Replace non-alphanumeric characters (except `.` and `_`) with hyphens
+ * 3. Strip leading dots and hyphens
+ * 4. Truncate to 255 characters, then strip trailing dots and hyphens
+ * 5. Fall back to `"unnamed-skill"` if empty
+ * 6. Preserve canonical names; otherwise append a deterministic discriminator
+ */
+export declare const sanitizeName: (name: string) => string;
+/**
+ * Converts a human-authored label into a valid AXM extension name.
+ */
+export declare const normalizeExtensionName: (name: string) => ExtensionName;
+//# sourceMappingURL=extension-name.d.ts.map

package/dist/src/workspace/extension-name.js

@@ -0,0 +1,66 @@
+/**
+ * Pure extension-name vocabulary.
+ *
+ * Deterministic naming helpers shared by every extension type: sanitizing an
+ * extension name into a safe on-disk directory name and normalizing a
+ * human-authored label into a valid AXM extension name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions/common";
+/**
+ * Sanitizes an extension name into a safe on-disk directory name.
+ *
+ * Transformation pipeline:
+ * 1. Convert to lowercase
+ * 2. Replace non-alphanumeric characters (except `.` and `_`) with hyphens
+ * 3. Strip leading dots and hyphens
+ * 4. Truncate to 255 characters, then strip trailing dots and hyphens
+ * 5. Fall back to `"unnamed-skill"` if empty
+ * 6. Preserve canonical names; otherwise append a deterministic discriminator
+ */
+export const sanitizeName = (name) => {
+    const sanitized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._]+/g, "-")
+        .replace(/^[.-]+/, "")
+        .slice(0, 255)
+        .replace(/[.-]+$/, "");
+    const fallback = sanitized || "unnamed-skill";
+    if (fallback === name) {
+        return fallback;
+    }
+    // Extension names are normally canonical before reaching filesystem code.
+    // Preserve those stable paths. For defensive non-canonical input,
+    // append a deterministic discriminator so distinct display names that
+    // normalize to the same slug cannot address each other's files.
+    let high = 0x9e3779b9;
+    let low = 0x811c9dc5;
+    for (const codePoint of name) {
+        const value = codePoint.codePointAt(0) ?? 0;
+        low = Math.imul(low ^ value, 0x01000193);
+        high = Math.imul(high ^ value, 0x85ebca6b);
+    }
+    const discriminator = `${(high >>> 0).toString(16).padStart(8, "0")}${(low >>> 0)
+        .toString(16)
+        .padStart(8, "0")}`;
+    const maxSlugLength = 255 - discriminator.length - 2;
+    const slug = fallback.slice(0, maxSlugLength).replace(/[.-]+$/, "") || "unnamed-skill";
+    return `${slug}__${discriminator}`;
+};
+/**
+ * Converts a human-authored label into a valid AXM extension name.
+ */
+export const normalizeExtensionName = (name) => {
+    const normalized = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "")
+        .slice(0, 64)
+        .replace(/-+$/, "");
+    return decodeExtensionNameSync(normalized || "unnamed-extension");
+};
+//# sourceMappingURL=extension-name.js.map

package/dist/src/workspace/extension-paths.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared extension directory path helpers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { ExtensionTypePlural } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { GitBasedSource, LocalSource, RegistrySource } from "@agentxm/extension-model/unstable/sources/types";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceLayout } from "./layout.js";
+export type ExtensionPathSource = {
+    readonly refType: "registry";
+    readonly owner: Handle;
+    readonly source: RegistrySource;
+    readonly portable?: false;
+} | {
+    readonly refType: "workspace";
+    readonly owner: Handle;
+    readonly portable?: false;
+} | {
+    readonly refType: "git-hosted";
+    readonly source: GitBasedSource;
+    readonly sourcePath?: string;
+    readonly portable?: boolean;
+} | {
+    readonly refType: "local";
+    readonly source: LocalSource;
+    readonly sourcePath?: string;
+    readonly portable?: boolean;
+};
+export type ExtensionPathLockEntry = {
+    readonly type: "registry";
+    readonly sourceName: string;
+    readonly endpoint: URL;
+    readonly owner: Handle;
+} | {
+    readonly type: "local";
+    readonly path: string;
+    readonly packageFormat: "agentxm" | "agent-skill";
+} | {
+    readonly type: "github" | "gitlab" | "bitbucket";
+    readonly sourceName: string;
+    readonly endpoint: URL;
+    readonly owner: string;
+    readonly repo: string;
+    readonly path?: string | undefined;
+    readonly ref?: string | undefined;
+    readonly packageFormat: "agentxm" | "agent-skill";
+} | {
+    readonly type: "azurerepos";
+    readonly sourceName: string;
+    readonly endpoint: URL;
+    readonly organization: string;
+    readonly project: string;
+    readonly repo: string;
+    readonly path?: string | undefined;
+    readonly ref?: string | undefined;
+    readonly packageFormat: "agentxm" | "agent-skill";
+} | {
+    readonly type: "git";
+    readonly url: string;
+    readonly path?: string | undefined;
+    readonly ref?: string | undefined;
+    readonly packageFormat: "agentxm" | "agent-skill";
+};
+export declare const extensionPathSourceFromLockEntry: (entry: ExtensionPathLockEntry) => Exclude<ExtensionPathSource, {
+    readonly refType: "workspace";
+}>;
+export interface ExtensionDirPaths {
+    readonly canonicalPath: AbsolutePath;
+    readonly extensionSrcPath: AbsolutePath;
+}
+export declare const extensionContentFilename: (name: string) => string;
+export declare const extensionContentPath: (join: (...paths: string[]) => string, root: string, name: string) => AbsolutePath;
+/** Render a portable display path for an acquired extension package. */
+export declare const acquiredExtensionDisplayPath: (root: string, source: Exclude<ExtensionPathSource, {
+    readonly refType: "workspace";
+}>, type: ExtensionTypePlural, name: string) => string;
+/** Render the acquired display path proven by a persisted lock entry. */
+export declare const acquiredExtensionDisplayPathFromLockEntry: (root: string, entry: ExtensionPathLockEntry, type: ExtensionTypePlural, name: string) => string;
+export declare const computeExtensionPathsForLayout: (join: (...paths: string[]) => string, layout: WorkspaceLayout, source: ExtensionPathSource, type: ExtensionTypePlural, sanitizedName: string) => ExtensionDirPaths;
+//# sourceMappingURL=extension-paths.d.ts.map

package/dist/src/workspace/extension-paths.js

@@ -0,0 +1,172 @@
+/**
+ * Shared extension directory path helpers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import { decodeAbsolutePathSync, } from "@agentxm/extension-model/unstable/path-types";
+export const extensionPathSourceFromLockEntry = (entry) => {
+    switch (entry.type) {
+        case "registry":
+            return {
+                refType: "registry",
+                owner: entry.owner,
+                source: {
+                    type: "registry",
+                    name: entry.sourceName,
+                    location: entry.endpoint,
+                    owner: Option.some(entry.owner),
+                },
+            };
+        case "local":
+            return {
+                refType: "local",
+                source: { type: "local", path: entry.path },
+                sourcePath: entry.path,
+                portable: entry.packageFormat === "agent-skill",
+            };
+        case "github":
+        case "gitlab":
+        case "bitbucket":
+            return {
+                refType: "git-hosted",
+                source: {
+                    type: entry.type,
+                    name: entry.sourceName,
+                    url: entry.endpoint,
+                    owner: entry.owner,
+                    repo: entry.repo,
+                    ref: Option.fromUndefinedOr(entry.ref),
+                    subPath: Option.fromUndefinedOr(entry.path),
+                },
+                ...(entry.path === undefined ? {} : { sourcePath: entry.path }),
+                portable: entry.packageFormat === "agent-skill",
+            };
+        case "azurerepos":
+            return {
+                refType: "git-hosted",
+                source: {
+                    type: "azurerepos",
+                    name: entry.sourceName,
+                    url: entry.endpoint,
+                    organization: entry.organization,
+                    project: entry.project,
+                    repo: entry.repo,
+                    ref: Option.fromUndefinedOr(entry.ref),
+                    subPath: Option.fromUndefinedOr(entry.path),
+                },
+                ...(entry.path === undefined ? {} : { sourcePath: entry.path }),
+                portable: entry.packageFormat === "agent-skill",
+            };
+        case "git":
+            return {
+                refType: "git-hosted",
+                source: {
+                    type: "git",
+                    url: new URL(entry.url),
+                    ref: Option.fromUndefinedOr(entry.ref),
+                },
+                ...(entry.path === undefined ? {} : { sourcePath: entry.path }),
+                portable: entry.packageFormat === "agent-skill",
+            };
+    }
+};
+export const extensionContentFilename = (name) => `${name}.md`;
+export const extensionContentPath = (join, root, name) => decodeAbsolutePathSync(join(root, extensionContentFilename(name)));
+const sourcePathSegments = (value) => {
+    const segments = value
+        .replaceAll("\\", "/")
+        .split("/")
+        .filter((segment) => segment !== "" && segment !== ".");
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error(`Extension source path cannot contain traversal segments: ${value}`);
+    }
+    return segments;
+};
+const localSourcePathSegments = (value) => value
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== ".")
+    .map((segment) => (segment === ".." ? "%2E%2E" : encodeURIComponent(segment)));
+const gitRepositorySegments = (url) => {
+    const pathSegments = sourcePathSegments(url.pathname);
+    const last = pathSegments.at(-1);
+    const repositorySegments = last?.endsWith(".git") === true
+        ? [...pathSegments.slice(0, -1), last.slice(0, -4)]
+        : pathSegments;
+    return [url.hostname, ...repositorySegments].filter((segment) => segment.length > 0);
+};
+const selectedSourcePath = (source) => source.sourcePath ??
+    (source.source.type === "git" ? undefined : Option.getOrUndefined(source.source.subPath));
+const acquiredSourceSegments = (source) => {
+    switch (source.refType) {
+        case "registry":
+            return [source.source.name, source.owner];
+        case "local":
+            return ["local", ...localSourcePathSegments(source.sourcePath ?? source.source.path)];
+        case "git-hosted": {
+            const selected = selectedSourcePath(source);
+            const selectedSegments = selected === undefined ? [] : sourcePathSegments(selected);
+            switch (source.source.type) {
+                case "github":
+                case "gitlab":
+                case "bitbucket":
+                    return [
+                        source.source.name,
+                        ...sourcePathSegments(source.source.owner),
+                        source.source.repo,
+                        ...selectedSegments,
+                    ];
+                case "azurerepos":
+                    return [
+                        source.source.name,
+                        source.source.organization,
+                        source.source.project,
+                        source.source.repo,
+                        ...selectedSegments,
+                    ];
+                case "git":
+                    return ["git", ...gitRepositorySegments(source.source.url), ...selectedSegments];
+            }
+        }
+    }
+};
+/** Render a portable display path for an acquired extension package. */
+export const acquiredExtensionDisplayPath = (root, source, type, name) => [
+    root.replace(/[\\/]+$/u, ""),
+    ...acquiredSourceSegments(source),
+    ...(source.refType === "registry" ? [type, name] : []),
+].join("/");
+/** Render the acquired display path proven by a persisted lock entry. */
+export const acquiredExtensionDisplayPathFromLockEntry = (root, entry, type, name) => acquiredExtensionDisplayPath(root, extensionPathSourceFromLockEntry(entry), type, name);
+const extensionPathsAt = (join, canonicalPath, source, type) => ({
+    canonicalPath: decodeAbsolutePathSync(canonicalPath),
+    extensionSrcPath: decodeAbsolutePathSync(source.refType !== "workspace" && source.portable === true
+        ? canonicalPath
+        : type === "mcps" || type === "packs"
+            ? canonicalPath
+            : join(canonicalPath, "src")),
+});
+export const computeExtensionPathsForLayout = (join, layout, source, type, sanitizedName) => {
+    if (source.refType === "workspace") {
+        const canonicalPath = layout.scope === "project"
+            ? join(layout.authoredRoot(type === "mcps"
+                ? "mcp-server"
+                : type === "skills"
+                    ? "skill"
+                    : type === "subagents"
+                        ? "subagent"
+                        : type === "rules"
+                            ? "rule"
+                            : type === "hooks"
+                                ? "hook"
+                                : type === "knowledge"
+                                    ? "knowledge"
+                                    : "pack"), sanitizedName)
+            : join(layout.acquiredRoot, source.owner, type, sanitizedName);
+        return extensionPathsAt(join, canonicalPath, source, type);
+    }
+    const canonicalPath = join(layout.acquiredRoot, ...acquiredSourceSegments(source), ...(source.refType === "registry" ? [type, sanitizedName] : []));
+    return extensionPathsAt(join, canonicalPath, source, type);
+};
+//# sourceMappingURL=extension-paths.js.map