@giovannijecha/jecode 0.1.5-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giovanni Jecha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+<p align="center">
+  <img src="docs/assets/brand/jeco-256.png" width="128" alt="Jeco, the steel-blue Jecode gecko">
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/wordmark-light.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/brand/wordmark-dark.svg">
+    <img src="docs/assets/brand/wordmark-dark.svg" width="280" alt="Jecode">
+  </picture>
+</p>
+
+<p align="center"><strong>Your code. Your loop.</strong></p>
+
+<p align="center">
+  A focused coding agent that lives in your terminal, keeps tool use visible,
+  and stays under your control.
+</p>
+
+<p align="center">
+  <a href="https://github.com/giovannijecha/jecode/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/giovannijecha/jecode/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-669BD2"></a>
+  <img alt="Node.js 24+" src="https://img.shields.io/badge/node-%3E%3D24-86CB92">
+  <img alt="Runtime dependencies: zero" src="https://img.shields.io/badge/runtime_dependencies-0-8DB4DD">
+</p>
+
+> Jecode is an early 0.1.x release. The core loop is usable today; commands and
+> terminal interactions may still evolve before 1.0.
+
+## Why Jecode
+
+- **One controller.** One visible loop talks to the model, runs tools, and returns
+  control to you. There are no hidden workers or delegated agents.
+- **Terminal-native.** The transcript, composer, searchable menus, tool output,
+  diffs, approvals, reasoning, and status all share one full-screen TUI.
+- **Permission-aware.** Reads stay transparent; dangerous actions ask first.
+  Session approvals can be reviewed and revoked.
+- **Provider-neutral.** Use Anthropic, OpenAI, or a local/remote Ollama server
+  without changing the workflow.
+- **Lean by construction.** Jecode installs as plain JavaScript, runs on
+  Node.js 24, executes no installation scripts, and has zero third-party
+  runtime dependencies.
+
+## Install
+
+Jecode requires **Node.js 24 or newer** and npm. Release candidates are
+published on the **next** channel:
+
+~~~console
+npm install --global @giovannijecha/jecode@next
+jecode --version
+~~~
+
+Then open the project you want to work on and run Jecode:
+
+~~~console
+cd path/to/your/project
+jecode
+~~~
+
+You can point at another workspace explicitly:
+
+~~~console
+jecode --root path/to/your/project
+~~~
+
+Run **jecode --help** for all startup options. Tested platforms are Windows,
+Ubuntu, and macOS.
+
+### Update
+
+Install the current release candidate over the existing global command:
+
+~~~console
+npm install --global @giovannijecha/jecode@next
+jecode --version
+~~~
+
+### Uninstall
+
+~~~console
+npm uninstall --global @giovannijecha/jecode
+~~~
+
+Uninstalling the command preserves **~/.jecode** so saved settings and
+credentials remain available after a reinstall. Remove that directory only
+when you intentionally want to erase Jecode's local data.
+
+### Linux and WSL
+
+WSL has its own Node.js installation and `PATH`; the Node.js version installed
+on Windows does not apply inside it. If installation succeeds but `jecode` is
+not found, run **npm config get prefix** and ensure its **bin/** directory is on
+your Linux `PATH`. Do not ignore an `EBADENGINE` warning: **node --version** must
+report 24 or newer.
+
+### Build from source
+
+~~~console
+git clone https://github.com/giovannijecha/jecode.git
+cd jecode
+npm ci
+npm run build:release
+npm link
+jecode
+~~~
+
+Development runs TypeScript directly with **npm run start**. **dist/** is an
+ignored, generated tree used only by linked commands and release tarballs.
+**npm pack** and **npm publish** rebuild it from a clean target; installing the
+published package runs no compilation or installation scripts.
+
+## First session
+
+Jecode opens on an empty composer instead of forcing a setup wizard. Type
+**/settings** when you are ready to choose a provider, select a model, and add a
+credential. A credential can remain in memory for the current session or be
+saved explicitly under **~/.jecode**; it is never stored in the workspace.
+
+| Provider | Credential | Notes |
+|---|---|---|
+| Anthropic | ANTHROPIC_API_KEY | Cloud |
+| OpenAI | OPENAI_API_KEY | Cloud |
+| Ollama | OLLAMA_API_KEY for Cloud/remote | Cloud with a key, local without one |
+
+Choose **cloud**, **local**, or a custom endpoint from the Ollama connection row
+in **/settings**. Existing users with an Ollama API key automatically use
+**https://ollama.com**; without a key, Jecode uses the local daemon at
+**http://127.0.0.1:11434**. Remote custom endpoints must use HTTPS.
+
+## Use the TUI
+
+Type **/** to open searchable command completion inside the composer.
+
+| Command | What it does |
+|---|---|
+| /settings | Manage provider, connection, model, limits, motion, and credentials |
+| /effort | Change and save reasoning effort directly |
+| /providers | Switch the provider for the next turn |
+| /models | Search the live model catalogue |
+| /credentials | Add, replace, inspect, or forget saved credentials |
+| /permissions | Review or revoke remembered session approvals |
+| /usage | Show normalized token usage |
+| /new | Start a clean in-memory conversation |
+| /export | Save a timestamped Markdown transcript in the launch directory |
+| /help | Show commands and controls |
+| /exit | Restore the terminal and exit |
+
+Useful controls:
+
+- **Up/Down** moves through command suggestions, menus, and input history.
+- **Tab** completes a slash command without running it; **Enter** sends.
+- **Alt+Enter** inserts a newline.
+- **Esc** closes a menu or interrupts the foreground operation.
+- **Ctrl+C** interrupts, or exits while idle. **Ctrl+D** requests a clean exit.
+- **PageUp/PageDown** and the mouse wheel scroll the transcript without losing
+  the place you are reading.
+- **Ctrl+O** expands or compacts the latest reasoning or tool-detail block.
+
+The one-line footer keeps model, effort, and workspace on the left. Live work,
+readiness guidance, and temporary feedback use the right edge without polluting
+the transcript.
+
+## Configuration
+
+Startup precedence is: command-line flags, environment variables, saved
+settings, built-in defaults.
+
+| Flag | Environment | Default |
+|---|---|---|
+| --provider | JECODE_PROVIDER | anthropic |
+| --model | JECODE_MODEL | Provider default or interactive selection |
+| --ollama-host | OLLAMA_HOST | Cloud with an Ollama key, local without one |
+| --root | — | Current directory |
+| --effort | JECODE_EFFORT | high |
+| --max-tokens | JECODE_MAX_TOKENS | 64000 |
+| --max-steps | JECODE_MAX_STEPS | 40 |
+| --reduced-motion | JECODE_REDUCED_MOTION=1 | Off |
+| --auto-approve | JECODE_AUTO_APPROVE=1 | Off |
+
+Persistent preferences live in **~/.jecode/settings.json**. Explicitly saved
+credentials live in **~/.jecode/credentials.json** with owner-only permissions
+where the operating system supports them. Environment credentials always win.
+
+Jecode has one interface theme: dark Steel. **NO_COLOR** is supported for
+terminals and pipelines that disable colour.
+
+## Automation
+
+When stdin or stdout is piped, Jecode switches to a plain line-oriented mode:
+
+~~~console
+printf "explain this project\n" | jecode --root .
+~~~
+
+Dangerous tools stay denied in batch mode unless **--auto-approve** is supplied
+explicitly.
+
+## Safety model
+
+Jecode treats model output, workspace content, tool output, and terminal text as
+untrusted data.
+
+- Tool paths are confined to the selected workspace. Writes reject symlink and
+  junction components, then revalidate the boundary during atomic replacement.
+- Dangerous tools require approval unless the process was started with
+  **--auto-approve**.
+- Credential fields are masked and excluded from transcripts. Approved shell
+  commands receive no credential-like environment variables, and recognized
+  credential values are redacted before tool output reaches the model, screen,
+  history, or export.
+- Terminal control characters are neutralized before rendering.
+- Remote Ollama endpoints require HTTPS. Provider HTTP redirects are rejected
+  rather than followed across an implicit trust boundary.
+- Provider handshakes and idle response bodies have finite deadlines. Only
+  idempotent catalogue reads retry; generation requests are never replayed.
+- Model and filesystem input are bounded before they reach the screen or
+  provider.
+
+`run_command` is not an operating-system sandbox: an approved shell command can
+still access files and account resources available to the current user. Review
+commands carefully and reserve **--auto-approve** for controlled environments.
+
+Please read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
+
+## Community
+
+Jecode is built around people using the product and telling us where the loop
+can improve.
+
+- Ask questions, share workflows, and explore ideas in
+  [GitHub Discussions](https://github.com/giovannijecha/jecode/discussions).
+- Report reproducible bugs and focused feature requests through
+  [GitHub Issues](https://github.com/giovannijecha/jecode/issues).
+- Report security concerns privately through the repository Security tab.
+
+Public pull requests are not accepted at this stage; code changes remain a
+maintainer/collaborator workflow. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+short routing guide and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
+expectations.
+
+## Development
+
+~~~console
+npm ci
+npm run check
+~~~
+
+The visual lab exercises the TUI without a provider, network access, tool
+execution, or workspace writes:
+
+~~~console
+npm run tui:lab
+~~~
+
+For a manual long-session rendering probe, run **npm run bench:transcript**.
+
+Architecture and security boundaries are documented in
+[docs/architecture.md](docs/architecture.md). Brand assets and usage rules live
+in [docs/brand.md](docs/brand.md).
+
+## License
+
+Jecode is available under the [MIT License](LICENSE).

package/bin/jecode.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const major = Number.parseInt(process.versions.node, 10);
+if (major < 24) {
+  process.stderr.write(
+    `jecode requires Node.js 24 or newer (current: ${process.versions.node})\n`,
+  );
+  process.exitCode = 1;
+} else {
+  await import("../dist/main.js");
+}

package/dist/atomic.js

@@ -0,0 +1,78 @@
+// Crash-safe replacement of one file, using a verified temporary sibling and
+// rename.
+import { lstat, open, rename, rm, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+export async function atomicWrite(file, content, options = {}) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle;
+    let identity;
+    try {
+        await options.validate?.("before-open");
+        const permissions = options.mode ?? (await existingMode(file));
+        handle = await open(temporary, "wx", permissions);
+        identity = fileIdentity(await handle.stat());
+        await options.validate?.("before-write");
+        await assertNamedFile(temporary, identity);
+        await handle.writeFile(content, "utf8");
+        if (permissions !== undefined && process.platform !== "win32") {
+            await handle.chmod(permissions);
+        }
+        await handle.sync();
+        identity = fileIdentity(await handle.stat());
+        await options.validate?.("before-rename");
+        await assertNamedFile(temporary, identity);
+        await rename(temporary, file);
+        const completed = handle;
+        handle = undefined;
+        await completed.close().catch(() => undefined);
+    }
+    catch (error) {
+        if (handle !== undefined) {
+            await handle.truncate(0).catch(() => undefined);
+            await handle.sync().catch(() => undefined);
+            await handle.close().catch(() => undefined);
+            handle = undefined;
+        }
+        await removeTemporary(temporary, identity, options.validate);
+        throw error;
+    }
+}
+async function assertNamedFile(file, expected) {
+    const details = await lstat(file);
+    if (details.isSymbolicLink() || !sameFile(expected, fileIdentity(details))) {
+        throw new Error("atomic write target changed during replacement");
+    }
+}
+async function removeTemporary(file, expected, validate) {
+    if (expected === undefined)
+        return;
+    try {
+        await validate?.("before-cleanup");
+        await assertNamedFile(file, expected);
+        await rm(file);
+    }
+    catch {
+        // A changed path is no longer ours to remove.
+    }
+}
+function fileIdentity(details) {
+    return { dev: details.dev, ino: details.ino, birthtimeMs: details.birthtimeMs };
+}
+function sameFile(left, right) {
+    if (left.dev !== right.dev || left.ino !== right.ino)
+        return false;
+    return left.ino !== 0 || left.birthtimeMs === right.birthtimeMs;
+}
+async function existingMode(file) {
+    if (process.platform === "win32")
+        return undefined;
+    try {
+        return (await stat(file)).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}

package/dist/batch-view.js

@@ -0,0 +1,17 @@
+// Project semantic blocks into a compact transcript for pipes.
+import { render } from "./tui/blocks.js";
+export function renderBatch(block, width, pal) {
+    const rows = [];
+    let lastWasBlank = false;
+    for (const rendered of render(block, width, pal)) {
+        const line = rendered.trimEnd();
+        const blank = line === "";
+        if (blank && lastWasBlank)
+            continue;
+        rows.push(line);
+        lastWasBlank = blank;
+    }
+    while (rows.at(-1) === "")
+        rows.pop();
+    return rows;
+}

package/dist/batch.js

@@ -0,0 +1,100 @@
+// The non-interactive path: stdin is a pipe, so there is no screen to own.
+//
+// It exists so the agent can be scripted and tested. It shares the controller,
+// the tools and the block renderer with the TUI — only the surface differs.
+import * as readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { runTurn } from "./controller.js";
+import { handleCommand } from "./commands.js";
+import { renderBatch } from "./batch-view.js";
+import { columns } from "./ui/render.js";
+import { terminalText } from "./ui/terminal-text.js";
+import { recordUsage } from "./usage.js";
+export async function runBatch(session, environment = {}) {
+    const rl = environment.lines === undefined ? readline.createInterface({ input: stdin }) : undefined;
+    const lines = environment.lines ?? rl;
+    const write = environment.write ?? ((text) => stdout.write(text));
+    const width = environment.width ?? columns();
+    const emit = (block) => {
+        for (const line of renderBatch(block, width, session.palette))
+            write(`${line}\n`);
+    };
+    try {
+        for await (const raw of lines) {
+            const line = raw.trim();
+            if (line === "")
+                continue;
+            if (line.startsWith("/")) {
+                if ((await handleCommand(line, session, { emit })) === "exit")
+                    break;
+                continue;
+            }
+            write(`> ${terminalText(line)}\n`);
+            session.history.push({ role: "user", content: [{ kind: "text", text: line }] });
+            const turn = events(emit, session);
+            try {
+                await runTurn(session.history, options(session), turn);
+            }
+            catch (error) {
+                emit({ kind: "notice", text: error.message, tone: "error" });
+            }
+            finally {
+                turn.flush();
+            }
+        }
+    }
+    finally {
+        rl?.close();
+    }
+}
+function options(session) {
+    return {
+        provider: session.provider,
+        tools: session.tools,
+        model: session.model,
+        system: session.system,
+        maxTokens: session.config.maxTokens,
+        effort: session.config.effort,
+        maxSteps: session.config.maxSteps,
+        toolContext: { root: session.config.root },
+    };
+}
+// Prose is buffered rather than streamed: without a screen to repaint there is
+// nothing to gain from partial lines, and plenty to lose in readability.
+function events(emit, session) {
+    let answer = "";
+    const flush = () => {
+        if (answer === "")
+            return;
+        emit({ kind: "answer", text: answer });
+        answer = "";
+    };
+    return {
+        flush,
+        onStream(event) {
+            if (event.kind === "text")
+                answer += event.text;
+        },
+        onToolCall() {
+            flush();
+        },
+        onToolResult(call, result, summary) {
+            emit({
+                kind: "tool",
+                name: call.name,
+                target: "",
+                right: summary ?? "",
+                tone: result.isError ? "fail" : "ok",
+            });
+        },
+        approve() {
+            flush();
+            // Nobody is watching a pipe. Approval has to be granted up front with
+            // --auto-approve, never inferred from silence.
+            return Promise.resolve(session.config.autoApprove);
+        },
+        onUsage(usage) {
+            recordUsage(session.usage, usage);
+        },
+    };
+}

package/dist/cli-info.js

@@ -0,0 +1,40 @@
+// Information requests that finish before configuration or terminal takeover.
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+const HELP = `jecode — an owned coding agent for the terminal
+
+Usage:
+  jecode [options]
+
+Options:
+  --root <path>          workspace root (default: current directory)
+  --provider <id>        anthropic, openai, or ollama
+  --model <id>           model for the selected provider
+  --ollama-host <url>    Ollama Cloud, local, or custom endpoint
+  --effort <level>       low, medium, high, or max
+  --max-tokens <number>  output-token ceiling
+  --max-steps <number>   tool-loop ceiling
+  --reduced-motion       disable animated terminal states
+  --auto-approve         allow dangerous tools for this process
+  -h, --help             show this help
+  -v, --version          show the installed version
+
+Inside Jecode, type / to discover interactive commands.`;
+export async function showCliInfo(args, applicationRoot, write) {
+    if (args.includes("--help") || args.includes("-h")) {
+        write(`${HELP}\n`);
+        return true;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        write(`${await packageVersion(applicationRoot)}\n`);
+        return true;
+    }
+    return false;
+}
+async function packageVersion(applicationRoot) {
+    const manifest = JSON.parse(await readFile(path.join(applicationRoot, "package.json"), "utf8"));
+    if (typeof manifest.version !== "string" || manifest.version === "") {
+        throw new Error("package version is missing");
+    }
+    return manifest.version;
+}