akm-cli 0.6.0-rc1 → 0.6.0-rc2

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

@@ -1,15 +1,16 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import { loadConfig } from "./config";
-import { closeDatabase, openDatabase } from "./db";
-import { NotFoundError, UsageError } from "./errors";
-import { resolveSourcesForOrigin } from "./origin-resolve";
-import { getDbPath } from "./paths";
-import { resolveStashSources } from "./search-source";
-import { parseAssetRef } from "./stash-ref";
-import { resolveAssetPath } from "./stash-resolve";
-import { closeWorkflowDatabase, openWorkflowDatabase } from "./workflow-db";
-import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
+import { parseAssetRef } from "../core/asset-ref";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { getDbPath } from "../core/paths";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+import { resolveAssetPath } from "../sources/resolve";
+import { formatWorkflowErrors } from "./authoring";
+import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
+import { parseWorkflow } from "./parser";
 export async function startWorkflowRun(ref, params = {}) {
     const asset = await loadWorkflowAsset(ref);
     const workflowDb = openWorkflowDatabase();
@@ -209,7 +210,7 @@ async function loadWorkflowAsset(ref) {
         throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
     }
     const config = loadConfig();
-    const allSources = resolveStashSources(undefined, config);
+    const allSources = resolveSourceEntries(undefined, config);
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
     let assetPath;
     let sourcePath;
@@ -226,15 +227,69 @@ async function loadWorkflowAsset(ref) {
     if (!assetPath) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
+    const resolvedSourcePath = sourcePath ?? loadConfig().stashDir ?? assetPath;
+    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
+    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
+    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
+}
+function loadWorkflowDocumentFromDisk(assetPath) {
     const content = fs.readFileSync(assetPath, "utf8");
-    const workflow = parseWorkflowDocument(content);
+    const result = parseWorkflow(content, { path: assetPath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
+    }
+    return result.document;
+}
+function readWorkflowDocumentFromIndex(sourcePath, ref) {
+    const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath))
+        return null;
+    const db = openDatabase(dbPath);
+    try {
+        const parsed = parseAssetRef(ref);
+        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+        const row = db
+            .prepare(`SELECT wd.document_json AS document_json
+           FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
+          LIMIT 1`)
+            .get(entryKey);
+        if (!row)
+            return null;
+        try {
+            return JSON.parse(row.document_json);
+        }
+        catch {
+            return null;
+        }
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function projectAsset(doc, ref, assetPath, sourcePath) {
     return {
-        ref: `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`,
+        ref,
         path: assetPath,
-        sourcePath: sourcePath ?? loadConfig().stashDir ?? assetPath,
-        title: workflow.title,
-        ...(workflow.parameters ? { parameters: workflow.parameters } : {}),
-        steps: workflow.steps,
+        sourcePath,
+        title: doc.title,
+        ...(doc.parameters
+            ? {
+                parameters: doc.parameters.map((p) => ({
+                    name: p.name,
+                    ...(p.description ? { description: p.description } : {}),
+                })),
+            }
+            : {}),
+        steps: doc.steps.map((s) => ({
+            id: s.id,
+            title: s.title,
+            instructions: s.instructions.text,
+            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
+            sequenceIndex: s.sequenceIndex,
+        })),
     };
 }
 function resolveWorkflowEntryId(sourcePath, ref) {
@@ -361,14 +416,3 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-function parseWorkflowDocument(content) {
-    try {
-        return parseWorkflowMarkdown(content);
-    }
-    catch (error) {
-        if (error instanceof WorkflowValidationError) {
-            throw new UsageError(error.message);
-        }
-        throw error;
-    }
-}

package/dist/workflows/schema.js

@@ -0,0 +1,11 @@
+/**
+ * Validated JSON shape for a workflow asset.
+ *
+ * `parseWorkflow` (parser.ts) converts a workflow markdown file into a
+ * `WorkflowDocument` plus a list of `WorkflowError`s. The document is the
+ * single source of truth consumed by the renderer, the indexer (cached
+ * into `workflow_documents` in `index.db`), and the run engine. Source
+ * markdown is referenced by `SourceRef` line spans so editors and agents
+ * can rewrite content in place without a full re-parse.
+ */
+export const WORKFLOW_SCHEMA_VERSION = 1;

package/dist/workflows/validator.js

@@ -0,0 +1,48 @@
+/**
+ * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
+ *
+ * The parser handles per-line shape checks; this module runs rules that need
+ * the whole document or the raw frontmatter at once: duplicate step IDs,
+ * step-id format, and the frontmatter key whitelist.
+ */
+const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
+    checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
+    checkStepIdFormat(draft, errors);
+    checkDuplicateStepIds(draft, errors);
+}
+function checkFrontmatterKeys(data, fmEndLine, errors) {
+    for (const key of Object.keys(data)) {
+        if (ALLOWED_FRONTMATTER_KEYS.has(key))
+            continue;
+        errors.push({
+            line: fmEndLine,
+            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params.`,
+        });
+    }
+}
+function checkStepIdFormat(draft, errors) {
+    for (const step of draft.steps) {
+        if (STEP_ID_REGEX.test(step.id))
+            continue;
+        errors.push({
+            line: step.source.start,
+            message: `Step ID "${step.id}" is invalid. Use letters, numbers, ".", "_" or "-" (e.g. "deploy-job").`,
+        });
+    }
+}
+function checkDuplicateStepIds(draft, errors) {
+    const firstSeenLine = new Map();
+    for (const step of draft.steps) {
+        const previous = firstSeenLine.get(step.id);
+        if (previous !== undefined) {
+            errors.push({
+                line: step.source.start,
+                message: `Step ID "${step.id}" is already used on line ${previous}. Step IDs must be unique within a workflow.`,
+            });
+            continue;
+        }
+        firstSeenLine.set(step.id, step.source.start);
+    }
+}

package/docs/migration/release-notes/0.6.0.md

@@ -1,29 +1,75 @@
 Migration notes for akm v0.6.0
 
-This release is a clean break: the runtime "kit" / "source" concept is renamed to **stash**, the registry wire format moves from `kits[]` to `stashes[]` (schema v3), and the discovery keyword/topic is renamed from `akm-kit` to `akm-stash`.
+This release ships the v1 architecture refactor on top of the earlier 0.6
+terminology cut (`kit` → `stash` in the registry wire format). The CLI
+command surface is unchanged. Most users have nothing to do.
+
+Locked v1 decisions:
+- `writable` defaults to `true` on `filesystem`, `false` on `git` /
+  `website` / `npm`.
+- Registry results are off by default in `akm search`; pass
+  `--include-registry` (or `--source registry|both`) to include them.
+- Write target resolves as: `--target` flag → `defaultWriteTarget` config
+  key → `stashDir` (working stash) → `ConfigError`.
+- `writable: true` on `website` / `npm` is rejected at config load.
+
+Manual actions required:
+- If your config contains an `openviking` source, remove it. akm exits at
+  load with `ConfigError` and points to `akm config sources remove <name>`.
+  API-backed sources will return as a separate `QuerySource` tier post-v1.
+- If your config sets `writable: true` on a `website` or `npm` source,
+  drop the flag or re-add the path as a `filesystem` source.
+- If you previously ran `akm enable context-hub` / `akm disable
+  context-hub`, those toggles are gone. Add Context Hub as a regular git
+  source with `akm add github:andrewyng/context-hub`, or list it as a kit
+  entry in your registry.
 
 Automatic (no action required):
+- Config key `stashes[]` is loaded as `sources[]` with one deprecation
+  warning. The new key is persisted on the next `akm config` write.
 - `stash.lock` is renamed to `akm.lock` on startup.
-- `config.installed[]` entries are mapped to `config.stashes[]` + `akm.lock` records.
-- `stashDir` is loaded as an implicit `primary: true` filesystem stash entry.
-- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"` in memory.
+- `config.installed[]` entries are mapped to `config.sources[]` plus
+  `akm.lock` records.
+- `stashDir` is loaded as an implicit `primary: true` filesystem source.
+- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"`.
 
-Manual actions required:
-- Replace `akm enable context-hub` / `akm disable context-hub` with
-  `akm add github:andrewyng/context-hub --name context-hub`.
-- Switch error-handling scripts from string-matching the `error` message
-  to comparing the new machine-readable `code` field.
-- Replace `--for-agent` with `--detail=agent` (old flag is retained as a
-  deprecated alias for one release cycle).
-- Replace `disableGlobalStashes: true` with `stashInheritance: "replace"`.
-
-Publishers:
-- The discovery keyword/topic was renamed from `akm-kit` to `akm-stash`.
-  Update your npm `keywords` and GitHub topics. Legacy keywords are no
-  longer honored — clean break, no transition window.
-
-Self-hosted registries:
-- The wire format `kits[]` is renamed to `stashes[]`. Schema is bumped
-  to v3 and `akm-cli >= 0.6.0` only parses v3.
-
-Full migration guide: https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md
+What changed under the hood (no user impact):
+- `SourceProvider` interface simplified to `{ name, kind, init, path,
+  sync? }`. Plugin authors should re-read the v1 spec.
+- Search and show consult the unified FTS5 index and read files from
+  disk; the per-provider fan-out is gone.
+- Single write helper (`writeAssetToSource`) handles filesystem and git
+  destinations.
+- Error classes own their `hint()` text. Hints now print to stderr inline
+  without `--verbose`.
+- Registry providers (`static-index`, `skills-sh`) loop through a uniform
+  interface; the Context Hub special case was deleted.
+- `src/` reorganized into purpose-named subdirectories (`commands/`,
+  `core/`, `indexer/`, `output/`, `registry/`, `setup/`, `sources/`,
+  `wiki/`, `workflows/`). akm has no public API, so external consumers
+  are unaffected.
+- Removed legacy re-export shims: `src/llm.ts`, `src/registry-provider.ts`,
+  `src/ripgrep.ts`.
+
+Earlier-in-cycle terminology cut (still applies):
+- The registry wire format `kits[]` is renamed to `stashes[]` with schema
+  bumped to v3. `akm-cli >= 0.6.0` only parses v3 indexes.
+- npm packages and GitHub repos are discovered via the `akm-stash`
+  keyword/topic only. `akm-kit` and `agentikit` are no longer honored.
+- Internal types: `RegistryKitEntry` → `RegistryStashEntry`,
+  `InstalledKitEntry` → `InstalledStashEntry`,
+  `KitInstallStatus` → `StashInstallStatus`, `KitSource` → `StashSource`.
+- Documentation: `docs/kit-makers.md` → `docs/stash-makers.md`.
+
+CLI command surface (unchanged in 0.6.0):
+add | remove | list | update | search | show | clone | index | setup |
+remember | import | feedback | registry * | info | curate | workflow |
+vault | wiki | enable | disable | completions | upgrade | save | help |
+hints
+
+Full migration guides:
+- https://github.com/itlackey/akm/blob/main/docs/migration/v1.md (v1
+  architecture refactor — read this first if you are coming from 0.5.x or
+  an earlier 0.6 pre-release)
+- https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md
+  (terminology cut, registry schema v3, publisher changes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.6.0-rc1",
+  "version": "0.6.0-rc2",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [

package/dist/errors.js

@@ -1,45 +0,0 @@
-/**
- * Typed error classes for structured exit code classification.
- *
- * - ConfigError  -> exit 78  (configuration / environment problems)
- * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
- * - NotFoundError -> exit 1  (requested resource missing)
- *
- * Each error carries a machine-readable `code` field. Codes are stable
- * identifiers safe to consume from scripts and JSON output. Existing throw
- * sites without an explicit code receive a default code per error class so
- * older call sites continue to compile and behave unchanged.
- */
-/** Raised when configuration or environment is invalid or missing. */
-export class ConfigError extends Error {
-    code;
-    constructor(msg, code = "INVALID_CONFIG_FILE") {
-        super(msg);
-        this.name = "ConfigError";
-        this.code = code;
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-/** Raised when the user supplies invalid arguments or input. */
-export class UsageError extends Error {
-    code;
-    constructor(msg, code = "INVALID_FLAG_VALUE") {
-        super(msg);
-        this.name = "UsageError";
-        this.code = code;
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-/** Raised when a requested resource (asset, entry, file) is not found. */
-export class NotFoundError extends Error {
-    code;
-    constructor(msg, code = "ASSET_NOT_FOUND") {
-        super(msg);
-        this.name = "NotFoundError";
-        this.code = code;
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}

package/dist/llm.js

@@ -1,16 +0,0 @@
-/**
- * Backward-compatible facade for the LLM module.
- *
- * The implementation has been split into:
- * - `./llm-client`     — transport (chatCompletion, parseJsonResponse,
- *                       isLlmAvailable, probeLlmCapabilities, ChatMessage,
- *                       ChatCompletionOptions, stripJsonFences)
- * - `./metadata-enhance` — higher-level metadata enhancement workflow
- *                          (enhanceMetadata)
- *
- * New code should import from those modules directly. This re-export barrel
- * exists so existing call sites and tests that import from `./llm` keep
- * working without modification.
- */
-export * from "./llm-client";
-export { enhanceMetadata } from "./metadata-enhance";

package/dist/registry-factory.js

@@ -1,19 +0,0 @@
-/**
- * Registry provider factory map.
- *
- * Maps registry provider type identifiers (e.g. "static-index", "skills-sh")
- * to factory functions that create RegistryProvider instances.
- *
- * "Registry" here refers to the stash discovery registries (npm, GitHub, static
- * index files) — not to be confused with the stash provider factory map in
- * stash-provider-factory.ts or the installed-stash operations in installed-stashes.ts.
- */
-import { createProviderRegistry } from "./create-provider-registry";
-// ── Factory map ─────────────────────────────────────────────────────────────
-const registry = createProviderRegistry();
-export function registerProvider(type, factory) {
-    registry.register(type, factory);
-}
-export function resolveProviderFactory(type) {
-    return registry.resolve(type);
-}

package/dist/ripgrep.js

@@ -1,2 +0,0 @@
-export { ensureRg } from "./ripgrep-install";
-export { isRgAvailable, resolveRg } from "./ripgrep-resolve";

package/dist/stash-provider-factory.js

@@ -1,35 +0,0 @@
-/**
- * Stash provider factory map.
- *
- * Maps stash source type identifiers (e.g. "filesystem", "openviking") to
- * factory functions that create StashProvider instances from a StashConfigEntry.
- *
- * "Stash providers" are runtime data sources for the search and show commands —
- * distinct from the stash-discovery registries (registry-factory.ts) and the
- * installed-stash operations (installed-stashes.ts).
- */
-import { createProviderRegistry } from "./create-provider-registry";
-// ── Factory map ─────────────────────────────────────────────────────────────
-const registry = createProviderRegistry();
-export function registerStashProvider(type, factory) {
-    registry.register(type, factory);
-}
-export function resolveStashProviderFactory(type) {
-    return registry.resolve(type);
-}
-/**
- * Resolve all non-filesystem stash providers from config.
- * Filesystem entries are excluded — they are handled by resolveStashSources().
- */
-export function resolveStashProviders(config) {
-    const providers = [];
-    for (const entry of config.stashes ?? []) {
-        if (entry.enabled === false)
-            continue;
-        const factory = registry.resolve(entry.type);
-        if (factory) {
-            providers.push(factory(entry));
-        }
-    }
-    return providers;
-}

package/dist/stash-provider.js

@@ -1,3 +0,0 @@
-export function isSyncable(p) {
-    return p.kind === "syncable";
-}

package/dist/stash-providers/filesystem.js

@@ -1,71 +0,0 @@
-import { resolveStashDir } from "../common";
-import { loadConfig } from "../config";
-import { searchLocal } from "../db-search";
-import { ConfigError } from "../errors";
-import { resolveStashSources } from "../search-source";
-import { registerStashProvider } from "../stash-provider-factory";
-import { showLocal } from "../stash-show";
-import { detectStashRoot } from "./provider-utils";
-class FilesystemStashProvider {
-    type = "filesystem";
-    kind = "syncable";
-    name;
-    stashDir;
-    constructor(entry) {
-        this.stashDir = entry.path ?? resolveStashDir();
-        this.name = entry.name ?? this.stashDir;
-    }
-    async search(options) {
-        const config = loadConfig();
-        const sources = resolveStashSources(this.stashDir, config);
-        const result = await searchLocal({
-            query: options.query.toLowerCase(),
-            searchType: options.type ?? "any",
-            limit: options.limit,
-            stashDir: this.stashDir,
-            sources,
-            config,
-        });
-        return {
-            hits: result.hits,
-            warnings: result.warnings,
-            embedMs: result.embedMs,
-            rankMs: result.rankMs,
-        };
-    }
-    async show(ref, view) {
-        return showLocal({ ref, view });
-    }
-    canShow(ref) {
-        return !ref.includes("://");
-    }
-    /** No-op: a filesystem stash already lives on disk. */
-    async sync(config, options) {
-        if (!config.path) {
-            throw new ConfigError("filesystem stash entry must include a `path`");
-        }
-        const stashRoot = detectStashRoot(config.path);
-        const syncedAt = (options?.now ?? new Date()).toISOString();
-        return {
-            id: stashRoot,
-            source: "local",
-            ref: stashRoot,
-            artifactUrl: stashRoot,
-            contentDir: stashRoot,
-            cacheDir: stashRoot,
-            extractedDir: stashRoot,
-            syncedAt,
-        };
-    }
-    getContentDir(config) {
-        if (!config.path) {
-            throw new ConfigError("filesystem stash entry must include a `path`");
-        }
-        return config.path;
-    }
-    async remove(_config) {
-        // Filesystem stashes are user-managed; never delete the source on `akm remove`.
-    }
-}
-// ── Self-register ───────────────────────────────────────────────────────────
-registerStashProvider("filesystem", (config) => new FilesystemStashProvider(config));