akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/setup/detect.js

@@ -8,7 +8,12 @@
  * a result object describing what was found.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { defaultWhich } from "../integrations/agent/detect.js";
+import { SESSION_LOG_HARNESSES } from "../integrations/harnesses/index.js";
+import { spawn } from "../runtime.js";
+import { detectHarnessConfigs } from "./harness-config-import.js";
 // ── Ollama Detection ────────────────────────────────────────────────────────
 const OLLAMA_BASE = "http://localhost:11434";
 /**
@@ -41,7 +46,7 @@ export async function detectOllama() {
     }
     // CLI fallback
     try {
-        const proc = Bun.spawn(["ollama", "list"], {
+        const proc = spawn(["ollama", "list"], {
             stdout: "pipe",
             stderr: "pipe",
         });
@@ -64,15 +69,52 @@ export async function detectOllama() {
     }
     return result;
 }
+const LMSTUDIO_BASE = "http://localhost:1234";
+/**
+ * Detect if LM Studio is running and list available models.
+ * Probes the OpenAI-compatible /v1/models endpoint.
+ */
+export async function detectLMStudio() {
+    const result = { available: false, models: [], endpoint: LMSTUDIO_BASE };
+    try {
+        const response = await fetch(`${LMSTUDIO_BASE}/v1/models`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        if (response.ok) {
+            const data = (await response.json());
+            if (Array.isArray(data.data)) {
+                result.models = data.data
+                    .map((m) => (typeof m.id === "string" ? m.id : ""))
+                    .filter(Boolean)
+                    .sort();
+                result.available = true;
+            }
+        }
+    }
+    catch {
+        // LM Studio not running or not accessible
+    }
+    return result;
+}
 // ── Agent Platform Detection ────────────────────────────────────────────────
-const AGENT_PLATFORMS = [
-    { name: "Claude Code", relPath: ".claude" },
-    { name: "OpenCode", relPath: ".config/opencode" },
-    { name: "Continue", relPath: ".continue" },
-    { name: "Codeium / Windsurf", relPath: ".codeium" },
-    { name: "Cursor", relPath: ".cursor" },
-    { name: "Codex CLI", relPath: ".codex" },
-];
+/**
+ * Setup stash-source candidates, derived from the unified harness registry
+ * (#567).
+ *
+ * BEHAVIOUR FIX: the old hardcoded list named 6 harnesses (Claude Code,
+ * OpenCode, Continue, Codeium/Windsurf, Cursor, Codex CLI) but only the first
+ * two have a session-log provider. Selecting any of the other four added a
+ * filesystem stash source that was never indexed/extracted — a silent no-op
+ * "detection trap" (sessions never reached the improve pipeline).
+ *
+ * The registry is now the single source of which harnesses are real stash
+ * sources: a candidate must (a) have `capabilities.sessionLogs === true` AND
+ * (b) declare a `setupDetectionDir`. `SESSION_LOG_HARNESSES` already filters by
+ * (a), so dropping the four dead options is automatic — they aren't even in the
+ * registry. Adding a new session-log harness with a detection dir makes it
+ * appear here with no edit to this file.
+ */
+const AGENT_PLATFORMS = SESSION_LOG_HARNESSES.filter((h) => h.setupDetectionDir).map((h) => ({ name: h.displayName, relPath: h.setupDetectionDir }));
 /**
  * Scan the user's home directory for known agent platform config directories.
  * Supports both HOME (Unix) and USERPROFILE (Windows).
@@ -94,3 +136,290 @@ export function detectAgentPlatforms() {
         path: path.join(home, p.relPath),
     }));
 }
+/**
+ * Map of env var NAME → { provider, kind }. The key NAMES are the only thing
+ * this module ever inspects from `process.env`; values are never touched.
+ */
+const PROVIDER_ENV_VARS = [
+    { name: "ANTHROPIC_API_KEY", provider: "anthropic", kind: "apiKey" },
+    { name: "OPENAI_API_KEY", provider: "openai", kind: "apiKey" },
+    { name: "GEMINI_API_KEY", provider: "gemini", kind: "apiKey" },
+    { name: "GOOGLE_API_KEY", provider: "gemini", kind: "apiKey" },
+    { name: "GROQ_API_KEY", provider: "groq", kind: "apiKey" },
+    { name: "OLLAMA_HOST", provider: "ollama", kind: "endpoint" },
+    { name: "OLLAMA_BASE_URL", provider: "ollama", kind: "endpoint" },
+    { name: "LM_STUDIO_BASE_URL", provider: "lmstudio", kind: "endpoint" },
+    { name: "LM_STUDIO_API_BASE", provider: "lmstudio", kind: "endpoint" },
+    { name: "LMSTUDIO_BASE_URL", provider: "lmstudio", kind: "endpoint" },
+    { name: "LMSTUDIO_API_BASE", provider: "lmstudio", kind: "endpoint" },
+    { name: "AKM_LLM_API_KEY", provider: "akm-llm", kind: "apiKey" },
+    { name: "AKM_LLM_ENDPOINT", provider: "akm-llm", kind: "endpoint" },
+    { name: "AKM_LLM_BASE_URL", provider: "akm-llm", kind: "endpoint" },
+];
+/**
+ * Scan `process.env` for the presence of known provider configuration env var
+ * NAMES and return inferred providers.
+ *
+ * Pure function — no network, no filesystem. It reads only whether each known
+ * key is *defined and non-empty*; it never reads, returns, or logs the value.
+ *
+ * @param envSource  Env to inspect. Defaults to `process.env`. Tests inject a
+ *                   fake env so a real API key is never required.
+ * @returns Inferred providers, each carrying the env var NAME only.
+ */
+export function scanProviderEnvVars(envSource = process.env) {
+    const results = [];
+    for (const entry of PROVIDER_ENV_VARS) {
+        const value = envSource[entry.name];
+        const present = typeof value === "string" && value.trim().length > 0;
+        if (!present)
+            continue;
+        results.push({ provider: entry.provider, envVar: entry.name, kind: entry.kind });
+    }
+    return results;
+}
+/** Default endpoints probed in addition to any harness-config base URLs. */
+const DEFAULT_LOCAL_ENDPOINTS = [
+    { baseUrl: "http://localhost:11434", label: "Ollama" },
+    { baseUrl: "http://localhost:1234", label: "LM Studio" },
+    { baseUrl: "http://localhost:8080", label: "Local (8080)" },
+];
+/**
+ * Pick a sensible default model from a list via a name heuristic.
+ *
+ * Preference order: an explicit "instruct" variant, then the longest name
+ * (a rough proxy for the larger / more-capable variant), then the first.
+ * Returns `undefined` for an empty list.
+ */
+export function pickDefaultModel(models) {
+    const cleaned = models.filter((m) => typeof m === "string" && m.trim().length > 0);
+    if (cleaned.length === 0)
+        return undefined;
+    const instruct = cleaned.filter((m) => /instruct/i.test(m));
+    const pool = instruct.length > 0 ? instruct : cleaned;
+    // Prefer the longest name as a proxy for the larger/most-specific variant,
+    // breaking ties by sort order for determinism.
+    return [...pool].sort((a, b) => b.length - a.length || a.localeCompare(b))[0];
+}
+/**
+ * Probe a single OpenAI-compatible `/v1/models` endpoint.
+ *
+ * Tolerant of failure: any network/timeout/parse error yields an
+ * `available: false` result rather than throwing.
+ */
+export async function probeLocalEndpoint(baseUrl, label, timeoutMs = 2000) {
+    const result = { baseUrl, label, available: false, models: [] };
+    const url = `${baseUrl.replace(/\/$/, "")}/v1/models`;
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (response.ok) {
+            const data = (await response.json());
+            if (Array.isArray(data.data)) {
+                result.models = data.data
+                    .map((m) => (typeof m.id === "string" ? m.id : ""))
+                    .filter(Boolean)
+                    .sort();
+                result.available = true;
+                result.defaultModel = pickDefaultModel(result.models);
+            }
+        }
+    }
+    catch {
+        // Endpoint down/unreachable — leave available=false.
+    }
+    return result;
+}
+/**
+ * Probe the default local endpoints (Ollama 11434, LM Studio 1234, generic
+ * 8080) plus any base URLs found in imported harness configs.
+ *
+ * Never throws: every endpoint being down yields a list of unavailable
+ * results, not an error.
+ *
+ * @param harnessBaseUrls  Extra base URLs to probe (e.g. from harness configs).
+ */
+export async function detectLocalServers(harnessBaseUrls = []) {
+    const endpoints = [...DEFAULT_LOCAL_ENDPOINTS];
+    for (const raw of harnessBaseUrls) {
+        if (typeof raw !== "string" || raw.trim().length === 0)
+            continue;
+        // Strip a trailing /v1 (and trailing slash) so we probe consistently.
+        const baseUrl = raw.replace(/\/$/, "").replace(/\/v1$/, "");
+        if (!endpoints.some((e) => e.baseUrl === baseUrl)) {
+            endpoints.push({ baseUrl, label: `Harness (${baseUrl})` });
+        }
+    }
+    return Promise.all(endpoints.map((e) => probeLocalEndpoint(e.baseUrl, e.label)));
+}
+/**
+ * Suggest stash directories, ranked (lower rank = higher priority).
+ *
+ * Sources, in priority order:
+ *   1. An existing config `stashDir` (always rank 0 — no-op / keep current).
+ *   2. A `akm/` or `agent-stash/` directory in the CWD git repo.
+ *   3. `~/akm` then `~/.akm` when they already exist.
+ *
+ * Pure function — filesystem reads only, no network. Tests inject `cwd`/`home`.
+ */
+export function detectStashDir(opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const home = opts?.home ?? os.homedir();
+    const suggestions = [];
+    const seen = new Set();
+    const push = (p, reason, rank) => {
+        const abs = path.resolve(p);
+        if (seen.has(abs))
+            return;
+        seen.add(abs);
+        suggestions.push({ path: abs, reason, rank });
+    };
+    if (opts?.existingStashDir?.trim()) {
+        push(opts.existingStashDir, "existing config stashDir", 0);
+    }
+    // CWD git repo containing akm/ or agent-stash/
+    const repoRoot = findGitRepoRoot(cwd);
+    if (repoRoot) {
+        for (const dirName of ["akm", "agent-stash"]) {
+            const candidate = path.join(repoRoot, dirName);
+            try {
+                if (fs.statSync(candidate).isDirectory()) {
+                    push(candidate, `git repo contains ${dirName}/`, 1);
+                }
+            }
+            catch {
+                // not present
+            }
+        }
+    }
+    // ~/akm then ~/.akm when they exist
+    if (home) {
+        for (const dirName of ["akm", ".akm"]) {
+            const candidate = path.join(home, dirName);
+            try {
+                if (fs.statSync(candidate).isDirectory()) {
+                    push(candidate, `${dirName} exists in home`, 2);
+                }
+            }
+            catch {
+                // not present
+            }
+        }
+    }
+    return suggestions.sort((a, b) => a.rank - b.rank);
+}
+/** Walk up from `start` looking for a directory containing `.git`. */
+function findGitRepoRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        try {
+            if (fs.existsSync(path.join(dir, ".git")))
+                return dir;
+        }
+        catch {
+            // ignore
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Detect the best agent harness in priority order:
+ *   1. OpenCode SDK resolvable via `import('@opencode-ai/sdk')`.
+ *   2. `opencode` binary on PATH.
+ *   3. `claude` binary on PATH.
+ *   4. none.
+ *
+ * Pure aside from the dynamic import resolution (which performs no network).
+ */
+export async function detectHarness(whichFn = defaultWhich) {
+    try {
+        await import("@opencode-ai/sdk");
+        return "opencode-sdk";
+    }
+    catch {
+        // SDK not installed — fall through to bin probes.
+    }
+    if (whichFn("opencode"))
+        return "opencode";
+    if (whichFn("claude"))
+        return "claude";
+    return "none";
+}
+/**
+ * Run the full environment-detection pipeline once and return a single typed
+ * result. Orchestrates env-var scan, harness config import, harness selection,
+ * local-server probes, and stash-dir suggestions.
+ *
+ * SAFETY: No API key VALUE is ever read, stored, logged, or returned — only
+ * env var NAMES. Tolerant of every detector failing.
+ *
+ * @param opts.existingStashDir  Current config stashDir (no-op suggestion).
+ * @param opts.envSource  Env to scan. Defaults to `process.env`.
+ * @param opts.whichFn  Binary lookup. Tests inject a stub.
+ */
+export async function detectEnvironment(opts) {
+    const envSource = opts?.envSource ?? process.env;
+    const whichFn = opts?.whichFn ?? defaultWhich;
+    let harnessConfigs = [];
+    try {
+        harnessConfigs = detectHarnessConfigs();
+    }
+    catch {
+        harnessConfigs = [];
+    }
+    const harnessBaseUrls = harnessConfigs.map((c) => c.baseUrl).filter((u) => typeof u === "string");
+    const [harness, localServers] = await Promise.all([
+        detectHarness(whichFn),
+        detectLocalServers(harnessBaseUrls).catch(() => []),
+    ]);
+    let agentPlatforms = [];
+    try {
+        agentPlatforms = detectAgentPlatforms();
+    }
+    catch {
+        agentPlatforms = [];
+    }
+    return {
+        harness,
+        providers: scanProviderEnvVars(envSource),
+        harnessConfigs,
+        localServers,
+        stashSuggestions: detectStashDir({
+            existingStashDir: opts?.existingStashDir,
+            cwd: opts?.cwd,
+            home: opts?.home,
+        }),
+        agentPlatforms,
+    };
+}
+/**
+ * Render a compact, human-readable "Detected environment" summary block.
+ * Contains env var NAMES only — never any value.
+ */
+export function renderDetectionSummary(env) {
+    const lines = ["Detected environment:"];
+    lines.push(`  Harness:        ${env.harness}`);
+    const liveServers = env.localServers.filter((s) => s.available);
+    if (liveServers.length > 0) {
+        lines.push(`  Local servers:  ${liveServers
+            .map((s) => `${s.label}${s.defaultModel ? ` (${s.defaultModel})` : ""}`)
+            .join(", ")}`);
+    }
+    else {
+        lines.push("  Local servers:  none reachable");
+    }
+    if (env.providers.length > 0) {
+        // NAMES only — never values.
+        lines.push(`  Provider keys:  ${env.providers.map((p) => `${p.provider}:${p.envVar}`).join(", ")}`);
+    }
+    else {
+        lines.push("  Provider keys:  none in environment");
+    }
+    const topStash = env.stashSuggestions[0];
+    if (topStash) {
+        lines.push(`  Stash suggest:  ${topStash.path} (${topStash.reason})`);
+    }
+    return lines.join("\n");
+}

package/dist/setup/harness-config-import.js

@@ -0,0 +1,56 @@
+// 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/.
+/**
+ * Pluggable registry of LLM config importers for supported agent harnesses.
+ *
+ * Each importer detects whether a harness is installed (filesystem only,
+ * no network) and, if so, reads its config to extract LLM connection details.
+ * API key VALUES are never stored — only the env var names that hold them.
+ *
+ * To add a new harness: implement {@link HarnessConfigImporter} and append it
+ * to {@link HARNESS_CONFIG_IMPORTERS}.
+ *
+ * NOTE: The `detect()` method in each importer overlaps intentionally with
+ * `detectAgentPlatforms()` in `detect.ts`. That function scans for harness
+ * presence to display installed platforms to the user; these importers go
+ * further by reading and parsing the harness config. They serve different
+ * purposes and should not be deduplicated.
+ */
+import { claudeCodeImporter } from "../integrations/harnesses/claude/config-import.js";
+import { openCodeImporter } from "../integrations/harnesses/opencode/config-import.js";
+// The Claude Code importer was migrated to its harness directory in #563
+// (`harnesses/claude/config-import.ts`) and the OpenCode importer in #564
+// (`harnesses/opencode/config-import.ts`). Both are imported back into
+// HARNESS_CONFIG_IMPORTERS below so detection order is unchanged.
+// ── Registry ─────────────────────────────────────────────────────────────────
+/**
+ * Registry of all supported harness config importers.
+ * To add a new harness: implement {@link HarnessConfigImporter} and append here.
+ */
+export const HARNESS_CONFIG_IMPORTERS = [claudeCodeImporter, openCodeImporter];
+/**
+ * Run all importers whose `detect()` returns `true` and collect their configs.
+ *
+ * Pure function — filesystem reads only, no network, no side effects.
+ * Individual importer failures are swallowed so one broken harness never
+ * blocks the setup wizard.
+ *
+ * @returns List of detected harness configs (may be empty).
+ */
+export function detectHarnessConfigs() {
+    const results = [];
+    for (const importer of HARNESS_CONFIG_IMPORTERS) {
+        try {
+            if (!importer.detect())
+                continue;
+            const config = importer.importConfig();
+            if (config)
+                results.push(config);
+        }
+        catch {
+            // Never let one importer crash the whole detection
+        }
+    }
+    return results;
+}

package/dist/setup/registry-stash-loader.js

@@ -0,0 +1,99 @@
+// 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/.
+/**
+ * Registry-driven stash discovery for the setup wizard.
+ *
+ * Fetches the list of available stashes from the official AKM registry,
+ * using a cached result when available. Falls back to FALLBACK_STASHES
+ * when the registry is unreachable or returns no results.
+ *
+ * Adding a new default-selected stash: append its registry ID to
+ * DEFAULT_SELECTED_STASH_IDS below. No other change required.
+ */
+// ── Default selections ──────────────────────────────────────────────────────
+/**
+ * Registry stash IDs that are pre-selected by default during setup.
+ * To add a new default stash: append its registry ID here.
+ * IDs must match the `id` field in the official registry index.
+ *
+ * This is the single source of truth for which stashes are pre-checked
+ * in the setup wizard. No other change is required to adjust defaults.
+ */
+export const DEFAULT_SELECTED_STASH_IDS = ["itlackey/akm-stash"];
+// ── Fallback list ───────────────────────────────────────────────────────────
+/**
+ * Hardcoded stash list used when the registry is unreachable.
+ * Mirrors the previous RECOMMENDED_GITHUB_REPOS constant.
+ */
+const FALLBACK_STASHES = [
+    {
+        id: "itlackey/akm-stash",
+        name: "itlackey/akm-stash",
+        description: "Official AKM onboarding stash",
+        url: "https://github.com/itlackey/akm-stash",
+        source: "fallback",
+        defaultSelected: true,
+    },
+    {
+        id: "andrewyng/context-hub",
+        name: "andrewyng/context-hub",
+        description: "Optional community prompt and context stash",
+        url: "https://github.com/andrewyng/context-hub",
+        source: "fallback",
+        defaultSelected: false,
+    },
+];
+// ── Loader ──────────────────────────────────────────────────────────────────
+/**
+ * Fetch available stashes from the registry and map to SetupStashEntry[].
+ *
+ * Falls back to FALLBACK_STASHES on network failure, parse error, or
+ * empty response — setup never crashes due to a registry outage.
+ *
+ * @param registryUrl  URL of the registry index JSON.
+ * @param timeoutMs    Fetch timeout in ms (default: 4000).
+ */
+export async function loadSetupStashes(registryUrl, timeoutMs = 4000) {
+    try {
+        const response = await fetch(registryUrl, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { Accept: "application/json" },
+        });
+        if (!response.ok)
+            return FALLBACK_STASHES;
+        const raw = (await response.json());
+        if (!Array.isArray(raw.stashes) || raw.stashes.length === 0)
+            return FALLBACK_STASHES;
+        const entries = raw.stashes.flatMap((item) => {
+            if (!item || typeof item !== "object")
+                return [];
+            const s = item;
+            const id = typeof s.id === "string" ? s.id : "";
+            const name = typeof s.name === "string" ? s.name : id;
+            const description = typeof s.description === "string" ? s.description : "";
+            // Prefer github/git source URL built from the ref; fall back to homepage
+            const url = (s.source === "github" || s.source === "git") && typeof s.ref === "string"
+                ? `https://github.com/${s.ref.replace(/^github:/, "")}`
+                : typeof s.homepage === "string"
+                    ? s.homepage
+                    : "";
+            if (!id || !url)
+                return [];
+            return [
+                {
+                    id,
+                    name,
+                    description,
+                    url,
+                    source: "registry",
+                    defaultSelected: DEFAULT_SELECTED_STASH_IDS.includes(id),
+                },
+            ];
+        });
+        return entries.length > 0 ? entries : FALLBACK_STASHES;
+    }
+    catch {
+        return FALLBACK_STASHES;
+    }
+}