@lightward/mechanic-cli 0.1.0

package/dist/commands/tasks/push.js

@@ -0,0 +1,370 @@
+import { createHash } from "node:crypto";
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { linkForSlug, saveLinks, updateLink } from "../../config.js";
+import { CliError } from "../../errors.js";
+import { stableStringify } from "../../json.js";
+import { displayTaskPath, remoteChangedSinceLastPull, remoteChangedSinceLastPullDetails, remoteChangedSinceLastPullMessage, selectedTaskFiles, readRawTaskFile, slugFromTaskFile, taskForPush, taskSlug, unbundledHelperDirForTaskFile, validateTaskForPush, writeTaskFilePathAndRefreshHelper, } from "../../tasks.js";
+function createTaskIdempotencyKey(shopDomain, slug) {
+    const hex = createHash("sha256")
+        .update(`mechanic-cli-task-create\0${shopDomain}\0${slug}`)
+        .digest("hex");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join("-");
+}
+export default class TasksPush extends BaseCommand {
+    static hidden = true;
+    static summary = "Publish one local task, or use --all to publish every local task.";
+    static description = "Publish one local task to Mechanic, or use --all to publish every local task JSON file in this project.";
+    static args = {
+        file: Args.string({ required: false, description: "Task file, helper directory, linked task ID, or unique local task slug." }),
+    };
+    static flags = {
+        all: Flags.boolean({ description: "Publish every task JSON file in this project." }),
+        "dry-run": Flags.boolean({ description: "Show what would be published without writing to Mechanic or local files." }),
+        force: Flags.boolean({ description: "Bypass remote content hash conflict protection." }),
+        json: Flags.boolean({ description: "Print publish result or dry-run plan as JSON for agents, scripts, or editor integrations." }),
+    };
+    async run() {
+        const commandClass = this.constructor;
+        const { args, flags } = await this.parse(commandClass);
+        await this.runPush(args.file, flags);
+    }
+    async runPush(file, flags) {
+        const project = await this.loadProject();
+        const files = await selectedTaskFiles(project, file, Boolean(flags.all));
+        const preparation = await this.prepareTasks(project, files, Boolean(flags["dry-run"]));
+        if (flags["dry-run"]) {
+            const result = await this.dryRunPush(project, preparation, Boolean(flags.force));
+            if (flags.json) {
+                this.outputJson({
+                    shop_domain: project.shopDomain,
+                    dry_run: true,
+                    blocked: result.blocked,
+                    tasks: result.rows,
+                });
+            }
+            else {
+                this.table(this.pushRowsToTable(project, "Plan", result.rows, (status) => this.planLabel(status)));
+            }
+            if (result.blocked) {
+                throw new CliError("Dry-run found blocked tasks.", 2);
+            }
+            return;
+        }
+        const rows = await this.publishTasks(project, preparation, Boolean(flags.force));
+        if (flags.json) {
+            this.outputJson({
+                shop_domain: project.shopDomain,
+                dry_run: false,
+                tasks: rows,
+            });
+            return;
+        }
+        this.table(this.pushRowsToTable(project, "Action", rows, (status) => this.actionLabel(status)));
+    }
+    async publishTasks(project, preparation, force) {
+        const client = await this.verifiedClientForProject(project);
+        let links = project.links;
+        const rows = [];
+        await this.blockUnlinkedCreateCollisions(client, project, links, preparation.preparedTasks);
+        const remoteBySlug = force
+            ? new Map()
+            : await this.preflightRemoteChanges(client, project, links, preparation.preparedTasks);
+        for (const { file, slug, relativeFile, task } of preparation.preparedTasks) {
+            const link = linkForSlug({ ...project, links }, slug);
+            if (!link) {
+                const created = await client.createTask(task, createTaskIdempotencyKey(project.shopDomain, slug));
+                links = updateLink({ ...project, links }, slug, created.id, created.content_hash);
+                await saveLinks(project, links);
+                await writeTaskFilePathAndRefreshHelper(file, created.task);
+                rows.push({
+                    file: relativeFile,
+                    status: "created",
+                    task_id: created.id,
+                    content_hash: created.content_hash,
+                    details: "created disabled; enable in Mechanic",
+                });
+                continue;
+            }
+            if (!force) {
+                const remote = remoteBySlug.get(slug) || await client.getTask(link.remote_id);
+                if (stableStringify(task) === stableStringify(taskForPush(remote.task))) {
+                    rows.push({
+                        file: relativeFile,
+                        status: "skipped",
+                        task_id: remote.id,
+                        content_hash: remote.content_hash,
+                        details: "",
+                    });
+                    continue;
+                }
+            }
+            const updated = await client.updateTask(link.remote_id, {
+                task,
+                ...(force ? { force: true } : { previous_content_hash: link.last_remote_content_hash }),
+            });
+            links = updateLink({ ...project, links }, slug, updated.id, updated.content_hash);
+            await saveLinks(project, links);
+            await writeTaskFilePathAndRefreshHelper(file, updated.task);
+            rows.push({
+                file: relativeFile,
+                status: force ? "forced" : "updated",
+                task_id: updated.id,
+                content_hash: updated.content_hash,
+                details: "",
+            });
+        }
+        return rows;
+    }
+    async preflightRemoteChanges(client, project, links, preparedTasks) {
+        const remoteBySlug = new Map();
+        const conflicts = [];
+        for (const { slug, relativeFile } of preparedTasks) {
+            const link = linkForSlug({ ...project, links }, slug);
+            if (!link) {
+                continue;
+            }
+            const remote = await client.getTask(link.remote_id);
+            remoteBySlug.set(slug, remote);
+            if (remoteChangedSinceLastPull(link, remote)) {
+                conflicts.push(remoteChangedSinceLastPullMessage(relativeFile, link.remote_id));
+            }
+        }
+        if (conflicts.length > 0) {
+            throw new CliError([
+                "Remote changes found before publishing. Nothing was published.",
+                "",
+                ...conflicts.map((conflict) => `- ${conflict}`),
+            ].join("\n"), 2);
+        }
+        return remoteBySlug;
+    }
+    async unlinkedCreateCollisions(client, project, links, preparedTasks) {
+        const unlinkedTasks = preparedTasks.filter(({ slug }) => !linkForSlug({ ...project, links }, slug));
+        if (unlinkedTasks.length === 0) {
+            return new Map();
+        }
+        const remoteBySlug = new Map();
+        const response = await client.listTasks();
+        for (const remote of response.tasks || []) {
+            const remoteName = typeof remote.task?.name === "string" && remote.task.name.trim()
+                ? remote.task.name
+                : remote.id;
+            remoteBySlug.set(taskSlug(remoteName), remote);
+        }
+        return new Map(unlinkedTasks.flatMap(({ slug, task }) => {
+            const localName = typeof task.name === "string" && task.name.trim() ? task.name : slug;
+            const localSlugs = new Set([slug, taskSlug(localName)]);
+            const collision = [...localSlugs].flatMap((localSlug) => {
+                const remote = remoteBySlug.get(localSlug);
+                if (!remote) {
+                    return [];
+                }
+                const remoteName = typeof remote.task?.name === "string" && remote.task.name.trim()
+                    ? remote.task.name
+                    : remote.id;
+                return [{
+                        remoteId: remote.id,
+                        remoteName,
+                    }];
+            })[0];
+            return collision ? [[slug, collision]] : [];
+        }));
+    }
+    async blockUnlinkedCreateCollisions(client, project, links, preparedTasks) {
+        const collisions = await this.unlinkedCreateCollisions(client, project, links, preparedTasks);
+        if (collisions.size === 0) {
+            return;
+        }
+        throw new CliError([
+            "Unlinked local task files match existing Mechanic tasks. Nothing was published.",
+            "",
+            ...preparedTasks.flatMap(({ slug, relativeFile }) => {
+                const collision = collisions.get(slug);
+                if (!collision) {
+                    return [];
+                }
+                return [
+                    `- ${relativeFile} looks like "${collision.remoteName}" (${collision.remoteId}). Run "mechanic tasks pull ${collision.remoteId}" before publishing, or rename the local task if it should be separate.`,
+                ];
+            }),
+        ].join("\n"), 2);
+    }
+    async prepareTasks(project, files, collectBlockedRows) {
+        const preparedTasks = [];
+        const rows = [];
+        let blocked = false;
+        for (const file of files) {
+            const slug = slugFromTaskFile(file);
+            const relativeFile = displayTaskPath(project, file);
+            let localTask;
+            try {
+                localTask = await readRawTaskFile(file);
+            }
+            catch (error) {
+                if (!collectBlockedRows) {
+                    throw error;
+                }
+                blocked = true;
+                rows.push({
+                    file: relativeFile,
+                    status: "blocked",
+                    task_id: null,
+                    content_hash: null,
+                    details: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+            const validation = validateTaskForPush(localTask, relativeFile);
+            if (!validation.ok) {
+                const message = [
+                    `${relativeFile} is not a valid task export.`,
+                    ...validation.errors.map((error) => `- ${error}`),
+                ].join("\n");
+                if (!collectBlockedRows) {
+                    throw new CliError(message, 2);
+                }
+                blocked = true;
+                rows.push({
+                    file: relativeFile,
+                    status: "blocked",
+                    task_id: null,
+                    content_hash: null,
+                    details: validation.errors.join("; "),
+                });
+                continue;
+            }
+            const helperDir = await unbundledHelperDirForTaskFile(file, localTask);
+            if (helperDir) {
+                const relativeHelperDir = displayTaskPath(project, helperDir);
+                const message = [
+                    `${relativeFile} is out of date with ${relativeHelperDir}.`,
+                    "",
+                    "The helper directory has changes that are not bundled into the JSON file.",
+                    "",
+                    "Bundle first:",
+                    `  mechanic tasks bundle ${relativeHelperDir}`,
+                    "",
+                    "Then publish:",
+                    `  mechanic tasks publish ${relativeFile}`,
+                ].join("\n");
+                if (!collectBlockedRows) {
+                    throw new CliError(message, 2);
+                }
+                blocked = true;
+                rows.push({
+                    file: relativeFile,
+                    status: "blocked",
+                    task_id: null,
+                    content_hash: null,
+                    details: `bundle ${relativeHelperDir} first`,
+                });
+                continue;
+            }
+            preparedTasks.push({
+                file,
+                slug,
+                relativeFile,
+                task: taskForPush(localTask),
+            });
+        }
+        return { blocked, preparedTasks, rows };
+    }
+    async dryRunPush(project, preparation, force) {
+        let client = null;
+        let blocked = preparation.blocked;
+        const getClient = async () => {
+            client ||= await this.verifiedClientForProject(project);
+            return client;
+        };
+        if (preparation.preparedTasks.length > 0) {
+            await getClient();
+        }
+        const createCollisions = preparation.preparedTasks.length > 0
+            ? await this.unlinkedCreateCollisions(await getClient(), project, project.links, preparation.preparedTasks)
+            : new Map();
+        for (const { slug, relativeFile, task } of preparation.preparedTasks) {
+            const link = linkForSlug(project, slug);
+            if (!link) {
+                const collision = createCollisions.get(slug);
+                if (collision) {
+                    blocked = true;
+                    preparation.rows.push({
+                        file: relativeFile,
+                        status: "blocked",
+                        task_id: collision.remoteId,
+                        content_hash: null,
+                        details: `remote "${collision.remoteName}" already exists; pull before publishing`,
+                    });
+                    continue;
+                }
+                preparation.rows.push({
+                    file: relativeFile,
+                    status: "would create",
+                    task_id: null,
+                    content_hash: null,
+                    details: "creates disabled task; enable in Mechanic",
+                });
+                continue;
+            }
+            const remote = await (await getClient()).getTask(link.remote_id);
+            const remoteChanged = remoteChangedSinceLastPull(link, remote);
+            if (remoteChanged && !force) {
+                blocked = true;
+                preparation.rows.push({
+                    file: relativeFile,
+                    status: "conflict",
+                    task_id: remote.id,
+                    content_hash: remote.content_hash,
+                    details: remoteChangedSinceLastPullDetails(),
+                });
+                continue;
+            }
+            const localComparable = stableStringify(task);
+            const remoteComparable = stableStringify(taskForPush(remote.task));
+            const changed = localComparable !== remoteComparable;
+            const details = remoteChanged ? remoteChangedSinceLastPullDetails(true) : "";
+            preparation.rows.push({
+                file: relativeFile,
+                status: changed ? "would update" : "no change",
+                task_id: remote.id,
+                content_hash: remote.content_hash,
+                details,
+            });
+        }
+        return { blocked, rows: preparation.rows };
+    }
+    pushRowsToTable(project, statusHeader, rows, label) {
+        return [
+            ["File", statusHeader, "Task ID", "Hash", "Details"],
+            ...rows.map((row) => [
+                this.taskName(row.file),
+                label(row.status),
+                row.task_id ? this.taskId(project, row.task_id) : "--",
+                row.content_hash ? this.muted(row.content_hash) : "--",
+                row.details,
+            ]),
+        ];
+    }
+    planLabel(plan) {
+        switch (plan) {
+            case "would create":
+                return this.success(plan);
+            case "would update":
+                return this.color("cyan", plan);
+            case "no change":
+                return this.muted(plan);
+            case "conflict":
+            case "blocked":
+                return this.color("red", plan);
+            default:
+                return plan;
+        }
+    }
+}

package/dist/commands/tasks/status.d.ts

@@ -0,0 +1,30 @@
+import { BaseCommand } from "../../base-command.js";
+import { linkForSlug } from "../../config.js";
+import type { MechanicClient } from "../../client.js";
+import type { JsonObject, Project } from "../../types.js";
+type HelperStatus = {
+    label: string;
+    blocked: boolean;
+    details?: string;
+};
+export default class TasksStatus extends BaseCommand {
+    static summary: string;
+    static description: string;
+    static args: {
+        file: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        remote: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    helperStatus(project: Project, file: string, task: JsonObject): Promise<HelperStatus>;
+    remoteStatus(client: MechanicClient | null, task: JsonObject, link: ReturnType<typeof linkForSlug>): Promise<{
+        label: string;
+        details?: string;
+    }>;
+    localLabel(label: string): string;
+    remoteLabel(label: string): string;
+}
+export {};
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/tasks/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/tasks/status.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAe9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE1D,KAAK,YAAY,GAAG;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAqBF,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,WAAW;IAClD,OAAgB,OAAO,SAAuE;IAC9F,OAAgB,WAAW,SAA0H;IAErJ,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;MAQnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAsGpB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IA4BrF,YAAY,CAChB,MAAM,EAAE,cAAc,GAAG,IAAI,EAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GACnC,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/C,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAejC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAgBnC"}

package/dist/commands/tasks/status.js

@@ -0,0 +1,183 @@
+import { Args, Flags } from "@oclif/core";
+import path from "node:path";
+import { BaseCommand } from "../../base-command.js";
+import { linkForSlug } from "../../config.js";
+import { pathExists } from "../../fs.js";
+import { stableStringify } from "../../json.js";
+import { displayTaskPath, helperDirForTaskFile, readRawTaskFile, remoteChangedSinceLastPull, remoteChangedSinceLastPullDetails, selectedTaskFiles, slugFromTaskFile, taskForPush, unbundledHelperDirForTaskFile, validateTaskForPush, } from "../../tasks.js";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export default class TasksStatus extends BaseCommand {
+    static summary = "Show local task link, readiness, and optional remote sync status.";
+    static description = "Show whether local task files are linked, ready to publish, and optionally in sync with their remote Mechanic tasks.";
+    static args = {
+        file: Args.string({ required: false, description: "Task file, helper directory, linked task ID, or unique local task slug. Defaults to every task JSON file." }),
+    };
+    static flags = {
+        json: Flags.boolean({
+            description: "Print task status as JSON for agents, scripts, or editor integrations.",
+        }),
+        remote: Flags.boolean({
+            char: "r",
+            description: "Check linked remote tasks and report no-change, local-change, or conflict state.",
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TasksStatus);
+        const project = await this.loadProject();
+        const files = await selectedTaskFiles(project, args.file, !args.file);
+        const statuses = [];
+        let client = null;
+        const getClient = async () => {
+            client ||= await this.verifiedClientForProject(project);
+            return client;
+        };
+        for (const file of files) {
+            const slug = slugFromTaskFile(file);
+            const relativeFile = displayTaskPath(project, file);
+            const link = linkForSlug(project, slug);
+            let task = null;
+            const details = [];
+            let helperStatus = { label: "not checked", blocked: true };
+            try {
+                task = await readRawTaskFile(file);
+                const validation = validateTaskForPush(task, relativeFile);
+                if (!validation.ok) {
+                    helperStatus = {
+                        label: "blocked",
+                        blocked: true,
+                        details: validation.errors.join("; "),
+                    };
+                }
+                else {
+                    helperStatus = await this.helperStatus(project, file, task);
+                }
+            }
+            catch (error) {
+                helperStatus = {
+                    label: "blocked",
+                    blocked: true,
+                    details: errorMessage(error),
+                };
+            }
+            if (helperStatus.details) {
+                details.push(helperStatus.details);
+            }
+            const remote = flags.remote && task && !helperStatus.blocked
+                ? await this.remoteStatus(link ? await getClient() : null, task, link)
+                : flags.remote ? { label: "skipped", details: undefined } : null;
+            if (remote?.details) {
+                details.push(remote.details);
+            }
+            else if (!link && task && !helperStatus.blocked) {
+                details.push("publish will create disabled task");
+            }
+            statuses.push({
+                file: relativeFile,
+                slug,
+                link: {
+                    linked: Boolean(link),
+                    remote_id: link?.remote_id || null,
+                },
+                local: helperStatus,
+                remote,
+                details,
+            });
+        }
+        if (flags.json) {
+            this.outputJson({
+                shop_domain: project.shopDomain,
+                remote_checked: Boolean(flags.remote),
+                tasks: statuses,
+            });
+            return;
+        }
+        const rows = flags.remote
+            ? [["File", "Link", "Local", "Remote", "Task ID", "Details"]]
+            : [["File", "Link", "Local", "Task ID", "Details"]];
+        for (const status of statuses) {
+            const row = [
+                this.taskName(status.file),
+                status.link.linked ? this.success("linked") : this.color("yellow", "unlinked"),
+                this.localLabel(status.local.label),
+            ];
+            if (flags.remote) {
+                row.push(this.remoteLabel(status.remote?.label || "not checked"));
+            }
+            row.push(status.link.remote_id ? this.taskId(project, status.link.remote_id) : "--", status.details.join("; "));
+            rows.push(row);
+        }
+        this.table(rows);
+    }
+    async helperStatus(project, file, task) {
+        const helperDir = helperDirForTaskFile(file);
+        if (!helperDir || !(await pathExists(path.join(helperDir, "task.json")))) {
+            return { label: "ready", blocked: false };
+        }
+        try {
+            const driftDir = await unbundledHelperDirForTaskFile(file, task);
+            if (driftDir) {
+                return {
+                    label: "needs bundle",
+                    blocked: true,
+                    details: `run mechanic tasks bundle ${displayTaskPath(project, driftDir)}`,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                label: "blocked",
+                blocked: true,
+                details: errorMessage(error),
+            };
+        }
+        return { label: "ready", blocked: false };
+    }
+    async remoteStatus(client, task, link) {
+        if (!link) {
+            return { label: "will create", details: "publish will create disabled task" };
+        }
+        if (!client) {
+            return { label: "not checked" };
+        }
+        const remote = await client.getTask(link.remote_id);
+        if (remoteChangedSinceLastPull(link, remote)) {
+            return { label: "conflict", details: remoteChangedSinceLastPullDetails() };
+        }
+        if (stableStringify(taskForPush(task)) !== stableStringify(taskForPush(remote.task))) {
+            return { label: "local changes", details: "publish would update" };
+        }
+        return { label: "no change" };
+    }
+    localLabel(label) {
+        switch (label) {
+            case "ready":
+                return this.success(label);
+            case "needs bundle":
+                return this.color("yellow", label);
+            case "blocked":
+                return this.color("red", label);
+            case "not checked":
+                return this.muted(label);
+            default:
+                return label;
+        }
+    }
+    remoteLabel(label) {
+        switch (label) {
+            case "will create":
+            case "no change":
+                return this.success(label);
+            case "local changes":
+                return this.color("cyan", label);
+            case "conflict":
+                return this.color("red", label);
+            case "skipped":
+            case "not checked":
+                return this.muted(label);
+            default:
+                return label;
+        }
+    }
+}

package/dist/commands/tasks/unbundle.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from "../../base-command.js";
+export default class TasksUnbundle extends BaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        file: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        out: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private resolveUnbundlePaths;
+}
+//# sourceMappingURL=unbundle.d.ts.map

package/dist/commands/tasks/unbundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbundle.d.ts","sourceRoot":"","sources":["../../../src/commands/tasks/unbundle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKpD,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,WAAW;IACpD,OAAgB,OAAO,SAAkD;IACzE,OAAgB,WAAW,SAAiJ;IAC5K,OAAgB,QAAQ,WAKtB;IAEF,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;MAOnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YA+BZ,oBAAoB;CA2CnC"}