@illuminis/comprism 0.1.3 → 0.1.5

package/out/executor/hooks.d.ts

@@ -1,67 +1,51 @@
-export interface Hook {
-    /** Which actions this runs around. Three forms, all common in the market:
-     *
-     *    "edit_file"                 exactly that one
-     *    "write_file|edit_file"      any in the list
-     *    "*"                         every one
-     *
-     *  Anything else is treated as a regular expression anchored at both ends, so
-     *  `"git_.*"` covers the git actions without naming all five. A pattern that
-     *  will not compile matches nothing and says so once, rather than matching
-     *  everything: a broken pattern that ran a hook on every action would be the
-     *  dangerous way to be wrong. */
-    on: string;
-    /** "before" or "after". */
-    when: "before" | "after";
+/** 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;
-    /** Words a person reads in the timeline when it runs. */
-    what?: string;
+    what?: string | null;
+    timeout_s?: number;
+    source?: string;
 }
-/** What this project asks for, or nothing.
- *
- *  A malformed file is ignored with a warning rather than failing the job. A
- *  project whose hook configuration has a trailing comma should not be a project
- *  where the agent refuses to work, and the person who broke it is not usually
- *  the person now trying to get something done.
- */
-export declare function hooksFor(root: string): Hook[];
-/** Does this hook's matcher cover this action.
- *
- *  Exported because it is the part with the rules in it, and a rule with no
- *  test is a rule that drifts.
- */
-export declare function covers(pattern: string, action: string): boolean;
-export interface HookOutcome {
-    ran: number;
+/** 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 that come before one action.
- *
- * **A non-zero exit cancels the action.** This is the one place a hook changes
- * what happens, and it is deliberate: "do not let the agent touch anything under
- * generated/" is a real thing to want, and refusing is the only way for a
- * project to say it.
- *
- * It can only ever REFUSE. There is no exit code that approves something the
- * agent was not already allowed to do, because a permission system inside the
- * repository would live exactly where an attacker who got that far already is.
- */
-export declare function before(root: string, action: string, args: Record<string, unknown>, hooks?: Hook[]): Promise<HookOutcome>;
-/**
- * Run the hooks that come after one action.
+ * Run the hooks the service named, one after another, in its order.
  *
- * A failure here is reported and nothing else: the action has already happened,
- * and refusing it afterwards is not a thing that can be done. The overwhelming
- * case is a formatter, and a formatter that fails is worth knowing about and not
- * worth losing the work over.
+ * 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 after(root: string, action: string, args: Record<string, unknown>, hooks?: Hook[]): Promise<{
-    ran: number;
-    failed: string[];
-}>;
-/** The example a person copies. Kept in code so the readme and the behavior
- *  cannot drift: this is what the reader actually gets. */
-export declare const EXAMPLE: string;
+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/executor/hooks.js

@@ -33,215 +33,122 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXAMPLE = void 0;
-exports.hooksFor = hooksFor;
-exports.covers = covers;
-exports.before = before;
-exports.after = after;
+exports.IN_HOOK = exports.FILES = void 0;
+exports.insideHook = insideHook;
+exports.hookFiles = hookFiles;
+exports.runHooks = runHooks;
+exports.reportLines = reportLines;
 /**
- * Something of your own, run before or after the agent acts.
- *
- * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
- * item C18. What Claude Code calls hooks.
- *
- * ## Why this belongs on the client
- *
- * A hook is the customer's own command, running in their own project, on their
- * own machine. Nothing about it is ours to run: the command is theirs, the
- * environment is theirs, and the thing it usually wants to do is reformat a
- * file that only exists there.
- *
- * So the configuration is read from the project itself rather than from our
- * database. A hook that lives in the repository is reviewed like any other
- * change, travels with a branch, and is the same for everybody who works there.
- * A hook stored in our settings would be invisible in the repository and
- * different for whoever configured it.
- *
- * ## What they are for, in practice
- *
- * The overwhelming case is "run the formatter after the agent edits a file", and
- * the reason it earns a feature is that the alternative is telling the model to
- * remember to do it, which it does four times out of five.
- *
- * ## What a hook may not do
- *
- * **It cannot approve anything and it cannot change the decision.** A hook that
- * could turn a refusal into an approval would be a permission system in a file
- * inside the repository, which is the wrong place for one: the repository is
- * exactly what an attacker who has got that far already controls.
- *
- * A hook that fails is reported and does not stop the job, with one exception
- * stated in `before`: a `before` hook exiting non-zero cancels that one action,
- * because "do not let the agent touch generated files" is a real thing to want
- * and refusing is the only way to say it.
+ * 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");
-/** Where a project declares its hooks, in the order they are tried.
- *
- *  The settings file comes first, because that is where every other thing a
- *  project says about its agent now lives, and keeping hooks somewhere else was
- *  one more folder for a newcomer to know about.
- *
- *  `.illuminis/hooks.json` is still read, and last. It is what projects were
- *  told to write, and silently ignoring a file somebody wrote on our
- *  instructions would mean their formatter stops running with no message
- *  anywhere. Only one file is used: the first that has hooks in it wins, so a
- *  project that has moved does not get both. */
-const CONFIGS = [
+/** 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",
 ];
-/** What this project asks for, or nothing.
- *
- *  A malformed file is ignored with a warning rather than failing the job. A
- *  project whose hook configuration has a trailing comma should not be a project
- *  where the agent refuses to work, and the person who broke it is not usually
- *  the person now trying to get something done.
- */
-function hooksFor(root) {
-    for (const name of CONFIGS) {
+/** 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);
-        if (!fs.existsSync(file))
-            continue;
         try {
-            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-            const hooks = Array.isArray(parsed.hooks) ? parsed.hooks : [];
-            const usable = hooks.filter((h) => h && typeof h.command === "string" && h.command.trim()
-                && (h.when === "before" || h.when === "after")
-                && typeof h.on === "string" && h.on.trim());
-            // A settings file with no hooks section is the ordinary case, and it must
-            // not stop the older file being read. Only a file that actually declares
-            // hooks ends the search.
-            if (usable.length)
-                return usable;
+            if (fs.existsSync(file))
+                out[name] = fs.readFileSync(file, "utf8").slice(0, 200_000);
         }
-        catch (err) {
-            process.stderr.write(`  ${name} could not be read (${err.message}), so no hooks ran.\n`);
-            return [];
+        catch {
+            /* unreadable is the same as absent to the service */
         }
     }
-    return [];
+    return out;
 }
-/** Does this hook's matcher cover this action.
- *
- *  Exported because it is the part with the rules in it, and a rule with no
- *  test is a rule that drifts.
- */
-function covers(pattern, action) {
-    const p = String(pattern ?? "").trim();
-    if (!p || !action)
-        return false;
-    if (p === "*")
-        return true;
-    if (p === action)
-        return true;
-    if (p.includes("|") && !/[\\^$.?*+()[\]{}]/.test(p)) {
-        return p.split("|").some((one) => one.trim() === action);
-    }
-    if (!/[\\^$.?*+()[\]{}|]/.test(p))
-        return false;
-    try {
-        return new RegExp(`^(?:${p})$`).test(action);
-    }
-    catch {
-        // A pattern that will not compile matches NOTHING. The other direction,
-        // matching everything, would run somebody's script on every action because
-        // of a typo, which is the expensive way to be wrong.
-        process.stderr.write(`  A hook pattern is not valid and was skipped: ${p}\n`);
-        return false;
-    }
-}
-function matching(hooks, action, when) {
-    return hooks.filter((h) => h.when === when && covers(h.on, action));
+function fileOf(args) {
+    return String(args.path ?? args.file_path ?? args.to ?? "");
 }
-/** The path the action is about, for a hook that wants to know. */
-function targetOf(args) {
-    return String(args.path ?? args.to ?? "");
+function said(h) {
+    return h.what || h.command;
 }
 /**
- * Run the hooks that come before one action.
- *
- * **A non-zero exit cancels the action.** This is the one place a hook changes
- * what happens, and it is deliberate: "do not let the agent touch anything under
- * generated/" is a real thing to want, and refusing is the only way for a
- * project to say it.
+ * Run the hooks the service named, one after another, in its order.
  *
- * It can only ever REFUSE. There is no exit code that approves something the
- * agent was not already allowed to do, because a permission system inside the
- * repository would live exactly where an attacker who got that far already is.
+ * 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 before(root, action, args, hooks = hooksFor(root)) {
-    const applicable = matching(hooks, action, "before");
-    let ran = 0;
-    for (const hook of applicable) {
+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: 60_000,
-            // What the hook is about, as environment rather than as arguments, so an
-            // existing script needs no wrapper to read it.
-            extraEnv: { ILLUMINIS_ACTION: action, ILLUMINIS_PATH: targetOf(args) },
+            timeoutMs: secs * 1000,
+            input,
+            label: `hook: ${hook.command}`,
+            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),
+            },
         });
-        ran += 1;
-        if (result.isError || !/^exit 0/.test(result.content)) {
-            return {
-                ran,
-                refusedBy: hook.command,
-                detail: `${hook.what ?? "A check in this project"} refused this: ${result.content.slice(0, 500)}`,
-            };
+        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 { ran };
+    return outcome;
 }
-/**
- * Run the hooks that come after one action.
- *
- * A failure here is reported and nothing else: the action has already happened,
- * and refusing it afterwards is not a thing that can be done. The overwhelming
- * case is a formatter, and a formatter that fails is worth knowing about and not
- * worth losing the work over.
- */
-async function after(root, action, args, hooks = hooksFor(root)) {
-    const applicable = matching(hooks, action, "after");
-    const failed = [];
-    let ran = 0;
-    for (const hook of applicable) {
-        const result = await (0, shell_1.runCommand)(hook.command, {
-            root, timeoutMs: 120_000,
-            extraEnv: { ILLUMINIS_ACTION: action, ILLUMINIS_PATH: targetOf(args) },
-        });
-        ran += 1;
-        if (result.isError || !/^exit 0/.test(result.content)) {
-            failed.push(`${hook.what ?? hook.command}: ${result.content.slice(0, 300)}`);
-        }
+/** 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 { ran, failed };
+    return lines;
 }
-/** The example a person copies. Kept in code so the readme and the behavior
- *  cannot drift: this is what the reader actually gets. */
-exports.EXAMPLE = JSON.stringify({
-    hooks: [
-        {
-            on: "write_file|edit_file|multi_edit",
-            when: "after",
-            command: "npm run lint --silent",
-            what: "Lint after anything is written",
-        },
-        {
-            on: "edit_file",
-            when: "after",
-            command: "npx prettier --write $ILLUMINIS_PATH",
-            what: "Format the file that was just changed",
-        },
-        {
-            on: "write_file",
-            when: "before",
-            command: "test \"${ILLUMINIS_PATH#generated/}\" = \"$ILLUMINIS_PATH\"",
-            what: "Nothing under generated/ is edited by hand",
-        },
-    ],
-}, null, 2);

package/out/executor/index.d.ts

@@ -1,5 +1,7 @@
-import { RunResult, guessTestCommand, stopEverything } from "./shell";
-export { stopEverything, guessTestCommand };
+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
@@ -7,23 +9,37 @@ export type { RunResult };
 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?;
-    /** What this project asks to happen around the agent's actions, read once. */
-    private hooks?;
     /** 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);
-    execute(name: string, a: Record<string, unknown>): Promise<RunResult>;
+    /** 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;
 }