@junoflow/cli 0.12.0 → 0.14.0

package/README.md

@@ -178,6 +178,17 @@ The group's working-copy commands (`integration init`, `gen-types`,
 | `juno webhook write`          | `write_webhook`          | `id`       | change |
 | `juno webhook fire`           | `fire_webhook`           | `id`       | act    |
 
+**`job`** (external jobs)
+
+| Command                              | Tool           | Positional | Effect |
+| ------------------------------------ | -------------- | ---------- | ------ |
+| `juno job list`                      | `list_jobs`    | —          | read   |
+| `juno job get-runs`                  | `get_job_runs` | `id`       | read   |
+| `juno job write`                     | `write_job`    | `id`       | change |
+| `juno job delete`                    | `delete_job`   | `id`       | act    |
+| `juno job run [<url>] -- <command>…` | none           | ping URL   | act    |
+| `juno job ping [<url>]`              | none           | ping URL   | act    |
+
 **`credential`**
 
 | Command                    | Tool               | Positional    | Effect |
@@ -327,6 +338,51 @@ exits 1 without sending anything otherwise. Any other message sent to a session
 waiting for an approval denies it, and the assistant sees the message as the
 reason.
 
+### `juno job run`
+
+Wraps a scheduled command so its runs are reported to an external job's ping URL
+(`juno job write` answers it as `url`):
+
+```bash
+juno job run https://juno.example/ping/<token> -- ./backup.sh --full
+juno job run --url-file .secrets/juno-jobs/backup -- ./backup.sh --full
+JUNO_JOB_URL=https://juno.example/ping/<token> juno job run -- python3 check.py
+```
+
+The command runs exactly as it would unwrapped: same stdin, the same stdout and
+stderr bytes as they arrive, the same exit status (`128 + N` when killed by
+signal `N`; 127, or 126 for a file that is not executable, when it cannot be
+started). Everything after `--` is the command's, flags included. Juno gets a
+`start`, then the exit status with the last 64 KiB of stdout and stderr, paired
+by a run id. The URL comes from the argument, else `--url-file` (keeps the token
+out of `ps`), else `$JUNO_JOB_URL`; nothing else is read — no instance config,
+no API key. A report that fails is retried once and then dropped silently
+(`--verbose` prints one line): Juno turns a run it never heard about into an
+overdue finding by itself. `SIGINT`, `SIGTERM` and `SIGHUP` are passed on to the
+command.
+
+The wrapper never times a command out: a run that hangs stays open, and the job
+goes down once its start plus grace has passed. A wrapper killed outright leaves
+the run open the same way.
+
+### `juno job ping`
+
+Sends one report, for a task with no command to wrap:
+
+```bash
+juno job ping --url-file .secrets/juno-jobs/digest                 # success
+juno job ping --url-file .secrets/juno-jobs/digest --start --rid r1
+juno job ping --url-file .secrets/juno-jobs/digest --exit 3 --rid r1
+juno job ping --url-file .secrets/juno-jobs/digest --fail
+```
+
+The URL comes from the same three places as `juno job run`'s. `--log` sends a
+log report, and `--rid` pairs a start with its finish. A report that still fails
+after one retry exits 1 with the reason.
+
+See [External jobs](https://boivie.github.io/juno/external-jobs/) for creating
+the job, the ping protocol, and systemd and crontab examples.
+
 ### `juno credential set`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Develop Juno flows, integrations and apps, and operate a Juno instance from the command line",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@junoflow/eslint-plugin": "0.12.0",
+    "@junoflow/eslint-plugin": "0.14.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {

package/src/commands/job-run.js

@@ -0,0 +1,363 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFile as nodeReadFile } from 'node:fs/promises';
+import { constants } from 'node:os';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { UsageError } from '../errors.js';
+import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
+
+export const JOB_RUN_USAGE =
+  'juno job run [<url>] [--url-file <path>] [--verbose] -- <command> [args…]';
+
+/** The tail of each stream a run reports; Juno keeps the same. */
+export const TAIL_BYTES = 64 << 10;
+
+/** The signals the wrapper passes on to the command instead of obeying. */
+const FORWARDED = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+const DEFAULT_TIMEOUTS = {
+  start: 5000,
+  finish: 10000,
+  retryDelay: 1000,
+};
+
+/**
+ * `juno job run` runs a command and reports it to an external job's ping URL
+ * (plan-external-jobs-2-wrapper-and-tools.md, Decisions 3–5). Its first rule
+ * is transparency: the command gets the same stdin, and the wrapper's stdout,
+ * stderr and exit status are the command's, byte for byte — a scheduler such
+ * as OpenClaw delivers a task's stdout as its message. Juno gets a `start`,
+ * then the exit status with the last 64 KiB of each stream. A report that
+ * fails is dropped: a run Juno never hears about becomes an overdue finding
+ * on its own, so the wrapper never queues and never fails the command.
+ *
+ * It reads no Juno config and no API key; the URL is all it needs. argv is
+ * everything after `job run`, `--` included. The exit code is returned, not
+ * passed to process.exit, so stdout is flushed before the process ends.
+ * deps is injectable for the tests; the default binds the real ones.
+ */
+export async function jobRun(argv, io, deps = {}) {
+  const {
+    spawn = nodeSpawn,
+    fetch = globalThis.fetch,
+    env = process.env,
+    readFile = nodeReadFile,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    signals = process,
+    timeouts = DEFAULT_TIMEOUTS,
+  } = deps;
+
+  const dash = argv.indexOf('--');
+  const command = dash === -1 ? [] : argv.slice(dash + 1);
+  const own = dash === -1 ? argv : argv.slice(0, dash);
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: own,
+      allowPositionals: true,
+      options: {
+        'url-file': { type: 'string' },
+        verbose: { type: 'boolean', default: false },
+      },
+    });
+  } catch (err) {
+    throw new UsageError(
+      `juno job run: ${err.message}\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  if (command.length === 0) {
+    throw new UsageError(
+      `juno job run: missing -- <command>\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  if (parsed.positionals.length > 1) {
+    throw new UsageError(
+      `juno job run: one URL before --, got ${parsed.positionals.length} arguments\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  const url = await pingURL('job run', JOB_RUN_USAGE, {
+    positional: parsed.positionals[0],
+    file: parsed.values['url-file'],
+    env,
+    readFile,
+    cwd: io.cwd,
+  });
+  const verbose = parsed.values.verbose;
+
+  const rid = randomUUID();
+  await report(fetch, endpoint(url, 'start', rid), {
+    method: 'GET',
+    timeout: timeouts.start,
+  });
+
+  const out = new Tail();
+  const err = new Tail();
+  const outcome = await runCommand(command, {
+    spawn,
+    signals,
+    onStdout: (chunk) => out.push(chunk),
+    onStderr: (chunk) => err.push(chunk),
+    stdout,
+    stderr,
+  });
+
+  let suffix;
+  let exitCode;
+  if (outcome.startError) {
+    const line = `juno job run: ${command[0]}: ${outcome.startError.message}`;
+    io.error(line);
+    err.push(Buffer.from(`${line}\n`));
+    suffix = 'fail';
+    exitCode = outcome.startError.code === 'EACCES' ? 126 : 127;
+  } else if (outcome.signal) {
+    suffix = 'fail';
+    exitCode = 128 + (constants.signals[outcome.signal] ?? 0);
+  } else {
+    suffix = String(outcome.code);
+    exitCode = outcome.code;
+  }
+
+  const finish = () => {
+    const body = new FormData();
+    body.append('stdout', new Blob([out.bytes()]), 'stdout');
+    body.append('stderr', new Blob([err.bytes()]), 'stderr');
+    return report(fetch, endpoint(url, suffix, rid), {
+      method: 'POST',
+      body,
+      timeout: timeouts.finish,
+    });
+  };
+  let failure = await finish();
+  if (failure) {
+    await new Promise((resolve) => setTimeout(resolve, timeouts.retryDelay));
+    failure = await finish();
+  }
+  if (failure && verbose) {
+    io.error(`juno job run: could not report to Juno: ${failure}`);
+  }
+  return exitCode;
+}
+
+/**
+ * pingURL is the URL from the first source that yields one: the positional,
+ * then --url-file (its contents, trimmed), then $JUNO_JOB_URL. The two
+ * indirect sources keep the token off the command line, where `ps` and the
+ * scheduler's job definition would show it. command and usage name the verb
+ * in its refusals.
+ */
+async function pingURL(
+  command,
+  usage,
+  { positional, file, env, readFile, cwd = '.' }
+) {
+  if (positional?.trim()) return positional.trim();
+  if (file !== undefined) {
+    let text;
+    try {
+      text = await readFile(resolve(cwd, file), 'utf8');
+    } catch (err) {
+      throw new UsageError(
+        `juno ${command}: --url-file ${file}: ${err.message}`
+      );
+    }
+    if (text.trim()) return text.trim();
+  }
+  if (env.JUNO_JOB_URL?.trim()) return env.JUNO_JOB_URL.trim();
+  throw new UsageError(
+    `juno ${command}: no ping URL — pass it, --url-file or JUNO_JOB_URL\nusage: ${usage}`
+  );
+}
+
+/**
+ * endpoint is `<url>/<suffix>?rid=<rid>`, used as given otherwise: no /ping/
+ * check, so a Healthchecks URL works too. A query the URL already carries is
+ * kept; without a rid there is no `rid` parameter.
+ */
+export function endpoint(url, suffix, rid) {
+  const q = url.indexOf('?');
+  const path = (q === -1 ? url : url.slice(0, q)).replace(/\/+$/, '');
+  const params = [];
+  if (q !== -1 && q < url.length - 1) params.push(url.slice(q + 1));
+  if (rid) params.push(`rid=${encodeURIComponent(rid)}`);
+  return params.length
+    ? `${path}/${suffix}?${params.join('&')}`
+    : `${path}/${suffix}`;
+}
+
+/**
+ * report sends one ping and answers why it failed, or undefined when it did
+ * not. It never throws: a ping that fails changes nothing about the command.
+ */
+async function report(fetch, url, { method, body, timeout }) {
+  try {
+    const res = await fetch(url, {
+      method,
+      body,
+      signal: AbortSignal.timeout(timeout),
+    });
+    await res.arrayBuffer().catch(() => {});
+    return res.ok ? undefined : `HTTP ${res.status}`;
+  } catch (err) {
+    return err?.cause?.message ?? err?.message ?? String(err);
+  }
+}
+
+/**
+ * runCommand spawns argv with stdin inherited and stdout and stderr piped,
+ * with no shell, and copies each chunk to the wrapper's own stream as it
+ * arrives. It resolves with `{code}`, `{signal}` or, when the command could
+ * not be started, `{startError}`. While it runs, SIGINT, SIGTERM and SIGHUP
+ * are passed on to the command, and do not end the wrapper.
+ */
+function runCommand(
+  argv,
+  { spawn, signals, onStdout, onStderr, stdout, stderr }
+) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({ startError: err });
+      return;
+    }
+
+    const forward = Object.fromEntries(
+      FORWARDED.map((sig) => [
+        sig,
+        () => {
+          try {
+            child.kill(sig);
+          } catch {
+            // Already gone: its exit is on its way.
+          }
+        },
+      ])
+    );
+    for (const [sig, fn] of Object.entries(forward)) signals.on(sig, fn);
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      for (const [sig, fn] of Object.entries(forward)) signals.off(sig, fn);
+      resolve(result);
+    };
+
+    child.stdout.on('data', onStdout);
+    child.stderr.on('data', onStderr);
+    child.stdout.pipe(stdout, { end: false });
+    child.stderr.pipe(stderr, { end: false });
+
+    child.on('error', (err) => {
+      // A spawn failure leaves no process behind; any later error is about
+      // one that did start, whose close still comes.
+      if (child.pid === undefined) settle({ startError: err });
+    });
+    child.on('close', (code, signal) => {
+      settle(signal ? { signal } : { code });
+    });
+  });
+}
+
+/**
+ * Tail keeps the last TAIL_BYTES of a stream as the chunks that arrived,
+ * dropping whole chunks from the front once over the limit and cutting the
+ * first one kept, so a long run costs at most a little over 64 KiB.
+ */
+export class Tail {
+  #chunks = [];
+  #size = 0;
+
+  push(chunk) {
+    this.#chunks.push(chunk);
+    this.#size += chunk.length;
+    while (this.#size - this.#chunks[0].length >= TAIL_BYTES) {
+      this.#size -= this.#chunks.shift().length;
+    }
+    if (this.#size > TAIL_BYTES) {
+      const cut = this.#size - TAIL_BYTES;
+      this.#chunks[0] = this.#chunks[0].subarray(cut);
+      this.#size -= cut;
+    }
+  }
+
+  bytes() {
+    return Buffer.concat(this.#chunks, this.#size);
+  }
+}
+
+export const JOB_PING_USAGE =
+  'juno job ping [<url>] [--url-file <path>] [--start | --fail | --exit <0-255> | --log] [--rid <id>]';
+
+const PING_KINDS = ['start', 'fail', 'exit', 'log'];
+
+/**
+ * `juno job ping` sends one report to an external job's ping URL, for a task
+ * `job run` cannot wrap — one whose scheduler runs no command, or whose start
+ * and finish happen in different places. Without a flag it reports success;
+ * `--start`, `--fail`, `--exit <n>` and `--log` send the other reports, and
+ * `--rid` pairs a start with its finish. It sends no output.
+ *
+ * It finds the URL as `job run` does and, like it, reads no Juno config and no
+ * API key. Unlike `job run` it has nothing else to do, so a report that still
+ * fails after one retry is exit 1 with the reason, not silence: the caller
+ * asked for exactly this and can `|| true` it.
+ */
+export async function jobPing(args, io, deps = {}) {
+  const {
+    fetch = globalThis.fetch,
+    env = process.env,
+    readFile = nodeReadFile,
+    timeouts = DEFAULT_TIMEOUTS,
+  } = deps;
+  const usage = (msg) =>
+    new UsageError(`juno job ping: ${msg}\nusage: ${JOB_PING_USAGE}`);
+
+  if (args._.length > 1) {
+    throw usage(`one URL, got ${args._.length} arguments`);
+  }
+  const kinds = PING_KINDS.filter(
+    (k) => args[k] !== undefined && args[k] !== false
+  );
+  if (kinds.length > 1) {
+    throw usage(`--${kinds.join(' and --')} are different reports; pick one`);
+  }
+  let suffix = 'success';
+  if (kinds[0] === 'exit') {
+    const n = args.exit.trim();
+    if (!/^\d{1,3}$/.test(n) || Number(n) > 255) {
+      throw usage(`--exit takes a status from 0 to 255, got "${args.exit}"`);
+    }
+    suffix = String(Number(n));
+  } else if (kinds[0]) {
+    suffix = kinds[0];
+  }
+  const url = await pingURL('job ping', JOB_PING_USAGE, {
+    positional: args._[0],
+    file: args['url-file'],
+    env,
+    readFile,
+    cwd: io.cwd,
+  });
+
+  const send = () =>
+    report(fetch, endpoint(url, suffix, args.rid), {
+      method: 'GET',
+      timeout: timeouts.finish,
+    });
+  let failure = await send();
+  if (failure) {
+    await new Promise((resolve) => setTimeout(resolve, timeouts.retryDelay));
+    failure = await send();
+  }
+  if (failure) {
+    io.error(`juno job ping: could not report to Juno: ${failure}`);
+    return EXIT_FAILURE;
+  }
+  return EXIT_OK;
+}

package/src/exit.js

@@ -12,6 +12,9 @@
  *      409 because the active version is not the copy's base_version
  *   5  `juno ask` / `session approve`: the turn is still running (pending)
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
+ *
+ * `juno job run` is the exception once its own arguments are accepted: it
+ * exits with the wrapped command's status, as a shell would report it.
  */
 export const EXIT_OK = 0;
 export const EXIT_FAILURE = 1;

package/src/index.js

@@ -29,6 +29,12 @@ import { FLOW_INIT_USAGE, flowInit } from './commands/flow-init.js';
 import { FLOW_PULL_USAGE, flowPull } from './commands/flow-pull.js';
 import { GEN_TYPES_USAGE, genTypes } from './commands/gen-types.js';
 import { INIT_USAGE, init } from './commands/init.js';
+import {
+  JOB_PING_USAGE,
+  JOB_RUN_USAGE,
+  jobPing,
+  jobRun,
+} from './commands/job-run.js';
 import { PULL_USAGE, pull } from './commands/pull.js';
 import { SKILL_USAGE, skill } from './commands/skill.js';
 import {
@@ -102,6 +108,32 @@ const NON_TOOL = {
     },
     usage: CREDENTIAL_SET_USAGE,
   },
+  // raw: everything after `--` is the wrapped command's, verbatim, so the
+  // argv goes to the handler unparsed (see runRow). No --url or --token: the
+  // wrapper reads no Juno config, only the ping URL.
+  'job run': {
+    run: (argv, io) => jobRun(argv, io, { env: io.env }),
+    options: {
+      'url-file': { type: 'string' },
+      verbose: { type: 'boolean', default: false },
+    },
+    usage: JOB_RUN_USAGE,
+    raw: true,
+  },
+  // No --url or --token either: one report to the ping URL, found as job run
+  // finds it.
+  'job ping': {
+    run: (args, io) => jobPing(args, io, { env: io.env }),
+    options: {
+      'url-file': { type: 'string' },
+      start: { type: 'boolean' },
+      fail: { type: 'boolean' },
+      exit: { type: 'string' },
+      log: { type: 'boolean' },
+      rid: { type: 'string' },
+    },
+    usage: JOB_PING_USAGE,
+  },
   'config set': { run: configSet, options: {}, usage: CONFIG_SET_USAGE },
   'agent-skill install': {
     run: agentSkillInstall,
@@ -405,6 +437,17 @@ async function showGroupHelp(group, args, io, code) {
 function runRow(row, argv, leading, io) {
   if (!row.tool) {
     const handler = handlerFor(row);
+    if (handler.raw) {
+      // Only the words before `--` are the command's own; a --help after it
+      // belongs to the wrapped program.
+      const dash = argv.indexOf('--');
+      const own = dash === -1 ? argv : argv.slice(0, dash);
+      if (own.includes('--help') || own.includes('-h')) {
+        io.log(nonToolHelp(row, handler));
+        return EXIT_OK;
+      }
+      return handler.run(argv, io);
+    }
     const run =
       row.working_copy && !handler.positional
         ? (args, io) => {

package/verbs.json

@@ -221,6 +221,10 @@
     },
     { "command": "webhook write", "tool": "write_webhook", "id_field": "id" },
     { "command": "webhook fire", "tool": "fire_webhook", "id_field": "id" },
+    { "command": "job list", "tool": "list_jobs" },
+    { "command": "job get-runs", "tool": "get_job_runs", "id_field": "id" },
+    { "command": "job write", "tool": "write_job", "id_field": "id" },
+    { "command": "job delete", "tool": "delete_job", "id_field": "id" },
     { "command": "credential list", "tool": "list_credentials" },
     { "command": "person list", "tool": "list_people" },
     { "command": "person get", "tool": "get_person", "id_field": "id" },
@@ -271,6 +275,16 @@
       "effect": "act",
       "summary": "Approve the tool call an assistant session is waiting on"
     },
+    {
+      "command": "job run",
+      "effect": "act",
+      "summary": "Run a command and report it to an external job's ping URL"
+    },
+    {
+      "command": "job ping",
+      "effect": "act",
+      "summary": "Send one report (success, start, fail, an exit status or a log) to an external job's ping URL"
+    },
     {
       "command": "credential set",
       "effect": "act",