@kodel-ai/kodel 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -1,23 +1,131 @@
 # Kodel
 
-Spec-driven pipelines for solo developers, running inside the coding agent you already use.
+Spec-driven pipelines that run inside the coding agent you already use, and are checked outside of it.
 
-> Status: early development. Nothing here is released yet, and the documentation will be
-> written once the first working version exists.
+[![npm](https://img.shields.io/npm/v/@kodel-ai/kodel?include_prereleases)](https://www.npmjs.com/package/@kodel-ai/kodel)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/kodelai/kodel-cli/blob/main/LICENSE)
 
-## Idea
+> **Status: beta.** Formats and commands may still change before 1.0. The full documentation is not
+> written yet; until then this README and [AGENTS.md](https://github.com/kodelai/kodel-cli/blob/main/AGENTS.md) are the entry points.
 
-- Describe *how you work* as a reusable pipeline file that lives in your repository.
-- Your agent (Claude Code, Codex, OpenCode, ...) drives the run through MCP tools.
-- Every step result is validated outside the agent, so "done" is verifiable.
-- Run history stays in git and is analyzed to suggest improvements to the pipeline.
-- Optional [tasks](docs/tasks.md): the agent writes down what it finds on the way ("create a task for
-  that bug"), you ask what is left, and a tracker such as Jira can sit behind the same interface.
+## Quick start
 
-## Repository
+Requirement: Node >= 22.19. Kodel works with Claude Code, Codex and OpenCode (see
+[adapters](https://github.com/kodelai/kodel-cli/blob/main/adapters/README.md) for what is checked on a real agent).
 
-See [AGENTS.md](AGENTS.md) for the layout and contribution rules.
+**1. Install.**
+
+```bash
+npm install -g @kodel-ai/kodel@beta
+```
+
+**2. Set up your repository.** In the repository you want to work on:
+
+```bash
+kodel init
+```
+
+It adds the MCP server, the skills, the config and the hooks for the agents it finds.
+
+**3. Create a pipeline.** Restart your agent so it picks up the MCP server, then ask it to design one:
+
+```text
+/kodel-design
+```
+
+Follow the agent's instructions. When it proposes a pipeline, accept it in a terminal:
+
+```bash
+kodel pipeline proposals show
+kodel pipeline proposals apply <name>
+```
+
+**4. Run it.** Give the agent a task:
+
+```text
+/kodel-run fix the login timeout
+```
+
+The agent works through the steps, and the engine checks each result. When a run needs you, the agent
+says what to look at and which command to decide with:
+
+```bash
+kodel status              # list the runs, or show one
+kodel gate approve <run>  # decide the human step a run is waiting at (or: gate reject)
+kodel report <run>        # where the time went and what was redone
+```
+
+An example of a full pipeline, with a plan, two human gates, a review and tests, is
+[`examples/pipelines/feature.yaml`](https://github.com/kodelai/kodel-cli/blob/main/examples/pipelines/feature.yaml).
+
+## Commands for people
+
+These ask for confirmation and refuse to run without a terminal, on purpose: an agent can propose,
+only a person decides.
+
+| Command | What it does |
+| --- | --- |
+| `kodel init` | Set the project up for your coding agents. |
+| `kodel status [run]` | List the runs, or show one. |
+| `kodel wait <run>` | Stay until a run stops waiting for a person, print one line, exit. It changes nothing. |
+| `kodel gate approve\|reject <run>` | Decide the human step a run is waiting at. |
+| `kodel resume <run>` | Carry on a paused run, with more attempts for the step that stopped it. |
+| `kodel ack <run>` | Accept the state of a run after you changed it by hand. |
+| `kodel seal <run>` | Accept the files of a finished run after a deliberate change. |
+| `kodel report [run]` | Where the time went and what was redone in a run. |
+| `kodel pipeline changes ...` | Review a change to the pipeline of a run that is going. |
+| `kodel pipeline proposals ...` | Review a pipeline the agent proposed outside a run. |
+| `kodel feedback [text]` | Send a bug report, an idea or a note to the Kodel developers. |
+
+Run `kodel <command> --help` for the options.
+
+## How it is built
+
+A Bun workspace in TypeScript, shipped as a single JavaScript file that runs on plain Node.
+
+| Package | Role |
+| --- | --- |
+| `packages/pipeline-core` | The pure engine: pipeline spec, result checks, run state machine, redaction, and the MCP tool definitions. No file system, process or clock access. |
+| `packages/local` | Local adapters: file state store, process executor, git snapshots, clock, local tasks. |
+| `packages/cli` | The `kodel` command, including the human-only commands. |
+| `packages/testkit` | Scripted and adversarial fake agents and fixtures (private). |
+
+The engine knows nothing about transport or I/O, and node and check kinds are registered by `kind`.
+That is what lets a server backend implement the same adapter interfaces later. The principles
+behind this (untrusted agent input, fail-closed, redaction on every write, humans decide trust) are in
+[AGENTS.md](https://github.com/kodelai/kodel-cli/blob/main/AGENTS.md). How Kodel reads the logs of your agent sessions is in
+[docs/history.md](https://github.com/kodelai/kodel-cli/blob/main/docs/history.md).
+
+## Something went wrong?
+
+Open an [issue](https://github.com/kodelai/kodel-cli/issues/new/choose), or send a note straight from
+the terminal:
+
+```bash
+kodel feedback "gate refuses to run in tmux" --type bug   # or: feature, feedback
+```
+
+It sends only your text and a short description of your system, shows both, and asks before it sends.
+For a security problem, see [SECURITY.md](https://github.com/kodelai/kodel-cli/blob/main/SECURITY.md) instead.
+
+## Contributing
+
+To work on Kodel itself you need [Bun](https://bun.sh) as well as Node. `bun run build` produces
+`packages/cli/dist/kodel.js`, the same file that is published.
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run lint
+bun test
+bun run build && node scripts/check-artifact.mjs
+```
+
+CI runs the same on Linux, macOS and Windows. Sign off your commits (`git commit -s`): the project uses
+the Developer Certificate of Origin. Open a pull request, never push to `main`. Everything committed,
+including comments and commit messages, is in English. Read [AGENTS.md](https://github.com/kodelai/kodel-cli/blob/main/AGENTS.md) before you start:
+it also says what an AI agent may and may not do in this repository.
 
 ## License
 
-Apache-2.0. See [LICENSE](LICENSE).
+Apache-2.0. See [LICENSE](https://github.com/kodelai/kodel-cli/blob/main/LICENSE).

package/dist/kodel-hook.js

@@ -29,6 +29,12 @@ import { basename, dirname, isAbsolute, join as join2, relative, resolve, sep }
 
 // ../local/src/git.ts
 import { execFile } from "node:child_process";
+import { devNull, tmpdir } from "node:os";
+class DeadlineError extends Error {
+  constructor() {
+    super("deadline: git took longer than the time allowed for recording the changes");
+  }
+}
 var SAFE_CONFIG = [
   "-c",
   "core.fsmonitor=false",
@@ -37,18 +43,35 @@ var SAFE_CONFIG = [
   "-c",
   "log.showSignature=false"
 ];
-function git(args, cwd, env = {}, input) {
+var NO_HOOKS = ["-c", `core.hooksPath=${devNull}`];
+function commandName(args) {
+  for (let i = 0;i < args.length; i += 1) {
+    const arg = args[i] ?? "";
+    if (arg === "-c")
+      i += 1;
+    else if (!arg.startsWith("-"))
+      return arg;
+  }
+  return args[0] ?? "";
+}
+function git(args, cwd, env = {}, input, timeoutMs) {
   return new Promise((resolveResult, reject) => {
     const child = execFile("git", [...SAFE_CONFIG, ...args], {
       cwd,
       env: { ...process.env, ...env },
       maxBuffer: 256 * 1024 * 1024,
       encoding: "utf8",
-      windowsHide: true
+      windowsHide: true,
+      ...timeoutMs === undefined ? {} : { timeout: timeoutMs, killSignal: "SIGKILL" }
     }, (error, stdout, stderr) => {
       if (error) {
+        const tooMuch = error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        if (timeoutMs !== undefined && error.killed && !tooMuch) {
+          reject(new DeadlineError);
+          return;
+        }
         const detail = (stderr || error.message).trim();
-        reject(new Error(`git ${args[0]} failed: ${detail}`));
+        reject(new Error(`git ${commandName(args)} failed: ${detail}`));
       } else {
         resolveResult({ stdout });
       }
@@ -291,11 +314,11 @@ class HookRegistry {
   }
 }
 function raced(work, ms, timer) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve, reject) => {
     const cancel = timer.start(ms, () => reject(new Error(`timed out after ${ms} ms`)));
     work.then((value) => {
       cancel();
-      resolve2(value);
+      resolve(value);
     }, (error) => {
       cancel();
       reject(error);
@@ -308,9 +331,9 @@ async function dispatch(registry, event, context, options) {
   const parts = handlers.map(() => "");
   await Promise.all(handlers.map(async (handler, index) => {
     try {
-      const text2 = await raced(Promise.resolve().then(() => handler.run(event, context)), options.timeoutMs, options.timer);
-      if (handler.prints === true && typeof text2 === "string")
-        parts[index] = text2;
+      const text = await raced(Promise.resolve().then(() => handler.run(event, context)), options.timeoutMs, options.timer);
+      if (handler.prints === true && typeof text === "string")
+        parts[index] = text;
     } catch (error) {
       failures.push({
         handler: handler.id,