@josfox/jos 4.1.0 → 5.0.0

package/examples/14-serve.jos

@@ -0,0 +1,88 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.serve",
+  "meta": {
+    "name": "tour.serve",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Serve a read-only HTML index of ~/.jos/runs on http://127.0.0.1:8765/ for 60 s, from a temporary folder (never ~/.jos itself)",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "stopped and removed"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf",
+      "curl",
+      "wget"
+    ],
+    "limit": {
+      "seconds": 900,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "index": {
+        "engine": "shell",
+        "run": [
+          "/bin/sh",
+          "-c",
+          "dir=$(mktemp -d \"${TMPDIR:-/tmp}/jos-runs-index.XXXXXX\") || exit 1\nnode -e 'const fs = require(\"fs\"), path = require(\"path\");\nconst [runs, out] = process.argv.slice(1);\nconst esc = (s) => String(s).replace(/[&<>\"]/g, (c) => ({ \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", \"\\\"\": \"&quot;\" })[c]);\nlet ids = [];\ntry { ids = fs.readdirSync(runs).filter((n) => /^run_[0-9A-Za-z]+$/.test(n)).sort().reverse(); } catch (e) { ids = []; }\nconst rows = ids.map((id) => {\n  let es = [];\n  try { es = fs.readFileSync(path.join(runs, id, \"ledger.jsonl\"), \"utf8\").split(\"\\n\").filter(Boolean).map((l) => JSON.parse(l)); } catch (e) { es = []; }\n  const b = (e) => (e && e.body) || {};\n  const end = b(es.find((e) => e.kind === \"end\"));\n  const top = b(es.filter((e) => e.kind === \"receipt\").pop());\n  const cells = [id, top.step || \"\", end.code === undefined ? \"\" : end.code, es.length ? es[0].ts : \"\"];\n  return \"<tr>\" + cells.map((c) => \"<td>\" + esc(c) + \"</td>\").join(\"\") + \"</tr>\";\n});\nfs.writeFileSync(out, \"<!doctype html>\\n<meta charset=\\\"utf-8\\\">\\n<title>jos runs</title>\\n<h1>Runs in ~/.jos/runs</h1>\\n<p>A read-only snapshot. Check a run with <code>jos ledger verify &lt;run_id&gt;</code>.</p>\\n<table>\\n<tr><th>run</th><th>document</th><th>code</th><th>started</th></tr>\\n\" + rows.join(\"\\n\") + \"\\n</table>\\n\");\nconsole.error(ids.length + \" runs indexed\");' \"$HOME/.jos/runs\" \"$dir/index.html\" || { rmdir \"$dir\"; exit 1; }\nprintf %s \"$dir\"",
+          "index"
+        ],
+        "execution": {
+          "env": [
+            "PATH",
+            "HOME",
+            "TMPDIR"
+          ]
+        },
+        "as": "site",
+        "description": "Write index.html for ~/.jos/runs into a new temporary folder"
+      },
+      "serve": {
+        "engine": "shell",
+        "run": [
+          "/bin/sh",
+          "-c",
+          "dir=$(node -e 'let s = \"\"; process.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => { process.stdout.write(String(JSON.parse(s).input.dir)); });') || exit 2\ncase \"$dir\" in \"\"|\"$HOME/.jos\"|\"$HOME/.jos/\"*) echo \"refusing to serve $dir\" >&2; exit 2;; esac\n[ -f \"$dir/index.html\" ] || { echo \"no index in $dir\" >&2; exit 2; }\ncommand -v python3 >/dev/null 2>&1 || { echo \"python3 is not installed\" >&2; rm -f \"$dir/index.html\"; rmdir \"$dir\"; exit 3; }\nport=\"${JOS_SERVE_PORT:-8765}\"\nsecs=\"${JOS_SERVE_SECONDS:-60}\"\nlog=\"$dir.log\"\npython3 -u -m http.server \"$port\" --bind 127.0.0.1 --directory \"$dir\" >\"$log\" 2>/dev/null &\npid=$!\nn=0\nuntil grep -q '^Serving HTTP on' \"$log\" 2>/dev/null; do\n  if ! kill -0 \"$pid\" 2>/dev/null; then echo \"python3 could not serve on 127.0.0.1:$port (is the port in use?)\" >&2; rm -f \"$dir/index.html\" \"$log\"; rmdir \"$dir\"; exit 1; fi\n  if [ \"$n\" -ge 600 ]; then echo \"python3 did not start serving on 127.0.0.1:$port within 60 s\" >&2; kill \"$pid\" 2>/dev/null; wait \"$pid\" 2>/dev/null; rm -f \"$dir/index.html\" \"$log\"; rmdir \"$dir\"; exit 1; fi\n  n=$((n + 1))\n  sleep 0.1\ndone\nsleep \"$secs\"\nkill \"$pid\" 2>/dev/null\nwait \"$pid\" 2>/dev/null\nrm -f \"$dir/index.html\" \"$log\"\nrmdir \"$dir\"\necho \"served a read-only index of ~/.jos/runs from $dir on http://127.0.0.1:$port/ for $secs s; stopped and removed it\"",
+          "serve"
+        ],
+        "execution": {
+          "env": [
+            "PATH",
+            "HOME",
+            "JOS_SERVE_PORT",
+            "JOS_SERVE_SECONDS"
+          ]
+        },
+        "needs": [
+          "index"
+        ],
+        "with": {
+          "dir": "{{ site }}"
+        },
+        "description": "python3 -m http.server --bind 127.0.0.1 on that folder, counted from the moment it says it is serving, then remove it"
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "index",
+          "serve"
+        ]
+      }
+    }
+  }
+}

package/examples/README.md

@@ -0,0 +1,105 @@
+# The tour
+
+Each example is one capability of `jos`, and each one runs. Copy the folder first, so the runs do not write into
+the installed package (a run of `05-sealed` keeps its ledger in `05-sealed/.jos/replays/`; the others in
+`~/.jos/runs/`):
+
+```
+cp -R "$(npm root -g)/@josfox/jos/examples" jos-tour && cd jos-tour
+```
+
+Every `jos run` prints the document's intention before it runs (`Intention`, `Done when`, `Avoid`, `Limit`), then
+the verdict of each criterion as jos-core evaluated it, then `Intention met` or `Intention NOT met (code N: …)`.
+`--json` prints jos-core's result object instead, unchanged.
+
+| Example | Command | Result |
+|---|---|---|
+| `01-hello.jos` | `jos run 01-hello.jos` | prints `hello, .jos`; `✓ Intention met`; exit 0 |
+| `02-criteria.jos` | `jos run 02-criteria.jos` | one verdict line per criterion: `exit`, `stdout_contains`, `stdout_matches`, `stderr_empty`, `not`, and a descriptive one (recorded, never evaluated); exit 0. Change the `echo` text and it is exit 1 |
+| `03-flow-gate.jos` | `jos run 03-flow-gate.jos` | `build` runs, the human gate stops the flow: `Intention NOT met (code 1: not done)` and the command to approve; exit 1 |
+| | `jos run 03-flow-gate.jos --approve build` | `build`, then `publish`; prints `published`; exit 0 |
+| | `jos run 03-flow-gate.jos --flow build-only` | runs the other flow of the document (`build` only); exit 0 |
+| `04-use-template/` | `jos run 04-use-template/use.jos --library 04-use-template/lib` | one template, used twice with `with`, pinned by its digest; prints `hello, Leo`; exit 0. See [its README](04-use-template/README.md) |
+| | `jos run 04-use-template/lib/greeting.jos --with '{"name":"Ana"}'` | the template run directly; prints `hello, Ana`; exit 0 |
+| `05-sealed/` | `jos run 05-sealed` | the folder runs while its hash matches `integrity.hash`; exit 0. Edit it and it is exit 3. See [its README](05-sealed/README.md) |
+| `06-requires.jos` | `jos run 06-requires.jos` | needs a `payments` service this runtime does not provide: refused before anything starts, `/requires/0: not satisfied`; exit 5 |
+| `07-sandbox.jos` | `jos run 07-sandbox.jos` | `security.tier: sandbox`, and this kernel cannot confine a process: refused, `sandbox not available`; exit 5 |
+| `08-ids-ledger-meter.md` | the commands in it | `jos ids`, `jos runs`, `jos ledger verify`, `jos meter` over the runs above |
+| `10-ollama.jos` | `jos run 10-ollama.jos` | checks `http://localhost:11434`; without Ollama it says so and sends nothing (exit 1); with Ollama the objective goes to `ollama run ${OLLAMA_MODEL:-llama3.2}` and the answer is printed (exit 0) |
+| `11-openai.jos` | `jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos` | the objective to the OpenAI Responses API (`${OPENAI_MODEL:-gpt-5-mini}`); prints the answer; exit 0. Without the key: `OPENAI_API_KEY is not set: no request was sent.`, exit 1 |
+| `12-gemini.jos` | `jos secrets exec --only GEMINI_API_KEY -- jos run 12-gemini.jos` | the same with the Gemini API (`${GEMINI_MODEL:-gemini-2.5-flash}`) |
+| `13-anthropic.jos` | `jos secrets exec --only ANTHROPIC_API_KEY -- jos run 13-anthropic.jos` | the same with the Anthropic Messages API (`${ANTHROPIC_MODEL:-claude-opus-5-5}`) |
+| `14-serve.jos` | `jos run 14-serve.jos` | writes a read-only HTML index of `~/.jos/runs` into a new temporary folder and serves only that folder with `python3 -m http.server --bind 127.0.0.1` on port `${JOS_SERVE_PORT:-8765}` for `${JOS_SERVE_SECONDS:-60}` seconds, counted from the moment python3 says it is serving (it may take a few seconds to listen; at most 60 s), then removes it; exit 0 |
+
+`hello.jos` is the document `jos verify` runs.
+
+## The provider examples and your keys
+
+`11`, `12` and `13` are shell steps that call the provider's REST API with `curl`. They are paid calls on your
+account. Store a key once, then give it only to the run that needs it:
+
+```
+jos secrets set OPENAI_API_KEY --stdin          # type or paste the key; it is not echoed
+jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos
+```
+
+What happens to the key: `jos secrets exec` puts it only in the environment of that `jos run`; the document's
+`execution.env` lets it reach the step; the step hands it to `curl` on stdin (`-H @-`), so it is never on a command
+line; the examples never print it, and an error message from the API is printed with the key replaced by `[key]`.
+The key is not in the receipts or the ledger: a receipt records the step's code, its criteria verdicts and hashes
+of its input and output, never the environment (the test suite checks the ledger, the result and the output for
+the key). The answer itself is printed
+to your terminal and not stored. The model's tokens and cost are not recorded either: the `shell` engine does not
+report them, so `jos meter` shows them as "not reported".
+
+## What `jos run` prints (NO_COLOR)
+
+```
+$ jos run 03-flow-gate.jos
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JOS RUN // jos-core 2.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  File: 03-flow-gate.jos
+
+Intention: Build, wait for a person to approve the build, then publish
+Done when:
+  • exit 0
+Avoid: "rm -rf"
+Limit: 10 s, 65536 output bytes per stream, 0 retries
+
+  ID: art_572a58662e9e76761b6844bfd091ed08636023e39ce10cd13dc1cdf463741d96
+  Input version: 2.0.0
+  Capability: cap_01M5DX8R8WT15PS3SQV70CV2PM (local-trusted)
+  Ledger: ~/.jos/runs/run_01M5DX8R8TCEQ2D7DESRZQH8JG/ledger.jsonl
+
+built
+
+Verdict:
+  [1] build ✓ code 0
+    ✓ stdout_contains: found
+  [1] tour.flow-gate (flow main) ✖ code 1
+    ✓ exit: exit 0 (want 0)
+
+✖ Intention NOT met (code 1: not done) (run_01M5DX8R8TCEQ2D7DESRZQH8JG)
+  gate human: waiting for an approval of "build"
+  To approve it: jos run 03-flow-gate.jos --approve build
+
+$ jos run 03-flow-gate.jos --approve build
+…
+published
+
+Verdict:
+  [1] build ✓ code 0
+    ✓ stdout_contains: found
+  [1] publish ✓ code 0
+    ✓ stdout_contains: found
+  [1] tour.flow-gate (flow main) ✓ code 0
+    ✓ exit: exit 0 (want 0)
+
+✓ Intention met (code 0, run_01M5DX8R9YSZT1S7GKJJJNS9MM)
+```
+
+The `run_` and `cap_` ids and the ledger path are yours; the `art_` is the same on every machine and in both
+reference kernels, because it is the hash of the document's content.

package/examples/hello.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "hello",
+  "meta": {
+    "name": "hello",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Print a greeting and exit cleanly",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "hello"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf",
+      "curl",
+      "wget"
+    ],
+    "limit": {
+      "seconds": 5,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "hello, .jos"
+    ],
+    "on_error": "fail",
+    "env": [
+      "PATH",
+      "HOME"
+    ],
+    "cwd": "."
+  }
+}

package/package.json

@@ -1,40 +1,57 @@
-{
-  "name": "@josfox/jos",
-  "version": "4.1.0",
-  "description": "Stoic kernel for AI agent orchestration. Zero dependencies. Offline first.",
-  "license": "MIT",
-  "author": "JOS Open Standards Foundation",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/josfox-ai/jos.git"
-  },
-  "homepage": "https://josfox.ai",
-  "keywords": [
-    "cli",
-    "ai",
-    "agent",
-    "orchestration",
-    "jos",
-    "josfox",
-    "artifacts",
-    "offline-first",
-    "zero-dependencies"
-  ],
-  "bin": {
-    "jos": "bin/jos",
-    "josfox": "bin/jos"
-  },
-  "files": [
-    "bin/",
-    "src/"
-  ],
-  "type": "commonjs",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node bin/jos verify",
-    "test:cli": "node bin/jos verify",
-    "test:all": "node bin/jos verify && node bin/jos validate ../examples/reference-v0.0.7.jos --no-strict"
-  }
-}
+{
+  "name": "@josfox/jos",
+  "version": "5.0.0",
+  "description": "Host CLI for the jos-core kernel: run and validate .jos documents (2.0.0, 1.1.0, 1.0.0, 0.0.7). Offline first.",
+  "license": "Apache-2.0",
+  "author": "Josué Emmanuel Gómez Carrillo (JOSFOX LLC)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josfox-jos/jos.git",
+    "directory": "packages/jos"
+  },
+  "homepage": "https://github.com/josfox-jos/jos/tree/main/packages/jos",
+  "keywords": [
+    "cli",
+    "ai",
+    "agent",
+    "orchestration",
+    "jos",
+    "josfox",
+    "artifacts",
+    "offline-first",
+    "zero-dependencies"
+  ],
+  "bin": {
+    "jos": "bin/jos"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "SECURITY-SECRETS.md",
+    "SECURITY-MCP.md",
+    "STYLE.md",
+    "PROMISES.md",
+    "promises.json",
+    "!src/commands/_frozen/",
+    "src/commands/_frozen/*.README.md"
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@josfox/jos-core": "^2.0.0"
+  },
+  "scripts": {
+    "test": "node test/gate.js",
+    "test:cli": "node bin/jos verify",
+    "test:coverage": "node test/coverage.js",
+    "test:host": "node --test test/host.test.js",
+    "test:promises": "node --test test/promises.test.js",
+    "promises:md": "node test/promises-md.js",
+    "promises:check": "node test/promises-md.js --check",
+    "test:secrets": "node --test --experimental-test-coverage --test-coverage-include=src/commands/secrets.js --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 test/secrets.test.js",
+    "test:mcp": "node --test --experimental-test-coverage --test-coverage-include=src/mcp.js --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 test/mcp.test.js"
+  }
+}