@agentxm/extension-discovery 0.28.4-bootstrap.0

package/dist/src/packaging/swift.js

@@ -0,0 +1,141 @@
+/**
+ * Swift 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 { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { PackageUrlPartsSchema, } from "@agentxm/extension-model/unstable/packaging/package-url";
+import { decodeAxmMeta, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const swiftType = Schema.decodeUnknownSync(PackageTypeSchema)("swift");
+const makePackageUrlParts = Schema.decodeUnknownSync(PackageUrlPartsSchema);
+/**
+ * Regex to match `exact: "version"` in a package declaration.
+ */
+const EXACT_VERSION_REGEX = /exact:\s*"([^"]+)"/;
+/**
+ * Parse a Swift package URL into namespace and name parts.
+ * URL format: https://github.com/Owner/RepoName.git
+ * namespace = host/org, name = repo (without .git)
+ */
+const parseSwiftUrl = (url) => {
+    try {
+        const parsed = new URL(url);
+        const pathParts = parsed.pathname.split("/").filter((p) => p.length > 0);
+        if (pathParts.length < 2)
+            return undefined;
+        const host = parsed.hostname;
+        // All segments except the last form the org path
+        const orgParts = pathParts.slice(0, -1);
+        const rawName = pathParts[pathParts.length - 1];
+        if (rawName === undefined)
+            return undefined;
+        // Strip .git suffix
+        const name = rawName.endsWith(".git") ? rawName.slice(0, -4) : rawName;
+        const namespace = `${host}/${orgParts.join("/")}`;
+        return { namespace, name };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Extract the version requirement from a package declaration line/context.
+ * Returns the exact version if specified, undefined otherwise (ranges are versionless).
+ */
+const extractVersion = (packageContext) => {
+    const exactMatch = EXACT_VERSION_REGEX.exec(packageContext);
+    if (exactMatch?.[1] !== undefined)
+        return exactMatch[1];
+    return undefined;
+};
+/**
+ * Build PackageUrlParts directly for swift packages.
+ * packageurl-js v2 requires a version for swift type purls, but we need
+ * versionless purls for range dependencies. We construct parts directly
+ * through the PackageUrlPartsSchema to bypass purl-string validation.
+ */
+const buildSwiftPurlParts = (namespace, name, version) => makePackageUrlParts(version !== undefined
+    ? { type: "swift", namespace, name, version }
+    : { type: "swift", namespace, name });
+/**
+ * Parse Package.swift content and extract dependencies using regex.
+ * Since running `swift package dump-package` requires the Swift CLI,
+ * we use simple regex to extract `.package(url: "...")` dependencies.
+ */
+const parsePackageSwift = (content, source) => {
+    const results = [];
+    // Find all .package(url: "...") declarations
+    // We search for the entire package(...) block to extract version info too
+    const packageBlockRegex = /\.package\([^)]*url:\s*"([^"]+)"[^)]*\)/g;
+    let match;
+    while ((match = packageBlockRegex.exec(content)) !== null) {
+        const url = match[1];
+        if (url === undefined)
+            continue;
+        const parsed = parseSwiftUrl(url);
+        if (parsed === undefined)
+            continue;
+        // Extract version from the full match context
+        const version = extractVersion(match[0]);
+        const purlParts = buildSwiftPurlParts(parsed.namespace, parsed.name, version);
+        results.push({ purl: purlParts, type: swiftType, source });
+    }
+    return results;
+};
+/**
+ * Swift package detector.
+ *
+ * Scans `Package.swift` in the project directory and extracts `.package(url: ...)`
+ * dependencies using regex pattern matching.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const swiftDetector = {
+    type: swiftType,
+    detect: Effect.fn("detect.swift")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const manifestPath = path.join(projectDir, "Package.swift");
+        const content = yield* readFileOptional(manifestPath);
+        if (Option.isNone(content))
+            return [];
+        const deps = parsePackageSwift(content.value, manifestPath);
+        return deps;
+    }, Effect.annotateLogs({ detector: "swift" }), Effect.withSpan("detect.swift")),
+};
+/**
+ * Swift package reader.
+ *
+ * Reads `.build/checkouts/<package-name>/axm.json` for each detected SwiftPM
+ * package and extracts recommendation metadata.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const swiftReader = {
+    type: swiftType,
+    read: Effect.fn("read.swift")(function* (pkg) {
+        const path = yield* Path.Path;
+        // Derive project directory from the source manifest path
+        const projectDir = path.dirname(pkg.source);
+        const axmJsonPath = path.join(projectDir, ".build", "checkouts", pkg.purl.name, "axm.json");
+        const content = yield* readFileOptional(axmJsonPath);
+        if (Option.isNone(content))
+            return Option.none();
+        const parsed = yield* parseJsonOptional(content.value, `${pkg.purl.name}/axm.json`);
+        if (Option.isNone(parsed))
+            return Option.none();
+        // Validate axm metadata structure
+        const metaResult = decodeAxmMeta(parsed.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: "swift" }), Effect.withSpan("read.swift")),
+};
+//# sourceMappingURL=swift.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * Detector and reader interfaces for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Path from "effect/Path";
+import type { PackageExtensionDeclaration } from "@agentxm/registry-client";
+import type { PackageType } from "@agentxm/extension-model/unstable/packaging/package-type";
+import type { PackageUrlParts } from "@agentxm/extension-model/unstable/packaging/package-url";
+/**
+ * A package detected in a project directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface DetectedPackage {
+    readonly purl: PackageUrlParts;
+    readonly type: PackageType;
+    /** File that produced this purl (for diagnostics). */
+    readonly source: string;
+}
+/**
+ * Scans a project directory for packages of a specific type.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface PackageDetector {
+    readonly type: PackageType;
+    readonly detect: (projectDir: string) => Effect.Effect<ReadonlyArray<DetectedPackage>, never, FileSystem.FileSystem | Path.Path>;
+}
+/**
+ * Reads local recommendation data from a detected package.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface PackageReader {
+    readonly type: PackageType;
+    readonly read: (pkg: DetectedPackage) => Effect.Effect<Option.Option<ReadonlyArray<PackageExtensionDeclaration>>, never, FileSystem.FileSystem | Path.Path>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/packaging/types.js

@@ -0,0 +1,8 @@
+/**
+ * Detector and reader interfaces for package-compatibility discovery.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * Zig package detector and reader for package-compatibility discovery.
+ *
+ * Parses `build.zig.zon` for URL-based dependencies and reads axm metadata
+ * from the Zig package cache at `~/.cache/zig/`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { PackageDetector, PackageReader } from "./types.js";
+/**
+ * Zig package detector.
+ *
+ * Scans `build.zig.zon` in the project directory and extracts dependency
+ * names from the `.dependencies` field, producing `pkg:zig/<name>` purls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const zigDetector: PackageDetector;
+/**
+ * Zig package reader.
+ *
+ * Reads `axm.json` sidecar files from `~/.cache/zig/p/<hash>/` for each
+ * detected Zig package and extracts recommendation metadata.
+ *
+ * Since Zig uses content-addressed hashes for packages rather than named
+ * directories, the reader does a best-effort scan of the cache.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const zigReader: PackageReader;
+//# sourceMappingURL=zig.d.ts.map

package/dist/src/packaging/zig.js

@@ -0,0 +1,151 @@
+/**
+ * Zig package detector and reader for package-compatibility discovery.
+ *
+ * Parses `build.zig.zon` for URL-based dependencies and reads axm metadata
+ * from the Zig package cache at `~/.cache/zig/`.
+ *
+ * @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 FileSystem from "effect/FileSystem";
+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 { PackageTypeSchema } from "@agentxm/extension-model/unstable/packaging/package-type";
+import { decodeAxmMeta, decodePurl, parseJsonOptional, readFileOptional } from "./reader-io.js";
+const zigType = Schema.decodeUnknownSync(PackageTypeSchema)("zig");
+/**
+ * Extract dependency names from build.zig.zon content.
+ *
+ * Zon uses a struct-like syntax:
+ * ```
+ * .dependencies = .{
+ *     .zap = .{ .url = "...", .hash = "..." },
+ *     .mach = .{ .url = "...", .hash = "..." },
+ * },
+ * ```
+ *
+ * We extract the dependency names (keys) using regex.
+ */
+const parseZonDependencies = (content) => {
+    // Find the start of the .dependencies block
+    const startIdx = content.indexOf(".dependencies");
+    if (startIdx === -1)
+        return [];
+    // Find the opening .{ after .dependencies =
+    const openBrace = content.indexOf(".{", startIdx);
+    if (openBrace === -1)
+        return [];
+    // Track brace depth to find the matching closing }
+    let depth = 0;
+    let endIdx = openBrace;
+    for (let i = openBrace; i < content.length; i++) {
+        if (content[i] === "{")
+            depth++;
+        if (content[i] === "}") {
+            depth--;
+            if (depth === 0) {
+                endIdx = i;
+                break;
+            }
+        }
+    }
+    const depsBlock = content.slice(openBrace, endIdx + 1);
+    const names = [];
+    // Match dependency names: .name = .{ ... }
+    // Also support quoted names: .@"name-with-dashes" = .{ ... }
+    const depPattern = /\.(?:@"([^"]+)"|([a-zA-Z_][a-zA-Z0-9_]*))\s*=\s*\.?\{/g;
+    let match = depPattern.exec(depsBlock);
+    while (match !== null) {
+        const name = match[1] ?? match[2];
+        if (name !== undefined) {
+            names.push(name);
+        }
+        match = depPattern.exec(depsBlock);
+    }
+    return names;
+};
+/**
+ * Zig package detector.
+ *
+ * Scans `build.zig.zon` in the project directory and extracts dependency
+ * names from the `.dependencies` field, producing `pkg:zig/<name>` purls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const zigDetector = {
+    type: zigType,
+    detect: Effect.fn("detect.zig")(function* (projectDir) {
+        const path = yield* Path.Path;
+        const manifestPath = path.join(projectDir, "build.zig.zon");
+        const content = yield* readFileOptional(manifestPath);
+        if (Option.isNone(content))
+            return [];
+        const names = parseZonDependencies(content.value);
+        if (names.length === 0) {
+            // Check if the file looks like it should have dependencies but we couldn't parse
+            if (content.value.includes(".dependencies") &&
+                !content.value.includes(".dependencies = .{")) {
+                yield* Effect.logWarning("Malformed build.zig.zon: could not parse .dependencies, skipping");
+            }
+            return [];
+        }
+        const results = [];
+        for (const name of names) {
+            const purl = new PackageURL("zig", null, name, null, null, null);
+            const purlParts = decodePurl(purl.toString());
+            results.push({ purl: purlParts, type: zigType, source: manifestPath });
+        }
+        return results;
+    }, Effect.annotateLogs({ detector: "zig" }), Effect.withSpan("detect.zig")),
+};
+/**
+ * Zig package reader.
+ *
+ * Reads `axm.json` sidecar files from `~/.cache/zig/p/<hash>/` for each
+ * detected Zig package and extracts recommendation metadata.
+ *
+ * Since Zig uses content-addressed hashes for packages rather than named
+ * directories, the reader does a best-effort scan of the cache.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const zigReader = {
+    type: zigType,
+    read: Effect.fn("read.zig")(function* (pkg) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const cacheDir = path.join(os.homedir(), ".cache", "zig", "p");
+        // Check if cache directory exists
+        const cacheDirExists = yield* fs.exists(cacheDir).pipe(Effect.option);
+        if (Option.isNone(cacheDirExists) || !cacheDirExists.value)
+            return Option.none();
+        // Scan cache directory entries for axm.json
+        const entries = yield* fs.readDirectory(cacheDir).pipe(Effect.option);
+        if (Option.isNone(entries))
+            return Option.none();
+        // Check each cache entry for axm.json with matching package name
+        for (const entry of entries.value) {
+            const axmJsonPath = path.join(cacheDir, entry, "axm.json");
+            const content = yield* readFileOptional(axmJsonPath);
+            if (Option.isNone(content))
+                continue;
+            const parsed = yield* parseJsonOptional(content.value, `${pkg.purl.name}/axm.json`);
+            if (Option.isNone(parsed))
+                continue;
+            const metaResult = decodeAxmMeta(parsed.value);
+            if (Result.isFailure(metaResult)) {
+                yield* Effect.logWarning(`Invalid axm metadata in zig cache for ${pkg.purl.name}: schema validation failed`);
+                continue;
+            }
+            return Option.some(metaResult.success.extensions);
+        }
+        return Option.none();
+    }, Effect.annotateLogs({ reader: "zig" }), Effect.withSpan("read.zig")),
+};
+//# sourceMappingURL=zig.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agentxm/extension-discovery",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM extension-discovery feature: project package detectors, local extension declarations, Registry recommendations, and discovery results for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/extension-discovery"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "packageurl-js": "^2.0.1",
+    "yaml": "^2.9.0",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-client": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
+    "@agentxm/extension-workspace": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}