@agentxm/extension-sources 0.28.4-bootstrap.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @agentxm/extension-sources
+
+The AXM extension-source integration: source locator routing over the
+contract grammar, source host providers for the Registry, GitHub, GitLab,
+Bitbucket, Azure Repos, generic Git, and local paths, convention and manifest
+package discovery, installed/registry identifier resolution, and shallow git
+acquisition.
+
+Unstable and unsupported — use the [axm.sh](https://axm.sh) CLI.

package/dist/src/axm-skill-gate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Official AXM skill candidate gate for registry resolution.
+ *
+ * Resolving the official AXM skill from a registry is gated on whether the
+ * candidate release is compatible with the running CLI. That policy is owned
+ * above this integration, so the registry host provider consumes it through
+ * this port: candidate bytes in, a rendered verdict out. The composition
+ * root implements it from the extension-workspace compatibility policy (see
+ * the application runtime's axm-skill gate Live).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Path from "effect/Path";
+import * as ServiceMap from "effect/Context";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+import type { CarriedFailureCategory } from "./failure-category.js";
+declare const AxmSkillGateUnavailable_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: "AxmSkillGateUnavailable";
+} & Readonly<A>;
+/**
+ * The gate implementation could not produce a verdict. The implementation
+ * owns the category and wording at construction; the provider transports the
+ * failure without re-rendering it.
+ */
+export declare class AxmSkillGateUnavailable extends AxmSkillGateUnavailable_base<{
+    readonly category: CarriedFailureCategory;
+    readonly detail: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+/** A candidate extracted to disk for evaluation. */
+export interface AxmSkillCandidate {
+    readonly ref: SkillExtensionRef;
+    readonly packageRoot: string;
+    readonly skillSourcePath: string;
+}
+/**
+ * The rendered compatibility verdict for one official AXM skill candidate:
+ * the incompatibility sentence and the recovery command and target already
+ * rendered by the policy owner.
+ */
+export interface AxmSkillCandidateVerdict {
+    readonly status: "compatible" | "incompatible";
+    readonly detail: string | null;
+    readonly recoveryCommand: string | null;
+    readonly recoveryTarget: string;
+}
+export interface AxmSkillCandidateGateService {
+    /**
+     * Evaluate one extracted candidate. `null` means the candidate is not the
+     * official AXM skill and the gate does not apply.
+     */
+    readonly evaluate: (candidate: AxmSkillCandidate) => Effect.Effect<AxmSkillCandidateVerdict | null, AxmSkillGateUnavailable, FileSystem.FileSystem | Path.Path>;
+}
+declare const AxmSkillCandidateGate_base: ServiceMap.ServiceClass<AxmSkillCandidateGate, "@agentxm/extension-sources/axm-skill-gate/AxmSkillCandidateGate", AxmSkillCandidateGateService>;
+export declare class AxmSkillCandidateGate extends AxmSkillCandidateGate_base {
+}
+export {};
+//# sourceMappingURL=axm-skill-gate.d.ts.map

package/dist/src/axm-skill-gate.js

@@ -0,0 +1,25 @@
+/**
+ * Official AXM skill candidate gate for registry resolution.
+ *
+ * Resolving the official AXM skill from a registry is gated on whether the
+ * candidate release is compatible with the running CLI. That policy is owned
+ * above this integration, so the registry host provider consumes it through
+ * this port: candidate bytes in, a rendered verdict out. The composition
+ * root implements it from the extension-workspace compatibility policy (see
+ * the application runtime's axm-skill gate Live).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Data from "effect/Data";
+import * as ServiceMap from "effect/Context";
+/**
+ * The gate implementation could not produce a verdict. The implementation
+ * owns the category and wording at construction; the provider transports the
+ * failure without re-rendering it.
+ */
+export class AxmSkillGateUnavailable extends Data.TaggedError("AxmSkillGateUnavailable") {
+}
+export class AxmSkillCandidateGate extends ServiceMap.Service()("@agentxm/extension-sources/axm-skill-gate/AxmSkillCandidateGate") {
+}
+//# sourceMappingURL=axm-skill-gate.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Failure vocabulary for the extension-sources layer.
+ *
+ * Source resolution interprets user-supplied locators against configured
+ * hosts and external systems, so its failures carry the deciding facts as
+ * typed fields plus the user-facing sentence the resolution site owns. The
+ * category vocabulary uses the same strings as the application error codes so
+ * the boundary conversion is a field copy; the application asserts the parity
+ * at compile time. Suggestions carried here are display data in the shared
+ * `SuggestedAction` contract shape, and `recover`/`cmd` reproduce the
+ * application envelope's recovery sugar verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+import { type RegistryClientFailure } from "@agentxm/registry-client";
+import { AxmSkillGateUnavailable } from "./axm-skill-gate.js";
+import { WorkspaceCatalogUnavailable } from "./workspace-catalog.js";
+/** Every category a source-resolution failure can carry. Identical strings to the CLI error codes. */
+export declare const SOURCE_ERROR_CATEGORIES: readonly ["conflict", "internal", "network", "not_found", "validation"];
+export type SourceErrorCategory = (typeof SOURCE_ERROR_CATEGORIES)[number];
+declare const SourceSyntaxInvalid_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: "SourceSyntaxInvalid";
+} & Readonly<A>;
+/**
+ * Input that does not parse as any source locator grammar the resolver
+ * understands: malformed URLs, SCP addresses, provider shorthands, or empty
+ * input. Always a validation failure.
+ */
+export declare class SourceSyntaxInvalid extends SourceSyntaxInvalid_base<{
+    readonly detail: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+declare const SourceHostNotConfigured_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: "SourceHostNotConfigured";
+} & Readonly<A>;
+/**
+ * Syntactically valid input that no configured source host serves: an
+ * unmatched hostname, an unknown source name, a host/params type mismatch, or
+ * an ambiguous match across configured hosts. Always a validation failure.
+ */
+export declare class SourceHostNotConfigured extends SourceHostNotConfigured_base<{
+    readonly detail: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+declare const SourceNotResolvable_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: "SourceNotResolvable";
+} & Readonly<A>;
+/**
+ * A well-formed locator or identifier that did not resolve to a usable
+ * extension source: nothing matched, the match was ambiguous, discovered
+ * content was invalid, or resolution was refused. The constructing site owns
+ * the category and the sentence; `recover`/`cmd` reproduce the application
+ * envelope's recovery sugar.
+ */
+export declare class SourceNotResolvable extends SourceNotResolvable_base<{
+    readonly category: SourceErrorCategory;
+    readonly detail: string;
+    readonly recover?: string;
+    readonly cmd?: string;
+    readonly suggestions?: ReadonlyArray<SuggestedAction>;
+    readonly cause?: unknown;
+}> {
+}
+declare const SourceNetworkFailure_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: "SourceNetworkFailure";
+} & Readonly<A>;
+/**
+ * A network-facing acquisition step failed: temp-dir staging for a clone or
+ * archive, an integrity mismatch, or a ref that carries no fetchable
+ * location. Always a network failure; `retryable` is carried only when the
+ * failing step established it.
+ */
+export declare class SourceNetworkFailure extends SourceNetworkFailure_base<{
+    readonly detail: string;
+    readonly retryable?: boolean;
+    readonly cause?: unknown;
+}> {
+}
+/** The git subprocess operations this package performs. */
+export type GitOperation = "clone" | "get-commit-sha" | "get-tree-sha";
+declare const GitOperationFailed_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: "GitOperationFailed";
+} & Readonly<A>;
+/**
+ * A git subprocess operation failed. Clones are network failures; SHA reads
+ * over an existing checkout are validation failures.
+ */
+export declare class GitOperationFailed extends GitOperationFailed_base<{
+    readonly operation: GitOperation;
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+/** Every typed failure constructed by this package's own modules. */
+export type SourceError = SourceSyntaxInvalid | SourceHostNotConfigured | SourceNotResolvable | SourceNetworkFailure | GitOperationFailed;
+/**
+ * Every failure a source-resolution effect can surface: this package's own
+ * families, the two composition-root port failures, and registry-client
+ * failures propagated from registry-backed providers.
+ */
+export type SourceResolutionFailure = SourceError | WorkspaceCatalogUnavailable | AxmSkillGateUnavailable | RegistryClientFailure;
+export declare const isSourceError: (error: unknown) => error is SourceError;
+export declare const isSourceResolutionFailure: (error: unknown) => error is SourceResolutionFailure;
+/**
+ * The category a source-resolution failure resolves to at the application
+ * boundary. Fallback branches key typed decisions on this instead of
+ * sniffing the rendered envelope.
+ */
+export declare const sourceResolutionFailureCategory: (error: SourceResolutionFailure) => string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,98 @@
+/**
+ * Failure vocabulary for the extension-sources layer.
+ *
+ * Source resolution interprets user-supplied locators against configured
+ * hosts and external systems, so its failures carry the deciding facts as
+ * typed fields plus the user-facing sentence the resolution site owns. The
+ * category vocabulary uses the same strings as the application error codes so
+ * the boundary conversion is a field copy; the application asserts the parity
+ * at compile time. Suggestions carried here are display data in the shared
+ * `SuggestedAction` contract shape, and `recover`/`cmd` reproduce the
+ * application envelope's recovery sugar verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import { isRegistryClientFailure } from "@agentxm/registry-client";
+import { AxmSkillGateUnavailable } from "./axm-skill-gate.js";
+import { WorkspaceCatalogUnavailable } from "./workspace-catalog.js";
+/** Every category a source-resolution failure can carry. Identical strings to the CLI error codes. */
+export const SOURCE_ERROR_CATEGORIES = [
+    "conflict",
+    "internal",
+    "network",
+    "not_found",
+    "validation",
+];
+/**
+ * Input that does not parse as any source locator grammar the resolver
+ * understands: malformed URLs, SCP addresses, provider shorthands, or empty
+ * input. Always a validation failure.
+ */
+export class SourceSyntaxInvalid extends Data.TaggedError("SourceSyntaxInvalid") {
+}
+/**
+ * Syntactically valid input that no configured source host serves: an
+ * unmatched hostname, an unknown source name, a host/params type mismatch, or
+ * an ambiguous match across configured hosts. Always a validation failure.
+ */
+export class SourceHostNotConfigured extends Data.TaggedError("SourceHostNotConfigured") {
+}
+/**
+ * A well-formed locator or identifier that did not resolve to a usable
+ * extension source: nothing matched, the match was ambiguous, discovered
+ * content was invalid, or resolution was refused. The constructing site owns
+ * the category and the sentence; `recover`/`cmd` reproduce the application
+ * envelope's recovery sugar.
+ */
+export class SourceNotResolvable extends Data.TaggedError("SourceNotResolvable") {
+}
+/**
+ * A network-facing acquisition step failed: temp-dir staging for a clone or
+ * archive, an integrity mismatch, or a ref that carries no fetchable
+ * location. Always a network failure; `retryable` is carried only when the
+ * failing step established it.
+ */
+export class SourceNetworkFailure extends Data.TaggedError("SourceNetworkFailure") {
+}
+/**
+ * A git subprocess operation failed. Clones are network failures; SHA reads
+ * over an existing checkout are validation failures.
+ */
+export class GitOperationFailed extends Data.TaggedError("GitOperationFailed") {
+}
+export const isSourceError = (error) => error instanceof SourceSyntaxInvalid ||
+    error instanceof SourceHostNotConfigured ||
+    error instanceof SourceNotResolvable ||
+    error instanceof SourceNetworkFailure ||
+    error instanceof GitOperationFailed;
+export const isSourceResolutionFailure = (error) => isSourceError(error) ||
+    error instanceof WorkspaceCatalogUnavailable ||
+    error instanceof AxmSkillGateUnavailable ||
+    isRegistryClientFailure(error);
+/**
+ * The category a source-resolution failure resolves to at the application
+ * boundary. Fallback branches key typed decisions on this instead of
+ * sniffing the rendered envelope.
+ */
+export const sourceResolutionFailureCategory = (error) => {
+    switch (error._tag) {
+        case "SourceSyntaxInvalid":
+        case "SourceHostNotConfigured":
+            return "validation";
+        case "SourceNotResolvable":
+            return error.category;
+        case "SourceNetworkFailure":
+            return "network";
+        case "GitOperationFailed":
+            return error.operation === "clone" ? "network" : "validation";
+        case "WorkspaceCatalogUnavailable":
+        case "AxmSkillGateUnavailable":
+            return error.category;
+        case "RegistryProblem":
+        case "RegistryRequestFailed":
+        case "RegistryOperationFailed":
+            return error.category;
+    }
+};
+//# sourceMappingURL=errors.js.map

package/dist/src/failure-category.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Failure category vocabulary carried by this package's composition-root
+ * ports. The literals are the same strings as the CLI's `AppErrorCode`; the
+ * application's conversion site asserts the parity at compile time by
+ * assigning this type to its own.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type CarriedFailureCategory = "issues" | "usage" | "not_found" | "auth" | "forbidden" | "conflict" | "rate_limit" | "network" | "validation" | "internal" | "unavailable" | "quota" | "auth_required" | "auth_expired" | "auth_denied" | "timeout";
+//# sourceMappingURL=failure-category.d.ts.map

package/dist/src/failure-category.js

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

package/dist/src/file-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared utility functions for source parsing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+/** Convert a `file://` URL to a local filesystem path. */
+export declare const fileUrlToPath: (fileUrl: string) => string;
+//# sourceMappingURL=file-url.d.ts.map

package/dist/src/file-url.js

@@ -0,0 +1,12 @@
+/**
+ * Shared utility functions for source parsing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Intentional escape hatch: node:url fileURLToPath has no @effect/platform equivalent.
+// This is a pure string transform (no I/O) so wrapping in Effect adds no value.
+import { fileURLToPath as nodeFileUrlToPath } from "node:url";
+/** Convert a `file://` URL to a local filesystem path. */
+export const fileUrlToPath = (fileUrl) => nodeFileUrlToPath(fileUrl);
+//# sourceMappingURL=file-url.js.map

package/dist/src/git/detect.d.ts

@@ -0,0 +1,7 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+export declare const findGitRoot: (workspaceRoot: string) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
+export declare const isGitManaged: (workspaceRoot: string) => Effect.Effect<boolean, never, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/src/git/detect.js

@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+const entryExists = (filePath) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    return yield* fs.exists(filePath).pipe(Effect.catch(() => Effect.succeed(false)));
+});
+export const findGitRoot = (workspaceRoot) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const walk = (current) => Effect.gen(function* () {
+        const hasGitEntry = yield* entryExists(path.join(current, ".git"));
+        if (hasGitEntry)
+            return Option.some(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            return Option.none();
+        return yield* walk(parent);
+    });
+    return yield* walk(path.resolve(workspaceRoot));
+});
+export const isGitManaged = (workspaceRoot) => findGitRoot(workspaceRoot).pipe(Effect.map(Option.isSome));
+//# sourceMappingURL=detect.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Git operations for cloning repositories at specific refs.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { GitOperationFailed } from "../errors.js";
+/**
+ * Shallow clone a git repository (depth 1, single branch).
+ * Significantly faster than a full clone for read-only use cases like skill discovery.
+ *
+ * @param url - Repository URL (HTTPS or SSH)
+ * @param destination - Local path to clone to
+ * @param ref - Optional git ref (branch or tag) to clone
+ * @returns Effect that resolves on success or fails with GitError
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const shallowClone: (url: string, destination: string, ref?: string) => Effect.Effect<string, GitOperationFailed, Path.Path>;
+/** Get the immutable commit checked out at HEAD. */
+export declare const getCommitSha: (repoPath: string) => Effect.Effect<string, GitOperationFailed, never>;
+/**
+ * Get the git tree SHA for a path within a repository.
+ *
+ * The tree SHA is a hash of the directory's contents at the current commit.
+ * Unlike commit SHA, it is stable across rebases that don't change content.
+ *
+ * @param repoPath - Path to the git repository root
+ * @param subPath - Optional subpath within the repository (defaults to root ".")
+ * @returns Effect that resolves to the tree SHA, or fails if path is not in a git repo
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const getTreeSha: (repoPath: string, subPath?: string) => Effect.Effect<string, GitOperationFailed, never>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/src/git/operations.js

@@ -0,0 +1,101 @@
+/**
+ * Git operations for cloning repositories at specific refs.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { simpleGit } from "simple-git";
+import { GitOperationFailed } from "../errors.js";
+// -----------------------------------------------------------------------------
+// Internal Helpers
+// -----------------------------------------------------------------------------
+const createGit = (baseDir, abort) => {
+    const options = {
+        baseDir,
+        binary: "git",
+        maxConcurrentProcesses: 1,
+        ...(abort === undefined ? {} : { abort }),
+    };
+    return simpleGit(options).env("GIT_TERMINAL_PROMPT", "0").env("GIT_LFS_SKIP_SMUDGE", "1");
+};
+/**
+ * Maps unknown errors to the typed git failure with appropriate context.
+ */
+const mapGitError = (operation, context) => (error) => {
+    const baseMessage = context ?? `Git ${operation} failed`;
+    return new GitOperationFailed({
+        operation,
+        detail: baseMessage,
+        cause: error,
+    });
+};
+// -----------------------------------------------------------------------------
+// Git Operations
+// -----------------------------------------------------------------------------
+/**
+ * Shallow clone a git repository (depth 1, single branch).
+ * Significantly faster than a full clone for read-only use cases like skill discovery.
+ *
+ * @param url - Repository URL (HTTPS or SSH)
+ * @param destination - Local path to clone to
+ * @param ref - Optional git ref (branch or tag) to clone
+ * @returns Effect that resolves on success or fails with GitError
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const shallowClone = (url, destination, ref) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    return yield* Effect.tryPromise({
+        try: (signal) => createGit(path.dirname(destination), signal).clone(url, destination, [
+            "--depth",
+            "1",
+            "--single-branch",
+            ...(ref ? ["--branch", ref] : []),
+        ]),
+        catch: mapGitError("clone", `Failed to shallow clone ${url}`),
+    });
+}).pipe(Effect.withSpan("Git.shallowClone"));
+/** Get the immutable commit checked out at HEAD. */
+export const getCommitSha = (repoPath) => Effect.tryPromise({
+    try: async (signal) => (await createGit(repoPath, signal).revparse(["HEAD"])).trim(),
+    catch: mapGitError("get-commit-sha", "Failed to get checked-out commit SHA"),
+}).pipe(Effect.withSpan("Git.getCommitSha"));
+/**
+ * Get the git tree SHA for a path within a repository.
+ *
+ * The tree SHA is a hash of the directory's contents at the current commit.
+ * Unlike commit SHA, it is stable across rebases that don't change content.
+ *
+ * @param repoPath - Path to the git repository root
+ * @param subPath - Optional subpath within the repository (defaults to root ".")
+ * @returns Effect that resolves to the tree SHA, or fails if path is not in a git repo
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const getTreeSha = (repoPath, subPath = ".") => Effect.tryPromise({
+    try: async (signal) => {
+        const git = createGit(repoPath, signal);
+        // For root directory, use rev-parse HEAD^{tree}
+        if (subPath === "." || subPath === "") {
+            const result = await git.revparse(["HEAD^{tree}"]);
+            return result.trim();
+        }
+        // For subdirectories, use ls-tree to get the tree object SHA
+        // ls-tree returns: <mode> <type> <sha>\t<path>
+        const result = await git.raw(["ls-tree", "HEAD", subPath]);
+        const trimmed = result.trim();
+        if (!trimmed) {
+            throw new Error(`Path '${subPath}' not found in repository`);
+        }
+        // Parse the output: "040000 tree <sha>\t<path>" or "100644 blob <sha>\t<path>"
+        const parts = trimmed.split(/\s+/);
+        const sha = Option.getOrThrowWith(Array.get(parts, 2), () => new Error(`Unexpected ls-tree output: ${trimmed}`));
+        return sha;
+    },
+    catch: mapGitError("get-tree-sha", `Failed to get tree SHA for '${subPath}'`),
+}).pipe(Effect.withSpan("Git.getTreeSha"));
+//# sourceMappingURL=operations.js.map