@illuminis/comprism 0.1.5 → 0.1.6

package/out/machine/executor/git.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitStatus = gitStatus;
+exports.gitDiff = gitDiff;
+exports.gitLog = gitLog;
+exports.gitBranch = gitBranch;
+exports.gitCommit = gitCommit;
+exports.gitPush = gitPush;
+/**
+ * Reading the repository, and recording work in it.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D23 to D27.
+ *
+ * **Pushing is the only thing here that sends anything anywhere**, and it is
+ * the only one the server has to have allowed first. Pull requests, reviews,
+ * checks and releases are not git operations at all: they go through GitHub's
+ * own API, on the server, because they need the tenant's credential and that
+ * must never be sent to a client.
+ *
+ * So the split is by what each thing needs. A push needs the repository, which
+ * is here. A pull request needs the credential, which is there.
+ *
+ * Every command goes through `runCommand`, so the folder boundary, the trimmed
+ * environment, the timeout and the output cap all apply here too rather than
+ * being reimplemented for git.
+ */
+const shell_1 = require("./shell");
+/** Every git call is a program and a list of arguments, with no shell.
+ *
+ *  A commit message is written by a model and can contain anything: quotes,
+ *  backticks, a newline, a semicolon. Pasting one into a shell string is how a
+ *  message becomes a second command, and quoting it for one shell broke it on
+ *  another: Windows kept the POSIX quotes as part of the message. */
+const git = (args, opts) => (0, shell_1.runProgram)("git", args, opts);
+async function gitStatus(opts) {
+    // Porcelain, because the human-readable format changes between versions and
+    // the model has to be able to rely on the shape.
+    const r = await git(["status", "--porcelain=v1", "--branch"], opts);
+    if (!r.isError && /^exit 0/.test(r.content) && r.content.trim().split("\n").length <= 3) {
+        return { ...r, content: `${r.content}\n\n[Nothing has changed in the working tree.]` };
+    }
+    return r;
+}
+async function gitDiff(opts) {
+    const parts = ["--no-pager", "diff"];
+    if (opts.staged)
+        parts.push("--staged");
+    // Color off explicitly: a diff full of escape codes costs tokens and reads
+    // as noise to a model.
+    parts.push("--no-color");
+    if (opts.path)
+        parts.push("--", opts.path);
+    return git(parts, opts);
+}
+async function gitLog(opts) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));
+    const parts = [
+        "--no-pager", "log", "-n", String(limit),
+        // One argument, spaces and all. When this went through a shell it had to be
+        // quoted, or git read "%an" as a revision and failed with "ambiguous
+        // argument", which reads like a broken repository.
+        "--pretty=format:%h %an %ar %s",
+    ];
+    if (opts.path)
+        parts.push("--", opts.path);
+    return git(parts, opts);
+}
+async function gitBranch(name, opts) {
+    if (!/^[\w./-]{1,120}$/.test(name)) {
+        return {
+            isError: true,
+            content: `Refused: ${name} is not a usable branch name. Letters, numbers, dots, dashes, underscores and slashes only.`,
+        };
+    }
+    return git(["checkout", "-b", name], opts);
+}
+async function gitCommit(message, opts) {
+    if (!message.trim()) {
+        return { isError: true, content: "Refused: a commit needs a message." };
+    }
+    // Only the files named: what the agent changed, or what the person named.
+    // Never "add everything", which would sweep in the person's own unrelated
+    // work (manual 5.17).
+    if (!opts.paths?.length) {
+        return {
+            isError: true,
+            content: "Refused: nothing to commit that this session changed. Name the files to commit.",
+        };
+    }
+    const staged = await git(["add", "--", ...opts.paths], opts);
+    if (staged.isError || !/^exit 0/.test(staged.content))
+        return { ...staged, isError: true };
+    // Nothing to commit is a normal outcome, not a failure. Reported plainly so
+    // the model does not conclude that committing is broken and try again.
+    const check = await git(["diff", "--staged", "--quiet"], opts);
+    if (/^exit 0\b/.test(check.content)) {
+        return { content: "Nothing to commit: no changes are staged.", summary: "nothing to commit" };
+    }
+    // Attribution, always. A commit that hides having been written by an agent is
+    // a commit somebody later reads as a colleague's careful work, and the whole
+    // record this product keeps depends on that not happening.
+    const trailer = "\n\nCo-authored-by: illuminis coding agent <agent@illuminis.ai>";
+    const made = await git(["commit", "-m", message + trailer], opts);
+    // A commit hook that refused it is a failed commit, said so (manual 5.17).
+    // Its output is the reason; what was staged is left staged for the person.
+    if (!/^exit 0/.test(made.content)) {
+        return { ...made, isError: true, summary: "commit failed", content: `Commit failed. ${made.content}` };
+    }
+    return { ...made, summary: `committed ${opts.paths.join(", ")}` };
+}
+/** Send commits to the remote.
+ *
+ *  Reached only after the server has allowed it: the branch is one the person
+ *  named for this repository, it is not a branch the project is built from, and
+ *  they have just confirmed it. This function does not re-decide any of that,
+ *  and it must not: a client that could decide whether it may publish is a
+ *  client that could grant itself permission.
+ *
+ *  **There is no force push and there is no upstream rewrite.** Not as an
+ *  option, not behind a flag. Everything on the remote stays recoverable by
+ *  whoever is working from it.
+ */
+async function gitPush(branch, opts) {
+    if (!/^[\w./-]{1,120}$/.test(branch)) {
+        return { isError: true, content: `Refused: ${branch} is not a usable branch name.` };
+    }
+    // What is about to go, named before it goes. A push that reports success
+    // without saying what it sent is a push nobody can check afterwards.
+    // A branch the remote has not seen yet has no range to compare with, so the
+    // last five commits stand in for it.
+    let ahead = await git(["--no-pager", "log", "--oneline", `origin/${branch}..HEAD`], opts);
+    if (!/^exit 0/.test(ahead.content))
+        ahead = await git(["--no-pager", "log", "--oneline", "-5"], opts);
+    // `-u` on a new branch so later pushes need no arguments, and nothing else.
+    // No `--force`, no `--force-with-lease`, no `+refs` refspec.
+    const pushed = await git(["push", ...(opts.createRemote ? ["-u"] : []), "origin", branch], opts);
+    if (pushed.isError || !/^exit 0/.test(pushed.content)) {
+        return { ...pushed, isError: true };
+    }
+    return {
+        content: `Pushed to ${branch}.\n\nWhat went:\n${ahead.content}`,
+        summary: `pushed ${branch}`,
+    };
+}

package/out/machine/executor/hooks.d.ts

@@ -0,0 +1,51 @@
+/** The settings files that can hold hooks, sent as read for `comprism hooks`. */
+export declare const FILES: string[];
+/** One hook as the service hands it over. */
+export interface PlannedHook {
+    when: string;
+    on?: string;
+    command: string;
+    what?: string | null;
+    timeout_s?: number;
+    source?: string;
+}
+/** The hooks to run around one action, in order. */
+export interface HookPlan {
+    before?: PlannedHook[];
+    after?: PlannedHook[];
+}
+/** Set inside a hook's own commands, so nothing they do runs hooks again. */
+export declare const IN_HOOK = "COMPRISM_IN_HOOK";
+export declare function insideHook(): boolean;
+/** The settings files present in this project, as text, for the service. */
+export declare function hookFiles(root: string): Record<string, string>;
+export interface HookContext {
+    when: string;
+    action?: string;
+    args?: Record<string, unknown>;
+    facts?: Record<string, unknown>;
+}
+export interface HookRun {
+    hook: PlannedHook;
+    ok: boolean;
+    timedOut: boolean;
+    output: string;
+}
+export interface HooksOutcome {
+    runs: HookRun[];
+    /** Set when a `before` hook refused the action. */
+    refusedBy?: string;
+    detail?: string;
+    /** `after`, `job_start`, `job_end` and `waiting` hooks that failed. */
+    failed: string[];
+}
+/**
+ * Run the hooks the service named, one after another, in its order.
+ *
+ * Details go in as `COMPRISM_` variables and as one JSON object on standard
+ * input. Each hook has its own time limit (30 seconds unless the service said
+ * otherwise) and is stopped and reported when it runs over.
+ */
+export declare function runHooks(root: string, hooks: PlannedHook[], ctx: HookContext): Promise<HooksOutcome>;
+/** One line per hook that ran, for the full view and `hooks test` (10.10). */
+export declare function reportLines(outcome: HooksOutcome): string[];

package/out/machine/executor/hooks.js

@@ -0,0 +1,154 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IN_HOOK = exports.FILES = void 0;
+exports.insideHook = insideHook;
+exports.hookFiles = hookFiles;
+exports.runHooks = runHooks;
+exports.reportLines = reportLines;
+/**
+ * Hooks: running the person's own commands at the moments the service names
+ * (manual 10.9, 10.10).
+ *
+ * Which hooks run, for which action, in what order and with what time limit is
+ * decided by the service and arrives with each action, or with a `run_hooks`
+ * request for a moment of the job. Nothing here matches a hook to an action.
+ * What is left is the physical part: read the project's settings files when
+ * `comprism hooks` asks, and run a command with the details it needs.
+ *
+ * A `before` hook can refuse its action. Nothing a hook does approves one, and
+ * a hook's own commands never set off hooks: they are not the job's actions,
+ * and a command started from inside a hook runs with every hook switched off.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const shell_1 = require("./shell");
+/** The settings files that can hold hooks, sent as read for `comprism hooks`. */
+exports.FILES = [
+    ".completionprism/settings.json",
+    ".completionprism/settings.local.json",
+    ".comprism/settings.json",
+    ".claude/settings.json",
+    ".illuminis/hooks.json",
+];
+/** Set inside a hook's own commands, so nothing they do runs hooks again. */
+exports.IN_HOOK = "COMPRISM_IN_HOOK";
+function insideHook() {
+    return process.env[exports.IN_HOOK] === "1";
+}
+/** The settings files present in this project, as text, for the service. */
+function hookFiles(root) {
+    const out = {};
+    for (const name of exports.FILES) {
+        const file = path.join(root, name);
+        try {
+            if (fs.existsSync(file))
+                out[name] = fs.readFileSync(file, "utf8").slice(0, 200_000);
+        }
+        catch {
+            /* unreadable is the same as absent to the service */
+        }
+    }
+    return out;
+}
+function fileOf(args) {
+    return String(args.path ?? args.file_path ?? args.to ?? "");
+}
+function said(h) {
+    return h.what || h.command;
+}
+/**
+ * Run the hooks the service named, one after another, in its order.
+ *
+ * Details go in as `COMPRISM_` variables and as one JSON object on standard
+ * input. Each hook has its own time limit (30 seconds unless the service said
+ * otherwise) and is stopped and reported when it runs over.
+ */
+async function runHooks(root, hooks, ctx) {
+    const outcome = { runs: [], failed: [] };
+    if (!hooks.length || insideHook())
+        return outcome;
+    const args = ctx.args ?? {};
+    const input = JSON.stringify({ when: ctx.when, action: ctx.action ?? null, input: args,
+        ...(ctx.facts ?? {}) });
+    for (const hook of hooks) {
+        const secs = Math.max(1, Number(hook.timeout_s ?? 30));
+        const result = await (0, shell_1.runCommand)(hook.command, {
+            root,
+            timeoutMs: secs * 1000,
+            input,
+            label: `hook: ${hook.command}`, // client-strings-allowed: the hook's own command, shown verbatim in the job log
+            extraEnv: {
+                [exports.IN_HOOK]: "1",
+                COMPRISM_WHEN: ctx.when,
+                COMPRISM_ACTION: ctx.action ?? "",
+                COMPRISM_FILE: fileOf(args),
+                COMPRISM_COMMAND: String(args.command ?? ""),
+                COMPRISM_OUTCOME: String(ctx.facts?.outcome ?? ""),
+                // The earlier names, so a script written for them keeps working.
+                ILLUMINIS_ACTION: ctx.action ?? "",
+                ILLUMINIS_PATH: fileOf(args),
+            },
+        });
+        const timedOut = Boolean(result.facts?.timed_out);
+        const ok = !result.isError && /^exit 0/.test(result.content);
+        const output = timedOut
+            ? `stopped after ${secs}s, its time limit`
+            : result.content.replace(/^exit -?\d+\s*/, "").trim().slice(0, 2000);
+        outcome.runs.push({ hook, ok, timedOut, output });
+        if (ok)
+            continue;
+        if (ctx.when === "before") {
+            outcome.refusedBy = hook.command;
+            outcome.detail = `${hook.what ?? "A hook in this project"} refused this`
+                + (timedOut ? ` (it was stopped after ${secs}s, its time limit)` : "")
+                + (output && !timedOut ? `: ${output.slice(0, 500)}` : ".");
+            return outcome;
+        }
+        outcome.failed.push(`${said(hook)}: ${timedOut ? `stopped after ${secs}s, its time limit` : output.slice(0, 300) || "failed"}`);
+    }
+    return outcome;
+}
+/** One line per hook that ran, for the full view and `hooks test` (10.10). */
+function reportLines(outcome) {
+    const lines = [];
+    for (const run of outcome.runs) {
+        const mark = run.ok ? "ok  " : run.timedOut ? "time" : "fail";
+        lines.push(`${mark}  hook ${run.hook.when}  ${run.hook.command}`);
+        for (const l of run.output.split("\n").filter(Boolean).slice(0, 20))
+            lines.push(`      ${l}`);
+    }
+    return lines;
+}

package/out/machine/executor/index.d.ts

@@ -0,0 +1,45 @@
+import * as hooks from "./hooks";
+import { ToolServers } from "./toolservers";
+import { RunResult, guessTestCommand, stopEverything, stopForeground } from "./shell";
+export { stopEverything, stopForeground, guessTestCommand };
+export type { RunResult };
+/** Everything a machine with a shell can do. Sent to the server on hello, and
+ *  the catalog offered to the model is narrowed to it, so a client is never
+ *  told about an action it cannot perform. */
+export declare const NATIVE_CAPABILITIES: string[];
+export interface ExecutorOptions {
+    root: string;
+    /** Folders the person added for this job (manual 2.3). */
+    added?: string[];
+    /** Called with each chunk of a running command's output, so a terminal can
+     *  show it as it happens rather than in one block at the end. */
+    onOutput?: (chunk: string) => void;
+}
+export declare class NativeExecutor {
+    /** What this machine can do. The browser actions only where a browser is
+     *  installed (manual 10.16); the service offers them only when switched on. */
+    readonly capabilities: string[];
+    /** The job's browser, started on first use (10.16). */
+    private browser?;
+    /** Close what this job opened on the machine: its browser. */
+    close(): void;
+    readonly root: string;
+    private readonly onOutput?;
+    /** The test command, once it has been worked out or supplied. Remembered so a
+     *  job that had to be told does not have to be told again. */
+    private testCommand?;
+    /** Whether the last test run passed. The grading signal the whole product
+     *  rests on, kept so a session can report it when the job ends. */
+    lastTestsPassed?: boolean;
+    /** The operating system's sandbox, set when the service turns it on for a
+     *  job (manual 4.12). Absent, commands run with the person's own access. */
+    sandbox?: import("./sandbox").Sandbox;
+    constructor(opts: ExecutorOptions);
+    /** One executor per helper copy, rooted there and nowhere else. */
+    private readonly inCopies;
+    /** Tool servers this job started (manual 9.10), stopped when it ends. */
+    readonly toolServers: ToolServers;
+    execute(name: string, a: Record<string, unknown>, plan?: hooks.HookPlan): Promise<RunResult>;
+    private browse;
+    private perform;
+}