akm-cli 0.8.0 → 0.8.2

package/dist/commands/stash-skeleton.js

@@ -0,0 +1,78 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+const SKELETON_DIR = path.join(import.meta.dir, "../assets/stash-skeleton");
+/**
+ * Copy the default stash skeleton into a newly created stash directory.
+ *
+ * Each file in src/assets/stash-skeleton/ is written to the stash root only
+ * if the destination does not already exist — existing files are never
+ * overwritten. Non-fatal: if the skeleton directory is missing or a copy
+ * fails the caller continues normally.
+ */
+export function copyStashSkeleton(stashDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(SKELETON_DIR);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const src = path.join(SKELETON_DIR, entry);
+        const dest = path.join(stashDir, entry);
+        if (fs.existsSync(dest))
+            continue;
+        try {
+            fs.copyFileSync(src, dest);
+        }
+        catch {
+            // Non-fatal — stash is usable without skeleton files
+        }
+    }
+}
+/**
+ * Scaffold the optional `.meta/index.md` orientation doc for the stash
+ * `.meta/` convention. Written only when absent — an existing `.meta/index.md`
+ * is never overwritten. Non-fatal: a stash works fine without it.
+ *
+ * `.meta/` is a dot-directory, so the indexer skips it; the template is
+ * written here (rather than shipped under `src/assets/`) because the
+ * build-time asset glob excludes dotfiles.
+ */
+export function scaffoldStashMeta(stashDir) {
+    const metaDir = path.join(stashDir, ".meta");
+    const indexPath = path.join(metaDir, "index.md");
+    if (fs.existsSync(indexPath))
+        return;
+    try {
+        fs.mkdirSync(metaDir, { recursive: true });
+        fs.writeFileSync(indexPath, STASH_META_INDEX_TEMPLATE);
+    }
+    catch {
+        // Non-fatal — stash is usable without the .meta orientation doc
+    }
+}
+const STASH_META_INDEX_TEMPLATE = `---
+# Optional, human-authored orientation for this stash. Not indexed; surfaced
+# on demand via \`akm show meta\` (this file) or \`akm show <stash>//meta\`.
+# Every field is optional — delete what you don't need.
+purpose:
+  - Describe what this stash is for.
+entry_points:
+  # Refs an agent should start from, e.g. skill:code-review, workflow:ship-release
+conventions:
+  # House rules an agent should follow when working in this stash.
+maintainer:
+---
+# About this stash
+
+Replace this with a short orientation for agents and humans: what lives here,
+where to start, and the conventions to follow.
+
+Extend the \`.meta/\` directory with more docs as needed — \`.meta/about.md\`,
+\`.meta/conventions.md\`, \`.meta/license\` — and read any of them with
+\`akm show meta:<name>\` (or \`akm show <stash>//meta:<name>\`).
+`;

package/dist/{setup/ripgrep-install.js → core/ripgrep/install.js}

@@ -4,8 +4,8 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../core/common";
-import { RG_BINARY, resolveRg } from "./ripgrep-resolve";
+import { IS_WINDOWS } from "../common";
+import { RG_BINARY, resolveRg } from "./resolve";
 /**
  * Platform and architecture detection for ripgrep binary downloads.
  */

package/dist/{setup/ripgrep-resolve.js → core/ripgrep/resolve.js}

@@ -3,8 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../core/common";
-import { getBinDir } from "../core/paths";
+import { IS_WINDOWS } from "../common";
+import { getBinDir } from "../paths";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))

package/dist/core/stash-meta.js

@@ -0,0 +1,110 @@
+// 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/.
+/**
+ * Stash `.meta/` convention.
+ *
+ * A stash may carry an optional, human-authored `.meta/` directory at its
+ * root holding orientation docs for the stash as a whole: purpose, key
+ * assets, conventions, maintainer info. Because `.meta/` is a dot-directory,
+ * the indexer's walker already skips it (see `src/indexer/walker.ts`), so
+ * these files never pollute the search corpus. They are surfaced on demand
+ * via `akm show [<origin>//]meta[:<name>]`, which direct-reads the file
+ * rather than going through the index.
+ *
+ * This is deliberately a *convention* enabled by a thin resolver: stash
+ * owners extend it by dropping new files (`.meta/about.md`, `.meta/license`,
+ * `.meta/conventions.md`) with zero further code changes.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./errors";
+/** Root-relative directory holding a stash's meta docs. */
+export const META_DIR = ".meta";
+/** Default meta doc shown when no name is given (`akm show <ref>//meta`). */
+export const META_DEFAULT_NAME = "index";
+/**
+ * Parse a `meta` show target. Returns `null` when `ref` is not a meta ref so
+ * callers can fall through to normal asset resolution.
+ *
+ * Accepted shapes (the leading `[origin//]` is optional):
+ *   - `meta`            → { name: "index" }
+ *   - `meta:about`      → { name: "about" }
+ *   - `local//meta`     → { origin: "local", name: "index" }
+ *   - `github:o/r//meta:conventions` → { origin: "github:o/r", name: "conventions" }
+ */
+export function parseMetaRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        return null;
+    let origin;
+    let body = trimmed;
+    const boundary = trimmed.indexOf("//");
+    if (boundary >= 0) {
+        origin = trimmed.slice(0, boundary) || undefined;
+        body = trimmed.slice(boundary + 2);
+    }
+    if (body === "meta")
+        return { origin, name: META_DEFAULT_NAME };
+    if (body.startsWith("meta:")) {
+        const name = body.slice("meta:".length).trim();
+        return { origin, name: name || META_DEFAULT_NAME };
+    }
+    return null;
+}
+/**
+ * Reject meta names that would escape the `.meta/` directory. Mirrors the
+ * traversal guards in `parseAssetRef`'s `validateName`.
+ */
+function assertSafeMetaName(name) {
+    if (name.includes("\0")) {
+        throw new UsageError("Null byte in meta name.", "PATH_ESCAPE_VIOLATION");
+    }
+    if (/^[A-Za-z]:/.test(name)) {
+        throw new UsageError("Windows drive path in meta name.", "PATH_ESCAPE_VIOLATION");
+    }
+    const normalized = path.posix.normalize(name.replace(/\\/g, "/"));
+    if (path.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../")) {
+        throw new UsageError("Path traversal in meta name.", "PATH_ESCAPE_VIOLATION");
+    }
+    if (normalized.split("/").some((seg) => seg === "." || seg === "..")) {
+        throw new UsageError("Meta name cannot contain relative path segments.", "PATH_ESCAPE_VIOLATION");
+    }
+}
+/**
+ * Candidate filenames for a meta doc, in resolution order. Markdown is
+ * preferred so `meta:about` resolves `.meta/about.md` ahead of `.meta/about`,
+ * while names that already carry an extension (`license.txt`) are tried
+ * verbatim first.
+ */
+function metaCandidates(name) {
+    if (path.posix.extname(name))
+        return [name, `${name}.md`];
+    return [`${name}.md`, name];
+}
+/**
+ * Resolve a meta doc to an absolute file path under `<sourceRoot>/.meta/`,
+ * or `null` when no candidate file exists. Guards against path traversal
+ * both before and after resolution (symlink containment).
+ */
+export function resolveMetaFilePath(sourceRoot, name) {
+    assertSafeMetaName(name);
+    const metaRoot = path.resolve(sourceRoot, META_DIR);
+    for (const candidate of metaCandidates(name)) {
+        const resolved = path.resolve(metaRoot, candidate);
+        if (resolved !== metaRoot && !resolved.startsWith(metaRoot + path.sep)) {
+            throw new UsageError("Meta ref resolves outside the stash .meta directory.", "PATH_ESCAPE_VIOLATION");
+        }
+        if (isRegularFile(resolved))
+            return resolved;
+    }
+    return null;
+}
+function isRegularFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/indexer/indexer.js

@@ -322,8 +322,8 @@ export async function akmIndex(options) {
                 totalMs: Date.now() - timing.t0,
                 walkMs: timing.tWalkEnd - timing.tWalkStart,
                 llmMs: timing.tLlmEnd - timing.tWalkEnd,
-                embedMs: timing.tEmbedEnd - timing.tFtsEnd,
-                ftsMs: timing.tFtsEnd - timing.tLlmEnd,
+                embedMs: timing.tEmbedEnd - timing.tLlmEnd,
+                ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
             },
             ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
         };

package/dist/llm/graph-extract.js

@@ -20,11 +20,11 @@
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */
+import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common";
 import { warn, warnVerbose } from "../core/warn";
 import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
 import { tryLlmFeature } from "./feature-gate";
-import userPromptTemplate from "./prompts/graph-extract-user-prompt.md" with { type: "text" };
 /**
  * Separator token used between assets in a batch prompt.
  * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.

package/dist/output/cli-hints.js

@@ -10,6 +10,6 @@
  * `EMBEDDED_HINTS` (`--detail brief`, short reference, ~40 lines) and
  * `EMBEDDED_HINTS_FULL` (`--detail normal|full`, ~250 lines).
  */
-import EMBEDDED_HINTS_FULL from "./cli-hints-full.md" with { type: "text" };
-import EMBEDDED_HINTS from "./cli-hints-short.md" with { type: "text" };
+import EMBEDDED_HINTS_FULL from "../assets/hints/cli-hints-full.md" with { type: "text" };
+import EMBEDDED_HINTS from "../assets/hints/cli-hints-short.md" with { type: "text" };
 export { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL };

package/dist/setup/detect.js

@@ -64,6 +64,33 @@ 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" },

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

@@ -0,0 +1,170 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function homeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? "";
+}
+// ── Claude Code Importer ─────────────────────────────────────────────────────
+/**
+ * Imports LLM config from a Claude Code installation.
+ *
+ * Claude Code stores settings in `~/.claude/settings.json` or `~/.claude.json`.
+ * The model field may appear at the root or under `env.ANTHROPIC_MODEL`.
+ * The API key is always `ANTHROPIC_API_KEY`.
+ */
+const claudeCodeImporter = {
+    harnessName: "Claude Code",
+    detect() {
+        const home = homeDir();
+        // Claude Code is installed if the ~/.claude/ directory exists
+        return fs.existsSync(path.join(home, ".claude"));
+    },
+    importConfig() {
+        const home = homeDir();
+        // Try ~/.claude/settings.json, then ~/.claude.json
+        const candidates = [path.join(home, ".claude", "settings.json"), path.join(home, ".claude.json")];
+        for (const filePath of candidates) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+                // Claude Code settings: model may be at root or nested under env
+                const envBlock = raw.env;
+                const model = typeof raw.model === "string"
+                    ? raw.model
+                    : typeof envBlock?.ANTHROPIC_MODEL === "string"
+                        ? String(envBlock.ANTHROPIC_MODEL)
+                        : undefined;
+                return {
+                    harnessName: "Claude Code",
+                    provider: "anthropic",
+                    model: model ?? "claude-sonnet-4-5",
+                    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+                };
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        // ~/.claude exists but no readable settings — still return basic Anthropic config
+        return {
+            harnessName: "Claude Code",
+            provider: "anthropic",
+            model: "claude-sonnet-4-5",
+            apiKeyEnvVar: "ANTHROPIC_API_KEY",
+        };
+    },
+};
+// ── OpenCode Importer ────────────────────────────────────────────────────────
+/**
+ * Imports LLM config from an OpenCode installation.
+ *
+ * OpenCode stores config in `~/.config/opencode/config.json` or
+ * `~/.opencode/config.json`. Its schema has a `providers` array and a
+ * `model` field. API keys in providers appear as `$ENV_VAR_NAME` references.
+ */
+const openCodeImporter = {
+    harnessName: "OpenCode",
+    detect() {
+        const home = homeDir();
+        return fs.existsSync(path.join(home, ".config", "opencode")) || fs.existsSync(path.join(home, ".opencode"));
+    },
+    importConfig() {
+        const home = homeDir();
+        const candidates = [
+            path.join(home, ".config", "opencode", "config.json"),
+            path.join(home, ".opencode", "config.json"),
+            path.join(process.cwd(), ".opencode", "config.json"),
+        ];
+        for (const filePath of candidates) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+                // OpenCode config shape: { model?: string, providers?: Array<{id, apiKey, baseUrl, ...}> }
+                const model = typeof raw.model === "string" ? raw.model : undefined;
+                // Extract provider info from the first entry in the providers array
+                let provider;
+                let baseUrl;
+                let apiKeyEnvVar;
+                const providers = Array.isArray(raw.providers) ? raw.providers : [];
+                if (providers.length > 0) {
+                    const first = providers[0];
+                    provider = typeof first?.id === "string" ? first.id : undefined;
+                    baseUrl =
+                        typeof first?.baseUrl === "string"
+                            ? first.baseUrl
+                            : typeof first?.base_url === "string"
+                                ? first.base_url
+                                : undefined;
+                    // apiKey is an env var reference like "$OPENAI_API_KEY" — extract the var name
+                    const apiKeyVal = typeof first?.apiKey === "string" ? first.apiKey : "";
+                    if (apiKeyVal.startsWith("$")) {
+                        apiKeyEnvVar = apiKeyVal.slice(1);
+                    }
+                }
+                return {
+                    harnessName: "OpenCode",
+                    provider,
+                    model,
+                    baseUrl,
+                    apiKeyEnvVar,
+                };
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        return null;
+    },
+};
+// ── 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;
+    }
+}