devcontour-harness 0.0.0-stage → 0.1.0-alpha.5

package/lib/environment/lifecycle.d.ts

@@ -0,0 +1,40 @@
+import type { z } from 'zod';
+import { environmentSchema, lifecycleSchema, stepSchema, type ExecutionPolicy } from '../contracts/index.ts';
+export { redactor } from './redaction.ts';
+type Environment = z.infer<typeof environmentSchema>;
+type Lifecycle = z.infer<typeof lifecycleSchema>;
+type Step = z.infer<typeof stepSchema>;
+/** Отказ обязательной очистки окружения: приёмка с ним не происходит. */
+export declare class CleanupFailure extends Error {
+    name: string;
+}
+/** Жив ли процесс (сигнал 0 не доставляется, только проверяется). */
+export declare function processAlive(pid: number): boolean;
+export declare function executionEnvironment(profiles: (Environment | undefined)[], devcontour?: NodeJS.ProcessEnv, source?: NodeJS.ProcessEnv): {
+    env: NodeJS.ProcessEnv;
+    redact: import("./redaction.ts").Redactor;
+};
+/**
+ * Маска по тем секретам и наследуемым значениям, что заданы, — даже когда
+ * окружение целиком собрать нельзя. Незаданный секрет — причина отказа, но не
+ * повод снимать маску с остальных: известный секрет иначе сохранялся бы в
+ * команде и итоге проверки.
+ */
+export declare function availableRedactor(profiles: (Environment | undefined)[], source?: NodeJS.ProcessEnv): import("./redaction.ts").Redactor;
+export declare function runSteps(steps: Step[], cwd: string, dir: string, execution: ReturnType<typeof executionEnvironment>, signal: AbortSignal): Promise<void>;
+export declare function withEnvironment<T>(lifecycle: Lifecycle | undefined, cwd: string, dir: string, execution: ReturnType<typeof executionEnvironment>, signal: AbortSignal, action: () => Promise<T>, measure?: <R>(stage: string, action: () => Promise<R>) => Promise<R>): Promise<T>;
+/**
+ * Завершить очистку окружения, прерванную падением процесса: по сохранённому
+ * receipt, только внутри разрешённых корней, только при той же политике
+ * очистки и только когда процесс-владелец уже не существует (или это он сам,
+ * `options.owner`, после окончания попытки).
+ */
+export declare function cleanupEnvironment(receiptPath: string, policy: ExecutionPolicy, allowedRoots: string[], 
+/** `owner` — процесс, который вправе повторить очистку своего окружения сам. */
+options?: {
+    owner?: number;
+}): Promise<{
+    status: "already-cleaned";
+} | {
+    status: "cleaned";
+}>;

package/lib/environment/lifecycle.js

@@ -0,0 +1,191 @@
+import { mkdir, writeFile, readFile, realpath } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { digestOf, } from "../contracts/index.js";
+import { command } from "./process.js";
+import { redactor } from "./redaction.js";
+export { redactor } from "./redaction.js";
+/** Отказ обязательной очистки окружения: приёмка с ним не происходит. */
+export class CleanupFailure extends Error {
+    name = 'CleanupFailure';
+}
+/** Жив ли процесс (сигнал 0 не доставляется, только проверяется). */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function executionEnvironment(profiles, devcontour = {}, source = process.env) {
+    // Окружение прогона — минимальное: исполнитель не должен наследовать всё,
+    // что оказалось у оператора. Но учётные данные runtime живут в системном
+    // хранилище, а найти их там нельзя, не зная имени учётной записи: без USER
+    // claude на macOS отвечает «Not logged in», и единственным выходом остаётся
+    // передать API-ключ — то есть платить за то, что уже оплачено подпиской.
+    // USER и LOGNAME — не секреты, а адрес в хранилище.
+    const env = {
+        PATH: source.PATH,
+        HOME: source.HOME,
+        TMPDIR: source.TMPDIR,
+        USER: source.USER,
+        LOGNAME: source.LOGNAME ?? source.USER,
+        CI: '1',
+    };
+    const secretValues = [];
+    for (const profile of profiles) {
+        if (!profile)
+            continue;
+        for (const key of profile.inherit) {
+            if (source[key] === undefined)
+                throw new Error(`Не задана переменная окружения: ${key}`);
+            env[key] = source[key];
+            // Inherited values are also redacted: callers need not classify every provider token.
+            if (source[key])
+                secretValues.push(source[key]);
+        }
+        Object.assign(env, profile.values);
+        for (const [key, from] of Object.entries(profile.secrets)) {
+            if (!source[from])
+                throw new Error(`Не задан секрет окружения: ${from} (для ${key})`);
+            env[key] = source[from];
+            secretValues.push(source[from]);
+        }
+    }
+    // Переменные контура: исторические DEVCONTOUR_* — часть договора проверок
+    // пользователей — и их псевдонимы HARNESS_* с теми же значениями.
+    for (const [key, value] of Object.entries(devcontour)) {
+        env[key] = value;
+        if (key.startsWith('DEVCONTOUR_'))
+            env['HARNESS_' + key.slice('DEVCONTOUR_'.length)] = value;
+    }
+    return { env, redact: redactor(secretValues) };
+}
+/**
+ * Маска по тем секретам и наследуемым значениям, что заданы, — даже когда
+ * окружение целиком собрать нельзя. Незаданный секрет — причина отказа, но не
+ * повод снимать маску с остальных: известный секрет иначе сохранялся бы в
+ * команде и итоге проверки.
+ */
+export function availableRedactor(profiles, source = process.env) {
+    const values = [];
+    for (const profile of profiles) {
+        if (!profile)
+            continue;
+        for (const key of profile.inherit)
+            if (source[key])
+                values.push(source[key]);
+        for (const from of Object.values(profile.secrets))
+            if (source[from])
+                values.push(source[from]);
+    }
+    return redactor(values);
+}
+export async function runSteps(steps, cwd, dir, execution, signal) {
+    await mkdir(dir, { recursive: true });
+    for (const step of steps) {
+        signal.throwIfAborted();
+        const result = await command(step.command, cwd, {
+            signal,
+            timeoutMs: step.timeoutMs,
+            env: execution.env,
+            redact: execution.redact,
+        });
+        await writeFile(join(dir, step.id + '.log'), result.stdout + '\n' + result.stderr);
+        if (result.code || result.timedOut || signal.aborted)
+            throw new Error(`Шаг ${step.id}: exit=${result.code}; timeout=${result.timedOut}`);
+    }
+}
+// Teardown uses a fresh deadline: cancellation must not cancel cleanup itself.
+// The receipt is retained after crashes and can be explicitly resumed with environment-cleanup.
+export async function withEnvironment(lifecycle, cwd, dir, execution, signal, action, measure = (_stage, action) => action()) {
+    if (!lifecycle)
+        return action();
+    await mkdir(dir, { recursive: true });
+    const receiptPath = join(dir, 'environment.json');
+    const receipt = {
+        version: 1,
+        ownerPid: process.pid,
+        devcontourEnv: Object.fromEntries(Object.entries(execution.env).filter(([key]) => key.startsWith('DEVCONTOUR_'))),
+        cwd,
+        lifecycle,
+        policyDigest: digestOf(lifecycle),
+        status: 'active',
+        startedAt: new Date().toISOString(),
+        runId: execution.env.DEVCONTOUR_RUN_ID,
+    };
+    await writeFile(receiptPath, JSON.stringify(receipt, null, 2));
+    let result, failure;
+    try {
+        await measure('setup', () => runSteps(lifecycle.setup, cwd, join(dir, 'setup'), execution, signal));
+        await measure('ready', () => runSteps(lifecycle.ready, cwd, join(dir, 'ready'), execution, signal));
+        result = await action();
+    }
+    catch (error) {
+        // A thrown undefined/false must still fail the attempt after cleanup.
+        failure =
+            error instanceof Error
+                ? error
+                : new Error('Операция окружения завершилась ошибкой', { cause: error });
+    }
+    try {
+        await measure('cleanup', () => teardown(lifecycle, cwd, dir, execution));
+        receipt.status = 'cleaned';
+    }
+    catch (error) {
+        receipt.status = 'cleanup-failed';
+        failure = new CleanupFailure(`${failure instanceof Error ? failure.message + '; ' : ''}Очистка окружения не завершена: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    await writeFile(receiptPath, JSON.stringify(receipt, null, 2));
+    if (failure)
+        throw failure;
+    return result;
+}
+async function teardown(lifecycle, cwd, dir, execution) {
+    const failures = [];
+    for (const step of lifecycle.teardown) {
+        try {
+            await runSteps([step], cwd, join(dir, 'teardown'), execution, AbortSignal.timeout(step.timeoutMs + 2000));
+        }
+        catch (e) {
+            failures.push(e instanceof Error ? e.message : String(e));
+        }
+    }
+    if (failures.length)
+        throw new Error(failures.join('; '));
+}
+/**
+ * Завершить очистку окружения, прерванную падением процесса: по сохранённому
+ * receipt, только внутри разрешённых корней, только при той же политике
+ * очистки и только когда процесс-владелец уже не существует (или это он сам,
+ * `options.owner`, после окончания попытки).
+ */
+export async function cleanupEnvironment(receiptPath, policy, allowedRoots, 
+/** `owner` — процесс, который вправе повторить очистку своего окружения сам. */
+options = {}) {
+    const receipt = JSON.parse(await readFile(receiptPath, 'utf8'));
+    const cwd = await realpath(receipt.cwd);
+    if (!allowedRoots.some((root) => cwd.startsWith(root + sep)))
+        throw new Error('Окружение находится вне рабочих каталогов');
+    const repositoryId = receipt.devcontourEnv?.DEVCONTOUR_REPOSITORY_ID;
+    const repo = policy.repositories.find((r) => r.id === repositoryId);
+    if (repositoryId && !repo)
+        throw new Error('Неизвестный репозиторий сохранённого окружения');
+    const lifecycle = [repo?.lifecycle, policy.lifecycle]
+        .filter(Boolean)
+        .find((l) => digestOf(l) === receipt.policyDigest);
+    if (!lifecycle)
+        throw new Error('Политика очистки изменилась; сверьте сохранённое окружение вручную');
+    if (receipt.status === 'cleaned')
+        return { status: 'already-cleaned' };
+    if (receipt.ownerPid && receipt.ownerPid !== options.owner && processAlive(receipt.ownerPid))
+        throw new Error('Процесс владельца окружения ещё существует; сначала остановите его');
+    const execution = executionEnvironment([policy.environment, repo?.environment], {
+        ...receipt.devcontourEnv,
+        ...(receipt.runId ? { DEVCONTOUR_RUN_ID: receipt.runId } : {}),
+    });
+    await teardown(lifecycle, cwd, join(receiptPath, '..'), execution);
+    await writeFile(receiptPath, JSON.stringify({ ...receipt, status: 'cleaned' }, null, 2));
+    return { status: 'cleaned' };
+}

package/lib/environment/live-calls.d.ts

@@ -0,0 +1,14 @@
+import { type CallOwner } from '../engine/usage.ts';
+/** Момент старта процесса по данным ОС, мс; `undefined` — узнать нельзя. */
+export declare function processStartedAt(pid: number): number | undefined;
+/**
+ * Этот процесс: по нему восстановление и бюджет отличают свои идущие вызовы.
+ * Момент старта отличает процесс от другого, получившего тот же pid.
+ */
+export declare const CURRENT_PROCESS: CallOwner;
+/**
+ * Идентификатор текущей загрузки ОС: Linux сообщает его прямо, macOS — момент
+ * загрузки. `undefined` — узнать нельзя, и монотонные часы ОС между
+ * процессами не сравниваются.
+ */
+export declare const BOOT_ID: string | undefined;

package/lib/environment/live-calls.js

@@ -0,0 +1,72 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { registerMonotonic, registerProcess } from "../engine/usage.js";
+import { processAlive } from "./lifecycle.js";
+/** Момент старта процесса по данным ОС, мс; `undefined` — узнать нельзя. */
+export function processStartedAt(pid) {
+    try {
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+            encoding: 'utf8',
+            env: { ...process.env, LC_ALL: 'C' },
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        const at = Date.parse(out);
+        return Number.isFinite(at) ? at : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Этот процесс: по нему восстановление и бюджет отличают свои идущие вызовы.
+ * Момент старта отличает процесс от другого, получившего тот же pid.
+ */
+export const CURRENT_PROCESS = {
+    id: randomUUID(),
+    pid: process.pid,
+    ...((at) => (at === undefined ? {} : { startedAt: at }))(processStartedAt(process.pid)),
+};
+/** Тот же ли это процесс: pid существует и момент старта совпадает. */
+const sameProcess = (owner) => {
+    if (owner.startedAt === undefined || !processAlive(owner.pid))
+        return false;
+    // Оба момента — из одного источника (ОС) с одним округлением: у того же
+    // процесса они равны, любое расхождение — другой процесс.
+    return processStartedAt(owner.pid) === owner.startedAt;
+};
+/** Процесса нет или pid достался другому процессу; неизвестное — не «ушёл». */
+const gone = (owner) => {
+    if (!processAlive(owner.pid))
+        return true;
+    if (owner.startedAt === undefined)
+        return false;
+    const started = processStartedAt(owner.pid);
+    return started !== undefined && started !== owner.startedAt;
+};
+/**
+ * Идентификатор текущей загрузки ОС: Linux сообщает его прямо, macOS — момент
+ * загрузки. `undefined` — узнать нельзя, и монотонные часы ОС между
+ * процессами не сравниваются.
+ */
+export const BOOT_ID = (() => {
+    try {
+        return readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    }
+    catch {
+        try {
+            const out = execFileSync('sysctl', ['-n', 'kern.boottime'], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 2000,
+            });
+            return /sec = \d+, usec = \d+/.exec(out)?.[0];
+        }
+        catch {
+            return undefined;
+        }
+    }
+})();
+registerProcess(CURRENT_PROCESS, sameProcess, gone);
+registerMonotonic(() => process.hrtime.bigint(), BOOT_ID);

package/lib/environment/process.d.ts

@@ -0,0 +1,32 @@
+import { type Redactor } from './redaction.ts';
+import type { RuntimeDiagnostics } from '../contracts/index.ts';
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    diagnostics: RuntimeDiagnostics;
+}
+export declare function command(argv: string[], cwd: string, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+    redact?: Redactor;
+    onOutput?: (stream: 'stdout' | 'stderr', text: string) => void;
+    /**
+     * Владеть всеми потомками, включая сменивших группу или сессию: после
+     * завершения они останавливаются, и результат не возвращается, пока
+     * хотя бы один жив. Сигнал группе не достаёт отсоединившегося потомка.
+     *
+     * Потомок узнаётся по любому из трёх признаков: метка окружения (её
+     * наследуют все, кто не очистил окружение), замеченное опросом родство с
+     * командой и текущий каталог внутри `dirs` — каталогов, которые принадлежат
+     * только этой команде (worktree, scratch). Ни один признак сам по себе не
+     * полон: окружение можно очистить, опрос можно опередить, каталог сменить.
+     */
+    contain?: boolean | {
+        dirs: string[];
+    };
+}): Promise<CommandResult>;
+export declare function git(cwd: string, ...args: string[]): Promise<string>;