devcontour-harness 0.1.0-alpha.5 → 0.1.0-alpha.7

package/lib/integrations/connector/redact.d.ts

@@ -0,0 +1,19 @@
+import { redactor, type Redactor } from '../../environment/redaction.ts';
+import { type RelayTransport } from './transport.ts';
+/**
+ * Маскирование известных секретов в диагностике коннектора.
+ *
+ * Ошибка транспорта (HTTP body, stderr CLI) может дословно содержать значение
+ * секрета. Обёртка маскирует сообщение каждой ошибки транспорта до того, как
+ * она попадёт в отчёт `source-check`, `source-status`, сохранённые причины
+ * шагов/операций, `lastError` доставки или вывод CLI. Данные успешных ответов
+ * не меняются: это содержимое задач, которое закрепляется по digest.
+ */
+/** Значения секретов: `secrets`-карты политики (на любом уровне) из окружения controller. */
+export declare function policySecrets(policy: unknown, env?: NodeJS.ProcessEnv): string[];
+/** Значения настроек provider, по имени похожие на секрет (например, `relay.env.RELAY_TOKEN`). */
+export declare function settingsSecrets(settings: unknown): string[];
+export declare function maskError(error: unknown, redact: Redactor): unknown;
+/** Транспорт, ошибки которого замаскированы `redact`. Повторная обёртка не создаётся. */
+export declare function redactingTransport(inner: RelayTransport, redact: Redactor): RelayTransport;
+export { redactor };

package/lib/integrations/connector/redact.js

@@ -0,0 +1,91 @@
+import { HarnessError } from "../../contracts/index.js";
+import { redactor } from "../../environment/redaction.js";
+import { TransportError } from "./transport.js";
+/**
+ * Маскирование известных секретов в диагностике коннектора.
+ *
+ * Ошибка транспорта (HTTP body, stderr CLI) может дословно содержать значение
+ * секрета. Обёртка маскирует сообщение каждой ошибки транспорта до того, как
+ * она попадёт в отчёт `source-check`, `source-status`, сохранённые причины
+ * шагов/операций, `lastError` доставки или вывод CLI. Данные успешных ответов
+ * не меняются: это содержимое задач, которое закрепляется по digest.
+ */
+/** Значения секретов: `secrets`-карты политики (на любом уровне) из окружения controller. */
+export function policySecrets(policy, env = process.env) {
+    const out = new Set();
+    const walk = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value))
+            return value.forEach(walk);
+        for (const [key, v] of Object.entries(value)) {
+            if (key === 'secrets' && v && typeof v === 'object' && !Array.isArray(v))
+                for (const name of Object.values(v))
+                    if (typeof name === 'string' && env[name])
+                        out.add(env[name]);
+            walk(v);
+        }
+    };
+    walk(policy);
+    return [...out];
+}
+const SECRET_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|CREDENTIAL|AUTH)/i;
+/** Значения настроек provider, по имени похожие на секрет (например, `relay.env.RELAY_TOKEN`). */
+export function settingsSecrets(settings) {
+    const out = [];
+    const walk = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [key, v] of Object.entries(value)) {
+            if (typeof v === 'string' && SECRET_NAME.test(key) && v.length >= 4)
+                out.push(v);
+            else
+                walk(v);
+        }
+    };
+    walk(settings);
+    return out;
+}
+export function maskError(error, redact) {
+    if (error instanceof TransportError)
+        return new TransportError(error.kind, error.operation, redact(error.message), error.details);
+    if (error instanceof HarnessError)
+        return new HarnessError(error.code, redact(error.message), error.issues.map((i) => ({ path: i.path, message: redact(i.message) })));
+    if (error instanceof Error) {
+        const safe = new Error(redact(error.message));
+        safe.name = error.name;
+        return safe;
+    }
+    return typeof error === 'string' ? redact(error) : error;
+}
+const marked = Symbol('redacting-transport');
+/** Транспорт, ошибки которого замаскированы `redact`. Повторная обёртка не создаётся. */
+export function redactingTransport(inner, redact) {
+    if (inner[marked] || !redact.secrets?.length)
+        return inner;
+    const wrapped = new Proxy(inner, {
+        get(target, prop, receiver) {
+            if (prop === marked)
+                return true;
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function')
+                return value;
+            return (...args) => {
+                let out;
+                try {
+                    out = value.apply(target, args);
+                }
+                catch (error) {
+                    throw maskError(error, redact);
+                }
+                return out instanceof Promise
+                    ? out.catch((error) => {
+                        throw maskError(error, redact);
+                    })
+                    : out;
+            };
+        },
+    });
+    return wrapped;
+}
+export { redactor };

package/lib/integrations/connector/registry.d.ts

@@ -0,0 +1,15 @@
+import { type LoadedConfig } from './config.ts';
+import type { RelayTransport } from './transport.ts';
+/**
+ * Реестр транспортов по явному provider. Модуль адаптера загружается только
+ * для выбранного provider (opt-in): core и файловый сценарий не загружают
+ * Relay-адаптеры и не требуют их окружения.
+ *
+ * Договор адаптера: модуль `src/integrations/<adapter>/index.ts` экспортирует
+ * `createTransport(settings, options?)`, где `settings` — объект `relay` из
+ * конфигурации коннектора, дополненный `projectId` и `actor` верхнего уровня
+ * (и для relay-v2-cli — абсолютными путями `binary`/`config`, разрешёнными от
+ * каталога файла конфигурации). Неверные настройки — `INVALID_INPUT`.
+ */
+export declare function settingsFor(loaded: LoadedConfig): Record<string, unknown>;
+export declare function createTransportFor(loaded: LoadedConfig): Promise<RelayTransport>;

package/lib/integrations/connector/registry.js

@@ -0,0 +1,43 @@
+import { HarnessError } from "../../contracts/index.js";
+import { resolveFrom } from "./config.js";
+/**
+ * Реестр транспортов по явному provider. Модуль адаптера загружается только
+ * для выбранного provider (opt-in): core и файловый сценарий не загружают
+ * Relay-адаптеры и не требуют их окружения.
+ *
+ * Договор адаптера: модуль `src/integrations/<adapter>/index.ts` экспортирует
+ * `createTransport(settings, options?)`, где `settings` — объект `relay` из
+ * конфигурации коннектора, дополненный `projectId` и `actor` верхнего уровня
+ * (и для relay-v2-cli — абсолютными путями `binary`/`config`, разрешёнными от
+ * каталога файла конфигурации). Неверные настройки — `INVALID_INPUT`.
+ */
+export function settingsFor(loaded) {
+    const { config, baseDir } = loaded;
+    const relay = { ...config.relay };
+    for (const key of ['projectId', 'actor'])
+        if (key in relay && relay[key] !== config[key])
+            throw new HarnessError('INVALID_INPUT', `source.relay.${key} не совпадает с ${key} конфигурации коннектора`);
+    const settings = {
+        ...relay,
+        projectId: config.projectId,
+        actor: config.actor,
+    };
+    if (config.provider === 'relay-v2-cli') {
+        settings.binary = resolveFrom(baseDir, config.relay.binary);
+        settings.config = resolveFrom(baseDir, config.relay.config);
+    }
+    return settings;
+}
+export async function createTransportFor(loaded) {
+    const settings = settingsFor(loaded);
+    switch (loaded.config.provider) {
+        case 'relay-v1-http': {
+            const adapter = await import("../relay-v1/index.js");
+            return adapter.createTransport(settings);
+        }
+        case 'relay-v2-cli': {
+            const adapter = await import("../relay-v2/index.js");
+            return adapter.createTransport(settings);
+        }
+    }
+}

package/lib/integrations/connector/snapshot.d.ts

@@ -0,0 +1,131 @@
+import { HarnessError, type ContextSnapshot, type WorkGraph } from '../../contracts/index.ts';
+import { type ConnectorConfig, type TaskMapping } from './config.ts';
+import type { ReceiptRecord } from './store.ts';
+import { type CriterionRecord, type RelayTransport, type TaskRead, type TransportIdentity } from './transport.ts';
+/**
+ * Снимок задач backend: чтение без смешения редакций, semantic digest,
+ * WorkGraph, ContextSnapshot и manifest.
+ *
+ * Semantic digest — то, к чему привязано согласование (`SourceRef.revision`):
+ * текст требований, определения критериев (без отметок выполнения),
+ * зависимости, подзадачи, значимые документы и digest mapping. Колонка, свой
+ * in-progress, комментарии, история и отметки критериев в него не входят:
+ * они не меняют постановку. CAS-ревизии, токены согласованности чтения и
+ * идентичность сборки backend хранятся только в manifest — не в поле Git SHA
+ * и не в графе.
+ */
+export interface SnapshotProblem {
+    code: 'TASK_DONE' | 'TASK_CANCELLED' | 'COLUMN_NOT_ELIGIBLE' | 'DEPENDENCY_UNFINISHED' | 'DEPENDENCY_UNPROVEN' | 'LIMIT_EXCEEDED' | 'DOCUMENT_MISSING' | 'MAPPING_INVALID';
+    taskId: string;
+    key: string;
+    message: string;
+}
+export interface DocumentManifest {
+    id: string;
+    key: string;
+    name: string;
+    revision: number;
+    bytes: number;
+    required: boolean;
+    included: 'full' | 'truncated' | 'omitted';
+    includedBytes: number;
+    reason?: string;
+}
+export interface TaskManifest {
+    ref: string;
+    id: string;
+    key: string;
+    identity: string;
+    orderId: string;
+    semanticDigest: string;
+    /** CAS-ревизия backend на момент чтения (не Git SHA). */
+    casRevision: number;
+    column: string;
+    consistency: {
+        before: string;
+        after: string;
+    };
+    criteria: {
+        id: string;
+        title: string;
+        mapped: boolean;
+        completed: boolean;
+    }[];
+    dependencies: {
+        id: string;
+        key: string;
+        column: string;
+        finished: boolean;
+        inGraph: boolean;
+    }[];
+    children: {
+        id: string;
+        key: string;
+        column: string;
+        finished: boolean;
+    }[];
+    documents: DocumentManifest[];
+}
+export interface SnapshotManifest {
+    version: 1;
+    provider: string;
+    projectId: string;
+    connector: string;
+    build: Record<string, string>;
+    capabilities: string[];
+    graphId: string;
+    graphDigest: string;
+    contextDigest: string;
+    /** Semantic digest набора задач — `graph.source.revision`. */
+    revision: string;
+    readAt: string;
+    rounds: number;
+    limits: ConnectorConfig['limits'];
+    tasks: TaskManifest[];
+    truncated: string[];
+    problems: SnapshotProblem[];
+}
+export interface BuiltSnapshot {
+    graph: WorkGraph;
+    context: ContextSnapshot;
+    manifest: SnapshotManifest;
+    revision: string;
+    problems: SnapshotProblem[];
+}
+/** Безопасная причина отказа транспорта при чтении: сеть/CLI — не пустой список. */
+export declare function readFailure(error: unknown, what: string): HarnessError;
+/** Проверка подключения: provider и projectId backend обязаны совпасть с настроенными. */
+export declare function checkIdentity(transport: RelayTransport, config: ConnectorConfig, signal?: AbortSignal): Promise<TransportIdentity>;
+/**
+ * Полное согласованное чтение набора задач. Раунд — чтение всех задач; у
+ * каждой `consistency.before === after`. Снимок принимается, когда два
+ * последовательных раунда совпали токенами и содержимым: между ними ничего
+ * не менялось, и граф не собирается из разных редакций. Изменения —
+ * ограниченный повтор (`rereads`), затем явный отказ. Ошибка чтения —
+ * отказ, а не пустой результат.
+ */
+export declare function readStable(transport: RelayTransport, refs: string[], rereads: number, signal?: AbortSignal): Promise<{
+    reads: TaskRead[];
+    rounds: number;
+}>;
+export declare const matchCriterion: (criteria: CriterionRecord[], m: TaskMapping["criteria"][number]) => CriterionRecord[];
+/** Semantic digest задачи: смысл постановки без операционных полей. */
+export declare function semanticDigest(config: ConnectorConfig, mapping: TaskMapping, read: TaskRead): string;
+/** Прочитанная задача и её доверенные предпосылки → граф, контекст и manifest. */
+export declare function buildSnapshot(input: {
+    config: ConnectorConfig;
+    identity: TransportIdentity;
+    reads: TaskRead[];
+    rounds: number;
+    /** Доверенный receipt этого коннектора для задачи-зависимости вне графа. */
+    receiptOf: (orderId: string) => ReceiptRecord | undefined;
+}): BuiltSnapshot;
+/** Прочитать, собрать и проверить идентичность: общий путь `source-snapshot` и `run --source`. */
+export declare function takeSnapshot(input: {
+    config: ConnectorConfig;
+    transport: RelayTransport;
+    receiptOf: (orderId: string) => ReceiptRecord | undefined;
+    signal?: AbortSignal;
+}): Promise<BuiltSnapshot>;
+/** Отказ по eligibility/limits: причина и предел в сообщении, без запуска. */
+export declare function assertEligible(snapshot: BuiltSnapshot): void;