@junoflow/cli 0.13.0 → 0.14.0

package/README.md

@@ -185,7 +185,9 @@ The group's working-copy commands (`integration init`, `gen-types`,
 | `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`**
 
@@ -359,6 +361,25 @@ no API key. A report that fails is retried once and then dropped silently
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.13.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.13.0",
+    "@junoflow/eslint-plugin": "0.14.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {

package/src/commands/job-run.js

@@ -6,6 +6,7 @@ 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…]';
@@ -77,7 +78,13 @@ export async function jobRun(argv, io, deps = {}) {
       `juno job run: one URL before --, got ${parsed.positionals.length} arguments\nusage: ${JOB_RUN_USAGE}`
     );
   }
-  const url = await pingURL(parsed, env, readFile, io.cwd);
+  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();
@@ -138,37 +145,46 @@ export async function jobRun(argv, io, deps = {}) {
  * 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.
+ * scheduler's job definition would show it. command and usage name the verb
+ * in its refusals.
  */
-async function pingURL(parsed, env, readFile, cwd = '.') {
-  const [positional] = parsed.positionals;
+async function pingURL(
+  command,
+  usage,
+  { positional, file, env, readFile, cwd = '.' }
+) {
   if (positional?.trim()) return positional.trim();
-  const file = parsed.values['url-file'];
   if (file !== undefined) {
     let text;
     try {
       text = await readFile(resolve(cwd, file), 'utf8');
     } catch (err) {
-      throw new UsageError(`juno job run: --url-file ${file}: ${err.message}`);
+      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 job run: no ping URL — pass it, --url-file or JUNO_JOB_URL\nusage: ${JOB_RUN_USAGE}`
+    `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.
+ * 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 query = q === -1 ? '' : `${url.slice(q + 1)}&`;
-  return `${path}/${suffix}?${query}rid=${encodeURIComponent(rid)}`;
+  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}`;
 }
 
 /**
@@ -274,3 +290,74 @@ export class Tail {
     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/index.js

@@ -29,7 +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_RUN_USAGE, jobRun } from './commands/job-run.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 {
@@ -115,6 +120,20 @@ const NON_TOOL = {
     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,

package/verbs.json

@@ -224,6 +224,7 @@
     { "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" },
@@ -279,6 +280,11 @@
       "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",