akm-cli 0.5.0 → 0.6.0-rc2

package/dist/sources/providers/sync-from-ref.js

@@ -0,0 +1,45 @@
+/**
+ * Unified install-ref dispatcher.
+ *
+ * Replaces the historical `installRegistryRef()` entry point. Given an
+ * unparsed install ref, this resolves the right syncable provider and
+ * invokes its `sync()` method.
+ *
+ * Audit is intentionally NOT performed here; callers (`akmAdd`,
+ * `akmUpdate`) decide whether to run `auditInstallCandidate` on the
+ * synced `contentDir` because they own the `--trust` flag.
+ */
+import { UsageError } from "../../core/errors";
+import { parseRegistryRef } from "../../registry/resolve";
+import { detectStashRoot } from "./provider-utils";
+export async function syncFromRef(ref, options) {
+    const parsed = parseRegistryRef(ref);
+    if (parsed.source === "local") {
+        return syncLocalRef(parsed, options);
+    }
+    if (parsed.source === "npm") {
+        const { syncNpmRef } = await import("./npm");
+        return syncNpmRef(ref, options);
+    }
+    if (parsed.source === "git" || parsed.source === "github") {
+        const { syncRegistryGitRef } = await import("./git");
+        return syncRegistryGitRef(ref, options);
+    }
+    // Exhaustiveness — `parseRegistryRef` only emits the four sources above.
+    throw new UsageError(`No syncable provider for ref: ${ref} (source=${parsed.source})`);
+}
+function syncLocalRef(parsed, options) {
+    const stashRoot = detectStashRoot(parsed.sourcePath);
+    const syncedAt = (options?.now ?? new Date()).toISOString();
+    return {
+        id: parsed.id,
+        source: "local",
+        ref: parsed.ref,
+        artifactUrl: parsed.sourcePath,
+        contentDir: stashRoot,
+        cacheDir: parsed.sourcePath,
+        extractedDir: parsed.sourcePath,
+        writable: options?.writable,
+        syncedAt,
+    };
+}

package/dist/sources/providers/tar-utils.js

@@ -0,0 +1,154 @@
+/**
+ * Tar archive extraction and integrity verification utilities.
+ *
+ * These helpers are security-critical: they validate archive entries to
+ * prevent path traversal, run a post-extraction scan for symlink escapes,
+ * and verify integrity hashes (SRI or hex shasum) before extraction.
+ *
+ * Extracted from `registry-install.ts` and shared by all syncable
+ * providers that fetch tarballs (currently `NpmSourceProvider` and the
+ * registry index builder).
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isWithin } from "../../core/common";
+import { warn } from "../../core/warn";
+/**
+ * Verify an archive's integrity against a known hash. Throws and removes
+ * the archive when verification fails.
+ *
+ * Supports SRI hashes (sha256-/sha512-) and hex SHA-1 from npm.
+ * Skips verification for git/github sources (revisions are commit SHAs,
+ * not content hashes).
+ */
+export function verifyArchiveIntegrity(archivePath, expected, source) {
+    if (!expected)
+        return;
+    // For GitHub and git sources, resolvedRevision is a commit SHA, not a content hash.
+    // Content integrity cannot be verified from a commit hash, so skip verification.
+    if (source === "github" || source === "git")
+        return;
+    const fileBuffer = fs.readFileSync(archivePath);
+    // SRI hash format: sha256-<base64> or sha512-<base64>
+    if (expected.startsWith("sha256-") || expected.startsWith("sha512-")) {
+        const dashIndex = expected.indexOf("-");
+        const algorithm = expected.slice(0, dashIndex);
+        const expectedBase64 = expected.slice(dashIndex + 1);
+        const actualBase64 = createHash(algorithm).update(fileBuffer).digest("base64");
+        if (actualBase64 !== expectedBase64) {
+            fs.unlinkSync(archivePath);
+            throw new Error(`Integrity check failed for ${archivePath}: expected ${algorithm} digest ${expectedBase64}, got ${actualBase64}`);
+        }
+        return;
+    }
+    // Hex shasum (SHA-1 from npm)
+    if (/^[0-9a-f]{40}$/i.test(expected)) {
+        const actualHex = createHash("sha1").update(fileBuffer).digest("hex");
+        if (actualHex.toLowerCase() !== expected.toLowerCase()) {
+            fs.unlinkSync(archivePath);
+            throw new Error(`Integrity check failed for ${archivePath}: expected sha1 ${expected}, got ${actualHex}`);
+        }
+        return;
+    }
+    // Unrecognized format — warn and skip verification
+    warn("Unrecognized integrity format: %s — verification skipped", expected);
+}
+/**
+ * Extract a tar.gz archive into `destinationDir`, validating entries first
+ * (no absolute paths, no `..` traversal, no NUL bytes), invoking tar with
+ * `--no-same-owner --strip-components=1`, and finally scanning the extracted
+ * tree for symlinks that would escape the destination.
+ */
+export function extractTarGzSecure(archivePath, destinationDir) {
+    const listResult = spawnSync("tar", ["tzf", archivePath], { encoding: "utf8" });
+    if (listResult.status !== 0) {
+        const err = listResult.stderr?.trim() || listResult.error?.message || "unknown error";
+        throw new Error(`Failed to inspect archive ${archivePath}: ${err}`);
+    }
+    validateTarEntries(listResult.stdout);
+    fs.rmSync(destinationDir, { recursive: true, force: true });
+    fs.mkdirSync(destinationDir, { recursive: true });
+    const extractResult = spawnSync("tar", ["xzf", archivePath, "--no-same-owner", "--strip-components=1", "-C", destinationDir], { encoding: "utf8" });
+    if (extractResult.status !== 0) {
+        const err = extractResult.stderr?.trim() || extractResult.error?.message || "unknown error";
+        throw new Error(`Failed to extract archive ${archivePath}: ${err}`);
+    }
+    // Post-extraction scan: verify all extracted files are within destinationDir
+    // This mitigates TOCTOU between validateTarEntries (list) and tar extract.
+    scanExtractedFiles(destinationDir, destinationDir);
+}
+function scanExtractedFiles(dir, root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        // Reject only entries whose name is exactly the parent-traversal segment
+        // (or `.`). Substring matches (`foo..bar`, `archive..2024.tar`) are
+        // legitimate filenames that the previous `entry.name.includes("..")`
+        // check rejected as false positives — flagged in PR #168 review.
+        if (entry.name === ".." || entry.name === ".") {
+            throw new Error(`Post-extraction scan: suspicious entry name: ${fullPath}`);
+        }
+        // Symlinks: resolve and confirm the target stays inside the destination.
+        if (entry.isSymbolicLink()) {
+            const target = fs.realpathSync(fullPath);
+            if (!isWithin(target, root)) {
+                throw new Error(`Post-extraction scan: symlink escapes destination directory: ${fullPath} -> ${target}`);
+            }
+        }
+        // Belt-and-suspenders: check that the resolved path of regular entries
+        // stays within the destination root. This catches path traversal attempts
+        // via symlink TOCTOU, directory renames, or any other anomalies.
+        if (!entry.isSymbolicLink()) {
+            const resolved = path.resolve(fullPath);
+            if (!isWithin(resolved, root)) {
+                throw new Error(`Post-extraction scan: entry escapes destination directory: ${fullPath}`);
+            }
+        }
+        if (entry.isDirectory()) {
+            scanExtractedFiles(fullPath, root);
+        }
+    }
+}
+/**
+ * Validate the line-oriented `tar tzf` listing for unsafe entries.
+ *
+ * Rejects:
+ *   - empty/NUL-containing entries
+ *   - absolute paths
+ *   - parent traversal (`..` / `../`)
+ *   - any entry that would still escape after `--strip-components=1`
+ */
+export function validateTarEntries(listOutput) {
+    const lines = listOutput.split(/\r?\n/).filter(Boolean);
+    for (const rawLine of lines) {
+        const entry = rawLine.trim();
+        if (!entry || entry.includes("\0")) {
+            throw new Error(`Archive contains an invalid entry: ${JSON.stringify(rawLine)}`);
+        }
+        if (entry.startsWith("/")) {
+            throw new Error(`Archive contains an absolute path entry: ${entry}`);
+        }
+        const normalized = path.posix.normalize(entry);
+        if (normalized === ".." || normalized.startsWith("../")) {
+            throw new Error(`Archive contains a path traversal entry: ${entry}`);
+        }
+        const parts = normalized.split("/").filter(Boolean);
+        const stripped = parts.slice(1).join("/");
+        if (!stripped)
+            continue;
+        const normalizedStripped = path.posix.normalize(stripped);
+        if (normalizedStripped === ".." ||
+            normalizedStripped.startsWith("../") ||
+            path.posix.isAbsolute(normalizedStripped)) {
+            throw new Error(`Archive contains an unsafe entry after strip-components: ${entry}`);
+        }
+    }
+}

package/dist/{stash-providers → sources/providers}/website.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { ConfigError, UsageError } from "../errors";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerStashProvider } from "../stash-provider-factory";
+import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap } from "../../core/common";
+import { ConfigError, UsageError } from "../../core/errors";
+import { getRegistryIndexCacheDir } from "../../core/paths";
+import { warn } from "../../core/warn";
+import { registerSourceProvider } from "../provider-factory";
 import { isExpired, sanitizeString } from "./provider-utils";
 /** Refresh website snapshots every 12 hours to balance freshness with scraping load. */
 const CACHE_REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000;
@@ -14,27 +15,48 @@ const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 const QUEUE_EXPANSION_FACTOR = 5;
 const MAX_PAGES_DEFAULT = 50;
 const MAX_DEPTH_DEFAULT = 3;
-class WebsiteStashProvider {
-    type = "website";
+/**
+ * Per-page body cap for website scraping. HTML pages this large are
+ * almost never useful as agent knowledge sources and a runaway server
+ * streaming tens of megabytes would blow memory with no upside.
+ */
+const WEBSITE_PAGE_BYTE_CAP = 5 * 1024 * 1024;
+/**
+ * Wall-clock cap for a full crawl (10 minutes). With per-request timeouts
+ * of 15s and a `maxPages` default of 50, an unresponsive site could
+ * otherwise stall `akm add` for 12.5 minutes with no feedback. Cap the
+ * whole crawl and return what we have when time runs out.
+ */
+const WEBSITE_CRAWL_WALL_CLOCK_MS = 10 * 60 * 1000;
+/**
+ * Website source provider — scrapes pages into a local mirror so the FTS5
+ * indexer can walk them. Implements the v1 {@link SourceProvider} interface
+ * (spec §2.1): `{ name, kind, init, path, sync }`.
+ *
+ * Reading is the indexer's job — this class doesn't implement `search` or
+ * `show`.
+ */
+class WebsiteSourceProvider {
+    kind = "website";
     name;
+    #config;
+    #url;
     constructor(config) {
+        this.#config = config;
         this.name = config.name ?? "website";
-        validateWebsiteUrl(config.url ?? "");
+        this.#url = validateWebsiteUrl(config.url ?? "");
     }
-    /** Content is indexed through the standard FTS5 pipeline. */
-    async search(_options) {
-        return { hits: [] };
+    async init(_ctx) {
+        // URL validation already happens in the constructor; nothing else to do.
     }
-    /** Content is local files, shown via showLocal. */
-    async show(_ref, _view) {
-        throw new Error("Website provider content is shown via local index");
+    path() {
+        return getCachePaths(this.#url).stashDir;
     }
-    /** Content is local; no remote show needed. */
-    canShow(_ref) {
-        return false;
+    async sync() {
+        await ensureWebsiteMirror(this.#config, { requireStashDir: true });
     }
 }
-registerStashProvider("website", (config) => new WebsiteStashProvider(config));
+registerSourceProvider("website", (config) => new WebsiteSourceProvider(config));
 function getCachePaths(siteUrl) {
     const key = createHash("sha256").update(normalizeSiteUrl(siteUrl)).digest("hex").slice(0, 16);
     const rootDir = path.join(getRegistryIndexCacheDir(), `website-${key}`);
@@ -49,6 +71,7 @@ async function ensureWebsiteMirror(config, options) {
     const normalizedUrl = validateWebsiteUrl(rawUrl);
     const cachePaths = getCachePaths(normalizedUrl);
     const requireStashDir = options?.requireStashDir === true;
+    const force = options?.force === true;
     let mtime = 0;
     try {
         mtime = fs.statSync(cachePaths.manifestPath).mtimeMs;
@@ -56,7 +79,8 @@ async function ensureWebsiteMirror(config, options) {
     catch {
         /* no cached manifest */
     }
-    if (mtime &&
+    if (!force &&
+        mtime &&
         !isExpired(mtime, CACHE_REFRESH_INTERVAL_MS) &&
         (!requireStashDir || hasExtractedSite(cachePaths.stashDir))) {
         return cachePaths;
@@ -124,7 +148,10 @@ async function crawlWebsite(startUrl, options) {
     const queue = [{ url: start.toString(), depth: 0 }];
     const visited = new Set();
     const pages = [];
+    const deadline = Date.now() + WEBSITE_CRAWL_WALL_CLOCK_MS;
     while (queue.length > 0 && pages.length < options.maxPages) {
+        if (Date.now() > deadline)
+            break;
         const next = queue.shift();
         if (!next)
             break;
@@ -149,6 +176,9 @@ async function crawlWebsite(startUrl, options) {
             queue.push({ url: candidate, depth: next.depth + 1 });
         }
     }
+    if (Date.now() > deadline) {
+        warn("[akm] website crawl stopped at the %ds wall-clock cap with %d/%d pages collected from %s.", WEBSITE_CRAWL_WALL_CLOCK_MS / 1000, pages.length, options.maxPages, startUrl);
+    }
     return pages;
 }
 async function fetchWebsitePage(pageUrl) {
@@ -164,7 +194,17 @@ async function fetchWebsitePage(pageUrl) {
         throw new Error(`Failed to fetch website content (${response.status}) from ${pageUrl}`);
     }
     const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
-    const body = await response.text();
+    let body;
+    try {
+        body = await readBodyWithByteCap(response, WEBSITE_PAGE_BYTE_CAP);
+    }
+    catch (err) {
+        if (err instanceof ResponseTooLargeError) {
+            // Skip oversized pages rather than aborting the whole crawl.
+            return null;
+        }
+        throw err;
+    }
     const finalUrl = normalizeCrawlUrl(response.url || pageUrl) ?? pageUrl;
     if (contentType.includes("text/html") || contentType.includes("application/xhtml+xml") || looksLikeMarkup(body)) {
         const title = extractHtmlTitle(body) || new URL(finalUrl).hostname;
@@ -440,4 +480,4 @@ function safeCodePointToString(value) {
         return undefined;
     }
 }
-export { ensureWebsiteMirror, getCachePaths, validateWebsiteInputUrl, validateWebsiteUrl, WebsiteStashProvider };
+export { ensureWebsiteMirror, getCachePaths, validateWebsiteInputUrl, validateWebsiteUrl, WebsiteSourceProvider };

package/dist/{stash-resolve.js → sources/resolve.js}

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "./asset-spec";
-import { hasErrnoCode, isWithin } from "./common";
-import { NotFoundError, UsageError } from "./errors";
-import { runMatchers } from "./file-context";
-import { walkStashFlat } from "./walker";
+import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "../core/asset-spec";
+import { hasErrnoCode, isWithin } from "../core/common";
+import { NotFoundError, UsageError } from "../core/errors";
+import { runMatchers } from "../indexer/file-context";
+import { walkStashFlat } from "../indexer/walker";
 /**
  * Resolve an asset path from a stash directory, type, and name.
  */
@@ -30,27 +30,28 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
     const resolvedRoot = resolveAndValidateTypeRoot(root, type, name);
     const resolvedTarget = path.resolve(target);
     if (!isWithin(resolvedTarget, resolvedRoot)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!fs.existsSync(resolvedTarget) || !fs.statSync(resolvedTarget).isFile()) {
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`);
+        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
     }
     const realTarget = fs.realpathSync(resolvedTarget);
     if (!isWithin(realTarget, resolvedRoot)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!isRelevantAssetFile(type, path.basename(resolvedTarget))) {
         if (type === "script") {
             throw new NotFoundError("Script ref must resolve to a file with a supported script extension. Refer to the akm documentation for the complete list of supported script extensions.");
         }
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`);
+        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
     }
     return realTarget;
 }
 function resolveAndValidateTypeRoot(root, type, name) {
     const rootStat = readTypeRootStat(root, type, name);
     if (!rootStat.isDirectory()) {
-        throw new NotFoundError(`Stash type root is not a directory for ref: ${type}:${name}`);
+        throw new NotFoundError(`Asset directory for ${type} assets is not accessible — got a file where a directory was expected for ref: ${type}:${name}. ` +
+            "Run `akm index` to rebuild the index, or check your source configuration.", "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources and verify the source path exists.");
     }
     return fs.realpathSync(root);
 }
@@ -60,7 +61,7 @@ function readTypeRootStat(root, type, name) {
     }
     catch (error) {
         if (hasErrnoCode(error, "ENOENT")) {
-            throw new NotFoundError(`Stash type root not found for ref: ${type}:${name}`);
+            throw new NotFoundError(`Asset not found for ref: ${type}:${name}. No ${type} assets are present in the configured source.`, "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources, or `akm index` to rebuild the search index.");
         }
         throw error;
     }
@@ -77,7 +78,7 @@ async function resolveByCanonicalName(stashDir, type, name) {
         const realTarget = fs.realpathSync(ctx.absPath);
         const resolvedRoot = fs.realpathSync(stashDir);
         if (!isWithin(realTarget, resolvedRoot)) {
-            throw new UsageError("Ref resolves outside the stash root.");
+            throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
         }
         return realTarget;
     }

package/dist/{wiki.js → wiki/wiki.js}

@@ -15,13 +15,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
-import { isWithin } from "./common";
-import { loadUserConfig, saveConfig } from "./config";
-import { NotFoundError, UsageError } from "./errors";
-import { parseFrontmatter, parseFrontmatterBlock } from "./frontmatter";
-import { resolveStashSources } from "./search-source";
-import { akmSearch } from "./stash-search";
-import { buildIndexMd, buildLogMd, buildSchemaMd } from "./templates/wiki-templates";
+import { akmSearch } from "../commands/search";
+import { isWithin } from "../core/common";
+import { loadUserConfig, saveConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { buildIndexMd, buildLogMd, buildSchemaMd } from "../templates/wiki-templates";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const WIKIS_SUBDIR = "wikis";
 export const SCHEMA_MD = "schema.md";
@@ -64,7 +64,7 @@ function wikiNotFoundMessage(name) {
     return `Wiki not found: ${name}. Run \`akm wiki create ${name}\` to create it or \`akm wiki register ${name} <path-or-repo>\` to register an external wiki.`;
 }
 function registeredWikiSources(stashDir) {
-    return resolveStashSources(stashDir)
+    return resolveSourceEntries(stashDir)
         .filter((source) => typeof source.wikiName === "string")
         .map((source) => ({
         name: source.wikiName,
@@ -82,17 +82,17 @@ export function resolveWikiSource(stashDir, name) {
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (external)
         return external;
-    throw new NotFoundError(wikiNotFoundMessage(name));
+    throw new NotFoundError(wikiNotFoundMessage(name), "STASH_NOT_FOUND");
 }
 export function ensureWikiNameAvailable(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
     if (fs.existsSync(wikiDir)) {
-        throw new UsageError(`Wiki already exists: ${name}.`);
+        throw new UsageError(`Wiki already exists: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (external) {
-        throw new UsageError(`Wiki already registered: ${name}.`);
+        throw new UsageError(`Wiki already registered: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
 }
 /**
@@ -305,7 +305,7 @@ export function showWiki(stashDir, name) {
 export function createWiki(stashDir, name) {
     const existing = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (existing) {
-        throw new UsageError(`Wiki already registered: ${name}.`);
+        throw new UsageError(`Wiki already registered: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const wikiDir = resolveWikiDir(stashDir, name);
     fs.mkdirSync(wikiDir, { recursive: true });
@@ -357,11 +357,12 @@ export function removeWiki(stashDir, name, options = {}) {
     const wikiDir = resolved.path;
     if (resolved.mode === "external") {
         const config = loadUserConfig();
-        const stashes = (config.stashes ?? []).filter((entry) => entry.wikiName !== name);
+        const filteredSources = (config.sources ?? config.stashes ?? []).filter((entry) => entry.wikiName !== name);
         const installed = (config.installed ?? []).filter((entry) => entry.wikiName !== name);
         saveConfig({
             ...config,
-            stashes: stashes.length > 0 ? stashes : undefined,
+            sources: filteredSources.length > 0 ? filteredSources : undefined,
+            stashes: undefined,
             installed: installed.length > 0 ? installed : undefined,
         });
         return {
@@ -373,11 +374,11 @@ export function removeWiki(stashDir, name, options = {}) {
         };
     }
     if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`);
+        throw new NotFoundError(`Wiki not found: ${name}.`, "STASH_NOT_FOUND");
     }
     const wikisRoot = resolveWikisRoot(stashDir);
     if (!isWithin(wikiDir, wikisRoot)) {
-        throw new UsageError(`Refusing to remove a path outside the wikis root: ${wikiDir}`);
+        throw new UsageError(`Refusing to remove a path outside the wikis root: ${wikiDir}`, "PATH_ESCAPE_VIOLATION");
     }
     const removed = [];
     const rawDir = path.join(wikiDir, RAW_SUBDIR);
@@ -527,7 +528,7 @@ export async function searchInWiki(input) {
     const rawDir = path.join(wikiDir, RAW_SUBDIR);
     const filtered = [];
     for (const hit of response.hits) {
-        // hits can be StashSearchHit or RegistrySearchResultHit (union); filter
+        // hits can be SourceSearchHit or RegistrySearchResultHit (union); filter
         // by path inclusion. Registry hits have no path and are dropped.
         if (hit.type === "registry")
             continue;

package/dist/{workflow-authoring.js → workflows/authoring.js}

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveAssetPathFromName } from "./asset-spec";
-import { isWithin, resolveStashDir } from "./common";
-import { UsageError } from "./errors";
-import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
+import { resolveAssetPathFromName } from "../core/asset-spec";
+import { isWithin, resolveStashDir } from "../core/common";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+import { parseWorkflow } from "./parser";
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
     title: "Example Workflow",
     firstStepTitle: "First Step",
@@ -22,7 +23,10 @@ export function buildWorkflowTemplate(name) {
         firstStepTitle: `${title} Setup`,
         firstStepId: `${stepId}-setup`,
     });
-    parseWorkflowMarkdown(customized);
+    const result = parseWorkflow(customized, { path: `<template:${name}>` });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, result.errors));
+    }
     return customized;
 }
 export function createWorkflowAsset(input) {
@@ -32,22 +36,18 @@ export function createWorkflowAsset(input) {
     const normalizedName = normalizeWorkflowName(input.name);
     const assetPath = resolveAssetPathFromName("workflow", typeRoot, normalizedName);
     if (!isWithin(assetPath, typeRoot)) {
-        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`);
+        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
     }
     if (fs.existsSync(assetPath) && !input.force) {
-        throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`);
+        throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const content = input.from
-        ? readWorkflowSource(input.from)
+        ? readWorkflowSource(input.from, stashDir)
         : (input.content ?? buildWorkflowTemplate(normalizedName));
-    try {
-        parseWorkflowMarkdown(content);
-    }
-    catch (error) {
-        if (error instanceof WorkflowValidationError) {
-            throw new UsageError(error.message);
-        }
-        throw error;
+    const sourcePath = input.from ?? `workflows/${normalizedName}.md`;
+    const result = parseWorkflow(content, { path: sourcePath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
     }
     fs.mkdirSync(path.dirname(assetPath), { recursive: true });
     fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
@@ -57,7 +57,7 @@ export function createWorkflowAsset(input) {
         stashDir,
     };
 }
-function readWorkflowSource(source) {
+function readWorkflowSource(source, stashDir) {
     const resolved = path.resolve(source);
     let stat;
     try {
@@ -69,6 +69,13 @@ function readWorkflowSource(source) {
     if (!stat.isFile()) {
         throw new UsageError(`Workflow source must be a file: "${source}".`);
     }
+    // The user is allowed to import any readable file as a workflow body, but
+    // an import from outside the stash is unusual enough to warn about. Anyone
+    // running `akm workflow create --from /etc/passwd` deserves a heads-up.
+    if (!isWithin(resolved, stashDir)) {
+        warn(`Importing workflow content from outside the stash: ${resolved}\n  ` +
+            `If this was unintentional, abort and re-run with a --from path inside ${stashDir}.`);
+    }
     return fs.readFileSync(resolved, "utf8");
 }
 function normalizeWorkflowName(name) {
@@ -102,6 +109,30 @@ function slugifyWorkflowStepId(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "") || "workflow");
 }
+export function formatWorkflowErrors(path, errors) {
+    const lines = errors.map((e) => `  ${path}:${e.line} — ${e.message}`);
+    const heading = errors.length === 1 ? "Workflow has 1 error:" : `Workflow has ${errors.length} errors:`;
+    return [heading, ...lines].join("\n");
+}
+/**
+ * Validate a workflow by ref (`workflow:<name>`) or filesystem path.
+ *
+ * Returns the parse result plus the source-relative path used. Throws
+ * `UsageError` only when the target cannot be located on disk; parse
+ * failures are returned as `{ ok: false, errors }` so callers can
+ * format them however they like.
+ */
+export function validateWorkflowSource(target) {
+    if (target.startsWith("workflow:")) {
+        throw new UsageError(`validateWorkflowSource expects a filesystem path; resolve refs to paths in the caller before invoking.`);
+    }
+    const resolved = path.resolve(target);
+    if (!fs.existsSync(resolved)) {
+        throw new UsageError(`Workflow file not found: "${target}".`);
+    }
+    const content = fs.readFileSync(resolved, "utf8");
+    return { path: target, parse: parseWorkflow(content, { path: target }) };
+}
 function renderWorkflowTemplate(input) {
     return `---
 description: Describe what this workflow accomplishes

package/dist/{workflow-cli.js → workflows/cli.js}

@@ -1,4 +1,4 @@
-import { UsageError } from "./errors";
+import { UsageError } from "../core/errors";
 export const WORKFLOW_STEP_STATES = [
     "completed",
     "blocked",
@@ -14,6 +14,7 @@ export const WORKFLOW_SUBCOMMANDS = new Set([
     "create",
     "template",
     "resume",
+    "validate",
 ]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)

package/dist/{workflow-db.js → workflows/db.js}

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
-import { getWorkflowDbPath } from "./paths";
+import { getWorkflowDbPath } from "../core/paths";
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const dir = path.dirname(dbPath);
     if (!fs.existsSync(dir)) {

package/dist/workflows/document-cache.js

@@ -0,0 +1,20 @@
+/**
+ * Side-channel cache that lets the workflow renderer hand a validated
+ * `WorkflowDocument` to the indexer without persisting it through the
+ * `entry_json` column or widening `StashEntry` with a workflow-shaped field.
+ *
+ * The renderer is called during metadata generation; the indexer writes the
+ * document to `workflow_documents` after `upsertEntry` returns the row id.
+ * A WeakMap keyed by the entry object preserves the parse work between the
+ * two phases without leaking memory if the entry is dropped.
+ */
+const cache = new WeakMap();
+export function cacheWorkflowDocument(entry, doc) {
+    cache.set(entry, doc);
+}
+export function takeWorkflowDocument(entry) {
+    const doc = cache.get(entry);
+    if (doc !== undefined)
+        cache.delete(entry);
+    return doc;
+}