@lightward/mechanic-cli 0.1.13 → 0.1.14

package/README.md

@@ -122,6 +122,19 @@ mechanic shop status
 Most commands that editor integrations or agents would call support `--json`.
 Use JSON output for automation instead of parsing tables or colored text.
 
+When a `--json` command fails before producing its normal output (auth
+problems, network failures, rate limits), it prints a JSON error envelope to
+stdout instead, with exit codes unchanged:
+
+```json
+{ "error": { "message": "Mechanic API rate limit exceeded.", "status": 429, "retry_after_seconds": 7 } }
+```
+
+`status` is present when the Mechanic API rejected the request, and
+`retry_after_seconds` is present when a rate limit response includes
+`Retry-After`. With `--json`, stdout is always a single JSON document: the
+command's normal output, or this error envelope.
+
 ## Commands
 
 ```bash
@@ -141,7 +154,7 @@ mechanic tasks status [task] [--local] [--json]
 mechanic tasks pull [--force]
 mechanic tasks pull <task> [--force]
 mechanic tasks pull --all [--force]
-mechanic tasks preview <task> [--remote] [--verbose] [--json]
+mechanic tasks preview [task] [--stdin] [--remote] [--verbose] [--json]
 mechanic tasks diff <task> [--exit-code] [--json]
 mechanic tasks diff --all [--exit-code] [--json]
 mechanic tasks publish <task> [--force] [--dry-run] [--json]
@@ -240,7 +253,25 @@ current task already in Mechanic instead of your local draft. Add `--verbose`
 to show event, task run, and action run result details in the terminal. Add
 `--json` when an agent, script, or CI job needs the raw preview response.
 Missing Shopify permissions are approved in the Mechanic app after publishing
-or enabling the task.
+or enabling the task. Preview exits `0` when the preview passes, `1` when
+sample runs fail, and `2` when the task is invalid.
+
+`tasks preview --stdin` reads task JSON from stdin instead of local files, so
+editors and other tools can preview in-memory task content without writing it
+to disk first:
+
+```bash
+cat build/order-tagger.json | mechanic tasks preview order-tagger --stdin
+generate-task | mechanic tasks preview --stdin --json
+```
+
+Pass a task selector alongside `--stdin` to preview the piped content in the
+context of that linked Mechanic task, or omit the selector to preview the
+content as a new unlinked task. `--stdin` trusts the piped content as the
+source of truth, so it skips the stale helper directory check. Previews are
+rate limited per token; tools that preview on every edit should debounce and
+respect `429 Retry-After` responses. With `--json`, a rate limited preview
+prints the JSON error envelope, including `retry_after_seconds`.
 
 `tasks publish` sends local task JSON back to Mechanic.
 
@@ -253,8 +284,8 @@ Mechanic, `.mechanic/links.json`, or local task JSON. New tasks created by
 they are ready to run.
 
 For automation or editor integrations, add `--json` to `tasks list`, `tasks
-status`, `tasks diff`, `tasks validate`, `tasks bundle`, `tasks unbundle`,
-`tasks publish`, or `shop status`.
+status`, `tasks preview`, `tasks diff`, `tasks validate`, `tasks bundle`,
+`tasks unbundle`, `tasks publish`, or `shop status`.
 
 `tasks unbundle` and `tasks bundle` operate on one task at a time. By default,
 `mechanic tasks unbundle order-tagger` writes to `tasks/order-tagger/`, and

package/dist/base-command.d.ts

@@ -1,7 +1,9 @@
-import { Command } from "@oclif/core";
+import { Command, type Interfaces } from "@oclif/core";
 import { MechanicClient } from "./client.js";
 import type { Project } from "./types.js";
 export declare abstract class BaseCommand extends Command {
+    private wroteJson;
+    protected catch(error: Interfaces.CommandError): Promise<unknown>;
     protected finally(error: Error | undefined): Promise<void>;
     loadProject(): Promise<Project>;
     clientForProject(project: Project): Promise<MechanicClient>;

package/dist/base-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-command.d.ts","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAM,MAAM,aAAa,CAAC;AAI1C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,8BAAsB,WAAY,SAAQ,OAAO;cACtB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAQ3D,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAMnE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI5B,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAenC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAI1C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3B,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAIhC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B,eAAe,IAAI,MAAM;IAQzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAIhD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;CAgB9B"}
+{"version":3,"file":"base-command.d.ts","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAM,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAI3D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,8BAAsB,WAAY,SAAQ,OAAO;IAC/C,OAAO,CAAC,SAAS,CAAS;cAED,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;cAQvD,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAQ3D,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAMnE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI5B,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAenC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAI1C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3B,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAKhC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B,eAAe,IAAI,MAAM;IAQzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAIhD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;CAgB9B"}

package/dist/base-command.js

@@ -4,9 +4,16 @@ import terminalLink from "terminal-link";
 import { requireToken } from "./auth.js";
 import { MechanicClient } from "./client.js";
 import { loadProject, taskAdminUrl } from "./config.js";
-import { CliError } from "./errors.js";
+import { CliError, errorJson } from "./errors.js";
 import { getUpdateNotice, shouldCheckForUpdates } from "./update-check.js";
 export class BaseCommand extends Command {
+    wroteJson = false;
+    async catch(error) {
+        if (this.argv.includes("--json") && !this.wroteJson) {
+            this.outputJson(errorJson(error));
+        }
+        return super.catch(error);
+    }
     async finally(error) {
         await super.finally(error);
         if (error || this.id === "version" || !shouldCheckForUpdates(this.argv)) {
@@ -66,6 +73,7 @@ export class BaseCommand extends Command {
         return this.color("dim", text);
     }
     outputJson(value) {
+        this.wroteJson = true;
         this.log(JSON.stringify(value, null, 2));
     }
     success(text) {

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAKpB,eAAO,MAAM,UAAU,QAAkD,CAAC;AAE1E,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE;QACL,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,GAAG,IAAI,CAAC;IACT,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;CACH,CAAC;AAwGF,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAM7G,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAgD5E,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIvC,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI5C,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAMvE,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAItC,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOnE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOlE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI1C,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASxE,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM3D,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5E,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;CAM3H"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAKpB,eAAO,MAAM,UAAU,QAAkD,CAAC;AAE1E,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE;QACL,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,GAAG,IAAI,CAAC;IACT,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;CACH,CAAC;AAoHF,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAM7G,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAgD5E,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIvC,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI5C,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAMvE,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAItC,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOnE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOlE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI1C,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASxE,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM3D,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5E,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;CAM3H"}

package/dist/client.js

@@ -20,17 +20,25 @@ function parseBody(text) {
         return { raw: text };
     }
 }
-function retryDelayMilliseconds(response, attempt) {
+function retryAfterSeconds(response) {
     const retryAfter = response.headers.get("retry-after");
-    if (retryAfter) {
-        const parsedSeconds = Number.parseFloat(retryAfter);
-        if (Number.isFinite(parsedSeconds) && parsedSeconds >= 0) {
-            return parsedSeconds * 1000;
-        }
-        const parsedDate = Date.parse(retryAfter);
-        if (Number.isFinite(parsedDate)) {
-            return Math.max(parsedDate - Date.now(), 0);
-        }
+    if (!retryAfter) {
+        return undefined;
+    }
+    const parsedSeconds = Number.parseFloat(retryAfter);
+    if (Number.isFinite(parsedSeconds) && parsedSeconds >= 0) {
+        return parsedSeconds;
+    }
+    const parsedDate = Date.parse(retryAfter);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(parsedDate - Date.now(), 0) / 1000;
+    }
+    return undefined;
+}
+function retryDelayMilliseconds(response, attempt) {
+    const seconds = retryAfterSeconds(response);
+    if (seconds !== undefined) {
+        return seconds * 1000;
     }
     return 250 * (2 ** (attempt - 1));
 }
@@ -131,7 +139,7 @@ export class MechanicClient {
                 await sleep(retryDelayMilliseconds(response, attempt));
                 continue;
             }
-            throw new HttpError(apiErrorMessage(response, parsed), response.status, parsed);
+            throw new HttpError(apiErrorMessage(response, parsed), response.status, parsed, retryAfterSeconds(response));
         }
         throw new HttpError("Request failed", 0, null);
     }

package/dist/commands/secrets/set.d.ts

@@ -1,8 +1,6 @@
-import { stdin } from "node:process";
 import { BaseCommand } from "../../base-command.js";
-type SecretStdin = typeof stdin;
-export declare function readStdin(input?: SecretStdin): Promise<string>;
-export declare function readSecretValueFromStdin(input?: SecretStdin): Promise<string>;
+import { type StdinStream } from "../../stdin.js";
+export declare function readSecretValueFromStdin(input?: StdinStream): Promise<string>;
 export declare function readSecretValueFromEnv(envName: string, env?: NodeJS.ProcessEnv): string;
 export default class SecretsSet extends BaseCommand {
     static summary: string;
@@ -22,5 +20,4 @@ export default class SecretsSet extends BaseCommand {
         "value-env"?: string;
     }): Promise<string>;
 }
-export {};
 //# sourceMappingURL=set.d.ts.map

package/dist/commands/secrets/set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../../src/commands/secrets/set.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIpD,KAAK,WAAW,GAAG,OAAO,KAAK,CAAC;AAEhC,wBAAgB,SAAS,CAAC,KAAK,GAAE,WAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBrE;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,GAAE,WAAmB,GACzB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAYR;AAED,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAAW;IACjD,OAAgB,OAAO,SAA0B;IACjD,OAAgB,WAAW,SAAwE;IACnG,OAAgB,QAAQ,WAKtB;IAEF,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;;MAanB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpB,WAAW,CAAC,KAAK,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAsB5F"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../../src/commands/secrets/set.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7D,wBAAsB,wBAAwB,CAC5C,KAAK,GAAE,WAAmB,GACzB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAYR;AAED,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAAW;IACjD,OAAgB,OAAO,SAA0B;IACjD,OAAgB,WAAW,SAAwE;IACnG,OAAgB,QAAQ,WAKtB;IAEF,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;;MAanB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpB,WAAW,CAAC,KAAK,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAsB5F"}

package/dist/commands/secrets/set.js

@@ -4,24 +4,9 @@ import { promptForHiddenValue } from "../../auth.js";
 import { BaseCommand } from "../../base-command.js";
 import { validateConfigKey } from "../../config-keys.js";
 import { CliError } from "../../errors.js";
-export function readStdin(input = stdin) {
-    if (input.isTTY) {
-        throw new CliError("Cannot read secret value from stdin while stdin is a TTY. Pipe a value or use --value-env.", 2);
-    }
-    return new Promise((resolve, reject) => {
-        let value = "";
-        input.setEncoding("utf8");
-        input.on("data", (chunk) => {
-            value += chunk;
-        });
-        input.on("end", () => {
-            resolve(value);
-        });
-        input.on("error", reject);
-    });
-}
+import { readStdin } from "../../stdin.js";
 export async function readSecretValueFromStdin(input = stdin) {
-    const value = await readStdin(input);
+    const value = await readStdin("Cannot read secret value from stdin while stdin is a TTY. Pipe a value or use --value-env.", input);
     if (value.length === 0) {
         throw new CliError("Secret value cannot be blank.", 2);
     }

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

@@ -1,4 +1,5 @@
 import { BaseCommand } from "../../base-command.js";
+import { type StdinStream } from "../../stdin.js";
 import type { MechanicClient } from "../../client.js";
 import type { JsonObject, Project, TaskPreviewResponse } from "../../types.js";
 type PreviewDiagnostic = NonNullable<TaskPreviewResponse["diagnostics"]>[number];
@@ -11,19 +12,24 @@ type PreparedPreview = {
 type PreviewRenderOptions = {
     verbose: boolean;
 };
+export declare function taskJsonFromStdin(input?: StdinStream): Promise<JsonObject>;
 export default class TasksPreview extends BaseCommand {
     static summary: string;
     static description: string;
+    static examples: string[];
     static args: {
-        target: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        target: 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>;
+        stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
     exitForStatus(response: TaskPreviewResponse): void;
+    prepareStdinPreview(project: Project, target: string | undefined): Promise<PreparedPreview>;
+    taskFromStdin(): Promise<JsonObject>;
     preparePreview(project: Project, target: string, remote: boolean): Promise<PreparedPreview>;
     requestPreview(client: MechanicClient, prepared: PreparedPreview, remote: boolean): Promise<TaskPreviewResponse>;
     renderPreview(project: Project, prepared: PreparedPreview, response: TaskPreviewResponse, options: PreviewRenderOptions): void;

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

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/commands/tasks/preview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/commands/tasks/preview.ts"],"names":[],"mappings":"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"}

package/dist/commands/tasks/preview.js

@@ -1,7 +1,10 @@
 import { Args, Flags } from "@oclif/core";
+import { stdin } from "node:process";
 import { BaseCommand } from "../../base-command.js";
 import { HttpError, CliError } from "../../errors.js";
 import { pathExists } from "../../fs.js";
+import { parseJson } from "../../json.js";
+import { readStdin } from "../../stdin.js";
 import { displayTaskPath, readRawTaskFile, resolveTaskSelector, rawTaskFromHelperDir, taskForPush, slugFromTaskFile, unbundledHelperDirForTaskFile, validateTaskForPush, } from "../../tasks.js";
 function errorBodyAsPreview(body) {
     if (!body || typeof body !== "object") {
@@ -10,25 +13,49 @@ function errorBodyAsPreview(body) {
     const candidate = body;
     return candidate.status === "invalid" ? candidate : null;
 }
+export async function taskJsonFromStdin(input = stdin) {
+    const contents = await readStdin("Cannot read task JSON from stdin while stdin is a TTY. Pipe task JSON or preview a local task file instead.", input);
+    if (contents.trim().length === 0) {
+        throw new CliError("No task JSON received on stdin.", 2);
+    }
+    const task = parseJson(contents, "stdin");
+    if (!task || typeof task !== "object" || Array.isArray(task)) {
+        throw new CliError("stdin must contain a single task JSON object.", 2);
+    }
+    return task;
+}
 export default class TasksPreview extends BaseCommand {
     static summary = "Preview one task with Mechanic sample events.";
     static description = [
         "Preview one local task JSON file or helper directory without publishing it.",
         "The report shows sample event results, action failures, and Shopify permissions detected by the previewed paths.",
+        "Use --stdin to preview task JSON piped from an editor or another tool without writing it to disk.",
         "Use --remote to preview the current task already in Mechanic, or --json for agents, scripts, and CI.",
     ].join("\n");
+    static examples = [
+        "$ mechanic tasks preview order-tagger",
+        "$ mechanic tasks preview order-tagger --verbose",
+        "$ cat build/order-tagger.json | mechanic tasks preview order-tagger --stdin --json",
+        "$ generate-task | mechanic tasks preview --stdin --json",
+    ];
     static args = {
-        target: Args.string({ required: true, description: "Local task slug, task file, helper directory, or linked task ID." }),
+        target: Args.string({ description: "Local task slug, task file, helper directory, or linked task ID. Optional with --stdin." }),
     };
     static flags = {
         json: Flags.boolean({ description: "Print the raw preview response as JSON for agents or CI." }),
-        remote: Flags.boolean({ description: "Preview the current task in Mechanic instead of local content." }),
+        remote: Flags.boolean({ description: "Preview the current task in Mechanic instead of local content.", exclusive: ["stdin"] }),
+        stdin: Flags.boolean({ description: "Read task JSON from stdin instead of local task files. Pass a target to keep its linked task context.", exclusive: ["remote"] }),
         verbose: Flags.boolean({ char: "v", description: "Show event, task run, and action run result details." }),
     };
     async run() {
         const { args, flags } = await this.parse(TasksPreview);
+        if (!args.target && !flags.stdin) {
+            throw new CliError("Provide a task selector, or use --stdin to preview task JSON from stdin.", 2);
+        }
         const project = await this.loadProject();
-        const prepared = await this.preparePreview(project, args.target, Boolean(flags.remote));
+        const prepared = flags.stdin
+            ? await this.prepareStdinPreview(project, args.target)
+            : await this.preparePreview(project, args.target, Boolean(flags.remote));
         const client = await this.verifiedClientForProject(project);
         const response = await this.requestPreview(client, prepared, Boolean(flags.remote));
         if (flags.json) {
@@ -47,6 +74,34 @@ export default class TasksPreview extends BaseCommand {
             throw new CliError("Preview found failed runs.", 1);
         }
     }
+    async prepareStdinPreview(project, target) {
+        let label = "stdin";
+        let slug;
+        let remoteId;
+        if (target) {
+            const selector = await resolveTaskSelector(project, target, {
+                allowHelperDir: true,
+                allowRemoteId: true,
+            });
+            const targetLabel = selector.helperDir
+                ? displayTaskPath(project, selector.helperDir)
+                : selector.file ? displayTaskPath(project, selector.file) : target;
+            label = `stdin (${targetLabel})`;
+            slug = selector.slug;
+            remoteId = selector.remoteId;
+        }
+        const task = await this.taskFromStdin();
+        this.validateLocalTask(task, label);
+        return {
+            label,
+            slug,
+            task: taskForPush(task),
+            remoteId,
+        };
+    }
+    async taskFromStdin() {
+        return taskJsonFromStdin();
+    }
     async preparePreview(project, target, remote) {
         const selector = await resolveTaskSelector(project, target, {
             allowHelperDir: true,

package/dist/errors.d.ts

@@ -5,6 +5,15 @@ export declare class CliError extends Error {
 export declare class HttpError extends CliError {
     readonly status: number;
     readonly body: unknown;
-    constructor(message: string, status: number, body: unknown);
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, status: number, body: unknown, retryAfterSeconds?: number);
 }
+export type ErrorJson = {
+    error: {
+        message: string;
+        status?: number;
+        retry_after_seconds?: number;
+    };
+};
+export declare function errorJson(error: unknown): ErrorJson;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI;CAK1C;AAED,qBAAa,SAAU,SAAQ,QAAQ;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI;CAK1C;AAED,qBAAa,SAAU,SAAQ,QAAQ;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,CAAC,EAAE,MAAM;CAOvF;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH,CAAC;AAEF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAanD"}

package/dist/errors.js

@@ -9,10 +9,23 @@ export class CliError extends Error {
 export class HttpError extends CliError {
     status;
     body;
-    constructor(message, status, body) {
+    retryAfterSeconds;
+    constructor(message, status, body, retryAfterSeconds) {
         super(message, status === 409 ? 2 : 1);
         this.name = "HttpError";
         this.status = status;
         this.body = body;
+        this.retryAfterSeconds = retryAfterSeconds;
     }
 }
+export function errorJson(error) {
+    const message = error instanceof Error && error.message ? error.message : String(error);
+    const envelope = { error: { message } };
+    if (error instanceof HttpError) {
+        envelope.error.status = error.status;
+        if (error.retryAfterSeconds !== undefined) {
+            envelope.error.retry_after_seconds = error.retryAfterSeconds;
+        }
+    }
+    return envelope;
+}

package/dist/stdin.d.ts

@@ -0,0 +1,4 @@
+import { stdin } from "node:process";
+export type StdinStream = typeof stdin;
+export declare function readStdin(ttyMessage: string, input?: StdinStream): Promise<string>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../src/stdin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAGrC,MAAM,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC;AAEvC,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,WAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBzF"}

package/dist/stdin.js

@@ -0,0 +1,18 @@
+import { stdin } from "node:process";
+import { CliError } from "./errors.js";
+export function readStdin(ttyMessage, input = stdin) {
+    if (input.isTTY) {
+        throw new CliError(ttyMessage, 2);
+    }
+    return new Promise((resolve, reject) => {
+        let value = "";
+        input.setEncoding("utf8");
+        input.on("data", (chunk) => {
+            value += chunk;
+        });
+        input.on("end", () => {
+            resolve(value);
+        });
+        input.on("error", reject);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightward/mechanic-cli",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Develop, preview, diff, and publish Mechanic Shopify automation tasks from local files",
   "type": "module",
   "keywords": [