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

package/dist/tasks/schedule.js

@@ -15,9 +15,9 @@
  *   • a launchd plist `<StartCalendarInterval>` / `<StartInterval>` (macOS),
  *   • Task Scheduler XML triggers (Windows).
  *
- * The shared subset is `*`, single integers, `*\/N`, plus the `@hourly /
+ * The shared subset is `*`, single integers, `*\/N`, `A-B/N`, plus the `@hourly /
  * @daily / @weekly / @monthly` aliases. Patterns outside that — multi-value
- * lists, ranges, step values other than `*\/N`, day-of-month AND
+ * lists, plain ranges, day-of-month AND
  * day-of-week combinations — are rejected with a {@link UsageError}.
  *
  * Cron is the most permissive of the three backends; some patterns it
@@ -41,9 +41,9 @@ const FIELD_LIMITS = {
     month: { min: 1, max: 12 },
     dow: { min: 0, max: 6 },
 };
-const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), step-on-star (`*/N`), and comma lists (`7,37`). " +
+const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), steps (`*/N`, `A-B/N`), and comma lists (`7,37`). " +
     "Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`. " +
-    "Lists, ranges, and named days/months are not supported.";
+    "Plain ranges and named days/months are not supported.";
 export function parseSchedule(input, backend) {
     const cron = expandAlias(input);
     const fields = parseCronFields(cron, input);
@@ -99,6 +99,16 @@ function parseField(raw, name, limit, original) {
         }
         return { kind: "step", step };
     }
+    const rangeStepMatch = raw.match(/^(\d+)-(\d+)\/(\d+)$/);
+    if (rangeStepMatch) {
+        const start = Number(rangeStepMatch[1]);
+        const end = Number(rangeStepMatch[2]);
+        const step = Number(rangeStepMatch[3]);
+        if (start < limit.min || end > limit.max || start > end || step <= 0) {
+            throw new UsageError(`Invalid ${name} range-step "${raw}" in schedule "${original}" (allowed ${limit.min}-${limit.max}).`, "INVALID_FLAG_VALUE");
+        }
+        return { kind: "rangeStep", start, end, step };
+    }
     if (/^\d+$/.test(raw)) {
         const value = Number(raw);
         if (value < limit.min || value > limit.max) {
@@ -128,22 +138,28 @@ export function translateToCron(spec) {
 }
 export function translateToLaunchd(spec) {
     const f = spec.fields;
-    // `*/N` minute (everything else `*`) → StartInterval = N*60 seconds.
-    if (f.minute.kind === "step" &&
+    rejectDomDowCombination(spec, "macOS launchd");
+    // Expand minute steps into clock-minute anchors. StartInterval would drift
+    // from cron whenever the agent is loaded away from a matching boundary.
+    if ((f.minute.kind === "step" || f.minute.kind === "rangeStep") &&
         f.hour.kind === "star" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { intervalSeconds: f.minute.step * 60 };
+        return { calendars: expandFieldValues(f.minute, FIELD_LIMITS.minute).map((Minute) => ({ Minute })) };
     }
-    // `*/N` hour → StartInterval = N*3600.
+    // Likewise, anchor hour steps to the same hours cron selects each day.
     if (f.minute.kind === "value" &&
-        f.minute.value === 0 &&
-        f.hour.kind === "step" &&
+        (f.hour.kind === "step" || f.hour.kind === "rangeStep") &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { intervalSeconds: f.hour.step * 3600 };
+        return {
+            calendars: expandFieldValues(f.hour, FIELD_LIMITS.hour).map((Hour) => ({
+                Minute: f.minute.kind === "value" ? f.minute.value : 0,
+                Hour,
+            })),
+        };
     }
     // Otherwise build a calendar dict from concrete values. launchd treats any
     // omitted key as "every value", so a `*` field translates to "no key".
@@ -166,39 +182,101 @@ export function translateToLaunchd(spec) {
     if (f.dow.kind === "value")
         calendar.Weekday = f.dow.value;
     // launchd's CalendarInterval requires at least one specific key. If every
-    // field is `*` the schedule has no anchor and we'd need a StartInterval
-    // instead — treat this as "every minute".
+    // Expand every-minute to explicit minute boundaries rather than a
+    // load-relative 60-second interval.
     if (Object.keys(calendar).length === 0) {
-        return { intervalSeconds: 60 };
+        return {
+            calendars: expandFieldValues({ kind: "step", step: 1 }, FIELD_LIMITS.minute).map((Minute) => ({ Minute })),
+        };
     }
     return { calendar };
 }
+function expandFieldValues(field, limit) {
+    const start = field.kind === "rangeStep" ? field.start : limit.min;
+    const end = field.kind === "rangeStep" ? field.end : limit.max;
+    const values = [];
+    for (let value = start; value <= end; value += field.step)
+        values.push(value);
+    return values;
+}
 function rejectStepInsideCalendar(field, name, spec) {
     if (field.kind === "step") {
         throw new UsageError(`Schedule "${spec.raw}" uses step (${name} = */N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either restrict the step to the minute or hour field only, or rewrite the schedule with concrete values.");
     }
+    if (field.kind === "rangeStep") {
+        throw new UsageError(`Schedule "${spec.raw}" uses range-step (${name} = A-B/N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Restrict the range-step to the minute or hour field, or rewrite the schedule with a concrete value.");
+    }
     if (field.kind === "list") {
         throw new UsageError(`Schedule "${spec.raw}" uses comma list (${name} = a,b,...) which macOS launchd cannot express as a single trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either install one task per list element, or rewrite the schedule with a step (`*/N`) or single value.");
     }
 }
+const MAX_SCHTASKS_TRIGGERS = 48;
 export function translateToSchtasks(spec) {
     const f = spec.fields;
-    // `*/N` minute → MINUTE, every N.
+    rejectDomDowCombination(spec, "Windows Task Scheduler");
+    // A repetition interval is cron-equivalent indefinitely only when it divides
+    // the field's wall-clock cycle. Other steps must reset at every hour.
     if (f.minute.kind === "step" &&
         f.hour.kind === "star" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
+        if (60 % f.minute.step !== 0) {
+            return minuteValuesTrigger(expandFieldValues(f.minute, FIELD_LIMITS.minute), spec);
+        }
         return { kind: "minute", everyMinutes: f.minute.step };
     }
-    // `0 */N * * *` → HOURLY, every N.
+    if (f.minute.kind === "rangeStep" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        if (f.minute.start === FIELD_LIMITS.minute.min && f.minute.end === FIELD_LIMITS.minute.max) {
+            if (60 % f.minute.step === 0)
+                return { kind: "minute", everyMinutes: f.minute.step };
+        }
+        return minuteValuesTrigger(expandFieldValues(f.minute, FIELD_LIMITS.minute), spec);
+    }
+    // Fixed-minute hour schedules can use one daily-reset repetition only when
+    // the interval divides 24 hours. Non-divisors become explicit daily times.
     if (f.minute.kind === "value" &&
-        f.minute.value === 0 &&
         f.hour.kind === "step" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
         f.dow.kind === "star") {
-        return { kind: "hour", everyHours: f.hour.step };
+        if (24 % f.hour.step === 0 && f.hour.step < 24) {
+            return { kind: "hour", everyHours: f.hour.step, atMinute: f.minute.value };
+        }
+        return {
+            kind: "hourValues",
+            hours: expandFieldValues(f.hour, FIELD_LIMITS.hour),
+            atMinute: f.minute.value,
+        };
+    }
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "rangeStep" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        if (f.hour.start === FIELD_LIMITS.hour.min && f.hour.end === FIELD_LIMITS.hour.max) {
+            if (24 % f.hour.step === 0 && f.hour.step < 24) {
+                return { kind: "hour", everyHours: f.hour.step, atMinute: f.minute.value };
+            }
+        }
+        return {
+            kind: "hourValues",
+            hours: expandFieldValues(f.hour, FIELD_LIMITS.hour),
+            atMinute: f.minute.value,
+        };
+    }
+    // `M * * * *` includes the shipped top-of-hour task and arbitrary fixed
+    // minutes. A daily calendar trigger resets the hourly repetition each day.
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { kind: "hour", everyHours: 1, atMinute: f.minute.value };
     }
     // `M H * * *` → DAILY at H:M.
     if (f.minute.kind === "value" &&
@@ -221,7 +299,18 @@ export function translateToSchtasks(spec) {
             daysOfWeek: [f.dow.value],
         };
     }
-    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: */N minutes, every N hours (0 */N * * *), daily at HH:MM, or weekly on a single weekday.");
+    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: minute steps/range-steps, fixed-minute hour steps/range-steps, hourly, daily, or weekly on a single weekday.");
+}
+function minuteValuesTrigger(minutes, spec) {
+    if (minutes.length > MAX_SCHTASKS_TRIGGERS) {
+        throw new UsageError(`Schedule "${spec.raw}" requires ${minutes.length} native triggers; Windows Task Scheduler allows at most ${MAX_SCHTASKS_TRIGGERS}.`, "INVALID_FLAG_VALUE", "Use a full-field step whose interval divides 60, or reduce the minute range.");
+    }
+    return { kind: "minuteValues", minutes };
+}
+function rejectDomDowCombination(spec, backend) {
+    if (spec.fields.dom.kind !== "star" && spec.fields.dow.kind !== "star") {
+        throw new UsageError(`Schedule "${spec.raw}": day-of-month and day-of-week use OR semantics in cron, which ${backend} cannot express portably.`, "INVALID_FLAG_VALUE", "Use either day-of-month or day-of-week, but not both.");
+    }
 }
 /** Human-readable summary used by `tasks doctor`. */
 export const SCHEDULE_SUPPORTED_SUBSET_HINT = SUPPORTED_HINT;

package/dist/tasks/scheduler-invocation.js

@@ -0,0 +1,296 @@
+// 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, getTaskContextDir } from "../core/paths.js";
+export const SCHEDULED_TASK_CONTEXT_KEYS = [
+    "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_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)),
+        // 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.
+ *
+ * `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,
+            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) {
+    const inputKeys = Object.keys(input);
+    if (inputKeys.length !== SCHEDULED_TASK_CONTEXT_KEYS.length ||
+        inputKeys.some((key) => !SCHEDULED_TASK_CONTEXT_KEYS.includes(key))) {
+        throw invalidSchedulerContext();
+    }
+    const context = {};
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = input[key];
+        if (typeof value !== "string" ||
+            value.trim().length === 0 ||
+            containsControlCharacter(value) ||
+            (!path.posix.isAbsolute(value) && !path.win32.isAbsolute(value))) {
+            throw invalidSchedulerContext();
+        }
+        context[key] = value;
+    }
+    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;
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function resolveStateDir(env, platform) {
+    const override = env.AKM_STATE_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "state");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "state");
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "..", "Local", "akm", "state");
+        throw new ConfigError("Unable to determine state directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, "akm");
+    const home = env.HOME?.trim();
+    return home ? path.join(home, ".local", "state", "akm") : path.join("/tmp", "akm-state");
+}
+function invalidSchedulerContext() {
+    return new ConfigError(`Invalid scheduler context; expected exactly ${SCHEDULED_TASK_CONTEXT_KEYS.join(", ")} as absolute paths.`, "INVALID_CONFIG_FILE");
+}

package/dist/tasks/schema.js

@@ -12,4 +12,4 @@
  * Tasks are stored as pure YAML files at `<stash>/tasks/<id>.yml`. Multi-line
  * inline prompts use a YAML block scalar (`prompt: |`).
  */
-export const TASK_SCHEMA_VERSION = 1;
+export const TASK_SCHEMA_VERSION = 2;

package/dist/tasks/task-id.js

@@ -0,0 +1,35 @@
+// 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 { UsageError } from "../core/errors.js";
+const VALID_TASK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TASK_FILE_SUFFIX_RE = /\.(?:yml|yaml)$/i;
+const WINDOWS_RESERVED_DEVICE_RE = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i;
+const WINDOWS_TASK_PATH_MAX_LENGTH = 238;
+const WINDOWS_TASK_FOLDER_PREFIX_LENGTH = "\\akm\\".length;
+const PORTABLE_FILENAME_COMPONENT_MAX_LENGTH = 255;
+const LAUNCHD_FILENAME_OVERHEAD = "com.akm.task.".length + ".plist".length;
+const TASK_FILENAME_OVERHEAD = ".yml".length;
+const SCHTASKS_TEMP_FILENAME_OVERHEAD = "akm-task-".length + "-".length + 13 + ".xml".length;
+export const MAX_PORTABLE_TASK_ID_LENGTH = Math.min(WINDOWS_TASK_PATH_MAX_LENGTH - WINDOWS_TASK_FOLDER_PREFIX_LENGTH, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - LAUNCHD_FILENAME_OVERHEAD, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - TASK_FILENAME_OVERHEAD, PORTABLE_FILENAME_COMPONENT_MAX_LENGTH - SCHTASKS_TEMP_FILENAME_OVERHEAD);
+export function validateTaskId(id) {
+    if (!id) {
+        throw new UsageError("Task id must be non-empty.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!VALID_TASK_ID_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" is invalid. Use letters, digits, dots, underscores, and dashes only.`, "INVALID_FLAG_VALUE");
+    }
+    if (id.length > MAX_PORTABLE_TASK_ID_LENGTH) {
+        throw new UsageError(`Task id "${id}" is invalid. Use at most ${MAX_PORTABLE_TASK_ID_LENGTH} characters for all supported schedulers.`, "INVALID_FLAG_VALUE");
+    }
+    if (TASK_FILE_SUFFIX_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" is invalid. Use the bare task id without a .yml or .yaml suffix.`, "INVALID_FLAG_VALUE");
+    }
+    if (WINDOWS_RESERVED_DEVICE_RE.test(id)) {
+        throw new UsageError(`Task id "${id}" uses a reserved Windows device name. Choose a different task id.`, "INVALID_FLAG_VALUE");
+    }
+    return id;
+}
+export function normaliseTaskId(raw) {
+    return validateTaskId(raw.trim());
+}

package/dist/tasks/validator.js

@@ -8,27 +8,27 @@
  *   • the schedule is parseable and translates to the active backend
  *   • the workflow ref resolves (workflow targets)
  *   • the asset/file source exists (prompt targets)
- *   • the agent profile resolves (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 { parseAssetRef } from "../core/asset/asset-ref.js";
-import { resolveStashDir } from "../core/common.js";
+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 { requireAgentProfile } from "../integrations/agent/index.js";
+import { resolveEngine } from "../integrations/agent/engine-resolution.js";
 import { resolveAssetPath } from "../sources/resolve.js";
 import { parseSchedule } from "./schedule.js";
 export async function validateTaskDocument(task, options) {
     // Schedule must parse and translate.
     parseSchedule(task.schedule, options.backend);
     if (task.target.kind === "workflow") {
-        const stashDir = options.stashDir ?? resolveStashDir();
-        const ref = parseAssetRef(task.target.ref);
+        const stashDir = options.stashDir;
+        const ref = parseRefInput(task.target.ref);
         if (ref.type !== "workflow") {
             throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
         }
@@ -38,17 +38,31 @@ export async function validateTaskDocument(task, options) {
     if (task.target.kind !== "prompt") {
         return;
     }
-    // Prompt target. Resolve the profile unconditionally — when no profile is
-    // set on the task, requireAgentProfile falls back to defaults.agent and
-    // throws a clear error if neither is configured. Catching this at
-    // `tasks add` / `tasks sync` time is much more useful than failing only
+    // Prompt target. Resolve the engine unconditionally — when no engine is
+    // set on the task, defaults.engine is required. Catching this at
+    // `task add` / `task sync` time is much more useful than failing only
     // when the OS scheduler fires.
     const config = loadConfig();
-    requireAgentProfile(config, task.target.profile);
+    const engine = task.target.engine ?? config.defaults?.engine;
+    if (!engine)
+        throw new NotFoundError(`Task "${task.id}" has no selected engine.`, "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");
+    }
     const src = task.target.source;
     if (src.kind === "asset") {
-        const stashDir = options.stashDir ?? resolveStashDir();
-        const ref = parseAssetRef(src.ref);
+        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") {