akm-cli 0.8.6 → 0.8.14

package/dist/commands/tasks/default-tasks.js

@@ -0,0 +1,173 @@
+// 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/.
+/**
+ * Default scheduled-task set for the improve pipeline (issue #552).
+ *
+ * Ships a well-tuned multi-cadence task set so a typical single-developer
+ * install is correct with zero manual config. Registration is **idempotent**:
+ * running `akm setup` / `akm tasks init` twice yields the same task set with no
+ * duplicates. Each default task is a shell-command task (`akm improve --profile
+ * <name>`), so the profile is overridable in `config.json` without editing the
+ * task definition.
+ *
+ * The OS-scheduler-touching primitives (`add` / `setEnabled` / `list`) are
+ * injected via {@link RegisterDefaultTasksDeps} so tests can supply fakes and
+ * never mutate the host scheduler or a real stash — mirroring the
+ * dependency-injection pattern used by `stepScheduledTasks` in setup.ts.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import { akmTasksAdd, akmTasksList } from "./tasks.js";
+/**
+ * The canonical default improve task set. `update-stashes` is deliberately NOT
+ * listed here — it ships as an embedded core template and is left unchanged.
+ */
+export const DEFAULT_IMPROVE_TASKS = [
+    {
+        id: "akm-improve-frequent",
+        profile: "frequent",
+        command: "akm improve --profile frequent --auto-accept safe",
+        schedule: "0 * * * *",
+        description: "Frequent extract + inference pass (every 60 min)",
+        enableMode: "always",
+    },
+    {
+        id: "akm-improve-consolidate",
+        profile: "consolidate",
+        command: "akm improve --profile consolidate --auto-accept safe",
+        schedule: "0 */4 * * *",
+        description: "Consolidation-only pass (every 4h)",
+        enableMode: "always",
+    },
+    {
+        id: "akm-improve-nightly",
+        profile: "thorough",
+        command: "akm improve --profile thorough --auto-accept safe",
+        schedule: "0 2 * * *",
+        description: "Full nightly quality sweep (daily 2am)",
+        enableMode: "server",
+    },
+    {
+        id: "akm-improve-catchup",
+        profile: "catchup",
+        command: "akm improve --profile catchup --auto-accept safe",
+        schedule: null,
+        description: "Manual recovery — consolidation + triage drain (run on demand)",
+        enableMode: "manual",
+    },
+    {
+        id: "akm-graph-refresh-weekly",
+        profile: "graph-refresh",
+        command: "akm improve --profile graph-refresh --auto-accept safe",
+        schedule: "0 3 * * 0",
+        description: "Full-corpus graph rebuild (weekly Sunday 3am)",
+        enableMode: "always",
+    },
+];
+/**
+ * A schedule for the manual catch-up task. The scheduler requires a valid
+ * cron expression even when the task is registered disabled, so we give the
+ * unscheduled task a nominal far-future-ish cadence and leave it disabled —
+ * the documented entry point is `akm tasks run akm-improve-catchup`.
+ */
+const MANUAL_TASK_NOMINAL_SCHEDULE = "0 4 1 1 *"; // 04:00 on Jan 1 — never effectively fires
+const DEFAULT_DEPS = {
+    list: akmTasksList,
+    add: akmTasksAdd,
+};
+/**
+ * Decide whether `akm setup` is running in a CI environment, where it must
+ * register NO scheduled tasks. Mirrors the common `CI=true` convention used by
+ * GitHub Actions, GitLab CI, CircleCI, etc.
+ */
+export function isCiEnvironment(env = process.env) {
+    const ci = env.CI;
+    if (ci === undefined || ci === null)
+        return false;
+    const v = String(ci).trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+/**
+ * Platform-appropriate default for the "Is this a server install?" prompt:
+ *  - Linux without a battery → `true` (server).
+ *  - macOS / any host with a battery (laptop) → `false`.
+ * Used as the default when setup is non-interactive (no TTY / --yes / CI).
+ */
+export function detectServerDefault() {
+    if (os.platform() !== "linux")
+        return false;
+    // A laptop exposes a battery under /sys/class/power_supply/BAT*. Absence of
+    // any battery is our heuristic for "server / desktop".
+    try {
+        const entries = fs.readdirSync("/sys/class/power_supply");
+        const hasBattery = entries.some((e) => /^BAT/i.test(e));
+        return !hasBattery;
+    }
+    catch {
+        // If we cannot read power-supply info, prefer the safe server default on
+        // Linux (the nightly sweep is low-impact and re-runnable).
+        return true;
+    }
+}
+/**
+ * Idempotently register the default improve task set.
+ *
+ * - Skips entirely when `CI` is set (returns `{ skipped: true, reason: "ci" }`).
+ * - Creates any missing task; never duplicates an existing one.
+ * - Re-aligns the enabled-state of existing tasks to the desired default only
+ *   when the install is fresh-creating them (existing tasks the user may have
+ *   toggled are left untouched — we only toggle tasks we just created, plus we
+ *   never re-disable a user-enabled task).
+ */
+export async function registerDefaultTasks(options = {}) {
+    if (isCiEnvironment()) {
+        return { skipped: true, reason: "ci", created: [], existing: [], toggled: [] };
+    }
+    const deps = options.deps ?? DEFAULT_DEPS;
+    const serverInstall = options.serverInstall ?? detectServerDefault();
+    let installed = [];
+    try {
+        installed = (await deps.list()).tasks;
+    }
+    catch {
+        installed = [];
+    }
+    const existingIds = new Set(installed.map((t) => t.id));
+    const created = [];
+    const existing = [];
+    const toggled = [];
+    for (const spec of DEFAULT_IMPROVE_TASKS) {
+        const desiredEnabled = resolveDesiredEnabled(spec, serverInstall);
+        if (existingIds.has(spec.id)) {
+            // Idempotent: never re-create. Leave the existing task in place.
+            existing.push(spec.id);
+            continue;
+        }
+        const schedule = spec.schedule ?? MANUAL_TASK_NOMINAL_SCHEDULE;
+        const addInput = {
+            id: spec.id,
+            schedule,
+            command: spec.command,
+            description: spec.description,
+            // Manual + non-server-enabled tasks are written disabled so the
+            // scheduler entry is inert until the user opts in / runs it manually.
+            disabled: !desiredEnabled,
+        };
+        await deps.add(addInput);
+        created.push(spec.id);
+        if (desiredEnabled)
+            toggled.push(spec.id);
+    }
+    return { skipped: false, created, existing, toggled };
+}
+function resolveDesiredEnabled(spec, serverInstall) {
+    switch (spec.enableMode) {
+        case "always":
+            return true;
+        case "server":
+            return serverInstall;
+        case "manual":
+            return false;
+    }
+}

package/dist/commands/tasks/tasks-cli.js

@@ -0,0 +1,210 @@
+// 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/.
+/**
+ * `akm tasks` command family. Extracted verbatim from src/cli.ts (WS6) so the
+ * God Module shrinks; the `main.subCommands.tasks` key and every subcommand's
+ * args/output shape are byte-identical. Handlers whose body is a plain
+ * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
+ * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
+ * form. `tasks run` keeps a plain `defineCommand` because it forwards the
+ * task's own exit code via `process.exit`. The private helper
+ * `makeTasksToggleCommand` and the `TASKS_SUBCOMMAND_SET` routing constant move
+ * with the family.
+ */
+import { defineCommand } from "citty";
+import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { getHyphenatedArg } from "../../output/context.js";
+import { detectServerDefault, registerDefaultTasks } from "./default-tasks.js";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./tasks.js";
+const tasksAddCommand = defineJsonCommand({
+    meta: { name: "add", description: "Register a new scheduled task and install it in the OS scheduler" },
+    args: {
+        id: { type: "positional", description: "Task id (used as filename and scheduler entry)", required: true },
+        schedule: { type: "string", description: 'Cron-style schedule, e.g. "0 9 * * *" or "@daily"', required: true },
+        workflow: { type: "string", description: "Workflow ref to invoke (e.g. workflow:my-flow)" },
+        prompt: {
+            type: "string",
+            description: "Prompt for the configured agent harness — inline text, an asset ref like agent:foo, or ./path.md",
+        },
+        command: {
+            type: "string",
+            description: 'Shell command to run on the schedule (no AI agent), e.g. "akm improve --auto-accept safe". Split on whitespace; quote the whole flag value.',
+        },
+        profile: { type: "string", description: "Agent profile to use for prompt targets (default: defaults.agent)" },
+        params: { type: "string", description: "Workflow params as a JSON object" },
+        name: { type: "string", description: "Human-readable name for the task" },
+        "when-to-use": { type: "string", description: "Guidance on when this task runs or should be used" },
+        description: { type: "string", description: "Human-readable description" },
+        tags: { type: "string", description: "Comma-separated tags" },
+        disabled: { type: "boolean", description: "Register but leave disabled in the OS scheduler", default: false },
+        force: { type: "boolean", description: "Overwrite an existing task with the same id", default: false },
+    },
+    async run({ args }) {
+        const result = await akmTasksAdd({
+            id: args.id,
+            schedule: args.schedule,
+            workflow: args.workflow,
+            prompt: args.prompt,
+            command: args.command,
+            profile: args.profile,
+            params: args.params,
+            name: args.name,
+            when_to_use: getHyphenatedArg(args, "when-to-use"),
+            description: args.description,
+            tags: args.tags
+                ? args.tags
+                    .split(/[\s,]+/)
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : undefined,
+            disabled: args.disabled === true,
+            force: args.force === true,
+        });
+        output("tasks-add", result);
+    },
+});
+const tasksInitCommand = defineJsonCommand({
+    meta: {
+        name: "init",
+        description: "Idempotently register the default improve task set (skips when CI=true)",
+    },
+    args: {
+        server: {
+            type: "boolean",
+            description: "Treat this as a server install (enables the nightly sweep). Defaults to platform detection.",
+        },
+        laptop: {
+            type: "boolean",
+            description: "Treat this as a laptop install (leaves the nightly sweep disabled).",
+        },
+    },
+    async run({ args }) {
+        const serverInstall = args.server === true ? true : args.laptop === true ? false : detectServerDefault();
+        const result = await registerDefaultTasks({ serverInstall });
+        output("tasks-init", result);
+    },
+});
+const tasksListCommand = defineJsonCommand({
+    meta: { name: "list", description: "List scheduled tasks in the stash" },
+    async run() {
+        const result = await akmTasksList();
+        output("tasks-list", result);
+    },
+});
+const tasksShowCommand = defineJsonCommand({
+    meta: { name: "show", description: "Show a parsed task definition" },
+    args: { id: { type: "positional", description: "Task id or task:<id>", required: true } },
+    async run({ args }) {
+        const { id } = parseTaskRef(args.id);
+        const result = await akmTasksShow(id);
+        output("tasks-show", result);
+    },
+});
+const tasksRemoveCommand = defineJsonCommand({
+    meta: { name: "remove", description: "Delete a task file and uninstall it from the OS scheduler" },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        const { id } = parseTaskRef(args.id);
+        const result = await akmTasksRemove(id);
+        output("tasks-remove", result);
+    },
+});
+function makeTasksToggleCommand(enabled) {
+    const verb = enabled ? "enable" : "disable";
+    const description = enabled
+        ? "Enable a previously-disabled task"
+        : "Disable a task in the OS scheduler without removing the file";
+    return defineJsonCommand({
+        meta: { name: verb, description },
+        args: { id: { type: "positional", description: "Task id", required: true } },
+        async run({ args }) {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksSetEnabled(id, enabled);
+            output(`tasks-${verb}`, result);
+        },
+    });
+}
+const tasksEnableCommand = makeTasksToggleCommand(true);
+const tasksDisableCommand = makeTasksToggleCommand(false);
+const tasksRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Execute a task now (this is what cron / launchd / schtasks invoke at the scheduled time)",
+    },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const envelope = await akmTasksRun(id);
+            output("tasks-run", envelope);
+            if (envelope.exitCode !== 0)
+                process.exit(envelope.exitCode);
+        });
+    },
+});
+const tasksHistoryCommand = defineJsonCommand({
+    meta: { name: "history", description: "Show recent task run history" },
+    args: {
+        id: { type: "string", description: "Filter to one task id" },
+        limit: { type: "string", description: "Maximum rows to return (default 50)" },
+    },
+    async run({ args }) {
+        const limit = parsePositiveIntFlag(args.limit ?? undefined);
+        const result = await akmTasksHistory({ id: args.id, limit });
+        output("tasks-history", result);
+    },
+});
+const tasksSyncCommand = defineJsonCommand({
+    meta: {
+        name: "sync",
+        description: "Reconcile the on-disk task files with the OS scheduler",
+    },
+    async run() {
+        const result = await akmTasksSync();
+        output("tasks-sync", result);
+    },
+});
+const tasksDoctorCommand = defineJsonCommand({
+    meta: {
+        name: "doctor",
+        description: "Report the active scheduler backend, akm bin path, log dir, and supported schedule subset",
+    },
+    async run() {
+        const result = await akmTasksDoctor();
+        output("tasks-doctor", result);
+    },
+});
+// Single source of truth: the routing set is derived from the subCommands keys
+// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
+const tasksSubCommands = {
+    add: tasksAddCommand,
+    init: tasksInitCommand,
+    list: tasksListCommand,
+    show: tasksShowCommand,
+    remove: tasksRemoveCommand,
+    enable: tasksEnableCommand,
+    disable: tasksDisableCommand,
+    run: tasksRunCommand,
+    history: tasksHistoryCommand,
+    sync: tasksSyncCommand,
+    doctor: tasksDoctorCommand,
+};
+const TASKS_SUBCOMMAND_SET = new Set(Object.keys(tasksSubCommands));
+export const tasksCommand = defineCommand({
+    meta: {
+        name: "tasks",
+        alias: "task",
+        description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
+    },
+    subCommands: tasksSubCommands,
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
+                return;
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});

package/dist/commands/{tasks.js → tasks/tasks.js}

@@ -11,20 +11,20 @@
 import fs from "node:fs";
 import path from "node:path";
 import { stringify as yamlStringify } from "yaml";
-import { resolveAssetPathFromName } from "../core/asset-spec";
-import { isWithin, resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
-import { ConfigError, NotFoundError, UsageError } from "../core/errors";
-import { getTaskHistoryDir, getTaskLogDir } from "../core/paths";
-import { listAgentProfileNames } from "../integrations/agent";
-import { resolveAssetPath } from "../sources/resolve";
-import { backendNameForPlatform, selectBackend } from "../tasks/backends";
-import { parseTaskDocument } from "../tasks/parser";
-import { resolveAkmInvocation } from "../tasks/resolveAkmBin";
-import { exitCodeForStatus, readTaskHistory, runTask } from "../tasks/runner";
-import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../tasks/schedule";
-import { validateTaskDocument } from "../tasks/validator";
-import { resolveImproveProfile } from "./improve-profiles";
+import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { isWithin, resolveStashDir } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
+import { listAgentProfileNames } from "../../integrations/agent/index.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
+import { parseTaskDocument } from "../../tasks/parser.js";
+import { resolveAkmInvocation } from "../../tasks/resolveAkmBin.js";
+import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
+import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
+import { validateTaskDocument } from "../../tasks/validator.js";
+import { resolveImproveProfile } from "../improve/improve-profiles.js";
 export async function akmTasksAdd(input) {
     const id = normaliseTaskId(input.id);
     const hasCommand = input.command !== undefined &&