@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/cpan.js

@@ -0,0 +1,189 @@
+/**
+ * CPAN (Perl) package detector and reader for package-compatibility discovery.
+ *
+ * Parses `cpanfile` (`requires 'Name'` lines) and `Makefile.PL` (`PREREQ_PM`).
+ * Reads `x_axm` from `<lib-path>/.meta/<dist>/MYMETA.json`.
+ *
+ * @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 { readEnv } from "../internal/environment.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const cpanType = Schema.decodeUnknownSync(PackageTypeSchema)("cpan");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Perl module name to a CPAN distribution-style name.
+ * Module names use :: as separator (e.g., Moose::Util),
+ * distribution names use - (e.g., Moose-Util).
+ */
+const moduleToDistName = (moduleName) => moduleName.replace(/::/g, "-");
+/**
+ * Parse a `cpanfile` and extract dependencies.
+ * Format: requires 'Module::Name', 'version';
+ *         requires 'Module::Name';
+ */
+const parseCpanfile = (content, source) => {
+    const results = [];
+    const seenNames = new Set();
+    // Match: requires 'Name' or requires 'Name', 'version'
+    // Also: requires "Name" or requires "Name", "version"
+    const requiresRegex = /requires\s+['"]([^'"]+)['"]\s*(?:,\s*['"]([^'"]*)['"]\s*)?;/g;
+    let match;
+    while ((match = requiresRegex.exec(content)) !== null) {
+        const moduleName = match[1];
+        if (moduleName === undefined)
+            continue;
+        const name = moduleToDistName(moduleName);
+        if (seenNames.has(name))
+            continue;
+        seenNames.add(name);
+        const versionSpec = match[2]?.trim();
+        // Only exact versions (no ranges)
+        const version = versionSpec !== undefined && /^\d+(?:\.\d+)*$/.test(versionSpec) ? versionSpec : undefined;
+        results.push({
+            purl: {
+                type: cpanType,
+                name,
+                ...(version !== undefined ? { version } : {}),
+            },
+            type: cpanType,
+            source,
+        });
+    }
+    return results;
+};
+/**
+ * Parse `Makefile.PL` and extract dependencies from PREREQ_PM.
+ * Format: PREREQ_PM => { 'Module::Name' => 'version', ... }
+ */
+const parseMakefilePL = (content, source) => {
+    const results = [];
+    const seenNames = new Set();
+    // Match PREREQ_PM => { ... } block
+    const prereqMatch = /PREREQ_PM\s*=>\s*\{([^}]*)}/s.exec(content);
+    if (!prereqMatch)
+        return [];
+    const block = prereqMatch[1] ?? "";
+    // Match 'Module::Name' => 'version' or "Module::Name" => "version"
+    const entryRegex = /['"]([^'"]+)['"]\s*=>\s*['"]?([^'",}]*?)['"]?\s*(?:,|$)/g;
+    let match;
+    while ((match = entryRegex.exec(block)) !== null) {
+        const moduleName = match[1];
+        if (moduleName === undefined)
+            continue;
+        const name = moduleToDistName(moduleName);
+        if (seenNames.has(name))
+            continue;
+        seenNames.add(name);
+        const versionSpec = match[2]?.trim();
+        const version = versionSpec !== undefined && versionSpec !== "" && /^\d+(?:\.\d+)*$/.test(versionSpec)
+            ? versionSpec
+            : undefined;
+        results.push({
+            purl: {
+                type: cpanType,
+                name,
+                ...(version !== undefined ? { version } : {}),
+            },
+            type: cpanType,
+            source,
+        });
+    }
+    return results;
+};
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+/**
+ * CPAN package detector.
+ *
+ * Scans `cpanfile` and `Makefile.PL` in the project directory and extracts
+ * dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const cpanDetector = {
+    type: cpanType,
+    detect: Effect.fn("detect.cpan")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const allPackages = [];
+        const seenNames = new Set();
+        const addUnique = (pkgs) => {
+            for (const pkg of pkgs) {
+                if (!seenNames.has(pkg.purl.name)) {
+                    seenNames.add(pkg.purl.name);
+                    allPackages.push(pkg);
+                }
+            }
+        };
+        // 1. cpanfile
+        const cpanfilePath = path.join(projectDir, "cpanfile");
+        const cpanfileContent = yield* readFileOptional(cpanfilePath);
+        if (Option.isSome(cpanfileContent)) {
+            addUnique(parseCpanfile(cpanfileContent.value, cpanfilePath));
+        }
+        // 2. Makefile.PL
+        const makefilePath = path.join(projectDir, "Makefile.PL");
+        const makefileContent = yield* readFileOptional(makefilePath);
+        if (Option.isSome(makefileContent)) {
+            addUnique(parseMakefilePL(makefileContent.value, makefilePath));
+        }
+        return allPackages;
+    }, Effect.annotateLogs({ detector: "cpan" }), Effect.withSpan("detect.cpan")),
+};
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/** Schema for extracting the x_axm field from MYMETA.json. */
+const MymetaAxmSchema = Schema.Struct({
+    x_axm: Schema.optional(Schema.Unknown),
+});
+const decodeMymetaAxm = Schema.decodeUnknownResult(MymetaAxmSchema);
+/**
+ * CPAN package reader.
+ *
+ * Reads `x_axm` from `<lib-path>/.meta/<dist>/MYMETA.json` for each
+ * detected CPAN package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const cpanReader = {
+    type: cpanType,
+    read: Effect.fn("read.cpan")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Default Perl local::lib path
+        const libPath = yield* Effect.sync(() => readEnv("PERL5LIB") ?? readEnv("PERL_LOCAL_LIB_ROOT") ?? "local/lib/perl5");
+        const distName = pkg.purl.name;
+        const version = pkg.purl.version;
+        const metaDir = version !== undefined ? `${distName}-${version}` : distName;
+        const mymetaPath = path.join(libPath, ".meta", metaDir, "MYMETA.json");
+        const content = yield* readFileOptional(mymetaPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const parsed = yield* parseJsonOptional(content.value, `${distName}/MYMETA.json`);
+        if (Option.isNone(parsed))
+            return Option.none();
+        // Extract x_axm metadata
+        const containerResult = decodeMymetaAxm(parsed.value);
+        if (Result.isFailure(containerResult))
+            return Option.none();
+        const axmRaw = containerResult.success.x_axm;
+        if (axmRaw === undefined)
+            return Option.none();
+        const metaResult = decodeAxmMeta(axmRaw);
+        if (Result.isFailure(metaResult)) {
+            yield* Effect.logWarning(`Invalid axm metadata in ${distName}: schema validation failed`);
+            return Option.none();
+        }
+        return Option.some(metaResult.success.extensions);
+    }, Effect.annotateLogs({ reader: "cpan" }), Effect.withSpan("read.cpan")),
+};
+//# sourceMappingURL=cpan.js.map

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

@@ -0,0 +1,29 @@
+/**
+ * CRAN (R) package detector and reader for package-compatibility discovery.
+ *
+ * Parses `DESCRIPTION` files for `Depends`, `Imports`, and `Suggests` fields.
+ * Reads `Config/axm` prefixed fields from installed package DESCRIPTION files.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * CRAN package detector.
+ *
+ * Scans `DESCRIPTION` file in the project directory and extracts dependencies
+ * from `Depends`, `Imports`, and `Suggests` fields.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const cranDetector: PackageDetector;
+/**
+ * CRAN package reader.
+ *
+ * Reads `Config/axm` prefixed fields from `<lib-path>/<pkg>/DESCRIPTION`
+ * for each detected CRAN package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const cranReader: PackageReader;
+//# sourceMappingURL=cran.d.ts.map

package/dist/src/packaging/cran.js

@@ -0,0 +1,176 @@
+/**
+ * CRAN (R) package detector and reader for package-compatibility discovery.
+ *
+ * Parses `DESCRIPTION` files for `Depends`, `Imports`, and `Suggests` fields.
+ * Reads `Config/axm` prefixed fields from installed package DESCRIPTION files.
+ *
+ * @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 { readEnv } from "../internal/environment.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, readFileOptional } from "./reader-io.js";
+const cranType = Schema.decodeUnknownSync(PackageTypeSchema)("cran");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a DESCRIPTION file into a key-value map.
+ * Handles continuation lines (lines starting with whitespace are appended
+ * to the previous field value).
+ */
+const parseDescriptionFile = (content) => {
+    const result = {};
+    let currentKey;
+    for (const line of content.split("\n")) {
+        // Continuation line: starts with whitespace
+        if (/^\s/.test(line) && currentKey !== undefined) {
+            const existing = result[currentKey];
+            if (existing !== undefined) {
+                result[currentKey] = existing + " " + line.trim();
+            }
+            continue;
+        }
+        // New field: Key: Value
+        const colonIdx = line.indexOf(":");
+        if (colonIdx > 0) {
+            currentKey = line.slice(0, colonIdx).trim();
+            result[currentKey] = line.slice(colonIdx + 1).trim();
+        }
+    }
+    return result;
+};
+/**
+ * Parse a comma-separated list of R package dependencies.
+ * Each entry is like "name (>= version)" or just "name".
+ * Filters out base R packages like "R" itself.
+ */
+const parseDependencyList = (value, source) => {
+    const results = [];
+    for (const entry of value.split(",")) {
+        const trimmed = entry.trim();
+        if (trimmed === "")
+            continue;
+        // Parse "name (>= version)" or "name"
+        const match = /^([A-Za-z][A-Za-z0-9.]*)(?:\s*\((.+)\))?$/.exec(trimmed);
+        if (!match)
+            continue;
+        const name = match[1];
+        if (name === undefined || name === "R")
+            continue;
+        // Only extract exact version constraints
+        const constraint = match[2]?.trim();
+        let version;
+        if (constraint !== undefined) {
+            const exactMatch = /^==\s*(.+)$/.exec(constraint);
+            if (exactMatch) {
+                version = exactMatch[1]?.trim();
+            }
+        }
+        results.push({
+            purl: {
+                type: cranType,
+                name,
+                ...(version !== undefined ? { version } : {}),
+            },
+            type: cranType,
+            source,
+        });
+    }
+    return results;
+};
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+/**
+ * CRAN package detector.
+ *
+ * Scans `DESCRIPTION` file in the project directory and extracts dependencies
+ * from `Depends`, `Imports`, and `Suggests` fields.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const cranDetector = {
+    type: cranType,
+    detect: Effect.fn("detect.cran")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const descriptionPath = path.join(projectDir, "DESCRIPTION");
+        const content = yield* readFileOptional(descriptionPath);
+        if (Option.isNone(content))
+            return [];
+        const fields = parseDescriptionFile(content.value);
+        const allPackages = [];
+        const seenNames = new Set();
+        const addUnique = (pkgs) => {
+            for (const pkg of pkgs) {
+                if (!seenNames.has(pkg.purl.name)) {
+                    seenNames.add(pkg.purl.name);
+                    allPackages.push(pkg);
+                }
+            }
+        };
+        // Extract from Depends, Imports, Suggests
+        for (const field of ["Depends", "Imports", "Suggests"]) {
+            const value = fields[field];
+            if (value !== undefined) {
+                addUnique(parseDependencyList(value, descriptionPath));
+            }
+        }
+        return allPackages;
+    }, Effect.annotateLogs({ detector: "cran" }), Effect.withSpan("detect.cran")),
+};
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the R library path.
+ * Checks R_LIBS_USER, then defaults to ~/R/library.
+ */
+const resolveRLibPath = () => Effect.sync(() => readEnv("R_LIBS_USER") ?? `${os.homedir()}/R/library`);
+/**
+ * CRAN package reader.
+ *
+ * Reads `Config/axm` prefixed fields from `<lib-path>/<pkg>/DESCRIPTION`
+ * for each detected CRAN package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const cranReader = {
+    type: cranType,
+    read: Effect.fn("read.cran")(function* (pkg) {
+        const path = yield* Path.Path;
+        const libPath = yield* resolveRLibPath();
+        const descriptionPath = path.join(libPath, pkg.purl.name, "DESCRIPTION");
+        const content = yield* readFileOptional(descriptionPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const fields = parseDescriptionFile(content.value);
+        // Look for Config/axm fields - the metadata is stored as JSON in Config/axm
+        const axmField = fields["Config/axm"];
+        if (axmField === undefined)
+            return Option.none();
+        // Parse the axm metadata JSON
+        const axmParsed = yield* Effect.try({
+            try: () => JSON.parse(axmField),
+            catch: () => ({ _tag: "JsonParseError" }),
+        }).pipe(Effect.option);
+        if (Option.isNone(axmParsed)) {
+            yield* Effect.logWarning(`Malformed Config/axm in ${pkg.purl.name}: invalid JSON`);
+            return Option.none();
+        }
+        const metaResult = decodeAxmMeta(axmParsed.value);
+        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: "cran" }), Effect.withSpan("read.cran")),
+};
+//# sourceMappingURL=cran.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Detect orchestrator: runs all package detectors concurrently,
+ * flattens results, and deduplicates by purl equivalence.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import type { PackageDetector } from "./types.js";
+/**
+ * Run all detectors concurrently, flatten and deduplicate results.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const detectPackages: (projectDir: string, detectors: readonly PackageDetector[]) => Effect.Effect<import("./types.js").DetectedPackage[], never, import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/src/packaging/detect.js

@@ -0,0 +1,25 @@
+/**
+ * Detect orchestrator: runs all package detectors concurrently,
+ * flattens results, and deduplicates by purl equivalence.
+ *
+ * @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 Schema from "effect/Schema";
+import { PackageUrlPartsSchema } from "@agentxm/extension-model/unstable/packaging/package-url";
+const purlEquivalence = Schema.toEquivalence(PackageUrlPartsSchema);
+/**
+ * Run all detectors concurrently, flatten and deduplicate results.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const detectPackages = Effect.fn("discover.detect")(function* (projectDir, detectors) {
+    const results = yield* Effect.forEach(detectors, (d) => d.detect(projectDir), {
+        concurrency: "unbounded",
+    });
+    const allDetected = Array.flatten(results);
+    return Array.dedupeWith(allDetected, (a, b) => purlEquivalence(a.purl, b.purl));
+});
+//# sourceMappingURL=detect.js.map

package/dist/src/packaging/detected-package.d.ts

@@ -0,0 +1,14 @@
+import * as Option from "effect/Option";
+import type { PackageType } from "@agentxm/extension-model/unstable/packaging/package-type";
+import type { DetectedPackage } from "./types.js";
+interface DetectedPackageInput {
+    readonly type: PackageType;
+    readonly namespace?: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly source: string;
+}
+/** Builds a package identity without allowing malformed manifests to throw. */
+export declare const makeDetectedPackage: (input: DetectedPackageInput) => Option.Option<DetectedPackage>;
+export {};
+//# sourceMappingURL=detected-package.d.ts.map

package/dist/src/packaging/detected-package.js

@@ -0,0 +1,20 @@
+import * as Option from "effect/Option";
+import { PackageURL } from "packageurl-js";
+import { decodePurl } from "./reader-io.js";
+/** Builds a package identity without allowing malformed manifests to throw. */
+export const makeDetectedPackage = (input) => {
+    if (input.name.trim() === "")
+        return Option.none();
+    try {
+        const purl = new PackageURL(input.type, input.namespace === undefined || input.namespace === "" ? null : input.namespace, input.name, input.version ?? null, null, null);
+        return Option.some({
+            purl: decodePurl(purl.toString()),
+            type: input.type,
+            source: input.source,
+        });
+    }
+    catch {
+        return Option.none();
+    }
+};
+//# sourceMappingURL=detected-package.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * Docker image detector and reader for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * Docker package detector.
+ *
+ * Scans `Dockerfile`, `docker-compose.yml`, and `docker-compose.yaml`
+ * for image dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const dockerDetector: PackageDetector;
+/**
+ * Docker package reader.
+ *
+ * Inspects local Docker image metadata for `sh.axm.recommended-extensions`
+ * annotation. Since inspecting Docker images requires the Docker CLI,
+ * this reader returns Option.none when Docker is not available.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const dockerReader: PackageReader;
+//# sourceMappingURL=docker.d.ts.map