@cleocode/core 2026.10.8 → 2026.10.9-rc.ci.676

package/dist/hooks/project-runner.js

@@ -0,0 +1,328 @@
+/** Ordered project executor, separate from the best-effort internal registry (T13343). */
+import { spawn } from 'node:child_process';
+import { ProjectHookVerdictSchema, } from '@cleocode/contracts/project-hooks.js';
+import { discoveryEnv } from '../git/work-tree.js';
+import { atomicWrite } from '../store/atomic.js';
+import { computeHookActivation, inspectProjectHooks, matchesProjectHook, readProjectHookRecord, readProjectHooksLocalState, readProjectHooksManifest, resolveProjectHookContext, resolveProjectHookExecutable, resolveProjectHookFile, resolveProjectHookStateFile, } from './project-state.js';
+import { HOOKS_V1_UNRELEASED } from './release-gate.js';
+const MAX_INPUT_BYTES = 65536;
+const MAX_OUTPUT_BYTES = 65536;
+const MAX_INVOCATION_MS = 120000;
+function fault(invocation, code, id = 'cleo.project-hooks') {
+    return {
+        id,
+        status: 'infrastructure-error',
+        blocks: invocation.source === 'ci',
+        code,
+        exitCode: null,
+        signal: null,
+        durationMs: 0,
+    };
+}
+function sameInputs(left, right) {
+    return Boolean(left &&
+        right &&
+        left.projectIdentity === right.projectIdentity &&
+        left.manifestHash === right.manifestHash &&
+        JSON.stringify(left.files) === JSON.stringify(right.files) &&
+        JSON.stringify(left.executables) === JSON.stringify(right.executables));
+}
+function blocksFor(status, hook, invocation) {
+    if (invocation.source === 'agent')
+        return false;
+    if (invocation.source === 'ci')
+        return !['pass', 'skip'].includes(status);
+    return (status === 'block' ||
+        (['checker-error', 'timeout'].includes(status) && hook.checkerErrorPolicy === 'block'));
+}
+async function executeOne(hook, invocation, remainingMs, signal) {
+    const started = performance.now();
+    const outcome = {
+        id: hook.id,
+        status: 'checker-error',
+        blocks: false,
+        code: 'HOOK_CHECKER_ERROR',
+        exitCode: null,
+        signal: null,
+        durationMs: 0,
+    };
+    try {
+        const executable = await resolveProjectHookExecutable(invocation.projectRoot, hook.executable);
+        const handler = await resolveProjectHookFile(invocation.projectRoot, hook.handler);
+        const payload = JSON.stringify(invocation);
+        await new Promise((complete) => {
+            const child = spawn(executable, [handler, ...hook.args], {
+                cwd: invocation.projectRoot,
+                env: discoveryEnv(),
+                shell: false,
+                detached: process.platform !== 'win32',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let finished = false;
+            const stdout = [];
+            let bytes = 0;
+            let interrupted = false;
+            let cleanupTimer;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                if (cleanupTimer)
+                    clearTimeout(cleanupTimer);
+                signal?.removeEventListener('abort', onAbort);
+                child.stdin.destroy();
+                child.stdout.destroy();
+                child.stderr.destroy();
+                complete();
+            };
+            const killGroup = () => {
+                try {
+                    if (process.platform !== 'win32' && child.pid)
+                        process.kill(-child.pid, 'SIGKILL');
+                    else
+                        child.kill('SIGKILL');
+                }
+                catch {
+                    /* The child may already have exited. */
+                }
+            };
+            const terminate = () => {
+                interrupted = true;
+                killGroup();
+                outcome.signal = 'SIGKILL';
+                cleanupTimer = setTimeout(finish, 250);
+            };
+            const onAbort = () => {
+                outcome.status = 'infrastructure-error';
+                outcome.code = 'HOOK_ABORTED';
+                terminate();
+            };
+            const timer = setTimeout(() => {
+                outcome.status = remainingMs < hook.timeoutMs ? 'infrastructure-error' : 'timeout';
+                outcome.code = remainingMs < hook.timeoutMs ? 'HOOK_INVOCATION_TIMEOUT' : 'HOOK_TIMEOUT';
+                terminate();
+            }, Math.min(hook.timeoutMs, remainingMs));
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+            child.stdout.on('data', (chunk) => {
+                if (interrupted)
+                    return;
+                bytes += chunk.length;
+                if (bytes > MAX_OUTPUT_BYTES) {
+                    outcome.code = 'HOOK_OUTPUT_TOO_LARGE';
+                    terminate();
+                    return;
+                }
+                stdout.push(chunk);
+            });
+            // Never persist child stderr: it may contain secrets or arbitrary payloads.
+            child.stderr.on('data', (chunk) => {
+                bytes += chunk.length;
+                if (!interrupted && bytes > MAX_OUTPUT_BYTES) {
+                    outcome.code = 'HOOK_OUTPUT_TOO_LARGE';
+                    terminate();
+                }
+            });
+            child.on('error', () => {
+                outcome.status = 'infrastructure-error';
+                outcome.code = 'HOOK_EXECUTION_FAILED';
+                finish();
+            });
+            child.stdin.on('error', () => {
+                /* close/error determines the verdict. */
+            });
+            child.on('exit', () => {
+                // Stop descendants that remain in the checker process group after its verdict.
+                killGroup();
+            });
+            child.on('close', (exitCode, signal) => {
+                if (finished)
+                    return;
+                outcome.exitCode = exitCode;
+                outcome.signal = signal;
+                if (!interrupted) {
+                    if (signal)
+                        outcome.code = 'HOOK_SIGNAL';
+                    else if (exitCode !== 0)
+                        outcome.code = 'HOOK_NONZERO_EXIT';
+                    else {
+                        try {
+                            const verdict = ProjectHookVerdictSchema.parse(JSON.parse(Buffer.concat(stdout).toString('utf8')));
+                            outcome.status = verdict.status;
+                            if (verdict.message)
+                                outcome.message = verdict.message;
+                            outcome.code = `HOOK_${verdict.status.toUpperCase().replace('-', '_')}`;
+                        }
+                        catch {
+                            outcome.code = 'HOOK_INVALID_VERDICT';
+                        }
+                    }
+                }
+                finish();
+            });
+            child.stdin.end(payload);
+        });
+    }
+    catch {
+        outcome.status = 'infrastructure-error';
+        outcome.code = 'HOOK_EXECUTION_UNAVAILABLE';
+    }
+    outcome.durationMs = Math.round(performance.now() - started);
+    outcome.blocks = blocksFor(outcome.status, hook, invocation);
+    return outcome;
+}
+/** Execute activated definitions in source order; internal faults always allow locally. */
+export async function executeProjectHooks(invocation, id, activationRoot, signal) {
+    const deadline = performance.now() + MAX_INVOCATION_MS;
+    try {
+        if (Buffer.byteLength(JSON.stringify(invocation)) > MAX_INPUT_BYTES)
+            return [fault(invocation, 'HOOK_INPUT_TOO_LARGE')];
+        const inspection = await inspectProjectHooks(activationRoot ?? invocation.projectRoot, deadline, signal);
+        const checkout = resolveProjectHookContext(invocation.projectRoot);
+        if (checkout.gitCommonDir !== invocation.gitCommonDir ||
+            checkout.projectRoot !== invocation.projectRoot ||
+            checkout.gitCommonDir !== inspection.context.gitCommonDir) {
+            return [fault(invocation, 'HOOK_CHECKOUT_MISMATCH')];
+        }
+        if (activationRoot &&
+            checkout.projectRoot !== inspection.context.projectRoot &&
+            inspection.activation === 'active') {
+            const target = await computeHookActivation(checkout, await readProjectHooksManifest(checkout), deadline, signal);
+            const state = await readProjectHooksLocalState(inspection.context);
+            const approved = state.activation;
+            // Inherit approval only for the same project and identical executable inputs.
+            // A changed worktree definition or dependency always requires reactivation.
+            if (!approved ||
+                target.projectIdentity !== approved.projectIdentity ||
+                target.manifestHash !== approved.manifestHash ||
+                JSON.stringify(target.files) !== JSON.stringify(approved.files) ||
+                JSON.stringify(target.executables) !== JSON.stringify(approved.executables)) {
+                return [
+                    {
+                        id: id ?? 'cleo.project-hooks',
+                        status: 'warn',
+                        blocks: invocation.source === 'ci',
+                        code: 'HOOK_REACTIVATION_REQUIRED',
+                        exitCode: null,
+                        signal: null,
+                        durationMs: 0,
+                    },
+                ];
+            }
+        }
+        if (inspection.activation === 'unreleased') {
+            // T13557: inert on a build without hooks-v1; a required CI check still fails.
+            if (invocation.source === 'ci')
+                return [fault(invocation, HOOKS_V1_UNRELEASED)];
+            return [
+                {
+                    id: id ?? 'cleo.project-hooks',
+                    status: 'skip',
+                    blocks: false,
+                    code: HOOKS_V1_UNRELEASED,
+                    exitCode: null,
+                    signal: null,
+                    durationMs: 0,
+                },
+            ];
+        }
+        if (inspection.activation !== 'active') {
+            if (invocation.source === 'ci')
+                return [fault(invocation, 'HOOK_REQUIRED_ACTIVATION_MISSING')];
+            return [
+                {
+                    id: id ?? 'cleo.project-hooks',
+                    status: inspection.activation === 'disabled' ? 'skip' : 'warn',
+                    blocks: false,
+                    code: inspection.activation === 'disabled' ? 'HOOK_DISABLED' : 'HOOK_REACTIVATION_REQUIRED',
+                    exitCode: null,
+                    signal: null,
+                    durationMs: 0,
+                },
+            ];
+        }
+        const definitions = inspection.manifest.hooks.filter((hook) => id ? hook.id === id : matchesProjectHook(hook, invocation.source, invocation.event));
+        if (id && definitions.length === 0)
+            return [fault(invocation, 'HOOK_NOT_FOUND', id)];
+        const outcomes = [];
+        const approved = (await readProjectHooksLocalState(inspection.context)).activation;
+        for (const hook of definitions) {
+            // Recheck between handlers: an earlier checker may have changed later code.
+            const fresh = await readProjectHooksLocalState(inspection.context);
+            const target = await computeHookActivation(checkout, await readProjectHooksManifest(checkout), deadline, signal);
+            if (!fresh.hooks.project.enabled ||
+                !sameInputs(fresh.activation, approved) ||
+                !sameInputs(target, approved)) {
+                outcomes.push({
+                    id: hook.id,
+                    status: 'warn',
+                    blocks: invocation.source === 'ci',
+                    code: 'HOOK_REACTIVATION_REQUIRED',
+                    exitCode: null,
+                    signal: null,
+                    durationMs: 0,
+                });
+                break;
+            }
+            const remainingMs = Math.floor(deadline - performance.now());
+            if (remainingMs <= 0) {
+                outcomes.push({
+                    id: hook.id,
+                    status: 'infrastructure-error',
+                    blocks: invocation.source === 'ci',
+                    code: 'HOOK_INVOCATION_TIMEOUT',
+                    exitCode: null,
+                    signal: null,
+                    durationMs: MAX_INVOCATION_MS,
+                });
+                break;
+            }
+            if (signal?.aborted) {
+                outcomes.push(fault(invocation, 'HOOK_ABORTED', hook.id));
+                break;
+            }
+            outcomes.push(await executeOne(hook, invocation, remainingMs, signal));
+        }
+        // A last-result record is bounded and contains only executor-owned metadata.
+        // A failed receipt write is visible as infrastructure fault, never a fake pass.
+        try {
+            const receipt = {
+                schemaVersion: 1,
+                manifestHash: approved?.manifestHash ?? '',
+                source: invocation.source,
+                event: invocation.event.slice(0, 128),
+                recordedAt: new Date().toISOString(),
+                outcomes: outcomes.map(({ message: _message, ...safe }) => safe),
+            };
+            await atomicWrite(await resolveProjectHookStateFile(inspection.context, 'last-execution.json'), `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        }
+        catch {
+            outcomes.push(fault(invocation, 'HOOK_RECEIPT_WRITE_FAILED'));
+        }
+        return outcomes;
+    }
+    catch {
+        return [fault(invocation, 'HOOK_INFRASTRUCTURE_ERROR')];
+    }
+}
+/** Contracts port for worktree and other consumers; no internal registry coupling. */
+export const projectHookExecutor = { execute: executeProjectHooks };
+/** Bind worktree inheritance to an explicitly activated source checkout. */
+export function createProjectHookExecutor(activationRoot) {
+    return { execute: (invocation) => executeProjectHooks(invocation, undefined, activationRoot) };
+}
+/** Read only a bounded last execution record and validate its safe shape. */
+export async function readLastProjectHookExecution(cwd) {
+    const inspection = await inspectProjectHooks(cwd);
+    const file = await resolveProjectHookStateFile(inspection.context, 'last-execution.json');
+    try {
+        const { HookExecutionReceiptSchema } = await import('@cleocode/contracts/project-hooks.js');
+        return HookExecutionReceiptSchema.parse(JSON.parse(await readProjectHookRecord(file, MAX_OUTPUT_BYTES)));
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=project-runner.js.map

package/dist/hooks/project-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-runner.js","sourceRoot":"","sources":["../../src/hooks/project-runner.ts"],"names":[],"mappings":"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"}

package/dist/hooks/project-state.d.ts

@@ -0,0 +1,41 @@
+import type { ProjectHookDeliveryServices } from '@cleocode/contracts/project-hook-delivery.js';
+import { type HookActivation, type ProjectHookContext, type ProjectHookDefinition, type ProjectHookInspection, type ProjectHooksLocalState, type ProjectHooksManifest } from '@cleocode/contracts/project-hooks.js';
+export { HooksV1UnreleasedError } from './release-gate.js';
+/** Read a hook definition or private record with a hard allocation bound, including racing growth. */
+export declare function readProjectHookRecord(path: string, maxBytes: number): Promise<string>;
+/**
+ * Supply canonical cold-path utilities through the provider delivery contracts port.
+ * @remarks
+ * This keeps provider delivery independent of the SDK at runtime while reusing its bounded reader.
+ * Git receives a snapshot without ambient repository overrides; the process environment is unchanged.
+ * @returns The bounded reader and sanitized Git discovery environment for one delivery invocation.
+ * @example
+ * ```typescript
+ * const services = createProjectHookDeliveryServices();
+ * const canReadConfiguration = typeof services.readTextFile === 'function';
+ * ```
+ */
+export declare function createProjectHookDeliveryServices(): ProjectHookDeliveryServices;
+/** Resolve checkout and hook paths through Git without reading CLEO stores. */
+export declare function resolveProjectHookContext(cwd: string): ProjectHookContext;
+/** Resolve a real path inside this checkout, refusing symlink escapes. */
+export declare function resolveProjectHookFile(root: string, file: string): Promise<string>;
+/** Read a bounded tracked definition and reject malformed or duplicate entries. */
+export declare function readProjectHooksManifest(context: ProjectHookContext): Promise<ProjectHooksManifest>;
+/** Resolve a shell-free executable; project executable paths must remain inside checkout. */
+export declare function resolveProjectHookExecutable(root: string, executable: string): Promise<string>;
+/** Compute the executable inputs bound by explicit activation. */
+export declare function computeHookActivation(context: ProjectHookContext, manifest: ProjectHooksManifest, deadline?: number, signal?: AbortSignal): Promise<HookActivation>;
+/** Resolve a private receipt path and reject redirected state directories or files. */
+export declare function resolveProjectHookStateFile(context: ProjectHookContext, name: string): Promise<string>;
+/** Read machine-local feature state; no record means disabled. */
+export declare function readProjectHooksLocalState(context: ProjectHookContext): Promise<ProjectHooksLocalState>;
+/** Check that the explicit local approval still matches all declared code inputs. */
+export declare function inspectProjectHooks(cwd: string, deadline?: number, signal?: AbortSignal): Promise<ProjectHookInspection>;
+/** Explicitly activate the present definitions; does not install or grant harness trust. */
+export declare function activateProjectHooks(cwd: string): Promise<ProjectHooksLocalState>;
+/** Disable machine-local execution without modifying project or native harness configuration. */
+export declare function disableProjectHooks(cwd: string): Promise<void>;
+/** Match a project's binding without treating shell command text as a Git operation. */
+export declare function matchesProjectHook(hook: ProjectHookDefinition, source: string, event: string): boolean;
+//# sourceMappingURL=project-state.d.ts.map

package/dist/hooks/project-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-state.d.ts","sourceRoot":"","sources":["../../src/hooks/project-state.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAChG,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE1B,KAAK,sBAAsB,EAE3B,KAAK,oBAAoB,EAE1B,MAAM,sCAAsC,CAAC;AAM9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,sGAAsG;AACtG,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,IAAI,2BAA2B,CAE/E;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAmBzE;AAED,0EAA0E;AAC1E,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQxF;AAED,mFAAmF;AACnF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAW/B;AAED,6FAA6F;AAC7F,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AA0CD,kEAAkE;AAClE,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,SAA6B,EACrC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAgDzB;AAED,uFAAuF;AACvF,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,kEAAkE;AAClE,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CAWjC;AA4CD,qFAAqF;AACrF,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAiChC;AAED,4FAA4F;AAC5F,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0BvF;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpE;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,qBAAqB,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAET"}