@colony2/c2j 0.0.22 → 0.0.24

package/README.md

@@ -6,6 +6,8 @@ Use it when you want to:
 
 - submit a recipe job from a named recipe or a local recipe file
 - run or continue an existing job
+- count and claim available jobs for external scheduling
+- run a tenant worker loop with bounded local concurrency
 - use the embedded local runtime for fast iteration
 - inspect the current cell configuration used for job targeting
 - list jobs for a cell
@@ -19,7 +21,11 @@ c2j self
 c2j cells
 c2j init
 c2j submit
-c2j exec
+c2j run
+c2j run one
+c2j run any
+c2j run loop
+c2j ready
 c2j list
 c2j test
 ```
@@ -85,7 +91,7 @@ c2j list --self --embed
 Continue a submitted job:
 
 ```bash
-c2j exec --job-id <job-id> --embed
+c2j run --job-id <job-id> --embed
 ```
 
 ## Current Cell Commands
@@ -316,20 +322,22 @@ Useful flags:
 
 ## Running Jobs
 
-`c2j exec` executes or continues an existing job and prints live story progress to stdout.
+`c2j run` executes or continues one existing job and prints live story progress
+to stdout. `c2j run one` is the explicit form of the same command.
 
 Basic usage:
 
 ```bash
-c2j exec --job-id <job-id> --embed
+c2j run --job-id <job-id> --embed
+c2j run one --job-id <job-id> --embed
 ```
 
 Common variants:
 
 ```bash
-c2j exec --job-id <job-id> --wait-timeout 30m --embed
-c2j exec --job-id <job-id> --input-mode fail --embed
-c2j exec --job-id <job-id> --ci --embed
+c2j run --job-id <job-id> --wait-timeout 30m --embed
+c2j run --job-id <job-id> --input-mode fail --embed
+c2j run --job-id <job-id> --ci --embed
 ```
 
 Important behavior:
@@ -355,7 +363,7 @@ Important behavior:
 
 ### Not-ready handling
 
-`--on-not-ready` controls how `exec` reacts when a job is not runnable yet:
+`--on-not-ready` controls how `run` reacts when a job is not runnable yet:
 
 - `wait`
 - `fail`
@@ -364,17 +372,70 @@ Important behavior:
 - `fail-on-future`
 - `fail-on-missing-capability`
 
-With the default `wait`, `exec` will print `waiting: ...` lines and poll until the job becomes runnable or the wait timeout is reached.
+With the default `wait`, `run` will print `waiting: ...` lines and poll until
+the job becomes runnable or the wait timeout is reached.
 
 ### Exit codes
 
-`c2j exec` uses distinct exit codes:
+`c2j run` uses distinct exit codes:
 
 - `1`: general failure or job failure
 - `2`: wait timeout
 - `3`: input required
 - `4`: job not runnable under the selected policy
-- `5`: invalid job identity or invalid exec arguments
+- `5`: invalid job identity or invalid run arguments
+
+## Worker Modes
+
+`c2j run loop` runs a long-lived worker for one tenant. It leases available jobs
+from an external SWF runtime and executes up to the configured local concurrency.
+
+Basic usage:
+
+```bash
+c2j run loop --tenant-id <tenant-id> --swf-url http://localhost:9047 --concurrency 4
+```
+
+Important behavior:
+
+- `--concurrency <n>` controls how many jobs this process can run at once
+- `--tenant-id` defaults the same way as `submit`, `run`, and `list`
+- `--swf-url` must be an external `http://` or `https://` runtime
+- `--embed` is not available for `run loop`
+- `--swf-url embed:///` is rejected for `run loop`
+- `run loop` is non-interactive; use `run` or an ops surface for jobs that need input
+
+### Loose scheduling with `ready` and `run any`
+
+`c2j ready` prints the number of currently ready recipe jobs for one tenant:
+
+```bash
+c2j ready --tenant-id <tenant-id> --swf-url http://localhost:9047
+```
+
+`c2j run any` atomically polls for one available item of recipe work, leases it,
+runs it, and exits. If no lease is available, it exits successfully after
+printing `no jobs found`.
+
+```bash
+c2j run any --tenant-id <tenant-id> --swf-url http://localhost:9047
+```
+
+These can be composed by an external scheduler:
+
+```bash
+count=$(c2j ready --tenant-id <tenant-id> --swf-url http://localhost:9047)
+if [ "$count" -gt 0 ]; then
+  for _ in $(seq 1 "$count"); do
+    c2j run any --tenant-id <tenant-id> --swf-url http://localhost:9047 &
+  done
+  wait
+fi
+```
+
+`ready` is only a non-mutating snapshot and can become stale under competing
+workers. `run any` uses SWF polling so finding available work and acquiring the
+lease happen in one runtime operation.
 
 ## Listing Jobs
 
@@ -468,6 +529,8 @@ export C2J_TENANT_ID=123
 ```
 
 When `--embed` is present, it overrides `C2J_SWF_URL` for that command.
+`c2j run loop` is the exception: it does not support `--embed` and rejects
+`C2J_SWF_URL=embed:///`.
 
 ## Common Workflows
 
@@ -482,7 +545,7 @@ c2j submit --recipe-file ./recipes/my-recipe.yaml --run --embed
 
 ```bash
 c2j submit --recipe-file ./recipes/my-recipe.yaml --json --embed
-c2j exec --job-id <job-id> --embed
+c2j run --job-id <job-id> --embed
 ```
 
 ### Run against a remote runtime instead of embed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colony2/c2j",
   "type": "module",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "c2j job system",
   "scripts": {
     "postinstall": "node install.js",
@@ -26,55 +26,55 @@
   "dependencies": {
     "jszip": "3.10.1",
     "proxy-agent": "8.0.1",
-    "tar": "7.5.13"
+    "tar": "7.5.15"
   },
   "archives": {
     "darwin-arm64": {
-      "name": "c2j_0.0.22_Darwin_arm64.tar.gz",
-      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.22/c2j_0.0.22_Darwin_arm64.tar.gz",
+      "name": "c2j_0.0.24_Darwin_arm64.tar.gz",
+      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.24/c2j_0.0.24_Darwin_arm64.tar.gz",
       "bins": [
         "c2j"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "5c20d523b73e68b67ef853a63d5724339619d134c441915518367a257bf29575"
+        "digest": "34ca8f77c4f5e53c92698427f5dc054d4f60e8545dc2b4a49c9f4a02d6250682"
       }
     },
     "darwin-x64": {
-      "name": "c2j_0.0.22_Darwin_x86_64.tar.gz",
-      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.22/c2j_0.0.22_Darwin_x86_64.tar.gz",
+      "name": "c2j_0.0.24_Darwin_x86_64.tar.gz",
+      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.24/c2j_0.0.24_Darwin_x86_64.tar.gz",
       "bins": [
         "c2j"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "5b038ff429d5d3b44cc145811d5a13e7ebaac9aaa3a4f053cf0a63742b25ced5"
+        "digest": "84fbff2bb0c69598b53523169421c8d885277ae1c3053e6e48a16c817aed60ec"
       }
     },
     "linux-arm64": {
-      "name": "c2j_0.0.22_Linux_arm64.tar.gz",
-      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.22/c2j_0.0.22_Linux_arm64.tar.gz",
+      "name": "c2j_0.0.24_Linux_arm64.tar.gz",
+      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.24/c2j_0.0.24_Linux_arm64.tar.gz",
       "bins": [
         "c2j"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "de9caf6f4af2182b4e25794d6a5a71e1137130e1398d76f9cde72ac2ef2f967d"
+        "digest": "b97cf3e305c8122f44c4c403e01d64a355afa6022ffa943ccd022460e8b4a47a"
       }
     },
     "linux-x64": {
-      "name": "c2j_0.0.22_Linux_x86_64.tar.gz",
-      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.22/c2j_0.0.22_Linux_x86_64.tar.gz",
+      "name": "c2j_0.0.24_Linux_x86_64.tar.gz",
+      "url": "https://github.com/colony-2/c2j-release/releases/download/v0.0.24/c2j_0.0.24_Linux_x86_64.tar.gz",
       "bins": [
         "c2j"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "d4dfc4b2d734f3efeed4c30dbc78258595d4fd5683a272ee7ea3a53ee40c3487"
+        "digest": "31913776acc40d186c863ec0699e9ec6fa19b936f1e21691afbd51a92d9bf8df"
       }
     }
   },