akm-cli 0.6.0 → 0.7.0-rc1

package/dist/{output → src/output}/text.js

@@ -182,10 +182,446 @@ export function formatPlain(command, result, detail) {
             const over = r.overwritten ? " (overwritten)" : "";
             return `Cloned${remote} → ${dst}${over}`;
         }
+        // Output shape registration for `akm history` — paired with the shape function in shapes.ts.
+        case "history": {
+            return formatHistoryPlain(r);
+        }
+        // Output shape registration for `akm events list` / `akm events tail`
+        // (#204). Both share a renderer; `events-tail` is also called per-event
+        // by the streaming code path via `formatEventLine`.
+        case "events-list":
+        case "events-tail": {
+            return formatEventsPlain(r);
+        }
+        // Output shape registration for `akm proposal *` (#225).
+        case "proposal-list": {
+            return formatProposalListPlain(r);
+        }
+        case "proposal-show": {
+            return formatProposalShowPlain(r);
+        }
+        case "proposal-accept": {
+            return formatProposalAcceptPlain(r);
+        }
+        case "proposal-reject": {
+            return formatProposalRejectPlain(r);
+        }
+        case "proposal-diff": {
+            return formatProposalDiffPlain(r);
+        }
+        // Output shape registration for `akm reflect` / `akm propose` (#226).
+        case "reflect":
+        case "propose": {
+            return formatProposalProducerPlain(command, r);
+        }
+        // Output shape registration for `akm distill <ref>` (#228). Three branches
+        // mirror the three terminal `outcome` values.
+        case "distill": {
+            return formatDistillPlain(r);
+        }
+        case "info":
+            return formatInfoPlain(r);
+        case "config":
+            return formatConfigPlain(r);
+        case "feedback":
+            return formatFeedbackPlain(r);
+        case "remember":
+            return formatRememberPlain(r);
+        case "import":
+            return formatImportPlain(r);
+        case "save":
+            return formatSavePlain(r);
+        case "enable":
+        case "disable":
+            return formatToggleComponentPlain(command, r);
+        case "registry-list":
+            return formatRegistryListPlain(r);
+        case "registry-add":
+            return formatRegistryAddPlain(r);
+        case "registry-remove":
+            return formatRegistryRemovePlain(r);
+        case "registry-search":
+            return formatRegistrySearchPlain(r, detail);
+        case "registry-build-index":
+            return formatRegistryBuildIndexPlain(r);
+        case "vault-list":
+            return formatVaultListPlain(r);
+        case "vault-create":
+            return `Created vault ${String(r.ref ?? "?")} at ${String(r.path ?? "?")}`;
+        case "vault-set":
+            return `Set ${String(r.key ?? "?")} in ${String(r.ref ?? "?")} (value not displayed)`;
+        case "vault-unset": {
+            const removed = r.removed === true;
+            const head = removed
+                ? `Removed ${String(r.key ?? "?")} from ${String(r.ref ?? "?")}`
+                : `Key ${String(r.key ?? "?")} was not present in ${String(r.ref ?? "?")}`;
+            return head;
+        }
+        case "wiki-register":
+            return formatWikiRegisterPlain(r);
+        case "workflow-resume":
+            return formatWorkflowStatusPlain(r) ?? `Resumed workflow run ${String(r.id ?? r.runId ?? "?")}`;
+        case "workflow-validate":
+            return formatWorkflowValidatePlain(r);
         default:
             return null; // fall through to YAML
     }
 }
+export function formatInfoPlain(r) {
+    const lines = [];
+    if (r.version)
+        lines.push(`version: ${String(r.version)}`);
+    if (r.stashDir)
+        lines.push(`stashDir: ${String(r.stashDir)}`);
+    if (r.configPath)
+        lines.push(`configPath: ${String(r.configPath)}`);
+    if (r.cacheDir)
+        lines.push(`cacheDir: ${String(r.cacheDir)}`);
+    if (r.dbPath)
+        lines.push(`dbPath: ${String(r.dbPath)}`);
+    const capabilities = r.capabilities;
+    if (capabilities) {
+        lines.push("capabilities:");
+        for (const [k, v] of Object.entries(capabilities)) {
+            lines.push(`  ${k}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`);
+        }
+    }
+    const indexStats = r.index;
+    if (indexStats) {
+        lines.push("index:");
+        for (const [k, v] of Object.entries(indexStats)) {
+            lines.push(`  ${k}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`);
+        }
+    }
+    if (lines.length === 0)
+        return JSON.stringify(r, null, 2);
+    return lines.join("\n");
+}
+export function formatConfigPlain(r) {
+    // Recursive flattener: prints `key=value` lines, and nested objects as
+    // `parent.child=value`. Arrays render as JSON for compactness.
+    const lines = [];
+    const walk = (obj, prefix) => {
+        for (const [k, v] of Object.entries(obj)) {
+            const path = prefix ? `${prefix}.${k}` : k;
+            if (v === null || v === undefined) {
+                lines.push(`${path}=`);
+            }
+            else if (Array.isArray(v)) {
+                lines.push(`${path}=${JSON.stringify(v)}`);
+            }
+            else if (typeof v === "object") {
+                walk(v, path);
+            }
+            else {
+                lines.push(`${path}=${String(v)}`);
+            }
+        }
+    };
+    walk(r, "");
+    if (lines.length === 0)
+        return "(empty config)";
+    return lines.join("\n");
+}
+export function formatFeedbackPlain(r) {
+    const ref = String(r.ref ?? "?");
+    const signal = String(r.signal ?? "?");
+    const note = typeof r.note === "string" && r.note ? ` — ${r.note}` : "";
+    return `Recorded ${signal} feedback for ${ref}${note}`;
+}
+export function formatRememberPlain(r) {
+    const ref = String(r.ref ?? "?");
+    const pathValue = String(r.path ?? "?");
+    return `Saved ${ref} at ${pathValue}`;
+}
+export function formatImportPlain(r) {
+    const ref = String(r.ref ?? "?");
+    const source = String(r.source ?? "?");
+    const pathValue = String(r.path ?? "?");
+    return `Imported ${source} → ${ref} at ${pathValue}`;
+}
+export function formatSavePlain(r) {
+    if (r.ok === false) {
+        const reason = typeof r.reason === "string" ? r.reason : "unknown";
+        return `save: failed (${reason})`;
+    }
+    const name = typeof r.name === "string" ? r.name : "primary stash";
+    const committed = r.committed === true;
+    const pushed = r.pushed === true;
+    const parts = [`save: ${name}`];
+    parts.push(committed ? "committed" : "no changes");
+    if (pushed)
+        parts.push("pushed");
+    return parts.join(" — ");
+}
+export function formatToggleComponentPlain(command, r) {
+    const verb = command === "enable" ? "Enabled" : "Disabled";
+    const component = String(r.component ?? "?");
+    const changed = r.changed === true;
+    return changed ? `${verb} ${component}` : `${component} was already ${command}d`;
+}
+export function formatRegistryListPlain(r) {
+    const registries = Array.isArray(r.registries) ? r.registries : [];
+    if (registries.length === 0) {
+        return "No registries configured. Add one with `akm registry add <url>`.";
+    }
+    const lines = [];
+    for (const reg of registries) {
+        const url = String(reg.url ?? "?");
+        const name = typeof reg.name === "string" ? reg.name : "";
+        const provider = typeof reg.provider === "string" ? ` (${reg.provider})` : "";
+        const enabled = reg.enabled === false ? " [disabled]" : "";
+        const head = name ? `${name}: ${url}` : url;
+        lines.push(`${head}${provider}${enabled}`);
+    }
+    return lines.join("\n");
+}
+export function formatRegistryAddPlain(r) {
+    if (r.added === false) {
+        return typeof r.message === "string" ? r.message : "Registry already configured.";
+    }
+    const registries = Array.isArray(r.registries) ? r.registries.length : 0;
+    return `Registry added (${registries} total).`;
+}
+export function formatRegistryRemovePlain(r) {
+    if (r.removed === false) {
+        return typeof r.message === "string" ? r.message : "No matching registry found.";
+    }
+    const entry = r.entry;
+    const url = entry ? String(entry.url ?? entry.name ?? "?") : "?";
+    return `Removed registry ${url}`;
+}
+export function formatRegistrySearchPlain(r, detail) {
+    // Reuse the same renderer as `search` — both share `hits` / `registryHits`.
+    return formatSearchPlain(r, detail);
+}
+export function formatRegistryBuildIndexPlain(r) {
+    const outPath = String(r.outPath ?? "?");
+    const total = typeof r.totalKits === "number" ? r.totalKits : 0;
+    const version = typeof r.version === "number" ? `v${r.version}` : "";
+    return `Wrote registry index ${version} (${total} kits) → ${outPath}`.replace(/\s+/g, " ").trim();
+}
+export function formatVaultListPlain(r) {
+    // Single-vault listing: { ref, path, entries: [{ key, comment? }, ...] }
+    if (typeof r.ref === "string" && Array.isArray(r.entries)) {
+        const ref = r.ref;
+        const entries = r.entries;
+        if (entries.length === 0) {
+            return `No keys in ${ref}. Set one with \`akm vault set ${ref} KEY=VALUE\`.`;
+        }
+        const lines = [ref];
+        for (const e of entries) {
+            const key = String(e.key ?? "?");
+            const comment = typeof e.comment === "string" && e.comment ? `  # ${e.comment}` : "";
+            lines.push(`  ${key}${comment}`);
+        }
+        return lines.join("\n");
+    }
+    // Multi-vault listing: { vaults: [{ ref, path, keyCount }, ...] }
+    const vaults = Array.isArray(r.vaults) ? r.vaults : [];
+    if (vaults.length === 0) {
+        return "No vaults. Create one with `akm vault create <name>` then `akm vault set vault:<name> KEY=VALUE`.";
+    }
+    const lines = [];
+    for (const v of vaults) {
+        const ref = String(v.ref ?? "?");
+        const keyCount = typeof v.keyCount === "number" ? v.keyCount : 0;
+        lines.push(`${ref}\t${keyCount} key(s)`);
+    }
+    return lines.join("\n");
+}
+export function formatWikiRegisterPlain(r) {
+    const name = String(r.name ?? r.wiki ?? "?");
+    const ref = String(r.ref ?? r.path ?? r.url ?? "?");
+    return `Registered wiki ${name} → ${ref}`;
+}
+export function formatWorkflowValidatePlain(r) {
+    const ok = r.ok !== false;
+    const pathValue = String(r.path ?? "?");
+    if (!ok)
+        return `workflow validate: failed (${pathValue})`;
+    const title = typeof r.title === "string" ? r.title : "";
+    const stepCount = typeof r.stepCount === "number" ? r.stepCount : 0;
+    return `workflow validate: ok — ${title || pathValue} (${stepCount} step(s))`;
+}
+export function formatProposalProducerPlain(command, r) {
+    if (r.ok === false) {
+        const reason = String(r.reason ?? "unknown");
+        const error = typeof r.error === "string" ? r.error : "";
+        const lines = [`${command}: failed (${reason})`];
+        if (error)
+            lines.push(`  error: ${error}`);
+        if (r.ref)
+            lines.push(`  ref: ${String(r.ref)}`);
+        if (r.exitCode !== undefined && r.exitCode !== null) {
+            lines.push(`  exitCode: ${String(r.exitCode)}`);
+        }
+        return lines.join("\n");
+    }
+    const proposal = r.proposal ?? {};
+    const id = String(proposal.id ?? "?");
+    const ref = String(r.ref ?? proposal.ref ?? "?");
+    const status = String(proposal.status ?? "pending");
+    return `${command}: queued proposal ${id} (${ref}) [${status}]`;
+}
+export function formatProposalListPlain(r) {
+    const proposals = Array.isArray(r.proposals) ? r.proposals : [];
+    const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
+    if (proposals.length === 0) {
+        return `${total} proposal(s).\nNo proposals.\nGenerate one with \`akm reflect <ref>\`, \`akm propose <type> <name> --task ...\`, or \`akm distill <ref>\`.`;
+    }
+    const lines = [`${total} proposal(s)`, ""];
+    for (const p of proposals) {
+        const id = String(p.id ?? "?");
+        const ref = String(p.ref ?? "?");
+        const status = String(p.status ?? "?");
+        const source = String(p.source ?? "?");
+        const created = String(p.createdAt ?? "?");
+        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}`);
+    }
+    return lines.join("\n").trimEnd();
+}
+export function formatProposalShowPlain(r) {
+    const p = r.proposal ?? {};
+    const lines = [];
+    lines.push(`# proposal ${String(p.id ?? "?")}`);
+    lines.push(`ref: ${String(p.ref ?? "?")}`);
+    lines.push(`status: ${String(p.status ?? "?")}`);
+    lines.push(`source: ${String(p.source ?? "?")}`);
+    if (p.sourceRun)
+        lines.push(`sourceRun: ${String(p.sourceRun)}`);
+    if (p.createdAt)
+        lines.push(`createdAt: ${String(p.createdAt)}`);
+    if (p.updatedAt)
+        lines.push(`updatedAt: ${String(p.updatedAt)}`);
+    const review = p.review;
+    if (review) {
+        lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);
+        if (review.reason)
+            lines.push(`review.reason: ${String(review.reason)}`);
+        if (review.decidedAt)
+            lines.push(`review.decidedAt: ${String(review.decidedAt)}`);
+    }
+    const validation = r.validation;
+    if (validation) {
+        const ok = validation.ok === true;
+        const findings = Array.isArray(validation.findings) ? validation.findings : [];
+        lines.push("");
+        lines.push(`validation: ${ok ? "ok" : `${findings.length} finding(s)`}`);
+        for (const f of findings) {
+            lines.push(`  - [${String(f.kind)}] ${String(f.message)}`);
+        }
+    }
+    const payload = p.payload;
+    if (payload && typeof payload.content === "string") {
+        lines.push("");
+        lines.push("payload:");
+        lines.push(payload.content);
+    }
+    return lines.join("\n").trimEnd();
+}
+export function formatProposalAcceptPlain(r) {
+    return `Accepted proposal ${String(r.id ?? "?")} → ${String(r.ref ?? "?")} at ${String(r.assetPath ?? "?")}`;
+}
+export function formatProposalRejectPlain(r) {
+    const reason = r.reason ? ` (${String(r.reason)})` : "";
+    return `Rejected proposal ${String(r.id ?? "?")} (${String(r.ref ?? "?")})${reason}`;
+}
+export function formatDistillPlain(r) {
+    const outcome = String(r.outcome ?? "unknown");
+    const inputRef = String(r.inputRef ?? "?");
+    const lessonRef = String(r.lessonRef ?? "?");
+    if (outcome === "queued") {
+        const id = String(r.proposalId ?? "?");
+        return `Distilled ${inputRef} → proposal ${id} (${lessonRef}). Run \`akm proposal show ${id}\` to review.`;
+    }
+    if (outcome === "validation_failed") {
+        const findings = Array.isArray(r.findings) ? r.findings : [];
+        const lines = [`Distillation produced an invalid lesson for ${inputRef}; no proposal queued.`];
+        for (const f of findings) {
+            lines.push(`  - ${String(f.message ?? f.kind ?? "validation finding")}`);
+        }
+        return lines.join("\n");
+    }
+    // skipped
+    const message = typeof r.message === "string" ? r.message : "feature disabled or LLM unavailable";
+    return `Distill skipped for ${inputRef}: ${message}`;
+}
+export function formatProposalDiffPlain(r) {
+    const header = r.isNew
+        ? `# proposal ${String(r.id ?? "?")} (new asset: ${String(r.ref ?? "?")})`
+        : `# proposal ${String(r.id ?? "?")} (update: ${String(r.ref ?? "?")})`;
+    const unified = typeof r.unified === "string" ? r.unified : "";
+    if (!unified)
+        return `${header}\n(no changes)`;
+    return `${header}\n${unified}`;
+}
+export function formatEventsPlain(r) {
+    const events = Array.isArray(r.events) ? r.events : [];
+    const headerParts = [];
+    if (typeof r.ref === "string" && r.ref)
+        headerParts.push(`ref: ${r.ref}`);
+    if (typeof r.type === "string" && r.type)
+        headerParts.push(`type: ${r.type}`);
+    if (typeof r.since === "string" && r.since)
+        headerParts.push(`since: ${r.since}`);
+    const totalCount = typeof r.totalCount === "number" ? r.totalCount : events.length;
+    headerParts.push(`${totalCount} event(s)`);
+    const header = headerParts.join("  ");
+    if (events.length === 0) {
+        return `${header}\nNo events.`;
+    }
+    const lines = [header, ""];
+    for (const event of events) {
+        lines.push(formatEventLine(event));
+    }
+    return lines.join("\n").trimEnd();
+}
+export function formatEventLine(event) {
+    const ts = String(event.ts ?? "?");
+    const eventType = String(event.eventType ?? "?");
+    const ref = event.ref ? String(event.ref) : null;
+    const head = ref ? `${ts}  [${eventType}] ${ref}` : `${ts}  [${eventType}]`;
+    if (event.metadata != null && event.metadata !== "") {
+        const meta = typeof event.metadata === "string" ? event.metadata : JSON.stringify(event.metadata);
+        return `${head}\n  metadata: ${meta}`;
+    }
+    return head;
+}
+export function formatHistoryPlain(r) {
+    const entries = Array.isArray(r.entries) ? r.entries : [];
+    const headerParts = [];
+    if (typeof r.ref === "string" && r.ref)
+        headerParts.push(`ref: ${r.ref}`);
+    if (typeof r.since === "string" && r.since)
+        headerParts.push(`since: ${r.since}`);
+    const totalCount = typeof r.totalCount === "number" ? r.totalCount : entries.length;
+    headerParts.push(`${totalCount} event(s)`);
+    const header = headerParts.join("  ");
+    if (entries.length === 0) {
+        const scope = typeof r.ref === "string" && r.ref ? ` for ${r.ref}` : "";
+        return `${header}\nNo history${scope}.`;
+    }
+    const lines = [header, ""];
+    for (const entry of entries) {
+        const created = String(entry.createdAt ?? "?");
+        const eventType = String(entry.eventType ?? "?");
+        const ref = entry.ref ? String(entry.ref) : null;
+        const signal = entry.signal ? String(entry.signal) : null;
+        const query = entry.query ? String(entry.query) : null;
+        const head = ref ? `${created}  [${eventType}] ${ref}` : `${created}  [${eventType}]`;
+        lines.push(head);
+        if (signal)
+            lines.push(`  signal: ${signal}`);
+        if (query)
+            lines.push(`  query: ${query}`);
+        if (entry.metadata != null && entry.metadata !== "") {
+            const meta = typeof entry.metadata === "string" ? entry.metadata : JSON.stringify(entry.metadata);
+            lines.push(`  metadata: ${meta}`);
+        }
+    }
+    return lines.join("\n").trimEnd();
+}
 function formatShowPlain(r, detail) {
     const lines = [];
     if (r.type || r.name) {
@@ -260,8 +696,9 @@ function formatShowPlain(r, detail) {
 }
 export function formatWorkflowListPlain(result) {
     const runs = Array.isArray(result.runs) ? result.runs : [];
-    if (runs.length === 0)
-        return "No workflow runs found.";
+    if (runs.length === 0) {
+        return "No workflow runs. Start one with `akm workflow next workflow:<name>` or author one with `akm workflow create <name>`.";
+    }
     return runs
         .map((run) => {
         const id = typeof run.id === "string" ? run.id : "unknown";
@@ -351,8 +788,14 @@ export function formatSearchPlain(r, detail) {
             lines.push(`  run: ${String(hit.run)}`);
         if (Array.isArray(hit.tags) && hit.tags.length > 0)
             lines.push(`  tags: ${hit.tags.join(", ")}`);
-        if (hit.curated !== undefined)
-            lines.push(`  curated: ${String(hit.curated)}`);
+        // Optional v1 spec §4.2 quality marker (e.g. "curated" / "proposed").
+        if (typeof hit.quality === "string" && hit.quality)
+            lines.push(`  quality: ${hit.quality}`);
+        // Surface optional hit-level warnings (v1 spec §4.2). The legacy
+        // `curated` boolean was removed in v1.
+        if (Array.isArray(hit.warnings) && hit.warnings.length > 0) {
+            lines.push(`  warnings: ${hit.warnings.join("; ")}`);
+        }
         if (detail === "full") {
             if (hit.path)
                 lines.push(`  path: ${String(hit.path)}`);

package/dist/{registry → src/registry}/build-index.js

@@ -8,9 +8,9 @@
  * updated together with this builder.
  */
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { fetchWithRetry, jsonWithByteCap } from "../core/common";
+import { getCacheDir } from "../core/paths";
 import { generateMetadataFlat, loadStashFile } from "../indexer/metadata";
 import { walkStashFlat } from "../indexer/walker";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
@@ -173,7 +173,16 @@ async function scanGithub(githubApiBase) {
     return stashes;
 }
 async function inspectArchive(url, headers) {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-registry-build-"));
+    // Route registry-build scratch space under the akm cache dir instead of
+    // the system temp directory. Long-running registry builds that crash
+    // mid-flight previously left orphan dirs under `/tmp`, which can fill
+    // the OS partition. Pinning to `${getCacheDir()}/registry-build/` keeps
+    // a single `rm -rf` of that directory sufficient to reclaim the space
+    // and leaves the operator's `/tmp` untouched. See #276 for the
+    // bench-tmp precedent and #284 for this non-bench rollout.
+    const tmpRoot = path.join(getCacheDir(), "registry-build");
+    fs.mkdirSync(tmpRoot, { recursive: true });
+    const tempDir = fs.mkdtempSync(path.join(tmpRoot, "build-"));
     const archivePath = path.join(tempDir, "archive.tgz");
     const extractDir = path.join(tempDir, "extract");
     try {
@@ -283,7 +292,9 @@ async function loadManualEntries(manualEntriesPath) {
         const parsed = parseRegistryIndex({ version: 3, updatedAt: new Date().toISOString(), stashes: candidateKits });
         if (!parsed)
             return [];
-        return parsed.stashes.map((stash) => normalizeStash({ ...stash, curated: stash.curated ?? true }));
+        // Legacy `curated` flag on input entries is ignored (v1 spec §4.2). The
+        // builder no longer emits it on the resulting index.
+        return parsed.stashes.map((stash) => normalizeStash(stash));
     }
     catch {
         return [];
@@ -327,7 +338,6 @@ function mergeEntries(a, b) {
         author: a.author ?? b.author,
         license: a.license ?? b.license,
         latestVersion: a.latestVersion ?? b.latestVersion,
-        curated: a.curated || b.curated || undefined,
     });
 }
 function mergeAssets(a, b) {

package/dist/{registry → src/registry}/factory.js

@@ -23,11 +23,3 @@ export function registerProvider(type, factory) {
 export function resolveProviderFactory(type) {
     return registry.resolve(type);
 }
-/**
- * Iterate over all registered registry providers. Used by the orchestrator
- * (`src/commands/registry-search.ts`) to fan out queries through the same
- * `RegistryProvider` interface regardless of provider kind.
- */
-export function listProviderTypes() {
-    return registry.list();
-}

package/dist/{registry → src/registry}/providers/static-index.js

@@ -213,6 +213,9 @@ function parseStashEntry(raw) {
     const source = asSource(obj.source);
     if (!id || !name || !ref || !source)
         return null;
+    // The legacy registry boolean `curated` is removed in v1. Legacy index JSON
+    // containing a `curated` key parses normally; the key is silently ignored
+    // (v1 spec §4.2, docs/migration/v1.md).
     return {
         id,
         name,
@@ -226,7 +229,6 @@ function parseStashEntry(raw) {
         author: asString(obj.author),
         license: asString(obj.license),
         latestVersion: asString(obj.latestVersion),
-        curated: obj.curated === true ? true : undefined,
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
@@ -294,7 +296,6 @@ function toSearchHit(stash, score, registryName) {
         homepage: stash.homepage,
         score: Math.round(score * 1000) / 1000,
         metadata,
-        curated: stash.curated,
         registryName,
     };
 }

package/dist/{registry → src/registry}/resolve.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { fetchWithRetry, jsonWithByteCap } from "../core/common";
-import { UsageError } from "../core/errors";
+import { NotFoundError, UsageError } from "../core/errors";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
 /**
  * Validate that a URL is safe to pass to git.
@@ -200,7 +200,7 @@ function tryParseLocalRef(rawRef, explicitPath) {
     catch {
         // Explicit paths (./foo, ../bar, /abs) should throw on missing
         if (explicitPath) {
-            throw new Error(`Local path not found: ${resolvedPath}`);
+            throw new NotFoundError(`Local path not found: ${resolvedPath}`, "FILE_NOT_FOUND", "Check the path exists and is readable.");
         }
         // Bare names that don't exist on disk — let caller fall through to npm/github
         return undefined;
@@ -231,6 +231,71 @@ function isPathLikeRef(ref) {
     }
     return ref.includes("/") || ref.includes("\\");
 }
+/** Default public npm registry host. */
+const DEFAULT_NPM_REGISTRY_HOST = "registry.npmjs.org";
+/**
+ * Typed error raised when the npm registry returns a tarball URL on a host
+ * that is not the public registry or the operator-configured mirror. Carries
+ * a stable `.code` so callers (and JSON envelope output) can branch on it
+ * without parsing the message string.
+ */
+export class UntrustedNpmTarballError extends Error {
+    code = "UNTRUSTED_NPM_TARBALL";
+    _hint;
+    constructor(msg, hint) {
+        super(msg);
+        this.name = "UntrustedNpmTarballError";
+        this._hint = hint;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return (this._hint ??
+            "Set AKM_NPM_REGISTRY to your private npm mirror's base URL if you install from a non-default registry.");
+    }
+}
+/**
+ * Resolve the set of npm registry hosts whose tarballs are considered trusted.
+ * Always includes the public npm registry, plus the host of an operator-set
+ * `AKM_NPM_REGISTRY` environment variable (if it parses to a valid URL).
+ */
+export function trustedNpmTarballHosts() {
+    const hosts = new Set([DEFAULT_NPM_REGISTRY_HOST]);
+    const override = process.env.AKM_NPM_REGISTRY?.trim();
+    if (override) {
+        try {
+            const overrideHost = new URL(override).hostname.toLowerCase();
+            if (overrideHost)
+                hosts.add(overrideHost);
+        }
+        catch {
+            // Ignore unparseable overrides; the default host still applies.
+        }
+    }
+    return hosts;
+}
+/**
+ * Validate that an npm tarball URL points at a trusted registry host. A
+ * compromised mirror could otherwise return an attacker-controlled
+ * `dist.tarball` field, redirecting installs to a third-party host.
+ */
+export function validateNpmTarballUrl(tarballUrl, packageRef) {
+    let url;
+    try {
+        url = new URL(tarballUrl);
+    }
+    catch {
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned an invalid tarball URL: ${tarballUrl}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball with disallowed scheme "${url.protocol}".`);
+    }
+    const trusted = trustedNpmTarballHosts();
+    const host = url.hostname.toLowerCase();
+    if (!trusted.has(host)) {
+        const allowed = Array.from(trusted).join(", ");
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball URL on untrusted host "${host}" (allowed: ${allowed}).`);
+    }
+}
 async function resolveNpmArtifact(parsed) {
     const encodedName = encodeURIComponent(parsed.packageName);
     const metadata = await fetchJson(`https://registry.npmjs.org/${encodedName}`);
@@ -262,6 +327,7 @@ async function resolveNpmArtifact(parsed) {
     if (!tarballUrl) {
         throw new Error(`npm package ${parsed.packageName}@${resolvedVersion} does not expose a tarball URL.`);
     }
+    validateNpmTarballUrl(tarballUrl, `${parsed.packageName}@${resolvedVersion}`);
     const resolvedRevision = asString(dist.shasum) ?? asString(dist.integrity);
     return {
         id: parsed.id,