@jigging/jig 0.1.0-alpha.12 → 0.1.0-alpha.14

package/README.md

@@ -1,201 +1,49 @@
 # `@jigging/jig`
 
-Jig is a local, secure host for admitted FLOW packages. The direct-run alpha
-has one finite command surface:
-
-```text
-jig init --bare <directory>
-jig review [project] [--yes]
-jig run <flow:path|binding:id> [--input JSON] [--timeout DURATION]
-jig --version
-```
-
-`jig --version` prints the built package version without opening a project or
-acquiring a sandbox.
-
-There is no `jig setup`. `review` and `run` transparently acquire the rootless
-authority they need or fail closed.
+Put reusable Agent methods to work with powers you approve. Choose your Agents,
+combine specialists, inspect their results, and stop owned work.
 
 ## Install
 
 ```console
-npm install --global @jigging/jig@0.1.0-alpha.10
+npm install --global @jigging/jig@alpha
 ```
 
-Installing Jig also installs `@oven/bun-linux-x64-baseline@1.3.3` as an exact
-external runtime dependency. Bun is not embedded in or bundled with the
-`@jigging/jig` archive. npm verifies the installed package; Jig selects only
-that closed package-local path, authenticates its version, revision, and digest
-before evaluator or Flow bytes execute, and revalidates it before each launch.
-
-## Supported host
-
-The alpha has been independently tested on a provisioned Ubuntu 24.04 x86_64
-host. Other Linux x86_64 hosts meeting the requirements below have not yet been
-independently validated; Jig fails closed when a required capability is absent.
-
-The alpha requires:
-
-- Linux x86_64 with glibc 2.17 or newer and an SSE4.2-capable baseline CPU;
-- Bubblewrap 0.12 or newer and GNU `readlink -f`, located as described below;
-- cgroup v2 with delegated `cpu`, `memory`, and `pids` controllers;
-- a systemd user manager with transient delegated scopes; and
-- unprivileged user, mount, PID, network, IPC, UTS, and cgroup namespaces.
+The developer alpha requires Linux x86_64/glibc, Bubblewrap, and a systemd user
+manager with delegated cgroup v2 controllers. See the
+[complete supported-host requirements](https://jig.md/guide/#supported-host).
+npm installs Jig's exact Bun runtime dependency alongside the package.
 
-The glibc and SSE4.2 floors come from the selected Bun baseline runtime.
+## Get started
 
-Host tools are resolved through `/usr/bin`, `/bin`, or the NixOS system profile
-`/run/current-system/sw/bin`, never ambient `PATH`. An operator may select
-Bubblewrap using an absolute `JIG_BWRAP_PATH`, including a shell-local Nix
-dependency. It receives the same validation and never falls back on failure.
-On NixOS, enable
-`programs.nix-ld.enable` for the unmodified npm runtime. Jig uses the real glibc
-loader at the system-managed `share/nix-ld/lib/ld.so` link, mounting only that
-loader and its required libraries into Runs. It does not mount nix-ld or the
-whole Nix store. NixOS path support is included in this source candidate;
-independent NixOS host conformance is not yet established.
+[Create your first Flow](https://jig.md/guide/#your-first-flow), or try
+[an issue becoming a tested patch](https://jig.md/guide/tested-patch): selected
+local source becomes a reviewable patch with executed checks, while the original
+repository stays unchanged.
 
-Jig commands do not use `sudo`, download runtimes, or expose host control to
-Flow code. Runtime installation is handled once by npm with the Jig package.
-
-Flow Runs default to 30 seconds. `jig run --timeout DURATION` accepts a
-positive integer followed by `ms`, `s`, `m`, or `h`, up to 24 hours. Flow
-execution scopes remain fixed at 256 MiB aggregate memory, 48 aggregate PIDs,
-and 50% of one CPU. Project evaluation is fixed at 3 seconds, 256 MiB, 64
-PIDs, and 50% CPU. Locked dependency preparation is fixed at 60 seconds, 512
-MiB, 64 PIDs, and one CPU. See the repository
-[`SECURITY.md`](https://github.com/jiggy/jig/blob/main/SECURITY.md) for the
-threat boundary and private reporting channel.
-
-## Use
-
-```console
-jig init --bare my-project
-cd my-project
-```
-
-Place packages under `flows/<name>/`. Each package has exact-case `FLOW.md`
-and, for this alpha, one `flow.ts`. The generated `jig.ts`
-explicitly discovers `./flows` and `./bindings`.
-
-The paired `@jigging/flow@0.1.0-alpha.6` package provides the small Run/1
-authoring API. Declare it exactly in the Flow's `package.json`, generate a text
-`bun.lock` with Bun 1.3.3 and `bun install --lockfile-only`, then handle one
-finite Run:
-
-```ts
-import { handle } from "@jigging/flow";
-
-await handle(async (run) => ({
-  outcome: "done",
-  output: { received: run.input },
-}));
-```
+Jig has three project commands:
 
-```console
-jig review
-jig run flow:flows/example --input '{}'
-```
-
-For a longer Run, add a bounded duration such as `--timeout 2m`. The timeout
-starts when Jig accepts the root Run. Project acquisition happens before it;
-mandatory fencing and cleanup may finish afterward.
-
-`jig review` shows the complete proposed project change, including exact
-current and proposed Package/1 content digests, and asks for approval. It is
-not a source-file diff; inspect editable source with your normal tools. When
-standard input and output are both terminals, Jig prompts for approval.
-Otherwise it prints the review and exits with `JIG_APPROVAL_REQUIRED`; `--yes`
-records an already explicit approval. The CLI keeps review and admission
-mechanics internal.
-
-A target is marked changed when its package identity or exact execution
-evidence changes. Package digests appear once in the package section;
-host-specific evidence remains private.
-
-For ordinary dependencies, place `package.json` and text `bun.lock` beside
-`flow.ts`; do not include `node_modules`. `bun install --lockfile-only` is the
-author-side lock-generation step: it creates no project-local `node_modules`,
-but may use the network and Bun's author-side cache. On the first `jig review`
-after those inputs change, Jig fetches the frozen production artifacts and
-materializes a private execution snapshot in a contained trusted preparation
-process, using the fixed Bun runtime, the default npm registry, and no
-lifecycle scripts. It reuses the Run containment and ownership mechanism but
-deliberately has registry network access. A declined review may therefore have
-materialized inert evidence without granting authority. Unsupported or
-unlocked sources fail before admission.
-
-Unreleased code can remain ordinary readable files inside the Flow package and
-be imported relatively. Code shared from elsewhere must be copied or bundled
-into the finished package before `jig review`; Jig does not follow symlinks or
-resolve `file:`, `workspace:`, or Git dependencies and does not own that build
-step.
-
-A dependency-free package needs no `bun.lock`; omit it rather than preserving
-an empty or stale lock. Optional package schemas are FLOW Schema/1 files and
-must begin with the exact root declaration
-`"$schema": "https://flow.jig.md/schemas/schema-1.json"`.
-
-The admitted Run uses only the retained prepared bytes. It has no network,
-ambient `PATH`, package installation, or lifecycle scripts. Packages with no
-runtime dependencies continue to run directly, and already bundled
-package-local code remains valid. An unchanged `jig review` reuses the admitted
-prepared tree only while its source and host evidence still match.
-
-Bindings use an explicit target. A declaration may also give its package exact
-child-Flow slots:
-
-```ts
-import { defineBinding } from "@jigging/jig";
-
-export default defineBinding({
-  package: "./flows/reviewer",
-  slots: { research: "flow:flows/research" },
-});
-```
-
-```console
-jig run binding:reviewer --input '{}'
+```text
+jig init --bare <directory>
+jig review [project] [--yes]
+jig run <flow:path|binding:id> [options]
 ```
 
-`slots` is optional and omission normalizes to `{}`. It maps at most 256
-LocalName keys to explicit `flow:<path>` or `binding:<id>` targets in the same
-admitted generation. Slots belong to the Binding; a direct `flow:` Run has none.
-Selected child Bindings must have no child slots of their own.
-
-Each `flow/call` carries JSON/1 input into a fresh child context and returns a
-complete JSON/1 Run result. The child receives its selected target's admitted
-settings and Agent capability, empty attachments, no inherited slots, and a
-deadline no later than its parent. It selects its own package-local Skills per
-Agent call; providers and credentials remain host choices. Run/1 controls
-operation identity, duplicate joins, conflicting reuse, cancellation, and
-uncertainty; Jig does not replay uncertain dispatch automatically. There is no
-separate child history, administration, scheduler, catalogue, or resolver. Jig
-also never guesses an unprefixed target.
-
-Each Run context admits one active operation; a child Flow can own one Agent
-operation while its parent awaits it. Excess distinct concurrent calls receive
-`RESOURCE_EXHAUSTED`, while sequential calls remain available. Cancellation and
-cleanup cover the specialist and its locally owned Agent worker.
+`review` asks you to approve the proposed project changes. `run` executes the
+admitted revision and returns JSON after settling owned work. Use
+`jig --version` to inspect the installed version.
 
-One experimental [Agent Run capability](https://jig.md/spec/agent-run) is
-available through ordinary Run/1 `effect/call`. The host may use the official
-OpenAI JavaScript SDK against an operator-selected OpenAI-compatible endpoint,
-or run native Codex, Claude Code, or Pi through one private ACP mechanism.
-Direct API configuration uses `OPENAI_API_KEY` and `OPENAI_MODEL`; optional
-`OPENAI_BASE_URL` and `OPENAI_API` select the HTTPS endpoint and either the
-`responses` (default) or `chat-completions` wire shape. Jig supplies no default
-model. Client, API, endpoint, model, executable path, and credentials are
-trusted host configuration, not FLOW or Binding inputs, and Jig exposes no
-provider registry.
+## Guides
 
-The complete runnable example and current specification map are in the
-[repository README](https://github.com/jiggy/jig#readme) and
-[`docs/jig/guide/index.md`](https://github.com/jiggy/jig/blob/main/docs/jig/guide/index.md).
+- [Choose an Agent](https://jig.md/guide/agents)
+- [Working with files](https://jig.md/guide/files)
+- [Dependencies](https://jig.md/guide/dependencies)
+- [Workflow design](https://jig.md/guide/workflow-design)
+- [Project authoring](https://jig.md/spec/project-sdk)
+- [Execution policy](https://jig.md/spec/project-policy)
+- [Security boundary](https://github.com/jiggy/jig/blob/main/SECURITY.md)
 
-This is a prerelease alpha. It does not expose Services, Hooks, event sources,
-a provider registry or package-selected provider configuration, Agent sessions,
-Semantic Choice, Jig Graph, schedulers, catalogues, runtime registries, or
-sandbox registries.
+Jig is prerelease software. [FLOW](https://flow.jig.md/) remains an independent
+standard for portable methods.
 
 Copyright © 2026 Victor Duarte <zvictor> and contributors.

package/dist/index.js

@@ -105,6 +105,43 @@ function validateString(value, byteLimit) {
   }
 }
 
+// src/project/commands.ts
+function projectCommandPath(value) {
+  if (typeof value !== "string" || value.length > 256 || !/^[A-Za-z0-9_][A-Za-z0-9_./-]*$/.test(value) || value.split("/").some((part) => part === "" || part === "." || part === "..") || value.split("/").length > 16)
+    throw new TypeError("command file paths must be bounded relative paths without traversal");
+  return value;
+}
+function normalizeProjectCommands(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("commands must be an object");
+  const entries = Object.entries(value);
+  if (entries.length > 8)
+    throw new TypeError("commands exceed eight entries");
+  const output = Object.create(null);
+  for (const [name, item] of entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64)
+      throw new TypeError("command name must be a LocalName");
+    if (item === null || typeof item !== "object" || Array.isArray(item) || Object.keys(item).length !== 1)
+      throw new TypeError(`command ${name} must contain run or test`);
+    const command = item;
+    if (Object.hasOwn(command, "run")) {
+      const path = projectCommandPath(command.run);
+      if (!path.endsWith(".ts") && !path.endsWith(".js"))
+        throw new TypeError("command run must name a .ts or .js entrypoint");
+      output[name] = Object.freeze({ run: path });
+    } else if (Object.hasOwn(command, "test") && Array.isArray(command.test)) {
+      if (command.test.length === 0 || command.test.length > 16)
+        throw new TypeError("command test must select one to sixteen test files");
+      const paths = command.test.map(projectCommandPath);
+      if (new Set(paths).size !== paths.length || paths.some((path) => !/\.(test|spec)\.(ts|js)$/.test(path)))
+        throw new TypeError("command test must name distinct .test or .spec files");
+      output[name] = Object.freeze({ test: Object.freeze(paths) });
+    } else
+      throw new TypeError(`command ${name} must contain run or test`);
+  }
+  return Object.freeze(output);
+}
+
 // src/package/case-fold-15.1.ts
 var CASE_FOLD_15_1 = new Map([
   [65, "a"],
@@ -1797,7 +1834,7 @@ function bindingRef(id) {
 }
 function normalizeBinding(input, canonical) {
   const captured = snapshotJsonObject(input, "Binding definition");
-  assertClosedObject(captured, canonical ? ["kind", "package", "settings", "slots"] : ["package", "settings", "slots"], "Binding definition");
+  assertClosedObject(captured, canonical ? ["kind", "package", "settings", "slots", "commands"] : ["package", "settings", "slots", "commands"], "Binding definition");
   if (canonical && captured.kind !== "package") {
     throw new TypeError("Binding kind must be package");
   }
@@ -1806,11 +1843,13 @@ function normalizeBinding(input, canonical) {
   const packagePath = normalizeProjectPath(captured.package, "package");
   const settings = Object.hasOwn(captured, "settings") ? expectJsonObject(captured.settings, "settings") : emptyRecord();
   const slots = Object.hasOwn(captured, "slots") ? normalizeFlowSlots(captured.slots) : emptyRecord();
+  const commands = normalizeProjectCommands(Object.hasOwn(captured, "commands") ? captured.commands : {});
   return record({
     kind: "package",
     package: packagePath,
     settings,
-    slots
+    slots,
+    ...Object.keys(commands).length === 0 ? {} : { commands }
   });
 }
 function normalizeFlowSlots(value) {

package/dist/project/author.d.ts

@@ -1,4 +1,5 @@
 import type { JsonObject } from '../json.js';
+import { type ProjectCommands } from './commands.js';
 export interface DiscoverySource {
     readonly kind: 'discover';
     readonly roots: readonly string[];
@@ -31,11 +32,13 @@ export interface PackageBindingDefinition {
     readonly package: string;
     readonly settings: JsonObject;
     readonly slots: Readonly<Record<string, string>>;
+    readonly commands?: ProjectCommands;
 }
 export interface PackageBindingInput {
     readonly package: string;
     readonly settings?: JsonObject;
     readonly slots?: Readonly<Record<string, string>>;
+    readonly commands?: ProjectCommands;
 }
 export type BindingDefinition = PackageBindingDefinition;
 export declare function discover(roots: string | readonly string[]): DiscoverySource;

package/dist/project/commands.d.ts

@@ -0,0 +1,10 @@
+/** Reviewed invocation policy; runtime and containment remain host choices. */
+export type ProjectCommand = {
+    readonly run: string;
+} | {
+    readonly test: readonly string[];
+};
+export type ProjectCommands = Readonly<Record<string, ProjectCommand>>;
+export declare function projectCommandPath(value: unknown): string;
+/** Input must already be an ordinary JSON snapshot at the owning boundary. */
+export declare function normalizeProjectCommands(value: unknown): ProjectCommands;

package/libexec/evaluator/project-authoring-1.schema.json

@@ -102,6 +102,9 @@
             "$ref": "#/$defs/targetSelector"
           },
           "maxProperties": 256
+        },
+        "commands": {
+          "$ref": "#/$defs/commands"
         }
       },
       "required": ["kind", "package", "settings", "slots"],
@@ -109,6 +112,43 @@
     },
     "bindingDefinition": {
       "$ref": "#/$defs/packageBinding"
+    },
+    "commands": {
+      "type": "object",
+      "maxProperties": 8,
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "run": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256
+              }
+            },
+            "required": ["run"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "test": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 16,
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 256
+                }
+              }
+            },
+            "required": ["test"],
+            "additionalProperties": false
+          }
+        ]
+      }
     }
   }
 }

package/libexec/evaluator/project-evaluator-sdk.bundle.js

@@ -105,6 +105,43 @@ function validateString(value, byteLimit) {
   }
 }
 
+// src/project/commands.ts
+function projectCommandPath(value) {
+  if (typeof value !== "string" || value.length > 256 || !/^[A-Za-z0-9_][A-Za-z0-9_./-]*$/.test(value) || value.split("/").some((part) => part === "" || part === "." || part === "..") || value.split("/").length > 16)
+    throw new TypeError("command file paths must be bounded relative paths without traversal");
+  return value;
+}
+function normalizeProjectCommands(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("commands must be an object");
+  const entries = Object.entries(value);
+  if (entries.length > 8)
+    throw new TypeError("commands exceed eight entries");
+  const output = Object.create(null);
+  for (const [name, item] of entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64)
+      throw new TypeError("command name must be a LocalName");
+    if (item === null || typeof item !== "object" || Array.isArray(item) || Object.keys(item).length !== 1)
+      throw new TypeError(`command ${name} must contain run or test`);
+    const command = item;
+    if (Object.hasOwn(command, "run")) {
+      const path = projectCommandPath(command.run);
+      if (!path.endsWith(".ts") && !path.endsWith(".js"))
+        throw new TypeError("command run must name a .ts or .js entrypoint");
+      output[name] = Object.freeze({ run: path });
+    } else if (Object.hasOwn(command, "test") && Array.isArray(command.test)) {
+      if (command.test.length === 0 || command.test.length > 16)
+        throw new TypeError("command test must select one to sixteen test files");
+      const paths = command.test.map(projectCommandPath);
+      if (new Set(paths).size !== paths.length || paths.some((path) => !/\.(test|spec)\.(ts|js)$/.test(path)))
+        throw new TypeError("command test must name distinct .test or .spec files");
+      output[name] = Object.freeze({ test: Object.freeze(paths) });
+    } else
+      throw new TypeError(`command ${name} must contain run or test`);
+  }
+  return Object.freeze(output);
+}
+
 // src/package/case-fold-15.1.ts
 var CASE_FOLD_15_1 = new Map([
   [65, "a"],
@@ -1797,7 +1834,7 @@ function bindingRef(id) {
 }
 function normalizeBinding(input, canonical) {
   const captured = snapshotJsonObject(input, "Binding definition");
-  assertClosedObject(captured, canonical ? ["kind", "package", "settings", "slots"] : ["package", "settings", "slots"], "Binding definition");
+  assertClosedObject(captured, canonical ? ["kind", "package", "settings", "slots", "commands"] : ["package", "settings", "slots", "commands"], "Binding definition");
   if (canonical && captured.kind !== "package") {
     throw new TypeError("Binding kind must be package");
   }
@@ -1806,11 +1843,13 @@ function normalizeBinding(input, canonical) {
   const packagePath = normalizeProjectPath(captured.package, "package");
   const settings = Object.hasOwn(captured, "settings") ? expectJsonObject(captured.settings, "settings") : emptyRecord();
   const slots = Object.hasOwn(captured, "slots") ? normalizeFlowSlots(captured.slots) : emptyRecord();
+  const commands = normalizeProjectCommands(Object.hasOwn(captured, "commands") ? captured.commands : {});
   return record({
     kind: "package",
     package: packagePath,
     settings,
-    slots
+    slots,
+    ...Object.keys(commands).length === 0 ? {} : { commands }
   });
 }
 function normalizeFlowSlots(value) {