@agentxm/extension-discovery 0.28.4-bootstrap.0

package/LICENSE

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

package/dist/src/discover.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Discover pipeline: detect direct packages, read package-native extension
+ * declarations, submit them to the registry, and render attestation results.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import type { RegistryClient } from "@agentxm/registry-client";
+import type { DiscoveryExtensionResult } from "@agentxm/registry-protocol/unstable/registry/discover-schema";
+import type { PackageUrlParts } from "@agentxm/extension-model/unstable/packaging/package-url";
+export interface DiscoverResultEntry {
+    readonly ref: string;
+    readonly resolved: boolean;
+    readonly extension: DiscoveryExtensionResult["extension"];
+    readonly attestedBy: ReadonlyArray<"package" | "extension">;
+    readonly official: boolean;
+    readonly packageVersionInRange: boolean;
+}
+export interface DiscoverPackageResult {
+    readonly detectedPackage: PackageUrlParts;
+    readonly extensions: ReadonlyArray<DiscoverResultEntry>;
+}
+export interface DiscoverResult {
+    readonly packages: ReadonlyArray<DiscoverPackageResult>;
+    readonly totalDetected: number;
+    readonly registryAvailable: boolean;
+}
+export declare const discover: (projectDir: string, registryClient: RegistryClient) => Effect.Effect<{
+    packages: readonly DiscoverPackageResult[];
+    totalDetected: number;
+    registryAvailable: boolean;
+}, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/src/discover.js

@@ -0,0 +1,133 @@
+/**
+ * Discover pipeline: detect direct packages, read package-native extension
+ * declarations, submit them to the registry, and render attestation results.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as HashMap from "effect/HashMap";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { parseExtensionFqnParts, toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions/common";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { detectPackages } from "./packaging/detect.js";
+import { packageDetectors, packageReaders } from "./packaging/index.js";
+import { PackageUrlSchema } from "@agentxm/extension-model/unstable/packaging/package-url";
+import { readLocalRecommendations } from "./packaging/read.js";
+const encodePurl = Schema.encodeSync(PackageUrlSchema);
+const packageIdentity = (parts) => ({
+    type: parts.type,
+    name: parts.name,
+    ...(parts.namespace === undefined ? {} : { namespace: parts.namespace }),
+    ...(parts.qualifiers === undefined ? {} : { qualifiers: parts.qualifiers }),
+    ...(parts.subpath === undefined ? {} : { subpath: parts.subpath }),
+});
+const extensionDeclarationToRef = (value) => {
+    const parts = parseExtensionFqnParts(value.ref);
+    if (parts === undefined) {
+        return undefined;
+    }
+    return `${parts.owner}/${toExtensionTypePlural(parts.type)}/${parts.name}`;
+};
+export const discover = (projectDir, registryClient) => Effect.gen(function* () {
+    const detected = yield* detectPackages(projectDir, packageDetectors).pipe(Effect.withSpan("discover.detect"));
+    if (detected.length === 0) {
+        return {
+            packages: [],
+            totalDetected: 0,
+            registryAvailable: true,
+        };
+    }
+    const localExtensions = yield* readLocalRecommendations(detected, packageReaders).pipe(Effect.withSpan("discover.readLocal"));
+    // v1 submits direct dependencies only. Revisit transitive submission and
+    // privacy-mode filtering together so users get one coherent consent model.
+    const submittedPackages = detected.flatMap((pkg) => {
+        if (pkg.purl.version === undefined) {
+            return [];
+        }
+        const purl = encodePurl(pkg.purl);
+        const declaredExtensions = Option.match(HashMap.get(localExtensions, purl), {
+            onNone: () => [],
+            onSome: (value) => value,
+        });
+        return [
+            {
+                purl: packageIdentity(pkg.purl),
+                version: pkg.purl.version,
+                declaredExtensions,
+            },
+        ];
+    });
+    const registryResult = yield* Effect.result(registryClient.discoverPackages({ packages: submittedPackages })).pipe(Effect.withSpan("discover.queryRegistry"));
+    if (Result.isFailure(registryResult)) {
+        yield* Effect.logWarning("Registry is unreachable; showing local package declarations only");
+    }
+    const registryAvailable = Result.isSuccess(registryResult);
+    const packages = registryAvailable
+        ? mergeRegistryResults(detected, registryResult.success.results)
+        : buildLocalOnlyResults(detected, localExtensions);
+    return {
+        packages,
+        totalDetected: detected.length,
+        registryAvailable,
+    };
+}).pipe(Effect.annotateLogs({ command: "discover", projectDir }), Effect.withSpan("discover"));
+const mergeRegistryResults = (detected, results) => {
+    const detectedByIdentity = new Map(detected.map((pkg) => [encodePurl(packageIdentity(pkg.purl)), pkg.purl]));
+    return results.flatMap((result) => {
+        const detectedPackage = detectedByIdentity.get(result.purl);
+        if (detectedPackage === undefined || result.extensions.length === 0) {
+            return [];
+        }
+        return [
+            {
+                detectedPackage,
+                extensions: result.extensions.map((entry) => ({
+                    ref: entry.ref,
+                    resolved: entry.resolved,
+                    extension: entry.extension,
+                    attestedBy: entry.attestedBy,
+                    official: entry.official,
+                    packageVersionInRange: entry.packageVersionInRange,
+                })),
+            },
+        ];
+    });
+};
+const buildLocalOnlyResults = (detected, localExtensions) => {
+    const fallbackVersion = decodeVersionSync("0.0.0");
+    return detected.flatMap((pkg) => {
+        const refs = HashMap.get(localExtensions, encodePurl(pkg.purl));
+        if (Option.isNone(refs) || refs.value.length === 0) {
+            return [];
+        }
+        const extensions = refs.value.flatMap((entry) => {
+            const parts = parseExtensionFqnParts(entry.ref);
+            const ref = extensionDeclarationToRef(entry);
+            if (parts === undefined || ref === undefined) {
+                return [];
+            }
+            return [
+                {
+                    ref,
+                    resolved: true,
+                    extension: {
+                        owner: parts.owner,
+                        type: parts.type,
+                        name: parts.name,
+                        installVersion: fallbackVersion,
+                    },
+                    attestedBy: ["package"],
+                    official: false,
+                    packageVersionInRange: true,
+                },
+            ];
+        });
+        return extensions.length === 0
+            ? []
+            : [{ detectedPackage: pkg.purl, extensions }];
+    });
+};
+//# sourceMappingURL=discover.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extension-discovery feature: project package detectors, package-native
+ * extension declarations, Registry recommendations, and discovery results.
+ *
+ * @experimental All exports from this module are unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { discover, type DiscoverResult, type DiscoverPackageResult, type DiscoverResultEntry, } from "./discover.js";
+export type { DetectedPackage, PackageDetector, PackageReader } from "./packaging/types.js";
+export { detectPackages } from "./packaging/detect.js";
+export { readLocalRecommendations } from "./packaging/read.js";
+export { packageDetectors, packageReaders } from "./packaging/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * Extension-discovery feature: project package detectors, package-native
+ * extension declarations, Registry recommendations, and discovery results.
+ *
+ * @experimental All exports from this module are unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { discover, } from "./discover.js";
+export { detectPackages } from "./packaging/detect.js";
+export { readLocalRecommendations } from "./packaging/read.js";
+export { packageDetectors, packageReaders } from "./packaging/index.js";
+//# sourceMappingURL=index.js.map

package/dist/src/internal/environment.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Environment variable access for package detectors.
+ *
+ * Mirrors the shared helpers the extracted kernels carry; a generic utils
+ * package is deliberately not created.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+export declare const readEnv: (name: string) => string | undefined;
+/** Read an optional env var. Centralized access point for process.env. */
+export declare const envOption: (name: string) => Effect.Effect<Option.Option<string>>;
+/** Read an env var with a default value. Centralized access point for process.env. */
+export declare const envWithDefault: (name: string, fallback: string) => Effect.Effect<string>;
+//# sourceMappingURL=environment.d.ts.map

package/dist/src/internal/environment.js

@@ -0,0 +1,15 @@
+/**
+ * Environment variable access for package detectors.
+ *
+ * Mirrors the shared helpers the extracted kernels carry; a generic utils
+ * package is deliberately not created.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+// eslint-disable-next-line no-restricted-properties -- Centralized env var access point; all callers use these helpers
+export const readEnv = (name) => process.env[name];
+/** Read an optional env var. Centralized access point for process.env. */
+export const envOption = (name) => Effect.sync(() => Option.fromUndefinedOr(readEnv(name)));
+/** Read an env var with a default value. Centralized access point for process.env. */
+export const envWithDefault = (name, fallback) => Effect.sync(() => readEnv(name) ?? fallback);
+//# sourceMappingURL=environment.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * Bazel package 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";
+/**
+ * Bazel package detector.
+ *
+ * Scans `MODULE.bazel` for `bazel_dep()` calls. Dependencies are deduplicated
+ * by name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const bazelDetector: PackageDetector;
+/**
+ * Bazel package reader.
+ *
+ * Reads `axm.json` from the Bazel external repository directory under
+ * the output base (`external/<repo>/`). The output base is checked via
+ * the BAZEL_OUTPUT_BASE environment variable or a default location.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const bazelReader: PackageReader;
+//# sourceMappingURL=bazel.d.ts.map

package/dist/src/packaging/bazel.js

@@ -0,0 +1,125 @@
+/**
+ * Bazel package detector and reader for package-compatibility discovery.
+ *
+ * @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 { readEnv } from "../internal/environment.js";
+import { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const bazelType = Schema.decodeUnknownSync(PackageTypeSchema)("bazel");
+/**
+ * Parse MODULE.bazel content for bazel_dep() calls.
+ * Format: bazel_dep(name = "rules_go", version = "0.41.0")
+ */
+const parseModuleBazel = (content, source) => {
+    const results = [];
+    // Match bazel_dep(...) calls, handling multi-line
+    const bazelDepRegex = /bazel_dep\s*\(([^)]*)\)/g;
+    let match;
+    while ((match = bazelDepRegex.exec(content)) !== null) {
+        const args = match[1];
+        if (args === undefined)
+            continue;
+        // Extract name attribute
+        const nameMatch = /name\s*=\s*"([^"]+)"/.exec(args);
+        if (nameMatch === null || nameMatch[1] === undefined)
+            continue;
+        const name = nameMatch[1];
+        // Extract optional version attribute
+        const versionMatch = /version\s*=\s*"([^"]+)"/.exec(args);
+        const version = versionMatch?.[1];
+        const purl = new PackageURL("bazel", null, name, version ?? null, null, null);
+        const purlParts = decodePurl(purl.toString());
+        results.push({ purl: purlParts, type: bazelType, source });
+    }
+    return results;
+};
+/**
+ * Bazel package detector.
+ *
+ * Scans `MODULE.bazel` for `bazel_dep()` calls. Dependencies are deduplicated
+ * by name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const bazelDetector = {
+    type: bazelType,
+    detect: Effect.fn("detect.bazel")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const allDeps = [];
+        const seenNames = new Set();
+        const addDeps = (deps) => {
+            for (const dep of deps) {
+                if (!seenNames.has(dep.purl.name)) {
+                    seenNames.add(dep.purl.name);
+                    allDeps.push(dep);
+                }
+            }
+        };
+        // Parse MODULE.bazel (preferred Bzlmod format)
+        const moduleBazelPath = path.join(projectDir, "MODULE.bazel");
+        const moduleContent = yield* readFileOptional(moduleBazelPath);
+        if (Option.isSome(moduleContent)) {
+            const deps = parseModuleBazel(moduleContent.value, moduleBazelPath);
+            if (deps.length === 0 && moduleContent.value.trim().length > 0) {
+                if (!moduleContent.value.includes("module(") &&
+                    !moduleContent.value.includes("bazel_dep")) {
+                    yield* Effect.logWarning("Malformed MODULE.bazel, skipping");
+                }
+            }
+            addDeps(deps);
+        }
+        return allDeps;
+    }, Effect.annotateLogs({ detector: "bazel" }), Effect.withSpan("detect.bazel")),
+};
+/**
+ * Bazel package reader.
+ *
+ * Reads `axm.json` from the Bazel external repository directory under
+ * the output base (`external/<repo>/`). The output base is checked via
+ * the BAZEL_OUTPUT_BASE environment variable or a default location.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const bazelReader = {
+    type: bazelType,
+    read: Effect.fn("read.bazel")(function* (pkg) {
+        const path = yield* Path.Path;
+        const pkgName = pkg.purl.name;
+        // Derive project directory from the source manifest path
+        const projectDir = path.dirname(pkg.source);
+        // Try to find output base from environment or common location
+        const outputBase = readEnv("BAZEL_OUTPUT_BASE");
+        // Candidate paths for axm.json
+        const candidatePaths = [];
+        if (outputBase !== undefined) {
+            candidatePaths.push(path.join(outputBase, "external", pkgName, "axm.json"));
+        }
+        // Also try project-local bazel-out external directory
+        candidatePaths.push(path.join(projectDir, "bazel-out", "external", pkgName, "axm.json"));
+        candidatePaths.push(path.join(projectDir, "bazel-" + path.basename(projectDir), "external", pkgName, "axm.json"));
+        for (const candidatePath of candidatePaths) {
+            const content = yield* readFileOptional(candidatePath);
+            if (Option.isNone(content))
+                continue;
+            const parsed = yield* parseJsonOptional(content.value, `${pkgName}/axm.json`);
+            if (Option.isNone(parsed))
+                return Option.none();
+            const metaResult = decodeAxmMeta(parsed.value);
+            if (Result.isFailure(metaResult)) {
+                yield* Effect.logWarning(`Invalid axm metadata in ${pkgName}: schema validation failed`);
+                return Option.none();
+            }
+            return Option.some(metaResult.success.extensions);
+        }
+        return Option.none();
+    }, Effect.annotateLogs({ reader: "bazel" }), Effect.withSpan("read.bazel")),
+};
+//# sourceMappingURL=bazel.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * Cargo (Rust) package 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";
+/**
+ * Cargo package detector.
+ *
+ * Scans `Cargo.toml` in the project directory and extracts dependencies
+ * from `[dependencies]`, `[dev-dependencies]`, and `[build-dependencies]`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const cargoDetector: PackageDetector;
+/**
+ * Cargo package reader.
+ *
+ * Reads `[package.metadata.axm]` from
+ * `$CARGO_HOME/registry/src/<index>/<crate>-<version>/Cargo.toml` for each
+ * detected cargo crate. `[package.metadata.*]` is Cargo's standard
+ * extensibility mechanism for third-party tools (used by docs.rs, cargo-deb,
+ * cargo-bundle, etc.).
+ *
+ * When the crate version is unknown, scans the registry source directory
+ * for any matching crate directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const cargoReader: PackageReader;
+//# sourceMappingURL=cargo.d.ts.map