akm-cli 0.4.0 → 0.5.0-rc1

package/dist/llm.js

@@ -1,5 +1,5 @@
 import { fetchWithTimeout } from "./common";
-async function chatCompletion(config, messages) {
+export async function chatCompletion(config, messages, options) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
         headers.Authorization = `Bearer ${config.apiKey}`;
@@ -10,8 +10,8 @@ async function chatCompletion(config, messages) {
         body: JSON.stringify({
             model: config.model,
             messages,
-            temperature: config.temperature ?? 0.3,
-            max_tokens: config.maxTokens ?? 512,
+            temperature: options?.temperature ?? config.temperature ?? 0.3,
+            max_tokens: options?.maxTokens ?? config.maxTokens ?? 512,
         }),
     });
     if (!response.ok) {
@@ -21,6 +21,23 @@ async function chatCompletion(config, messages) {
     const json = (await response.json());
     return json.choices?.[0]?.message?.content?.trim() ?? "";
 }
+/** Strip leading/trailing markdown code fences from an LLM response. */
+function stripJsonFences(raw) {
+    return raw
+        .trim()
+        .replace(/^```(?:json)?\s*\n?/i, "")
+        .replace(/\n?```\s*$/i, "")
+        .trim();
+}
+/** Parse a possibly-fenced JSON response. Returns undefined if invalid. */
+export function parseJsonResponse(raw) {
+    try {
+        return JSON.parse(stripJsonFences(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
 // ── Metadata Enhancement ────────────────────────────────────────────────────
 const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
 /**
@@ -50,28 +67,22 @@ Return ONLY the JSON object, no explanation.`;
         { role: "system", content: SYSTEM_PROMPT },
         { role: "user", content: userPrompt },
     ]);
-    try {
-        // Strip markdown code fences if present
-        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "");
-        const parsed = JSON.parse(cleaned);
-        const result = {};
-        if (typeof parsed.description === "string" && parsed.description) {
-            result.description = parsed.description;
-        }
-        if (Array.isArray(parsed.searchHints)) {
-            result.searchHints = parsed.searchHints
-                .filter((s) => typeof s === "string" && s.trim().length > 0)
-                .slice(0, 8);
-        }
-        if (Array.isArray(parsed.tags)) {
-            result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
-        }
-        return result;
-    }
-    catch {
-        // LLM returned unparseable output, return empty
+    const parsed = parseJsonResponse(raw);
+    if (!parsed)
         return {};
+    const result = {};
+    if (typeof parsed.description === "string" && parsed.description) {
+        result.description = parsed.description;
     }
+    if (Array.isArray(parsed.searchHints)) {
+        result.searchHints = parsed.searchHints
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .slice(0, 8);
+    }
+    if (Array.isArray(parsed.tags)) {
+        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+    }
+    return result;
 }
 /**
  * Check if the LLM endpoint is reachable.
@@ -85,3 +96,33 @@ export async function isLlmAvailable(config) {
         return false;
     }
 }
+// ── Capability probe ────────────────────────────────────────────────────────
+/**
+ * Ask the model to emit a strict JSON object so we know whether the knowledge
+ * wiki ingest/lint flows can rely on structured output. Failure is non-fatal —
+ * the caller can fall back to assist-only mode.
+ */
+export async function probeLlmCapabilities(config) {
+    try {
+        const raw = await chatCompletion(config, [
+            {
+                role: "system",
+                content: "You return only valid JSON. No prose, no markdown fences.",
+            },
+            {
+                role: "user",
+                content: 'Return exactly this JSON object and nothing else: {"ok": true, "ingest": true, "lint": true}',
+            },
+        ], { maxTokens: 64, temperature: 0 });
+        if (!raw)
+            return { reachable: false, structuredOutput: false, error: "empty response" };
+        const parsed = parseJsonResponse(raw);
+        return {
+            reachable: true,
+            structuredOutput: Boolean(parsed && parsed.ok === true),
+        };
+    }
+    catch (err) {
+        return { reachable: false, structuredOutput: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}

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,36 @@ 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;
+    }
+}
 /**
  * Extract `@param` JSDoc tags from a script file's leading comment block.
  *
@@ -316,6 +370,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 +380,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;
@@ -418,6 +477,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 +487,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/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";