@iseoane/agent-depot 0.4.1 → 0.5.0

package/dist/src/cli.js

@@ -5,6 +5,9 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { checkAppUpdates, createAppOperations } from "./app-flow.js";
 import { describeAppResult, describeManualCompletion, runAppCommand } from "./app-cli.js";
+import { createPackageOperations } from "./package-flow.js";
+import { describeLifecyclePlan, describePackageResult, describePackageUpdateCheck, formatPackageSelection, packageSelectionMatches, runPackageCommand } from "./package-cli.js";
+import { selectionKey } from "./package-model.js";
 import { EXPORT_USAGE, IMPORT_USAGE, runProfileExport, runProfileImport } from "./profile-cli.js";
 import { pathsOverlap } from "./path-safety.js";
 import { skillTreeBaseline } from "./skill-discovery.js";
@@ -30,9 +33,9 @@ const USAGE = [
     "  agent-depot discover <source-id> [source-id...]",
     "  agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--yes] [--confirm-additional-host]",
     "  agent-depot install --scope project --manifest --portable-v1 [--yes] [--confirm-additional-host]",
-    "  agent-depot update check --scope <project|user-global>",
-    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>...) [--yes] [--confirm-path <relative-path>...]",
-    "    Apps run after Skills; --all --scope project skips Apps.",
+    "  agent-depot update check --scope <project|user-global> [--package <selection>...]",
+    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>... | --package <selection>...) [--yes] [--confirm-path <relative-path>...]",
+    "    Apps and Packages run after Skills; --all --scope project skips Apps and Packages.",
     "  agent-depot skill remove <id|path>... [--yes]",
     "  agent-depot skill remove <id|path> --host <host>... [--yes]",
     "  agent-depot skill host add <id|path> --host <host>... [--yes] [--confirm-additional-host]",
@@ -42,6 +45,12 @@ const USAGE = [
     "  agent-depot app approve <name> [--yes]",
     "  agent-depot app install|update|uninstall <name> [--yes] [--manual-done]",
     "  agent-depot app uninstall <name> --forget [--yes]",
+    "  agent-depot package list",
+    "  agent-depot package discover <source-id>",
+    "  agent-depot package inspect <selection> --host <host>",
+    "  agent-depot package approve <selection> --host <host> [--action <install|update|uninstall>]",
+    "  agent-depot package install|update|uninstall <selection> --host <host> [--yes]",
+    "  agent-depot package forget <selection> --host <host> --yes",
     `  ${EXPORT_USAGE}`,
     `  ${IMPORT_USAGE}`,
     "  agent-depot tui",
@@ -70,10 +79,18 @@ const SOURCE_SUBCOMMANDS = new Map([
     ["remove", (values, { operations, dependencies, output }) => runSourceRemoval(values, operations, dependencies, output)],
     ["migrate", (values, { operations, dependencies, output }) => runSourceMigration(values, operations, dependencies, output)],
 ]);
+function packageOperationsFor(dependencies, operations) {
+    return dependencies.packageOperations ?? createPackageOperations({
+        ...(dependencies.homeDirectory === undefined ? {} : { homeDirectory: dependencies.homeDirectory }),
+        sourceOperations: operations,
+        ...(dependencies.sourceContentAccess === undefined ? {} : { sourceContentAccess: dependencies.sourceContentAccess }),
+    });
+}
 const COMMANDS = new Map([
-    ["import", (values, { operations, dependencies, output }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies)],
-    ["export", (values, { operations, dependencies, output }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies.stderr ?? (line => console.error(line)), dependencies.homeDirectory)],
+    ["import", (values, { operations, dependencies, output }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, { ...dependencies, packageOperations: packageOperationsFor(dependencies, operations) })],
+    ["export", (values, { operations, dependencies, output }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies.stderr ?? (line => console.error(line)), dependencies.homeDirectory, packageOperationsFor(dependencies, operations))],
     ["app", (values, { dependencies, output }) => runAppCommand(values, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output)],
+    ["package", (values, { operations, dependencies, output }) => runPackageCommand(values, packageOperationsFor(dependencies, operations), operations, output)],
     ["install", async (values, { operations, dependencies, output }) => {
             await runInstall(values, operations, dependencies, output);
             return 0;
@@ -684,8 +701,14 @@ async function runUninstall(argv, operations, dependencies, output) {
 async function runUpdate(argv, operations, dependencies, output) {
     const options = parseUpdateOptions(argv);
     const apps = dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory });
+    const packages = packageOperationsFor(dependencies, operations);
+    const requestedPackages = options.scope === "user-global" && options.requestedPackages.length > 0
+        ? await resolvePackageUpdateSelections(packages, options.requestedPackages)
+        : [];
     let appUpdates = [];
     let appCheckFailed = false;
+    let packageUpdates = [];
+    let packageCheckFailed = false;
     if (options.scope === "user-global") {
         try {
             appUpdates = await checkAppUpdates(apps);
@@ -694,6 +717,13 @@ async function runUpdate(argv, operations, dependencies, output) {
             appCheckFailed = true;
             output(`Error (Apps): ${error instanceof Error ? error.message : String(error)}`);
         }
+        try {
+            packageUpdates = await packages.checkUpdates(requestedPackages.length === 0 ? undefined : requestedPackages);
+        }
+        catch (error) {
+            packageCheckFailed = true;
+            output(`Error (Packages): ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     let loaded;
     try {
@@ -720,10 +750,13 @@ async function runUpdate(argv, operations, dependencies, output) {
     for (const item of appUpdates) {
         output(`App ${item.entry.recipe?.name ?? item.entry.file}: ${item.status}; installed ${item.installedVersion ?? "unknown"}; latest ${item.latestVersion ?? "unknown"}${item.reason ? `; ${item.reason}` : ""}`);
     }
+    for (const item of packageUpdates) {
+        output(describePackageUpdateCheck(item));
+    }
     if (!loaded)
         return 1;
     if (options.action === "check") {
-        return appCheckFailed ? 1 : 0;
+        return appCheckFailed || packageCheckFailed ? 1 : 0;
     }
     const { assessment, context } = loaded;
     const selectedApps = options.all ? appUpdates.filter(item => item.status === "update available")
@@ -734,8 +767,13 @@ async function runUpdate(argv, operations, dependencies, output) {
             }
             return matches[0];
         });
+    const selectedPackages = options.all
+        ? packageUpdates.filter(item => item.status === "update available")
+        : selectPackageUpdateChecks(packageUpdates, requestedPackages);
     const appPlans = [];
+    const packagePlans = [];
     let appFailed = appCheckFailed ? 1 : 0;
+    let packageFailed = packageCheckFailed ? 1 : 0;
     for (const item of selectedApps) {
         try {
             const plan = await apps.planLifecycle(item.entry, "update", undefined, item);
@@ -751,6 +789,24 @@ async function runUpdate(argv, operations, dependencies, output) {
             output(`App ${item.entry.recipe.name}: preview failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    for (const item of selectedPackages) {
+        try {
+            const plan = await packages.planLifecycle(item.installed.selection, "update");
+            const approval = await packages.approvalStatus(item.installed.selection, "update");
+            describeLifecyclePlan(plan, approval, output);
+            if (approval === "approved") {
+                packagePlans.push(plan);
+            }
+            else {
+                packageFailed++;
+                output(`Package ${formatPackageSelection(item.installed.selection)}: needs approval for update`);
+            }
+        }
+        catch (error) {
+            packageFailed++;
+            output(`Package ${formatPackageSelection(item.installed.selection)}: preview failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     const selected = selectUpdateCandidates(assessment, options);
     const { plans, failures: previewFailures, nonCanonicalPaths } = await previewUpdateCandidates(selected, context);
     // Successes and failures are reported in candidate order, as the preview runs.
@@ -803,8 +859,25 @@ async function runUpdate(argv, operations, dependencies, output) {
             output(`App ${plan.entry.recipe.name}: failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    output(`Update summary: ${result.updated.length + appUpdated} updated, ${result.failed.length + appFailed} failed`);
-    return result.failed.length + appFailed === 0 ? 0 : 1;
+    let packageUpdated = 0;
+    for (const plan of packagePlans) {
+        try {
+            const outcome = await packages.executeLifecycle(plan, true);
+            output(`Package ${formatPackageSelection(plan.selection)}: ${describePackageResult(outcome)}`);
+            if (outcome.status === "updated") {
+                packageUpdated++;
+            }
+            else {
+                packageFailed++;
+            }
+        }
+        catch (error) {
+            packageFailed++;
+            output(`Package ${formatPackageSelection(plan.selection)}: failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    output(`Update summary: ${result.updated.length + appUpdated + packageUpdated} updated, ${result.failed.length + appFailed + packageFailed} failed`);
+    return result.failed.length + appFailed + packageFailed === 0 ? 0 : 1;
 }
 function selectUpdateCandidates(assessment, options) {
     if (!options.all && !options.requested.length)
@@ -821,6 +894,35 @@ function selectUpdateCandidates(assessment, options) {
         throw error;
     }
 }
+async function resolvePackageUpdateSelections(packages, requested) {
+    const records = await packages.list();
+    return Object.freeze(requested.map((value) => {
+        const matches = records.filter((record) => packageSelectionMatches(record.selection, value));
+        if (matches.length !== 1) {
+            throw new CliUsageError(matches.length === 0
+                ? `Unknown Package selection ${JSON.stringify(value)}`
+                : `Package selection ${JSON.stringify(value)} is ambiguous`);
+        }
+        return matches[0].selection;
+    }));
+}
+function selectPackageUpdateChecks(checks, selections) {
+    return Object.freeze(selections.map((selection) => {
+        const label = formatPackageSelection(selection);
+        const matches = checks.filter((check) => selectionKey(check.installed.selection) === selectionKey(selection));
+        if (matches.length !== 1) {
+            throw new CliUsageError(`Package ${JSON.stringify(label)} is unknown or not updateable`);
+        }
+        const match = matches[0];
+        if (match.status === "unknown") {
+            throw new CliUsageError(`Package ${JSON.stringify(label)} has unknown version status and is not updateable`);
+        }
+        if (match.status === "current") {
+            throw new CliUsageError(`Package ${JSON.stringify(label)} has no available update`);
+        }
+        return match;
+    }));
+}
 function parseUpdateOptions(argv) {
     const action = argv[0];
     if (action !== "check" && action !== "apply") {
@@ -831,6 +933,7 @@ function parseUpdateOptions(argv) {
     let confirmed = false;
     const requested = [];
     const requestedApps = [];
+    const requestedPackages = [];
     const confirmedPaths = [];
     for (let index = 1; index < argv.length; index += 1) {
         switch (argv[index]) {
@@ -846,6 +949,9 @@ function parseUpdateOptions(argv) {
             case "--app":
                 requestedApps.push(requireOptionValue(argv, ++index, "--app"));
                 break;
+            case "--package":
+                requestedPackages.push(requireOptionValue(argv, ++index, "--package"));
+                break;
             case "--skill":
                 requested.push(requireOptionValue(argv, ++index, "--skill"));
                 break;
@@ -860,15 +966,19 @@ function parseUpdateOptions(argv) {
         throw new CliUsageError("Update scope must be explicit: use --scope project or --scope user-global");
     }
     if (action === "check" && (all || requested.length > 0 || requestedApps.length > 0 || confirmed || confirmedPaths.length > 0)) {
-        throw new CliUsageError("update check only accepts --scope; use update apply to select and apply updates");
+        throw new CliUsageError("update check only accepts --scope and optional --package filters; use update apply to select and apply updates");
     }
-    if (action === "apply" && (all === (requested.length + requestedApps.length > 0))) {
-        throw new CliUsageError("update apply requires exactly one selection mode: --all or one or more --skill/--app values");
+    if (action === "apply" && (all === (requested.length + requestedApps.length + requestedPackages.length > 0))) {
+        throw new CliUsageError("update apply requires exactly one selection mode: --all or one or more --skill/--app/--package values");
     }
     if (requestedApps.length && scope !== "user-global")
         throw new CliUsageError("Apps are user-global only");
+    if (requestedPackages.length && scope !== "user-global")
+        throw new CliUsageError("Packages are user-global only");
     if (new Set(requestedApps).size !== requestedApps.length)
         throw new CliUsageError("Duplicate App selection");
+    if (new Set(requestedPackages).size !== requestedPackages.length)
+        throw new CliUsageError("Duplicate Package selection");
     if (scope === "user-global" && confirmedPaths.length > 0) {
         throw new CliUsageError("--confirm-path only applies to --scope project");
     }
@@ -878,6 +988,7 @@ function parseUpdateOptions(argv) {
         all,
         requested: Object.freeze(requested),
         requestedApps: Object.freeze(requestedApps),
+        requestedPackages: Object.freeze(requestedPackages),
         confirmed,
         confirmedPaths: Object.freeze(confirmedPaths),
     };

package/dist/src/executable-resolution.js

@@ -0,0 +1,54 @@
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import path from "node:path";
+/** A POSIX path on a mounted Windows drive, which WSL cannot execute. */
+export function isWindowsExecutableOnWsl(executable, environment) {
+    const relative = path.posix.relative(environment.wslMountRoot, executable);
+    return environment.isWsl && /^[a-z]\//iu.test(relative);
+}
+/**
+ * Resolves one host executable without a shell. The injected resolver is the
+ * test and embedding seam; otherwise the name is looked up on PATH, and a
+ * Windows executable reachable from WSL is reported as blocked rather than run.
+ */
+export function createPortableExecutableResolver(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const injected = options.resolveExecutable;
+    const wslEnvironment = {
+        isWsl: options.isWsl ?? (platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP)),
+        wslMountRoot: options.wslMountRoot ?? "/mnt",
+    };
+    return async function resolve(name) {
+        if (injected) {
+            const executable = await injected(name);
+            const target = executable ? await realpath(executable).catch(() => executable) : undefined;
+            return { executable, blocked: target !== undefined && isWindowsExecutableOnWsl(target, wslEnvironment) };
+        }
+        let blockedExecutable;
+        const suffixes = platform === "win32"
+            ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")]
+            : [""];
+        for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+            if (!path.isAbsolute(directory)) {
+                continue;
+            }
+            for (const suffix of suffixes) {
+                const candidate = path.join(directory, name + suffix);
+                try {
+                    await access(candidate, platform === "win32" ? constants.F_OK : constants.X_OK);
+                    const target = await realpath(candidate);
+                    if (isWindowsExecutableOnWsl(target, wslEnvironment)) {
+                        blockedExecutable ??= candidate;
+                        continue;
+                    }
+                    // Preserve shim/multicall identity when spawning; realpath is only a safety check.
+                    return { executable: candidate, blocked: false };
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        return { executable: blockedExecutable, blocked: blockedExecutable !== undefined };
+    };
+}

package/dist/src/git-source.js

@@ -18,6 +18,24 @@ const EXCLUDED_LIFECYCLE_SEGMENTS = new Set([
     "deprecated",
     "retired",
 ]);
+/**
+ * One file a Source snapshot carries: a Skill manifest, or a bundle manifest the
+ * Package discovery pass reads. The Pi root `package.json` and the two Claude
+ * `.claude-plugin` manifests sit beside the Skill files in the same immutable
+ * Source view, so one read feeds both passes.
+ */
+export function isSourceSnapshotFile(relativePath, scopeDirectory) {
+    if (path.posix.basename(relativePath) === "SKILL.md") {
+        return true;
+    }
+    const segments = relativePath.split("/");
+    if (segments.at(-2) === ".claude-plugin") {
+        const name = segments.at(-1);
+        return name === "plugin.json" || name === "marketplace.json";
+    }
+    const root = scopeDirectory === undefined || scopeDirectory === "" ? "package.json" : `${scopeDirectory}/package.json`;
+    return relativePath === root;
+}
 export class GitSourceAccessError extends Error {
     constructor(source, reason) {
         super(`Unable to refresh Git Source ${JSON.stringify(source.id)} from ${JSON.stringify(source.url)}: ${reason}`);
@@ -111,14 +129,14 @@ export class GitSourceAccessAdapter {
                 "fetch",
                 "--prune",
                 "--force",
-                source.url,
+                gitSourceLocation(source.url).repositoryUrl,
                 "+refs/*:refs/*",
             ]);
             return;
         }
         const temporaryDestination = `${destination}.${process.pid}.${randomUUID()}.tmp`;
         try {
-            await this.runner.run("git", ["clone", "--mirror", source.url, temporaryDestination]);
+            await this.runner.run("git", ["clone", "--mirror", gitSourceLocation(source.url).repositoryUrl, temporaryDestination]);
             await assertNoSymlinkPath(temporaryDestination, "cache path");
             if ((await pathType(temporaryDestination)) !== "directory") {
                 throw new Error("Git clone did not create a directory mirror");
@@ -170,6 +188,10 @@ export class GitSourceSnapshotAccess {
     /** Reads Skill bytes and the commit they came from as one immutable snapshot. */
     async readSkillTreeSnapshot(source, skillPath) {
         const relativeSkillPath = validateSkillDirectoryPath(skillPath);
+        const directory = gitSourceLocation(source.url).directory;
+        if (directory !== undefined && !relativeSkillPath.startsWith(`${directory}/`) && relativeSkillPath !== directory) {
+            throw new Error("Selected Skill path is outside the Git Source directory");
+        }
         const destination = await this.requireMirror(source);
         const commit = await this.readResolvedCommit(source);
         const tree = await this.runner.run("git", [
@@ -219,7 +241,7 @@ export class GitSourceSnapshotAccess {
     /** Resolves the selected ref to an immutable commit without refreshing the mirror. */
     async readResolvedCommit(source) {
         const destination = await this.requireMirror(source);
-        const revision = source.ref === undefined ? "HEAD" : validateGitRef(source.ref);
+        const revision = validateGitRef(source.ref ?? gitSourceLocation(source.url).ref ?? "HEAD");
         const commit = (await this.runner.run("git", [
             "--git-dir",
             destination,
@@ -235,7 +257,11 @@ export class GitSourceSnapshotAccess {
     async readSnapshot(source) {
         const destination = await this.requireMirror(source);
         const commit = await this.readResolvedCommit(source);
-        const tree = await this.runner.run("git", ["--git-dir", destination, "ls-tree", "-r", "-z", commit]);
+        const directory = gitSourceLocation(source.url).directory;
+        const tree = await this.runner.run("git", [
+            "--git-dir", destination, "ls-tree", "-r", "-z", commit,
+            ...(directory === undefined ? [] : ["--", directory]),
+        ]);
         const files = [];
         for (const record of tree.split("\0")) {
             if (!record) {
@@ -250,7 +276,8 @@ export class GitSourceSnapshotAccess {
             if (metadata[0] === "120000"
                 || metadata[1] !== "blob"
                 || !relativePath
-                || path.posix.basename(relativePath) !== "SKILL.md"
+                || (directory !== undefined && !relativePath.startsWith(`${directory}/`))
+                || !isSourceSnapshotFile(relativePath, directory)
                 || relativePath.split("/").slice(0, -1).some((segment) => EXCLUDED_LIFECYCLE_SEGMENTS.has(segment))) {
                 continue;
             }
@@ -261,6 +288,76 @@ export class GitSourceSnapshotAccess {
         }
         return Object.freeze(files);
     }
+    /** File paths at or under `root`, from the same immutable commit as the other reads. */
+    async listFiles(source, root) {
+        const relativeRoot = root === "" ? "" : validateSkillDirectoryPath(root);
+        const destination = await this.requireMirror(source);
+        const commit = await this.readResolvedCommit(source);
+        const tree = await this.runner.run("git", [
+            "--git-dir", destination, "ls-tree", "-r", "-z", commit,
+            ...(relativeRoot === "" ? [] : ["--", relativeRoot]),
+        ], { maxOutputBytes: SKILL_TREE_LIMITS.maxListingBytes });
+        if (Buffer.byteLength(tree, "utf8") > SKILL_TREE_LIMITS.maxListingBytes) {
+            throw new Error("Source file listing exceeds the safe size limit");
+        }
+        const files = [];
+        for (const record of tree.split("\0")) {
+            if (!record) {
+                continue;
+            }
+            const separator = record.indexOf("\t");
+            if (separator < 0) {
+                continue;
+            }
+            const metadata = record.slice(0, separator).split(" ");
+            const relativePath = record.slice(separator + 1);
+            if (metadata[0] === "120000"
+                || metadata[1] !== "blob"
+                || !relativePath
+                || (relativeRoot !== "" && !relativePath.startsWith(`${relativeRoot}/`))) {
+                continue;
+            }
+            files.push(relativePath);
+        }
+        return Object.freeze(files);
+    }
+    /** One file's text at `path`, or undefined when the commit has no such blob. */
+    async readFile(source, path) {
+        const safePath = validateSkillDirectoryPath(path);
+        const destination = await this.requireMirror(source);
+        const commit = await this.readResolvedCommit(source);
+        const tree = await this.runner.run("git", [
+            "--git-dir", destination, "ls-tree", "-z", commit, "--", safePath,
+        ], { maxOutputBytes: SKILL_TREE_LIMITS.maxListingBytes });
+        for (const record of tree.split("\0")) {
+            if (!record) {
+                continue;
+            }
+            const separator = record.indexOf("\t");
+            if (separator < 0) {
+                continue;
+            }
+            const [mode, objectType, objectId] = record.slice(0, separator).split(" ");
+            const relativePath = record.slice(separator + 1);
+            if (relativePath !== safePath) {
+                continue;
+            }
+            if (objectType !== "blob" || (mode !== "100644" && mode !== "100755")) {
+                return undefined;
+            }
+            if (!objectId || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(objectId)) {
+                throw new Error("Git Source returned an unsafe object reference");
+            }
+            const content = await this.runner.run("git", [
+                "--git-dir", destination, "cat-file", "blob", objectId,
+            ], { maxOutputBytes: SKILL_TREE_LIMITS.maxFileBytes });
+            if (Buffer.byteLength(content, "utf8") > SKILL_TREE_LIMITS.maxFileBytes) {
+                throw new Error(`Source file exceeds the safe size limit: ${safePath}`);
+            }
+            return content;
+        }
+        return undefined;
+    }
 }
 export function defaultGitSourceCachePath(environment = process.env, platform = process.platform, homeDirectory = homedir()) {
     const pathApi = platform === "win32" ? path.win32 : path.posix;
@@ -400,7 +497,33 @@ export function canonicalizeGitSourceUrl(input) {
     if (parsed.pathname === "/" || parsed.pathname.length < 2) {
         throw new Error("Git Source URL must identify a repository path");
     }
-    return parsed.toString();
+    const canonicalUrl = parsed.toString();
+    gitSourceLocation(canonicalUrl);
+    return canonicalUrl;
+}
+/** The GitHub tree/<ref>/<directory> shape, parsed once so the Catalog label cannot describe a different scope than the clone and tree walk use. */
+export function githubTreeLocation(url) {
+    const parsed = new URL(url);
+    const segments = parsed.pathname.split("/").slice(1);
+    if (parsed.hostname !== "github.com" || !["https:", "http:"].includes(parsed.protocol) || segments[2] !== "tree") {
+        return undefined;
+    }
+    if (segments.length < 4 || !segments[0] || !segments[1] || !segments[3]) {
+        throw new Error("GitHub directory Source URL must include an owner, repository, and ref");
+    }
+    const ref = validateGitRef(decodeURIComponent(segments[3]));
+    if (ref.startsWith("-"))
+        throw new Error("GitHub directory Source ref must not start with a dash");
+    const directory = segments.length > 4
+        ? validateSkillDirectoryPath(segments.slice(4).map((segment) => decodeURIComponent(segment)).join("/"))
+        : undefined;
+    const repository = `${segments[0]}/${segments[1]}`;
+    parsed.pathname = `/${repository}`;
+    return { repository, repositoryUrl: parsed.toString(), ref, ...(directory === undefined ? {} : { directory }) };
+}
+/** Keep the registered URL (and identity) while deriving Git transport and discovery scope. */
+function gitSourceLocation(url) {
+    return githubTreeLocation(url) ?? { repositoryUrl: url };
 }
 export function sourceIdForUrl(url) {
     const canonicalUrl = canonicalizeGitSourceUrl(url);