@grida/fx 0.1.0 → 0.2.1

package/dist/runs.js

@@ -0,0 +1,233 @@
+/** A project's runs through the engine's public command line (spec/store.md §8 and §9): listing
+ * them, and removing named ones. The engine finds the project from cwd, selects, locks and
+ * removes; this module only reads what it prints. */
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { call, failure, USAGE_OR_ERROR } from "./engine.js";
+import { FxError } from "./errors.js";
+/** A removal the engine refused before removing anything, with its stable code, the RUN it
+ * names and the complete error document. Usage mistakes and malformed output reject with
+ * ordinary FxError; a refused or partial run does not reject (read each entry's `outcome`). */
+export class RunRemovalError extends FxError {
+    code;
+    run;
+    result;
+    constructor(result, done) {
+        super(result.error.message, {
+            exitCode: done.status,
+            signal: done.signal,
+            stdout: done.stdout,
+            stderr: done.stderr,
+            args: done.args,
+        });
+        this.name = "RunRemovalError";
+        this.code = result.error.code;
+        this.run = result.error.run;
+        this.result = result;
+    }
+}
+const LIST_KIND = "fx-run-list-v1";
+const REMOVAL_KIND = "fx-run-removal-v1";
+const PLACEMENTS = ["allocated", "named", "explicit", "external"];
+const STATES = [
+    "planned", "unfinished", "succeeded", "failed", "incomplete", "cancelled", "empty", "removing", "missing",
+];
+const PREVIEW_OUTCOMES = ["would_remove", "would_forget", "refused"];
+const APPLIED_OUTCOMES = ["removed", "forgotten", "refused", "partial"];
+const FAILED_OUTCOMES = ["refused", "partial"];
+const RUN_CODES = ["active", "holds_pick", "changed", "not_removable", "io"];
+const REMOVAL_SKIPS = ["named", "explicit", "external", "holds_pick", "young", "holds_runs"];
+const ERROR_CODES = ["invalid_target", "ambiguous_target", "not_a_run"];
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nullableText(value) {
+    return value === null || typeof value === "string";
+}
+function count(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function entry(value, cwd) {
+    if (!object(value))
+        throw new Error("run is not an object");
+    const { folder, workflow, source, name, placement, state, created_at, charged_usd, stand_in, stopped } = value;
+    if (typeof folder !== "string" || folder === "" || folder.includes("\0"))
+        throw new Error("invalid folder");
+    if (!nullableText(workflow) || !nullableText(source) || !nullableText(name) || !nullableText(created_at)) {
+        throw new Error("invalid run text field");
+    }
+    if (!PLACEMENTS.includes(placement) || !STATES.includes(state)) {
+        throw new Error("unknown placement or state");
+    }
+    if (charged_usd !== null && (typeof charged_usd !== "number" || !Number.isFinite(charged_usd))) {
+        throw new Error("invalid charged_usd");
+    }
+    if (typeof stand_in !== "boolean" || (stopped !== undefined && typeof stopped !== "string")) {
+        throw new Error("invalid stand_in or stopped");
+    }
+    return {
+        folder,
+        runDir: resolve(cwd, folder),
+        workflow,
+        source,
+        name,
+        placement: placement,
+        state: state,
+        created_at,
+        charged_usd,
+        stand_in,
+        ...(stopped !== undefined ? { stopped } : {}),
+    };
+}
+function parseList(done, cwd) {
+    if (done.status !== 0)
+        throw new Error("unexpected status");
+    const value = JSON.parse(done.stdout);
+    if (!object(value) || value.kind !== LIST_KIND || !Array.isArray(value.runs) || !Array.isArray(value.skipped)) {
+        throw new Error("incompatible result");
+    }
+    // What could not be read is not returned, so its entries are not read: a future code must
+    // not break listing.
+    return value.runs.map((run) => entry(run, cwd));
+}
+function removalEntry(value, cwd, applied) {
+    const run = entry(value, cwd);
+    const { outcome, code, message, freed_bytes, cache_bytes } = value;
+    if (!(applied ? APPLIED_OUTCOMES : PREVIEW_OUTCOMES).includes(outcome)) {
+        throw new Error("unknown or mismatched outcome");
+    }
+    if (code !== undefined && !RUN_CODES.includes(code))
+        throw new Error("unknown code");
+    if (message !== undefined && typeof message !== "string")
+        throw new Error("invalid message");
+    if (FAILED_OUTCOMES.includes(outcome) && (code === undefined || message === undefined)) {
+        throw new Error("refusal lacks code or message");
+    }
+    if (!count(freed_bytes) || !count(cache_bytes))
+        throw new Error("invalid byte counts");
+    return {
+        ...run,
+        outcome: outcome,
+        ...(code !== undefined ? { code: code } : {}),
+        ...(message !== undefined ? { message } : {}),
+        freed_bytes,
+        cache_bytes,
+    };
+}
+/** The error document of exit status 2, or null when stdout holds none. */
+function removalFailure(done) {
+    let value;
+    try {
+        value = JSON.parse(done.stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!object(value) || value.kind !== REMOVAL_KIND || value.applied !== false || !object(value.error)) {
+        return null;
+    }
+    const { code, message, run } = value.error;
+    if (!ERROR_CODES.includes(code) || typeof message !== "string" || !nullableText(run)) {
+        return null;
+    }
+    return { kind: REMOVAL_KIND, applied: false, error: { code: code, message, run } };
+}
+function parseRemoval(done, cwd, preview) {
+    const value = JSON.parse(done.stdout);
+    if (!object(value) || value.kind !== REMOVAL_KIND || "error" in value || value.applied !== !preview) {
+        throw new Error("incompatible result");
+    }
+    const { runs, skipped, freed_bytes, cache_bytes } = value;
+    if (!Array.isArray(runs) || !object(skipped) || !count(freed_bytes) || !count(cache_bytes)) {
+        throw new Error("missing or invalid fields");
+    }
+    for (const [reason, passed] of Object.entries(skipped)) {
+        if (!REMOVAL_SKIPS.includes(reason) || !count(passed) || passed < 1)
+            throw new Error("invalid skipped");
+    }
+    const entries = runs.map((run) => removalEntry(run, cwd, !preview));
+    const failed = entries.some((run) => FAILED_OUTCOMES.includes(run.outcome));
+    if (done.status !== (failed ? 1 : 0))
+        throw new Error("mismatched status");
+    return {
+        applied: !preview,
+        runs: entries,
+        skipped: { ...skipped },
+        freed_bytes,
+        cache_bytes,
+    };
+}
+function callOptions(options, cwd) {
+    return {
+        cwd,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    };
+}
+/** The runs of the project found from cwd, newest first. Reads only: no lock, no writes.
+ * Folders the engine could not read are left out. */
+export async function listRuns(options = {}) {
+    const args = ["runs", "list"];
+    if (options.workflow !== undefined) {
+        if (typeof options.workflow !== "string" || options.workflow === "" || options.workflow.includes("\0")) {
+            throw new TypeError("workflow is a nonempty workflow id without NUL");
+        }
+        args.push(`--workflow=${options.workflow}`);
+    }
+    const cwd = base(options.cwd);
+    const done = await call([...args, "--json"], callOptions(options, cwd));
+    try {
+        return parseList(done, cwd);
+    }
+    catch {
+        throw failure("runs list", done);
+    }
+}
+/** The working directory as the engine sees it: its real path, since the engine prints folders
+ * relative to its canonical working directory (resolved lexically when it cannot be read). */
+function base(cwd) {
+    const given = resolve(cwd ?? process.cwd());
+    try {
+        return realpathSync(given);
+    }
+    catch {
+        return given;
+    }
+}
+/** Remove exactly the named runs: run folders (relative to cwd) or `WORKFLOW_ID/NAME` of named
+ * runs; select them with {@link listRuns} first. Every RUN is resolved before anything is removed,
+ * and one that is not a run rejects with {@link RunRemovalError}. A run that is active, or the last
+ * holding a pick, is refused without rejecting: read each entry's `outcome`. Aborting a removal
+ * may leave a run `partial`; removing it again finishes it. */
+export async function removeRuns(runs, options = {}) {
+    if (!Array.isArray(runs) || runs.length === 0
+        || !runs.every((run) => typeof run === "string" && run !== "" && !run.includes("\0"))) {
+        throw new TypeError("runs is a nonempty array of nonempty run folders or WORKFLOW_ID/NAME, without NUL");
+    }
+    if (options.preview !== undefined && typeof options.preview !== "boolean") {
+        throw new TypeError("preview is true or false");
+    }
+    const preview = options.preview === true;
+    const cwd = base(options.cwd);
+    const done = await call(["runs", "remove", ...(preview ? [] : ["--yes"]), "--json", "--", ...runs], callOptions(options, cwd));
+    if (done.status === USAGE_OR_ERROR) {
+        const refused = removalFailure(done);
+        if (refused !== null)
+            throw new RunRemovalError(refused, done);
+        throw failure("runs remove", done);
+    }
+    try {
+        return parseRemoval(done, cwd, preview);
+    }
+    catch {
+        if (preview)
+            throw failure("runs remove", done);
+        const details = {
+            exitCode: done.status, signal: done.signal, stdout: done.stdout, stderr: done.stderr, args: done.args,
+        };
+        const what = done.status === 0 || done.status === 1
+            ? "grida-fx runs remove printed a result that could not be read"
+            : failure("runs remove", done).message;
+        throw new FxError(`${what}; the removal may already have taken effect`, details);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grida/fx",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Grida FX for JavaScript: the grida-fx command, and an SDK to build workflows and drive the engine.",
   "keywords": [
     "grida",
@@ -32,6 +32,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -42,13 +46,13 @@
   ],
   "sideEffects": false,
   "optionalDependencies": {
-    "@grida/fx-darwin-arm64": "0.1.0",
-    "@grida/fx-darwin-x64": "0.1.0",
-    "@grida/fx-linux-arm64-gnu": "0.1.0",
-    "@grida/fx-linux-x64-gnu": "0.1.0"
+    "@grida/fx-darwin-arm64": "0.2.1",
+    "@grida/fx-darwin-x64": "0.2.1",
+    "@grida/fx-linux-arm64-gnu": "0.2.1",
+    "@grida/fx-linux-x64-gnu": "0.2.1"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   }
 }