akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.7

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 { 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,20 +44,18 @@ export const SCHEDULED_TASK_CONTEXT_KEYS = [
     "AKM_STATE_DIR",
 ];
 /**
- * Directories a descriptor carries ONLY when the process that ran `task sync`
- * had them set explicitly in its environment. They are never resolved from
- * defaults: a descriptor written 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. At fire time an absent key resolves exactly as it does for an
- * interactive command on the same host.
+ * 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 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.
+ * 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 = {};
@@ -42,141 +66,112 @@ export function scheduledTaskContextEnv(env = process.env) {
     }
     return out;
 }
-export const SCHEDULER_CONTEXT_ARG = "--scheduler-context";
 /**
- * The directory context a scheduler descriptor carries: the resolved bundle
- * path, plus whichever `AKM_*_DIR` overrides the syncing process had set
- * explicitly. Resolved defaults are deliberately not captured — see
- * {@link EXPLICIT_CONTEXT_KEYS}.
+ * 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 resolveScheduledTaskContext(env = process.env) {
-    const context = { AKM_BUNDLE_DIR: path.resolve(resolveStashDir(env)) };
+export function scheduledRowEnvironment(env = process.env) {
+    const out = {};
+    try {
+        out.AKM_BUNDLE_DIR = path.resolve(resolveStashDir(env));
+    }
+    catch {
+        // No working stash: there is no primary bundle to attribute rows to either.
+    }
     for (const key of EXPLICIT_CONTEXT_KEYS) {
         const value = env[key]?.trim();
         if (value)
-            context[key] = path.resolve(value);
+            out[key] = path.resolve(value);
     }
-    return canonicalContext(context);
-}
-/** 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()) {
-    return { version: 1, environment: canonicalContext(context) };
-}
-export function schedulerContextPath(descriptor) {
-    const bytes = serializeDescriptor(descriptor);
-    const digest = createHash("sha256").update(bytes).digest("hex");
-    // The descriptor lives under the data directory it names when it names
-    // one, otherwise under this process's own.
-    return path.join(getTaskContextDir({ ...process.env, ...descriptor.environment }), `${digest}.json`);
+    return out;
 }
-/** 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 });
+/** 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 file;
+    return entries;
 }
-export function loadSchedulerContextDescriptor(file, env = process.env) {
-    const descriptor = validateSchedulerContextDescriptor(file);
+/** 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 = descriptor.environment[key];
-        if (value !== undefined)
-            env[key] = value;
+        const value = variables[key];
+        if (value)
+            out[key] = value;
     }
-    if (descriptor.environment.PATH !== undefined)
-        env.PATH = descriptor.environment.PATH;
+    return Object.keys(out).length > 0 ? out : undefined;
 }
-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));
+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");
+    }
+    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 canonicalDescriptor(parsed);
+    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);
@@ -184,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])
@@ -308,88 +282,6 @@ function isValidSchedulerInputFlagTail(tail) {
     }
     return true;
 }
-function canonicalContext(input) {
-    if (Object.keys(input).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 (value === undefined) {
-            if (key === "AKM_BUNDLE_DIR")
-                throw invalidSchedulerContext();
-            continue;
-        }
-        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 { PATH, ...rawContext } = rawEnvironment;
-    const context = canonicalContext(rawContext);
-    return {
-        version: 1,
-        environment: PATH === undefined ? context : { ...context, PATH: validatePathValue(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 invalidSchedulerContext() {
-    return new ConfigError("Invalid scheduler context; expected AKM_BUNDLE_DIR as an absolute path, " +
-        `optionally with ${EXPLICIT_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-sync.js

@@ -263,9 +263,10 @@ export function scheduledInvocationBundle(invocation) {
 /**
  * The scope that owns an installed row, or none. A row written before
  * `--bundle` existed names no bundle and belongs to the primary scope
- * unless its descriptor says otherwise; a row that names a bundle belongs
- * to the scope of that name — for the primary scope only when its
- * descriptor also proves the path.
+ * unless the bundle path it carries says otherwise; a row that names a
+ * bundle belongs to the scope of that name — for the primary scope only
+ * when its `AKM_BUNDLE_DIR` (inline, or in an older row's descriptor) also
+ * proves the path.
  */
 export function installedRowScope(row, scopes) {
     const bundle = row.target ?? scheduledInvocationBundle(row.invocation);
@@ -393,12 +394,13 @@ export function planSchedulerSync(input) {
         failures: Object.freeze(failures),
     });
 }
-/** An installed row keeps its own launcher unless `rebind`; the descriptor always follows the current policy. */
+/** An installed row keeps its own launcher unless `rebind`; its environment always follows the current policy. */
 function installOptionsFor(input, current) {
     if (current && !input.rebind) {
+        const environment = input.installOptions?.environment ?? current.environment;
         return Object.freeze({
             binding: Object.freeze([...current.binding]),
-            contextPath: input.installOptions?.contextPath ?? current.contextPath,
+            ...(environment !== undefined ? { environment } : {}),
         });
     }
     return input.installOptions ? Object.freeze({ ...input.installOptions }) : undefined;
@@ -417,9 +419,12 @@ function installedRowRef(row, scope) {
 /** Where an installed row was scheduled from, for messages. */
 export function installedRowOwner(row) {
     const bundle = row.target ?? scheduledInvocationBundle(row.invocation);
-    if (row.ownerBundlePath)
-        return `the bundle at ${JSON.stringify(row.ownerBundlePath)}`;
-    return bundle ? `bundle ${JSON.stringify(bundle)}` : "an installation this sync cannot attribute";
+    const installation = row.ownerBundlePath
+        ? `the installation whose working stash is ${JSON.stringify(row.ownerBundlePath)}`
+        : undefined;
+    if (bundle)
+        return installation ? `bundle ${JSON.stringify(bundle)} of ${installation}` : `bundle ${JSON.stringify(bundle)}`;
+    return installation ?? "an installation this sync cannot attribute";
 }
 function foreignRowMessage(nativeId, row) {
     return `Scheduler id ${JSON.stringify(nativeId)} is already scheduled from ${installedRowOwner(row)}; desired source ids must not collide across bundles. Leaving it out of this sync.`;