stack/packages/cli/src/instances.mjs

// `mosaic business instances` and `mosaic business instance add|set` (row 165, #1662, Q171,
// REQ-ROLE-3): the human reads, adds and changes role instances through the broker's instances
// and instances.set verbs, and with --tester the tester does (row 175, #1673, Q173). The broker
// refuses an agent and a reader; the business package's instance writer refuses a stale revision
// and every document `mosaic business validate` would refuse, and logs the change with its actor.
// Row 194 (#1692, D1): `business instance launch|terminate|regenerate|delete` and `business veto`.
// Rename r2 stage B: `mosaic org instances|instance|veto` is the primary spelling of all of these,
// with the same arguments and this same code (orgInstancesCommand). Only the usage text differs;
// the refusal reasons below still name the old spelling, which keeps working.
// Launch, regenerate and delete are requests the launcher's pass carries out. The command polls
// instance.request until the request closes or --wait runs out (D1.1 item 5).
import { readFileSync } from "node:fs";
import { CliError } from "./errors.mjs";

export const INSTANCES_USAGE = "mosaic business instances BUSINESS [--json] [--tester] | " +
  "business instance add BUSINESS INSTANCE --definition DEF [--vars FILE] [--launch] [--bot BOT --bot-id N] --revision REV [--tester] | " +
  "business instance set BUSINESS INSTANCE [--definition DEF] [--vars FILE] [--launch | --no-launch] --revision REV [--tester] | " +
  "business instance launch|regenerate BUSINESS INSTANCE [--wait SECONDS] [--tester] | " +
  "business instance terminate BUSINESS INSTANCE [--reason TEXT] [--tester] | " +
  "business instance delete BUSINESS INSTANCE --revision REV [--wait SECONDS] | " +
  "business veto BUSINESS keep|unkeep INSTANCE --revision REV | business veto BUSINESS nohire|hire DEFINITION --revision REV";

// Rename r2 stage B: the primary spelling. `mosaic org instances|instance|veto` takes the same
// arguments and runs the same command through the same proof-bearing call; only the usage text it
// prints for bad arguments reads `org`. Output and refusals are byte for byte the old spelling's.
export const ORG_INSTANCES_USAGE = INSTANCES_USAGE.replace(/^mosaic business /, "mosaic org ")
  .replaceAll(" | business ", " | org ").replaceAll("BUSINESS", "ORG");

// The bus answers a refusal with its code alone, so the reason a human reads is here.
export const REASONS = {
  "organization-credentials-out-of-scope": "only add binds credentials, as store references; set refuses a definition that " +
    "declares them and a definition change on an instance that holds them, and delete refuses a file or env reference; " +
    "those stay a hand edit of the business file",
  // Row 194 (brief item 7, sage-1610 a): add names an existing Vikunja bot; it makes no account.
  "organization-tracker-required": "the definition uses vikunja; add needs --bot BOT --bot-id N, an existing Vikunja bot",
  "organization-tracker-bot-taken": "another instance already uses that Vikunja bot name or id",
  "organization-instance-exists": "the business already has that instance; change it with `mosaic business instance set`",
  "organization-unknown-instance": "the business has no such instance; add it with `mosaic business instance add`",
  "organization-definition-refused": "this command neither adds nor changes an assistant, and moves no instance to the assistant " +
    "definition; an assistant changes only through `mosaic limits set` with an assistants patch",
  "organization-launch-not-configured": "the business file has no launch block, so launch membership can't change",
  "organization-no-change": "the business file already says that",
  "organization-project-mismatch": "a project file's id differs from its key in the business file; `mosaic business validate` shows it",
  "organization-unresolvable-instance": "an instance wouldn't resolve against a project file; `mosaic business validate` shows why",
  "revision-conflict": "the business file changed since that revision; read it again with `mosaic business instances`",
  // Row 194 (#1692): the lifecycle and veto refusals.
  "organization-instance-referenced": "the instance is launch.by or an arbiter; change that reference first",
  "organization-instance-kept": "the instance is kept; run `mosaic business veto BUSINESS unkeep INSTANCE` first",
  "organization-instance-retired": "that name was deleted and stays retired; pick another name",
  "instance-running": "the instance has a run; end it with `mosaic business instance terminate` first",
  "instance-starting": "a request for the instance has not closed yet; wait for it and try again",
  "instance-retired": "that name was deleted and launches no more",
  "not-thread-launch": "a thread instance starts on a thread message, not by launch",
  "regenerate-thread": "a thread instance isn't regenerated; its context is the thread's",
  "not-held": "the instance has no run and no open request",
  "launch-revoked": "launches are revoked for the business; `mosaic launches on --business BUSINESS` lifts it",
  "launches-disabled": "the bus host was started with --no-launch",
  "request-expired": "the launcher didn't take the request within its 60 s",
  "regenerate-timeout": "the old run didn't exit within the request's 60 s, so no new run started; it still runs",
  "workspace-rename-failed": "the business file is changed and the name retired, but the workspace stayed where it was; " +
    "run the same delete again to retry the rename",
  // Row 194 (brief item 8, deviation 11, sage-1620): a delete revokes before it writes, so a failure can
  // leave tokens revoked with the instance still listed. It holds nothing it can use, and a retry is safe.
  "credential-revoke-failed": "a credential couldn't be revoked, so the business file is unchanged; tokens already revoked " +
    "stay revoked and the instance can't use them; clear what else the agent's store directory holds and run the same " +
    "command again, which is safe",
  // Row 239 (#1745): a fire's or a delete's revoke runs under the writer's lock; these follow one that ran.
  "revision-conflict-revoked": "the business file changed after the agent's tokens were revoked and before the write, so " +
    "the file is unchanged; the tokens may already be revoked and the instance can't use them; read it again with " +
    "`mosaic business instances` and run the same command again, which is safe",
  "outcome-unknown-revoked": "the agent's tokens may already be revoked and the write's outcome is unknown; read the " +
    "business file again with `mosaic business instances` before trying again",
  "capacity-full": "a launch limit is reached; `mosaic limits --business BUSINESS` shows them",
  "limit-reached": "a launch limit is reached; `mosaic limits --business BUSINESS` shows them",
  "unknown-role": "the business has no such instance",
};

const LIFECYCLE_OPS = ["launch", "terminate", "regenerate", "delete"];
const VETO_OPS = ["keep", "unkeep", "nohire", "hire"];
const WAIT_SECONDS = 30;
const POLL_MS = 200;

export const RESTART_NEEDED = "restart needed: the running bus keeps the roles it loaded at start; this command does not restart it";
const NO_RESTART = "no restart: the launcher reads the change at its next launch check";

function parse(args) {
  const out = { positional: [], flags: new Set(), values: {} };
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    if (["--json", "--launch", "--no-launch", "--tester"].includes(arg)) {
      if (out.flags.has(arg)) throw new CliError(INSTANCES_USAGE, 4);
      out.flags.add(arg);
    } else if (["--definition", "--vars", "--revision", "--wait", "--reason", "--bot", "--bot-id"].includes(arg)) {
      if (!args[i + 1] || Object.hasOwn(out.values, arg)) throw new CliError(INSTANCES_USAGE, 4);
      out.values[arg] = args[++i];
    } else if (arg.startsWith("--")) throw new CliError(INSTANCES_USAGE, 4);
    else out.positional.push(arg);
  }
  return out;
}

// The args instances.set takes, from `instance add|set`. A usage error is exit 4 before any call.
function setArgs(parsed) {
  const [, op, , instance] = parsed.positional;
  const { values, flags } = parsed;
  if (values["--wait"] !== undefined || values["--reason"] !== undefined) throw new CliError(INSTANCES_USAGE, 4);
  const bot = values["--bot"] !== undefined || values["--bot-id"] !== undefined;
  if (bot && (op !== "add" || values["--bot"] === undefined || !/^[0-9]{1,15}$/.test(values["--bot-id"] ?? ""))) {
    throw new CliError(INSTANCES_USAGE, 4);
  }
  const launch = flags.has("--launch") ? true : flags.has("--no-launch") ? false : undefined;
  if (parsed.positional.length !== 4 || !["add", "set"].includes(op) || !values["--revision"] || flags.has("--json") ||
      (flags.has("--launch") && flags.has("--no-launch")) || (op === "add" && (!values["--definition"] || launch === false)) ||
      (op === "set" && !values["--definition"] && !values["--vars"] && launch === undefined)) {
    throw new CliError(INSTANCES_USAGE, 4);
  }
  const args = { revision: values["--revision"], instance, op: op === "add" ? "add" : "change" };
  if (values["--definition"]) args.definition = values["--definition"];
  if (values["--vars"]) {
    try {
      args.vars = JSON.parse(readFileSync(values["--vars"], "utf8"));
    } catch (error) {
      throw new CliError(`--vars ${values["--vars"]}: ${error.message}`, 4);
    }
  }
  if (launch !== undefined) args.launch = launch;
  if (bot) args.tracker = { bot: values["--bot"], botId: Number(values["--bot-id"]) };
  return args;
}

// Row 194: the lifecycle and veto args, or null when `instance OP` is add or set. Usage errors exit 4.
function lifecycleArgs(parsed) {
  const { positional, values, flags } = parsed;
  const [sub, op, , name] = positional;
  const only = (allowed) => Object.keys(values).every((k) => allowed.includes(k)) && [...flags].every((f) => allowed.includes(f));
  let wait = WAIT_SECONDS;
  if (values["--wait"] !== undefined) {
    if (!/^[0-9]{1,3}$/.test(values["--wait"]) || Number(values["--wait"]) > 600) throw new CliError(INSTANCES_USAGE, 4);
    wait = Number(values["--wait"]);
  }
  if (sub === "veto") {
    const [, , vop, target] = positional;
    if (positional.length !== 4 || !VETO_OPS.includes(vop) || !values["--revision"] || !only(["--revision"])) throw new CliError(INSTANCES_USAGE, 4);
    return { verb: "veto.set", args: { revision: values["--revision"], op: vop, name: target } };
  }
  if (!LIFECYCLE_OPS.includes(op)) return null;
  if (positional.length !== 4) throw new CliError(INSTANCES_USAGE, 4);
  if (op === "terminate") {
    if (!only(["--reason", "--tester"])) throw new CliError(INSTANCES_USAGE, 4);
    return { verb: "instance.end", args: { instance: name, ...(values["--reason"] !== undefined ? { reason: values["--reason"] } : {}) } };
  }
  if (op === "delete") {
    if (!values["--revision"] || !only(["--revision", "--wait"])) throw new CliError(INSTANCES_USAGE, 4);
    return { verb: "instances.set", args: { revision: values["--revision"], instance: name, op: "delete" }, wait };
  }
  if (!only(["--wait", "--tester"])) throw new CliError(INSTANCES_USAGE, 4);
  return { verb: `instance.${op}`, args: { instance: name }, wait };
}

// D1.1 item 5: polls instance.request until the request closes or `wait` seconds pass. A closed
// request with a refusal or a cancel is exit 3 (refused) with its code. Still open or taken at the
// end is exit 3 with the request id, as the design's timeout is: a taken request with no done is
// outcome-unknown.
async function follow(call, request, wait) {
  const end = Date.now() + wait * 1000;
  for (;;) {
    const r = await call("instance.request", { request });
    if (r.state === "closed") {
      if (r.cancelled) throw refusal("request-cancelled", `cancelled by ${r.cancelled.by} (request ${request})`);
      if (r.done?.refusal) {
        const kept = r.done.transaction ? `, transaction ${r.done.transaction}` : "";
        throw refusal(r.done.refusal, `${REASONS[r.done.refusal] ?? "the launcher refused the request"} (request ${request}${kept})`);
      }
      return r;
    }
    if (Date.now() >= end) {
      const error = r.state === "taken"
        ? new CliError(`outcome-unknown: request ${request} was taken and has not closed after ${wait} s; the launch log names any run it started`, 3)
        : new CliError(`request ${request} is still open after ${wait} s; the launcher takes it within its 60 s or closes it request-expired`, 3);
      error.code = r.state === "taken" ? "outcome-unknown" : "request-open";
      error.final = true;
      throw error;
    }
    await new Promise((resolve) => setTimeout(resolve, Math.min(POLL_MS, Math.max(0, end - Date.now()))));
  }
}

// `final`: the catch below passes it on as it is, with its request id.
function refusal(code, why) {
  const error = new CliError(`${code}: ${why}`, 3);
  error.code = code;
  error.final = true;
  return error;
}

function lifecycleLine(business, op, instance, r) {
  if (op === "delete") {
    const bot = r.done.bot ? `tracker bot ${r.done.bot}: remove the Vikunja bot user and any token it holds by hand in Vikunja\n` : "";
    return `business ${business}: deleted ${instance}, now retired\ntransaction ${r.done.transaction}\n${bot}`;
  }
  return `business ${business}: ${op === "launch" ? "launched" : "regenerated"} ${instance}, run ${r.done.run} (request ${r.request})\n`;
}

function terminateLines(business, instance, out) {
  const lines = [`business ${business}: ended ${instance} (request ${out.request})`];
  lines.push(out.runs.length ? `runs ${out.runs.join(", ")}: claims revoked, the launcher signals each` : "no run held a claim");
  if (out.cancelled.length) lines.push(`cancelled ${out.cancelled.join(", ")}`);
  if (out.taken.length) lines.push(`taken ${out.taken.join(", ")}: past cancelling; a run it starts is ended by the launcher's pass, or by a second terminate`);
  return `${lines.join("\n")}\n`;
}

export function formatInstances(view) {
  const lines = [`business ${view.business}, revision ${view.revision}`];
  for (const [name, entry] of Object.entries(view.instances)) {
    const marks = [entry.launcher && "launcher", entry.launched && "launched", entry.protected && "protected", entry.kept && "kept",
      entry.running?.length && `running ${entry.running.join(", ")}`].filter(Boolean);
    const vars = Object.keys(entry.vars).length ? ` vars ${JSON.stringify(entry.vars)}` : "";
    lines.push(`  ${name}: ${entry.definition}${marks.length ? ` (${marks.join(", ")})` : ""}${vars}`);
  }
  const definitions = Object.entries(view.definitions);
  const accepted = definitions.filter(([, d]) => d.accepted).map(([name]) => name);
  const bound = definitions.filter(([, d]) => d.services.length).map(([name, d]) => `${name} (${d.services.join(", ")})`);
  lines.push(`definitions add and set accept: ${accepted.join(", ") || "none"}`);
  if (bound.length) lines.push(`definitions that declare credentials, added with store references and a restart: ${bound.join(", ")}`);
  if (view.retired?.length) lines.push(`retired: ${view.retired.join(", ")}`);
  if (view.noHire?.length) lines.push(`the chief may not hire: ${view.noHire.join(", ")}`);
  return `${lines.join("\n")}\n`;
}

// args are the words after `mosaic org`; the same command as instancesCommand, with the org usage.
export async function orgInstancesCommand(args, io, callFor) {
  try {
    return await instancesCommand(args, io, callFor);
  } catch (error) {
    if (error instanceof CliError && error.message === INSTANCES_USAGE) throw new CliError(ORG_INSTANCES_USAGE, error.exitCode);
    throw error;
  }
}

// args are the words after `mosaic business`. callFor(parsed) returns the human's call(verb, args).
export async function instancesCommand(args, io, callFor) {
  const parsed = parse(args);
  const sub = parsed.positional[0];
  const business = parsed.positional[sub === "instance" ? 2 : 1];
  if (!["instances", "instance", "veto"].includes(sub) || !business) throw new CliError(INSTANCES_USAGE, 4);
  let request;
  const lifecycle = sub === "instances" ? null : lifecycleArgs(parsed);
  if (lifecycle) {
    // veto and the lifecycle verbs, below.
  } else if (sub === "instances") {
    if (parsed.positional.length !== 2 || Object.keys(parsed.values).length || parsed.flags.has("--launch") || parsed.flags.has("--no-launch")) {
      throw new CliError(INSTANCES_USAGE, 4);
    }
  } else request = setArgs(parsed);
  try {
    const call = callFor({ positional: parsed.positional, flags: parsed.flags, values: { "--business": business } });
    if (lifecycle) {
      const out = await call(lifecycle.verb, lifecycle.args);
      if (sub === "veto") {
        // Row 194 b6 (webby-0094 B1): a veto says whether the reload took, as instances.set does.
        return io.stdout.write(`business ${out.business}: veto ${lifecycle.args.op} ${lifecycle.args.name}\nrevision ${out.revision}\ntransaction ${out.transaction}\n${out.restart ? RESTART_NEEDED : NO_RESTART}\n`);
      }
      const op = parsed.positional[1];
      if (op === "terminate") return io.stdout.write(terminateLines(business, lifecycle.args.instance, out));
      io.stderr.write(`mosaic: request ${out.request}, waiting up to ${lifecycle.wait} s\n`);
      return io.stdout.write(lifecycleLine(business, op, lifecycle.args.instance, await follow(call, out.request, lifecycle.wait)));
    }
    if (!request) {
      const view = await call("instances", {});
      return io.stdout.write(parsed.flags.has("--json") ? `${JSON.stringify(view, null, 2)}\n` : formatInstances(view));
    }
    const result = await call("instances.set", request);
    const entry = result.instances[request.instance];
    io.stdout.write([
      `business ${result.business}: ${request.op === "add" ? "added" : "changed"} ${request.instance} (${entry.definition}${entry.launched ? ", launched" : ""})`,
      `revision ${result.revision}`,
      `transaction ${result.transaction}`,
      result.restart ? RESTART_NEEDED : NO_RESTART,
    ].join("\n") + "\n");
  } catch (error) {
    if (error.final) throw error;
    const code = error.code;
    if (Object.hasOwn(REASONS, code)) {
      const refused = new CliError(`${code}: ${REASONS[code]}`, error.exitCode ?? 2);
      refused.code = code;
      throw refused;
    }
    if (error instanceof CliError) throw error;
    throw new CliError(error.message, 2);
  }
}