akm-cli 0.7.5 → 0.8.0-rc.3

package/dist/commands/lint/base-linter.js

@@ -0,0 +1,291 @@
+import fs from "node:fs";
+import path from "node:path";
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function formatDate(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+function checkUnquotedColon(frontmatterText) {
+    if (!frontmatterText)
+        return null;
+    for (const line of frontmatterText.split(/\r?\n/)) {
+        const match = line.match(/^description:\s*(.*)/);
+        if (!match)
+            continue;
+        const value = match[1].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            return null;
+        }
+        if (value.includes(":")) {
+            return `description value contains unquoted colon: ${value}`;
+        }
+    }
+    return null;
+}
+function fixUnquotedColon(raw) {
+    return raw.replace(/^(description:\s*)(.*)/m, (_match, prefix, value) => {
+        const trimmed = value.trim();
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return _match;
+        }
+        const escaped = trimmed.replace(/"/g, '\\"');
+        return `${prefix}"${escaped}"`;
+    });
+}
+function checkMissingUpdated(data, frontmatterText) {
+    return frontmatterText !== null && !("updated" in data);
+}
+function fixMissingUpdated(raw, mtime) {
+    const dateStr = formatDate(mtime);
+    return raw.replace(/^(---\n[\s\S]*?)\n---/m, `$1\nupdated: ${dateStr}\n---`);
+}
+// ── stale-path helpers ────────────────────────────────────────────────────────
+function checkStalePath(body) {
+    const pathRe = /\/home\/[^\s"'`)\]>,]+/g;
+    let match;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
+    while ((match = pathRe.exec(body)) !== null) {
+        const candidate = match[0];
+        if (!fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+// ── missing-ref helpers ───────────────────────────────────────────────────────
+const REF_RE = /(?:^|[\s`"'(])((agent|command|knowledge|memory|script|skill|workflow|lesson|task|wiki|vault):[^\s"'`)\]>,\n]+)/gm;
+/** Map from ref type to relative path pattern within stashRoot. Returns null to skip. */
+function refToRelPath(refType, refName) {
+    switch (refType) {
+        case "agent":
+            return path.join("agents", `${refName}.md`);
+        case "command":
+            return path.join("commands", `${refName}.md`);
+        case "knowledge":
+            return path.join("knowledge", `${refName}.md`);
+        case "memory":
+            return path.join("memories", `${refName}.md`);
+        case "script":
+            return null; // scripts live in nested dirs — skip
+        case "skill":
+            return path.join("skills", refName, "SKILL.md");
+        case "workflow":
+            return path.join("workflows", `${refName}.md`);
+        case "lesson":
+            return path.join("lessons", `${refName}.md`);
+        case "task":
+            return path.join("tasks", `${refName}.md`);
+        case "wiki":
+            return path.join("wikis", `${refName}.md`);
+        case "vault":
+            // Vaults are .env files. The canonical name "default" (or empty) maps to
+            // ".env"; any other name maps to "<name>.env".  This mirrors the vault
+            // asset-spec toAssetPath logic in src/core/asset-spec.ts.
+            if (!refName || refName === "default") {
+                return path.join("vaults", ".env");
+            }
+            return path.join("vaults", `${refName}.env`);
+        default:
+            return null;
+    }
+}
+/**
+ * Returns true if `relPath` resolves to a real file (or multi-file directory
+ * primary) in ANY of the provided stash roots.
+ */
+function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
+    for (const root of stashRoots) {
+        const absPath = path.join(root, relPath);
+        if (fs.existsSync(absPath))
+            return true;
+        // Multi-file skill layout: directory containing SKILL.md
+        const bareDir = absPath.replace(/\.md$/, "");
+        if (fs.existsSync(bareDir) && fs.existsSync(path.join(bareDir, "SKILL.md")))
+            return true;
+        // .derived.md variant for memory refs
+        if (refType === "memory") {
+            const derivedPath = path.join(root, "memories", `${refName}.derived.md`);
+            if (fs.existsSync(derivedPath))
+                return true;
+        }
+        // Knowledge-specific: search subdirectories like knowledge/projects/, knowledge/tools/, etc.
+        if (refType === "knowledge") {
+            try {
+                const knowledgeDir = path.join(root, "knowledge");
+                if (fs.existsSync(knowledgeDir) && fs.statSync(knowledgeDir).isDirectory()) {
+                    const entries = fs.readdirSync(knowledgeDir);
+                    for (const entry of entries) {
+                        const subPath = path.join(knowledgeDir, entry, `${refName}.md`);
+                        if (fs.existsSync(subPath))
+                            return true;
+                    }
+                }
+            }
+            catch {
+                // Ignore errors reading directory
+            }
+        }
+        // Fallback: the refName may already encode the full stash-relative path
+        // (e.g. knowledge:skills/foo/references/bar where the file lives at
+        // <stash>/skills/foo/references/bar.md, not <stash>/knowledge/skills/...).
+        const directPath = path.join(root, `${refName}.md`);
+        if (fs.existsSync(directPath))
+            return true;
+        const directDir = path.join(root, refName);
+        if (fs.existsSync(directDir) && fs.existsSync(path.join(directDir, "SKILL.md")))
+            return true;
+    }
+    return false;
+}
+/**
+ * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
+ * body that does not resolve to a real file under any of the provided stash roots.
+ *
+ * Skips false-positive patterns:
+ * - Shell variables: memory:$(cmd) or knowledge:${VAR}
+ * - ACP type notation: agent::Type (double colons are C++/ACP syntax)
+ * - Incomplete/placeholder refs: slug is single character or "**"
+ */
+function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
+    const allRoots = [stashRoot, ...extraStashRoots];
+    const missing = [];
+    let match;
+    const re = new RegExp(REF_RE.source, REF_RE.flags);
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
+    while ((match = re.exec(body)) !== null) {
+        const fullRef = match[1]; // e.g. "workflow:foo" or "local//workflow:foo"
+        // Skip shell variables: memory:$(cmd) or knowledge:${VAR}
+        if (fullRef.includes("$(") || fullRef.includes("${")) {
+            continue;
+        }
+        // Skip ACP type notation: agent::Type (double colons)
+        if (fullRef.includes("::")) {
+            continue;
+        }
+        // Strip leading "local//" prefix if present
+        let ref = fullRef;
+        if (ref.startsWith("local//")) {
+            ref = ref.slice("local//".length);
+        }
+        else if (fullRef.includes("//")) {
+            // Has a remote origin prefix (e.g. "npm:", "github:", "owner/repo//") — skip
+            continue;
+        }
+        // Skip refs that start with obvious remote prefixes
+        const colonIdx = ref.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const refType = ref.slice(0, colonIdx);
+        const refName = ref.slice(colonIdx + 1);
+        // Guard against empty names or names that look like paths/URLs
+        if (!refName || refName.startsWith("/") || refName.startsWith("~") || refName.startsWith("http")) {
+            continue;
+        }
+        // Skip placeholder/incomplete refs: single character slug or "**"
+        if (refName.length <= 1 || refName === "**") {
+            continue;
+        }
+        const relPath = refToRelPath(refType, refName);
+        if (relPath === null)
+            continue; // type is skipped
+        if (!refExistsInAnyStash(relPath, refType, refName, allRoots)) {
+            missing.push({ ref: fullRef, resolvedRelPath: relPath });
+        }
+    }
+    return missing;
+}
+// ── BaseLinter ────────────────────────────────────────────────────────────────
+/**
+ * Abstract base class providing the two cross-type checks shared by all asset
+ * linters: `unquoted-colon` and `missing-updated`.
+ *
+ * Subclasses call `runBaseChecks(ctx)` and append any type-specific issues.
+ * File mutations triggered by base checks are flushed to disk inside this
+ * method; subclasses must re-read `ctx.raw` if they need the post-fix content
+ * (in practice the base class updates `ctx.raw` in place when `fix` is true).
+ */
+export class BaseLinter {
+    runBaseChecks(ctx) {
+        const issues = [];
+        let currentRaw = ctx.raw;
+        let modified = false;
+        // ── 1. unquoted-colon ──────────────────────────────────────────────────
+        const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
+        if (unquotedColonDetail) {
+            if (ctx.fix) {
+                currentRaw = fixUnquotedColon(currentRaw);
+                modified = true;
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "unquoted-colon",
+                    detail: unquotedColonDetail,
+                    fixed: true,
+                });
+            }
+            else {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "unquoted-colon",
+                    detail: unquotedColonDetail,
+                    fixed: false,
+                });
+            }
+        }
+        // ── 2. missing-updated ─────────────────────────────────────────────────
+        if (checkMissingUpdated(ctx.data, ctx.frontmatter)) {
+            if (ctx.fix) {
+                let mtime;
+                try {
+                    mtime = fs.statSync(ctx.filePath).mtime;
+                }
+                catch {
+                    mtime = new Date();
+                }
+                currentRaw = fixMissingUpdated(currentRaw, mtime);
+                modified = true;
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "missing-updated",
+                    detail: `stamped updated: ${formatDate(mtime)}`,
+                    fixed: true,
+                });
+            }
+            else {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "missing-updated",
+                    detail: "no updated field in frontmatter",
+                    fixed: false,
+                });
+            }
+        }
+        if (modified) {
+            fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
+            // Propagate the mutated raw back so subclasses can re-parse if needed
+            ctx.raw = currentRaw;
+        }
+        // ── 3. stale-path ──────────────────────────────────────────────────────
+        const stalePathMatch = checkStalePath(ctx.body);
+        if (stalePathMatch) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "stale-path",
+                detail: `nonexistent path: ${stalePathMatch}`,
+                fixed: false,
+            });
+        }
+        // ── 4. missing-ref ─────────────────────────────────────────────────────
+        const missingRefs = checkMissingRefs(ctx.body, ctx.stashRoot, ctx.extraStashRoots);
+        for (const { ref, resolvedRelPath } of missingRefs) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-ref",
+                detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/lint/command-linter.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `commands/` assets.
+ *
+ * Extra check beyond base:
+ *   - `missing-name-or-type`: frontmatter exists but `name` or `type` field is
+ *     absent. Not auto-fixable; detail includes a suggested slug.
+ */
+export class CommandLinter extends BaseLinter {
+    types = ["commands"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const missingFieldDetail = this.#checkMissingNameOrType(ctx.data, ctx.frontmatter);
+        if (missingFieldDetail) {
+            const slug = this.#suggestSlug(ctx.filePath);
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-name-or-type",
+                detail: `${missingFieldDetail}; suggested slug: ${slug}`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+    #checkMissingNameOrType(data, frontmatterText) {
+        if (!frontmatterText)
+            return null;
+        const missingFields = [];
+        if (!("name" in data) || !data.name)
+            missingFields.push("name");
+        if (!("type" in data) || !data.type)
+            missingFields.push("type");
+        if (missingFields.length === 0)
+            return null;
+        return `missing fields: ${missingFields.join(", ")}`;
+    }
+    #suggestSlug(filePath) {
+        return path
+            .basename(filePath, ".md")
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "");
+    }
+}

package/dist/commands/lint/default-linter.js

@@ -0,0 +1,13 @@
+import { BaseLinter } from "./base-linter";
+/**
+ * Default linter for asset types that have no type-specific rules beyond the
+ * base checks (`unquoted-colon`, `missing-updated`).
+ *
+ * Covers: `lessons`.
+ */
+export class DefaultLinter extends BaseLinter {
+    types = ["lessons"];
+    lint(ctx) {
+        return this.runBaseChecks(ctx);
+    }
+}

package/dist/commands/lint/index.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "../../core/common";
+import { loadConfig } from "../../core/config";
+import { parseFrontmatter } from "../../core/frontmatter";
+import { resolveSourceEntries } from "../../indexer/search-source";
+import { getLinterForType } from "./registry";
+import { checkVaultForDangerousKeys } from "./vault-key-rules";
+// ── Constants ─────────────────────────────────────────────────────────────────
+const STASH_SUBDIRS = [
+    "agents",
+    "commands",
+    "memories",
+    "skills",
+    "workflows",
+    "lessons",
+    "tasks",
+    "knowledge",
+];
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function collectMarkdownFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function collectEnvFiles(dir) {
+    const results = [];
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                results.push(...collectEnvFiles(full));
+            else if (entry.isFile() && entry.name.endsWith(".env"))
+                results.push(full);
+        }
+    }
+    catch {
+        /* dir may not exist */
+    }
+    return results;
+}
+/** True when the issue represents a file deletion that was successfully applied. */
+function isFileDeletion(issue) {
+    return issue.fixed === true && (issue.issue === "orphaned-stub" || issue.issue === "placeholder-stub");
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
+export function akmLint(options = {}) {
+    const stashRoot = options.dir ?? options.config?.stashDir ?? resolveStashDir();
+    // Collect secondary stash roots from configured filesystem sources so that
+    // cross-stash refs (e.g. referencing assets in dimm-city/agent-stash) are
+    // not falsely flagged as missing-ref.
+    const cfg = options.config ?? loadConfig();
+    const extraStashRoots = resolveSourceEntries(stashRoot, cfg)
+        .map((s) => s.path)
+        .filter((p) => p !== stashRoot && fs.existsSync(p));
+    const fix = options.fix ?? false;
+    const fixed = [];
+    const flagged = [];
+    for (const subdir of STASH_SUBDIRS) {
+        const dirPath = path.join(stashRoot, subdir);
+        const files = collectMarkdownFiles(dirPath);
+        const linter = getLinterForType(subdir);
+        // If the linter supports directory-level checks, run them for each direct
+        // subdirectory once before the per-file loop.
+        if (typeof linter.lintDirectory === "function" && fs.existsSync(dirPath)) {
+            for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    const subdirIssues = linter.lintDirectory(path.join(dirPath, entry.name), stashRoot);
+                    for (const issue of subdirIssues) {
+                        if (issue.fixed) {
+                            fixed.push(issue);
+                        }
+                        else {
+                            flagged.push(issue);
+                        }
+                    }
+                }
+            }
+        }
+        for (const filePath of files) {
+            const relPath = path.relative(stashRoot, filePath);
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const { data, content: body, frontmatter } = parseFrontmatter(raw);
+            const issues = linter.lint({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots });
+            let fileDeleted = false;
+            for (const issue of issues) {
+                if (isFileDeletion(issue)) {
+                    fileDeleted = true;
+                    fixed.push(issue);
+                }
+                else if (issue.fixed) {
+                    fixed.push(issue);
+                }
+                else {
+                    flagged.push(issue);
+                }
+            }
+            if (fileDeleted)
+                continue; // file is gone — skip any remaining checks
+        }
+    }
+    // ── Vault dangerous-key pass ───────────────────────────────────────────────
+    // Scan every `.env` file under <stashRoot>/vaults/ (and secondary stash
+    // roots) for keys that are known to enable process-execution hijacking.
+    // This is a warn-only pass — findings go into `flagged`, never `fixed`.
+    const vaultRoots = [stashRoot, ...extraStashRoots];
+    for (const root of vaultRoots) {
+        const vaultsDir = path.join(root, "vaults");
+        if (!fs.existsSync(vaultsDir))
+            continue;
+        const envFiles = collectEnvFiles(vaultsDir);
+        for (const vaultPath of envFiles) {
+            const baseName = path.basename(vaultPath, ".env");
+            // canonical vault ref: "default" (or empty) maps to ".env" → vault:default
+            const vaultRef = baseName === "" ? "vault:default" : `vault:${baseName}`;
+            const relPath = path.relative(root, vaultPath);
+            const issues = checkVaultForDangerousKeys(vaultPath, relPath, vaultRef);
+            for (const issue of issues) {
+                flagged.push(issue);
+            }
+        }
+    }
+    return {
+        ok: flagged.length === 0,
+        fixed,
+        flagged,
+        summary: { fixed: fixed.length, flagged: flagged.length },
+    };
+}

package/dist/commands/lint/knowledge-linter.js

@@ -0,0 +1,13 @@
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `knowledge/` assets.
+ *
+ * All checks are inherited from BaseLinter (`unquoted-colon`, `missing-updated`,
+ * `stale-path`, `missing-ref`). No type-specific rules needed.
+ */
+export class KnowledgeLinter extends BaseLinter {
+    types = ["knowledge"];
+    lint(ctx) {
+        return this.runBaseChecks(ctx);
+    }
+}

package/dist/commands/lint/memory-linter.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `memories/` assets.
+ *
+ * Extra check beyond base:
+ *   - `orphaned-stub`: `inferenceProcessed: true` in frontmatter AND body < 100
+ *     chars AND no sibling `.derived.md` file. Fix: delete the stub file.
+ */
+export class MemoryLinter extends BaseLinter {
+    types = ["memories"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        // After base checks the file might have been mutated; re-parse body from
+        // ctx.raw which was updated in place by BaseLinter when fix === true.
+        const body = ctx.body;
+        if (this.#isOrphanedStub(ctx.data, body, ctx.filePath)) {
+            if (ctx.fix) {
+                try {
+                    fs.unlinkSync(ctx.filePath);
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "orphaned-stub",
+                        detail: "deleted orphaned stub",
+                        fixed: true,
+                    });
+                }
+                catch (e) {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "orphaned-stub",
+                        detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                        fixed: false,
+                    });
+                }
+                // Signal caller to skip remaining checks via a sentinel issue
+                // (caller must handle the deletion path; we mark the file as gone)
+                return issues;
+            }
+            issues.push({
+                file: ctx.relPath,
+                issue: "orphaned-stub",
+                detail: "inferenceProcessed stub with no derived sibling",
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+    #isOrphanedStub(data, body, filePath) {
+        if (data.inferenceProcessed !== true)
+            return false;
+        if (body.trim().length >= 100)
+            return false;
+        const baseName = filePath.replace(/\.md$/, "");
+        const derivedPath = `${baseName}.derived.md`;
+        return !fs.existsSync(derivedPath);
+    }
+}

package/dist/commands/lint/registry.js

@@ -0,0 +1,33 @@
+import { AgentLinter } from "./agent-linter";
+import { CommandLinter } from "./command-linter";
+import { DefaultLinter } from "./default-linter";
+import { KnowledgeLinter } from "./knowledge-linter";
+import { MemoryLinter } from "./memory-linter";
+import { SkillLinter } from "./skill-linter";
+import { TaskLinter } from "./task-linter";
+import { WorkflowLinter } from "./workflow-linter";
+// Singleton instances — one per type, shared across all lint runs.
+const LINTERS = [
+    new AgentLinter(),
+    new MemoryLinter(),
+    new WorkflowLinter(),
+    new CommandLinter(),
+    new KnowledgeLinter(),
+    new SkillLinter(),
+    new TaskLinter(),
+    new DefaultLinter(),
+];
+const LINTER_MAP = new Map();
+for (const linter of LINTERS) {
+    for (const t of linter.types) {
+        LINTER_MAP.set(t, linter);
+    }
+}
+const DEFAULT_LINTER = new DefaultLinter();
+/**
+ * Return the appropriate linter for the given stash subdirectory name.
+ * Falls back to `DefaultLinter` for unknown types.
+ */
+export function getLinterForType(subdir) {
+    return LINTER_MAP.get(subdir) ?? DEFAULT_LINTER;
+}

package/dist/commands/lint/skill-linter.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `skills/` assets.
+ *
+ * Skills are **directory bundles**: each skill lives at `skills/<name>/` and
+ * must contain a `SKILL.md` entry-point file.
+ *
+ * Directory-level check (via `lintDirectory`):
+ *   - `missing-skill-md`: a skill subdirectory has no `SKILL.md`. Not
+ *     auto-fixable — flagged with detail `"no SKILL.md in skills/<name>/"`.
+ *
+ * Per-file check:
+ *   - Base checks (`unquoted-colon`, `missing-updated`) are run against any
+ *     `.md` files found inside skill subdirectories.
+ */
+export class SkillLinter extends BaseLinter {
+    types = ["skills"];
+    /**
+     * Called once per direct subdirectory of `skills/`. Reports a
+     * `missing-skill-md` issue when the directory does not contain a `SKILL.md`.
+     */
+    lintDirectory(subdirPath, stashRoot) {
+        const skillMdPath = path.join(subdirPath, "SKILL.md");
+        if (!fs.existsSync(skillMdPath)) {
+            const relDir = path.relative(stashRoot, subdirPath);
+            return [
+                {
+                    file: relDir,
+                    issue: "missing-skill-md",
+                    detail: `no SKILL.md in ${relDir}/`,
+                    fixed: false,
+                },
+            ];
+        }
+        return [];
+    }
+    lint(ctx) {
+        return this.runBaseChecks(ctx);
+    }
+}