@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/hex.js

@@ -0,0 +1,186 @@
+/**
+ * Hex package detector and reader for package-compatibility discovery.
+ *
+ * Supports both Elixir (mix.exs) and Gleam (gleam.toml) projects.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { PackageURL } from "packageurl-js";
+import { parseTomlStringEntries, readTomlSection } from "@agentxm/extension-workspace";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const hexType = Schema.decodeUnknownSync(PackageTypeSchema)("hex");
+/**
+ * Returns true if the specifier is an exact semver version (no range operators).
+ */
+const isExactVersion = (specifier) => /^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9._+-]*)?$/.test(specifier);
+/**
+ * Regex to detect :path or :git options which indicate non-registry deps.
+ */
+const PATH_OR_GIT_REGEX = /(?:path|git):\s*"/;
+/**
+ * Parse mix.exs content and extract dependency tuples from the deps function.
+ */
+const parseMixExs = (content, source) => {
+    const results = [];
+    // Extract the full dep tuples to check for path/git options
+    const fullTuples = new Map();
+    let fullMatch;
+    const fullRegex = /\{:(\w+)[^}]*\}/g;
+    while ((fullMatch = fullRegex.exec(content)) !== null) {
+        const name = fullMatch[1];
+        if (name !== undefined) {
+            fullTuples.set(name, fullMatch[0]);
+        }
+    }
+    // Now extract deps with version strings
+    let match;
+    const depRegex = /\{:(\w+),\s*"([^"]*)"/g;
+    while ((match = depRegex.exec(content)) !== null) {
+        const name = match[1];
+        const versionSpec = match[2];
+        if (name === undefined || versionSpec === undefined)
+            continue;
+        // Check if this dep has path: or git: options (skip if so)
+        const fullTuple = fullTuples.get(name);
+        if (fullTuple !== undefined && PATH_OR_GIT_REGEX.test(fullTuple))
+            continue;
+        const version = isExactVersion(versionSpec) ? versionSpec : undefined;
+        const purl = new PackageURL("hex", null, name, version ?? null, null, null);
+        const purlParts = decodePurl(purl.toString());
+        results.push({ purl: purlParts, type: hexType, source });
+    }
+    return results;
+};
+/**
+ * Parse a TOML-like section for dependencies.
+ * Handles simple `name = "version"` entries within a section block.
+ */
+const parseTomlDeps = (content, sectionName, source) => {
+    const results = [];
+    const sectionContent = readTomlSection(content, sectionName);
+    if (sectionContent === undefined)
+        return [];
+    for (const { key: name, value: versionSpec } of parseTomlStringEntries(sectionContent, "\\w+")) {
+        const version = isExactVersion(versionSpec) ? versionSpec : undefined;
+        const purl = new PackageURL("hex", null, name, version ?? null, null, null);
+        const purlParts = decodePurl(purl.toString());
+        results.push({ purl: purlParts, type: hexType, source });
+    }
+    return results;
+};
+/**
+ * Parse gleam.toml content and extract dependencies from [dependencies] and [dev-dependencies].
+ */
+const parseGleamToml = (content, source) => {
+    const deps = parseTomlDeps(content, "dependencies", source);
+    const devDeps = parseTomlDeps(content, "dev-dependencies", source);
+    return [...deps, ...devDeps];
+};
+/**
+ * Parse Erlang term format hex_metadata.config to extract the extra.axm field.
+ * This is a simplified parser that extracts the axm JSON from the extra field.
+ *
+ * Erlang binary strings use `<<"...">>` delimiters. The axm value is a JSON
+ * string embedded as an Erlang binary, potentially with escaped quotes inside.
+ */
+const parseHexMetadataExtra = (content) => {
+    // Look for <<"axm">> key followed by its value in <<"...">> format
+    // The value may contain escaped quotes within the Erlang binary string
+    const axmMatch = /<<"axm">>,\s*<<"((?:[^"\\]|\\.)*)">>/m.exec(content);
+    if (axmMatch?.[1] !== undefined) {
+        // Unescape any escaped quotes from the Erlang binary string encoding
+        const jsonStr = axmMatch[1].replace(/\\"/g, '"');
+        try {
+            const parsed = JSON.parse(jsonStr);
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+/**
+ * Hex package detector.
+ *
+ * Scans `mix.exs` and `gleam.toml` in the project directory and extracts
+ * dependencies from Elixir dependency tuples and Gleam TOML sections.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const hexDetector = {
+    type: hexType,
+    detect: Effect.fn("detect.hex")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const results = [];
+        // Try mix.exs (Elixir)
+        const mixPath = path.join(projectDir, "mix.exs");
+        const mixContent = yield* readFileOptional(mixPath);
+        if (Option.isSome(mixContent)) {
+            const mixDeps = parseMixExs(mixContent.value, mixPath);
+            results.push(...mixDeps);
+        }
+        // Try gleam.toml (Gleam)
+        const gleamPath = path.join(projectDir, "gleam.toml");
+        const gleamContent = yield* readFileOptional(gleamPath);
+        if (Option.isSome(gleamContent)) {
+            const gleamDeps = parseGleamToml(gleamContent.value, gleamPath);
+            results.push(...gleamDeps);
+        }
+        return results;
+    }, Effect.annotateLogs({ detector: "hex" }), Effect.withSpan("detect.hex")),
+};
+/**
+ * Hex package reader.
+ *
+ * Reads `deps/<package-name>/axm.json` as the primary source, falling back to
+ * parsing `hex_metadata.config` for each detected Hex package.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const hexReader = {
+    type: hexType,
+    read: Effect.fn("read.hex")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Derive project directory from the source manifest path
+        const projectDir = path.dirname(pkg.source);
+        const pkgName = pkg.purl.name;
+        // Try axm.json sidecar first
+        const axmJsonPath = path.join(projectDir, "deps", pkgName, "axm.json");
+        const axmContent = yield* readFileOptional(axmJsonPath);
+        if (Option.isSome(axmContent)) {
+            const parsed = yield* parseJsonOptional(axmContent.value, `${pkgName}/axm.json`);
+            if (Option.isSome(parsed)) {
+                const metaResult = decodeAxmMeta(parsed.value);
+                if (Result.isFailure(metaResult)) {
+                    yield* Effect.logWarning(`Invalid axm metadata in ${pkgName}/axm.json: schema validation failed`);
+                    return Option.none();
+                }
+                return Option.some(metaResult.success.extensions);
+            }
+        }
+        // Fall back to hex_metadata.config
+        const hexMetaPath = path.join(projectDir, "deps", pkgName, "hex_metadata.config");
+        const hexMetaContent = yield* readFileOptional(hexMetaPath);
+        if (Option.isSome(hexMetaContent)) {
+            const axmData = parseHexMetadataExtra(hexMetaContent.value);
+            if (axmData !== undefined) {
+                const metaResult = decodeAxmMeta(axmData);
+                if (Result.isFailure(metaResult)) {
+                    yield* Effect.logWarning(`Invalid axm metadata in ${pkgName}/hex_metadata.config: schema validation failed`);
+                    return Option.none();
+                }
+                return Option.some(metaResult.success.extensions);
+            }
+        }
+        return Option.none();
+    }, Effect.annotateLogs({ reader: "hex" }), Effect.withSpan("read.hex")),
+};
+//# sourceMappingURL=hex.js.map

package/dist/src/packaging/huggingface.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hugging Face (ML models) package reader for package-compatibility discovery.
+ *
+ * Reads YAML frontmatter from model cards in the Hugging Face cache directory.
+ * No detector is provided for this ecosystem.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageReader } from "./types.js";
+/**
+ * Hugging Face model reader.
+ *
+ * Reads YAML frontmatter from model cards in
+ * `~/.cache/huggingface/hub/models--<id>/` and extracts axm metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const huggingfaceReader: PackageReader;
+//# sourceMappingURL=huggingface.d.ts.map

package/dist/src/packaging/huggingface.js

@@ -0,0 +1,112 @@
+/**
+ * Hugging Face (ML models) package reader for package-compatibility discovery.
+ *
+ * Reads YAML frontmatter from model cards in the Hugging Face cache directory.
+ * No detector is provided for this ecosystem.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Intentional escape hatch: node:os homedir() has no @effect/platform equivalent.
+import * as os from "node:os";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import YAML from "yaml";
+import { readEnv } from "../internal/environment.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, readFileOptional } from "./reader-io.js";
+const huggingfaceType = Schema.decodeUnknownSync(PackageTypeSchema)("huggingface");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract YAML frontmatter from a markdown file.
+ * Frontmatter is delimited by `---` at the start and end.
+ */
+const extractYamlFrontmatter = (content) => {
+    if (!content.startsWith("---"))
+        return undefined;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx === -1)
+        return undefined;
+    return content.slice(3, endIdx).trim();
+};
+/** Schema for extracting the axm field from model card frontmatter. */
+const ModelCardAxmSchema = Schema.Struct({
+    axm: Schema.optional(Schema.Unknown),
+});
+const decodeModelCardAxm = Schema.decodeUnknownResult(ModelCardAxmSchema);
+/**
+ * Resolve the Hugging Face cache directory.
+ * Checks HF_HOME, HUGGINGFACE_HUB_CACHE, then defaults to ~/.cache/huggingface/hub.
+ */
+const resolveHfCache = () => Effect.sync(() => readEnv("HUGGINGFACE_HUB_CACHE") ??
+    (readEnv("HF_HOME") ? `${readEnv("HF_HOME")}/hub` : `${os.homedir()}/.cache/huggingface/hub`));
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/**
+ * Hugging Face model reader.
+ *
+ * Reads YAML frontmatter from model cards in
+ * `~/.cache/huggingface/hub/models--<id>/` and extracts axm metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const huggingfaceReader = {
+    type: huggingfaceType,
+    read: Effect.fn("read.huggingface")(function* (pkg) {
+        const path = yield* Path.Path;
+        const hfCache = yield* resolveHfCache();
+        // Model IDs use -- as separator in the cache directory
+        // e.g., models--org--model-name for org/model-name
+        const namespace = pkg.purl.namespace;
+        const modelDirName = namespace
+            ? `models--${namespace}--${pkg.purl.name}`
+            : `models--${pkg.purl.name}`;
+        // Look for README.md in the snapshot directory
+        const modelDir = path.join(hfCache, modelDirName);
+        // Find the latest snapshot by reading the refs/main file
+        const refsMainPath = path.join(modelDir, "refs", "main");
+        const refContent = yield* readFileOptional(refsMainPath);
+        if (Option.isNone(refContent))
+            return Option.none();
+        const snapshotHash = refContent.value.trim();
+        if (snapshotHash === "")
+            return Option.none();
+        const readmePath = path.join(modelDir, "snapshots", snapshotHash, "README.md");
+        const readmeContent = yield* readFileOptional(readmePath);
+        if (Option.isNone(readmeContent))
+            return Option.none();
+        // Extract YAML frontmatter
+        const frontmatter = extractYamlFrontmatter(readmeContent.value);
+        if (frontmatter === undefined)
+            return Option.none();
+        // Parse YAML frontmatter
+        const parsed = yield* Effect.try({
+            try: () => YAML.parse(frontmatter),
+            catch: () => ({ _tag: "YamlParseError" }),
+        }).pipe(Effect.option);
+        if (Option.isNone(parsed)) {
+            yield* Effect.logWarning(`Malformed YAML frontmatter in ${pkg.purl.name} model card, skipping`);
+            return Option.none();
+        }
+        // Extract axm metadata
+        const containerResult = decodeModelCardAxm(parsed.value);
+        if (Result.isFailure(containerResult))
+            return Option.none();
+        const axmRaw = containerResult.success.axm;
+        if (axmRaw === undefined)
+            return Option.none();
+        const metaResult = decodeAxmMeta(axmRaw);
+        if (Result.isFailure(metaResult)) {
+            yield* Effect.logWarning(`Invalid axm metadata in ${pkg.purl.name}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "huggingface" }), Effect.withSpan("read.huggingface")),
+};
+//# sourceMappingURL=huggingface.js.map

package/dist/src/packaging/index.d.ts

@@ -0,0 +1,44 @@
+export type { DetectedPackage, PackageDetector, PackageReader } from "./types.js";
+export { detectPackages } from "./detect.js";
+export { readLocalRecommendations } from "./read.js";
+import { npmDetector, npmReader } from "./npm.js";
+import { golangDetector, golangReader } from "./golang.js";
+import { pypiDetector, pypiReader } from "./pypi.js";
+import { cargoDetector, cargoReader } from "./cargo.js";
+import { gemDetector, gemReader } from "./gem.js";
+import { mavenDetector, mavenReader } from "./maven.js";
+import { nugetDetector, nugetReader } from "./nuget.js";
+import { composerDetector, composerReader } from "./composer.js";
+import { swiftDetector, swiftReader } from "./swift.js";
+import { hexDetector, hexReader } from "./hex.js";
+import { pubDetector, pubReader } from "./pub.js";
+import { dockerDetector, dockerReader } from "./docker.js";
+import { cocoapodsDetector, cocoapodsReader } from "./cocoapods.js";
+import { condaDetector, condaReader } from "./conda.js";
+import { conanDetector, conanReader } from "./conan.js";
+import { cranDetector, cranReader } from "./cran.js";
+import { huggingfaceReader } from "./huggingface.js";
+import { cpanDetector, cpanReader } from "./cpan.js";
+import { hackageDetector, hackageReader } from "./hackage.js";
+import { juliaDetector, juliaReader } from "./julia.js";
+import { luarocksDetector, luarocksReader } from "./luarocks.js";
+import { opamDetector, opamReader } from "./opam.js";
+import { bazelDetector, bazelReader } from "./bazel.js";
+import { zigDetector, zigReader } from "./zig.js";
+import { jsrDetector, denoReader } from "./jsr.js";
+import { mojoDetector, mojoReader } from "./mojo.js";
+import type { PackageDetector, PackageReader } from "./types.js";
+export { npmDetector, npmReader, golangDetector, golangReader, pypiDetector, pypiReader, cargoDetector, cargoReader, gemDetector, gemReader, mavenDetector, mavenReader, nugetDetector, nugetReader, composerDetector, composerReader, swiftDetector, swiftReader, hexDetector, hexReader, pubDetector, pubReader, dockerDetector, dockerReader, cocoapodsDetector, cocoapodsReader, condaDetector, condaReader, conanDetector, conanReader, cranDetector, cranReader, huggingfaceReader, cpanDetector, cpanReader, hackageDetector, hackageReader, juliaDetector, juliaReader, luarocksDetector, luarocksReader, opamDetector, opamReader, bazelDetector, bazelReader, zigDetector, zigReader, jsrDetector, denoReader, mojoDetector, mojoReader, };
+/**
+ * All registered package detectors.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const packageDetectors: ReadonlyArray<PackageDetector>;
+/**
+ * All registered package readers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const packageReaders: ReadonlyArray<PackageReader>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/packaging/index.js

@@ -0,0 +1,120 @@
+export { detectPackages } from "./detect.js";
+export { readLocalRecommendations } from "./read.js";
+// Tier 1
+import { npmDetector, npmReader } from "./npm.js";
+import { golangDetector, golangReader } from "./golang.js";
+import { pypiDetector, pypiReader } from "./pypi.js";
+// Tier 2
+import { cargoDetector, cargoReader } from "./cargo.js";
+import { gemDetector, gemReader } from "./gem.js";
+import { mavenDetector, mavenReader } from "./maven.js";
+import { nugetDetector, nugetReader } from "./nuget.js";
+// Tier 3
+import { composerDetector, composerReader } from "./composer.js";
+import { swiftDetector, swiftReader } from "./swift.js";
+import { hexDetector, hexReader } from "./hex.js";
+import { pubDetector, pubReader } from "./pub.js";
+import { dockerDetector, dockerReader } from "./docker.js";
+import { cocoapodsDetector, cocoapodsReader } from "./cocoapods.js";
+import { condaDetector, condaReader } from "./conda.js";
+// Tier 4
+import { conanDetector, conanReader } from "./conan.js";
+import { cranDetector, cranReader } from "./cran.js";
+import { huggingfaceReader } from "./huggingface.js";
+import { cpanDetector, cpanReader } from "./cpan.js";
+import { hackageDetector, hackageReader } from "./hackage.js";
+import { juliaDetector, juliaReader } from "./julia.js";
+import { luarocksDetector, luarocksReader } from "./luarocks.js";
+import { opamDetector, opamReader } from "./opam.js";
+import { bazelDetector, bazelReader } from "./bazel.js";
+// Tier 5
+import { zigDetector, zigReader } from "./zig.js";
+import { jsrDetector, denoReader } from "./jsr.js";
+import { mojoDetector, mojoReader } from "./mojo.js";
+export { 
+// Tier 1
+npmDetector, npmReader, golangDetector, golangReader, pypiDetector, pypiReader, 
+// Tier 2
+cargoDetector, cargoReader, gemDetector, gemReader, mavenDetector, mavenReader, nugetDetector, nugetReader, 
+// Tier 3
+composerDetector, composerReader, swiftDetector, swiftReader, hexDetector, hexReader, pubDetector, pubReader, dockerDetector, dockerReader, cocoapodsDetector, cocoapodsReader, condaDetector, condaReader, 
+// Tier 4
+conanDetector, conanReader, cranDetector, cranReader, huggingfaceReader, cpanDetector, cpanReader, hackageDetector, hackageReader, juliaDetector, juliaReader, luarocksDetector, luarocksReader, opamDetector, opamReader, bazelDetector, bazelReader, 
+// Tier 5
+zigDetector, zigReader, jsrDetector, denoReader, mojoDetector, mojoReader, };
+/**
+ * All registered package detectors.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const packageDetectors = [
+    // Tier 1
+    npmDetector,
+    golangDetector,
+    pypiDetector,
+    // Tier 2
+    cargoDetector,
+    gemDetector,
+    mavenDetector,
+    nugetDetector,
+    // Tier 3
+    composerDetector,
+    swiftDetector,
+    hexDetector,
+    pubDetector,
+    dockerDetector,
+    cocoapodsDetector,
+    condaDetector,
+    // Tier 4
+    conanDetector,
+    cranDetector,
+    cpanDetector,
+    hackageDetector,
+    juliaDetector,
+    luarocksDetector,
+    opamDetector,
+    bazelDetector,
+    // Tier 5
+    zigDetector,
+    jsrDetector,
+    mojoDetector,
+];
+/**
+ * All registered package readers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const packageReaders = [
+    // Tier 1
+    npmReader,
+    golangReader,
+    pypiReader,
+    // Tier 2
+    cargoReader,
+    gemReader,
+    mavenReader,
+    nugetReader,
+    // Tier 3
+    composerReader,
+    swiftReader,
+    hexReader,
+    pubReader,
+    dockerReader,
+    cocoapodsReader,
+    condaReader,
+    // Tier 4
+    conanReader,
+    cranReader,
+    huggingfaceReader,
+    cpanReader,
+    hackageReader,
+    juliaReader,
+    luarocksReader,
+    opamReader,
+    bazelReader,
+    // Tier 5
+    zigReader,
+    denoReader,
+    mojoReader,
+];
+//# sourceMappingURL=index.js.map

package/dist/src/packaging/jsr.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JSR package detector and Deno reader for package-compatibility discovery.
+ *
+ * Parses `deno.json`/`deno.jsonc` for `jsr:@scope/name` imports and reads
+ * axm metadata from Deno's module cache.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * JSR package detector.
+ *
+ * Scans `deno.json` and `deno.jsonc` in the project directory and extracts
+ * `jsr:@scope/name` imports, producing `pkg:jsr/<scope>/<name>` purls.
+ * npm-prefixed imports are skipped.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const jsrDetector: PackageDetector;
+/**
+ * Deno package reader.
+ *
+ * Reads axm metadata from cached module metadata in Deno's module cache.
+ * Checks for an `"axm"` field in cached `deno.json` files.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const denoReader: PackageReader;
+//# sourceMappingURL=jsr.d.ts.map