akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/core/asset/asset-spec.js

@@ -1,6 +1,7 @@
 // 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/.
+import fs from "node:fs";
 import path from "node:path";
 import { buildWorkflowAction } from "../../output/renderers.js";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry.js";
@@ -8,6 +9,59 @@ function toPosix(input) {
     return input.replace(/\\/g, "/");
 }
 const buildTaskAction = (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`;
+/**
+ * Recognized workflow asset extensions, in resolution-priority order.
+ * `.md` (classic linear markdown workflows — the stable contract) stays
+ * FIRST for back-compat; `.yaml`/`.yml` hold YAML workflow *programs*
+ * (redesign addendum, R1). `workflow:<name>` refs resolve against this list.
+ */
+export const WORKFLOW_EXTENSIONS = [".md", ".yaml", ".yml"];
+/**
+ * Strip a recognized workflow extension (`.md`/`.yaml`/`.yml`) from a workflow
+ * asset *name* so `foo`, `foo.yaml`, `foo.yml`, and `foo.md` collapse to one
+ * canonical identity — the same collapse `workflowSpec.toCanonicalName`
+ * performs on a resolved file path. Callers that turn a `workflow:<name>` ref
+ * into run identity (the active-run guard, list/status filters) MUST route the
+ * name through this so an aliased spelling (`workflow:foo.yaml`) and the
+ * canonical `workflow:foo` cannot start or hide parallel runs of the same
+ * workflow. Names without a recognized workflow extension pass through
+ * unchanged.
+ */
+export function canonicalizeWorkflowName(name) {
+    const lower = name.toLowerCase();
+    for (const ext of WORKFLOW_EXTENSIONS) {
+        if (lower.endsWith(ext))
+            return name.slice(0, -ext.length);
+    }
+    return name;
+}
+const workflowSpec = {
+    isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (rel.toLowerCase().endsWith(ext))
+                return rel.slice(0, -ext.length);
+        }
+        return rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Explicit extension wins (accepts refs like "release/ship.yaml").
+        const lower = name.toLowerCase();
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (lower.endsWith(ext))
+                return path.join(typeRoot, name);
+        }
+        // Probe in priority order — `.md` first for back-compat — and fall back
+        // to the markdown path so error messages keep naming the canonical file.
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            const candidate = path.join(typeRoot, `${name}${ext}`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(typeRoot, `${name}.md`);
+    },
+};
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -62,7 +116,10 @@ const ASSET_SPECS_INTERNAL = {
     knowledge: { stashDir: "knowledge", ...markdownSpec },
     workflow: {
         stashDir: "workflows",
-        ...markdownSpec,
+        ...workflowSpec,
+        // Type-level renderer for markdown workflows; YAML programs are claimed by
+        // the dedicated `workflowProgramMatcher`, which names the
+        // "workflow-program-yaml" renderer directly on its MatchResult.
         rendererName: "workflow-md",
         actionBuilder: (ref) => buildWorkflowAction(ref),
     },

package/dist/core/asset/frontmatter.js

@@ -10,7 +10,7 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import { assembleAsset } from "./asset-serialize.js";
+import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
  *
@@ -118,6 +118,13 @@ function parseFrontmatterLenient(frontmatter) {
  * or `null` to skip the write entirely (e.g. for idempotent no-ops). The body
  * content is preserved from the parse.
  *
+ * A frontmatter mutation is a METADATA edit, not a content edit: when the file
+ * already has a frontmatter block, only that block is replaced and the body
+ * bytes are kept verbatim (routing through `assembleAsset` would strip the
+ * body's leading blank lines and force a trailing newline, silently reshaping
+ * assets whose writer used a different separator style). A file gaining its
+ * FIRST frontmatter block goes through the canonical `assembleAsset` shape.
+ *
  * @returns `true` if a write occurred, `false` if the mutator returned `null`.
  */
 export function mutateFrontmatter(filePath, mutator) {
@@ -126,7 +133,10 @@ export function mutateFrontmatter(filePath, mutator) {
     const nextFrontmatter = mutator(parsed);
     if (nextFrontmatter === null)
         return false;
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    const next = parsed.frontmatter !== null
+        ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
+        : assembleAsset(nextFrontmatter, parsed.content);
+    fs.writeFileSync(filePath, next, "utf8");
     return true;
 }
 export function parseFrontmatterBlock(raw) {

package/dist/core/common.js

@@ -243,11 +243,12 @@ function normalizeFsPathForComparison(value) {
  */
 export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = timeoutMs === null ? undefined : setTimeout(() => controller.abort(), timeoutMs);
     const abortExternal = () => controller.abort(signal?.reason);
     if (signal) {
         if (signal.aborted) {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             controller.abort(signal.reason);
         }
         else {
@@ -269,7 +270,8 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     finally {
         if (signal)
             signal.removeEventListener("abort", abortExternal);
-        clearTimeout(timer);
+        if (timer)
+            clearTimeout(timer);
     }
 }
 /**

package/dist/core/config/config-io.js

@@ -17,7 +17,7 @@ import path from "node:path";
 import { sleepSync } from "../../runtime.js";
 import { writeFileAtomic } from "../common.js";
 import { ConfigError } from "../errors.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
 import { getCacheDir, getConfigDir } from "../paths.js";
 /**
  * Read the raw text of a config file. Returns `undefined` when the file does
@@ -80,7 +80,7 @@ export function writeConfigAtomic(configPath, config) {
 }
 /** Maximum number of timestamped config backups to retain (#459). */
 const MAX_CONFIG_BACKUPS = 5;
-export function backupExistingConfig(configPath) {
+export function backupExistingConfig(configPath, now = new Date()) {
     if (!fs.existsSync(configPath))
         return undefined;
     const backupDir = path.join(getCacheDir(), "config-backups");
@@ -89,10 +89,22 @@ export function backupExistingConfig(configPath) {
     // the copy→chmod window. chmod again to tighten a dir from an older version.
     fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
     fs.chmodSync(backupDir, 0o700);
-    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    const timestamped = path.join(backupDir, `config-${timestamp}.json`);
+    const timestamp = now.toISOString().replace(/[.:]/g, "-");
+    let sequence = 0;
+    let timestamped;
+    while (true) {
+        timestamped = path.join(backupDir, `config-${timestamp}${sequence === 0 ? "" : `-${sequence}`}.json`);
+        try {
+            fs.copyFileSync(configPath, timestamped, fs.constants.COPYFILE_EXCL);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            sequence++;
+        }
+    }
     const latest = path.join(backupDir, "config.latest.json");
-    fs.copyFileSync(configPath, timestamped);
     fs.copyFileSync(configPath, latest);
     // 08-F4: a config backup carries the same sensitive fields as the live config
     // (endpoints, tokens). `copyFileSync` inherits the source's (often 0644) mode,
@@ -141,7 +153,7 @@ function pruneOldBackups(backupDir) {
  * predictable for debugging. Uses $CONFIG (not $DATA) because config.json
  * itself lives in $CONFIG — they should fail together if the dir is read-only.
  */
-function getConfigLockPath() {
+export function getConfigLockPath() {
     return path.join(getConfigDir(), "config.json.lck");
 }
 const CONFIG_LOCK_MAX_RETRIES = 10;
@@ -157,8 +169,8 @@ function sleepSyncMs(ms) {
 /**
  * Acquire an exclusive sentinel around config writes.
  *
- * Returns a release function. Best-effort: when all retries are exhausted the
- * write proceeds unlocked rather than erroring (same posture as lockfile.ts).
+ * Returns a release function. Acquisition is fail-closed: config mutation may
+ * never continue without owning the lock that protects its read/merge/write.
  */
 export function acquireConfigLock() {
     const lockPath = getConfigLockPath();
@@ -170,16 +182,16 @@ export function acquireConfigLock() {
     }
     for (let attempt = 0; attempt < CONFIG_LOCK_MAX_RETRIES; attempt++) {
         try {
-            if (tryAcquireLockSync(lockPath, String(process.pid))) {
-                return () => releaseLock(lockPath);
+            const ownership = tryAcquireLockSync(lockPath, createLockPayload());
+            if (ownership) {
+                return () => releaseLock(ownership);
             }
         }
-        catch {
-            // Non-EEXIST error (permissions, etc.) — bail out and proceed unlocked.
-            break;
+        catch (error) {
+            throw new ConfigError(`Unable to acquire config lock at ${lockPath}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
         }
-        if (probeLock(lockPath).state === "stale") {
-            releaseLock(lockPath);
+        const probe = probeLock(lockPath);
+        if (probe.state === "stale" && reclaimStaleLock(lockPath, probe)) {
             continue; // Reclaimed — retry immediately.
         }
         if (attempt < CONFIG_LOCK_MAX_RETRIES - 1) {
@@ -195,8 +207,7 @@ export function acquireConfigLock() {
             sleepSyncMs(CONFIG_LOCK_RETRY_DELAY_MS);
         }
     }
-    // Best-effort: proceed without lock.
-    return () => { };
+    throw new ConfigError(`Timed out waiting for config lock at ${lockPath}. Another AKM process may be updating config.`, "INVALID_CONFIG_FILE");
 }
 /**
  * Run `fn` inside the config write lock. Always releases the lock.