akm-cli 0.8.6 → 0.8.14

package/dist/commands/{agent-dispatch.js → agent/agent-dispatch.js}

@@ -14,11 +14,11 @@
  * filled from the extra positional args in order.
  */
 import fs from "node:fs";
-import { parseAssetRef } from "../core/asset-ref";
-import { NotFoundError, UsageError } from "../core/errors";
-import { requireAgentProfile } from "../integrations/agent/config";
-import { runAgentSdk } from "../integrations/agent/sdk-runner";
-import { runAgent } from "../integrations/agent/spawn";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { requireAgentProfile } from "../../integrations/agent/config.js";
+import { runAgent } from "../../integrations/agent/spawn.js";
+import { runAgentSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 /**
  * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
  * corresponding entries in `args`. Any placeholder index that exceeds the
@@ -46,7 +46,7 @@ async function resolveAssetBody(ref) {
         throw new UsageError(`Invalid asset ref "${ref}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");
     }
     // Lazy import to avoid pulling the full indexer at startup.
-    const { lookup } = await import("../indexer/indexer.js");
+    const { lookup } = await import("../../indexer/indexer.js");
     const entry = await lookup(parsed);
     if (!entry) {
         throw new NotFoundError(`Asset "${ref}" not found in the index. Run \`akm index\` to rebuild the index.`);

package/dist/commands/{agent-support.js → agent/agent-support.js}

@@ -8,8 +8,8 @@
  * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
  * profile can import from here rather than copy-pasting.
  */
-import { loadConfig } from "../core/config";
-import { requireAgentProfile, } from "../integrations/agent";
+import { loadConfig } from "../../core/config/config.js";
+import { requireAgentProfile, } from "../../integrations/agent/index.js";
 // ── Config helpers ───────────────────────────────────────────────────────────
 /**
  * Load the loaded AkmConfig from disk.

package/dist/commands/agent/contribute-cli.js

@@ -0,0 +1,200 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Contribution command cluster (`akm agent`, `akm lint`, `akm propose`) —
+ * the asset authoring / validation / proposal-creation verbs. Extracted
+ * verbatim from src/cli.ts (WS6) so the God Module shrinks; the
+ * `main.subCommands.{agent,lint,propose}` keys and every command's args /
+ * output shape stay byte-identical.
+ *
+ * These three handlers each branch on the result and call `process.exit`
+ * conditionally (exit 1 on a failed dispatch / proposal, or on
+ * `--fail-on-flagged` lint findings), so they keep the inline
+ * `runWithJsonErrors` form rather than migrating to `defineJsonCommand`
+ * (which is reserved for plain runWithJsonErrors+output handlers).
+ *
+ * NOTE on `propose` vs `proposal`: the proposal MANAGEMENT family
+ * (list/show/accept/reject/…) lives in src/commands/proposal-cli.ts. The
+ * `propose` (create) verb here is the asset-authoring entry point and shares
+ * no private helper with that module — its path/name helpers come from the
+ * shared src/core/asset-create.ts module, imported below.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { EXIT_CODES, output, runWithJsonErrors } from "../../cli/shared.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { getHyphenatedArg } from "../../output/context.js";
+import { akmLint } from "../lint.js";
+import { akmPropose } from "../proposal/propose.js";
+import { akmAgentDispatch } from "./agent-dispatch.js";
+const EXIT_GENERAL = EXIT_CODES.GENERAL;
+export const agentCommand = defineCommand({
+    meta: {
+        name: "agent",
+        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a stash agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
+    },
+    args: {
+        profile: {
+            type: "positional",
+            description: "Agent profile / platform to use (opencode, claude, …)",
+            required: false,
+        },
+        "agent-ref": {
+            type: "positional",
+            description: "Optional agent asset ref (e.g. agent:code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
+            required: false,
+        },
+        prompt: { type: "string", description: "Task prompt to pass to the agent" },
+        command: { type: "string", description: "Load prompt from a command: asset" },
+        workflow: { type: "string", description: "Load prompt from a workflow: asset" },
+        model: {
+            type: "string",
+            description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
+        },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            if (!args.profile) {
+                throw new UsageError("Usage: akm agent <profile> [<agent-ref>] [--prompt <text>] [--model <model>]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in profiles.agent.");
+            }
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const config = loadConfig();
+            const { getDefaultLlmConfig } = await import("../../core/config/config.js");
+            // After 0.8.0 the agent block IS the loaded AkmConfig.
+            const agentConfig = config;
+            // Resolve agent asset ref → extract system prompt, model, and tool policy.
+            const agentRef = getStringArg(args, "agent-ref");
+            let systemPrompt;
+            let assetModel;
+            let assetTools;
+            if (agentRef) {
+                const { akmShowUnified } = await import("../read/show.js");
+                const asset = await akmShowUnified({ ref: agentRef, detail: "full" });
+                systemPrompt = typeof asset.content === "string" ? asset.content : undefined;
+                assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
+                assetTools = asset.toolPolicy;
+            }
+            // --model flag wins over the asset's modelHint.
+            const model = getStringArg(args, "model") ?? assetModel;
+            const promptText = getStringArg(args, "prompt");
+            const commandRef = getStringArg(args, "command");
+            const workflowRef = getStringArg(args, "workflow");
+            // Only build a dispatch request when there is something to dispatch — a
+            // prompt, an agent asset, or a model override. When none of these are
+            // present the agent is launched interactively (no injected prompt, no
+            // platform-specific flags beyond the profile's base args).
+            const hasDispatchContent = !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
+            const result = await akmAgentDispatch({
+                profileName: String(args.profile),
+                prompt: promptText,
+                commandRef,
+                workflowRef,
+                agentConfig,
+                llmConfig: getDefaultLlmConfig(config),
+                ...(hasDispatchContent
+                    ? {
+                        dispatch: {
+                            prompt: promptText ?? "",
+                            systemPrompt,
+                            model,
+                            tools: assetTools,
+                        },
+                    }
+                    : {}),
+                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+            });
+            output("agent-result", result);
+            if (!result.ok) {
+                process.exit(EXIT_GENERAL);
+            }
+        });
+    },
+});
+export const lintCommand = defineCommand({
+    meta: {
+        name: "lint",
+        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
+    },
+    args: {
+        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        dir: { type: "string", description: "Override stash root directory (default: from config)" },
+        "fail-on-flagged": {
+            type: "boolean",
+            description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = akmLint({
+                fix: args.fix ?? false,
+                dir: getStringArg(args, "dir"),
+            });
+            output("lint", result);
+            if (args["fail-on-flagged"] && result.summary.flagged > 0)
+                process.exit(EXIT_GENERAL);
+        });
+    },
+});
+export const proposeCommand = defineCommand({
+    meta: {
+        name: "propose",
+        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
+    },
+    args: {
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
+        name: {
+            type: "positional",
+            description: "Asset name (flat, no '/'; use --path for a subdirectory)",
+            required: false,
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under the type dir to place the proposed asset in (e.g. 'release'). The filename comes from the name.",
+        },
+        task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // citty silently shows help and exits 0 when required positionals are
+            // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
+            // structured JSON error reaches scripted callers.
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm propose <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
+            }
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
+            }
+            // `name` is flat; subdirectory placement is `--path`'s job.
+            assertFlatAssetName(String(args.name));
+            const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const result = await akmPropose({
+                type: String(args.type),
+                name: proposedName,
+                task: taskText,
+                profile: getStringArg(args, "profile"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            });
+            output("propose", result);
+            if (result.ok === false) {
+                process.exit(EXIT_GENERAL);
+            }
+        });
+    },
+});

package/dist/commands/completions.js

@@ -4,7 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { getAssetTypes } from "../core/asset-spec";
+import { getAssetTypes } from "../core/asset/asset-spec.js";
 // ── Known flag values ────────────────────────────────────────────────────────
 const FLAG_VALUES = {
     "--format": ["json", "text", "yaml", "jsonl"],

package/dist/commands/config-cli.js

@@ -16,9 +16,13 @@
  *   - `parseConfigValue` returns a Partial<AkmConfig> so it can be merged with
  *     the runtime config object via `mergeConfigValue`.
  */
-import { DEFAULT_CONFIG, getSources } from "../core/config";
-import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config-walker";
-import { UsageError } from "../core/errors";
+import { hasSubcommand } from "../cli/parse-args.js";
+import { defineJsonCommand, output } from "../cli/shared.js";
+import { resolveStashDir } from "../core/common.js";
+import { DEFAULT_CONFIG, getSources, loadConfig, loadUserConfig, saveConfig, } from "../core/config/config.js";
+import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
+import { UsageError } from "../core/errors.js";
+import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "../core/paths.js";
 // ── Legacy `llm.*` → `profiles.llm.<default>.*` aliasing ────────────────────
 /**
  * Map a legacy top-level `llm.<sub>` path onto the actual schema path. The
@@ -153,3 +157,226 @@ export function listConfig(config) {
     return result;
 }
 export { unknownKeyHint };
+// ── `akm config` command surface ────────────────────────────────────────────
+// Extracted verbatim from src/cli.ts (WS6). The `main.subCommands.config` key
+// and every config subcommand's args/output shape are byte-identical. The
+// `skills.sh` toggle helpers and the `CONFIG_SUBCOMMAND_SET` routing constant
+// are used ONLY by this command, so they move with the cluster. Leaf handlers
+// whose body is a plain `runWithJsonErrors(() => { … })` are migrated to
+// `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
+// exit-code) as the inline form.
+const SKILLS_SH_NAME = "skills.sh";
+const SKILLS_SH_URL = "https://skills.sh";
+const SKILLS_SH_PROVIDER = "skills-sh";
+function normalizeToggleTarget(target) {
+    const normalized = target.trim().toLowerCase();
+    if (normalized === "skills.sh" || normalized === "skills-sh")
+        return "skills.sh";
+    throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh`);
+}
+function toggleSkillsShRegistry(enabled) {
+    const config = loadUserConfig();
+    const registries = (config.registries ?? DEFAULT_CONFIG.registries ?? []).map((registry) => ({ ...registry }));
+    const idx = registries.findIndex((registry) => registry.provider === SKILLS_SH_PROVIDER || registry.name === SKILLS_SH_NAME || registry.url === SKILLS_SH_URL);
+    if (idx >= 0) {
+        const existing = registries[idx];
+        const wasEnabled = existing.enabled !== false;
+        existing.enabled = enabled;
+        saveConfig({ ...config, registries });
+        return { changed: wasEnabled !== enabled, component: SKILLS_SH_NAME, enabled };
+    }
+    if (!enabled) {
+        // Materialize the skills.sh registry explicitly if absent.
+        registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: false });
+        saveConfig({ ...config, registries });
+        return { changed: true, component: SKILLS_SH_NAME, enabled: false };
+    }
+    registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: true });
+    saveConfig({ ...config, registries });
+    return { changed: true, component: SKILLS_SH_NAME, enabled: true };
+}
+function toggleComponent(targetRaw, enabled) {
+    const target = normalizeToggleTarget(targetRaw);
+    if (target === "skills.sh")
+        return toggleSkillsShRegistry(enabled);
+    // normalizeToggleTarget throws for any unsupported target; this is unreachable.
+    throw new UsageError(`Unsupported target "${targetRaw}". Supported targets: skills.sh`);
+}
+export const configCommand = defineJsonCommand({
+    meta: { name: "config", description: "Show and manage configuration" },
+    args: {
+        list: { type: "boolean", description: "List current configuration", default: false },
+    },
+    subCommands: {
+        path: defineJsonCommand({
+            meta: { name: "path", description: "Show paths to config, stash, cache, and index" },
+            args: {
+                all: { type: "boolean", description: "Show all paths (config, stash, cache, index)", default: false },
+            },
+            run({ args }) {
+                const configPath = getConfigPath();
+                if (args.all) {
+                    let stashDir;
+                    try {
+                        stashDir = resolveStashDir({ readOnly: true });
+                    }
+                    catch {
+                        stashDir = `${getDefaultStashDir()} (not initialized)`;
+                    }
+                    const cacheDir = getCacheDir();
+                    const result = {
+                        config: configPath,
+                        stash: stashDir,
+                        cache: cacheDir,
+                        index: getDbPath(),
+                    };
+                    output("config", result);
+                }
+                else {
+                    console.log(configPath);
+                }
+            },
+        }),
+        list: defineJsonCommand({
+            meta: { name: "list", description: "List current configuration" },
+            run() {
+                output("config", listConfig(loadConfig()));
+            },
+        }),
+        show: defineJsonCommand({
+            meta: { name: "show", description: "Alias for `akm config list` — list current configuration" },
+            run() {
+                output("config", listConfig(loadConfig()));
+            },
+        }),
+        get: defineJsonCommand({
+            meta: { name: "get", description: "Get a configuration value by key" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key (for example: embedding, stashDir)" },
+            },
+            run({ args }) {
+                output("config", getConfigValue(loadConfig(), args.key));
+            },
+        }),
+        set: defineJsonCommand({
+            meta: { name: "set", description: "Set a configuration value by key" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key (for example: embedding, llm)" },
+                value: { type: "positional", required: true, description: "Config value" },
+                // #463: stable machine-friendly entry point for plugins / hooks.
+                // `--silent` suppresses the config dump on stdout so hook-driven
+                // writes don't pollute their host's output stream.
+                silent: {
+                    type: "boolean",
+                    description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
+                    default: false,
+                },
+                // #463: explicit layer flag for forward-compat. User layer is the only
+                // settable layer today; the flag exists so plugin authors can encode
+                // intent and the surface stays stable if project-layer writes return.
+                layer: {
+                    type: "string",
+                    description: "Config layer to write to. Currently only `user` is supported.",
+                    default: "user",
+                },
+            },
+            run({ args }) {
+                if (args.layer && args.layer !== "user") {
+                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
+                }
+                // Use loadConfig (not loadUserConfig) so the project-config
+                // deprecation warning fires consistently with `akm config get`
+                // (#457). Effective merged shape is identical post-0.8.0.
+                const updated = setConfigValue(loadConfig(), args.key, args.value);
+                saveConfig(updated);
+                if (!args.silent) {
+                    output("config", listConfig(updated));
+                }
+            },
+        }),
+        unset: defineJsonCommand({
+            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/llm section" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key to unset" },
+                silent: {
+                    type: "boolean",
+                    description: "Suppress the post-write config dump on stdout.",
+                    default: false,
+                },
+                layer: {
+                    type: "string",
+                    description: "Config layer to write to. Currently only `user` is supported.",
+                    default: "user",
+                },
+            },
+            run({ args }) {
+                if (args.layer && args.layer !== "user") {
+                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
+                }
+                const updated = unsetConfigValue(loadConfig(), args.key);
+                saveConfig(updated);
+                if (!args.silent) {
+                    output("config", listConfig(updated));
+                }
+            },
+        }),
+        validate: defineJsonCommand({
+            meta: {
+                name: "validate",
+                description: "Validate the on-disk config file against the schema. Exits non-zero on errors.",
+            },
+            async run() {
+                const { runConfigValidate } = await import("../cli/config-validate.js");
+                await runConfigValidate();
+            },
+        }),
+        migrate: defineJsonCommand({
+            meta: {
+                name: "migrate",
+                description: "Migrate the config file to the current schema version. Use --dry-run to preview without writing.",
+            },
+            args: {
+                "dry-run": { type: "boolean", description: "Preview the migration result without writing.", default: false },
+                "print-diff": {
+                    type: "boolean",
+                    description: "Print a unified diff of old vs new config alongside the migration output.",
+                    default: false,
+                },
+            },
+            async run({ args }) {
+                const { runConfigMigrate } = await import("../cli/config-migrate.js");
+                await runConfigMigrate({ dryRun: Boolean(args["dry-run"]), printDiff: Boolean(args["print-diff"]) });
+            },
+        }),
+        enable: defineJsonCommand({
+            meta: { name: "enable", description: "Enable an optional component (skills.sh)" },
+            args: {
+                target: { type: "positional", description: "Component to enable (skills.sh)", required: true },
+            },
+            run({ args }) {
+                const result = toggleComponent(args.target, true);
+                output("enable", result);
+            },
+        }),
+        disable: defineJsonCommand({
+            meta: { name: "disable", description: "Disable an optional component (skills.sh)" },
+            args: {
+                target: { type: "positional", description: "Component to disable (skills.sh)", required: true },
+            },
+            run({ args }) {
+                const result = toggleComponent(args.target, false);
+                output("disable", result);
+            },
+        }),
+    },
+    run({ args }) {
+        if (hasSubcommand(args, CONFIG_SUBCOMMAND_SET))
+            return;
+        if (args.list) {
+            output("config", listConfig(loadConfig()));
+            return;
+        }
+        output("config", listConfig(loadConfig()));
+    },
+});
+const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset", "enable", "disable"]);

package/dist/commands/db-cli.js

@@ -12,8 +12,8 @@
  * plain `mv`/`cp`) to recover. Keeping the surface narrow lets us evolve the
  * backup format under the hood without locking in an API.
  */
-import { getDataDir } from "../core/paths";
-import { listBackups } from "../indexer/db-backup";
+import { getDataDir } from "../core/paths.js";
+import { listBackups } from "../indexer/db/db-backup.js";
 export function akmDbBackups() {
     const dataDir = getDataDir();
     return {