@vzn/vx 0.0.631 → 0.0.633

package/schemas/last.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx last --format json",
+  "description": "`vx last [RUNID] [--failed]` prints a run; `--list` prints an array of invocations, newest first; `--log <task>` prints that task's output.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["invocation", "tasks"],
+      "properties": {
+        "invocation": { "$ref": "#/$defs/invocation" },
+        "tasks": { "type": "array", "items": { "$ref": "#/$defs/task" } }
+      }
+    },
+    { "type": "array", "items": { "$ref": "#/$defs/invocation" } },
+    { "$ref": "#/$defs/log" }
+  ],
+  "$defs": {
+    "log": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "taskId", "status", "source", "output"],
+      "properties": {
+        "runId": { "type": "string" },
+        "taskId": { "type": "string" },
+        "status": { "type": "string" },
+        "source": {
+          "enum": ["failure", "cache", null],
+          "description": "the kept failure output, the cache entry's log, or none kept"
+        },
+        "output": { "type": "string", "description": "plain text; '' when source is null" }
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "command",
+        "requestedTasks",
+        "cachePolicy",
+        "concurrency",
+        "flow",
+        "startedAt",
+        "endedAt",
+        "totalDurationMs",
+        "taskCount",
+        "failedCount",
+        "hitCount",
+        "hitLocalCount",
+        "hitRemoteCount",
+        "upToDateCount",
+        "restoredLocalCount",
+        "restoredRemoteCount",
+        "exitOk",
+        "commitSha",
+        "branch",
+        "dirty",
+        "ci",
+        "ciProvider",
+        "host",
+        "os",
+        "arch",
+        "vxVersion",
+        "tags"
+      ],
+      "properties": {
+        "runId": { "type": "string" },
+        "command": { "type": "string" },
+        "requestedTasks": { "type": "array", "items": { "type": "string" } },
+        "cachePolicy": { "type": "string" },
+        "concurrency": { "type": "integer" },
+        "flow": { "enum": ["focused", "broad", null] },
+        "startedAt": { "type": "integer", "description": "epoch ms" },
+        "endedAt": { "type": "integer", "description": "epoch ms" },
+        "totalDurationMs": { "type": "number" },
+        "taskCount": { "type": "integer" },
+        "failedCount": { "type": "integer" },
+        "hitCount": { "type": "integer" },
+        "hitLocalCount": { "type": "integer" },
+        "hitRemoteCount": { "type": "integer" },
+        "upToDateCount": {
+          "type": "integer",
+          "description": "hits that restored nothing: the disk already matched"
+        },
+        "restoredLocalCount": {
+          "type": "integer",
+          "description": "hits that restored outputs from the local cache"
+        },
+        "restoredRemoteCount": {
+          "type": "integer",
+          "description": "hits that restored outputs from the remote cache"
+        },
+        "exitOk": { "type": "boolean" },
+        "commitSha": { "type": ["string", "null"] },
+        "branch": { "type": ["string", "null"] },
+        "dirty": { "type": ["boolean", "null"] },
+        "ci": { "type": "boolean" },
+        "ciProvider": { "type": ["string", "null"] },
+        "host": { "type": ["string", "null"] },
+        "os": { "type": ["string", "null"] },
+        "arch": { "type": ["string", "null"] },
+        "vxVersion": { "type": "string" },
+        "tags": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "project",
+        "task",
+        "status",
+        "exitCode",
+        "durationMs",
+        "startedAt",
+        "endedAt",
+        "cacheHit",
+        "restored",
+        "cached",
+        "hash",
+        "cpuMs",
+        "peakRssBytes",
+        "wallclockStartNs",
+        "wallclockEndNs",
+        "blockedBy",
+        "timedOut",
+        "sandboxViolations",
+        "notReady",
+        "forwarded"
+      ],
+      "properties": {
+        "runId": { "type": ["string", "null"] },
+        "project": { "type": "string" },
+        "task": { "type": "string" },
+        "status": { "type": "string" },
+        "exitCode": { "type": "integer" },
+        "durationMs": { "type": "number" },
+        "startedAt": { "type": "integer", "description": "epoch ms" },
+        "endedAt": { "type": "integer", "description": "epoch ms" },
+        "cacheHit": {
+          "type": ["boolean", "null"],
+          "description": "true when the task's outputs came from the cache instead of running"
+        },
+        "restored": {
+          "type": ["boolean", "null"],
+          "description": "on a hit: true when outputs were restored, false when up-to-date"
+        },
+        "cached": {
+          "type": ["boolean", "null"],
+          "description": "whether the task declares a cache (false prints no-cache); not whether this run hit it"
+        },
+        "hash": { "type": "string" },
+        "cpuMs": { "type": ["number", "null"] },
+        "peakRssBytes": { "type": ["integer", "null"] },
+        "wallclockStartNs": {
+          "type": ["string", "null"],
+          "description": "decimal nanoseconds from the run's start"
+        },
+        "wallclockEndNs": { "type": ["string", "null"] },
+        "blockedBy": { "type": ["string", "null"] },
+        "timedOut": { "type": ["boolean", "null"] },
+        "sandboxViolations": { "type": ["integer", "null"] },
+        "notReady": { "enum": ["timeout", "exited", "spawn", null] },
+        "forwarded": { "type": "boolean" },
+        "output": {
+          "type": "string",
+          "description": "on a failed row: its output, plain text, bounded (first 8 KiB, last 56 KiB), secrets masked; '' when none was recorded"
+        },
+        "locations": {
+          "type": "array",
+          "description": "on a failed row: the existing files its output names, in order of first appearance",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file"],
+            "properties": {
+              "file": { "type": "string", "description": "absolute" },
+              "line": { "type": "integer" },
+              "col": { "type": "integer" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/lock.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx lock --check --format json",
+  "description": "The lock audit: exit 0 when upToDate, else 1 with each drift in problems.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["upToDate", "audited", "notAudited", "problems"],
+  "properties": {
+    "upToDate": { "type": "boolean" },
+    "audited": { "type": "integer", "description": "projects with a vx.config, each audited" },
+    "notAudited": {
+      "type": "integer",
+      "description": "projects without a vx.config: nothing to freeze, never audited"
+    },
+    "problems": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "one line per drift, as the plain audit prints it on stderr; a missing lock is one"
+    }
+  }
+}

package/schemas/plan.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx run --dry=json",
+  "description": "The task graph a run would execute and what the cache predicts for each task; nothing runs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["tasks"],
+  "properties": {
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "project", "task", "hash", "cacheStatus", "deps"],
+        "properties": {
+          "id": { "type": "string", "description": "project#task" },
+          "project": { "type": "string" },
+          "task": { "type": "string" },
+          "hash": { "type": "string", "description": "the cache key" },
+          "cacheStatus": {
+            "enum": ["hit-local", "hit-remote", "miss", "no-cache", "group", "not-started"]
+          },
+          "deps": { "type": "array", "items": { "type": "string" } },
+          "p50Ms": {
+            "type": "number",
+            "description": "typical executed duration, when history has one"
+          },
+          "executor": {
+            "type": "string",
+            "description": "where it would run; only when the workspace declares more than one executor"
+          },
+          "download": {
+            "const": "deferred",
+            "description": "outputs would stay remote (--download)"
+          },
+          "description": { "type": "string" },
+          "affected": {
+            "type": "object",
+            "description": "why --affected kept this requested task; absent on a dependency it pulled in",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+              "kind": {
+                "enum": ["input", "project", "package", "named", "selected"],
+                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
+              },
+              "file": { "type": "string", "description": "the changed file, workspace-relative" },
+              "project": { "type": "string", "description": "the changed package (kind package)" },
+              "via": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "the dependsOn chain, nearest first, to the task the change reached"
+              }
+            }
+          }
+        }
+      }
+    },
+    "predicted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wallMs", "workMs", "unknownCount", "criticalPath"],
+      "properties": {
+        "wallMs": { "type": "number" },
+        "workMs": { "type": "number" },
+        "unknownCount": {
+          "type": "integer",
+          "description": "would-run tasks with no history; the times are lower bounds when above 0"
+        },
+        "criticalPath": {
+          "type": "array",
+          "description": "the would-run task ids with history along the chain wallMs measures, dependencies first",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "downloadDowngrades": {
+      "type": "array",
+      "description": "producers --download wanted to defer but could not, and why",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["taskId", "reason"],
+        "properties": { "taskId": { "type": "string" }, "reason": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/show.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx show --format json",
+  "description": "`vx show` lists projects; `vx show <project>` prints one project's resolved config; `vx show <project>#<task>` one task's; `vx show <task>` that task in every project declaring it. A secret value is masked.",
+  "oneOf": [
+    { "type": "array", "items": { "$ref": "#/$defs/listRow" } },
+    { "$ref": "#/$defs/project" },
+    { "$ref": "#/$defs/task" },
+    { "type": "array", "items": { "$ref": "#/$defs/task" } }
+  ],
+  "$defs": {
+    "listRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "tags", "tasks"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": {
+          "type": "string",
+          "description": "relative to the workspace root, POSIX separators"
+        },
+        "tags": { "$ref": "#/$defs/stringList" },
+        "tasks": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "config"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string" },
+        "config": {
+          "type": ["object", "null"],
+          "description": "null when the package has no vx config and no plugin gave it one",
+          "additionalProperties": false,
+          "properties": {
+            "tags": { "$ref": "#/$defs/stringList" },
+            "tasks": { "type": "object", "additionalProperties": { "$ref": "#/$defs/taskConfig" } }
+          }
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "task", "config"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string" },
+        "task": { "type": "string" },
+        "config": { "$ref": "#/$defs/taskConfig" }
+      }
+    },
+    "stringList": { "type": "array", "items": { "type": "string" } },
+    "taskConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "dependsOn": { "$ref": "#/$defs/stringList" },
+        "exec": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["command"],
+          "properties": {
+            "command": { "type": "string" },
+            "remote": { "enum": [true, false, "only"] },
+            "timeout": { "type": "number", "description": "ms" },
+            "retries": { "type": "integer" },
+            "env": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "passThrough": { "$ref": "#/$defs/stringList" },
+                "define": { "type": "object", "additionalProperties": { "type": "string" } },
+                "secret": { "$ref": "#/$defs/stringList" }
+              }
+            },
+            "persistent": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": { "readyWhen": { "type": "string" } }
+            },
+            "interactive": { "type": "boolean" },
+            "sandbox": {
+              "type": "object",
+              "description": "as declared; its fields are the `exec.sandbox` section of the config schema"
+            }
+          }
+        },
+        "cache": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["inputs", "outputs"],
+          "properties": {
+            "inputs": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files"],
+              "properties": {
+                "files": { "$ref": "#/$defs/stringList" },
+                "workspaceFiles": { "$ref": "#/$defs/stringList" },
+                "env": { "$ref": "#/$defs/stringList" },
+                "tasks": { "$ref": "#/$defs/stringList" },
+                "runtime": { "$ref": "#/$defs/stringList" },
+                "workspaceRuntime": { "$ref": "#/$defs/stringList" }
+              }
+            },
+            "outputs": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files"],
+              "properties": {
+                "files": { "$ref": "#/$defs/stringList" },
+                "workspaceFiles": { "$ref": "#/$defs/stringList" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/summary.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx run --summarize",
+  "description": "Every task's outcome in one run: <cacheDir>/runs/<runId>.json, or the --summarize=<path> file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runId",
+    "ok",
+    "exitCode",
+    "startedAt",
+    "endedAt",
+    "totalMs",
+    "savedMs",
+    "tasks",
+    "aborted",
+    "summary"
+  ],
+  "properties": {
+    "runId": { "type": "string" },
+    "ok": { "type": "boolean", "description": "the run's verdict: exitCode is 0" },
+    "exitCode": { "type": "integer" },
+    "startedAt": { "type": "string", "description": "ISO 8601" },
+    "endedAt": { "type": "string", "description": "ISO 8601" },
+    "totalMs": { "type": "number" },
+    "savedMs": {
+      "type": "number",
+      "description": "what the cache hits skipped: the sum of their storedDurationMs"
+    },
+    "tasks": {
+      "type": "array",
+      "description": "every counted task: not a group, not aborted",
+      "items": { "$ref": "#/$defs/task" }
+    },
+    "aborted": {
+      "type": "array",
+      "description": "tasks a shutdown signal killed; in no bucket and no total",
+      "items": { "$ref": "#/$defs/task" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "successful",
+        "failed",
+        "skipped",
+        "cachedLocal",
+        "restoredLocal",
+        "restoredRemote",
+        "upToDate",
+        "cachedRemote",
+        "aborted",
+        "total"
+      ],
+      "properties": {
+        "successful": { "type": "integer" },
+        "failed": { "type": "integer" },
+        "skipped": { "type": "integer" },
+        "cachedLocal": { "type": "integer" },
+        "restoredLocal": { "type": "integer" },
+        "restoredRemote": { "type": "integer" },
+        "upToDate": { "type": "integer" },
+        "cachedRemote": { "type": "integer" },
+        "aborted": { "type": "integer" },
+        "total": { "type": "integer" }
+      }
+    }
+  },
+  "$defs": {
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "project", "task", "status", "exitCode", "durationMs", "hash"],
+      "properties": {
+        "id": { "type": "string" },
+        "project": { "type": "string" },
+        "task": { "type": "string" },
+        "status": {
+          "enum": ["success", "cache-hit", "cache-hit-remote", "failed", "skipped", "aborted"]
+        },
+        "exitCode": { "type": "integer" },
+        "durationMs": { "type": "number" },
+        "hash": { "type": ["string", "null"] },
+        "restored": {
+          "type": "boolean",
+          "description": "on a hit only: true when outputs were restored, false when they were already up to date"
+        },
+        "noCache": {
+          "const": true,
+          "description": "the task declares no cache block: it could never hit"
+        },
+        "flaky": {
+          "type": "object",
+          "description": "this key both passed and failed on record, or the task needed a retry",
+          "additionalProperties": false,
+          "required": ["passes", "failures", "attempts"],
+          "properties": {
+            "passes": { "type": "integer" },
+            "failures": { "type": "integer" },
+            "attempts": { "type": "integer" }
+          }
+        },
+        "cpuMs": { "type": "number" },
+        "peakRssBytes": { "type": "integer" },
+        "storedDurationMs": {
+          "type": "number",
+          "description": "a hit: how long the producing execution ran, what the hit skipped"
+        },
+        "storedCpuMs": {
+          "type": "number",
+          "description": "a hit: what the producing execution used"
+        },
+        "storedPeakRssBytes": { "type": "integer" },
+        "admissionHeldMs": {
+          "type": "number",
+          "description": "an admit policy held it with a worker free"
+        },
+        "blockedBy": {
+          "type": "string",
+          "description": "a skipped task: the failed task at the root of what blocked it"
+        },
+        "timedOut": { "const": true },
+        "sandboxViolations": { "type": "integer" },
+        "notReady": { "enum": ["timeout", "exited", "spawn"] },
+        "wallclockStartNs": {
+          "type": "string",
+          "description": "decimal nanoseconds from the run's start"
+        },
+        "wallclockEndNs": { "type": "string" }
+      }
+    }
+  }
+}