akm-cli 0.9.0-rc.9 → 0.9.0

package/dist/tasks/scheduler-invocation.js

@@ -1,35 +1,197 @@
 // 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 { createHash } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../core/common.js";
 import { ConfigError } from "../core/errors.js";
-import { getCacheDir, getConfigDir, getDataDir } from "../core/paths.js";
+import { getCacheDir, getConfigDir, getDataDir, getTaskContextDir } from "../core/paths.js";
 export const SCHEDULED_TASK_CONTEXT_KEYS = [
-    "AKM_STASH_DIR",
+    "AKM_BUNDLE_DIR",
     "AKM_CONFIG_DIR",
     "AKM_DATA_DIR",
     "AKM_CACHE_DIR",
     "AKM_STATE_DIR",
 ];
+export const SCHEDULER_CONTEXT_ARG = "--scheduler-context";
 /** Resolve the complete non-secret AKM directory context captured by schedulers. */
 export function resolveScheduledTaskContext(env = process.env, platform = process.platform) {
     return canonicalContext({
-        AKM_STASH_DIR: path.resolve(resolveStashDir(undefined, env)),
+        AKM_BUNDLE_DIR: path.resolve(resolveStashDir(env)),
         AKM_CONFIG_DIR: path.resolve(getConfigDir(env, platform)),
         AKM_DATA_DIR: path.resolve(getDataDir(env, platform)),
         AKM_CACHE_DIR: path.resolve(getCacheDir(env)),
-        // Retain the legacy state root for scheduled commands and upgrade tooling
-        // that still honor it even though current durable state lives under DATA.
+        // Capture the complete process directory context used by scheduled commands.
         AKM_STATE_DIR: path.resolve(resolveStateDir(env, platform)),
     });
 }
-/** Build the one scheduler-generated argv shape consumed by all backends. */
-export function buildScheduledTaskInvocation(akmArgv, id, context) {
-    const environment = canonicalContext(context);
+/**
+ * Build the one scheduler-generated argv shape consumed by all backends.
+ *
+ * `target` records the bundle a non-primary task lives in as a `--bundle
+ * <bundle>` token so the scheduled `akm task run` resolves the task (and its
+ * relative asset refs) from that bundle. It is emitted ONLY when supplied and
+ * non-empty — callers pass it exclusively for a non-default bundle, so a
+ * primary-bundle (or default) task omits the target pair.
+ */
+export function buildScheduledTaskInvocation(akmArgv, id, contextPath, target) {
+    const targetArgs = target !== undefined && target !== "" ? ["--bundle", target] : [];
     return {
-        argv: [...akmArgv, "tasks", "run", id, "--scheduled"],
-        environment,
+        argv: [
+            ...akmArgv,
+            SCHEDULER_CONTEXT_ARG,
+            assertAbsolutePath(contextPath),
+            "task",
+            "run",
+            id,
+            ...targetArgs,
+            "--scheduled",
+        ],
+    };
+}
+export function schedulerContextDescriptor(context = resolveScheduledTaskContext(), envPath = process.env.PATH ?? "") {
+    return {
+        version: 1,
+        environment: { ...canonicalContext(context), PATH: validatePathValue(envPath) },
+    };
+}
+export function schedulerContextPath(descriptor) {
+    const bytes = serializeDescriptor(descriptor);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    return path.join(getTaskContextDir(descriptor.environment), `${digest}.json`);
+}
+/** Write a content-addressed descriptor without ever replacing existing content. */
+export function writeSchedulerContextDescriptor(descriptor = schedulerContextDescriptor()) {
+    const file = schedulerContextPath(descriptor);
+    const bytes = serializeDescriptor(descriptor);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        fs.chmodSync(path.dirname(file), 0o700);
+    }
+    if (lstatIfExists(file)) {
+        if (serializeDescriptor(validateSchedulerContextDescriptor(file)) !== bytes)
+            throw invalidSchedulerContext();
+        return file;
+    }
+    const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs.writeFileSync(temp, bytes, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        try {
+            fs.renameSync(temp, file);
+        }
+        catch (error) {
+            if (!lstatIfExists(file) || serializeDescriptor(validateSchedulerContextDescriptor(file)) !== bytes)
+                throw error;
+        }
+        restrictDescriptor(file);
+        validateSchedulerContextDescriptor(file);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+    return file;
+}
+export function loadSchedulerContextDescriptor(file, env = process.env) {
+    const descriptor = validateSchedulerContextDescriptor(file);
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS)
+        env[key] = descriptor.environment[key];
+    env.PATH = descriptor.environment.PATH;
+}
+export function validateSchedulerContextDescriptor(file) {
+    const absolute = assertAbsolutePath(file);
+    let linkStat;
+    try {
+        linkStat = fs.lstatSync(absolute);
+    }
+    catch (error) {
+        throw schedulerContextFileError(absolute, error instanceof Error ? error.message : String(error));
+    }
+    if (linkStat.isSymbolicLink())
+        throw schedulerContextFileError(absolute, "symbolic links are not allowed");
+    if (!linkStat.isFile())
+        throw schedulerContextFileError(absolute, "path is not a regular file");
+    let descriptorBytes;
+    let fd;
+    try {
+        const noFollow = process.platform === "win32" ? 0 : fs.constants.O_NOFOLLOW;
+        fd = fs.openSync(absolute, fs.constants.O_RDONLY | noFollow);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw schedulerContextFileError(absolute, "path is not a regular file");
+        if (process.platform !== "win32") {
+            if (typeof process.getuid !== "function") {
+                throw schedulerContextFileError(absolute, "current uid is unavailable for ownership verification");
+            }
+            const uid = process.getuid();
+            if (stat.uid !== uid)
+                throw schedulerContextFileError(absolute, `file owner ${stat.uid} does not match uid ${uid}`);
+            if ((stat.mode & 0o077) !== 0) {
+                throw schedulerContextFileError(absolute, "group or other permissions must be disabled");
+            }
+        }
+        descriptorBytes = fs.readFileSync(fd);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw error;
+        throw schedulerContextFileError(absolute, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    const filename = path.basename(absolute);
+    const match = /^([a-f0-9]{64})\.json$/.exec(filename);
+    const digest = createHash("sha256").update(descriptorBytes).digest("hex");
+    if (!match || match[1] !== digest) {
+        throw schedulerContextFileError(absolute, "content SHA-256 does not match the descriptor filename");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(descriptorBytes.toString("utf8"));
+    }
+    catch (error) {
+        throw schedulerContextFileError(absolute, error instanceof Error ? error.message : String(error));
+    }
+    return canonicalDescriptor(parsed);
+}
+/** Load and remove the hidden descriptor argument before citty parses argv. */
+export function consumeSchedulerContextArg(argv, env = process.env) {
+    const separator = argv.indexOf("--");
+    const index = argv.slice(0, separator === -1 ? argv.length : separator).indexOf(SCHEDULER_CONTEXT_ARG);
+    if (index === -1)
+        return argv;
+    const file = argv[index + 1];
+    if (!file) {
+        throw new ConfigError(`${SCHEDULER_CONTEXT_ARG} requires an absolute descriptor path.`, "INVALID_CONFIG_FILE");
+    }
+    loadSchedulerContextDescriptor(file, env);
+    return [...argv.slice(0, index), ...argv.slice(index + 2)];
+}
+export function parseScheduledTaskArgv(argv) {
+    const contextIndex = argv.indexOf(SCHEDULER_CONTEXT_ARG);
+    if (contextIndex < 1 || argv.indexOf(SCHEDULER_CONTEXT_ARG, contextIndex + 1) !== -1)
+        return undefined;
+    const contextPath = argv[contextIndex + 1];
+    const tasksIndex = contextIndex + 2;
+    if (!contextPath || argv[tasksIndex] !== "task" || argv[tasksIndex + 1] !== "run" || !argv[tasksIndex + 2]) {
+        return undefined;
+    }
+    let index = tasksIndex + 3;
+    let target;
+    if (argv[index] === "--bundle") {
+        target = argv[index + 1];
+        if (!target)
+            return undefined;
+        index += 2;
+    }
+    if (argv[index] !== "--scheduled" || index !== argv.length - 1)
+        return undefined;
+    return {
+        binding: [...argv.slice(0, contextIndex)],
+        contextPath: assertAbsolutePath(contextPath),
+        ...(target !== undefined ? { target } : {}),
     };
 }
 function canonicalContext(input) {
@@ -51,6 +213,54 @@ function canonicalContext(input) {
     }
     return context;
 }
+function canonicalDescriptor(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        throw invalidSchedulerContext();
+    const record = input;
+    if (Object.keys(record).length !== 2 || record.version !== 1)
+        throw invalidSchedulerContext();
+    const rawEnvironment = record.environment;
+    if (typeof rawEnvironment !== "object" || rawEnvironment === null || Array.isArray(rawEnvironment)) {
+        throw invalidSchedulerContext();
+    }
+    const environment = rawEnvironment;
+    if (Object.keys(environment).length !== SCHEDULED_TASK_CONTEXT_KEYS.length + 1)
+        throw invalidSchedulerContext();
+    const PATH = validatePathValue(environment.PATH);
+    const { PATH: _, ...rawContext } = environment;
+    return { version: 1, environment: { ...canonicalContext(rawContext), PATH } };
+}
+function serializeDescriptor(descriptor) {
+    return `${JSON.stringify(canonicalDescriptor(descriptor))}\n`;
+}
+function validatePathValue(value) {
+    if (typeof value !== "string" || containsControlCharacter(value))
+        throw invalidSchedulerContext();
+    return value;
+}
+function assertAbsolutePath(value) {
+    if (containsControlCharacter(value) || (!path.posix.isAbsolute(value) && !path.win32.isAbsolute(value))) {
+        throw invalidSchedulerContext();
+    }
+    return value;
+}
+function restrictDescriptor(file) {
+    if (process.platform !== "win32")
+        fs.chmodSync(file, 0o600);
+}
+function lstatIfExists(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function schedulerContextFileError(file, reason) {
+    return new ConfigError(`Invalid scheduler context descriptor "${file}": ${reason}.`, "INVALID_CONFIG_FILE");
+}
 function containsControlCharacter(value) {
     for (const char of value) {
         const code = char.codePointAt(0) ?? 0;

package/dist/tasks/schema.js

@@ -4,7 +4,7 @@
 /**
  * Task asset schema. A task pairs a cron-style schedule with exactly one of:
  *
- *   • a workflow target  — invoked via `startWorkflowRun()`
+ *   • a workflow target  — executed via `runWorkflowSteps()`
  *   • a prompt target    — invoked via `runAgent()` against the configured
  *                          agent harness (e.g. `opencode run`)
  *   • a command target   — invoked directly via `Bun.spawn()`, no AI agent
@@ -13,3 +13,26 @@
  * inline prompts use a YAML block scalar (`prompt: |`).
  */
 export const TASK_SCHEMA_VERSION = 2;
+/**
+ * Lint-level shape problems for a parsed task YAML mapping: the field rules
+ * `src/tasks/parser.ts` enforces at load time, phrased as diagnostics. The ONE
+ * definition shared by both task linters (`core/adapter/adapters/akm-lint.ts`
+ * and `akm-task-adapter.ts`) so lint and runtime cannot disagree — they
+ * previously did, in both directions: lint demanded `enabled` (which the
+ * parser defaults to `true`, so a runnable task was flagged) and never checked
+ * `version` (which the parser hard-requires as `2`, so a lint-clean task died
+ * at runtime with TASK_SCHEMA_VERSION_UNSUPPORTED). `schemas/akm-task.json`
+ * agrees with the parser: `required: [version, schedule]`, `version:
+ * {const: 2}`, `enabled` optional but boolean. Target-arity rules stay with
+ * each caller (they legitimately differ: at-least-one vs exactly-one).
+ */
+export function taskFieldProblems(data) {
+    const problems = [];
+    if (data.version !== TASK_SCHEMA_VERSION)
+        problems.push(`version (must be ${TASK_SCHEMA_VERSION})`);
+    if (typeof data.schedule !== "string" || data.schedule.trim() === "")
+        problems.push("schedule");
+    if ("enabled" in data && typeof data.enabled !== "boolean")
+        problems.push("enabled (must be a boolean when present)");
+    return problems;
+}

package/dist/tasks/task-id.js

@@ -31,7 +31,5 @@ export function validateTaskId(id) {
     return id;
 }
 export function normaliseTaskId(raw) {
-    // Keep accepting old task-file suffixes at the CLI boundary, but never
-    // normalize filesystem-derived ids into a different filename.
-    return validateTaskId(raw.trim().replace(/\.(yml|md)$/, ""));
+    return validateTaskId(raw.trim());
 }

package/dist/tasks/validator.js

@@ -10,15 +10,17 @@
  *   • the asset/file source exists (prompt targets)
  *   • the selected engine resolves (prompt targets)
  *
- * Validation is deliberately split from parsing: callers that only want to
- * read frontmatter (e.g. `tasks list`) can skip these checks, while
- * `tasks add` and `tasks run` should always run them.
+ * Validation is deliberately split from parsing: callers that only inspect
+ * task metadata (e.g. `akm show`) can skip these checks, while
+ * `task add` and `task run` should always run them.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { placementSpecFor } from "../core/asset/asset-placement.js";
 import { parseRefInput } from "../core/asset/resolve-ref.js";
 import { loadConfig } from "../core/config/config.js";
 import { NotFoundError } from "../core/errors.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, withEngineFallback } from "../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../integrations/agent/engine-resolution.js";
 import { resolveAssetPath } from "../sources/resolve.js";
 import { parseSchedule } from "./schedule.js";
@@ -39,12 +41,15 @@ export async function validateTaskDocument(task, options) {
     }
     // Prompt target. Resolve the engine unconditionally — when no engine is
     // set on the task, defaults.engine is required. Catching this at
-    // `tasks add` / `tasks sync` time is much more useful than failing only
+    // `task add` / `task sync` time is much more useful than failing only
     // when the OS scheduler fires.
-    const config = loadConfig();
+    // Resolve against the SAME effective config the runner will use
+    // (`tasks/runner.ts`), or validation rejects at `task add` / `task sync` a
+    // task the runner would have happily executed via the implicit fallback.
+    const { config } = withEngineFallback(loadConfig());
     const engine = task.target.engine ?? config.defaults?.engine;
     if (!engine)
-        throw new NotFoundError(`Task "${task.id}" has no selected engine.`, "ASSET_NOT_FOUND");
+        throw new NotFoundError(`Task "${task.id}" ${NO_ENGINE_MESSAGE_SUFFIX}`, "ASSET_NOT_FOUND");
     const resolved = resolveEngine(engine, config);
     if (task.target.llm !== undefined && resolved.kind !== "llm") {
         throw new NotFoundError(`Task "${task.id}" uses llm overrides with non-LLM engine "${engine}".`, "ASSET_NOT_FOUND");
@@ -53,6 +58,15 @@ export async function validateTaskDocument(task, options) {
     if (src.kind === "asset") {
         const stashDir = options.stashDir;
         const ref = parseRefInput(src.ref);
+        // D11 — `parseRefInput` now also accepts an opaque adapter conceptId (a
+        // ref whose leading segment is not an AKM placement dir), but
+        // `resolveAssetPath` (src/sources/resolve.ts) is placement-dir-only: it
+        // has no stash-subdir to route an opaque type through. Surface a clean
+        // domain error here rather than let that helper crash on a missing
+        // directory mapping.
+        if (placementSpecFor(ref.type) === undefined) {
+            throw new NotFoundError(`Task "${task.id}" prompt asset ref "${src.ref}" is not an AKM-placed asset — adapter-owned (opaque) prompt sources are not resolvable as task inputs yet.`, "ASSET_NOT_FOUND");
+        }
         await resolveAssetPath(stashDir, ref.type, ref.name);
     }
     else if (src.kind === "file") {