@agentxm/extension-model 0.34.0 → 0.36.0

package/dist/src/unstable/extensions/registry-source.js

@@ -1,9 +1,10 @@
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as SchemaTransformation from "effect/SchemaTransformation";
-import { ExtensionNameSchema, ExtensionTypePluralSchema } from "./common.js";
+import { ExtensionNameSchema, ExtensionTypePluralSchema, splitExtensionReference, } from "./common.js";
 import { HandleSchema } from "./handle.js";
 import { VersionRangeSchema } from "../version-constraints/version-constraints.js";
 const invalidRegistrySourcePattern = (input) => `Expected registry source pattern in @handle, @handle/<plural-type>, or @handle/<plural-type>/<name>@<constraint> form, got: ${input}`;
@@ -44,26 +45,12 @@ export const RegistrySourceRefPartsSchema = Schema.Struct({
 });
 const decodeRegistrySourcePatternParts = Schema.decodeUnknownResult(RegistrySourcePatternPartsSchema);
 const decodeRegistrySourceRefParts = Schema.decodeUnknownResult(RegistrySourceRefPartsSchema);
-const parseNameAndConstraintSegment = (segment) => {
-    const atIndex = segment.indexOf("@");
-    if (atIndex === 0) {
-        return undefined;
-    }
-    if (atIndex === -1) {
-        return { name: segment };
-    }
-    const name = segment.slice(0, atIndex);
-    const versionRange = segment.slice(atIndex + 1);
-    if (name.length === 0 || versionRange.length === 0) {
-        return undefined;
-    }
-    return { name, versionRange };
-};
 export const parseRegistrySourcePatternParts = (input) => {
     if (!input.startsWith("@")) {
         return undefined;
     }
-    const segments = input.split("/");
+    const { name: reference, constraint } = splitExtensionReference(input);
+    const segments = reference.split("/");
     if (segments.length < 1 || segments.length > 3) {
         return undefined;
     }
@@ -83,17 +70,9 @@ export const parseRegistrySourcePatternParts = (input) => {
     }
     else {
         const type = segments[1];
-        const third = segments[2];
-        if (type !== undefined && third !== undefined) {
-            const parsedName = parseNameAndConstraintSegment(third);
-            if (parsedName !== undefined) {
-                candidate = {
-                    owner,
-                    type,
-                    name: parsedName.name,
-                    versionRange: parsedName.versionRange,
-                };
-            }
+        const name = segments[2];
+        if (type !== undefined && name !== undefined) {
+            candidate = { owner, type, name, versionRange: constraint };
         }
     }
     if (candidate === undefined) {
@@ -102,25 +81,31 @@ export const parseRegistrySourcePatternParts = (input) => {
     const result = decodeRegistrySourcePatternParts(candidate);
     return Result.isSuccess(result) ? result.success : undefined;
 };
-/** Parse a Registry locator, assigning unqualified input to the built-in agentxm source. */
+/**
+ * Parse a Registry locator, keeping the configured source name it spells
+ * (`<source>:@owner/...`) and leaving an unqualified locator unbound.
+ */
 export const parseSourceQualifiedRegistrySourcePatternParts = (input) => {
     const unqualified = parseRegistrySourcePatternParts(input);
     if (unqualified !== undefined) {
-        return { ...unqualified, sourceName: "agentxm" };
+        return { ...unqualified, sourceName: Option.none() };
     }
     const separator = input.indexOf(":");
     if (separator <= 0)
         return undefined;
     const sourceName = input.slice(0, separator);
     const qualified = parseRegistrySourcePatternParts(input.slice(separator + 1));
-    return qualified === undefined ? undefined : { ...qualified, sourceName };
+    return qualified === undefined
+        ? undefined
+        : { ...qualified, sourceName: Option.some(sourceName) };
 };
 export const parseRegistrySourceRef = (input) => {
     const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
     if (parsed?.type === undefined || parsed.name === undefined) {
         return undefined;
     }
-    const result = decodeRegistrySourceRefParts(parsed);
+    const { sourceName: _sourceName, ...parts } = parsed;
+    const result = decodeRegistrySourceRefParts(parts);
     return Result.isSuccess(result) ? result.success : undefined;
 };
 export const formatRegistrySourcePatternParts = (value) => {

package/dist/src/unstable/path-types.d.ts

@@ -26,4 +26,10 @@ export declare const makeWorkspaceRelativeSourcePath: (path: Path.Path, workspac
  * prefix is not mistaken for a child.
  */
 export declare const isPathSafe: (path: Path.Path, base: string, target: string) => boolean;
+/** Resolve a child against its base and reject paths that escape it. */
+export declare const safeChildPath: (path: Path.Path, base: string, target: string) => Option.Option<AbsolutePath>;
+/** Relative-path containment, including the parent itself. */
+export declare const isWithinOrEqual: (path: Path.Path, parent: string, child: string) => boolean;
+/** Relative-path containment that excludes the parent itself. */
+export declare const isStrictlyWithin: (path: Path.Path, parent: string, child: string) => boolean;
 //# sourceMappingURL=path-types.d.ts.map

package/dist/src/unstable/path-types.js

@@ -56,4 +56,24 @@ export const isPathSafe = (path, base, target) => {
     const resolvedTarget = path.resolve(target);
     return resolvedTarget === resolvedBase || resolvedTarget.startsWith(resolvedBase + path.sep);
 };
+/** Resolve a child against its base and reject paths that escape it. */
+export const safeChildPath = (path, base, target) => {
+    const resolvedBase = path.resolve(base);
+    const resolvedTarget = path.isAbsolute(target)
+        ? path.resolve(target)
+        : path.resolve(resolvedBase, target);
+    return isPathSafe(path, resolvedBase, resolvedTarget)
+        ? Option.some(makeAbsolutePath(path, resolvedTarget))
+        : Option.none();
+};
+/** Relative-path containment, including the parent itself. */
+export const isWithinOrEqual = (path, parent, child) => {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+/** Relative-path containment that excludes the parent itself. */
+export const isStrictlyWithin = (path, parent, child) => {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
 //# sourceMappingURL=path-types.js.map

package/dist/src/unstable/sources/forge-grammar.d.ts

@@ -1,22 +1,58 @@
 /**
- * Pure per-forge source shorthand printing grammar.
+ * Forge coordinate, clone URL, and browser URL grammar.
  *
- * Each printer formats source params as the forge's canonical shorthand
- * string. Probing and acquisition stay with the source-resolution providers;
- * only the string grammar lives here.
+ * Probing and acquisition stay with source resolution; the model owns the
+ * strings and URLs that identify each forge repository.
  *
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-import type { AzureReposSourceParams, BitbucketSourceParams, GitHubSourceParams, GitLabSourceParams, LocalSourceParams } from "./types.js";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
 /** @experimental */
-export declare const printGitHubSource: (source: GitHubSourceParams, sourceName?: string) => string;
+export declare const FORGE_PREFIXES: readonly ["github", "gitlab", "bitbucket", "azurerepos"];
 /** @experimental */
-export declare const printGitLabSource: (source: GitLabSourceParams, sourceName?: string) => string;
+export type ForgePrefix = (typeof FORGE_PREFIXES)[number];
 /** @experimental */
-export declare const printBitbucketSource: (source: BitbucketSourceParams, sourceName?: string) => string;
+export declare const isForgePrefix: (value: string) => value is ForgePrefix;
 /** @experimental */
-export declare const printAzureReposSource: (source: AzureReposSourceParams, sourceName?: string) => string;
+export interface ForgeCoordinate {
+    readonly forge: ForgePrefix;
+    readonly repository: string;
+    readonly ref: Option.Option<string>;
+    readonly subPath: Option.Option<string>;
+}
+interface BrowserPath {
+    readonly repository: string;
+    readonly ref?: string;
+    readonly subPath?: string;
+}
 /** @experimental */
-export declare const printLocalSource: (source: LocalSourceParams) => string;
+export interface Forge {
+    readonly prefix: ForgePrefix;
+    readonly hostname: string;
+    readonly repositorySegments: (count: number) => boolean;
+    readonly cloneUrl: (repository: string) => URL;
+    readonly repositoryFromCloneUrl: (pathname: string) => string | undefined;
+    readonly parseBrowserPath: (pathname: string) => BrowserPath | undefined;
+}
+/** @experimental */
+export declare const FORGES: Record<ForgePrefix, Forge>;
+/** @experimental */
+export declare const forgeForHostname: (hostname: string) => Forge | undefined;
+/** @experimental */
+export declare const parseForgeCoordinate: (forge: ForgePrefix, body: string) => Result.Result<ForgeCoordinate, {
+    readonly reason: string;
+}>;
+/** @experimental */
+export declare const printForgeCoordinateBody: (coordinate: ForgeCoordinate) => string;
+/** @experimental */
+export declare const printForgeCoordinate: (coordinate: ForgeCoordinate) => string;
+/** @experimental */
+export declare const forgeCloneUrl: (coordinate: ForgeCoordinate) => URL;
+/** @experimental */
+export declare const forgeCoordinateFromGitUrl: (url: URL, ref: Option.Option<string>, subPath: Option.Option<string>) => Option.Option<ForgeCoordinate>;
+/** @experimental */
+export declare const parseForgeBrowserUrl: (url: URL) => Option.Option<ForgeCoordinate>;
+export {};
 //# sourceMappingURL=forge-grammar.d.ts.map

package/dist/src/unstable/sources/forge-grammar.js

@@ -1,50 +1,170 @@
 /**
- * Pure per-forge source shorthand printing grammar.
+ * Forge coordinate, clone URL, and browser URL grammar.
  *
- * Each printer formats source params as the forge's canonical shorthand
- * string. Probing and acquisition stay with the source-resolution providers;
- * only the string grammar lives here.
+ * Probing and acquisition stay with source resolution; the model owns the
+ * strings and URLs that identify each forge repository.
  *
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
 import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { SourceNamespaceSchema, SourceRefSchema, SourceSubPathSchema } from "./types.js";
 /** @experimental */
-export const printGitHubSource = (source, sourceName = source.sourceName ?? "github") => {
-    let s = `${sourceName}:${source.owner}/${source.repo}`;
-    if (Option.isSome(source.subPath))
-        s += `//${source.subPath.value}`;
-    if (Option.isSome(source.ref))
-        s += `@${source.ref.value}`;
-    return s;
+export const FORGE_PREFIXES = ["github", "gitlab", "bitbucket", "azurerepos"];
+/** @experimental */
+export const isForgePrefix = (value) => FORGE_PREFIXES.some((prefix) => prefix === value);
+const segments = (pathname) => pathname.split("/").filter((segment) => segment.length > 0);
+const withoutGit = (name) => (name.endsWith(".git") ? name.slice(0, -4) : name);
+const hostedRepositoryFromCloneUrl = (pathname) => {
+    const parts = segments(pathname);
+    const last = parts.at(-1);
+    return last === undefined || parts.length < 2
+        ? undefined
+        : [...parts.slice(0, -1), withoutGit(last)].join("/");
+};
+const hostedBrowserPath = (pathname, marker) => {
+    const pattern = marker === "tree"
+        ? /^\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/tree\/([^/]+)(?:\/(.+))?)?$/u
+        : /^\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/src\/([^/]+)(?:\/(.+))?)?$/u;
+    const match = pattern.exec(pathname);
+    if (match?.[1] === undefined || match[2] === undefined)
+        return undefined;
+    return {
+        repository: `${match[1]}/${match[2]}`,
+        ...(match[3] === undefined ? {} : { ref: match[3] }),
+        ...(match[4] === undefined ? {} : { subPath: match[4] }),
+    };
+};
+const gitlabBrowserPath = (pathname) => {
+    const marker = "/-/tree/";
+    const markerIndex = pathname.indexOf(marker);
+    const repositoryParts = segments(markerIndex < 0 ? pathname : pathname.slice(0, markerIndex));
+    const last = repositoryParts.at(-1);
+    if (last === undefined || repositoryParts.length < 2)
+        return undefined;
+    const treePath = markerIndex < 0 ? [] : pathname.slice(markerIndex + marker.length).split("/");
+    const subPath = treePath.slice(1).join("/");
+    return {
+        repository: [...repositoryParts.slice(0, -1), withoutGit(last)].join("/"),
+        ...(treePath[0] === undefined ? {} : { ref: treePath[0] }),
+        ...(subPath.length === 0 ? {} : { subPath }),
+    };
+};
+const azureRepositoryFromCloneUrl = (pathname) => {
+    const parts = segments(pathname);
+    return parts.length === 4 && parts[2] === "_git"
+        ? `${parts[0]}/${parts[1]}/${withoutGit(parts[3] ?? "")}`
+        : undefined;
+};
+const azureBrowserPath = (pathname) => {
+    const match = /^\/([^/]+)\/([^/]+)\/_git\/([^/]+?)(?:\.git)?$/u.exec(pathname);
+    return match?.[1] === undefined || match[2] === undefined || match[3] === undefined
+        ? undefined
+        : { repository: `${match[1]}/${match[2]}/${match[3]}` };
+};
+const hostedForge = (prefix, hostname, parseBrowserPath) => ({
+    prefix,
+    hostname,
+    repositorySegments: (count) => count >= 2,
+    cloneUrl: (repository) => new URL(`https://${hostname}/${repository}.git`),
+    repositoryFromCloneUrl: hostedRepositoryFromCloneUrl,
+    parseBrowserPath,
+});
+/** @experimental */
+export const FORGES = {
+    github: hostedForge("github", "github.com", (pathname) => hostedBrowserPath(pathname, "tree")),
+    gitlab: hostedForge("gitlab", "gitlab.com", gitlabBrowserPath),
+    bitbucket: hostedForge("bitbucket", "bitbucket.org", (pathname) => hostedBrowserPath(pathname, "src")),
+    azurerepos: {
+        prefix: "azurerepos",
+        hostname: "dev.azure.com",
+        repositorySegments: (count) => count === 3,
+        cloneUrl: (repository) => {
+            const [organization, project, repo] = repository.split("/");
+            return new URL(`https://dev.azure.com/${organization}/${project}/_git/${repo}`);
+        },
+        repositoryFromCloneUrl: azureRepositoryFromCloneUrl,
+        parseBrowserPath: azureBrowserPath,
+    },
+};
+/** @experimental */
+export const forgeForHostname = (hostname) => Object.values(FORGES).find((forge) => forge.hostname === hostname);
+const decodeNamespace = Schema.decodeUnknownResult(SourceNamespaceSchema);
+const decodeSubPath = Schema.decodeUnknownResult(SourceSubPathSchema);
+const decodeRef = Schema.decodeUnknownResult(SourceRefSchema);
+const validCoordinate = (coordinate) => FORGES[coordinate.forge].repositorySegments(coordinate.repository.split("/").length) &&
+    Result.isSuccess(decodeNamespace(coordinate.repository)) &&
+    (Option.isNone(coordinate.subPath) ||
+        Result.isSuccess(decodeSubPath(coordinate.subPath.value))) &&
+    (Option.isNone(coordinate.ref) || Result.isSuccess(decodeRef(coordinate.ref.value)));
+const splitRef = (input) => {
+    const refIndex = input.lastIndexOf("@");
+    if (refIndex <= 0)
+        return { coordinate: input };
+    const ref = input.slice(refIndex + 1);
+    const subPathMarker = input.indexOf("//");
+    const isAtPathSegment = subPathMarker !== -1 &&
+        refIndex > subPathMarker + 1 &&
+        input[refIndex - 1] === "/" &&
+        ref.includes("/");
+    return isAtPathSegment ? { coordinate: input } : { coordinate: input.slice(0, refIndex), ref };
 };
 /** @experimental */
-export const printGitLabSource = (source, sourceName = source.sourceName ?? "gitlab") => {
-    let s = `${sourceName}:${source.owner}/${source.repo}`;
-    if (Option.isSome(source.subPath))
-        s += `//${source.subPath.value}`;
-    if (Option.isSome(source.ref))
-        s += `@${source.ref.value}`;
-    return s;
+export const parseForgeCoordinate = (forge, body) => {
+    const { coordinate, ref } = splitRef(body);
+    const marker = coordinate.indexOf("//");
+    const repository = marker < 0 ? coordinate : coordinate.slice(0, marker);
+    const subPath = marker < 0 ? undefined : coordinate.slice(marker + 2);
+    const parsed = {
+        forge,
+        repository,
+        ref: Option.fromUndefinedOr(ref),
+        subPath: Option.fromUndefinedOr(subPath),
+    };
+    return validCoordinate(parsed)
+        ? Result.succeed(parsed)
+        : Result.fail({ reason: `Expected valid ${forge} repository[//subpath][@ref]` });
 };
 /** @experimental */
-export const printBitbucketSource = (source, sourceName = source.sourceName ?? "bitbucket") => {
-    let s = `${sourceName}:${source.owner}/${source.repo}`;
-    if (Option.isSome(source.subPath))
-        s += `//${source.subPath.value}`;
-    if (Option.isSome(source.ref))
-        s += `@${source.ref.value}`;
-    return s;
+export const printForgeCoordinateBody = (coordinate) => {
+    let body = coordinate.repository;
+    if (Option.isSome(coordinate.subPath))
+        body += `//${coordinate.subPath.value}`;
+    if (Option.isSome(coordinate.ref))
+        body += `@${coordinate.ref.value}`;
+    return body;
 };
 /** @experimental */
-export const printAzureReposSource = (source, sourceName = source.sourceName ?? "azurerepos") => {
-    let s = `${sourceName}:${source.organization}/${source.project}/${source.repo}`;
-    if (Option.isSome(source.subPath))
-        s += `//${source.subPath.value}`;
-    if (Option.isSome(source.ref))
-        s += `@${source.ref.value}`;
-    return s;
+export const printForgeCoordinate = (coordinate) => `${coordinate.forge}:${printForgeCoordinateBody(coordinate)}`;
+/** @experimental */
+export const forgeCloneUrl = (coordinate) => FORGES[coordinate.forge].cloneUrl(coordinate.repository);
+/** @experimental */
+export const forgeCoordinateFromGitUrl = (url, ref, subPath) => {
+    const forge = forgeForHostname(url.hostname);
+    if (forge === undefined)
+        return Option.none();
+    const repository = forge.repositoryFromCloneUrl(url.pathname);
+    if (repository === undefined)
+        return Option.none();
+    const coordinate = { forge: forge.prefix, repository, ref, subPath };
+    return validCoordinate(coordinate) ? Option.some(coordinate) : Option.none();
 };
 /** @experimental */
-export const printLocalSource = (source) => source.path.startsWith("/") || source.path.startsWith(".") ? source.path : `./${source.path}`;
+export const parseForgeBrowserUrl = (url) => {
+    const forge = forgeForHostname(url.hostname);
+    if (forge === undefined)
+        return Option.none();
+    const parsed = forge.parseBrowserPath(url.pathname);
+    if (parsed === undefined)
+        return Option.none();
+    const coordinate = {
+        forge: forge.prefix,
+        repository: parsed.repository,
+        ref: Option.fromUndefinedOr(parsed.ref),
+        subPath: Option.fromUndefinedOr(parsed.subPath),
+    };
+    return validCoordinate(coordinate) ? Option.some(coordinate) : Option.none();
+};
 //# sourceMappingURL=forge-grammar.js.map

package/dist/src/unstable/sources/parser.d.ts

@@ -9,6 +9,7 @@
  * @packageDocumentation
  */
 import * as Option from "effect/Option";
+import { type ForgeCoordinate, type ForgePrefix } from "./forge-grammar.js";
 import type { VersionRange } from "../version-constraints/version-constraints.js";
 import type { ExtensionName, ExtensionType, ExtensionTypePlural } from "../extensions/common.js";
 import type { Handle } from "../extensions/handle.js";
@@ -17,10 +18,14 @@ type NameInput = {
     readonly pattern: "name-input";
     readonly name: string;
 };
-/** A namespaced registry source: `[source-name:]@owner/<plural-type>/name`. */
+/**
+ * A namespaced registry source: `[source-name:]@owner/<plural-type>/name`.
+ * `sourceName` is the configured source the input spells; an unqualified
+ * input leaves it unbound for the workspace to assign.
+ */
 type RegistryPatternInput = {
     readonly pattern: "registry-pattern-input";
-    readonly sourceName: string;
+    readonly sourceName: Option.Option<string>;
     readonly type: Option.Option<ExtensionTypePlural>;
     readonly owner: Handle;
     readonly name: Option.Option<ExtensionName>;
@@ -41,10 +46,7 @@ type GitScpAddress = {
 /** An `owner/repo[//path][@ref]` style pattern containing `/` (not a URL or file path). */
 type SlashPattern = {
     readonly pattern: "slash-pattern";
-    readonly first: string;
-    readonly second: string;
-    readonly third: Option.Option<string>;
-    readonly ref: Option.Option<string>;
+    readonly coordinate: ForgeCoordinate;
 };
 /** A local filesystem path matching `LOCAL_PATH_PATTERN`. */
 type FilePathPattern = {
@@ -54,7 +56,7 @@ type FilePathPattern = {
 /** A shorthand prefixed input: `<prefix>:...` where prefix is a known source provider. */
 export type ShorthandInput = {
     readonly pattern: "shorthand-input";
-    readonly prefix: string;
+    readonly prefix: ForgePrefix;
     readonly remainingInput: string;
 };
 /** A glob pattern containing `*` wildcards (e.g. `effect-*`). */

package/dist/src/unstable/sources/parser.js

@@ -10,14 +10,13 @@
  */
 import * as Option from "effect/Option";
 import * as Result from "effect/Result";
+import { isForgePrefix, parseForgeCoordinate, } from "./forge-grammar.js";
 import { parseFqn } from "../extensions/fqn.js";
 import { parseSourceQualifiedRegistrySourcePatternParts } from "../extensions/registry-source.js";
 /** Matches: ./path, ../path, /path, ~/path, ~\path, or Windows paths like C:\path */
 const LOCAL_PATH_PATTERN = /^(?:\.\.?\/|\/|~\/|~\\|[A-Za-z]:[\\/])/;
 /** SCP-style: `user@host:path` — no `://` scheme. */
 const SCP_PATTERN = /^([^@]+)@([^:]+):(.+)$/;
-/** Known shorthand prefixes. */
-const SHORTHAND_PREFIXES = new Set(["github", "gitlab", "bitbucket", "azurerepos"]);
 /** Simple name: alphanumeric with hyphens, no leading/trailing hyphen. */
 const NAME_PATTERN = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
 /**
@@ -66,10 +65,11 @@ export const parseInputPattern = (input) => {
     }
     // 4. Shorthand prefix (github:..., gitlab:..., etc.) — must check before URL
     const colonIndex = input.indexOf(":");
-    if (colonIndex > 0 && SHORTHAND_PREFIXES.has(input.slice(0, colonIndex))) {
+    const prefix = input.slice(0, colonIndex);
+    if (colonIndex > 0 && isForgePrefix(prefix)) {
         return Option.some(wrap({
             pattern: "shorthand-input",
-            prefix: input.slice(0, colonIndex),
+            prefix,
             remainingInput: input.slice(colonIndex + 1),
         }));
     }
@@ -90,34 +90,17 @@ export const parseInputPattern = (input) => {
     }
     // 7. Slash pattern (`owner/repo[//path][@ref]`)
     if (input.includes("/")) {
-        const refIndex = input.lastIndexOf("@");
-        const hasRef = refIndex > 0 && refIndex < input.length - 1;
-        const coordinate = hasRef ? input.slice(0, refIndex) : input;
-        const ref = hasRef ? input.slice(refIndex + 1) : undefined;
-        const subPathIndex = coordinate.indexOf("//");
-        const repositoryCoordinate = subPathIndex < 0 ? coordinate : coordinate.slice(0, subPathIndex);
-        const subPath = subPathIndex < 0 ? undefined : coordinate.slice(subPathIndex + 2);
-        const segments = repositoryCoordinate.split("/");
-        const first = segments.at(0);
-        const second = segments.at(1);
-        if (first !== undefined &&
-            second !== undefined &&
-            segments.length === 2 &&
-            NAME_PATTERN.test(first) &&
-            NAME_PATTERN.test(second) &&
-            (ref === undefined || (ref.length > 0 && !ref.includes("/"))) &&
-            (subPath === undefined ||
-                (subPath.length > 0 &&
-                    subPath.split("/").every((segment) => segment.length > 0 && segment !== "..")))) {
-            return Option.some(wrap({
-                pattern: "slash-pattern",
-                first,
-                second,
-                third: Option.fromUndefinedOr(subPath),
-                ref: Option.fromUndefinedOr(ref),
-            }));
+        const parsed = parseForgeCoordinate("github", input);
+        if (Result.isFailure(parsed))
+            return Option.none();
+        const coordinate = parsed.success;
+        const segments = coordinate.repository.split("/");
+        if (segments.length !== 2 ||
+            !segments.every((segment) => NAME_PATTERN.test(segment)) ||
+            Option.exists(coordinate.ref, (ref) => ref.includes("/"))) {
+            return Option.none();
         }
-        return Option.none();
+        return Option.some(wrap({ pattern: "slash-pattern", coordinate }));
     }
     // 8. Glob pattern (contains `*` wildcard)
     if (input.includes("*")) {

package/dist/src/unstable/sources/printer.js

@@ -6,7 +6,8 @@
  */
 import * as Option from "effect/Option";
 import { formatFqn } from "../extensions/fqn.js";
-import { printLocalSource } from "./forge-grammar.js";
+import { forgeCoordinateFromGitUrl, printForgeCoordinate } from "./forge-grammar.js";
+const printLocalSource = (source) => source.path.startsWith("/") || source.path.startsWith(".") ? source.path : `./${source.path}`;
 /**
  * Print source params as their canonical shorthand string.
  *
@@ -17,40 +18,14 @@ export const printSourceParams = (source) => {
         case "local":
             return printLocalSource(source);
         case "git": {
-            const repositorySegments = source.url.pathname
-                .split("/")
-                .filter((segment) => segment.length > 0);
-            if (source.url.hostname === "dev.azure.com" &&
-                repositorySegments.length === 4 &&
-                repositorySegments[2] === "_git") {
-                let shorthand = `azurerepos:${repositorySegments[0]}/${repositorySegments[1]}/${repositorySegments[3]}`;
-                if (Option.isSome(source.subPath))
-                    shorthand += `//${source.subPath.value}`;
-                if (Option.isSome(source.ref))
-                    shorthand += `@${source.ref.value}`;
-                return shorthand;
-            }
-            const lastSegment = repositorySegments.at(-1);
-            const repo = lastSegment?.endsWith(".git") ? lastSegment.slice(0, -4) : lastSegment;
-            const sourcePrefix = source.url.hostname === "github.com"
-                ? "github"
-                : source.url.hostname === "gitlab.com"
-                    ? "gitlab"
-                    : source.url.hostname === "bitbucket.org"
-                        ? "bitbucket"
-                        : undefined;
-            if (sourcePrefix !== undefined && repo !== undefined && repositorySegments.length >= 2) {
-                const owner = repositorySegments.slice(0, -1).join("/");
-                let shorthand = `${sourcePrefix}:${owner}/${repo}`;
-                if (Option.isSome(source.subPath))
-                    shorthand += `//${source.subPath.value}`;
-                if (Option.isSome(source.ref))
-                    shorthand += `@${source.ref.value}`;
-                return shorthand;
-            }
-            const url = new URL(source.url.href);
-            url.hash = Option.getOrElse(source.ref, () => "");
-            return url.href;
+            return Option.match(forgeCoordinateFromGitUrl(source.url, source.ref, source.subPath), {
+                onSome: printForgeCoordinate,
+                onNone: () => {
+                    const url = new URL(source.url.href);
+                    url.hash = Option.getOrElse(source.ref, () => "");
+                    return url.href;
+                },
+            });
         }
         case "registry": {
             return source.sourceName ?? ("name" in source ? String(source.name) : "agentxm");

package/dist/src/unstable/sources/source-host-provider.d.ts

@@ -7,7 +7,6 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-import type * as Duration from "effect/Duration";
 import type * as Effect from "effect/Effect";
 import type * as Option from "effect/Option";
 import type { ExtensionType, Handle } from "../extensions/index.js";
@@ -29,11 +28,6 @@ export interface FindOptions {
     /** Registry owner filter (e.g. "@acme"). */
     readonly owner: Option.Option<Handle>;
     readonly versionRange: Option.Option<string>;
-    /**
-     * Optional minimum age a registry release must have before it is selectable.
-     * Omitted for explicit attended installs.
-     */
-    readonly minimumReleaseAge?: Option.Option<Duration.Duration>;
 }
 export interface NamedRegistryFindOptions {
     readonly name: string;
@@ -54,6 +48,8 @@ export type NamedRegistryResolution = {
         readonly refType: "registry";
     }>;
     readonly newerHeld?: ReleaseAgeEvidence;
+    /** The newest release a range could select, whatever range was requested. */
+    readonly newestVisible?: string;
 } | {
     readonly kind: "exempted";
     readonly target: string;
@@ -62,6 +58,7 @@ export type NamedRegistryResolution = {
     }>;
     readonly bypassed: ReleaseAgeEvidence;
     readonly exemption: ReleaseAgeExemption;
+    readonly newestVisible?: string;
 } | {
     readonly kind: "not_found";
     readonly target: string;
@@ -87,11 +84,18 @@ export type NamedRegistryVersionDecision = {
     readonly kind: "selected";
     readonly version: string;
     readonly newerHeld?: ReleaseAgeEvidence;
+    /**
+     * The newest release the index lists that a range could select — not
+     * yanked, whatever range was requested — so a caller can say what its
+     * constraint held the selection below.
+     */
+    readonly newestVisible?: string;
 } | {
     readonly kind: "exempted";
     readonly version: string;
     readonly bypassed: ReleaseAgeEvidence;
     readonly exemption: ReleaseAgeExemption;
+    readonly newestVisible?: string;
 } | {
     readonly kind: "not_found";
 } | {