akm-cli 0.4.1 → 0.5.0-rc2

package/dist/local-search.js

@@ -14,7 +14,7 @@ import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { buildSearchText } from "./indexer";
-import { generateMetadataFlat, loadStashFile } from "./metadata";
+import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
@@ -619,6 +619,8 @@ async function indexAssets(stashDir, type) {
                         fileBasenameMap.get(entry.name.split("/").pop() ?? "") ??
                         (files[0] || dirPath);
             }
+            if (!shouldIndexStashFile(stashDir, entryPath))
+                continue;
             assets.push({ entry, path: entryPath });
         }
     }

package/dist/matchers.js

@@ -1,7 +1,7 @@
 /**
  * Built-in asset matchers for the akm file classification system.
  *
- * Four matchers are registered at module load time, each at a different
+ * Five matchers are registered at module load time, each at a different
  * specificity level. Extension and content determine type; directories are
  * optional specificity boosts, not requirements.
  *
@@ -15,6 +15,8 @@
  *   and body content for agent/command signals; falls back to "knowledge"
  *   at specificity 5 when no signals are found. Command signals (`agent`
  *   frontmatter, `$ARGUMENTS`/`$1`-`$3` placeholders) return 18.
+ * - `wikiMatcher` (20) -- classifies any `.md` under `wikis/<name>/…` as
+ *   `wiki`. Registered last so the later-wins tiebreaker beats agent at 20.
  */
 import { SCRIPT_EXTENSIONS } from "./asset-spec";
 import { registerMatcher } from "./file-context";
@@ -32,7 +34,9 @@ import { registerMatcher } from "./file-context";
 export function extensionMatcher(ctx) {
     // SKILL.md is a skill regardless of location — high specificity beats
     // smartMdMatcher's knowledge fallback and all directory-based matchers.
-    if (ctx.fileName === "SKILL.md") {
+    // Exception: files under wikis/<name>/… are always wiki pages; the wiki
+    // directory is an authoritative signal that outranks the filename.
+    if (ctx.fileName === "SKILL.md" && !ctx.ancestorDirs.includes("wikis")) {
         return { type: "skill", specificity: 25, renderer: "skill-md" };
     }
     // Known script extensions (excluding .md, handled by smartMdMatcher)
@@ -68,9 +72,15 @@ export function directoryMatcher(ctx) {
         if (dir === "knowledge" && ext === ".md") {
             return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
         }
+        if (dir === "workflows" && ext === ".md") {
+            return { type: "workflow", specificity: 10, renderer: "workflow-md" };
+        }
         if (dir === "memories" && ext === ".md") {
             return { type: "memory", specificity: 10, renderer: "memory-md" };
         }
+        if (dir === "vaults" && (ctx.fileName === ".env" || ctx.fileName.endsWith(".env"))) {
+            return { type: "vault", specificity: 10, renderer: "vault-env" };
+        }
     }
     return null;
 }
@@ -98,9 +108,15 @@ export function parentDirHintMatcher(ctx) {
     if (parentDir === "knowledge" && ext === ".md") {
         return { type: "knowledge", specificity: 15, renderer: "knowledge-md" };
     }
+    if (parentDir === "workflows" && ext === ".md") {
+        return { type: "workflow", specificity: 15, renderer: "workflow-md" };
+    }
     if (parentDir === "memories" && ext === ".md") {
         return { type: "memory", specificity: 15, renderer: "memory-md" };
     }
+    if (parentDir === "vaults" && (fileName === ".env" || fileName.endsWith(".env"))) {
+        return { type: "vault", specificity: 15, renderer: "vault-env" };
+    }
     return null;
 }
 // ── smartMdMatcher (specificity: 20 / 18 / 8 / 5) ──────────────────────────
@@ -123,6 +139,14 @@ const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 export function smartMdMatcher(ctx) {
     if (ctx.ext !== ".md")
         return null;
+    const body = ctx.content();
+    const hasWorkflowSignals = /^#\s+Workflow:\s+/m.test(body) &&
+        /^##\s+Step:\s+/m.test(body) &&
+        /^Step ID:\s+/m.test(body) &&
+        /^###\s+Instructions\s*$/m.test(body);
+    if (hasWorkflowSignals) {
+        return { type: "workflow", specificity: 19, renderer: "workflow-md" };
+    }
     const fm = ctx.frontmatter();
     if (fm) {
         // Agent-exclusive indicators: toolPolicy or tools
@@ -138,7 +162,6 @@ export function smartMdMatcher(ctx) {
     }
     // Command signal: body contains $ARGUMENTS or $1/$2/$3 placeholders.
     // These are definitively command template patterns (OpenCode convention).
-    const body = ctx.content();
     if (COMMAND_PLACEHOLDER_RE.test(body)) {
         return { type: "command", specificity: 18, renderer: "command-md" };
     }
@@ -154,9 +177,38 @@ export function smartMdMatcher(ctx) {
     // Weak fallback: any .md file is assumed to be knowledge
     return { type: "knowledge", specificity: 5, renderer: "knowledge-md" };
 }
+// ── wikiMatcher (specificity: 20) ──────────────────────────────────────────
+/**
+ * Classify any `.md` file that lives under `wikis/<name>/…` as `wiki`.
+ *
+ * Registered AFTER `smartMdMatcher` so the registered-later-wins tiebreaker
+ * puts wiki ahead of agent at specificity 20. That means a wiki page with
+ * agent-style frontmatter (e.g. `tools:`) still classifies as a wiki page,
+ * not an agent. That's intentional — the directory is the authoritative
+ * signal: files under `wikis/` are wiki content.
+ *
+ * Requires at least one path segment after `wikis/` (the wiki name) — a
+ * stray `.md` at the bare `wikis/` root is not a wiki page.
+ */
+export function wikiMatcher(ctx) {
+    if (ctx.ext !== ".md")
+        return null;
+    const idx = ctx.ancestorDirs.indexOf("wikis");
+    if (idx < 0)
+        return null;
+    if (idx + 1 >= ctx.ancestorDirs.length)
+        return null;
+    return { type: "wiki", specificity: 20, renderer: "wiki-md" };
+}
 // ── Registration ────────────────────────────────────────────────────────────
 /** All built-in matchers in registration order (later wins ties). */
-const builtinMatchers = [extensionMatcher, directoryMatcher, parentDirHintMatcher, smartMdMatcher];
+const builtinMatchers = [
+    extensionMatcher,
+    directoryMatcher,
+    parentDirHintMatcher,
+    smartMdMatcher,
+    wikiMatcher,
+];
 /**
  * Register all built-in matchers with the file-context registry.
  * Called once from the CLI entry point (or ensureBuiltinsRegistered).

package/dist/metadata.js

@@ -133,6 +133,30 @@ export function validateStashEntry(entry) {
         result.cwd = e.cwd.trim();
     if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
         result.fileSize = e.fileSize;
+    if (e.wikiRole === "schema" ||
+        e.wikiRole === "index" ||
+        e.wikiRole === "log" ||
+        e.wikiRole === "raw" ||
+        e.wikiRole === "page") {
+        result.wikiRole = e.wikiRole;
+    }
+    if (typeof e.pageKind === "string" && e.pageKind.trim().length > 0) {
+        result.pageKind = e.pageKind.trim();
+    }
+    if (Array.isArray(e.xrefs)) {
+        const filtered = e.xrefs
+            .filter((x) => typeof x === "string" && x.trim().length > 0)
+            .map((x) => x.trim());
+        if (filtered.length > 0)
+            result.xrefs = filtered;
+    }
+    if (Array.isArray(e.sources)) {
+        const filtered = e.sources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((s) => s.trim());
+        if (filtered.length > 0)
+            result.sources = filtered;
+    }
     if (Array.isArray(e.parameters)) {
         const validated = e.parameters
             .filter((p) => {
@@ -196,6 +220,68 @@ export function extractCommandParameters(template) {
     }
     return params.length > 0 ? params : undefined;
 }
+/**
+ * Extract wiki frontmatter fields (wikiRole, pageKind, xrefs, sources) from a parsed
+ * frontmatter block and apply them to the entry. Tolerates missing or malformed values.
+ */
+export function applyWikiFrontmatter(entry, fmData) {
+    const role = fmData.wikiRole;
+    if (role === "schema" || role === "index" || role === "log" || role === "raw" || role === "page") {
+        entry.wikiRole = role;
+    }
+    const pageKind = fmData.pageKind;
+    if (typeof pageKind === "string" && pageKind.trim().length > 0) {
+        entry.pageKind = pageKind.trim();
+    }
+    const xrefs = fmData.xrefs;
+    if (Array.isArray(xrefs)) {
+        const filtered = xrefs
+            .filter((x) => typeof x === "string" && x.trim().length > 0)
+            .map((x) => x.trim());
+        if (filtered.length > 0)
+            entry.xrefs = filtered;
+    }
+    const sources = fmData.sources;
+    if (Array.isArray(sources)) {
+        const filtered = sources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((s) => s.trim());
+        if (filtered.length > 0)
+            entry.sources = filtered;
+    }
+}
+const WIKI_INFRA_FILES = new Set(["schema.md", "index.md", "log.md"]);
+/**
+ * Apply wiki-specific index exclusions while leaving all other stash files
+ * untouched.
+ *
+ * - In a normal stash, excludes `wikis/<name>/raw/**` and wiki-root
+ *   `schema.md`, `index.md`, `log.md`.
+ * - In a wiki-root stash source (`wikiName`), excludes `raw/**` and those same
+ *   root-level infrastructure files.
+ */
+export function shouldIndexStashFile(stashRoot, file, options) {
+    const relPath = path.relative(stashRoot, file);
+    if (!relPath || relPath.startsWith("..") || path.isAbsolute(relPath))
+        return true;
+    const segments = relPath.split(/[\\/]+/).filter(Boolean);
+    if (segments.length === 0)
+        return true;
+    if (options?.treatStashRootAsWikiRoot) {
+        if (segments[0] === "raw")
+            return false;
+        return !(segments.length === 1 && WIKI_INFRA_FILES.has(segments[0]));
+    }
+    const wikisIdx = segments.indexOf("wikis");
+    if (wikisIdx < 0 || wikisIdx + 1 >= segments.length)
+        return true;
+    const wikiRelativeSegments = segments.slice(wikisIdx + 2);
+    if (wikiRelativeSegments.length === 0)
+        return true;
+    if (wikiRelativeSegments[0] === "raw")
+        return false;
+    return !(wikiRelativeSegments.length === 1 && WIKI_INFRA_FILES.has(wikiRelativeSegments[0]));
+}
 /**
  * Extract `@param` JSDoc tags from a script file's leading comment block.
  *
@@ -316,6 +402,8 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
+            // Pass wiki-pattern frontmatter through onto the entry
+            applyWikiFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -324,8 +412,11 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
                 }
             }
         }
-        // Extract @param from script files
-        if (ext !== ".md") {
+        // Extract @param from script files.
+        // Vault files (.env) are deliberately excluded — their contents are secrets
+        // and must never be parsed for @param or any other metadata that could
+        // embed a value into the entry.
+        if (ext !== ".md" && assetType !== "vault") {
             const scriptParams = extractScriptParameters(file);
             if (scriptParams)
                 entry.parameters = scriptParams;
@@ -369,6 +460,8 @@ export async function generateMetadataFlat(stashRoot, files) {
     const entries = [];
     const pkgMetaCache = new Map();
     for (const file of files) {
+        if (!shouldIndexStashFile(stashRoot, file))
+            continue;
         const ctx = buildFileContext(stashRoot, file);
         const match = await runMatchers(ctx);
         if (!match)
@@ -418,6 +511,8 @@ export async function generateMetadataFlat(stashRoot, files) {
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
+            // Pass wiki-pattern frontmatter through onto the entry
+            applyWikiFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -426,8 +521,11 @@ export async function generateMetadataFlat(stashRoot, files) {
                 }
             }
         }
-        // Extract @param from script files
-        if (ext !== ".md") {
+        // Extract @param from script files.
+        // Vault files (.env) are deliberately excluded — their contents are secrets
+        // and must never be parsed for @param or any other metadata that could
+        // embed a value into the entry.
+        if (ext !== ".md" && assetType !== "vault") {
             const scriptParams = extractScriptParameters(file, ctx.content());
             if (scriptParams)
                 entry.parameters = scriptParams;

package/dist/migration-help.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
+const EMBEDDED_MIGRATION_GUIDES = {
+    "0.5.0": `Migration notes for akm v0.5.0
+
+- New top-level surfaces: \`akm wiki …\`, \`akm workflow …\`, \`akm vault …\`, and \`akm save\`.
+- If you tried the unreleased single-wiki LLM prototype, move to the new \`akm wiki …\` workflow.
+- Removed from the prototype surface: \`akm lint\`, \`akm import --llm\`, \`akm import --dry-run\`, \`knowledge.pageKinds\`, and the old ingest/lint LLM prompts.
+- Existing raw wiki-like content should be moved into \`wikis/<name>/raw/\` and then managed with the new wiki commands.
+`,
+    "0.3.0": `Migration notes for akm v0.3.0
+
+- The old \`stash\` and \`kit\` command groups were folded into the top-level CLI.
+- Use \`akm add\`, \`akm list\`, and \`akm remove\` instead of the older split command surfaces.
+- Documentation and examples from older releases should be updated to the unified source model.
+`,
+    "0.2.0": `Migration notes for akm v0.2.0
+
+- Asset refs are user-facing \`type:name\` values; do not rely on URI-style refs.
+- The old fixed asset-type union was replaced by an extensible asset type system.
+- \`tool\` assets were removed; use \`script\` assets instead.
+- Config and docs should treat remote provider scores and local scores as part of one shared search pipeline.
+`,
+    "0.1.0": `Migration notes for akm v0.1.0
+
+- The package and project were rebranded from Agent-i-Kit to akm.
+- Update package references from \`agent-i-kit\` to \`akm-cli\`.
+- Update config, registry, plugin, path, and environment-variable references from \`agent-i-kit\` / \`AGENT_I_KIT_*\` to \`akm\` / \`AKM_*\`.
+- The \`tool\` asset type and \`submit\` command were removed.
+`,
+    "0.0.13": `Migration notes for akm v0.0.13
+
+- Initial public release.
+- No migration steps are required for earlier akm versions.
+`,
+};
+function loadChangelog() {
+    try {
+        const changelogPath = path.resolve(import.meta.dir, "../CHANGELOG.md");
+        if (fs.existsSync(changelogPath)) {
+            return fs.readFileSync(changelogPath, "utf8");
+        }
+    }
+    catch {
+        // fall through to embedded notes
+    }
+    return undefined;
+}
+function escapeRegexString(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeRequestedVersion(input) {
+    const value = input.trim();
+    if (!value)
+        return value;
+    if (value.toLowerCase() === "latest")
+        return "latest";
+    const withoutV = value.replace(/^v/i, "");
+    return withoutV;
+}
+function versionCandidates(requested) {
+    if (requested === "latest")
+        return ["latest"];
+    const exact = requested;
+    const stable = requested.replace(/[-+].*$/, "");
+    return stable === exact ? [exact] : [exact, stable];
+}
+function resolveLatestVersion(changelog) {
+    for (const match of changelog.matchAll(/^## \[([^\]]+)\]/gm)) {
+        const version = match[1];
+        if (version !== "Unreleased")
+            return version;
+    }
+    return undefined;
+}
+function extractChangelogSection(changelog, version) {
+    const pattern = new RegExp(`^## \\[${escapeRegexString(version)}\\][^\\n]*\\n([\\s\\S]*?)(?=^## \\[|\\Z)`, "m");
+    const match = changelog.match(pattern);
+    if (!match)
+        return undefined;
+    return `## [${version}]\n${match[1].trim()}\n`;
+}
+function fallbackGuide(version) {
+    const embedded = EMBEDDED_MIGRATION_GUIDES[version];
+    if (embedded)
+        return `${embedded.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+    return `No dedicated migration note is bundled for akm v${version}.\n\nSee the full changelog: ${CHANGELOG_URL}\n`;
+}
+export function renderMigrationHelp(versionInput, changelogText = loadChangelog()) {
+    const requested = normalizeRequestedVersion(versionInput);
+    if (!requested) {
+        return `Version is required.\n\nUsage: akm help migrate <version>\n`;
+    }
+    const resolvedLatest = changelogText ? resolveLatestVersion(changelogText) : undefined;
+    const candidates = requested === "latest" && resolvedLatest ? [resolvedLatest] : versionCandidates(requested);
+    if (changelogText) {
+        for (const candidate of candidates) {
+            const section = extractChangelogSection(changelogText, candidate);
+            if (section) {
+                const embedded = EMBEDDED_MIGRATION_GUIDES[candidate];
+                if (!embedded)
+                    return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+                return `${embedded.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            }
+        }
+    }
+    const fallbackVersion = candidates.find((candidate) => candidate !== "latest") ?? requested;
+    return fallbackGuide(fallbackVersion);
+}

package/dist/paths.js

@@ -68,6 +68,9 @@ export function getCacheDir() {
 export function getDbPath() {
     return path.join(getCacheDir(), "index.db");
 }
+export function getWorkflowDbPath() {
+    return path.join(getCacheDir(), "workflow.db");
+}
 export function getSemanticStatusPath() {
     return path.join(getCacheDir(), "semantic-status.json");
 }

package/dist/registry-install.js

@@ -20,6 +20,9 @@ export async function installRegistryRef(ref, options) {
     if (parsed.source === "git") {
         return installGitRegistryRef(parsed, config, options);
     }
+    if (parsed.source === "github") {
+        return installGithubRegistryRef(parsed, config, options);
+    }
     const resolved = await resolveRegistryArtifact(parsed);
     const registryLabels = deriveRegistryLabels({
         source: resolved.source,
@@ -38,7 +41,7 @@ export async function installRegistryRef(ref, options) {
             const cachedStashRoot = detectStashRoot(extractedDir);
             if (cachedStashRoot) {
                 const integrity = fs.existsSync(archivePath) ? await computeFileHash(archivePath) : undefined;
-                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -51,6 +54,7 @@ export async function installRegistryRef(ref, options) {
                     extractedDir,
                     stashRoot: cachedStashRoot,
                     integrity,
+                    writable: options?.writable,
                     audit,
                 };
             }
@@ -70,7 +74,7 @@ export async function installRegistryRef(ref, options) {
         verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
-        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -98,9 +102,24 @@ export async function installRegistryRef(ref, options) {
         extractedDir,
         stashRoot,
         integrity,
+        writable: options?.writable,
         audit,
     };
 }
+async function installGithubRegistryRef(parsed, config, options) {
+    const gitParsed = {
+        source: "git",
+        ref: parsed.ref,
+        id: parsed.id,
+        url: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+        requestedRef: parsed.requestedRef,
+    };
+    const installed = await installGitRegistryRef(gitParsed, config, options);
+    return {
+        ...installed,
+        source: "github",
+    };
+}
 async function installLocalRegistryRef(parsed, config, options) {
     const resolved = await resolveRegistryArtifact(parsed);
     const installedAt = (options?.now ?? new Date()).toISOString();
@@ -109,7 +128,7 @@ async function installLocalRegistryRef(parsed, config, options) {
         ref: resolved.ref,
         artifactUrl: resolved.artifactUrl,
     });
-    const audit = runInstallAuditOrThrow(parsed.sourcePath, resolved.source, resolved.ref, registryLabels, config);
+    const audit = runInstallAuditOrThrow(parsed.sourcePath, resolved.source, resolved.ref, registryLabels, config, options);
     // For local directories, detect the stash root within the source path.
     // If no nested stash is found, the source path itself is used.
     const stashRoot = detectStashRoot(parsed.sourcePath);
@@ -124,6 +143,7 @@ async function installLocalRegistryRef(parsed, config, options) {
         cacheDir: parsed.sourcePath,
         extractedDir: parsed.sourcePath,
         stashRoot,
+        writable: options?.writable,
         audit,
     };
 }
@@ -148,7 +168,7 @@ async function installGitRegistryRef(parsed, config, options) {
             const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
             const stashRoot = detectStashRoot(installRoot);
             if (stashRoot) {
-                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -160,6 +180,7 @@ async function installGitRegistryRef(parsed, config, options) {
                     cacheDir,
                     extractedDir,
                     stashRoot,
+                    writable: options?.writable,
                     audit,
                 };
             }
@@ -193,7 +214,7 @@ async function installGitRegistryRef(parsed, config, options) {
         copyDirectoryContents(cloneDir, extractedDir);
         // Clean up the clone dir
         fs.rmSync(cloneDir, { recursive: true, force: true });
-        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -220,6 +241,7 @@ async function installGitRegistryRef(parsed, config, options) {
         cacheDir,
         extractedDir,
         stashRoot,
+        writable: options?.writable,
         audit,
     };
 }
@@ -494,8 +516,15 @@ async function computeFileHash(filePath) {
     const hash = createHash("sha256").update(data).digest("hex");
     return `sha256:${hash}`;
 }
-function runInstallAuditOrThrow(rootDir, source, ref, registryLabels, config) {
-    const audit = auditInstallCandidate({ rootDir, source, ref, registryLabels, config });
+function runInstallAuditOrThrow(rootDir, source, ref, registryLabels, config, options) {
+    const audit = auditInstallCandidate({
+        rootDir,
+        source,
+        ref,
+        registryLabels,
+        config,
+        trustThisInstall: options?.trustThisInstall,
+    });
     if (audit.blocked) {
         throw new Error(formatInstallAuditFailure(ref, audit));
     }

package/dist/registry-resolve.js

@@ -273,6 +273,20 @@ async function resolveNpmArtifact(parsed) {
     };
 }
 async function resolveGithubArtifact(parsed) {
+    const gitUrl = `https://github.com/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}.git`;
+    // Prefer git-backed installs so private GitHub repos work with the user's
+    // normal git credential helper rather than requiring API-specific auth.
+    const gitResolvedRevision = resolveGitRevisionFromRemote(gitUrl, parsed.requestedRef);
+    if (gitResolvedRevision) {
+        return {
+            id: parsed.id,
+            source: parsed.source,
+            ref: parsed.ref,
+            artifactUrl: gitUrl,
+            resolvedVersion: parsed.requestedRef,
+            resolvedRevision: gitResolvedRevision,
+        };
+    }
     const headers = githubHeaders();
     if (parsed.requestedRef) {
         const commit = await tryFetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers);
@@ -315,6 +329,17 @@ async function resolveGithubArtifact(parsed) {
         resolvedRevision: asString(commit?.sha) ?? defaultBranch,
     };
 }
+function resolveGitRevisionFromRemote(url, requestedRef) {
+    validateGitUrl(url);
+    const ref = requestedRef ?? "HEAD";
+    if (requestedRef)
+        validateGitRef(requestedRef);
+    const result = spawnSync("git", ["ls-remote", url, ref], { encoding: "utf8", timeout: 30_000 });
+    if (result.status !== 0)
+        return undefined;
+    const firstLine = result.stdout.trim().split(/\r?\n/)[0];
+    return firstLine?.split(/\s/)[0] || undefined;
+}
 async function resolveGitArtifact(parsed) {
     validateGitUrl(parsed.url);
     const ref = parsed.requestedRef ?? "HEAD";