geloforge 0.6.0 → 0.9.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,214 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { createHash } from "node:crypto";
4
+ import { fileURLToPath } from "node:url";
5
+ import { createCheckpoint, listCheckpoints } from "./checkpoint.mjs";
6
+ import { captureEvidence } from "./evidence-capture.mjs";
7
+ import { assertSafeWithinRoot, atomicWriteFile, hasSecretContent, isForbiddenSecretPath } from "./path-safety.mjs";
8
+ import { loadProjectManifestAndState } from "./project-locator.mjs";
9
+ import { withProjectLock } from "./project-lock.mjs";
10
+ import { normalizeN8nId as normalizeId } from "./staging-evidence.mjs";
11
+ import { completeTask, createTask, getTask, listTasks, updateTask } from "./task-manager.mjs";
12
+
13
+ const MODULE_PATH = fileURLToPath(import.meta.url);
14
+ const MODE_FILE = "local-runtime/autonomous-mode.json";
15
+ export const AUDIT_CREATOR = "geloforge-autonomous";
16
+ const MAX_JSON_BYTES = 256 * 1024;
17
+ const VERIFICATION_TIMEOUT_MS = 3000;
18
+
19
+ export function readAutonomousMode(projectDir) {
20
+ const file = assertSafeWithinRoot(projectDir, MODE_FILE);
21
+ const stat = fs.lstatSync(file, { throwIfNoEntry: false });
22
+ if (!stat) return "off";
23
+ if (!stat.isFile() || stat.size > MAX_JSON_BYTES) {
24
+ throw new Error("Invalid autonomous mode file. Run geloforge autonomous off to reset regular files.");
25
+ }
26
+ let config;
27
+ try {
28
+ config = JSON.parse(fs.readFileSync(file, "utf8"));
29
+ } catch {
30
+ throw new Error("Cannot read autonomous mode. Run geloforge autonomous off to reset the file.");
31
+ }
32
+ if (typeof config?.enabled !== "boolean") {
33
+ throw new Error("Invalid autonomous mode setting. Run geloforge autonomous off to reset it.");
34
+ }
35
+ return config.enabled ? "on" : "off";
36
+ }
37
+
38
+ export function setAutonomousMode({ projectDir, harnessDir, enabled }) {
39
+ return withProjectLock(projectDir, () => {
40
+ loadProjectManifestAndState(projectDir, harnessDir);
41
+ const file = assertSafeWithinRoot(projectDir, MODE_FILE);
42
+ const stat = fs.lstatSync(file, { throwIfNoEntry: false });
43
+ if (stat && !stat.isFile()) throw new Error("Autonomous mode requires a regular settings file.");
44
+ atomicWriteFile(file, `${JSON.stringify({ enabled }, null, 2)}\n`);
45
+ return enabled ? "on" : "off";
46
+ });
47
+ }
48
+
49
+ export function findBlockedAudit(projectDir, blockedTaskIds) {
50
+ if (blockedTaskIds.length === 0) return null;
51
+ const owners = new Set(blockedTaskIds.map((taskId) => `${AUDIT_CREATOR}/${taskId}`));
52
+ return listCheckpoints({ projectDir }).checkpoints.find((item) =>
53
+ owners.has(item.created_by) && item.verification_evidence_ref === null
54
+ ) ?? null;
55
+ }
56
+
57
+ function inputPath(rawPath, label) {
58
+ if (typeof rawPath !== "string" || !/\.json$/i.test(rawPath) ||
59
+ path.win32.isAbsolute(rawPath) || path.posix.isAbsolute(rawPath) ||
60
+ isForbiddenSecretPath(rawPath) || hasSecretContent(rawPath)) {
61
+ throw new Error(`${label} must be a project-relative JSON file path.`);
62
+ }
63
+ return rawPath.replace(/\\/g, "/");
64
+ }
65
+
66
+ function readJsonInput(projectDir, relativePath, label) {
67
+ let raw;
68
+ try {
69
+ const target = assertSafeWithinRoot(projectDir, relativePath);
70
+ const stat = fs.lstatSync(target);
71
+ if (!stat.isFile() || stat.size > MAX_JSON_BYTES) throw new Error("Invalid file");
72
+ raw = fs.readFileSync(target);
73
+ if (raw.length > MAX_JSON_BYTES) throw new Error("File too large");
74
+ } catch {
75
+ throw new Error(`${label} is missing, unreadable, unsafe, or larger than 256 KiB. Use a regular local JSON file inside this project.`);
76
+ }
77
+ try {
78
+ return { data: JSON.parse(raw.toString("utf8").replace(/^\uFEFF/, "")), raw };
79
+ } catch {
80
+ throw new Error(`${label} is not valid JSON.`);
81
+ }
82
+ }
83
+
84
+ function readFailureEvent(projectDir, eventFile) {
85
+ const { data } = readJsonInput(projectDir, inputPath(eventFile, "--event"), "n8n failure event");
86
+ if (Array.isArray(data) && data.length !== 1) {
87
+ throw new Error("Supply a single n8n Error Trigger event per call.");
88
+ }
89
+ const event = Array.isArray(data) ? data[0] : data;
90
+ const workflowId = normalizeId(event?.workflow?.id);
91
+ const executionId = normalizeId(event?.execution?.id);
92
+ if (!workflowId || !executionId || typeof event.execution.error?.message !== "string" ||
93
+ !event.execution.error.message.trim()) {
94
+ throw new Error("Expected a saved n8n failure with workflow.id, execution.id, and execution.error.message.");
95
+ }
96
+ return { workflowId, executionId };
97
+ }
98
+
99
+ function verifyExecutionRecord(projectDir, recordPath, workflowId, executionId) {
100
+ const { data, raw } = readJsonInput(projectDir, inputPath(recordPath, "--execution"), "Execution record");
101
+ if (normalizeId(data?.id) !== executionId || normalizeId(data?.workflowId) !== workflowId) {
102
+ throw new Error("Execution record does not match the failure's workflow and execution IDs.");
103
+ }
104
+ if (data.status !== "error") throw new Error('Execution record must have status "error".');
105
+
106
+ // Preserve a short node label only. Raw errors, inputs, and payload bodies stay in the source files.
107
+ const rawNode = data.lastNodeExecuted || data.data?.resultData?.lastNodeExecuted;
108
+ const node = typeof rawNode === "string" ? rawNode.trim() : "";
109
+ const nodeLabel = /^[\p{L}\p{N} _()./-]{1,100}$/u.test(node) && !hasSecretContent(node)
110
+ ? `Last node: ${node}.`
111
+ : "Last node unavailable in the normalized evidence.";
112
+ const digest = createHash("sha256").update(raw).digest("hex");
113
+ return `Recorded failure matched workflow ${workflowId}, execution ${executionId}. ${nodeLabel} SHA-256: ${digest}.`;
114
+ }
115
+
116
+ export function stagingProgressPath(taskId) {
117
+ if (!/^TASK-\d{4}$/.test(taskId)) throw new Error("Invalid staging audit task ID.");
118
+ return `local-runtime/checkpoints/${taskId}-staging-audit.json`;
119
+ }
120
+
121
+ // The caller holds the project lock across lookup and allocation.
122
+ export function getOrCreateStagingTask({ projectDir, harnessDir, workflowId, executionId }) {
123
+ const title = `Audit n8n staging failure ${workflowId}/${executionId}`;
124
+ const project = { projectDir, harnessDir };
125
+ const existing = listTasks(project).tasks
126
+ .filter((task) => task.title === title)
127
+ .map((task) => getTask({ ...project, taskId: task.id }))
128
+ .find((task) => task.record.created_by === AUDIT_CREATOR);
129
+ const task = existing ?? createTask({
130
+ ...project, title, activate: true, createdBy: AUDIT_CREATOR,
131
+ assignedRole: "qa-security-reviewer", contextBudget: "quick",
132
+ objective: `Inspect saved staging execution ${executionId} for n8n workflow ${workflowId} and report evidence-based findings.`,
133
+ scopeIn: ["Inspect local staging execution evidence"],
134
+ scopeOut: ["Workflow changes", "Execution retries", "Customer messages"],
135
+ acceptanceCriteria: ["Verify the execution identity, recorded failure, and each cited finding reference."],
136
+ });
137
+ return { task, existing: Boolean(existing) };
138
+ }
139
+
140
+ /** Runs the first-pass audit of one delivered n8n staging failure using local files. */
141
+ export function auditStagingFailure({ projectDir, harnessDir, eventFile, executionFile }) {
142
+ return withProjectLock(projectDir, () => {
143
+ loadProjectManifestAndState(projectDir, harnessDir);
144
+ const mode = readAutonomousMode(projectDir);
145
+ const { workflowId, executionId } = readFailureEvent(projectDir, eventFile);
146
+ const result = { mode, workflowId, executionId, taskId: null, checkpointId: null, evidenceId: null, reused: false };
147
+ if (mode === "off") {
148
+ return {
149
+ ...result, status: "skipped",
150
+ nextAction: `Review workflow ${workflowId}, execution ${executionId} manually. Use geloforge recommend for project guidance.`,
151
+ };
152
+ }
153
+
154
+ const recordPath = executionFile === undefined ? null : inputPath(executionFile, "--execution");
155
+ const project = { projectDir, harnessDir };
156
+ const { task, existing } = getOrCreateStagingTask({ ...project, workflowId, executionId });
157
+ if (fs.existsSync(assertSafeWithinRoot(projectDir, stagingProgressPath(task.id)))) {
158
+ throw new Error("This task is managed by the staging worker. Resume it through autonomous watch.");
159
+ }
160
+ const taskOptions = { ...project, taskId: task.id };
161
+ const checkpointOwner = `${AUDIT_CREATOR}/${task.id}`;
162
+ const prior = existing && listCheckpoints(project).checkpoints.find((item) => item.created_by === checkpointOwner);
163
+ if (existing && task.record.status !== "active") {
164
+ return {
165
+ ...result, taskId: task.id, status: task.record.status, reused: true,
166
+ checkpointId: prior?.id ?? null, evidenceId: prior?.verification_evidence_ref ?? null,
167
+ nextAction: prior?.resume_instructions ?? `Inspect ${task.id} with geloforge task show --task ${task.id}.`,
168
+ };
169
+ }
170
+
171
+ let checkpoint = prior;
172
+ if (!checkpoint) {
173
+ const evidence = recordPath && captureEvidence({
174
+ ...taskOptions, name: "Verify saved n8n staging execution",
175
+ commandArgv: [process.execPath, MODULE_PATH, recordPath, workflowId, executionId],
176
+ displayCommand: `node "<geloforge-install>/core/autonomous-audit.mjs" ${JSON.stringify(recordPath)} ${workflowId} ${executionId}`,
177
+ timeoutMs: VERIFICATION_TIMEOUT_MS, linkVerifiedOnly: true,
178
+ });
179
+ const nextAction = evidence?.verified
180
+ ? `${evidence.outputExcerpt} Review the recorded failure in staging to determine the cause.`
181
+ : `${evidence?.record.checks[0].summary ?? "No saved staging execution record was supplied."} Obtain the saved error record for workflow ${workflowId}, execution ${executionId}, and confirm it before closing ${task.id}.`;
182
+ const saved = createCheckpoint({
183
+ ...project, createdBy: checkpointOwner,
184
+ evidenceRef: evidence?.verified ? evidence.id : null,
185
+ resumeInstructions: nextAction,
186
+ });
187
+ checkpoint = {
188
+ id: saved.checkpointId,
189
+ verification_evidence_ref: saved.record.verification_evidence_ref,
190
+ resume_instructions: saved.record.resume_instructions,
191
+ };
192
+ }
193
+
194
+ const evidenceId = checkpoint.verification_evidence_ref;
195
+ const updated = evidenceId
196
+ ? completeTask({ ...taskOptions, evidenceRefs: [evidenceId], requireEvidence: true })
197
+ : updateTask({ ...taskOptions, status: "blocked" });
198
+ return {
199
+ ...result, taskId: task.id, status: updated.status, reused: Boolean(existing),
200
+ checkpointId: checkpoint.id, evidenceId, nextAction: checkpoint.resume_instructions,
201
+ };
202
+ });
203
+ }
204
+
205
+ // A fixed local verifier is executed by evidence capture. Event data never chooses an executable.
206
+ if (process.argv[1] && path.resolve(process.argv[1]) === MODULE_PATH) {
207
+ const [recordPath, workflowId, executionId] = process.argv.slice(2);
208
+ try {
209
+ console.log(verifyExecutionRecord(process.cwd(), recordPath, workflowId, executionId));
210
+ } catch (err) {
211
+ console.error(err.message);
212
+ process.exitCode = 1;
213
+ }
214
+ }
@@ -12,6 +12,7 @@ import { validateAgainstSchema } from "./json-schema-lite.mjs";
12
12
  import { checkRecordSchemaVersion } from "./compatibility.mjs";
13
13
  import {
14
14
  assertSafeWithinRoot,
15
+ atomicWriteFile,
15
16
  hasSecretContent,
16
17
  isForbiddenSecretPath,
17
18
  walkNonSymlinkFiles,
@@ -25,6 +26,7 @@ const __filename = fileURLToPath(import.meta.url);
25
26
  const __dirname = path.dirname(__filename);
26
27
  const DEFAULT_HARNESS_DIR = path.resolve(__dirname, "..");
27
28
 
29
+ const LOCAL_CHECKPOINTS = "local-runtime/checkpoints";
28
30
  const ALLOWED_CHECKPOINT_STATUSES = new Set([
29
31
  "created",
30
32
  "verified",
@@ -178,7 +180,7 @@ export function createCheckpoint(options = {}) {
178
180
  }
179
181
 
180
182
  const explicitId = options.id ? String(options.id).trim().toUpperCase() : null;
181
- const searchDirs = Array.from(new Set([projectPaths.handoffs_dir, projectPaths.tasks_dir]));
183
+ const searchDirs = Array.from(new Set([projectPaths.handoffs_dir, projectPaths.tasks_dir, LOCAL_CHECKPOINTS]));
182
184
  const { id } = scanAndAllocateRecordId({
183
185
  projectDir,
184
186
  searchDirs,
@@ -186,7 +188,7 @@ export function createCheckpoint(options = {}) {
186
188
  explicitId,
187
189
  });
188
190
 
189
- const relPath = `${projectPaths.handoffs_dir}/${id}-checkpoint.yaml`;
191
+ const relPath = `${options.local ? LOCAL_CHECKPOINTS : projectPaths.handoffs_dir}/${id}-checkpoint.yaml`;
190
192
  if (isForbiddenSecretPath(relPath)) {
191
193
  throw new Error(`Refusing checkpoint destination path: ${relPath}`);
192
194
  }
@@ -195,7 +197,7 @@ export function createCheckpoint(options = {}) {
195
197
  throw new Error(`Checkpoint file already exists: ${relPath}`);
196
198
  }
197
199
 
198
- const nextStateRevision = (typeof state.state_revision === "number" ? state.state_revision : 0) + 1;
200
+ const nextStateRevision = (state.state_revision ?? 0) + (options.local ? 0 : 1);
199
201
  const stateRelPath = String(projectPaths.state || "brain/state/current.yaml").replace(/\\/g, "/");
200
202
 
201
203
  const checkpointSchema = loadCheckpointSchema(schemasDir);
@@ -242,7 +244,9 @@ export function createCheckpoint(options = {}) {
242
244
  throw new Error(`Updated state failed schema validation: ${stateCheck.errors.join("; ")}`);
243
245
  }
244
246
 
245
- if (!options.dryRun) {
247
+ if (!options.dryRun && options.local) {
248
+ atomicWriteFile(targetAbs, yamlText, { allowOverwrite: false });
249
+ } else if (!options.dryRun) {
246
250
  const stateAbs = assertSafeWithinRoot(projectDir, stateRelPath);
247
251
  runMultiFileTransaction(
248
252
  [
@@ -284,15 +288,15 @@ export function createCheckpoint(options = {}) {
284
288
  });
285
289
  }
286
290
 
287
- function scanCheckpointsInternal({ projectDir, schemasDir, compatConfig, projectPaths }) {
291
+ function scanCheckpointsInternal({ projectDir, schemasDir, compatConfig, projectPaths, projectId }) {
288
292
  const schema = loadCheckpointSchema(schemasDir);
289
- const searchDirs = Array.from(new Set([projectPaths.handoffs_dir, projectPaths.tasks_dir]));
293
+ const searchDirs = Array.from(new Set([projectPaths.handoffs_dir, projectPaths.tasks_dir, LOCAL_CHECKPOINTS]));
290
294
  const warnings = [];
291
295
  const checkpoints = [];
292
296
  const seenFiles = new Set();
293
297
 
294
298
  for (const relDir of searchDirs) {
295
- const absDir = path.join(projectDir, relDir);
299
+ const absDir = assertSafeWithinRoot(projectDir, relDir);
296
300
  const files = walkNonSymlinkFiles(
297
301
  projectDir,
298
302
  absDir,
@@ -327,6 +331,10 @@ function scanCheckpointsInternal({ projectDir, schemasDir, compatConfig, project
327
331
  warnings.push(`Checkpoint ${rel} failed schema check: ${res.errors.join("; ")}`);
328
332
  continue;
329
333
  }
334
+ if (data.project_id !== projectId) {
335
+ warnings.push(`Checkpoint ${rel} belongs to a different project.`);
336
+ continue;
337
+ }
330
338
  checkpoints.push({ relPath: rel, record: data });
331
339
  }
332
340
  }
@@ -349,7 +357,7 @@ export function listCheckpoints(options = {}) {
349
357
  if (typeof options.projectDir !== "string" || options.projectDir.trim().length === 0) {
350
358
  throw new Error("Missing required project directory (--project <dir>).");
351
359
  }
352
- const { projectDir, schemasDir, compatConfig, state, projectPaths } = loadProjectManifestAndState(
360
+ const { projectDir, schemasDir, compatConfig, manifest, state, projectPaths } = loadProjectManifestAndState(
353
361
  options.projectDir,
354
362
  harnessDir
355
363
  );
@@ -358,6 +366,7 @@ export function listCheckpoints(options = {}) {
358
366
  schemasDir,
359
367
  compatConfig,
360
368
  projectPaths,
369
+ projectId: manifest.project_id,
361
370
  });
362
371
 
363
372
  const statusFilter = options.status ? String(options.status).trim() : null;
@@ -399,7 +408,7 @@ export function getCheckpoint(options = {}) {
399
408
  if (typeof options.projectDir !== "string" || options.projectDir.trim().length === 0) {
400
409
  throw new Error("Missing required project directory (--project <dir>).");
401
410
  }
402
- const { projectDir, schemasDir, compatConfig, state, projectPaths } = loadProjectManifestAndState(
411
+ const { projectDir, schemasDir, compatConfig, manifest, state, projectPaths } = loadProjectManifestAndState(
403
412
  options.projectDir,
404
413
  harnessDir
405
414
  );
@@ -408,6 +417,7 @@ export function getCheckpoint(options = {}) {
408
417
  schemasDir,
409
418
  compatConfig,
410
419
  projectPaths,
420
+ projectId: manifest.project_id,
411
421
  });
412
422
 
413
423
  let found = null;
@@ -417,7 +427,7 @@ export function getCheckpoint(options = {}) {
417
427
  if (!found) {
418
428
  throw new Error(`Checkpoint "${targetId}" was not found or failed validation.`);
419
429
  }
420
- } else if (state?.last_checkpoint) {
430
+ } else if (state?.last_checkpoint && !options.newest) {
421
431
  found = checkpoints.find((c) => c.record.id === state.last_checkpoint) || checkpoints[0] || null;
422
432
  } else {
423
433
  found = checkpoints[0] || null;