@agentxm/extension-model 0.28.4-bootstrap.0

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

@@ -0,0 +1,50 @@
+/**
+ * Pure per-forge source shorthand printing 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.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+/** @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;
+};
+/** @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;
+};
+/** @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;
+};
+/** @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;
+};
+/** @experimental */
+export const printLocalSource = (source) => source.path.startsWith("/") || source.path.startsWith(".") ? source.path : `./${source.path}`;
+//# sourceMappingURL=forge-grammar.js.map

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

@@ -0,0 +1,85 @@
+/**
+ * Input pattern classification for source strings.
+ *
+ * Classifies raw input strings into typed `InputPattern` variants
+ * (URL, SCP, shorthand, file path, etc.) for downstream routing
+ * by `resolveSource`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+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";
+/** A simple name with no `/`, `@`, or URL scheme. */
+type NameInput = {
+    readonly pattern: "name-input";
+    readonly name: string;
+};
+/** A namespaced registry source: `[source-name:]@owner/<plural-type>/name`. */
+type RegistryPatternInput = {
+    readonly pattern: "registry-pattern-input";
+    readonly sourceName: string;
+    readonly type: Option.Option<ExtensionTypePlural>;
+    readonly owner: Handle;
+    readonly name: Option.Option<ExtensionName>;
+    readonly versionRange: Option.Option<VersionRange>;
+};
+/** A valid URL (validated via `Schema.URL`). */
+type UrlInput = {
+    readonly pattern: "url-input";
+    readonly url: URL;
+};
+/** An SCP-style git address: `user@host:path` (e.g. `git@github.com:owner/repo.git`). */
+type GitScpAddress = {
+    readonly pattern: "git-scp-address";
+    readonly user: string;
+    readonly host: string;
+    readonly path: string;
+};
+/** An `owner/repo[/path]` 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>;
+};
+/** A local filesystem path matching `LOCAL_PATH_PATTERN`. */
+type FilePathPattern = {
+    readonly pattern: "file-path-pattern";
+    readonly path: string;
+};
+/** A shorthand prefixed input: `<prefix>:...` where prefix is a known source provider. */
+export type ShorthandInput = {
+    readonly pattern: "shorthand-input";
+    readonly prefix: string;
+    readonly remainingInput: string;
+};
+/** A glob pattern containing `*` wildcards (e.g. `effect-*`). */
+type GlobInput = {
+    readonly pattern: "glob-input";
+    readonly value: string;
+};
+/** An intrinsic workspace package locator. */
+type WorkspacePatternInput = {
+    readonly pattern: "workspace-pattern-input";
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+};
+/** Discriminated union of all input patterns recognized by the parser. */
+export type InputPattern = NameInput | RegistryPatternInput | UrlInput | GitScpAddress | SlashPattern | FilePathPattern | ShorthandInput | GlobInput | WorkspacePatternInput;
+/** Parse result with the classified pattern and original input. */
+export type InputParseResult<T = InputPattern> = {
+    readonly pattern: T;
+    readonly originalInput: string;
+};
+/**
+ * Classify an input string into an InputPattern.
+ *
+ * Pure function — no effects, no trimming. Returns `None` for empty/whitespace-only input.
+ */
+export declare const parseInputPattern: (input: string) => Option.Option<InputParseResult>;
+export {};
+//# sourceMappingURL=parser.d.ts.map

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

@@ -0,0 +1,122 @@
+/**
+ * Input pattern classification for source strings.
+ *
+ * Classifies raw input strings into typed `InputPattern` variants
+ * (URL, SCP, shorthand, file path, etc.) for downstream routing
+ * by `resolveSource`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+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"]);
+/** Simple name: alphanumeric with hyphens, no leading/trailing hyphen. */
+const NAME_PATTERN = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+/**
+ * Classify an input string into an InputPattern.
+ *
+ * Pure function — no effects, no trimming. Returns `None` for empty/whitespace-only input.
+ */
+export const parseInputPattern = (input) => {
+    const wrap = (pattern) => ({ pattern, originalInput: input });
+    // 1. SCP-style git address (user@host:path) — must check before URL
+    const scpMatch = input.includes("://") ? null : input.match(SCP_PATTERN);
+    if (scpMatch && scpMatch[1] && scpMatch[2] && scpMatch[3]) {
+        return Option.some(wrap({
+            pattern: "git-scp-address",
+            user: scpMatch[1],
+            host: scpMatch[2],
+            path: scpMatch[3],
+        }));
+    }
+    // 2. Intrinsic workspace source — must be intercepted before URL parsing,
+    // because URL accepts arbitrary opaque schemes such as `workspace:`.
+    if (input.startsWith("workspace:")) {
+        const parsed = parseFqn(input.slice("workspace:".length));
+        if (Result.isFailure(parsed))
+            return Option.none();
+        return Option.some(wrap({
+            pattern: "workspace-pattern-input",
+            owner: parsed.success.owner,
+            type: parsed.success.type,
+            name: parsed.success.name,
+        }));
+    }
+    // 3. Registry source, including an explicit configured source name. This
+    // must be intercepted before URL parsing because URL accepts arbitrary
+    // opaque schemes such as `agentxm:`.
+    const registry = parseSourceQualifiedRegistrySourcePatternParts(input);
+    if (registry !== undefined) {
+        return Option.some(wrap({
+            pattern: "registry-pattern-input",
+            sourceName: registry.sourceName,
+            type: Option.fromUndefinedOr(registry.type),
+            owner: registry.owner,
+            name: Option.fromUndefinedOr(registry.name),
+            versionRange: Option.fromUndefinedOr(registry.versionRange),
+        }));
+    }
+    // 4. Shorthand prefix (github:..., gitlab:..., etc.) — must check before URL
+    const colonIndex = input.indexOf(":");
+    if (colonIndex > 0 && SHORTHAND_PREFIXES.has(input.slice(0, colonIndex))) {
+        return Option.some(wrap({
+            pattern: "shorthand-input",
+            prefix: input.slice(0, colonIndex),
+            remainingInput: input.slice(colonIndex + 1),
+        }));
+    }
+    // 5. File path — must check before URL (e.g. `C:/path` is a valid URL with scheme `c:`)
+    if (LOCAL_PATH_PATTERN.test(input)) {
+        return Option.some(wrap({ pattern: "file-path-pattern", path: input }));
+    }
+    // 6. URL
+    try {
+        const url = new URL(input);
+        if (url.protocol === "file:") {
+            return Option.some(wrap({ pattern: "file-path-pattern", path: url.pathname }));
+        }
+        return Option.some(wrap({ pattern: "url-input", url }));
+    }
+    catch {
+        // Not a URL
+    }
+    // 7. Slash pattern (`owner/repo` or `owner/repo/path`)
+    if (input.includes("/")) {
+        const segments = input.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) &&
+            segments.slice(2).every((s) => s.length > 0 && s !== "..")) {
+            const remaining = segments.slice(2).join("/");
+            return Option.some(wrap({
+                pattern: "slash-pattern",
+                first,
+                second,
+                third: remaining.length === 0 ? Option.none() : Option.some(remaining),
+            }));
+        }
+        return Option.none();
+    }
+    // 8. Glob pattern (contains `*` wildcard)
+    if (input.includes("*")) {
+        return Option.some(wrap({ pattern: "glob-input", value: input }));
+    }
+    // 9. Simple name (alphanumeric with hyphens, no leading/trailing hyphen)
+    if (NAME_PATTERN.test(input)) {
+        return Option.some(wrap({ pattern: "name-input", name: input }));
+    }
+    return Option.none();
+};
+//# sourceMappingURL=parser.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * Source printer for canonical shorthand strings.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SourceParams } from "./types.js";
+/**
+ * Print source params as their canonical shorthand string.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const printSourceParams: (source: SourceParams) => string;
+//# sourceMappingURL=printer.d.ts.map

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

@@ -0,0 +1,45 @@
+/**
+ * Source printer for canonical shorthand strings.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import { formatFqn } from "../extensions/fqn.js";
+import { printAzureReposSource, printBitbucketSource, printGitHubSource, printGitLabSource, printLocalSource, } from "./forge-grammar.js";
+/**
+ * Print source params as their canonical shorthand string.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const printSourceParams = (source) => {
+    switch (source.type) {
+        case "github":
+            return printGitHubSource(source, source.sourceName ?? ("name" in source ? String(source.name) : "github"));
+        case "gitlab":
+            return printGitLabSource(source, source.sourceName ?? ("name" in source ? String(source.name) : "gitlab"));
+        case "bitbucket":
+            return printBitbucketSource(source, source.sourceName ?? ("name" in source ? String(source.name) : "bitbucket"));
+        case "azurerepos":
+            return printAzureReposSource(source, source.sourceName ?? ("name" in source ? String(source.name) : "azurerepos"));
+        case "local":
+            return printLocalSource(source);
+        case "git": {
+            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");
+        }
+        case "inline":
+            return "inline";
+        case "workspace":
+            return `workspace:${formatFqn({
+                owner: source.owner,
+                type: source.extensionType,
+                name: source.name,
+            })}`;
+    }
+};
+//# sourceMappingURL=printer.js.map

package/dist/src/unstable/sources/source-hash.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Branded string for content source hashes.
+ *
+ * A `SourceHash` is an advisory change-detection marker: the SHA-256 of
+ * canonical content captured at install/enable time. It powers
+ * created/updated/unchanged reporting and drift hints. It is NOT a tamper
+ * seal — installed canonical content is workspace-owned and may be
+ * rewritten by content-preserving tools (formatters, line-ending
+ * normalization) after install, so a stored hash can legitimately go stale.
+ * Consumers must never hard-fail on a mismatch; supply-chain integrity is
+ * enforced separately by verifying registry archive SRI hashes at download
+ * time.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+export declare const SourceHashSchema: Schema.brand<Schema.String, "SourceHash">;
+/**
+ * Branded SourceHash type.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SourceHash = Schema.Schema.Type<typeof SourceHashSchema>;
+//# sourceMappingURL=source-hash.d.ts.map

package/dist/src/unstable/sources/source-hash.js

@@ -0,0 +1,22 @@
+/**
+ * Branded string for content source hashes.
+ *
+ * A `SourceHash` is an advisory change-detection marker: the SHA-256 of
+ * canonical content captured at install/enable time. It powers
+ * created/updated/unchanged reporting and drift hints. It is NOT a tamper
+ * seal — installed canonical content is workspace-owned and may be
+ * rewritten by content-preserving tools (formatters, line-ending
+ * normalization) after install, so a stored hash can legitimately go stale.
+ * Consumers must never hard-fail on a mismatch; supply-chain integrity is
+ * enforced separately by verifying registry archive SRI hashes at download
+ * time.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+export const SourceHashSchema = Schema.String.pipe(Schema.brand("SourceHash")).annotate({
+    description: "Advisory SHA-256 change-detection marker of canonical content at install time. " +
+        "Not a tamper guarantee: installed content is workspace-owned and may be rewritten " +
+        "by content-preserving tools after install.",
+});
+//# sourceMappingURL=source-hash.js.map

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

@@ -0,0 +1,112 @@
+/**
+ * Source provider abstraction for unified extension discovery and fetching.
+ *
+ * Defines the `SourceHostProvider` interface that all source types implement,
+ * along with supporting types for search criteria, discovery results, and errors.
+ *
+ * @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";
+import type { ExtensionRef } from "../extensions/refs/extension-ref.js";
+import type { Source } from "./types.js";
+import type { ReleaseAgeEvaluation, ReleaseAgeEvidence, ReleaseAgeExemption } from "../extensions/release-age.js";
+/**
+ * Search criteria passed to `find` -- independent of source identity.
+ *
+ * - `names`: extension names to match (empty = all)
+ * - `type`: findable extension type filter or `"*"` for all
+ * - `versionRange`: optional version constraint for registry-backed lookups
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface FindOptions {
+    readonly names: ReadonlyArray<string>;
+    readonly type: ExtensionType | "*";
+    /** 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;
+    readonly type: ExtensionType;
+    readonly owner: Handle;
+    readonly versionRange: Option.Option<string>;
+    readonly releaseAgeEvaluation: ReleaseAgeEvaluation;
+    /** Accepted immutable Registry identity that unattended resolution must not move behind. */
+    readonly accepted?: {
+        readonly version: string;
+        readonly publisherBindingId: string;
+    };
+}
+export type NamedRegistryResolution = {
+    readonly kind: "selected";
+    readonly target: string;
+    readonly ref: Extract<ExtensionRef, {
+        readonly refType: "registry";
+    }>;
+    readonly newerHeld?: ReleaseAgeEvidence;
+} | {
+    readonly kind: "exempted";
+    readonly target: string;
+    readonly ref: Extract<ExtensionRef, {
+        readonly refType: "registry";
+    }>;
+    readonly bypassed: ReleaseAgeEvidence;
+    readonly exemption: ReleaseAgeExemption;
+} | {
+    readonly kind: "not_found";
+    readonly target: string;
+} | {
+    readonly kind: "version_unsatisfied";
+    readonly target: string;
+    readonly requestedRange: string;
+} | {
+    readonly kind: "policy_held";
+    readonly target: string;
+    readonly requestedRange?: string;
+    readonly candidate: ReleaseAgeEvidence;
+};
+/**
+ * Materialized extension files ready for installation.
+ *
+ * Returned by `fetch` after files have been prepared.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ExtensionFiles {
+    /** Absolute path to directory containing extension files. */
+    readonly directory: string;
+}
+/**
+ * Source host provider that unifies how all source types are accessed.
+ *
+ * Each source type is implemented as a provider with `match`, `find` and `fetch`
+ * capabilities. The `R` parameter captures Effect requirements for the
+ * provider's operations.
+ *
+ * @typeParam S - The specific `Source` variant this provider handles.
+ * @typeParam R - Effect requirements for provider operations.
+ * @typeParam E - Typed failure channel for provider operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SourceHostProvider<S extends Source = Source, R = never, E = never> {
+    /** Source type discriminator matching `S["type"]`. */
+    readonly type: S["type"];
+    /** Check if a URL belongs to this provider. */
+    readonly match: (url: URL) => Effect.Effect<boolean, E, R>;
+    /** Discover extensions at the given source matching the search criteria. */
+    readonly find: (source: S, options: FindOptions) => Effect.Effect<ReadonlyArray<ExtensionRef>, E, R>;
+    /** Fetch and materialize extension files for a discovered ref. */
+    readonly fetch: (source: S, ref: ExtensionRef) => Effect.Effect<ExtensionFiles, E, R>;
+}
+//# sourceMappingURL=source-host-provider.d.ts.map

package/dist/src/unstable/sources/source-host-provider.js

@@ -0,0 +1,11 @@
+/**
+ * Source provider abstraction for unified extension discovery and fetching.
+ *
+ * Defines the `SourceHostProvider` interface that all source types implement,
+ * along with supporting types for search criteria, discovery results, and errors.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=source-host-provider.js.map