@giovannijecha/jecode 0.1.5-rc.2

package/dist/commands.js

@@ -0,0 +1,171 @@
+// Slash-command registry and dispatcher.
+//
+// One of them does reach the network — a menu of models cannot be built
+// without asking the provider what it has — but none of them ever sends a
+// message. Provider and credential interaction lives in provider-commands.ts;
+// this file keeps command discovery, dispatch, and local session operations.
+import { heading } from "./tui/picker.js";
+import { modelsCommand, providersCommand, setupCommand } from "./provider-commands.js";
+import { credentialsCommand } from "./credential-commands.js";
+import { effortCommand, settingsCommand } from "./settings-command.js";
+import { emptyUsage, formatTokens } from "./usage.js";
+/**
+ * The commands, declared once.
+ *
+ * `/help` and the completion menu both read this list, so a command cannot
+ * exist in the switch below and be missing from the two places that tell the
+ * user it exists.
+ *
+ * Deliberately short. `/settings` owns persistent defaults; the narrower
+ * provider, model, effort, credential, and setup commands remain useful direct
+ * paths into the same interactions.
+ */
+export const COMMANDS = [
+    { name: "help", blurb: "this list" },
+    { name: "exit", blurb: "exit and restore the terminal" },
+    { name: "new", blurb: "start a clean in-memory session" },
+    { name: "usage", blurb: "show token usage for this session" },
+    { name: "export", blurb: "save this transcript as Markdown" },
+    { name: "permissions", blurb: "review or revoke remembered approvals" },
+    { name: "settings", blurb: "change and save jecode defaults" },
+    { name: "effort", blurb: "set the reasoning effort" },
+    { name: "credentials", blurb: "inspect, replace, or forget API keys" },
+    { name: "setup", blurb: "make the current provider ready" },
+    { name: "models", blurb: "pick a model, from what the provider offers" },
+    { name: "providers", blurb: "pick a provider" },
+];
+export async function handleCommand(line, session, host) {
+    const [name] = line.slice(1).trim().split(/\s+/);
+    switch (name) {
+        case "help":
+            host.emit(help());
+            return "handled";
+        case "exit":
+            return "exit";
+        case "new":
+            session.history.length = 0;
+            session.usage = emptyUsage();
+            host.reset?.();
+            host.emit({ kind: "notice", text: "new session · history, usage, and approvals cleared", tone: "info" });
+            return "handled";
+        case "usage":
+            host.emit(usage(session));
+            return "handled";
+        case "export":
+            if (host.exportTranscript === undefined) {
+                host.emit({ kind: "notice", text: "export needs the interactive screen", tone: "warn" });
+            }
+            else {
+                const saved = await host.exportTranscript();
+                host.emit({ kind: "notice", text: `transcript saved to ${saved}`, tone: "info" });
+            }
+            return "handled";
+        case "permissions":
+            await permissions(session, host);
+            return "handled";
+        case "settings":
+            await settingsCommand(session, host);
+            return "handled";
+        case "effort":
+            await effortCommand(session, host);
+            return "handled";
+        case "credentials":
+            await credentialsCommand(session, host);
+            return "handled";
+        case "setup":
+            await setupCommand(session, host);
+            return "handled";
+        case "models":
+            await modelsCommand(session, host);
+            return "handled";
+        case "providers":
+            await providersCommand(session, host);
+            return "handled";
+        default:
+            host.emit({ kind: "notice", text: `unknown command /${name ?? ""} — try /help`, tone: "warn" });
+            return "handled";
+    }
+}
+function usage(session) {
+    const value = session.usage;
+    const rows = [
+        `  requests${String(value.requests).padStart(18)}`,
+        `  latest context${formatTokens(value.lastInputTokens).padStart(12)}`,
+        `  input${formatTokens(value.inputTokens).padStart(21)}`,
+        `  output${formatTokens(value.outputTokens).padStart(20)}`,
+    ];
+    if (value.cachedInputTokens > 0)
+        rows.push(`  cached input${formatTokens(value.cachedInputTokens).padStart(14)}`);
+    if (value.cacheWriteInputTokens > 0) {
+        rows.push(`  cache writes${formatTokens(value.cacheWriteInputTokens).padStart(14)}`);
+    }
+    if (value.reasoningTokens > 0)
+        rows.push(`  reasoning${formatTokens(value.reasoningTokens).padStart(17)}`);
+    return { kind: "list", items: rows.map((text) => ({ text, dim: false })) };
+}
+async function permissions(session, host) {
+    const choose = chooser(host);
+    if (choose === undefined)
+        return;
+    if (session.config.autoApprove) {
+        host.emit({
+            kind: "notice",
+            text: "--auto-approve is active · every dangerous call is allowed for this process",
+            tone: "warn",
+        });
+    }
+    const entries = host.permissions?.() ?? [];
+    if (entries.length === 0) {
+        host.emit({ kind: "notice", text: "no remembered session permissions", tone: "info" });
+        return;
+    }
+    const index = await choose({
+        title: heading("revoke permission", "applies only to this session", session.palette),
+        right: "↑↓ enter · esc close",
+        options: [
+            ...entries.map((entry) => ({ label: entry.label, hint: "revoke" })),
+            { label: "all remembered permissions", hint: "revoke all" },
+        ],
+        index: 0,
+    });
+    if (index === undefined)
+        return;
+    if (index === entries.length) {
+        host.revokePermission?.();
+        host.emit({ kind: "notice", text: "all remembered permissions revoked", tone: "info" });
+        return;
+    }
+    const entry = entries[index];
+    if (entry === undefined)
+        return;
+    host.revokePermission?.(entry.key);
+    host.emit({ kind: "notice", text: `revoked · ${entry.label}`, tone: "info" });
+}
+function chooser(host) {
+    if (host.choose === undefined) {
+        host.emit({ kind: "notice", text: "that command needs the screen", tone: "warn" });
+    }
+    return host.choose;
+}
+function help() {
+    const width = Math.max(...COMMANDS.map((c) => label(c).length));
+    return {
+        kind: "list",
+        items: [
+            ...COMMANDS.map((command) => ({
+                text: `  ${label(command).padEnd(width + 4)}${command.blurb}`,
+                dim: false,
+            })),
+            { text: "", dim: true },
+            { text: "  esc interrupts a running turn · ctrl+c exits", dim: true },
+            { text: "  wheel or pgup / pgdn scrolls · ctrl+l redraws", dim: true },
+            { text: "  ctrl+o expands the latest reasoning or tool details", dim: true },
+            { text: "  type in the model picker to filter · home/end jumps", dim: true },
+            { text: "  ↑↓ selects an open menu · tab completes · esc closes it", dim: true },
+            { text: "  enter selects or sends · alt+enter starts a new line", dim: true },
+        ],
+    };
+}
+function label(command) {
+    return `/${command.name}`;
+}

package/dist/config.js

@@ -0,0 +1,97 @@
+// Runtime configuration: flags, environment, saved defaults, built-ins.
+import * as path from "node:path";
+import { EFFORTS, readSettings } from "./settings.js";
+import { parseOllamaEndpoint } from "./providers/ollama-endpoint.js";
+const FLAGS = [
+    "provider",
+    "model",
+    "ollama-host",
+    "reduced-motion",
+    "effort",
+    "max-tokens",
+    "max-steps",
+    "root",
+    "auto-approve",
+];
+export function loadConfig(argv, saved = readSettings()) {
+    const flags = parseFlags(argv);
+    // A flag nobody declared is a typo. Swallowed in silence it becomes a
+    // setting the user believes is on, and the run that ignores it looks like
+    // the feature is broken rather than misspelled.
+    for (const name of Object.keys(flags)) {
+        if (!FLAGS.includes(name)) {
+            throw new Error(`unknown flag --${name} (known: ${FLAGS.map((f) => `--${f}`).join(", ")})`);
+        }
+    }
+    const providerId = pick(flags.provider, process.env.JECODE_PROVIDER, saved.provider ?? "anthropic");
+    const ollamaHost = optional(flags["ollama-host"], process.env.OLLAMA_HOST, saved.ollamaHost);
+    const effort = pick(flags.effort, process.env.JECODE_EFFORT, saved.effort ?? "high");
+    if (!EFFORTS.includes(effort)) {
+        throw new Error(`unknown effort "${effort}" (expected one of: ${EFFORTS.join(", ")})`);
+    }
+    return {
+        providerId,
+        model: pick(flags.model, process.env.JECODE_MODEL, saved.models?.[providerId] ?? ""),
+        ...(ollamaHost === undefined
+            ? {}
+            : { ollamaHost: parseOllamaEndpoint(ollamaHost).baseUrl }),
+        reducedMotion: bool(flags["reduced-motion"], process.env.JECODE_REDUCED_MOTION, saved.reducedMotion ?? false),
+        effort,
+        // Every request streams, so a large ceiling costs nothing in timeout risk.
+        maxTokens: toInt(pick(flags["max-tokens"], process.env.JECODE_MAX_TOKENS, String(saved.maxTokens ?? 64000)), "max-tokens"),
+        maxSteps: toInt(pick(flags["max-steps"], process.env.JECODE_MAX_STEPS, String(saved.maxSteps ?? 40)), "max-steps"),
+        root: path.resolve(pick(flags.root, undefined, process.cwd())),
+        autoApprove: flags["auto-approve"] === "true" || process.env.JECODE_AUTO_APPROVE === "1",
+    };
+}
+function bool(flag, env, fallback) {
+    if (flag !== undefined)
+        return flag === "true" || flag === "1";
+    if (env !== undefined && env !== "")
+        return env === "true" || env === "1";
+    return fallback;
+}
+function pick(flag, env, fallback) {
+    if (flag !== undefined && flag !== "")
+        return flag;
+    if (env !== undefined && env !== "")
+        return env;
+    return fallback;
+}
+function optional(flag, env, fallback) {
+    if (flag !== undefined && flag !== "")
+        return flag;
+    if (env !== undefined && env !== "")
+        return env;
+    return fallback;
+}
+function toInt(value, name) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`--${name} must be a positive integer`);
+    return n;
+}
+// Accepts --key value, --key=value, and bare --flag (which reads as "true").
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined || !arg.startsWith("--"))
+            continue;
+        const body = arg.slice(2);
+        const eq = body.indexOf("=");
+        if (eq !== -1) {
+            flags[body.slice(0, eq)] = body.slice(eq + 1);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[body] = next;
+            i++;
+        }
+        else {
+            flags[body] = "true";
+        }
+    }
+    return flags;
+}

package/dist/controller.js

@@ -0,0 +1,90 @@
+// The single controller.
+//
+// One loop, in dialogue with the user. It never delegates: no subagent, no
+// worker, no orchestrator split, no second loop. When a task is too big, this
+// loop iterates. That constraint is implemented here, not left as a product claim.
+import { isToolCall } from "./types.js";
+import { findTool, runTool, toolSpecs } from "./tools/index.js";
+export const MAX_TOOL_CALLS_PER_STEP = 32;
+/**
+ * Run one user turn to completion: keep exchanging with the model until it
+ * stops asking for tools. `history` is mutated in place, so an aborted turn
+ * still leaves the conversation in a consistent state.
+ */
+export async function runTurn(history, options, events, signal) {
+    const specs = toolSpecs(options.tools);
+    for (let step = 0; step < options.maxSteps; step++) {
+        events.onStep?.(step + 1, options.maxSteps);
+        // The message is displayed as it streams; what comes back here is the
+        // assembled version, which exists to be appended to the history.
+        const assistant = await options.provider.send({
+            model: options.model,
+            system: options.system,
+            messages: history,
+            tools: specs,
+            maxTokens: options.maxTokens,
+            effort: options.effort,
+            signal,
+            onStream: (event) => events.onStream(event),
+            onStatus: (status) => events.onStatus?.(status),
+        });
+        const calls = assistant.content.filter(isToolCall);
+        if (calls.length > MAX_TOOL_CALLS_PER_STEP) {
+            throw new Error(`provider returned ${calls.length} tool calls in one step (maximum ${MAX_TOOL_CALLS_PER_STEP})`);
+        }
+        history.push(assistant);
+        if (assistant.usage !== undefined)
+            events.onUsage?.(assistant.usage);
+        if (calls.length === 0)
+            return; // the model is done — hand back to the user
+        // Calls run one after another because approval prompts serialise anyway,
+        // but every result from this step goes back in a SINGLE message. Splitting
+        // them teaches the model to stop batching its calls.
+        const results = [];
+        for (let index = 0; index < calls.length; index++) {
+            const call = calls[index];
+            events.onToolProgress?.(index + 1, calls.length);
+            const preview = await look(call, options);
+            events.onToolCall(call, preview);
+            const { result, summary } = await settle(call, options, events, signal, preview);
+            events.onToolResult(call, result, summary);
+            results.push(result);
+        }
+        history.push({ role: "user", content: results });
+    }
+    throw new Error(`gave up after ${options.maxSteps} steps without finishing (raise --max-steps)`);
+}
+async function settle(call, options, events, signal, preview) {
+    const tool = findTool(options.tools, call.name);
+    if (tool === undefined) {
+        return refuse(call, `no such tool: ${call.name}`, "unknown tool");
+    }
+    if (tool.dangerous && !(await events.approve(call))) {
+        return refuse(call, "the user declined this call — ask them how to proceed", "declined");
+    }
+    return runTool(tool, call, { ...options.toolContext, signal, preview });
+}
+function refuse(call, reason, summary) {
+    return {
+        result: { kind: "tool_result", id: call.id, output: reason, isError: true },
+        summary,
+    };
+}
+/**
+ * What the call would change, asked of the tool that would change it.
+ *
+ * Read-only and best-effort by construction: a preview that throws — a missing
+ * file, a match that is not there — is simply no preview. Nothing about the
+ * turn depends on it, because it exists for the user, not for the model.
+ */
+async function look(call, options) {
+    const tool = findTool(options.tools, call.name);
+    if (tool?.preview === undefined)
+        return undefined;
+    try {
+        return await tool.preview(call.input, options.toolContext);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/credential-commands.js

@@ -0,0 +1,134 @@
+// Credential command flows shared by setup and provider selection.
+import { heading } from "./tui/picker.js";
+import { EMPTY } from "./tui/editor.js";
+import { PROVIDERS } from "./providers/index.js";
+import { credentialSource, forgetSaved, hasSaved, hold, keep, storeLabel, } from "./credentials.js";
+/** Ask for a key, then ask separately whether it may be written to disk. */
+export async function askForKey(name, host, pal) {
+    if (host.type === undefined || host.choose === undefined)
+        return false;
+    const field = {
+        title: [
+            { text: "paste key  ", fg: pal.ink.attention, bold: true },
+            { text: name, fg: pal.ink.bright, bold: true },
+        ],
+        right: "enter ok · esc skip",
+        editor: EMPTY,
+        secret: true,
+        note: "read from the environment first — an exported value still wins",
+    };
+    const value = await host.type(field);
+    if (value === undefined)
+        return false;
+    const index = await host.choose({
+        title: heading("remember it?", name, pal),
+        right: "↑↓ enter",
+        options: [
+            { label: "just this session", hint: "nothing is written", key: "s" },
+            { label: `save it to ${storeLabel()}`, hint: "owner-only file", key: "w" },
+            { label: "discard it", key: "d" },
+        ],
+        index: 0,
+    });
+    if (index === 0) {
+        hold(name, value);
+        host.emit({ kind: "notice", text: "credential available for this session", tone: "info" });
+        return true;
+    }
+    if (index === 1) {
+        try {
+            await keep(name, value);
+            host.emit({ kind: "notice", text: `credential saved · ${storeLabel()}`, tone: "info" });
+            return true;
+        }
+        catch (error) {
+            host.emit({ kind: "notice", text: `could not save credential · ${error.message}`, tone: "error" });
+            return false;
+        }
+    }
+    host.emit({ kind: "notice", text: "credential discarded", tone: "warn" });
+    return false;
+}
+export async function credentialsCommand(session, host) {
+    const choose = chooser(host);
+    if (choose === undefined)
+        return;
+    const index = await choose({
+        title: heading("credential", "values are never shown", session.palette),
+        right: "↑↓ enter · esc close",
+        options: PROVIDERS.map((provider) => ({
+            label: provider.keyVar,
+            hint: credentialSource(provider.keyVar) ?? "missing",
+        })),
+        index: Math.max(0, PROVIDERS.findIndex((provider) => provider.id === session.provider.id)),
+    });
+    if (index === undefined)
+        return;
+    const provider = PROVIDERS[index];
+    if (provider === undefined)
+        return;
+    const name = provider.keyVar;
+    const source = credentialSource(name);
+    if (source === "environment") {
+        host.emit({
+            kind: "notice",
+            text: `${name} comes from the environment · update it outside jecode and restart`,
+            tone: "info",
+        });
+        if (hasSaved(name))
+            await offerForget(name, session, host, "a saved copy is currently shadowed");
+        return;
+    }
+    const actions = [
+        { label: source === undefined ? "add credential" : "replace credential", key: "r" },
+        ...(hasSaved(name) ? [{ label: "forget saved copy", hint: storeLabel(), key: "f" }] : []),
+        { label: "close", key: "c" },
+    ];
+    const action = await choose({
+        title: heading(name, source ?? "missing", session.palette),
+        right: "↑↓ enter",
+        options: actions,
+        index: 0,
+    });
+    if (action === undefined || action === actions.length - 1)
+        return;
+    if (actions[action]?.key === "f") {
+        await forget(name, host);
+        return;
+    }
+    await askForKey(name, host, session.palette);
+}
+async function offerForget(name, session, host, hint) {
+    if (host.choose === undefined)
+        return;
+    const index = await host.choose({
+        title: heading(name, hint, session.palette),
+        right: "↑↓ enter",
+        options: [
+            { label: "keep saved copy", key: "k" },
+            { label: "forget saved copy", hint: storeLabel(), key: "f" },
+        ],
+        index: 0,
+    });
+    if (index === 1)
+        await forget(name, host);
+}
+async function forget(name, host) {
+    try {
+        const removed = await forgetSaved(name);
+        host.emit({
+            kind: "notice",
+            text: removed ? "saved credential removed" : "no saved credential to remove",
+            tone: removed ? "info" : "warn",
+        });
+    }
+    catch (error) {
+        host.emit({ kind: "notice", text: `could not forget: ${error.message}`, tone: "error" });
+    }
+}
+function chooser(host) {
+    if (host.choose === undefined) {
+        host.emit({ kind: "notice", text: "that command needs the screen", tone: "warn" });
+    }
+    return host.choose;
+}

package/dist/credential-safety.js

@@ -0,0 +1,86 @@
+// The shell needs a useful process environment, not the application's secrets.
+import { credentialValues } from "./credentials.js";
+const REDACTED = "[credential redacted]";
+const SENSITIVE_ENVIRONMENT_NAME = /(?:^|_)(?:API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|PASS|PWD|CREDENTIALS?|AUTH|JWT|COOKIE|PAT)(?:_|$)/i;
+const COMPACT_SENSITIVE_ENVIRONMENT_NAME = /^(?:PGPASSWORD)$/i;
+/** Preserve ordinary tool configuration while withholding credential-like values. */
+export function shellEnvironment(source = process.env) {
+    const environment = {};
+    for (const [name, value] of Object.entries(source)) {
+        if (value !== undefined && !sensitiveEnvironment(name, value))
+            environment[name] = value;
+    }
+    return environment;
+}
+/** Remove values Jecode recognizes as credentials before tool output leaves the shell boundary. */
+export function redactCredentials(text, source = process.env) {
+    return redact(text, secrets(source));
+}
+/** Redact before bounded capture, retaining enough raw overlap for split values. */
+export function credentialRedactor(source = process.env) {
+    const values = secrets(source);
+    const longest = Math.max(0, ...values.map((value) => value.length));
+    let pending = "";
+    return {
+        write(chunk) {
+            const combined = `${pending}${chunk}`;
+            const ready = [];
+            let at = 0;
+            while (at < combined.length) {
+                const complete = values.find((value) => combined.startsWith(value, at));
+                if (complete !== undefined) {
+                    ready.push(REDACTED);
+                    at += complete.length;
+                    continue;
+                }
+                const rest = combined.slice(at);
+                if (rest.length < longest && values.some((value) => value.startsWith(rest))) {
+                    pending = rest;
+                    return ready.join("");
+                }
+                ready.push(combined[at]);
+                at++;
+            }
+            pending = "";
+            return ready.join("");
+        },
+        end() {
+            const last = redact(pending, values);
+            pending = "";
+            return last;
+        },
+    };
+}
+function sensitiveEnvironmentName(name) {
+    const normalized = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[^a-z0-9]+/gi, "_")
+        .replace(/^_+|_+$/g, "");
+    return (SENSITIVE_ENVIRONMENT_NAME.test(normalized) ||
+        COMPACT_SENSITIVE_ENVIRONMENT_NAME.test(normalized));
+}
+function secrets(source) {
+    const values = new Set(credentialValues());
+    for (const [name, value] of Object.entries(source)) {
+        if (value !== undefined && value !== "" && sensitiveEnvironment(name, value))
+            values.add(value);
+    }
+    return [...values].filter((value) => value !== "").sort((left, right) => right.length - left.length);
+}
+function redact(text, values) {
+    let redacted = text;
+    for (const value of values)
+        redacted = redacted.replaceAll(value, REDACTED);
+    return redacted;
+}
+function sensitiveEnvironment(name, value) {
+    if (sensitiveEnvironmentName(name))
+        return true;
+    try {
+        const url = new URL(value);
+        return url.username !== "" || url.password !== "";
+    }
+    catch {
+        return /(?:^|[;\s])(?:password|pwd|token|secret)\s*=\s*[^;\s]+/i.test(value);
+    }
+}