akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/sources/providers/git-install.js

@@ -0,0 +1,210 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../../core/errors.js";
+import { getRegistryCacheDir } from "../../core/paths.js";
+import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve.js";
+import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, } from "./provider-utils.js";
+/**
+ * Shared subprocess wrapper for `git` invocations. Disables git's interactive
+ * terminal prompt so a missing credential never hangs the process.
+ */
+export function runGit(args, options) {
+    return spawnSync("git", args, {
+        encoding: "utf8",
+        ...options,
+        env: { ...process.env, ...options?.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+}
+/**
+ * Sync mode for a one-shot install ref (`akm add github:owner/repo` or
+ * `akm add git:url`). Runs the clone → strip → include-filter pipeline that
+ * historically lived in `installRegistryRef()`.
+ */
+export async function syncRegistryGitRef(ref, options) {
+    const parsed = parseRegistryRef(ref);
+    if (parsed.source === "github") {
+        const githubRef = {
+            source: "git",
+            ref: parsed.ref,
+            id: parsed.id,
+            url: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+            requestedRef: parsed.requestedRef,
+        };
+        const result = await doSyncGit(githubRef, options);
+        return { ...result, source: "github" };
+    }
+    if (parsed.source !== "git") {
+        throw new UsageError(`syncRegistryGitRef requires a git: or github: ref, got "${ref}"`);
+    }
+    return doSyncGit(parsed, options);
+}
+async function doSyncGit(parsed, options) {
+    const resolved = await resolveRegistryArtifact(parsed);
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
+    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
+    const cloneDir = path.join(cacheDir, "clone");
+    const extractedDir = path.join(cacheDir, "extracted");
+    // Cache hit
+    if (!options?.force && isDirectory(extractedDir)) {
+        try {
+            const provisionalKitRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            const stashRoot = detectStashRoot(installRoot);
+            if (stashRoot) {
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    contentDir: stashRoot,
+                    cacheDir,
+                    extractedDir,
+                    writable: options?.writable,
+                    syncedAt,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-clone
+        }
+    }
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // Validate URL and ref before passing to git to prevent command injection
+    validateGitUrl(parsed.url);
+    if (parsed.requestedRef)
+        validateGitRef(parsed.requestedRef);
+    let provisionalKitRoot;
+    let installRoot;
+    let stashRoot;
+    try {
+        const cloneArgs = ["clone", "--depth", "1"];
+        if (parsed.requestedRef) {
+            cloneArgs.push("--branch", parsed.requestedRef);
+        }
+        cloneArgs.push(parsed.url, cloneDir);
+        const cloneResult = runGit(cloneArgs, { timeout: 120_000 });
+        if (cloneResult.status !== 0) {
+            throw new Error(classifyCloneFailure(parsed.url, cloneResult.stderr, cloneResult.error));
+        }
+        // Copy contents to extracted dir without .git
+        fs.mkdirSync(extractedDir, { recursive: true });
+        copyDirectoryContents(cloneDir, extractedDir);
+        // Clean up the clone dir
+        fs.rmSync(cloneDir, { recursive: true, force: true });
+        provisionalKitRoot = detectStashRoot(extractedDir);
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        stashRoot = detectStashRoot(installRoot);
+    }
+    catch (err) {
+        // Clean up the cache directory so stale or partially-cloned artifacts
+        // don't cause false cache hits on the next install attempt.
+        try {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: resolved.resolvedRevision,
+        contentDir: stashRoot,
+        cacheDir,
+        extractedDir,
+        writable: options?.writable,
+        syncedAt,
+    };
+}
+export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
+    // Stage the clone into a sibling temp dir so that a failed clone never
+    // destroys a previously-valid destDir (e.g. when the remote is temporarily
+    // unreachable and we have a valid cached copy).
+    const tmpDir = `${destDir}.tmp-${randomBytes(4).toString("hex")}`;
+    const args = ["clone", "--depth", "1"];
+    if (ref)
+        args.push("--branch", ref);
+    args.push(cloneUrl, tmpDir);
+    const result = runGit(args, { timeout: 120_000 });
+    if (result.status !== 0) {
+        // Clean up the (possibly partial) temp dir but leave destDir untouched.
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        throw new Error(classifyCloneFailure(cloneUrl, result.stderr, result.error));
+    }
+    try {
+        if (!writable) {
+            // Remove .git directory — we only need the working tree for read-only stashes
+            const gitDir = path.join(tmpDir, ".git");
+            if (fs.existsSync(gitDir))
+                fs.rmSync(gitDir, { recursive: true, force: true });
+        }
+        // Swap: remove the old destDir (if any) then atomically rename tmpDir into place.
+        if (fs.existsSync(destDir))
+            fs.rmSync(destDir, { recursive: true, force: true });
+        fs.renameSync(tmpDir, destDir);
+    }
+    catch (err) {
+        // Post-clone steps failed — clean up the temp dir to avoid orphaned dirs.
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+// ── Clone-failure classification (#487) ─────────────────────────────────────
+/**
+ * Translate git's stderr into an actionable message. Without this, a user
+ * who passes a nonexistent or private repo to `akm add` sees:
+ *
+ *   "could not read Username for 'https://github.com': No such device or
+ *    address"
+ *
+ * That is git falling through to its auth-prompt path — the actual cause
+ * is "repo doesn't exist (or is private)". We classify the common patterns
+ * and emit a message that names the cause and the fix.
+ */
+export function classifyCloneFailure(url, stderr, spawnError) {
+    const safeUrl = redactUrlUserinfo(url);
+    const raw = (stderr ?? "").trim();
+    const spawnMsg = spawnError?.message ?? "";
+    // `git` binary not on PATH.
+    if (spawnError?.code === "ENOENT") {
+        return `Failed to clone ${safeUrl}: 'git' is not installed or not on PATH. Install git, then re-run.`;
+    }
+    // Auth-prompt fall-through (the headline #487 case).
+    if (/could not read Username|terminal prompts disabled|Authentication failed|fatal: Authentication/i.test(raw)) {
+        return (`Failed to clone ${safeUrl}: repository not found or private. ` +
+            `If the repository is public, double-check the URL and try again. ` +
+            `If it is private, set GH_TOKEN (or configure a git credential helper) before re-running.`);
+    }
+    // 404-style messages from git http.
+    if (/repository '.*' not found|HTTP 404|fatal: remote error|not found:|Not Found/i.test(raw)) {
+        return (`Failed to clone ${safeUrl}: repository not found. ` +
+            `Check the URL — for GitHub, the form is 'owner/repo' or 'github:owner/repo'.`);
+    }
+    // SSH connection issues.
+    if (/Permission denied \(publickey\)|kex_exchange_identification|Connection refused|Connection timed out/i.test(raw)) {
+        return (`Failed to clone ${safeUrl}: network or SSH failure. ` +
+            `Check connectivity, your SSH agent, and the remote host's availability.`);
+    }
+    // Branch / ref-specific failures.
+    if (/Remote branch .* not found in upstream origin|couldn't find remote ref/i.test(raw)) {
+        return (`Failed to clone ${safeUrl}: the requested branch/tag does not exist on the remote. ` +
+            `Verify the ref name and re-run.`);
+    }
+    const detail = raw || spawnMsg || "unknown error";
+    return `Failed to clone ${safeUrl}: ${redactUrlUserinfo(detail)}`;
+}
+function redactUrlUserinfo(text) {
+    return text.replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^\s/@]+)@/g, "$1[REDACTED]@");
+}

package/dist/sources/providers/git-provider.js

@@ -0,0 +1,234 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { getRegistryIndexCacheDir } from "../../core/paths.js";
+import { validateGitUrl } from "../../registry/resolve.js";
+import { registerSourceProvider } from "../provider-factory.js";
+import { cloneRepo, runGit, syncRegistryGitRef } from "./git-install.js";
+import { isExpired, sanitizeString } from "./provider-utils.js";
+/** Cache TTL before refreshing the mirrored repo (12 hours). */
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+/** Maximum stale age allowed when refresh fails (7 days). */
+const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Git source provider — clones (and re-pulls) a remote repo into a local
+ * cache directory. Implements the v1 {@link SourceProvider} interface (spec
+ * §2.1, §2.5): `{ name, kind, init, path, sync }`.
+ *
+ * Reading is the indexer's job — this class doesn't implement `search` or
+ * `show`. The install-time helpers `syncRegistryGitRef` / `syncMirroredRepo`
+ * live below as standalone functions used by `akm add` / `akm update`.
+ */
+export class GitSourceProvider {
+    kind = "git";
+    name;
+    #config;
+    #path = null;
+    constructor(config) {
+        this.#config = config;
+        this.name = config.name ?? "git";
+    }
+    path() {
+        if (this.#path == null) {
+            // Lazy resolution: providers are sometimes constructed without an
+            // explicit init() call (e.g. by legacy callers that just want the
+            // path). Resolve on demand and cache.
+            this.#path = resolveGitContentDir(this.#config);
+        }
+        return this.#path;
+    }
+    async sync(options) {
+        // Two execution modes:
+        //   1. Long-lived configured source (config.url) — mirror into the
+        //      registry-index cache and serve as a read-only working tree.
+        //   2. One-shot install ref (options.ref like "git:..." / "github:...") —
+        //      delegate to the install-time pipeline.
+        if (typeof this.#config.options?.ref === "string" && this.#config.options.ref) {
+            await syncRegistryGitRef(String(this.#config.options.ref), { force: options?.force });
+            return;
+        }
+        await syncMirroredRepo(this.#config, { force: options?.force });
+    }
+}
+/** Resolve the on-disk content directory for a configured git source. */
+function resolveGitContentDir(config) {
+    if (config.path)
+        return config.path;
+    if (config.url) {
+        const repo = parseGitRepoUrl(config.url);
+        return getCachePaths(repo.canonicalUrl).repoDir;
+    }
+    throw new ConfigError("git source entry must have either `path` or `url`");
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerSourceProvider("git", (config) => new GitSourceProvider(config));
+// ── Cache management ────────────────────────────────────────────────────────
+export function getCachePaths(repoUrl) {
+    const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
+    const cacheRoot = getRegistryIndexCacheDir();
+    const rootDir = path.join(cacheRoot, `git-${key}`);
+    return {
+        rootDir,
+        repoDir: path.join(rootDir, "repo"),
+        indexPath: path.join(rootDir, "index.json"),
+    };
+}
+export async function ensureGitMirror(repo, cachePaths, options) {
+    const requireRepoDir = options?.requireRepoDir === true;
+    const writable = options?.writable === true;
+    const force = options?.force === true;
+    // Check if cache is fresh
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(cachePaths.indexPath).mtimeMs;
+    }
+    catch {
+        /* no cached index */
+    }
+    if (!force && mtime && !isExpired(mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+        return;
+    }
+    try {
+        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
+        if (writable && fs.existsSync(path.join(cachePaths.repoDir, ".git"))) {
+            // Writable repo already cloned — pull instead of re-clone to preserve local changes
+            pullRepo(cachePaths.repoDir);
+        }
+        else {
+            cloneRepo(repo.cloneUrl, repo.ref, cachePaths.repoDir, writable);
+        }
+        // Touch index file to track freshness
+        fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
+    }
+    catch (err) {
+        if (mtime && !isExpired(mtime, CACHE_STALE_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * Sync mode for a long-lived configured git stash. Mirrors the repo into the
+ * shared registry-index cache (12h TTL) and exposes the working tree as the
+ * stash content directory.
+ */
+export async function syncMirroredRepo(config, options) {
+    if (!config.url) {
+        throw new ConfigError("git stash entry requires a URL when no install ref is supplied");
+    }
+    const repo = parseGitRepoUrl(config.url);
+    const cachePaths = getCachePaths(repo.canonicalUrl);
+    await ensureGitMirror(repo, cachePaths, {
+        requireRepoDir: true,
+        writable: options?.writable ?? config.writable === true,
+        force: options?.force,
+    });
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    const contentDir = cachePaths.repoDir;
+    return {
+        id: repo.canonicalUrl,
+        source: "git",
+        ref: repo.canonicalUrl,
+        artifactUrl: repo.canonicalUrl,
+        contentDir,
+        cacheDir: cachePaths.rootDir,
+        extractedDir: contentDir,
+        writable: options?.writable ?? config.writable === true,
+        syncedAt,
+    };
+}
+function pullRepo(repoDir) {
+    const result = runGit(["-C", repoDir, "pull", "--ff-only"], {
+        timeout: 120_000,
+    });
+    if (result.status !== 0) {
+        const err = result.stderr?.trim() || result.error?.message || "unknown error";
+        throw new Error(`Failed to pull ${repoDir}: ${err}`);
+    }
+}
+function hasExtractedRepo(repoDir) {
+    try {
+        if (!fs.statSync(repoDir).isDirectory())
+            return false;
+        if (fs.statSync(path.join(repoDir, "content")).isDirectory())
+            return true;
+    }
+    catch {
+        /* fall through to root-layout detection */
+    }
+    try {
+        if (!fs.statSync(repoDir).isDirectory())
+            return false;
+        return Object.values(TYPE_DIRS).some((dirName) => fs.existsSync(path.join(repoDir, dirName)));
+    }
+    catch {
+        return false;
+    }
+}
+export function parseGitRepoUrl(rawUrl) {
+    if (!rawUrl) {
+        throw new ConfigError("Git provider requires a repository URL");
+    }
+    // SSH shorthand: git@host:path — valid as-is, delegated to system git credentials
+    if (/^git@[^:]+:.+$/.test(rawUrl)) {
+        return { cloneUrl: rawUrl, ref: null, canonicalUrl: rawUrl };
+    }
+    // Validate URL scheme is safe before parsing
+    try {
+        validateGitUrl(rawUrl);
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw new ConfigError(err.message);
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`Git provider URL is not valid: "${rawUrl}"`);
+    }
+    // GitHub web URLs: extract a clean clone URL and optional branch from /tree/<ref>
+    if (parsed.hostname === "github.com" && parsed.protocol === "https:") {
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        if (segments.length < 2) {
+            throw new ConfigError(`Git provider URL must point to a repository, got "${rawUrl}"`);
+        }
+        const owner = sanitizeString(segments[0]);
+        const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
+        if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+            throw new ConfigError(`Unsupported repository URL: "${rawUrl}"`);
+        }
+        let ref = null;
+        if (segments[2] === "tree" && segments.length >= 4) {
+            const rawRef = sanitizeString(segments.slice(3).join("/"), 255);
+            if (rawRef && !rawRef.includes("..") && /^[A-Za-z0-9._/-]+$/.test(rawRef)) {
+                ref = rawRef;
+            }
+        }
+        const cloneUrl = `https://github.com/${owner}/${repo}`;
+        const canonicalUrl = ref ? `${cloneUrl}/tree/${ref}` : cloneUrl;
+        return { cloneUrl, ref, canonicalUrl };
+    }
+    // Any other valid git URL: use as-is for cloning, but strip embedded credentials
+    // from canonicalUrl so secrets don't leak into cache keys or warning messages.
+    let canonicalUrl = rawUrl;
+    try {
+        const u = new URL(rawUrl);
+        u.username = "";
+        u.password = "";
+        u.search = "";
+        u.hash = "";
+        canonicalUrl = u.toString();
+    }
+    catch {
+        // URL failed to parse — fall back to raw (validateGitUrl already accepted it)
+    }
+    return { cloneUrl: rawUrl, ref: null, canonicalUrl };
+}