akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/tasks/scheduler-invocation.js

@@ -1,13 +1,39 @@
 // 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";
+/**
+ * How a native scheduler row invokes akm.
+ *
+ * A row is `<launcher…> task run <id> --bundle <bundle> --scheduled
+ * [--<input> <value>…]`, or `<launcher…> workflow run <qualified-ref>`, and it
+ * carries its own context: the environment the scheduled process needs,
+ * set inline by the row itself (a cron `VAR=value` prefix, a launchd
+ * `EnvironmentVariables` entry, a PowerShell `$env:` assignment).
+ *
+ *   - `AKM_BUNDLE_DIR`: the working stash of the process that ran
+ *     `akm task sync`, on every row. The scheduled run uses the same working
+ *     stash, `--bundle <name>` finds a stash no config names, and sync
+ *     attributes the row to the installation that wrote it (#846).
+ *   - `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` and `AKM_STATE_DIR`
+ *     only when the process that ran `akm task sync` set them explicitly. A
+ *     default resolves at fire time exactly as it does for an interactive
+ *     command.
+ *
+ * That is exactly what the `--scheduler-context` descriptor held.
+ *
+ * `PATH` is the scheduler's own: the crontab's `# akm:env` block, the plist's
+ * `EnvironmentVariables`.
+ *
+ * Rows written by 0.9.0 through 0.9.17-alpha.6 name a
+ * `--scheduler-context <descriptor>` file instead. The CLI still accepts that
+ * argument and applies the file's environment, so such a row keeps firing
+ * until the next `akm task sync` rewrites it.
+ */
 import fs from "node:fs";
 import path from "node:path";
 import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { resolveStashDir } from "../core/common.js";
 import { ConfigError } from "../core/errors.js";
-import { getCacheDir, getConfigDir, getDataDir, getTaskContextDir } from "../core/paths.js";
 import { INPUT_NAME_PATTERN } from "../execution/input-contract.js";
 import { normaliseTaskConceptId } from "./task-id.js";
 export const SCHEDULED_TASK_CONTEXT_KEYS = [
@@ -18,9 +44,18 @@ export const SCHEDULED_TASK_CONTEXT_KEYS = [
     "AKM_STATE_DIR",
 ];
 /**
- * The AKM directory context currently restored from a scheduler descriptor.
- * Child environments that are built from an allowlist must forward this
- * closed set explicitly so nested AKM commands stay in the same installation.
+ * Directories a row carries ONLY when the process that ran `task sync` had
+ * them set explicitly in its environment. They are never resolved from
+ * defaults: a sync run from inside an app whose environment pointed `$STATE`
+ * somewhere private (an OpenCode desktop session, 2026-08 → 2026-09) froze
+ * that directory into eight cron rows, and the scheduled improve runs then
+ * held their locks in a `locks/` directory no interactive command could see.
+ */
+const EXPLICIT_CONTEXT_KEYS = ["AKM_CONFIG_DIR", "AKM_DATA_DIR", "AKM_CACHE_DIR", "AKM_STATE_DIR"];
+/**
+ * The AKM directory context of the current process. Child environments that
+ * are built from an allowlist must forward this closed set explicitly so
+ * nested AKM commands stay in the same installation.
  */
 export function scheduledTaskContextEnv(env = process.env) {
     const out = {};
@@ -31,134 +66,112 @@ export function scheduledTaskContextEnv(env = process.env) {
     }
     return out;
 }
-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 an installed argv from one already-validated public scheduler tail. */
-export function buildScheduledBindingInvocation(akmArgv, contextPath, invocation) {
-    const parsed = parsePublicSchedulerInvocation(invocation);
-    if (!parsed)
-        throw invalidSchedulerInvocation();
-    return {
-        argv: [...akmArgv, SCHEDULER_CONTEXT_ARG, assertAbsolutePath(contextPath), ...parsed.invocation],
-    };
-}
-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`);
+/**
+ * The environment every row a sync writes sets inline: `AKM_BUNDLE_DIR`,
+ * the syncing process's working stash, plus whichever `AKM_*_DIR` overrides
+ * it set explicitly. With no working stash to resolve (no default bundle, no
+ * `AKM_BUNDLE_DIR`), rows name their bundle by `--bundle` alone.
+ */
+export function scheduledRowEnvironment(env = process.env) {
+    const out = {};
     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);
+        out.AKM_BUNDLE_DIR = path.resolve(resolveStashDir(env));
+    }
+    catch {
+        // No working stash: there is no primary bundle to attribute rows to either.
     }
-    finally {
-        fs.rmSync(temp, { force: true });
+    for (const key of EXPLICIT_CONTEXT_KEYS) {
+        const value = env[key]?.trim();
+        if (value)
+            out[key] = path.resolve(value);
     }
-    return file;
+    return out;
 }
-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;
+/** A row environment's entries, in {@link SCHEDULED_TASK_CONTEXT_KEYS} order. */
+export function scheduledRowEnvironmentEntries(environment) {
+    const entries = [];
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = environment?.[key];
+        if (value)
+            entries.push([key, value]);
+    }
+    return entries;
 }
-export function validateSchedulerContextDescriptor(file) {
-    const absolute = assertAbsolutePath(file);
-    let linkStat;
-    try {
-        linkStat = fs.lstatSync(absolute);
+/** Keep the {@link SCHEDULED_TASK_CONTEXT_KEYS} a parsed row set; `undefined` when there are none. */
+export function scheduledRowEnvironmentFrom(variables) {
+    const out = {};
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = variables[key];
+        if (value)
+            out[key] = value;
     }
-    catch (error) {
-        throw schedulerContextFileError(absolute, error instanceof Error ? error.message : String(error));
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+const SCHEDULER_CONTEXT_ARG = "--scheduler-context";
+/** The installed argv: the launcher, then one already-validated public scheduler tail. */
+export function buildScheduledInvocation(akmArgv, invocation) {
+    const parsed = parsePublicSchedulerInvocation(invocation);
+    if (!parsed)
+        throw invalidSchedulerInvocation();
+    return [...akmArgv, ...parsed.invocation];
+}
+/**
+ * Parse an installed row's argv (after any inline environment): the current
+ * shape, the `--scheduler-context <descriptor>` shape 0.9.0 – 0.9.17-alpha.6
+ * wrote, or the bare shape before that. A row that carries
+ * `--scheduler-context` but does not parse around it is never reread as
+ * another shape.
+ */
+export function parseScheduledInvocationArgv(argv) {
+    const contextIndex = argv.indexOf(SCHEDULER_CONTEXT_ARG);
+    if (contextIndex !== -1) {
+        if (contextIndex < 1 || argv.indexOf(SCHEDULER_CONTEXT_ARG, contextIndex + 1) !== -1)
+            return undefined;
+        const contextPath = argv[contextIndex + 1];
+        if (!contextPath)
+            return undefined;
+        const publicInvocation = parsePublicSchedulerInvocation(argv.slice(contextIndex + 2));
+        if (!publicInvocation)
+            return undefined;
+        return { binding: argv.slice(0, contextIndex), contextPath, ...publicInvocation };
     }
-    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");
-            }
+    for (let index = 1; index < argv.length - 1; index += 1) {
+        if ((argv[index] === "task" || argv[index] === "workflow") && argv[index + 1] === "run") {
+            const publicInvocation = parsePublicSchedulerInvocation(argv.slice(index));
+            return publicInvocation ? { binding: argv.slice(0, index), ...publicInvocation } : undefined;
         }
-        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");
     }
+    return undefined;
+}
+/**
+ * The environment a `--scheduler-context` descriptor names: its `AKM_*_DIR`
+ * keys and, in one written before 0.9.17, `PATH`. It is read as plain JSON —
+ * the file is this user's own, next to the data it names.
+ */
+export function readLegacySchedulerContext(file) {
     let parsed;
     try {
-        parsed = JSON.parse(descriptorBytes.toString("utf8"));
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
     }
     catch (error) {
-        throw schedulerContextFileError(absolute, error instanceof Error ? error.message : String(error));
+        throw new ConfigError(`Cannot read scheduler context "${file}": ${error instanceof Error ? error.message : String(error)}. ` +
+            "Run `akm task sync` to rewrite this scheduled row.", "INVALID_CONFIG_FILE");
     }
-    return canonicalDescriptor(parsed);
+    const environment = parsed !== null && typeof parsed === "object" ? parsed.environment : undefined;
+    const out = {};
+    if (environment === null || typeof environment !== "object")
+        return out;
+    for (const key of [...SCHEDULED_TASK_CONTEXT_KEYS, "PATH"]) {
+        const value = environment[key];
+        if (typeof value === "string" && value.length > 0)
+            out[key] = value;
+    }
+    return out;
 }
-/** Load and remove the hidden descriptor argument before citty parses argv. */
+/**
+ * Apply and remove a row's `--scheduler-context <descriptor>` before citty
+ * parses argv. Only a row written by 0.9.0 – 0.9.17-alpha.6 passes it.
+ */
 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);
@@ -166,37 +179,16 @@ export function consumeSchedulerContextArg(argv, env = process.env) {
         return argv;
     const file = argv[index + 1];
     if (!file) {
-        throw new ConfigError(`${SCHEDULER_CONTEXT_ARG} requires an absolute descriptor path.`, "INVALID_CONFIG_FILE");
+        throw new ConfigError(`${SCHEDULER_CONTEXT_ARG} requires a descriptor path.`, "INVALID_CONFIG_FILE");
     }
-    loadSchedulerContextDescriptor(file, env);
+    Object.assign(env, readLegacySchedulerContext(file));
     return [...argv.slice(0, index), ...argv.slice(index + 2)];
 }
-/** Parse either the public scheduled task or qualified workflow invocation. */
-export function parseScheduledBindingArgv(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];
-    if (!contextPath)
-        return undefined;
-    const publicInvocation = parsePublicSchedulerInvocation(argv.slice(contextIndex + 2));
-    if (!publicInvocation)
-        return undefined;
-    return {
-        binding: [...argv.slice(0, contextIndex)],
-        contextPath: assertAbsolutePath(contextPath),
-        invocation: publicInvocation.invocation,
-        ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
-    };
-}
 /**
- * Parse just the public `task run …` / `workflow run …` tail, with no
- * `--scheduler-context` wrapper. Exported so a backend can recognize a
- * pre-`--scheduler-context` invocation still sitting inside akm's own
- * ownership-marked block (see `extractCronInvocation` in
- * `src/tasks/backends/cron.ts`) without re-implementing this grammar.
+ * Parse just the public `task run …` / `workflow run …` tail, the part of a
+ * row that names what it runs.
  */
-export function parsePublicSchedulerInvocation(invocation) {
+function parsePublicSchedulerInvocation(invocation) {
     if (invocation[0] === "task" && invocation[1] === "run" && invocation[2]) {
         try {
             if (normaliseTaskConceptId(invocation[2]) !== invocation[2])
@@ -290,106 +282,6 @@ function isValidSchedulerInputFlagTail(tail) {
     }
     return true;
 }
-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");
-}
 function invalidSchedulerInvocation() {
     return new ConfigError("Invalid scheduler invocation; expected public " +
         "`task run <id> [--bundle <bundle>] --scheduled [--<input> <value>…]` or `workflow run <qualified-ref>` argv.", "INVALID_CONFIG_FILE");

package/dist/tasks/scheduler-lock.js

@@ -0,0 +1,53 @@
+// 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/.
+/**
+ * The one process lock around native scheduler writes.
+ *
+ * `task sync|add|enable|disable|prune --yes` read the installed rows, plan,
+ * and apply under it, so two akm processes never interleave their writes to
+ * the same crontab or LaunchAgents directory. It is an `O_EXCL` lock file
+ * under `$STATE/locks`, reclaimed only from a verifiably dead holder, and
+ * re-entrant within one process (`add` runs `sync` inside it).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { TransientError } from "../core/errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { getStateDir } from "../core/paths.js";
+export function schedulerLockPath() {
+    return path.join(getStateDir(), "locks", "scheduler.lock");
+}
+let depth = 0;
+export async function withSchedulerLock(fn) {
+    if (depth > 0) {
+        depth += 1;
+        try {
+            return await fn();
+        }
+        finally {
+            depth -= 1;
+        }
+    }
+    const lockPath = schedulerLockPath();
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const acquire = () => tryAcquireLockSync(lockPath, createLockPayload({ purpose: "scheduler" }));
+    let ownership = acquire();
+    if (!ownership) {
+        const probe = probeLock(lockPath);
+        if (probe.state === "absent" || (probe.state === "stale" && reclaimStaleLock(lockPath, probe))) {
+            ownership = acquire();
+        }
+    }
+    if (!ownership) {
+        throw new TransientError("Another akm process is syncing the scheduler right now.", "SCHEDULER_LOCK_HELD");
+    }
+    depth = 1;
+    try {
+        return await fn();
+    }
+    finally {
+        depth = 0;
+        releaseLock(ownership);
+    }
+}