akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.8

package/docs/reference/cli.md

@@ -104,7 +104,7 @@ with an `INVALID_SHAPE_VALUE` usage error (exit 2) — an honest rejection rathe
 than a silent fallback. It returns a compact view suitable for capability
 discovery:
 
-- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`
+- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`, `links`
 
 ## Exit Codes and Error Envelope
 
@@ -331,7 +331,7 @@ Returns a JSON object with:
 | `semanticSearch` | Semantic search status: `mode`, `status`, and optional `reason`/`message` |
 | `registries` | Configured registries |
 | `sourceProviders` | Configured sources (filesystem, git, website, npm) |
-| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `lastBuiltAt`, `hasEmbeddings` |
+| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings` |
 
 `semanticSearch.status` values:
 - `"ready-js"` — every entry has a vector; semantic search is active (the name is historical: `"ready-vec"`, the sqlite-vec variant, is gone)
@@ -436,7 +436,8 @@ The indexed entity graph (entities/relations extracted from bundle assets) has
 no dedicated inspection command; its summary counts surface as an info-level
 metric in `akm health`. Graph data is automatically re-extracted on the first
 `akm improve` cycle after a `DB_VERSION` upgrade. The graph backs `akm show`'s
-`related` list and curate's support refs; it does not affect search ranking.
+`related` list; it does not affect search ranking. Curate's support refs come
+from declared links (`akm show`'s `links`), not from this graph.
 
 ### search
 
@@ -595,10 +596,13 @@ akm curate "learn the release workflow" --from all --format text
 | `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 
 `akm curate` takes the top `--limit` hits of one search, in search order, and
-enriches each with a preview, run details and up to two graph-related support
-refs. With `search.curateRerank.enabled`, a cross-encoder first reorders the
-top 30 fused candidates (`search.curateRerank.topN`) by name, description and
-the start of each asset's indexed content. Curate includes direct follow-up
+enriches each with a preview, run details and up to two support refs: the
+assets the hit's declared links name (`xrefs:`, `supersededBy:` and the other
+kinds `akm show` lists under `links`), what it links to before what links to
+it, skipping assets curate already selected. With
+`search.curateRerank.enabled`, a cross-encoder first reorders the top 30 fused
+candidates (`search.curateRerank.topN`) by name, description and the start of
+each asset's indexed content. Curate includes direct follow-up
 commands such as `akm show <ref>` or `akm bundle add <ref>` so you can
 immediately inspect or install what it found.
 `--detail` and `--shape agent` both work on curate output; `--shape summary`
@@ -691,6 +695,17 @@ returns a compact view with `type`, `name`, `ref`, `description`, `tags`,
 `parameters`, `workflowTitle`, `action`, `run`, `origin`, and `keys`, plus the
 optional fragment metadata described below.
 
+`links` lists the asset's declared links, grouped by kind: `outgoing` (the
+assets its own `xrefs:`, `supersededBy:`, `contradictedBy:`,
+`currentBeliefRefs:`, wiki `sources:`, `.derived` parent, page links, or
+workflow and task targets name), `incoming` (the assets that name it), and
+`unresolved` (tokens it names that match no indexed asset, as written). Each
+kind is `{ "total": n, "refs": [...] }` with at most 10 refs; `total` counts
+them all. The field is omitted when nothing links either way. Links are read
+from frontmatter and parsed structure at index time, with no model; they do
+not affect search ranking. `related` is separate: the LLM entity graph's
+shared-entity neighbours.
+
 Opaque fragment shows and `--context lead` keep `ref` as the canonical parent
 identity and add
 `selectedRef`, `parentRef`, one-based `fragmentOrdinal`, `fragmentCount`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.7",
+  "version": "0.9.17-alpha.8",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/dist/tasks/source/task-to-v3.js

@@ -1,453 +0,0 @@
-// 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/.
-/** Pure, byte-producing legacy-task to task-v3 migration planner. */
-import crypto from "node:crypto";
-import path from "node:path";
-import { LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
-import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
-import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
-import { WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_TIMEOUT_MS } from "../../workflows/resource-limits.js";
-import { validateTaskId } from "../task-id.js";
-import { assertBoundedTaskYamlDocument, TASK_V3_MAX_REDACT_NAMES } from "./bounded-document.js";
-import { classifyTaskV3Uses, parseTaskV3Yaml } from "./task-source-v3-frozen.js";
-const V2_KEYS = new Set([
-    "version",
-    "name",
-    "description",
-    "when_to_use",
-    "tags",
-    "schedule",
-    "enabled",
-    "workflow",
-    "prompt",
-    "command",
-    "params",
-    "engine",
-    "model",
-    "timeoutMs",
-    "maxSteps",
-    "maxRetries",
-    "llm",
-    "redact",
-]);
-const V2_SHARED_KEYS = new Set([
-    "version",
-    "name",
-    "description",
-    "when_to_use",
-    "tags",
-    "schedule",
-    "enabled",
-    "redact",
-]);
-const V2_LLM_KEYS = new Set([
-    "temperature",
-    "maxTokens",
-    "supportsJsonSchema",
-    "extraParams",
-    "contextLength",
-    "enableThinking",
-    "reasoningEffort",
-]);
-const SAFE_V2_COMMAND_TOKEN = /^[A-Za-z0-9_./:=+,-]+$/;
-const SHELL_ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
-/**
- * V2 executed argv directly, while v3 `run:` enters a host shell. An explicit
- * path bypasses shell aliases/builtins; `akm` is the one bare executable whose
- * v3 runtime resolution is contractually pinned to the current installation.
- */
-function shellStableV2Executable(executable) {
-    return executable === "akm" || executable.includes("/");
-}
-/**
- * `env NAME=value... cmd args...` is env(1) itself resolving and exec'ing
- * `cmd` via its own PATH search — that lookup happens inside env's execvp()
- * regardless of whether env was launched by direct execve (v2) or by a host
- * shell (v3 `run:`). The shell-vs-argv divergence `shellStableV2Executable`
- * guards against (bare names shadowed by shell aliases/builtins/functions)
- * therefore does not apply to whatever env ultimately invokes, so skip past
- * a leading `env` and its `NAME=value` assignments to find the real target.
- * Returns the original tokens, unchanged, when there is no such target
- * (e.g. `env` with nothing after its assignments).
- */
-function skipEnvAssignmentPrefix(tokens) {
-    if (tokens[0] !== "env")
-        return { tokens, envWrapped: false };
-    let index = 1;
-    while (index < tokens.length && SHELL_ASSIGNMENT_WORD.test(tokens[index]))
-        index += 1;
-    if (index >= tokens.length)
-        return { tokens, envWrapped: false };
-    return { tokens: tokens.slice(index), envWrapped: true };
-}
-const KNOWN_PROMPT_REF_FAMILIES = new Set([
-    "agents",
-    "commands",
-    "env",
-    "facts",
-    "instructions",
-    "knowledge",
-    "lessons",
-    "memories",
-    "scripts",
-    "secrets",
-    "sessions",
-    "skills",
-    "tasks",
-    "workflows",
-]);
-function hash(bytes) {
-    return crypto.createHash("sha256").update(bytes).digest("hex");
-}
-function base(input) {
-    return {
-        filePath: input.filePath,
-        before: Buffer.from(input.bytes),
-        beforeHash: hash(input.bytes),
-        mode: input.mode,
-        writable: input.writable,
-        ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
-        ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
-    };
-}
-/**
- * #902: the one blocker with an unambiguous remedy. The sibling shell-safety
- * reasons need a case-by-case judgement and stay reason-only.
- */
-const ARGV_ARRAY_BLOCK_DETAIL = "Manual conversion required: an array `command:` has no safe v3 `run:` string. Rewrite it by hand as " +
-    "`run:` (string) plus `shell:` — see docs/migration/v0.9.1-to-v0.9.2.md for the full v2 to v4 field mapping.";
-function blocked(input, reason, detail) {
-    return Object.freeze({ status: "blocked", ...base(input), reason, ...(detail ? { detail } : {}) });
-}
-function plainRecord(value, label) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        throw new Error(`${label} must be a mapping`);
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null)
-        throw new Error(`${label} must use a plain or null prototype`);
-    return value;
-}
-function exactString(value, label, nonempty = false) {
-    if (typeof value !== "string" || (nonempty && value.trim().length === 0)) {
-        throw new Error(`${label} must be ${nonempty ? "a non-empty " : "a "}string`);
-    }
-    return value;
-}
-function optionalString(value, label) {
-    if (value === undefined || value === null)
-        return undefined;
-    return exactString(value, label);
-}
-function parseLegacyTaskYaml(input) {
-    let source;
-    try {
-        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input.bytes);
-    }
-    catch {
-        throw new Error("task YAML contains invalid UTF-8 bytes");
-    }
-    const lineCounter = new LineCounter();
-    let document;
-    try {
-        document = parseDocument(source, { lineCounter, uniqueKeys: true });
-    }
-    catch (cause) {
-        throw new Error(`invalid YAML: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-    const [parseError] = document.errors;
-    if (parseError)
-        throw new Error(`invalid YAML: ${parseError.message.split("\n")[0]}`);
-    const [parseWarning] = document.warnings;
-    if (parseWarning)
-        throw new Error(`unsupported YAML construct: ${parseWarning.message}`);
-    assertBoundedTaskYamlDocument(document, {
-        filePath: input.filePath,
-        sourceLabel: "task v2 migration source",
-        lineCounter,
-    });
-    return { data: plainRecord(document.toJS({ maxAliasCount: 0 }), "task YAML"), source };
-}
-function validateCommonV2(data) {
-    const unknown = Object.keys(data).filter((key) => !V2_KEYS.has(key));
-    if (unknown.length > 0)
-        throw new Error(`unknown v2 field(s): ${unknown.join(", ")}`);
-    exactString(data.schedule, "schedule", true);
-    if (data.enabled !== undefined && typeof data.enabled !== "boolean")
-        throw new Error("enabled must be a boolean");
-    for (const key of ["name", "description", "when_to_use"])
-        optionalString(data[key], key);
-    if (data.tags !== undefined && data.tags !== null) {
-        if (!Array.isArray(data.tags) || data.tags.some((entry) => typeof entry !== "string" || entry.length === 0)) {
-            throw new Error("tags must be an array of non-empty strings");
-        }
-    }
-    if (data.timeoutMs !== undefined && data.timeoutMs !== null) {
-        if (!Number.isInteger(data.timeoutMs) ||
-            data.timeoutMs < 1 ||
-            data.timeoutMs > WORKFLOW_MAX_TIMEOUT_MS) {
-            throw new Error(`timeoutMs must be null or an integer from 1 through ${WORKFLOW_MAX_TIMEOUT_MS}`);
-        }
-    }
-    if (data.redact !== undefined && data.redact !== null) {
-        if (!Array.isArray(data.redact) ||
-            data.redact.length > TASK_V3_MAX_REDACT_NAMES ||
-            data.redact.some((entry) => typeof entry !== "string" || !WORKFLOW_ENV_VAR_NAME_PATTERN.test(entry))) {
-            throw new Error("redact must contain only bounded environment variable names");
-        }
-    }
-}
-function validateTargetFields(data, allowed) {
-    const targetFields = new Set([...allowed, "workflow", "prompt", "command"]);
-    const invalid = Object.keys(data).filter((key) => !V2_SHARED_KEYS.has(key) && !targetFields.has(key));
-    if (invalid.length > 0)
-        throw new Error(`field(s) not valid for this target: ${invalid.join(", ")}`);
-}
-function validateV2Llm(value) {
-    if (value === undefined)
-        return undefined;
-    const llm = plainRecord(value, "llm");
-    const unknown = Object.keys(llm).filter((key) => !V2_LLM_KEYS.has(key));
-    if (unknown.length > 0)
-        throw new Error(`llm has unknown field(s): ${unknown.join(", ")}`);
-    if (llm.temperature !== undefined && (typeof llm.temperature !== "number" || !Number.isFinite(llm.temperature))) {
-        throw new Error("llm.temperature must be a finite number");
-    }
-    for (const key of ["maxTokens", "contextLength"]) {
-        if (llm[key] !== undefined && (!Number.isInteger(llm[key]) || llm[key] <= 0)) {
-            throw new Error(`llm.${key} must be a positive integer`);
-        }
-    }
-    for (const key of ["supportsJsonSchema", "enableThinking"]) {
-        if (llm[key] !== undefined && typeof llm[key] !== "boolean")
-            throw new Error(`llm.${key} must be a boolean`);
-    }
-    if (llm.reasoningEffort !== undefined && (typeof llm.reasoningEffort !== "string" || !llm.reasoningEffort.trim())) {
-        throw new Error("llm.reasoningEffort must be a non-empty string");
-    }
-    if (llm.extraParams !== undefined) {
-        const issue = validateExtraParams(llm.extraParams)[0];
-        if (issue)
-            throw new Error(formatExtraParamsIssue("llm.extraParams", issue));
-    }
-    return llm;
-}
-function commonAkm(data) {
-    const akm = {
-        schedule: exactString(data.schedule, "schedule", true),
-        enabled: data.enabled === undefined ? true : data.enabled,
-    };
-    for (const key of ["description", "when_to_use", "tags"]) {
-        if (data[key] !== undefined && data[key] !== null)
-            akm[key] = data[key];
-    }
-    return akm;
-}
-function addRuntimeOverrides(data, akm) {
-    for (const key of ["engine", "model"]) {
-        const value = optionalString(data[key], key);
-        if (value)
-            akm[key] = value;
-    }
-    const llm = validateV2Llm(data.llm);
-    if (llm !== undefined)
-        akm.inference = llm;
-    if (data.timeoutMs !== undefined)
-        akm.timeout = data.timeoutMs;
-    if (data.redact !== undefined && data.redact !== null) {
-        akm.redact = [...new Set(data.redact)];
-    }
-}
-function addSharedNonPromptOverrides(data, akm) {
-    if (data.timeoutMs !== undefined)
-        akm.timeout = data.timeoutMs;
-    if (data.redact !== undefined && data.redact !== null) {
-        akm.redact = [...new Set(data.redact)];
-    }
-}
-function promptSourceKind(raw) {
-    const trimmed = raw.trim();
-    if (trimmed.startsWith("./") ||
-        trimmed.startsWith("../") ||
-        path.isAbsolute(trimmed) ||
-        /^[A-Za-z]:[\\/]/.test(trimmed)) {
-        return "file";
-    }
-    try {
-        const parsed = parseBundleRef(trimmed);
-        const family = parsed.conceptId.split("/", 1)[0] ?? "";
-        if (bundleRefToString(parsed) !== trimmed || !parsed.conceptId.includes("/")) {
-            return "inline";
-        }
-        if (!KNOWN_PROMPT_REF_FAMILIES.has(family))
-            return parsed.bundle === undefined ? "inline" : "other-ref";
-        if (family === "agents")
-            return "agent";
-        if (family === "commands")
-            return "command";
-        return "other-ref";
-    }
-    catch {
-        return "inline";
-    }
-}
-function migratedObject(data) {
-    validateCommonV2(data);
-    const targets = ["workflow", "prompt", "command"].filter((key) => Object.hasOwn(data, key) && data[key] !== null && data[key] !== "");
-    if (targets.length !== 1)
-        throw new Error("v2 task must declare exactly one of workflow, prompt, or command");
-    const output = { version: 3 };
-    if (data.name !== undefined && data.name !== null)
-        output.name = data.name;
-    const akm = commonAkm(data);
-    if (targets[0] === "workflow") {
-        validateTargetFields(data, ["params", "timeoutMs", "maxSteps", "maxRetries"]);
-        const ref = exactString(data.workflow, "workflow", true).trim();
-        let target;
-        try {
-            target = classifyTaskV3Uses(ref);
-        }
-        catch {
-            throw new Error("workflow is not a canonical v3 asset ref");
-        }
-        if (target.kind !== "workflow")
-            throw new Error("workflow target is not a workflows/ ref");
-        output.uses = ref;
-        if (data.params !== undefined && data.params !== null) {
-            const params = plainRecord(data.params, "params");
-            output.with = params;
-        }
-        if (data.maxSteps !== undefined && data.maxSteps !== null) {
-            if (!Number.isSafeInteger(data.maxSteps) || data.maxSteps < 1)
-                throw new Error("maxSteps must be positive");
-            akm.maxSteps = data.maxSteps;
-        }
-        if (data.maxRetries !== undefined && data.maxRetries !== null) {
-            if (!Number.isSafeInteger(data.maxRetries) || data.maxRetries < 0) {
-                throw new Error("maxRetries must be a non-negative integer");
-            }
-            akm.maxRetries = data.maxRetries;
-        }
-        addSharedNonPromptOverrides(data, akm);
-    }
-    else if (targets[0] === "prompt") {
-        validateTargetFields(data, ["engine", "model", "timeoutMs", "llm"]);
-        const prompt = exactString(data.prompt, "prompt", true).trim();
-        const kind = promptSourceKind(prompt);
-        if (kind === "file")
-            return "dynamic-file-read-cannot-be-inlined-without-changing-semantics";
-        if (kind === "agent")
-            return "agent-ref-has-persona-but-no-command-work";
-        if (kind === "other-ref")
-            return "non-command-asset-has-no-v3-command-ref-equivalent";
-        if (kind === "command")
-            output.uses = prompt;
-        else {
-            output.uses = "akm/command";
-            output.with = { content: prompt };
-        }
-        addRuntimeOverrides(data, akm);
-    }
-    else {
-        validateTargetFields(data, ["timeoutMs"]);
-        if (Array.isArray(data.command))
-            return "argv-array-has-no-portable-shell-string";
-        const command = exactString(data.command, "command", true).trim();
-        if (/['"\\]/.test(command))
-            return "shell-quoting-changes-v2-whitespace-split-semantics";
-        const tokens = command.split(/\s+/).filter(Boolean);
-        if (tokens.length === 0 || tokens.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
-            return "shell-operators-change-v2-literal-argv-semantics";
-        }
-        const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens);
-        const executable = targetTokens[0];
-        if (SHELL_ASSIGNMENT_WORD.test(executable) || (!envWrapped && !shellStableV2Executable(executable))) {
-            return "shell-command-resolution-changes-v2-literal-argv-semantics";
-        }
-        output.run = tokens.join(" ");
-        addSharedNonPromptOverrides(data, akm);
-    }
-    output.akm = akm;
-    return output;
-}
-function isReason(value) {
-    return typeof value === "string";
-}
-/** Convert one already-normalized legacy record directly to final task v3. */
-function planLegacyTaskDataToV3(input, data) {
-    if (data.version !== 2) {
-        return blocked(input, "unsupported-task-version", `expected normalized legacy version 2, got ${String(data.version)}`);
-    }
-    if (!input.writable || input.onDiskWritable === false) {
-        return blocked(input, "read-only-source", !input.writable ? "the owning source is not writable" : "the source file or publication directory is read-only");
-    }
-    try {
-        validateTaskId(path.basename(input.filePath, ".yml"));
-    }
-    catch (cause) {
-        return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
-    }
-    let migrated;
-    try {
-        migrated = migratedObject(data);
-    }
-    catch (cause) {
-        return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
-    }
-    if (isReason(migrated)) {
-        const detail = migrated === "argv-array-has-no-portable-shell-string" ? ARGV_ARRAY_BLOCK_DETAIL : undefined;
-        return blocked(input, migrated, detail);
-    }
-    const after = Buffer.from(stringifyYaml(migrated), "utf8");
-    try {
-        parseTaskV3Yaml({
-            yaml: after.toString("utf8"),
-            filePath: input.filePath,
-            ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
-        });
-    }
-    catch (cause) {
-        return blocked(input, "generated-v3-validation-failed", cause instanceof Error ? cause.message : String(cause));
-    }
-    return Object.freeze({
-        status: "changed",
-        ...base(input),
-        reason: "task-converted",
-        after,
-        afterHash: hash(after),
-    });
-}
-/** Plan exactly one source file without touching disk. */
-export function planTaskToV3File(input) {
-    let data;
-    let source;
-    try {
-        ({ data, source } = parseLegacyTaskYaml(input));
-    }
-    catch (cause) {
-        return blocked(input, "invalid-task-yaml", cause instanceof Error ? cause.message : String(cause));
-    }
-    if (data.version === 3) {
-        try {
-            parseTaskV3Yaml({
-                yaml: source,
-                filePath: input.filePath,
-                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
-            });
-            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v3" });
-        }
-        catch (cause) {
-            return blocked(input, "invalid-v3-task", cause instanceof Error ? cause.message : String(cause));
-        }
-    }
-    if (data.version === 4) {
-        // Generation 1 owns v2 only. Do not validate v4 here: generation 2 must
-        // be allowed to recognize and remove the retired schedule[].enabled field
-        // before the current runtime parser sees those bytes.
-        return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
-    }
-    if (data.version !== 2) {
-        return blocked(input, "unsupported-task-version", `expected version 2, 3, or 4, got ${String(data.version)}`);
-    }
-    return planLegacyTaskDataToV3(input, data);
-}