akm-cli 0.6.0-rc1 → 0.6.0

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

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap } from "../common";
-import { ConfigError, UsageError } from "../errors";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerStashProvider } from "../stash-provider-factory";
-import { isDirectory, isExpired, sanitizeString } from "./provider-utils";
+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;
 /** Allow up to 7 days of stale snapshots when refresh fails so search remains available during outages. */
@@ -28,68 +29,34 @@ const WEBSITE_PAGE_BYTE_CAP = 5 * 1024 * 1024;
  */
 const WEBSITE_CRAWL_WALL_CLOCK_MS = 10 * 60 * 1000;
 /**
- * Website stash provider. Implements {@link SyncableStashProvider} (which
- * extends LiveStashProvider) — scrapes pages into a local mirror so the FTS5
- * indexer can walk them.
+ * 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 WebsiteStashProvider {
-    type = "website";
-    kind = "syncable";
+class WebsiteSourceProvider {
+    kind = "website";
     name;
-    config;
+    #config;
+    #url;
     constructor(config) {
-        this.config = 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(config, options) {
-        const cachePaths = await ensureWebsiteMirror(config, { requireStashDir: true, force: options?.force });
-        const syncedAt = (options?.now ?? new Date()).toISOString();
-        const url = config.url ?? "";
-        // #123 added "website" to the StashSource union, so we can use it directly.
-        return {
-            id: url,
-            source: "website",
-            ref: url,
-            artifactUrl: url,
-            contentDir: cachePaths.stashDir,
-            cacheDir: cachePaths.rootDir,
-            extractedDir: cachePaths.stashDir,
-            syncedAt,
-        };
-    }
-    getContentDir(config) {
-        const url = config.url ?? "";
-        return getCachePaths(url).stashDir;
-    }
-    async remove(config) {
-        const url = config.url;
-        if (!url)
-            return;
-        const paths = getCachePaths(url);
-        if (isDirectory(paths.rootDir)) {
-            try {
-                fs.rmSync(paths.rootDir, { recursive: true, force: true });
-            }
-            catch {
-                /* best-effort */
-            }
-        }
+    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}`);
@@ -182,12 +149,9 @@ async function crawlWebsite(startUrl, options) {
     const visited = new Set();
     const pages = [];
     const deadline = Date.now() + WEBSITE_CRAWL_WALL_CLOCK_MS;
-    let stoppedAtDeadline = false;
     while (queue.length > 0 && pages.length < options.maxPages) {
-        if (Date.now() > deadline) {
-            stoppedAtDeadline = true;
+        if (Date.now() > deadline)
             break;
-        }
         const next = queue.shift();
         if (!next)
             break;
@@ -212,8 +176,8 @@ async function crawlWebsite(startUrl, options) {
             queue.push({ url: candidate, depth: next.depth + 1 });
         }
     }
-    if (stoppedAtDeadline) {
-        console.warn(`[akm] website crawl stopped at the ${WEBSITE_CRAWL_WALL_CLOCK_MS / 1000}s wall-clock cap with ${pages.length}/${options.maxPages} pages collected from ${startUrl}.`);
+    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;
 }
@@ -516,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.
  */
@@ -50,7 +50,8 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
 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;
     }

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,
@@ -76,7 +76,7 @@ function registeredWikiSources(stashDir) {
 export function resolveWikiSource(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
-    if (fs.existsSync(wikiDir)) {
+    if (fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir)) {
         return { name, path: wikiDir, mode: "stash" };
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
@@ -87,7 +87,7 @@ export function resolveWikiSource(stashDir, name) {
 export function ensureWikiNameAvailable(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
-    if (fs.existsSync(wikiDir)) {
+    if (fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir)) {
         throw new UsageError(`Wiki already exists: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
@@ -164,6 +164,17 @@ function scanWikiFiles(wikiDir) {
     }
     return { pages, raws, lastModifiedMs, pagesLastModifiedMs };
 }
+function hasWikiInfrastructure(wikiDir) {
+    for (const file of WIKI_SPECIAL_FILES) {
+        if (fs.existsSync(path.join(wikiDir, file)))
+            return true;
+    }
+    return false;
+}
+function isRecognizedStashWiki(wikiDir, buckets) {
+    const scanned = buckets ?? scanWikiFiles(wikiDir);
+    return scanned.pages.length > 0 || hasWikiInfrastructure(wikiDir);
+}
 function readSchemaDescription(wikiDir) {
     const schemaPath = path.join(wikiDir, SCHEMA_MD);
     let raw;
@@ -207,6 +218,8 @@ export function listWikis(stashDir) {
     }
     const summarize = (name, dir) => {
         const buckets = scanWikiFiles(dir);
+        if (!isRecognizedStashWiki(dir, buckets))
+            return;
         const summary = {
             name,
             path: dir,
@@ -353,15 +366,18 @@ export function createWiki(stashDir, name) {
  * ignore that (e.g. idempotent cleanup) by catching.
  */
 export function removeWiki(stashDir, name, options = {}) {
-    const resolved = resolveWikiSource(stashDir, name);
-    const wikiDir = resolved.path;
-    if (resolved.mode === "external") {
+    validateWikiName(name);
+    const wikiDir = resolveWikiDir(stashDir, name);
+    const external = registeredWikiSources(stashDir).find((source) => source.name === name);
+    const isStashWiki = fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir);
+    if (!isStashWiki && 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 {
@@ -372,8 +388,8 @@ export function removeWiki(stashDir, name, options = {}) {
             unregistered: true,
         };
     }
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`, "STASH_NOT_FOUND");
+    if (!fs.existsSync(wikiDir) || (!isStashWiki && !options.withSources)) {
+        throw new NotFoundError(wikiNotFoundMessage(name), "STASH_NOT_FOUND");
     }
     const wikisRoot = resolveWikisRoot(stashDir);
     if (!isWithin(wikiDir, wikisRoot)) {
@@ -527,7 +543,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,10 +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 { warn } from "./warn";
-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",
@@ -23,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) {
@@ -41,14 +44,10 @@ export function createWorkflowAsset(input) {
     const content = 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");
@@ -110,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;
+}