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

package/dist/workflows/authoring/authoring.js

@@ -4,43 +4,79 @@
 import fs from "node:fs";
 import path from "node:path";
 import workflowTemplate from "../../assets/workflows/workflow-template.md" with { type: "text" };
-import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
-import { isWithin, resolveStashDir } from "../../core/common.js";
+import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
+import { makeBundleRef } from "../../core/asset/asset-ref.js";
+import { isWithin, writeFileAtomic } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { defaultBundleForTarget } from "../../core/mutation-target.js";
+import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { warn } from "../../core/warn.js";
+import { prepareWriteTargetForMutation, resolveWriteTarget, withWriteTargetMutation } from "../../core/write-source.js";
+import { compileWorkflowPlan } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
-const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
-    title: "Example Workflow",
-    firstStepTitle: "First Step",
-    firstStepId: "first-step",
-});
+const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate("New Workflow");
 export function getWorkflowTemplate() {
     return DEFAULT_WORKFLOW_TEMPLATE;
 }
 export function buildWorkflowTemplate(name) {
     if (!name)
         return DEFAULT_WORKFLOW_TEMPLATE;
-    const title = humanizeWorkflowName(name);
-    const stepId = slugifyWorkflowStepId(name);
-    const customized = renderWorkflowTemplate({
-        title,
-        firstStepTitle: `${title} Setup`,
-        firstStepId: `${stepId}-setup`,
-    });
-    const result = parseWorkflow(customized, { path: `<template:${name}>` });
+    // Only the H1 is customized. Step ids are STRUCTURAL under the unified format
+    // — each appears in `steps[].id`, as a body `## <id>` heading, and possibly in
+    // another step's `inputs:` — so rewriting them from a name would have to patch
+    // three places consistently to stay parseable. Generic `first-step`/
+    // `second-step` are the author's to rename.
+    const customized = renderWorkflowTemplate(humanizeWorkflowName(name));
+    validateWorkflowContent(customized, `<template:${name}>`);
+    return customized;
+}
+/** Parse AND compile `content`, so a create never writes an asset that `show`/`start`/`validate` would then reject. */
+function validateWorkflowContent(content, sourcePath) {
+    const result = parseWorkflow(content, { path: sourcePath });
     if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, result.errors));
+        throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
     }
-    return customized;
+    const compiled = compileWorkflowPlan(result.document, slugifyWorkflowStepId(sourcePath));
+    if (!compiled.ok) {
+        throw new UsageError(formatWorkflowErrors(sourcePath, compiled.errors));
+    }
+}
+/** Recognized workflow-program suffixes — creating one is a lint-time usage error (workflow-format-unification). */
+const YAML_SUFFIX_RE = /\.ya?ml$/i;
+export function assertWorkflowMarkdownName(name) {
+    if (!YAML_SUFFIX_RE.test(name.trim()))
+        return;
+    throw new UsageError(`Workflows are markdown-only now (workflow-format-unification) — "${name}" cannot be created. ` +
+        `Use a plain name (no ".yaml"/".yml" suffix); the orchestration graph lives in the ".md" file's frontmatter.`);
 }
 export function createWorkflowAsset(input) {
-    const stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "workflows");
-    fs.mkdirSync(typeRoot, { recursive: true });
+    assertWorkflowMarkdownName(input.name);
+    const config = loadConfig();
+    const resolvedTarget = resolveWriteTarget(config);
+    const target = prepareWriteTargetForMutation(resolvedTarget, { allowedAdapters: ["akm", "akm-workflow"] });
+    const stashDir = target.source.path;
+    const standaloneWorkflowBundle = target.source.adapterId === "akm-workflow";
+    const typeRoot = standaloneWorkflowBundle ? stashDir : path.join(stashDir, "workflows");
     const normalizedName = normalizeWorkflowName(input.name);
-    const assetPath = resolveAssetPathFromName("workflow", typeRoot, normalizedName);
-    if (!isWithin(assetPath, typeRoot)) {
-        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
+    const conceptId = standaloneWorkflowBundle ? normalizedName : `workflows/${normalizedName}`;
+    const assetPath = path.join(typeRoot, `${normalizedName}.md`);
+    const relativeAssetPath = path.relative(path.resolve(typeRoot), path.resolve(assetPath));
+    if (relativeAssetPath === ".." ||
+        relativeAssetPath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeAssetPath)) {
+        throw new UsageError(`Resolved workflow path escapes the bundle: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
+    }
+    // A file whose canonical name matches but whose PATH differs can only be a
+    // case variant now (`upper.MD` vs `upper.md`) — the cross-EXTENSION case this
+    // guard also covered is gone with the unified `.md`-only format. It still
+    // matters: on a case-insensitive filesystem the two spellings are one file,
+    // so writing the target would silently clobber or shadow the existing asset.
+    const shadowing = findExistingWorkflowPaths(typeRoot, normalizedName).find((p) => p !== assetPath);
+    if (shadowing !== undefined) {
+        throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(stashDir, shadowing)} — the ` +
+            `\`${conceptId}\` ref resolves to that file, so creating this one would shadow it. ` +
+            `Remove or rename the existing file first, or create the workflow under a different name.`, "RESOURCE_ALREADY_EXISTS");
     }
     if (fs.existsSync(assetPath) && !input.force) {
         throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
@@ -49,14 +85,17 @@ export function createWorkflowAsset(input) {
         ? readWorkflowSource(input.from, stashDir)
         : (input.content ?? buildWorkflowTemplate(normalizedName));
     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");
+    validateWorkflowContent(content, sourcePath);
+    const authoredContent = ensureAkmMarkdownType(content, "workflow");
+    const mode = fs.existsSync(assetPath) ? fs.lstatSync(assetPath).mode & 0o777 : 0o644;
+    const defaultBundle = defaultBundleForTarget(config);
+    const ref = makeBundleRef(target.source.name === defaultBundle ? undefined : target.source.name, conceptId);
+    withWriteTargetMutation(target, [assetPath], { ignored: "reject", purpose: "workflow-authoring", message: `Create ${ref}` }, () => {
+        fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+        writeFileAtomic(assetPath, authoredContent.endsWith("\n") ? authoredContent : `${authoredContent}\n`, mode);
+    });
     return {
-        ref: `workflow:${normalizedName}`,
+        ref,
         path: assetPath,
         stashDir,
     };
@@ -83,11 +122,13 @@ function readWorkflowSource(source, stashDir) {
     return fs.readFileSync(resolved, "utf8");
 }
 function normalizeWorkflowName(name) {
-    const normalized = name
+    // Strip a recognized workflow extension (.md) so the canonical name — and
+    // thus the `workflows/<name>` ref — is extension-free regardless of how the
+    // user spelled it.
+    const normalized = canonicalizeWorkflowName(name
         .trim()
         .replace(/\\/g, "/")
-        .replace(/^\/+|\/+$/g, "")
-        .replace(/\.md$/i, "");
+        .replace(/^\/+|\/+$/g, ""));
     if (!normalized) {
         throw new UsageError("Workflow name cannot be empty.");
     }
@@ -103,7 +144,7 @@ function humanizeWorkflowName(name) {
         .pop()
         ?.replace(/[-_]+/g, " ")
         .replace(/\b\w/g, (match) => match.toUpperCase())
-        .trim() || "Example Workflow");
+        .trim() || "New Workflow");
 }
 function slugifyWorkflowStepId(name) {
     return (name
@@ -119,7 +160,7 @@ export function formatWorkflowErrors(path, errors) {
     return [heading, ...lines].join("\n");
 }
 /**
- * Validate a workflow by ref (`workflow:<name>`) or filesystem path.
+ * Validate a workflow filesystem path.
  *
  * Returns the parse result plus the source-relative path used. Throws
  * `UsageError` only when the target cannot be located on disk; parse
@@ -127,9 +168,6 @@ export function formatWorkflowErrors(path, errors) {
  * 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}".`);
@@ -137,9 +175,32 @@ export function validateWorkflowSource(target) {
     const content = fs.readFileSync(resolved, "utf8");
     return { path: target, parse: parseWorkflow(content, { path: target }) };
 }
-function renderWorkflowTemplate(input) {
-    return workflowTemplate
-        .replace("{{TITLE}}", input.title)
-        .replace("{{FIRST_STEP_TITLE}}", input.firstStepTitle)
-        .replace("{{FIRST_STEP_ID}}", input.firstStepId);
+/**
+ * Every file under `typeRoot` whose canonical workflow name equals
+ * `normalizedName`. Extension matching is case-INSENSITIVE, so `foo.MD` and
+ * `foo.md` both match — the case-variant collision the create path must refuse
+ * rather than silently clobber on a case-insensitive filesystem.
+ */
+function findExistingWorkflowPaths(typeRoot, normalizedName) {
+    const parent = path.join(typeRoot, path.dirname(normalizedName));
+    let entries;
+    try {
+        entries = fs.readdirSync(parent, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const basename = path.basename(normalizedName);
+    return WORKFLOW_EXTENSIONS.flatMap((extension) => entries
+        .filter((entry) => {
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            return false;
+        const entryExtension = path.extname(entry.name);
+        return entryExtension.toLowerCase() === extension && entry.name.slice(0, -entryExtension.length) === basename;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => path.join(parent, entry.name)));
+}
+function renderWorkflowTemplate(title) {
+    return workflowTemplate.replace("{{TITLE}}", title);
 }

package/dist/workflows/authoring/scope-key.js

@@ -21,7 +21,7 @@ export function resolveWorkflowScopeAnchor(startDir) {
     if (gitRoot)
         return gitRoot;
     try {
-        const stashDir = safeRealpath(resolveStashDir({ readOnly: true }));
+        const stashDir = safeRealpath(resolveStashDir());
         if (isWithin(cwd, stashDir))
             return stashDir;
     }

package/dist/workflows/cli.js

@@ -8,18 +8,6 @@ export const WORKFLOW_STEP_STATES = [
     "failed",
     "skipped",
 ];
-export const WORKFLOW_SUBCOMMANDS = new Set([
-    "start",
-    "next",
-    "complete",
-    "status",
-    "list",
-    "create",
-    "template",
-    "resume",
-    "abandon",
-    "validate",
-]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)
         return {};
@@ -43,7 +31,3 @@ export function parseWorkflowStepState(value) {
     }
     throw new UsageError(`Invalid workflow step state "${value}". Expected one of: ${WORKFLOW_STEP_STATES.join(", ")}`);
 }
-export function hasWorkflowSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && WORKFLOW_SUBCOMMANDS.has(command);
-}

package/dist/workflows/concurrency-policy.js

@@ -0,0 +1,15 @@
+// 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 os from "node:os";
+export const WORKFLOW_MAX_CONCURRENCY_CEILING = 64;
+export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
+    return Math.min(16, Math.max(1, cpuCount - 2));
+}
+export function clampMaxConcurrency(value) {
+    return Math.min(WORKFLOW_MAX_CONCURRENCY_CEILING, Math.max(1, Math.floor(value)));
+}
+/** Resolve and freeze the engine-wide cap once when a workflow run starts. */
+export function workflowMaxConcurrency(configured, cpuCount = os.cpus()?.length ?? 4) {
+    return configured === undefined ? cpuDerivedUnitConcurrency(cpuCount) : clampMaxConcurrency(configured);
+}