ai-engineering-loop 1.12.0 → 1.13.0

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.
@@ -0,0 +1,250 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { validateFindingLedger } = require('./orchestration.js');
6
+ const { validateVerificationBundle } = require('./gates.js');
7
+ const {
8
+ getCurrentRun,
9
+ getGitRevision,
10
+ loadRun,
11
+ runsDir
12
+ } = require('./run-state.js');
13
+
14
+ const ARTIFACT_TYPES = Object.freeze({
15
+ verification: 'verification',
16
+ findings: 'findings',
17
+ delivery: 'delivery'
18
+ });
19
+
20
+ function artifactError(message, code = 'ARTIFACT_TOOL_FAILED') {
21
+ const error = new Error(message);
22
+ error.code = code;
23
+ return error;
24
+ }
25
+
26
+ function resolveRun(rootDir, runId) {
27
+ if (runId) return loadRun(rootDir, runId);
28
+ const current = getCurrentRun(rootDir);
29
+ if (!current) throw artifactError('No current Run. Pass --run <id>.', 'NO_CURRENT_RUN');
30
+ return current;
31
+ }
32
+
33
+ function assertNoSymlinkPath(rootDir, targetPath) {
34
+ const root = path.resolve(rootDir);
35
+ const target = path.resolve(targetPath);
36
+ const relative = path.relative(root, target);
37
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
38
+ throw artifactError('Artifact path must stay inside the repository.', 'UNSAFE_ARTIFACT_PATH');
39
+ }
40
+ let current = root;
41
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
42
+ current = path.join(current, segment);
43
+ try {
44
+ if (fs.lstatSync(current).isSymbolicLink()) {
45
+ throw artifactError(`Artifact path crosses a symlink: ${path.relative(root, current)}`, 'UNSAFE_ARTIFACT_PATH');
46
+ }
47
+ } catch (cause) {
48
+ if (cause.code === 'ENOENT') return;
49
+ throw cause;
50
+ }
51
+ }
52
+ }
53
+
54
+ function templateFor(type, run, rootDir) {
55
+ const common = {
56
+ schemaVersion: 1,
57
+ runId: run.runId,
58
+ _templateOnly: true,
59
+ _instructions: 'Template only. Replace placeholders with observed evidence before validation or gating.'
60
+ };
61
+ const diffHash = run.artifacts?.diff?.sha256 || '__FILL_AFTER_GATE_MAKER__';
62
+
63
+ if (type === 'verification') {
64
+ return {
65
+ ...common,
66
+ gitRevision: getGitRevision(rootDir),
67
+ diffHash,
68
+ commands: [{
69
+ command: '__FILL_WITH_COMMAND__',
70
+ executionIdentity: '__FILL_WITH_PROCESS_OR_AGENT_ID__',
71
+ startTime: '__FILL_WITH_ISO_TIMESTAMP__',
72
+ endTime: '__FILL_WITH_ISO_TIMESTAMP__',
73
+ exitCode: null,
74
+ stdout: '',
75
+ timeoutStatus: 'NOT_RUN'
76
+ }]
77
+ };
78
+ }
79
+ if (type === 'findings') {
80
+ return {
81
+ ...common,
82
+ diffHash,
83
+ findings: [{
84
+ id: '',
85
+ axis: 'spec',
86
+ location: '',
87
+ failureScenario: '',
88
+ evidence: '',
89
+ severity: '',
90
+ validity: '',
91
+ disposition: ''
92
+ }]
93
+ };
94
+ }
95
+ if (type === 'delivery') {
96
+ return {
97
+ ...common,
98
+ destination: '',
99
+ summary: '',
100
+ humanApproved: false
101
+ };
102
+ }
103
+ throw artifactError(`Unknown artifact type '${type}'. Use ${Object.keys(ARTIFACT_TYPES).join('|')}.`, 'UNKNOWN_ARTIFACT_TYPE');
104
+ }
105
+
106
+ function scaffoldArtifact(rootDir, { type, runId } = {}) {
107
+ if (!Object.hasOwn(ARTIFACT_TYPES, type)) {
108
+ throw artifactError(`Unknown artifact type '${type || ''}'. Use ${Object.keys(ARTIFACT_TYPES).join('|')}.`, 'UNKNOWN_ARTIFACT_TYPE');
109
+ }
110
+ const run = resolveRun(rootDir, runId);
111
+ const filePath = path.join(runsDir(rootDir), run.runId, `${type}.template.json`);
112
+ const directory = path.dirname(filePath);
113
+ const repositoryPath = path.resolve(rootDir);
114
+ const realRoot = fs.realpathSync(rootDir);
115
+ assertNoSymlinkPath(repositoryPath, directory);
116
+ const realDirectory = fs.realpathSync(directory);
117
+ if (!realDirectory.startsWith(`${realRoot}${path.sep}`)) {
118
+ throw artifactError('Artifact template path escapes the repository.', 'UNSAFE_ARTIFACT_PATH');
119
+ }
120
+ let descriptor;
121
+ try {
122
+ descriptor = fs.openSync(filePath, 'wx', 0o600);
123
+ } catch (cause) {
124
+ if (cause.code === 'EEXIST') {
125
+ throw artifactError(`Template already exists: ${path.relative(rootDir, filePath)}. It was left unchanged.`, 'ARTIFACT_EXISTS');
126
+ }
127
+ throw cause;
128
+ }
129
+ try {
130
+ fs.writeFileSync(descriptor, `${JSON.stringify(templateFor(type, run, rootDir), null, 2)}\n`);
131
+ fs.fsyncSync(descriptor);
132
+ } finally {
133
+ fs.closeSync(descriptor);
134
+ }
135
+ return {
136
+ type,
137
+ runId: run.runId,
138
+ path: path.relative(rootDir, filePath).split(path.sep).join('/')
139
+ };
140
+ }
141
+
142
+ function resolveArtifactFile(rootDir, requestedPath) {
143
+ if (!requestedPath || path.isAbsolute(requestedPath)) {
144
+ throw artifactError('Artifact path must be repository-relative.', 'UNSAFE_ARTIFACT_PATH');
145
+ }
146
+ const root = fs.realpathSync(rootDir);
147
+ const absolute = path.resolve(root, requestedPath);
148
+ const relative = path.relative(root, absolute);
149
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
150
+ throw artifactError('Artifact path must stay inside the repository.', 'UNSAFE_ARTIFACT_PATH');
151
+ }
152
+ assertNoSymlinkPath(root, absolute);
153
+ const stat = fs.lstatSync(absolute);
154
+ if (stat.isSymbolicLink() || !stat.isFile()) {
155
+ throw artifactError('Artifact must be a regular file, not a symlink.', 'UNSAFE_ARTIFACT_PATH');
156
+ }
157
+ const realFile = fs.realpathSync(absolute);
158
+ if (!realFile.startsWith(`${root}${path.sep}`)) {
159
+ throw artifactError('Artifact path escapes the repository through a symlink.', 'UNSAFE_ARTIFACT_PATH');
160
+ }
161
+ return absolute;
162
+ }
163
+
164
+ function inferArtifactType(file, explicitType) {
165
+ if (explicitType && Object.hasOwn(ARTIFACT_TYPES, explicitType)) return explicitType;
166
+ const base = path.basename(file).replace(/\.template(?=\.json$)/, '');
167
+ const inferred = base.endsWith('.json') ? base.slice(0, -'.json'.length) : base;
168
+ if (Object.hasOwn(ARTIFACT_TYPES, inferred)) return inferred;
169
+ throw artifactError(
170
+ `Unable to infer artifact type from '${path.basename(file)}'. Pass --type ${Object.keys(ARTIFACT_TYPES).join('|')}.`,
171
+ 'UNKNOWN_ARTIFACT_TYPE'
172
+ );
173
+ }
174
+
175
+ function metadataErrors(document, run) {
176
+ const errors = [];
177
+ if (document.schemaVersion !== 1) errors.push('schemaVersion must be 1');
178
+ if (document.runId !== run.runId) errors.push(`runId must be ${run.runId}`);
179
+ return errors;
180
+ }
181
+
182
+ function validateDelivery(document, run) {
183
+ const errors = metadataErrors(document, run);
184
+ if (!String(document.destination || '').trim()) errors.push('destination is required');
185
+ if (!String(document.summary || '').trim()) errors.push('summary is required');
186
+ if (run.mode === 'ASSISTED' && document.humanApproved !== true) {
187
+ errors.push('humanApproved must be true for ASSISTED delivery');
188
+ }
189
+ return errors;
190
+ }
191
+
192
+ function validateArtifactDocument(type, document, run, rootDir) {
193
+ if (document?._templateOnly === true) {
194
+ return ['This is a scaffold, not evidence. Fill it with observed facts and remove _templateOnly before validation.'];
195
+ }
196
+ if (!document || typeof document !== 'object' || Array.isArray(document)) {
197
+ return ['Artifact must be a JSON object.'];
198
+ }
199
+ if (type === 'verification') {
200
+ const diffHash = run.artifacts?.diff?.sha256;
201
+ if (!diffHash) return ['Maker diff has not passed its gate yet.'];
202
+ try {
203
+ const result = validateVerificationBundle(document, run, diffHash, getGitRevision(rootDir));
204
+ return result.errors;
205
+ } catch (cause) {
206
+ return [cause.message];
207
+ }
208
+ }
209
+ if (type === 'findings') {
210
+ const errors = metadataErrors(document, run);
211
+ if (!run.artifacts?.diff?.sha256) errors.push('Maker diff has not passed its gate yet.');
212
+ if (document.diffHash !== run.artifacts?.diff?.sha256) errors.push('diffHash does not match the gated Maker diff.');
213
+ const result = validateFindingLedger(document);
214
+ if (!result.valid) errors.push(result.reason);
215
+ return errors;
216
+ }
217
+ return validateDelivery(document, run);
218
+ }
219
+
220
+ function validateArtifactFile(rootDir, { file, type } = {}) {
221
+ const filePath = resolveArtifactFile(rootDir, file);
222
+ const inferredType = inferArtifactType(file, type);
223
+ let document;
224
+ try {
225
+ document = JSON.parse(fs.readFileSync(filePath, 'utf8'));
226
+ } catch (cause) {
227
+ return {
228
+ valid: false,
229
+ type: inferredType,
230
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
231
+ errors: [`Invalid JSON: ${cause.message}`]
232
+ };
233
+ }
234
+ const run = resolveRun(rootDir, document?.runId);
235
+ const errors = validateArtifactDocument(inferredType, document, run, rootDir);
236
+ return {
237
+ valid: errors.length === 0,
238
+ type: inferredType,
239
+ runId: run.runId,
240
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
241
+ errors,
242
+ note: 'Validation checks artifact content only; the owning gate still enforces stage readiness, freshness, and explicit approvals.'
243
+ };
244
+ }
245
+
246
+ module.exports = {
247
+ ARTIFACT_TYPES,
248
+ scaffoldArtifact,
249
+ validateArtifactFile
250
+ };
@@ -1,5 +1,138 @@
1
1
  'use strict';
2
2
 
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { getCurrentRun, loadRun } = require('./run-state.js');
7
+
8
+ function claimedVsRealityError(message, code = 'CLAIMED_VS_REALITY_FAILED') {
9
+ const error = new Error(message);
10
+ error.code = code;
11
+ return error;
12
+ }
13
+
14
+ function markdownCell(value) {
15
+ return String(value ?? '')
16
+ .replace(/\|/g, '/')
17
+ .replace(/\s+/g, ' ')
18
+ .trim();
19
+ }
20
+
21
+ function frozenGoal(rootDir, run) {
22
+ const artifact = run.artifacts?.goalContract;
23
+ if (!artifact?.path || !artifact.sha256) {
24
+ throw claimedVsRealityError('The Goal Contract has not passed the Goal gate.', 'GOAL_NOT_FROZEN');
25
+ }
26
+ const root = fs.realpathSync(rootDir);
27
+ const goalPath = path.resolve(root, artifact.path);
28
+ const relative = path.relative(root, goalPath);
29
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
30
+ throw claimedVsRealityError('Frozen Goal Contract path escapes the repository.', 'UNSAFE_GOAL_PATH');
31
+ }
32
+ assertNoSymlinkPath(root, goalPath);
33
+ const stat = fs.lstatSync(goalPath);
34
+ if (!stat.isFile() || stat.isSymbolicLink()) {
35
+ throw claimedVsRealityError('Frozen Goal Contract must be a regular file.', 'UNSAFE_GOAL_PATH');
36
+ }
37
+ const content = fs.readFileSync(goalPath);
38
+ const hash = crypto.createHash('sha256').update(content).digest('hex');
39
+ if (hash !== artifact.sha256) {
40
+ throw claimedVsRealityError('Frozen Goal Contract changed after its gate.', 'STALE_GOAL');
41
+ }
42
+ let goal;
43
+ try {
44
+ goal = JSON.parse(content.toString('utf8'));
45
+ } catch (cause) {
46
+ throw claimedVsRealityError(`Frozen Goal Contract is invalid JSON: ${cause.message}`, 'INVALID_GOAL');
47
+ }
48
+ if (goal.runId !== run.runId || !Array.isArray(goal.acceptanceCriteria) || goal.acceptanceCriteria.length === 0) {
49
+ throw claimedVsRealityError('Frozen Goal Contract has no criteria for this Run.', 'INVALID_GOAL');
50
+ }
51
+ return goal;
52
+ }
53
+
54
+ function assertNoSymlinkPath(root, targetPath) {
55
+ const relative = path.relative(root, targetPath);
56
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
57
+ throw claimedVsRealityError('Output path must stay inside the repository.', 'UNSAFE_OUTPUT_PATH');
58
+ }
59
+ let current = root;
60
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
61
+ current = path.join(current, segment);
62
+ try {
63
+ if (fs.lstatSync(current).isSymbolicLink()) {
64
+ throw claimedVsRealityError(`Repository path crosses a symlink: ${path.relative(root, current)}`, 'UNSAFE_PATH');
65
+ }
66
+ } catch (cause) {
67
+ if (cause.code === 'ENOENT') return;
68
+ throw cause;
69
+ }
70
+ }
71
+ }
72
+
73
+ function renderClaimedVsRealityTemplate(goal) {
74
+ const lines = [
75
+ '# Claimed vs Reality',
76
+ '',
77
+ '> Generated from the frozen Goal Contract. Fill Claimed and Reality only after implementation and verification. Reality must cite observed command output; this template is not verification evidence.',
78
+ '',
79
+ '| AC | Claimed | Reality from command log |',
80
+ '|---|---|---|'
81
+ ];
82
+ for (const criterion of goal.acceptanceCriteria) {
83
+ const evidence = markdownCell(criterion.evidenceRequired);
84
+ const failures = (criterion.failureCases || []).map(markdownCell).filter(Boolean).join('; ');
85
+ const description = [
86
+ `${criterion.id}: ${markdownCell(criterion.statement)}`,
87
+ evidence ? `Evidence: ${evidence}` : '',
88
+ failures ? `Failure cases: ${failures}` : ''
89
+ ].filter(Boolean).join(' — ');
90
+ lines.push(`| ${markdownCell(description)} | | |`);
91
+ }
92
+ return `${lines.join('\n')}\n`;
93
+ }
94
+
95
+ function createClaimedVsRealityTemplate(rootDir, { runId, outputPath } = {}) {
96
+ const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
97
+ if (!run) throw claimedVsRealityError('No current Run. Pass --run <id>.', 'NO_CURRENT_RUN');
98
+ const goal = frozenGoal(rootDir, run);
99
+ const root = fs.realpathSync(rootDir);
100
+ const requestedPath = outputPath || '.ai-engineering-loop/tasks/claimed-vs-reality.md';
101
+ if (path.isAbsolute(requestedPath)) {
102
+ throw claimedVsRealityError('Output path must be repository-relative.', 'UNSAFE_OUTPUT_PATH');
103
+ }
104
+ const filePath = path.resolve(root, requestedPath);
105
+ const relative = path.relative(root, filePath);
106
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
107
+ throw claimedVsRealityError('Output path must stay inside the repository.', 'UNSAFE_OUTPUT_PATH');
108
+ }
109
+ assertNoSymlinkPath(root, path.dirname(filePath));
110
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
111
+ const realParent = fs.realpathSync(path.dirname(filePath));
112
+ if (realParent !== root && !realParent.startsWith(`${root}${path.sep}`)) {
113
+ throw claimedVsRealityError('Output path escapes the repository through a symlink.', 'UNSAFE_OUTPUT_PATH');
114
+ }
115
+ let descriptor;
116
+ try {
117
+ descriptor = fs.openSync(filePath, 'wx', 0o600);
118
+ } catch (cause) {
119
+ if (cause.code === 'EEXIST') {
120
+ throw claimedVsRealityError(
121
+ `Refusing to overwrite ${relative}. Choose --output <new-file> to preserve existing evidence.`,
122
+ 'OUTPUT_EXISTS'
123
+ );
124
+ }
125
+ throw cause;
126
+ }
127
+ try {
128
+ fs.writeFileSync(descriptor, renderClaimedVsRealityTemplate(goal));
129
+ fs.fsyncSync(descriptor);
130
+ } finally {
131
+ fs.closeSync(descriptor);
132
+ }
133
+ return { runId: run.runId, path: relative.split(path.sep).join('/') };
134
+ }
135
+
3
136
  function parseClaimedVsReality(markdown) {
4
137
  const rows = [];
5
138
  if (!markdown || !String(markdown).trim()) return { rows };
@@ -32,6 +165,7 @@ function readyForDa(markdown) {
32
165
  }
33
166
 
34
167
  module.exports = {
168
+ createClaimedVsRealityTemplate,
35
169
  parseClaimedVsReality,
36
170
  readyForDa
37
171
  };
@@ -35,9 +35,11 @@ const SENSITIVE_NAMES = [
35
35
  /\.(?:pem|key|p12|pfx|jks)$/i
36
36
  ];
37
37
 
38
- function contextError(message, code = 'UNSAFE_CONTEXT') {
38
+ function contextError(message, code = 'UNSAFE_CONTEXT', details = [], budget = null) {
39
39
  const err = new Error(message);
40
40
  err.code = code;
41
+ if (details.length) err.details = details;
42
+ if (budget) err.budget = budget;
41
43
  return err;
42
44
  }
43
45
 
@@ -95,10 +97,15 @@ function redactSecrets(input) {
95
97
  replace(/\bAKIA[A-Z0-9]{16}\b/g, 'aws-access-key', '[REDACTED AWS ACCESS KEY]');
96
98
  replace(/\bsk-(?:live-|test-)?[A-Za-z0-9_-]{8,}\b/g, 'api-token', '[REDACTED API TOKEN]');
97
99
  replace(
98
- /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
100
+ /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
99
101
  'key-value-secret',
100
102
  (_match, prefix) => `${prefix}[REDACTED]`
101
103
  );
104
+ replace(
105
+ /(^|[^\w-])(--?(?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|authorization)\s+)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi,
106
+ 'key-value-secret',
107
+ (_match, boundary, prefix) => `${boundary}${prefix}[REDACTED]`
108
+ );
102
109
 
103
110
  return { text, categories: [...categories].sort() };
104
111
  }
@@ -149,6 +156,7 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
149
156
  }
150
157
 
151
158
  const entries = [];
159
+ const budgetEntries = [];
152
160
  let totalBytes = 0;
153
161
  let estimatedTokens = 0;
154
162
  for (const requested of uniqueFiles) {
@@ -157,17 +165,67 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
157
165
  if (raw.includes(0)) throw contextError(`Binary context is blocked: ${requested}`, 'BINARY_CONTEXT');
158
166
 
159
167
  const remaining = limits.maxTotalBytes - totalBytes;
160
- if (remaining <= 0) throw contextError(`${stage} context exceeds its byte budget`, 'CONTEXT_BYTE_LIMIT');
168
+ if (remaining <= 0) {
169
+ const budget = {
170
+ stage,
171
+ reviewProfile,
172
+ maxTotalBytes: limits.maxTotalBytes,
173
+ requestedBytes: totalBytes + raw.length,
174
+ files: [...budgetEntries, {
175
+ path: safe.relative,
176
+ sourceBytes: raw.length,
177
+ includedBytes: 0,
178
+ estimatedTokens: 0,
179
+ truncated: true
180
+ }]
181
+ };
182
+ throw contextError(
183
+ `${stage} context exceeds its byte budget (${limits.maxTotalBytes.toLocaleString()}-byte limit; ${budget.requestedBytes.toLocaleString()} requested)`,
184
+ 'CONTEXT_BYTE_LIMIT',
185
+ budget.files.map((entry) =>
186
+ `${entry.path}: ${entry.estimatedTokens.toLocaleString()} estimated tokens, ${entry.includedBytes.toLocaleString()}/${entry.sourceBytes.toLocaleString()} bytes included`
187
+ ),
188
+ budget
189
+ );
190
+ }
161
191
  const allowedBytes = Math.min(raw.length, limits.maxFileBytes, remaining);
162
192
  const source = raw.subarray(0, allowedBytes).toString('utf8');
163
193
  const redacted = redactSecrets(source);
164
194
  const tokens = estimateTokens(redacted.text);
165
195
  if (estimatedTokens + tokens > limits.maxEstimatedTokens) {
166
- throw contextError(`${stage} context exceeds its estimated token budget`, 'CONTEXT_TOKEN_LIMIT');
196
+ const files = [...budgetEntries, {
197
+ path: safe.relative,
198
+ sourceBytes: raw.length,
199
+ includedBytes: allowedBytes,
200
+ estimatedTokens: tokens,
201
+ truncated: allowedBytes < raw.length
202
+ }];
203
+ const budget = {
204
+ stage,
205
+ reviewProfile,
206
+ maxEstimatedTokens: limits.maxEstimatedTokens,
207
+ requestedTokens: estimatedTokens + tokens,
208
+ files
209
+ };
210
+ throw contextError(
211
+ `${stage} context exceeds its estimated token budget (${limits.maxEstimatedTokens.toLocaleString()}-token limit; ${budget.requestedTokens.toLocaleString()} requested)`,
212
+ 'CONTEXT_TOKEN_LIMIT',
213
+ files.map((entry) =>
214
+ `${entry.path}: ${entry.estimatedTokens.toLocaleString()} estimated tokens, ${entry.includedBytes.toLocaleString()}/${entry.sourceBytes.toLocaleString()} bytes included${entry.truncated ? ' (truncated)' : ''}`
215
+ ),
216
+ budget
217
+ );
167
218
  }
168
219
 
169
220
  totalBytes += allowedBytes;
170
221
  estimatedTokens += tokens;
222
+ budgetEntries.push({
223
+ path: safe.relative,
224
+ sourceBytes: raw.length,
225
+ includedBytes: allowedBytes,
226
+ estimatedTokens: tokens,
227
+ truncated: allowedBytes < raw.length
228
+ });
171
229
  entries.push({
172
230
  path: safe.relative,
173
231
  sourceSha256: sha256(raw),
package/lib/sync-hosts.js CHANGED
@@ -173,6 +173,28 @@ function isSymlink(dest) {
173
173
  }
174
174
  }
175
175
 
176
+ function findSymlinkAncestor(home, destination) {
177
+ const homePath = path.resolve(home);
178
+ const destinationPath = path.resolve(destination);
179
+ const relative = path.relative(homePath, destinationPath);
180
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
181
+
182
+ let current = homePath;
183
+ const candidates = [];
184
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
185
+ current = path.join(current, segment);
186
+ candidates.push(current);
187
+ }
188
+ for (const candidate of candidates) {
189
+ try {
190
+ if (fs.lstatSync(candidate).isSymbolicLink()) return candidate;
191
+ } catch (error) {
192
+ if (error.code !== 'ENOENT') throw error;
193
+ }
194
+ }
195
+ return null;
196
+ }
197
+
176
198
  function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } = {}) {
177
199
  const results = [];
178
200
  for (const group of hostFileMap(home)) {
@@ -193,8 +215,14 @@ function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } =
193
215
  results.push({ ...item, action: 'skip', reason: 'src-missing' });
194
216
  continue;
195
217
  }
196
- if (isSymlink(file.dest)) {
197
- results.push({ ...item, action: 'skip', reason: 'symlink' });
218
+ const symlinkPath = findSymlinkAncestor(home, file.dest);
219
+ if (symlinkPath) {
220
+ const isDestinationSymlink = path.resolve(symlinkPath) === path.resolve(file.dest);
221
+ results.push({
222
+ ...item,
223
+ action: 'skip',
224
+ reason: isDestinationSymlink ? 'symlink' : 'symlink-ancestor'
225
+ });
198
226
  continue;
199
227
  }
200
228
  if (file.mode === 'update-if-exists' && !destExists(file.dest)) {
@@ -222,8 +250,25 @@ function applyHostSync({ packageRoot: root = packageRoot(), home = homeDir(), dr
222
250
  continue;
223
251
  }
224
252
  if (!dryRun) {
253
+ if (findSymlinkAncestor(home, item.dest)) {
254
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
255
+ continue;
256
+ }
225
257
  fs.mkdirSync(path.dirname(item.dest), { recursive: true });
226
- fs.writeFileSync(item.dest, item.content);
258
+ if (findSymlinkAncestor(home, item.dest)) {
259
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
260
+ continue;
261
+ }
262
+ const flags = fs.constants.O_WRONLY
263
+ | fs.constants.O_CREAT
264
+ | fs.constants.O_TRUNC
265
+ | (fs.constants.O_NOFOLLOW || 0);
266
+ const descriptor = fs.openSync(item.dest, flags, 0o600);
267
+ try {
268
+ fs.writeFileSync(descriptor, item.content);
269
+ } finally {
270
+ fs.closeSync(descriptor);
271
+ }
227
272
  }
228
273
  applied.push({ ...item, content: undefined, dryRun });
229
274
  }