geniejars 0.2.7 → 0.2.8

package/JFILE.md

@@ -0,0 +1,130 @@
+# JFile
+
+A `JFile` (shortedned `GeniejarsFile`), describes how to build a geniejars environment. The syntax mirrors Dockerfile.
+
+## Directives
+
+### `ENV <KEY>=<VALUE>`
+Set an environment variable. Applies to all subsequent `RUN` commands and to the main process started by `CMD`.
+
+```
+ENV NODE_ENV=production
+ENV PORT=3000
+```
+
+### `WORKDIR <path>`
+Set the working directory for subsequent `RUN` commands and for `CMD`. Relative paths are resolved inside the geniejars's home directory. The directory is created if it does not exist.
+
+```
+WORKDIR app
+```
+
+### `COPY <src> <dest>`
+Copy files or directories from the manager's filesystem into the geniejars's home. `src` is relative to the `GeniejarsFile`'s directory. `dest` is relative to the geniejars's home (or absolute).
+
+```
+COPY ./myapp app
+COPY ./config/prod.json app/config.json
+```
+
+### `RUN <command>`
+Execute a shell command as the geniejars during the build phase. Runs via the geniejars's agent socket — no sudo required. Uses the current `WORKDIR` and any `ENV` vars defined above it.
+
+```
+RUN npm install --omit=dev
+RUN mkdir -p logs
+```
+
+### `ADDPATH <path>`
+Prepend a directory to `PATH` when the main process is started via `CMD`. Multiple `ADDPATH` directives are accumulated in order. Has no effect on `RUN` commands (use `ENV PATH=...` for that).
+
+```
+ADDPATH ${COMMON}/bin
+ADDPATH ${COMMON}/node/bin
+```
+
+### `IMPORT <KEY>`
+Copy an environment variable from the manager's environment into the geniejars's environment. The value is captured at build time and stored with the geniejars's prepared config. Fails the build if the variable is not set on the manager.
+
+```
+IMPORT ANTHROPIC_API_KEY
+IMPORT MY_SECRET_TOKEN
+```
+
+### `DEPEND <path>`
+Assert that a path exists on the manager's filesystem before the build proceeds. If the path is missing, the build fails with a clear error. Typically used with `${COMMON}` to validate that a shared tool was installed before trying to use it.
+
+```
+DEPEND ${COMMON}/claude/bin/claude
+DEPEND /opt/my-tool/bin/my-tool
+```
+
+### `CMD <command>`
+Define the main process to start when `node script/run.mjs <name>` is called. Only the last `CMD` in the file takes effect.
+
+Plain string form (runs via `sh -c`):
+```
+CMD node app/server.js
+```
+
+JSON array form (preferred — no shell interpretation):
+```
+CMD ["node", "app/server.js", "--port", "3000"]
+```
+
+## Common directory
+
+`${COMMON}` expands to the `commonDir` path from `geniejars.config.json` (default: `/opt/geniejars-common`). This is a shared read-only space where the manager installs tools that geniejars need access to — for example a pinned version of `claude` or shared node modules.
+
+```
+DEPEND ${COMMON}/claude/bin/claude
+COPY ${COMMON}/claude/bin/claude bin/claude
+```
+
+`${COMMON}` is substituted before the file is parsed, so it works in any directive.
+
+## Port allocation
+
+Each geniejars is pre-assigned a fixed number of ports at `allocate` time (configured via `portsPerGeniejars` in `geniejars.config.json`). These ports can be referenced in any directive using the `${PORT(n)}` syntax, where `n` is 1-indexed.
+
+```
+${PORT(1)}   # first assigned port
+${PORT(2)}   # second assigned port
+```
+
+Substitution happens before the file is parsed, so `${PORT(n)}` works anywhere — in `ENV`, `RUN`, `COPY`, and `CMD`.
+
+At `run` time the ports are also automatically injected as `PORT_1`, `PORT_2`, etc. into the main process environment, regardless of whether `ENV` was used in the GeniejarsFile.
+
+## Comments and blank lines
+
+Lines starting with `#` are comments. Blank lines are ignored.
+
+```
+# This is a comment
+```
+
+## Example
+
+```
+# Build a Node.js app in a geniejars sandbox
+ENV NODE_ENV=production
+ENV PORT=${PORT(1)}
+ENV DEBUG_PORT=${PORT(2)}
+
+WORKDIR app
+COPY ./myapp .
+
+RUN npm install --omit=dev
+
+CMD ["node", "server.js"]
+```
+
+## Usage
+
+```
+node script/build.mjs <name> [GeniejarsFile]   # apply this file to a geniejars
+node script/run.mjs <name>                   # start the CMD
+node script/exec.mjs <name> <cmd> [args...]  # run a one-off command
+node script/stop.mjs <name>                  # stop the main process
+```

package/README.md

@@ -144,7 +144,7 @@ The `JFile` format mirrors Dockerfile. Supported directives:
 
 Port placeholders `${PORT(1)}`, `${PORT(2)}` etc. are substituted with the geniejars's pre-assigned ports at build time. `${COMMON}` expands to `commonDir`.
 
-See [SUBFILE.md](./SUBFILE.md) for full documentation.
+See [JFILE.md](./JFILE.md) for full documentation.
 
 ## Library usage
 
@@ -213,6 +213,10 @@ script/
   uninstall-geniejars.mjs remove all geniejars and system config (run as root)
 ```
 
+## Common Issues
+
+See [COMMON-ISSUES.md](./COMMON-ISSUES.md) for solving common issues.
+
 ## License
 
 MIT — see [LICENSE.md](./LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geniejars",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "type": "module",
   "description": "Linux geniejars sandboxing — library and CLI for running processes as isolated system users",
   "main": "src/index.mjs",
@@ -10,11 +10,14 @@
   "bin": {
     "geniejars": "script/geniejars.mjs"
   },
+  "license": "MIT",
   "files": [
     "src/",
     "script/",
     "geniejars.config.example.json",
-    "COMMON-ISSUES.md"
+    "COMMON-ISSUES.md",
+    "LICENSE.md",
+    "JFILE.md"
   ],
   "engines": {
     "node": ">=18.17.0"