devcontour-harness 0.1.0-alpha.22 → 0.1.0-alpha.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -2
- package/docs/compatibility.md +11 -11
- package/docs/contracts.md +17 -2
- package/docs/quickstart.md +1 -1
- package/docs/release-notes/0.1.0-alpha.23.md +122 -0
- package/docs/toolchains.md +2 -1
- package/docs/upgrade.md +17 -17
- package/lib/agents/cli-adapter.js +1 -0
- package/lib/agents/review-probe.d.ts +1 -0
- package/lib/agents/review-probe.js +4 -0
- package/lib/cli.js +1 -1
- package/lib/contracts/cli.d.ts +20 -0
- package/lib/contracts/cli.js +11 -0
- package/lib/contracts/ports.d.ts +6 -0
- package/lib/control/base-move.d.ts +2 -0
- package/lib/control/base-move.js +13 -2
- package/lib/control/doctor.d.ts +10 -0
- package/lib/control/doctor.js +19 -3
- package/lib/control/harness.d.ts +6 -0
- package/lib/control/harness.js +2 -0
- package/lib/engine/joint-runner.d.ts +5 -0
- package/lib/engine/joint-runner.js +28 -5
- package/lib/engine/runner.d.ts +18 -0
- package/lib/engine/runner.js +48 -7
- package/lib/environment/checkout-root.d.ts +78 -0
- package/lib/environment/checkout-root.js +133 -0
- package/lib/environment/git-trust.js +4 -0
- package/lib/environment/isolation.d.ts +29 -4
- package/lib/environment/isolation.js +42 -8
- package/lib/index.d.ts +5 -0
- package/lib/index.js +5 -0
- package/lib/verification/confirm.d.ts +7 -4
- package/lib/verification/confirm.js +4 -2
- package/lib/verification/gates-at.d.ts +9 -5
- package/lib/verification/gates-at.js +30 -5
- package/lib/verification/gates.d.ts +13 -4
- package/lib/verification/gates.js +3 -1
- package/lib/verification/spike.d.ts +7 -4
- package/lib/verification/spike.js +4 -2
- package/package.json +1 -1
package/lib/control/harness.d.ts
CHANGED
|
@@ -29,6 +29,12 @@ export interface HarnessOptions {
|
|
|
29
29
|
policySource?: PolicySource;
|
|
30
30
|
/** База блокировок ресурсов; по умолчанию — общая для машины. */
|
|
31
31
|
resourceDatabase?: string;
|
|
32
|
+
/**
|
|
33
|
+
* Корень рабочих деревьев попыток и совместных проверок; без него —
|
|
34
|
+
* `chooseCheckoutRoot` (кэш пользователя, если каталог состояния внутри
|
|
35
|
+
* репозитория, иначе каталог состояния).
|
|
36
|
+
*/
|
|
37
|
+
checkoutRoot?: string;
|
|
32
38
|
/**
|
|
33
39
|
* Дополнения хоста к попыткам (например, история работы внешнего
|
|
34
40
|
* хранилища задач до исполнения). Приёмку не решают: отказ хука — отказ
|
package/lib/control/harness.js
CHANGED
|
@@ -71,6 +71,7 @@ export class Harness {
|
|
|
71
71
|
...(options.environment ? { environment: options.environment } : {}),
|
|
72
72
|
...(options.resourceDatabase ? { resourceDatabase: options.resourceDatabase } : {}),
|
|
73
73
|
...(options.hooks ? { hooks: options.hooks } : {}),
|
|
74
|
+
...(options.checkoutRoot ? { checkoutRoot: options.checkoutRoot } : {}),
|
|
74
75
|
});
|
|
75
76
|
this.joint = new JointRunner({
|
|
76
77
|
engine: this.engine,
|
|
@@ -78,6 +79,7 @@ export class Harness {
|
|
|
78
79
|
baseDir: options.baseDir,
|
|
79
80
|
...(options.environment ? { environment: options.environment } : {}),
|
|
80
81
|
...(options.resourceDatabase ? { resourceDatabase: options.resourceDatabase } : {}),
|
|
82
|
+
...(options.checkoutRoot ? { checkoutRoot: options.checkoutRoot } : {}),
|
|
81
83
|
});
|
|
82
84
|
}
|
|
83
85
|
close() {
|
|
@@ -7,6 +7,11 @@ export interface JointRunnerOptions {
|
|
|
7
7
|
baseDir: string;
|
|
8
8
|
environment?: NodeJS.ProcessEnv;
|
|
9
9
|
resourceDatabase?: string;
|
|
10
|
+
/**
|
|
11
|
+
* Корень снимков компонентов (`<checkoutRoot>/.joint/<id>/components`: ID репозитория с точки не начинается); без
|
|
12
|
+
* него — `chooseCheckoutRoot` по каталогу состояния и каталогу проверки.
|
|
13
|
+
*/
|
|
14
|
+
checkoutRoot?: string;
|
|
10
15
|
/** Каталог проверки (по умолчанию `<stateDir>/joint/<id>`). */
|
|
11
16
|
directory?: (verification: JointVerificationState) => string;
|
|
12
17
|
/** Дополнительные переменные окружения gates этой проверки (у хоста — его идентификаторы). */
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
2
|
import { mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
|
|
3
|
-
import { isAbsolute, join, resolve, sep } from 'node:path';
|
|
3
|
+
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
4
4
|
import { digestOf, } from "../contracts/index.js";
|
|
5
5
|
import { git } from "../environment/process.js";
|
|
6
|
+
import { chooseCheckoutRoot } from "../environment/checkout-root.js";
|
|
7
|
+
import { credentialPaths } from "../environment/isolation.js";
|
|
6
8
|
import { CleanupFailure, availableRedactor, executionEnvironment, withEnvironment, } from "../environment/lifecycle.js";
|
|
7
9
|
import { composeRedactors } from "../environment/redaction.js";
|
|
8
10
|
import { defaultResourceDatabase, withResources } from "../environment/resources.js";
|
|
@@ -55,6 +57,17 @@ export class JointRunner {
|
|
|
55
57
|
}
|
|
56
58
|
}, Math.max(1000, this.policy.leaseMs / 3));
|
|
57
59
|
const dir = this.options.directory?.(v) ?? join(this.options.stateDir, 'joint', v.id);
|
|
60
|
+
// Снимки компонентов — вне дерева, если каталог проверки лежит внутри
|
|
61
|
+
// репозитория: gate, ищущий конфигурацию вверх, не упирается в закрытый checkout.
|
|
62
|
+
const placement = chooseCheckoutRoot({
|
|
63
|
+
stateDirs: [this.options.stateDir, dir],
|
|
64
|
+
repositories: this.policy.repositories.map((r) => this.repoPath(r)),
|
|
65
|
+
hidden: credentialPaths(),
|
|
66
|
+
...(this.options.checkoutRoot ? { configured: this.options.checkoutRoot } : {}),
|
|
67
|
+
});
|
|
68
|
+
const components = placement.root
|
|
69
|
+
? join(placement.root, '.joint', v.id, 'components')
|
|
70
|
+
: join(dir, 'components');
|
|
58
71
|
const worktrees = [];
|
|
59
72
|
const source = this.options.environment ?? process.env;
|
|
60
73
|
// Незавершённая очистка окружения оставляет снимки: их разбирает cleanup.
|
|
@@ -66,7 +79,10 @@ export class JointRunner {
|
|
|
66
79
|
resourceDatabase: this.options.resourceDatabase ?? defaultResourceDatabase(),
|
|
67
80
|
}, [...new Set(this.policy.workspaceGates.flatMap((g) => g.resources ?? []))], `${this.options.stateDir}:${v.id}`, signal, async (signal, resources) => {
|
|
68
81
|
await this.options.prepare?.(signal);
|
|
69
|
-
|
|
82
|
+
// Каталог проверки (impact, manifest, логи) — и тогда, когда
|
|
83
|
+
// компоненты лежат под корнем вне дерева.
|
|
84
|
+
await mkdir(dir, { recursive: true });
|
|
85
|
+
await mkdir(components, { recursive: true });
|
|
70
86
|
const works = this.engine.read((view) => v.workIds.map((id) => view.work(id)));
|
|
71
87
|
const manifest = {};
|
|
72
88
|
const paths = {};
|
|
@@ -78,7 +94,7 @@ export class JointRunner {
|
|
|
78
94
|
await git(path, 'merge-base', '--is-ancestor', w.resultSha, sha).catch(() => {
|
|
79
95
|
throw new Error(`Результат ${w.id} отсутствует в ${repo.targetRef} ${repo.id}`);
|
|
80
96
|
});
|
|
81
|
-
const cwd = join(
|
|
97
|
+
const cwd = join(components, repo.id);
|
|
82
98
|
await git(path, 'worktree', 'add', '--detach', cwd, sha);
|
|
83
99
|
worktrees.push({ repo: path, cwd });
|
|
84
100
|
manifest[repo.id] = { sha, tree: await git(cwd, 'rev-parse', 'HEAD^{tree}') };
|
|
@@ -163,6 +179,7 @@ export class JointRunner {
|
|
|
163
179
|
this.options.stateDir,
|
|
164
180
|
...this.policy.repositories.map((r) => this.repoPath(r)),
|
|
165
181
|
],
|
|
182
|
+
...(placement.root ? { checkouts: [placement.root] } : {}),
|
|
166
183
|
settingsDir: join(dir, gate.id),
|
|
167
184
|
env: {
|
|
168
185
|
...environment.env,
|
|
@@ -246,8 +263,14 @@ export class JointRunner {
|
|
|
246
263
|
if (!preserve) {
|
|
247
264
|
for (const w of worktrees)
|
|
248
265
|
await git(w.repo, 'worktree', 'remove', '--force', w.cwd).catch(() => undefined);
|
|
249
|
-
|
|
250
|
-
|
|
266
|
+
// Убирается только каталог, созданный здесь: в каталоге состояния или
|
|
267
|
+
// под корнем вне дерева.
|
|
268
|
+
const owned = placement.root ?? this.options.stateDir;
|
|
269
|
+
if (components.startsWith(owned + sep))
|
|
270
|
+
await rm(placement.root ? dirname(components) : components, {
|
|
271
|
+
recursive: true,
|
|
272
|
+
force: true,
|
|
273
|
+
}).catch(() => undefined);
|
|
251
274
|
}
|
|
252
275
|
}
|
|
253
276
|
}
|
package/lib/engine/runner.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type ImplementationResult, type AttemptState, type ContextSnapshot, type ExecutionPolicy, type RuntimeAdapter, type RuntimeName, type WorkState } from '../contracts/index.ts';
|
|
2
|
+
import { type CheckoutRoot } from '../environment/checkout-root.ts';
|
|
2
3
|
import { type FailureKind } from './failure.ts';
|
|
3
4
|
import { type Engine } from './engine.ts';
|
|
4
5
|
import { CorpusStore } from '../verification/corpus.ts';
|
|
@@ -13,6 +14,15 @@ export interface RunnerOptions {
|
|
|
13
14
|
* туда и его попытки.
|
|
14
15
|
*/
|
|
15
16
|
stateDirFor?: (repositoryId: string) => string;
|
|
17
|
+
/**
|
|
18
|
+
* Корень рабочих деревьев, снимков зависимостей и проверок потребителей
|
|
19
|
+
* (`<checkoutRoot>/<repositoryId>/worktrees/<attempt>`…). Без него —
|
|
20
|
+
* `chooseCheckoutRoot`: каталог кэша пользователя, если каталог состояния
|
|
21
|
+
* лежит внутри репозитория, иначе прежнее место в каталоге состояния.
|
|
22
|
+
* Лучше на том же томе, что репозитории: менеджеры пакетов ставят
|
|
23
|
+
* зависимости жёсткими ссылками и reflink.
|
|
24
|
+
*/
|
|
25
|
+
checkoutRoot?: string;
|
|
16
26
|
/** Каталог, от которого разрешаются относительные пути репозиториев политики. */
|
|
17
27
|
baseDir: string;
|
|
18
28
|
adapters: Partial<Record<RuntimeName, RuntimeAdapter>>;
|
|
@@ -90,6 +100,14 @@ export declare class Runner {
|
|
|
90
100
|
constructor(options: RunnerOptions);
|
|
91
101
|
/** Каталог попыток репозитория. */
|
|
92
102
|
private dirOf;
|
|
103
|
+
private placement?;
|
|
104
|
+
/**
|
|
105
|
+
* Действующий корень рабочих деревьев (`checkout-root.ts`): хост
|
|
106
|
+
* показывает его в диагностике. Выбирается один раз на исполнитель.
|
|
107
|
+
*/
|
|
108
|
+
checkoutRoot(): CheckoutRoot;
|
|
109
|
+
/** Каталог рабочего дерева вида `kind`: вне дерева или прежний в каталоге попыток. */
|
|
110
|
+
private checkout;
|
|
93
111
|
repoPath(repo: Repo): string;
|
|
94
112
|
private repo;
|
|
95
113
|
/**
|
package/lib/engine/runner.js
CHANGED
|
@@ -2,11 +2,13 @@ import { execFileSync } from 'node:child_process';
|
|
|
2
2
|
import { randomUUID } from 'node:crypto';
|
|
3
3
|
import { existsSync } from 'node:fs';
|
|
4
4
|
import { mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
|
|
5
|
-
import { isAbsolute, join, relative, resolve } from 'node:path';
|
|
5
|
+
import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
|
|
6
6
|
import { roleBinding, selectReviewer, mcpEnvironment, HarnessError, digestOf, contextDigest, implementationResultSchema, codeReviewHistory, codeReviewScope, checkCodeReview, logicalReview, DEFAULT_REVIEW_PROTOCOL_RETRIES, reviewResultSchema, sha256, } from "../contracts/index.js";
|
|
7
7
|
import { git, hostGitArgs } from "../environment/process.js";
|
|
8
8
|
import { protectedChanges, protectedSnapshot, SandboxPolicyError, } from "../environment/isolation.js";
|
|
9
9
|
import { executionEnvironment, runSteps, withEnvironment } from "../environment/lifecycle.js";
|
|
10
|
+
import { checkoutPath, chooseCheckoutRoot, realish, } from "../environment/checkout-root.js";
|
|
11
|
+
import { credentialPaths } from "../environment/isolation.js";
|
|
10
12
|
import { redactDeep } from "../environment/redaction.js";
|
|
11
13
|
import { alreadySatisfiedReviewOutputSchema, implementationOutputSchema, reviewOutputSchema, } from "../agents/schemas.js";
|
|
12
14
|
import { reviewInspection } from "../agents/inspect.js";
|
|
@@ -75,6 +77,23 @@ export class Runner {
|
|
|
75
77
|
dirOf(repositoryId) {
|
|
76
78
|
return this.options.stateDirFor?.(repositoryId) ?? this.options.stateDir;
|
|
77
79
|
}
|
|
80
|
+
placement;
|
|
81
|
+
/**
|
|
82
|
+
* Действующий корень рабочих деревьев (`checkout-root.ts`): хост
|
|
83
|
+
* показывает его в диагностике. Выбирается один раз на исполнитель.
|
|
84
|
+
*/
|
|
85
|
+
checkoutRoot() {
|
|
86
|
+
return (this.placement ??= chooseCheckoutRoot({
|
|
87
|
+
stateDirs: [this.options.stateDir, ...this.policy.repositories.map((r) => this.dirOf(r.id))],
|
|
88
|
+
repositories: this.policy.repositories.map((r) => this.repoPath(r)),
|
|
89
|
+
hidden: credentialPaths(),
|
|
90
|
+
...(this.options.checkoutRoot ? { configured: this.options.checkoutRoot } : {}),
|
|
91
|
+
}));
|
|
92
|
+
}
|
|
93
|
+
/** Каталог рабочего дерева вида `kind`: вне дерева или прежний в каталоге попыток. */
|
|
94
|
+
checkout(repositoryId, kind, ...rest) {
|
|
95
|
+
return checkoutPath(this.checkoutRoot(), join(this.dirOf(repositoryId), kind, ...rest), repositoryId, kind, ...rest);
|
|
96
|
+
}
|
|
78
97
|
repoPath(repo) {
|
|
79
98
|
return isAbsolute(repo.path) ? repo.path : resolve(this.options.baseDir, repo.path);
|
|
80
99
|
}
|
|
@@ -90,7 +109,11 @@ export class Runner {
|
|
|
90
109
|
*/
|
|
91
110
|
boundary(dependencies = []) {
|
|
92
111
|
const repos = this.policy.repositories.map((r) => this.repoPath(r));
|
|
112
|
+
const root = this.checkoutRoot().root;
|
|
93
113
|
return {
|
|
114
|
+
// Корень вне дерева закрыт целиком, как каталог состояния: свои
|
|
115
|
+
// деревья открыты более конкретным разрешением.
|
|
116
|
+
checkouts: root ? [root] : [],
|
|
94
117
|
hidden: [
|
|
95
118
|
...new Set([
|
|
96
119
|
this.options.stateDir,
|
|
@@ -374,6 +397,7 @@ export class Runner {
|
|
|
374
397
|
mode: this.policy.isolation.mode,
|
|
375
398
|
writable: review ? [] : [input.cwd],
|
|
376
399
|
denied: boundary.hidden,
|
|
400
|
+
...(boundary.checkouts.length ? { checkouts: boundary.checkouts } : {}),
|
|
377
401
|
readable: [
|
|
378
402
|
input.cwd,
|
|
379
403
|
...boundary.readable,
|
|
@@ -668,7 +692,7 @@ export class Runner {
|
|
|
668
692
|
controller.abort();
|
|
669
693
|
}
|
|
670
694
|
}, Math.max(1000, this.policy.leaseMs / 3));
|
|
671
|
-
const cwd =
|
|
695
|
+
const cwd = this.checkout(repo.id, 'worktrees', attempt.id);
|
|
672
696
|
const integrationCwd = cwd + '-integration';
|
|
673
697
|
const artifacts = join(this.dirOf(repo.id), 'artifacts', attempt.id);
|
|
674
698
|
const worktrees = [];
|
|
@@ -720,7 +744,7 @@ export class Runner {
|
|
|
720
744
|
const dependencies = await snapshotDependencies({
|
|
721
745
|
repos: this.repositories(),
|
|
722
746
|
repositoryId: repo.id,
|
|
723
|
-
dir:
|
|
747
|
+
dir: this.checkout(repo.id, 'dependencies', attempt.id),
|
|
724
748
|
artifacts,
|
|
725
749
|
runId: attempt.id,
|
|
726
750
|
policy: this.policy,
|
|
@@ -743,7 +767,7 @@ export class Runner {
|
|
|
743
767
|
// берётся ли кандидат предыдущей попытки вместо нового кода.
|
|
744
768
|
const reuse = this.engine.implementationBasis(attempt.id, attempt.token, implementationBasis(work, attempt, base, this.engine.version));
|
|
745
769
|
attempt = { ...attempt, ...(reuse.reusedFrom ? { reusedFrom: reuse.reusedFrom } : {}) };
|
|
746
|
-
await mkdir(
|
|
770
|
+
await mkdir(dirname(cwd), { recursive: true });
|
|
747
771
|
await git(repoPath, 'worktree', 'add', '-b', `${this.options.branchPrefix ?? 'harness/run-'}${attempt.id}`, cwd, reuse.reusedFrom?.candidateSha ?? base);
|
|
748
772
|
worktrees.push(cwd);
|
|
749
773
|
this.engine.phase(attempt.id, attempt.token, 'running', { baseSha: base, worktree: cwd });
|
|
@@ -1060,10 +1084,14 @@ export class Runner {
|
|
|
1060
1084
|
],
|
|
1061
1085
|
snapshots: [],
|
|
1062
1086
|
};
|
|
1087
|
+
// Окружения прежних попыток лежат в каталоге состояния, новых — под
|
|
1088
|
+
// корнем рабочих деревьев вне дерева.
|
|
1089
|
+
const outside = this.checkoutRoot().root;
|
|
1063
1090
|
const roots = [
|
|
1064
1091
|
...new Set([
|
|
1065
1092
|
await realpath(this.options.stateDir),
|
|
1066
1093
|
await realpath(this.dirOf(attempt.repositoryId)),
|
|
1094
|
+
...(outside ? [realish(outside)] : []),
|
|
1067
1095
|
]),
|
|
1068
1096
|
];
|
|
1069
1097
|
const cleaned = [];
|
|
@@ -1206,9 +1234,9 @@ export class Runner {
|
|
|
1206
1234
|
const repo = this.repo(consumer.repositoryId);
|
|
1207
1235
|
const checkout = this.repoPath(repo);
|
|
1208
1236
|
const id = `${attempt.id}-consumer-${repo.id}-${randomUUID().slice(0, 8)}`;
|
|
1209
|
-
const dir =
|
|
1237
|
+
const dir = this.checkout(repo.id, 'consumers', id);
|
|
1210
1238
|
const own = join(artifacts, 'integration', 'consumer', repo.id);
|
|
1211
|
-
await mkdir(
|
|
1239
|
+
await mkdir(dirname(dir), { recursive: true });
|
|
1212
1240
|
await git(checkout, 'worktree', 'add', '--detach', dir, repo.targetRef);
|
|
1213
1241
|
let dependencies = [];
|
|
1214
1242
|
let failure;
|
|
@@ -1225,7 +1253,7 @@ export class Runner {
|
|
|
1225
1253
|
dependencies = await snapshotDependencies({
|
|
1226
1254
|
repos: this.repositories(),
|
|
1227
1255
|
repositoryId: repo.id,
|
|
1228
|
-
dir:
|
|
1256
|
+
dir: this.checkout(repo.id, 'dependencies', id),
|
|
1229
1257
|
artifacts: own,
|
|
1230
1258
|
runId: attempt.id,
|
|
1231
1259
|
policy: this.policy,
|
|
@@ -1332,6 +1360,7 @@ export class Runner {
|
|
|
1332
1360
|
cwd,
|
|
1333
1361
|
controller: boundary.hidden,
|
|
1334
1362
|
readable: [cwd, ...boundary.readable],
|
|
1363
|
+
...(boundary.checkouts.length ? { checkouts: boundary.checkouts } : {}),
|
|
1335
1364
|
isolation: this.policy.isolation,
|
|
1336
1365
|
commandTimeoutMs: limits.commandTimeoutMs,
|
|
1337
1366
|
budgetMs,
|
|
@@ -1895,6 +1924,12 @@ export class Runner {
|
|
|
1895
1924
|
stateDir: this.options.stateDir,
|
|
1896
1925
|
repoPath: (repo) => this.repoPath(repo),
|
|
1897
1926
|
boundary: () => this.boundary(),
|
|
1927
|
+
// Прежнее место эксперимента — общий каталог состояния: меняется только корень вне дерева.
|
|
1928
|
+
...(this.checkoutRoot().root
|
|
1929
|
+
? {
|
|
1930
|
+
checkout: (repositoryId, kind, id) => this.checkout(repositoryId, kind, id),
|
|
1931
|
+
}
|
|
1932
|
+
: {}),
|
|
1898
1933
|
...(this.options.environment ? { environment: this.options.environment } : {}),
|
|
1899
1934
|
}, raw);
|
|
1900
1935
|
}
|
|
@@ -1909,6 +1944,12 @@ export class Runner {
|
|
|
1909
1944
|
stateDir: this.options.stateDir,
|
|
1910
1945
|
repoPath: (repo) => this.repoPath(repo),
|
|
1911
1946
|
boundary: () => this.boundary(),
|
|
1947
|
+
// Прежнее место эксперимента — общий каталог состояния: меняется только корень вне дерева.
|
|
1948
|
+
...(this.checkoutRoot().root
|
|
1949
|
+
? {
|
|
1950
|
+
checkout: (repositoryId, kind, id) => this.checkout(repositoryId, kind, id),
|
|
1951
|
+
}
|
|
1952
|
+
: {}),
|
|
1912
1953
|
...(this.options.environment ? { environment: this.options.environment } : {}),
|
|
1913
1954
|
}, raw);
|
|
1914
1955
|
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Где harness создаёт рабочие деревья попыток, снимки зависимостей, деревья
|
|
3
|
+
* переноса базы, проверки на SHA и проверки потребителей.
|
|
4
|
+
*
|
|
5
|
+
* Прежде они лежали в каталоге состояния. При встроенном размещении каталог
|
|
6
|
+
* состояния находится внутри репозитория человека (`<W>/.devcontour-local`),
|
|
7
|
+
* и тогда checkout кандидата оказывался вложен в его рабочее дерево. Песочница
|
|
8
|
+
* закрывает `<W>` целиком и открывает только сам checkout, а инструменты,
|
|
9
|
+
* которые ищут конфигурацию вверх по дереву (browserslist, Metro, postcss,
|
|
10
|
+
* tsconfig, prettier), доходили до `<W>/package.json` и получали EPERM вместо
|
|
11
|
+
* ENOENT. Без песочницы они бы прочитали конфигурацию рабочего дерева
|
|
12
|
+
* человека — кандидат проверялся бы не сам по себе.
|
|
13
|
+
*
|
|
14
|
+
* Поэтому корень рабочих деревьев выбирается так:
|
|
15
|
+
* - корень, заданный хостом (`checkoutRoot`), — как есть, если он не внутри
|
|
16
|
+
* репозитория, закрытого пути или каталога состояния (иначе отказ);
|
|
17
|
+
* - каталог состояния внутри репозитория политики или внутри закрытого
|
|
18
|
+
* песочницей пути — каталог кэша пользователя вне дерева: macOS
|
|
19
|
+
* `~/Library/Caches/devcontour-harness/<hash>`, Linux
|
|
20
|
+
* `$XDG_CACHE_HOME/devcontour-harness/<hash>` или
|
|
21
|
+
* `~/.cache/devcontour-harness/<hash>`; `<hash>` — устойчивый хэш
|
|
22
|
+
* настоящего пути каталога состояния;
|
|
23
|
+
* - иначе — прежнее место (отдельное размещение не меняется).
|
|
24
|
+
*
|
|
25
|
+
* Кэш на другом томе, чем репозиторий, ломает жёсткие ссылки и reflink
|
|
26
|
+
* менеджеров пакетов (pnpm store): тогда корень остаётся прежним, а причина
|
|
27
|
+
* видна в `note` (doctor хоста её показывает). Так же — кэш внутри
|
|
28
|
+
* репозитория, закрытого пути или каталога состояния (`XDG_CACHE_HOME=<W>/.cache`)
|
|
29
|
+
* и каталог кэша, который оказался ссылкой или принадлежит другому
|
|
30
|
+
* пользователю: каталоги кэша создаются с правами 0700.
|
|
31
|
+
*
|
|
32
|
+
* Корни кэша не убираются, когда workspace переносят или удаляют: каталоги
|
|
33
|
+
* `<кэш>/devcontour-harness/<hash>` без живого каталога состояния можно удалить
|
|
34
|
+
* вручную, когда harness не запущен.
|
|
35
|
+
*/
|
|
36
|
+
export type CheckoutPlacement = 'configured' | 'in-place' | 'cache' | 'cross-volume';
|
|
37
|
+
export interface CheckoutRoot {
|
|
38
|
+
/** Корень вне каталога состояния; без него — прежнее место. */
|
|
39
|
+
root?: string;
|
|
40
|
+
placement: CheckoutPlacement;
|
|
41
|
+
/** Пояснение для диагностики: почему корень такой. */
|
|
42
|
+
note?: string;
|
|
43
|
+
}
|
|
44
|
+
export interface CheckoutRootInput {
|
|
45
|
+
/** Каталоги состояния (общий и каталоги попыток репозиториев); первый задаёт хэш. */
|
|
46
|
+
stateDirs: string[];
|
|
47
|
+
/** Пути репозиториев политики. */
|
|
48
|
+
repositories: string[];
|
|
49
|
+
/** Что ещё закрыто песочницей (учётные данные, каталоги хоста). */
|
|
50
|
+
hidden?: string[];
|
|
51
|
+
/** Корень, заданный хостом. */
|
|
52
|
+
configured?: string;
|
|
53
|
+
platform?: NodeJS.Platform;
|
|
54
|
+
env?: NodeJS.ProcessEnv;
|
|
55
|
+
home?: string;
|
|
56
|
+
/** Номер тома пути (`stat.dev`); тест подменяет его. */
|
|
57
|
+
device?: (path: string) => number | undefined;
|
|
58
|
+
/**
|
|
59
|
+
* Создать каталоги кэша (0700). Без записи (`false`, диагностика) —
|
|
60
|
+
* только проверка существующих.
|
|
61
|
+
*/
|
|
62
|
+
create?: boolean;
|
|
63
|
+
/** Владелец каталогов кэша; по умолчанию — текущий пользователь. */
|
|
64
|
+
uid?: number;
|
|
65
|
+
}
|
|
66
|
+
/** Настоящий путь и для ещё не созданного каталога: от ближайшего существующего предка. */
|
|
67
|
+
export declare function realish(path: string): string;
|
|
68
|
+
/** Каталог кэша пользователя для рабочих деревьев (без хэша). */
|
|
69
|
+
export declare function checkoutCacheBase(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
|
|
70
|
+
/** Устойчивый хэш каталога состояния: тот же путь — тот же корень. */
|
|
71
|
+
export declare const stateHash: (stateDir: string) => string;
|
|
72
|
+
export declare function chooseCheckoutRoot(input: CheckoutRootInput): CheckoutRoot;
|
|
73
|
+
/**
|
|
74
|
+
* Каталог рабочего дерева вида `kind` (`worktrees`, `dependencies`,
|
|
75
|
+
* `gates-at`…). Корень вне дерева: `<root>/<repositoryId>/<kind>/…`; иначе —
|
|
76
|
+
* прежний путь `legacy`.
|
|
77
|
+
*/
|
|
78
|
+
export declare function checkoutPath(choice: CheckoutRoot, legacy: string, repositoryId: string, kind: string, ...rest: string[]): string;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { lstatSync, mkdirSync, realpathSync, statSync } from 'node:fs';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
5
|
+
import { HarnessError } from "../contracts/index.js";
|
|
6
|
+
/** Настоящий путь и для ещё не созданного каталога: от ближайшего существующего предка. */
|
|
7
|
+
export function realish(path) {
|
|
8
|
+
const absolute = resolve(path);
|
|
9
|
+
try {
|
|
10
|
+
return realpathSync(absolute);
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
const parent = dirname(absolute);
|
|
14
|
+
return parent === absolute ? absolute : join(realish(parent), basename(absolute));
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
const within = (path, root) => path === root || path.startsWith(root + sep);
|
|
18
|
+
/** Номер тома ближайшего существующего предка пути. */
|
|
19
|
+
function deviceOf(path) {
|
|
20
|
+
for (let dir = resolve(path);; dir = dirname(dir)) {
|
|
21
|
+
try {
|
|
22
|
+
return statSync(dir).dev;
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
if (dirname(dir) === dir)
|
|
26
|
+
return undefined;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/** Каталог кэша пользователя для рабочих деревьев (без хэша). */
|
|
31
|
+
export function checkoutCacheBase(platform = process.platform, env = process.env, home = homedir()) {
|
|
32
|
+
if (platform === 'darwin')
|
|
33
|
+
return join(home, 'Library', 'Caches', 'devcontour-harness');
|
|
34
|
+
const xdg = env.XDG_CACHE_HOME;
|
|
35
|
+
// Относительный XDG_CACHE_HOME спецификация велит игнорировать.
|
|
36
|
+
return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.cache'), 'devcontour-harness');
|
|
37
|
+
}
|
|
38
|
+
/** Устойчивый хэш каталога состояния: тот же путь — тот же корень. */
|
|
39
|
+
export const stateHash = (stateDir) => createHash('sha256').update(realish(stateDir)).digest('hex').slice(0, 16);
|
|
40
|
+
/**
|
|
41
|
+
* Каталог кэша безопасен для рабочих деревьев: настоящий каталог (не ссылка)
|
|
42
|
+
* этого пользователя. `create` — создать недостающий с правами 0700.
|
|
43
|
+
* Возвращает причину отказа или `undefined`.
|
|
44
|
+
*/
|
|
45
|
+
function unsafeDir(path, create, uid) {
|
|
46
|
+
let stat;
|
|
47
|
+
try {
|
|
48
|
+
stat = lstatSync(path);
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
if (!create)
|
|
52
|
+
return undefined;
|
|
53
|
+
try {
|
|
54
|
+
mkdirSync(path, { mode: 0o700 });
|
|
55
|
+
stat = lstatSync(path);
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
return `${path} не создан: ${error.code ?? String(error)}`;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
if (stat.isSymbolicLink())
|
|
62
|
+
return `${path} — символическая ссылка`;
|
|
63
|
+
if (!stat.isDirectory())
|
|
64
|
+
return `${path} не каталог`;
|
|
65
|
+
if (uid !== undefined && stat.uid !== uid)
|
|
66
|
+
return `${path} принадлежит другому пользователю`;
|
|
67
|
+
return undefined;
|
|
68
|
+
}
|
|
69
|
+
export function chooseCheckoutRoot(input) {
|
|
70
|
+
const states = input.stateDirs.map(realish);
|
|
71
|
+
const repos = input.repositories.map(realish);
|
|
72
|
+
const hidden = (input.hidden ?? []).map(realish);
|
|
73
|
+
// Корень внутри репозитория, закрытого пути или каталога состояния вернул
|
|
74
|
+
// бы ту же вложенность (или открыл бы закрытое).
|
|
75
|
+
const enclosing = (root) => [...repos, ...hidden, ...states].find((p) => within(root, p));
|
|
76
|
+
const uid = input.uid !== undefined ? input.uid : process.getuid?.();
|
|
77
|
+
const create = input.create ?? true;
|
|
78
|
+
if (input.configured) {
|
|
79
|
+
const root = realish(input.configured);
|
|
80
|
+
const inside = enclosing(root);
|
|
81
|
+
if (inside)
|
|
82
|
+
throw new HarnessError('INVALID_INPUT', `checkoutRoot ${root} внутри ${inside}: корень рабочих деревьев должен лежать вне репозиториев, закрытых путей и каталога состояния`);
|
|
83
|
+
const unsafe = unsafeDir(root, false, uid);
|
|
84
|
+
if (unsafe)
|
|
85
|
+
throw new HarnessError('INVALID_INPUT', 'checkoutRoot: ' + unsafe);
|
|
86
|
+
return { root, placement: 'configured' };
|
|
87
|
+
}
|
|
88
|
+
// Каталог состояния внутри репозитория (или им и являющийся) либо строго
|
|
89
|
+
// внутри другого закрытого пути: предки его рабочих деревьев были бы закрыты.
|
|
90
|
+
const nested = states.find((s) => repos.some((r) => within(s, r)) || hidden.some((h) => s !== h && within(s, h)));
|
|
91
|
+
if (!nested)
|
|
92
|
+
return { placement: 'in-place' };
|
|
93
|
+
const base = checkoutCacheBase(input.platform, input.env, input.home);
|
|
94
|
+
const root = join(base, stateHash(input.stateDirs[0] ?? nested));
|
|
95
|
+
const stay = (why) => ({
|
|
96
|
+
placement: 'in-place',
|
|
97
|
+
note: `${why}: рабочие деревья остаются в каталоге состояния ${nested} (внутри закрытого дерева инструменты, ищущие конфигурацию вверх по дереву, получат EPERM); задайте checkoutRoot`,
|
|
98
|
+
});
|
|
99
|
+
const inside = enclosing(realish(root));
|
|
100
|
+
if (inside)
|
|
101
|
+
return stay(`каталог кэша ${root} внутри ${inside}`);
|
|
102
|
+
const device = input.device ?? deviceOf;
|
|
103
|
+
const at = device(root);
|
|
104
|
+
const other = repos.find((r) => {
|
|
105
|
+
const d = device(r);
|
|
106
|
+
return at !== undefined && d !== undefined && d !== at;
|
|
107
|
+
});
|
|
108
|
+
if (other)
|
|
109
|
+
return {
|
|
110
|
+
placement: 'cross-volume',
|
|
111
|
+
note: `каталог кэша ${root} на другом томе, чем репозиторий ${other}: жёсткие ссылки и reflink менеджера пакетов там не работают, рабочие деревья остаются в каталоге состояния ${nested} (внутри закрытого дерева инструменты, ищущие конфигурацию вверх по дереву, получат EPERM); задайте checkoutRoot на томе репозитория`,
|
|
112
|
+
};
|
|
113
|
+
// Общий каталог кэша — только существующий предок: создаются и
|
|
114
|
+
// проверяются каталог harness и каталог этого состояния.
|
|
115
|
+
for (const dir of [base, root]) {
|
|
116
|
+
const unsafe = unsafeDir(dir, create, uid);
|
|
117
|
+
if (unsafe)
|
|
118
|
+
return stay('каталог кэша небезопасен: ' + unsafe);
|
|
119
|
+
}
|
|
120
|
+
return {
|
|
121
|
+
root,
|
|
122
|
+
placement: 'cache',
|
|
123
|
+
note: `каталог состояния ${nested} внутри репозитория или закрытого пути: рабочие деревья — вне дерева, в ${root}`,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Каталог рабочего дерева вида `kind` (`worktrees`, `dependencies`,
|
|
128
|
+
* `gates-at`…). Корень вне дерева: `<root>/<repositoryId>/<kind>/…`; иначе —
|
|
129
|
+
* прежний путь `legacy`.
|
|
130
|
+
*/
|
|
131
|
+
export function checkoutPath(choice, legacy, repositoryId, kind, ...rest) {
|
|
132
|
+
return choice.root ? join(choice.root, repositoryId, kind, ...rest) : legacy;
|
|
133
|
+
}
|
|
@@ -85,6 +85,10 @@ export function assertTrustedCheckout(cwd) {
|
|
|
85
85
|
/* нет `.git` на этом уровне */
|
|
86
86
|
}
|
|
87
87
|
const nested = insideKnown(dir);
|
|
88
|
+
// Файл `.git` созданного хостом дерева удалён: git ушёл бы в репозиторий
|
|
89
|
+
// предка (каталог состояния внутри checkout человека, чужой `.git` выше).
|
|
90
|
+
if (!stat && knownWorktrees.has(dir))
|
|
91
|
+
refuse(`${dotgit} рабочего дерева удалён`);
|
|
88
92
|
if (stat) {
|
|
89
93
|
if (nested)
|
|
90
94
|
refuse(`вложенный репозиторий ${dotgit} внутри рабочего дерева ${nested}`);
|
|
@@ -41,6 +41,16 @@ export declare function isolation(options: {
|
|
|
41
41
|
domains?: string[];
|
|
42
42
|
/** Элементы каталога контура хоста, которые закрываются и до своего появления. */
|
|
43
43
|
entries?: string[];
|
|
44
|
+
/**
|
|
45
|
+
* Корни рабочих деревьев вне каталога состояния (`checkout-root.ts`):
|
|
46
|
+
* закрыты целиком, как каталог состояния; свои деревья проверки открыты
|
|
47
|
+
* более конкретным разрешением (`write`, `readable`). Деревья других
|
|
48
|
+
* попыток закрыты, и появившиеся после построения политики тоже. Поиск
|
|
49
|
+
* конфигурации вверх по дереву не ломается: в корне нет файлов
|
|
50
|
+
* конфигурации, а `stat` отсутствующего файла под запретом Seatbelt
|
|
51
|
+
* отвечает ENOENT, метаданные каталогов-предков открыты.
|
|
52
|
+
*/
|
|
53
|
+
checkouts?: string[];
|
|
44
54
|
}): Isolation;
|
|
45
55
|
/** Sandbox Claude Code: применяется к Bash; без запасного выхода из песочницы. */
|
|
46
56
|
export declare function claudeSandbox(policy: Isolation, review: boolean, cwd: string): {
|
|
@@ -167,11 +177,26 @@ export declare function watchSandboxLog(tag: string): Promise<{
|
|
|
167
177
|
stop(drainMs: number): Promise<SandboxViolation[]>;
|
|
168
178
|
} | undefined>;
|
|
169
179
|
/**
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
*
|
|
180
|
+
* Запрет чтения, которым песочница закрыла путь: путь внутри закрытого и не
|
|
181
|
+
* внутри более конкретного открытого (srt: открытое внутри закрытого
|
|
182
|
+
* побеждает, закрытое внутри открытого — снова закрыто).
|
|
183
|
+
*/
|
|
184
|
+
export declare function hiddenReadRule(policy: Isolation, path: string): string | undefined;
|
|
185
|
+
/**
|
|
186
|
+
* Отказы песочницы, которые подтвердило ядро и которые правкой кода не снять.
|
|
187
|
+
*
|
|
188
|
+
* - Запись: обязательная политика в открытых проверке каталогах. Запись вне
|
|
189
|
+
* открытых каталогов — ошибка кода проверки, а не среды: её здесь нет.
|
|
190
|
+
* - Чтение (и `stat`): закрытый файл в предке рабочего каталога проверки
|
|
191
|
+
* (`cwd`), на котором она упала с EPERM. Инструменты ищут конфигурацию
|
|
192
|
+
* вверх по дереву и на EPERM (в отличие от ENOENT) падают. Нужны все
|
|
193
|
+
* признаки — запись ядра для тега этой проверки, форма поиска вверх
|
|
194
|
+
* (каталог файла — строгий предок `cwd`) и EPERM с этим путём в выводе
|
|
195
|
+
* (`output`). Чтение другого закрытого пути (`~/.ssh/id_rsa`), отказ,
|
|
196
|
+
* который проверка пережила, и обычный провал тестов отказом среды не
|
|
197
|
+
* становятся: отказ среды не тратит попытку и останавливает очередь.
|
|
173
198
|
*/
|
|
174
|
-
export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation): {
|
|
199
|
+
export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation, output?: string, cwd?: string): {
|
|
175
200
|
path: string;
|
|
176
201
|
rule: string;
|
|
177
202
|
}[];
|