@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/cli/cancel.js

@@ -0,0 +1,75 @@
+/**
+ * `mason cancel <session>`: stops the statement a session of the Postgres API is running, exactly as a client's own
+ * cancel (the protocol's CancelRequest) stops it — the listener's one path (src/api/postgres/server.ts `interrupt`),
+ * through the run's `POST /api/cancel` (src/cli/run-server.ts). The client is told 57014 "canceling statement due to
+ * user request", and the request log records it as cancelled. `mason logs --running` lists the sessions.
+ */
+import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { out as styleOut } from "./style.js";
+import { callRun } from "./control.js";
+import { reach } from "./state.js";
+import { guarded, oneLine, runFailure, spanText } from "./commands.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+export const CANCEL_USAGE = `usage: mason cancel <session> [--statement <n>] [--json]
+
+  Stops the statement a session of the Postgres API is running now, as the client's own cancel would: the client is
+  told "canceling statement due to user request" (SQLSTATE 57014), its session stays open, and the request log keeps
+  the statement as cancelled. mason logs --running lists the statements running now, with their sessions and numbers.
+
+    mason logs --running
+    mason cancel 12 --statement 340
+    mason cancel 12
+
+  --statement <n>   only that statement (its number in mason logs --running): if it ended and the session runs
+                    another, nothing is cancelled and the answer says so. Without it, whatever the session runs now
+                    is stopped, as a client's own cancel stops it.
+  --json            as data: { cancelled: { session, statement, user, applicationName, method, startedAt, runningMs,
+                    rows, query, queryTruncated } (the statement it stopped), next }
+`;
+export const CANCEL = {
+    needs: "run",
+    name: "cancel",
+    summary: "stop the statement a session of the Postgres API is running, as the client's cancel would: mason cancel 12",
+    usage: CANCEL_USAGE,
+    options: { statement: { type: "string" }, json: { type: "boolean" } },
+    json: ["cancelled", "next"],
+};
+export async function cancel(argv) {
+    const f = parseCommand(CANCEL, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    const running = ["mason logs --running", "the statements running now, with their sessions"];
+    if (f.positionals.length !== 1 || !/^[1-9]\d*$/.test(f.positionals[0])) {
+        return failed("cancel", { message: f.positionals.length === 0 ? "name the session: mason cancel <session>" : `${f.positionals.join(" ")} is not a session's number`,
+            code: "usage", fix: "mason logs --running lists each statement running with its session", next: [running], usage: CANCEL_USAGE }, { json });
+    }
+    const session = Number(f.positionals[0]);
+    const statement = f.values.statement;
+    if (statement !== undefined && (typeof statement !== "string" || !/^[1-9]\d*$/.test(statement))) {
+        return failed("cancel", { message: `--statement ${String(statement)} is not a statement's number`, code: "usage",
+            fix: "mason logs --running lists each statement running with its number", next: [running], usage: CANCEL_USAGE }, { json });
+    }
+    const w = await reach(CANCEL, json);
+    if (w === null || !("run" in w))
+        return 1;
+    const run = w.run;
+    return guarded("cancel", json, async () => {
+        const r = await callRun(run, "POST", "/api/cancel", { session, ...(statement !== undefined ? { statement: Number(statement) } : {}) });
+        if (r.status !== 200)
+            return failed("cancel", runFailure(r, [running]), { json });
+        const c = r.body.cancelled;
+        const next = [[`mason logs --requests --outcome cancelled -n 5`, "the statements cancelled, this one among them once it ended"], running];
+        if (json) {
+            out(jsonText(CANCEL, { cancelled: c }, next));
+            return 0;
+        }
+        out(reportText({
+            headline: `Cancelled session ${c.session}'s statement: it ends now, and its client gets a "canceling statement" error.`,
+            details: [["Statement", oneLine(c.query) || "(no statement)"], ["Client", `${c.applicationName || "(no application_name)"}${c.user ? ` (user ${c.user})` : ""}`],
+                ["Running", `${spanText(c.runningMs / 1000)}, ${c.rows.toLocaleString("en-US")} row${c.rows === 1 ? "" : "s"} sent`]],
+            next,
+        }, styleOut()));
+        return 0;
+    });
+}

package/dist/src/cli/command.js

@@ -24,7 +24,7 @@ export function parseCommand(spec, argv) {
         parsed = parseArgs({ args: argv, options: { ...spec.options, ...HELP }, allowPositionals: true });
     }
     catch (e) {
-        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv) });
+        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
     }
     if (parsed.values.help) {
         process.stdout.write(spec.usage);
@@ -76,8 +76,9 @@ export function nextJson(steps = []) {
     return steps.map(([command, what]) => what ? { command, what } : { command });
 }
 /** Whether a command line asked for data: `--json` anywhere on it (read before the line is parsed, so a wrong line
- *  is answered in JSON too). */
-export const wantsJson = (argv) => argv.includes("--json");
+ *  is answered in JSON too) — never for a command whose stdout is a protocol's (`CommandSpec.stdout`), whose every
+ *  failure is said on stderr. */
+export const wantsJson = (argv, spec) => spec?.stdout !== "protocol" && argv.includes("--json");
 /**
  * A COMMAND'S --json ANSWER (an agent wants clear, unambiguous context and a machine-readable format, and a person
  * and an agent both want the next steps): one JSON object on stdout, always with `next` — the same steps the human
@@ -104,6 +105,7 @@ export const FAILURE_CODES = {
     no_project: "no Mason project here or above (mason init makes one)",
     bad_config: "this folder is a Mason project whose .mason/config.json cannot be read: repair it, or move .mason/ aside and mason init",
     bad_source: "the project's sources file (mason/sources/<name>.yml) is missing or names something wrong: the file, the key and the way out are said",
+    bad_roles: "the project's roles file (mason/roles.yml) names something wrong: a table the sources file does not sync, a column the synced table lacks, a role with no table; the file, the key and the way out are said",
     not_running: "Mason is not running for the project (mason start)",
     unreachable: "Mason is running but does not answer (mason logs says why)",
     not_found: "a name nothing has: a table, a column, a user",