@flowdular/sdk 0.1.0

package/packages/sandbox/src/server/diff.ts

@@ -0,0 +1,230 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+export type FileChange = 'created' | 'modified' | 'deleted';
+
+export interface DiffLine {
+	readonly type: 'context' | 'add' | 'del';
+	readonly text: string;
+	readonly oldLine: number | null;
+	readonly newLine: number | null;
+}
+
+export interface DiffHunk {
+	readonly header: string;
+	readonly lines: readonly DiffLine[];
+}
+
+export interface FileDiff {
+	readonly path: string;
+	readonly change: FileChange;
+	readonly additions: number;
+	readonly deletions: number;
+	readonly binary: boolean;
+	readonly truncated: boolean;
+	readonly hunks: readonly DiffHunk[];
+}
+
+const IGNORED = new Set(['node_modules', 'dist', '.git']);
+const MAX_DIFF_LINES = 4_000;
+const CONTEXT_LINES = 3;
+
+async function listTree(root: string, directory = root): Promise<string[]> {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const files: string[] = [];
+	for (const entry of entries) {
+		if (IGNORED.has(entry.name)) continue;
+		const path = join(directory, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) files.push(...(await listTree(root, path)));
+		else files.push(relative(root, path));
+	}
+	return files;
+}
+
+async function readIfPresent(path: string): Promise<string | null> {
+	try {
+		const info = await stat(path);
+		if (!info.isFile()) return null;
+		return await readFile(path, 'utf8');
+	} catch {
+		return null;
+	}
+}
+
+/* Longest common subsequence over lines. Files above the guard are reported as
+   changed without hunks so one generated lock file cannot stall the sandbox. */
+function lineDiff(
+	before: readonly string[],
+	after: readonly string[],
+): readonly DiffLine[] {
+	const rows = before.length;
+	const columns = after.length;
+	const table: number[][] = Array.from({ length: rows + 1 }, () =>
+		new Array<number>(columns + 1).fill(0),
+	);
+	for (let row = rows - 1; row >= 0; row -= 1) {
+		for (let column = columns - 1; column >= 0; column -= 1) {
+			table[row]![column] =
+				before[row] === after[column]
+					? table[row + 1]![column + 1]! + 1
+					: Math.max(table[row + 1]![column]!, table[row]![column + 1]!);
+		}
+	}
+	const lines: DiffLine[] = [];
+	let row = 0;
+	let column = 0;
+	while (row < rows && column < columns) {
+		if (before[row] === after[column]) {
+			lines.push({
+				type: 'context',
+				text: before[row]!,
+				oldLine: row + 1,
+				newLine: column + 1,
+			});
+			row += 1;
+			column += 1;
+		} else if (table[row + 1]![column]! >= table[row]![column + 1]!) {
+			lines.push({
+				type: 'del',
+				text: before[row]!,
+				oldLine: row + 1,
+				newLine: null,
+			});
+			row += 1;
+		} else {
+			lines.push({
+				type: 'add',
+				text: after[column]!,
+				oldLine: null,
+				newLine: column + 1,
+			});
+			column += 1;
+		}
+	}
+	while (row < rows) {
+		lines.push({
+			type: 'del',
+			text: before[row]!,
+			oldLine: row + 1,
+			newLine: null,
+		});
+		row += 1;
+	}
+	while (column < columns) {
+		lines.push({
+			type: 'add',
+			text: after[column]!,
+			oldLine: null,
+			newLine: column + 1,
+		});
+		column += 1;
+	}
+	return lines;
+}
+
+function groupHunks(lines: readonly DiffLine[]): readonly DiffHunk[] {
+	const changedIndexes = lines
+		.map((line, index) => (line.type === 'context' ? -1 : index))
+		.filter((index) => index >= 0);
+	if (changedIndexes.length === 0) return [];
+
+	const hunks: DiffHunk[] = [];
+	let start = Math.max(0, changedIndexes[0]! - CONTEXT_LINES);
+	let end = Math.min(lines.length - 1, changedIndexes[0]! + CONTEXT_LINES);
+	for (const index of changedIndexes.slice(1)) {
+		if (index - end <= CONTEXT_LINES * 2) {
+			end = Math.min(lines.length - 1, index + CONTEXT_LINES);
+			continue;
+		}
+		hunks.push(buildHunk(lines, start, end));
+		start = Math.max(0, index - CONTEXT_LINES);
+		end = Math.min(lines.length - 1, index + CONTEXT_LINES);
+	}
+	hunks.push(buildHunk(lines, start, end));
+	return hunks;
+}
+
+function buildHunk(
+	lines: readonly DiffLine[],
+	start: number,
+	end: number,
+): DiffHunk {
+	const slice = lines.slice(start, end + 1);
+	const firstOld = slice.find((line) => line.oldLine !== null)?.oldLine ?? 0;
+	const firstNew = slice.find((line) => line.newLine !== null)?.newLine ?? 0;
+	const oldCount = slice.filter((line) => line.type !== 'add').length;
+	const newCount = slice.filter((line) => line.type !== 'del').length;
+	return {
+		header: `@@ -${firstOld},${oldCount} +${firstNew},${newCount} @@`,
+		lines: slice,
+	};
+}
+
+export async function diffFile(
+	beforePath: string,
+	afterPath: string,
+	path: string,
+): Promise<FileDiff | null> {
+	const before = await readIfPresent(beforePath);
+	const after = await readIfPresent(afterPath);
+	if (before === null && after === null) return null;
+	if (before === after) return null;
+
+	const change: FileChange =
+		before === null ? 'created' : after === null ? 'deleted' : 'modified';
+	const beforeLines = before === null ? [] : before.split('\n');
+	const afterLines = after === null ? [] : after.split('\n');
+	const binary = [before, after].some(
+		(content) => content !== null && content.includes(String.fromCharCode(0)),
+	);
+	const truncated =
+		beforeLines.length + afterLines.length > MAX_DIFF_LINES || binary;
+
+	if (truncated) {
+		return {
+			path,
+			change,
+			additions: afterLines.length,
+			deletions: beforeLines.length,
+			binary,
+			truncated: true,
+			hunks: [],
+		};
+	}
+	const lines = lineDiff(beforeLines, afterLines);
+	return {
+		path,
+		change,
+		additions: lines.filter((line) => line.type === 'add').length,
+		deletions: lines.filter((line) => line.type === 'del').length,
+		binary: false,
+		truncated: false,
+		hunks: groupHunks(lines),
+	};
+}
+
+export async function diffTrees(
+	basePath: string,
+	currentPath: string,
+): Promise<readonly FileDiff[]> {
+	const paths = new Set([
+		...(await listTree(basePath)),
+		...(await listTree(currentPath)),
+	]);
+	const diffs: FileDiff[] = [];
+	for (const path of [...paths].sort()) {
+		const diff = await diffFile(
+			join(basePath, path),
+			join(currentPath, path),
+			path,
+		);
+		if (diff) diffs.push(diff);
+	}
+	return diffs;
+}

package/packages/sandbox/src/server/gates.ts

@@ -0,0 +1,388 @@
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspectAutoReview } from './auto-review.ts';
+import { checkDeclaredDependencies } from './dependencies.ts';
+import {
+	modulePathOf,
+	type SandboxSession,
+	type SessionModule,
+	type SessionPaths,
+} from './sessions.ts';
+
+export type GateId =
+	| 'spec-schema'
+	| 'module-schema'
+	| 'dependencies'
+	| 'typecheck'
+	| 'tests'
+	| 'format'
+	| 'auto-review';
+
+export interface GateResult {
+	readonly id: GateId;
+	/* The draft module directory a module-level gate ran in; absent for a gate
+	   that checks the whole session workspace. */
+	readonly module?: string;
+	readonly status: 'passed' | 'failed' | 'skipped';
+	readonly durationMs: number;
+	readonly command: string;
+	readonly output: string;
+}
+
+interface GateDefinition {
+	readonly id: GateId;
+	readonly summary: string;
+	/* Workspace gates run once per session; module gates run per draft module. */
+	readonly scope: 'workspace' | 'module';
+	command(context: GateContext): {
+		readonly command: string;
+		readonly args: readonly string[];
+		readonly cwd: string;
+	} | null;
+	/* A gate the sandbox answers itself, without spawning a process. */
+	inspect?(context: GateContext): Promise<{
+		readonly passed: boolean;
+		readonly output: string;
+	}>;
+}
+
+interface GateContext {
+	readonly workspaceRoot: string;
+	readonly paths: SessionPaths;
+	readonly session: SandboxSession;
+	readonly module: SessionModule;
+	readonly modulePath: string;
+	readonly signal?: AbortSignal | undefined;
+}
+
+/* Output keeps its head and its tail: the head names what failed (the test
+   list, the first compiler errors), the tail carries the summary. */
+const HEAD_LIMIT = 10_000;
+const TAIL_LIMIT = 6_000;
+const GATE_TIMEOUT_MS = 5 * 60 * 1000;
+
+/* The only commands the sandbox may run. Agents never execute anything: they
+   request a gate by id and the orchestrator runs this fixed list. */
+const GATE_DEFINITIONS: readonly GateDefinition[] = [
+	{
+		id: 'auto-review',
+		summary: 'Review evidence matches the current module contents.',
+		scope: 'module',
+		command: () => null,
+		inspect: (context) => inspectAutoReview(context.paths, context.module),
+	},
+	{
+		id: 'spec-schema',
+		summary: 'Validate the module specification against its schema.',
+		scope: 'workspace',
+		command: (context) => ({
+			command: 'pnpm',
+			args: [
+				'--dir',
+				context.workspaceRoot,
+				'--silent',
+				'flowdular',
+				'spec',
+				'validate',
+				'--all',
+				'--json',
+				'--root',
+				context.paths.workspace,
+			],
+			cwd: context.workspaceRoot,
+		}),
+	},
+	{
+		id: 'module-schema',
+		summary: 'Validate the module manifest and registry references.',
+		scope: 'workspace',
+		command: (context) => ({
+			command: 'pnpm',
+			args: [
+				'--dir',
+				context.workspaceRoot,
+				'--silent',
+				'flowdular',
+				'module',
+				'validate',
+				'--json',
+				'--root',
+				context.paths.workspace,
+				/* The other modules in the session are manifest-only copies for the
+				   registry graph; file-level checks run against the drafts only. */
+				'--module',
+				context.session.modules.map((entry) => entry.id).join(','),
+			],
+			cwd: context.workspaceRoot,
+		}),
+	},
+	{
+		id: 'dependencies',
+		summary: 'Every imported package is declared by the module manifest.',
+		scope: 'module',
+		command: () => null,
+		inspect: async (context) => {
+			const report = await checkDeclaredDependencies(context.modulePath);
+			return {
+				passed: report.missing.length === 0,
+				output:
+					report.missing.length === 0
+						? `${report.imported.length} imported packages, all declared.`
+						: `Undeclared packages: ${report.missing.join(', ')}. Add them to package.json dependencies; the session installs what package.json declares and nothing else, and the ejected module would fail without them.`,
+			};
+		},
+	},
+	{
+		id: 'typecheck',
+		summary: 'Typecheck the module with the workspace compiler.',
+		scope: 'module',
+		command: (context) => ({
+			command: join(context.modulePath, 'node_modules', '.bin', 'tsrx-tsc'),
+			args: ['--noEmit', '-p', 'tsconfig.json'],
+			cwd: context.modulePath,
+		}),
+	},
+	{
+		id: 'tests',
+		summary: 'Run the module test suite.',
+		scope: 'module',
+		command: (context) => ({
+			command: join(context.modulePath, 'node_modules', '.bin', 'vitest'),
+			args: ['run', '--passWithNoTests=false'],
+			cwd: context.modulePath,
+		}),
+	},
+	{
+		id: 'format',
+		summary: 'Check formatting with the workspace Prettier configuration.',
+		scope: 'module',
+		command: (context) => ({
+			command: join(context.workspaceRoot, 'node_modules', '.bin', 'prettier'),
+			args: ['--check', '.'],
+			cwd: context.modulePath,
+		}),
+	},
+];
+
+export const GATE_IDS = GATE_DEFINITIONS.map((gate) => gate.id);
+
+/* Formatting is mechanical, so the sandbox fixes it on request instead of
+   spending an agent turn on it. It is still the orchestrator running the
+   command, never the model. */
+export async function formatDirectory(
+	workspaceRoot: string,
+	directory: string,
+): Promise<GateResult> {
+	const command = join(workspaceRoot, 'node_modules', '.bin', 'prettier');
+	const startedAt = Date.now();
+	try {
+		await access(command);
+	} catch {
+		return {
+			id: 'format',
+			status: 'skipped',
+			durationMs: 0,
+			command,
+			output: 'Prettier is not installed in this workspace.',
+		};
+	}
+	/* An operator asked for this directly, so it is not tied to a turn and has
+	   no turn signal to observe. */
+	const result = await runProcess(command, ['--write', '.'], directory);
+	return {
+		id: 'format',
+		status: result.code === 0 ? 'passed' : 'failed',
+		durationMs: Date.now() - startedAt,
+		command: `${command} --write .`,
+		output: result.output.trim(),
+	};
+}
+
+export async function formatSession(context: {
+	readonly workspaceRoot: string;
+	readonly paths: SessionPaths;
+	readonly session: SandboxSession;
+}): Promise<readonly GateResult[]> {
+	const results: GateResult[] = [];
+	for (const module of context.session.modules) {
+		results.push({
+			...(await formatDirectory(
+				context.workspaceRoot,
+				modulePathOf(context.paths, module.directory),
+			)),
+			module: module.directory,
+		});
+	}
+	return results;
+}
+
+export function isGateId(value: string): value is GateId {
+	return (GATE_IDS as readonly string[]).includes(value);
+}
+
+function runProcess(
+	command: string,
+	args: readonly string[],
+	cwd: string,
+	signal?: AbortSignal | undefined,
+): Promise<{ code: number | null; output: string }> {
+	return new Promise((resolvePromise) => {
+		if (signal?.aborted) {
+			resolvePromise({ code: null, output: 'The gate was stopped.' });
+			return;
+		}
+		const child = spawn(command, [...args], {
+			cwd,
+			env: { ...process.env, CI: 'true', FORCE_COLOR: '0' },
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+		let head = '';
+		let tail = '';
+		let omitted = 0;
+		const append = (chunk: string) => {
+			if (head.length < HEAD_LIMIT) {
+				const room = HEAD_LIMIT - head.length;
+				head += chunk.slice(0, room);
+				chunk = chunk.slice(room);
+				if (!chunk) return;
+			}
+			const kept = (tail + chunk).slice(-TAIL_LIMIT);
+			omitted += tail.length + chunk.length - kept.length;
+			tail = kept;
+		};
+		const output = () =>
+			omitted > 0
+				? `${head}\n[... ${omitted} characters omitted ...]\n${tail}`
+				: head + tail;
+		child.stdout.setEncoding('utf8');
+		child.stderr.setEncoding('utf8');
+		child.stdout.on('data', append);
+		child.stderr.on('data', append);
+		const timer = setTimeout(() => {
+			append('\nThe gate exceeded its time budget and was stopped.');
+			child.kill('SIGKILL');
+		}, GATE_TIMEOUT_MS);
+		timer.unref();
+		const stop = () => {
+			append('\nThe turn was stopped, so the gate was stopped with it.');
+			child.kill('SIGKILL');
+		};
+		signal?.addEventListener('abort', stop, { once: true });
+		const settle = (value: { code: number | null; output: string }) => {
+			clearTimeout(timer);
+			signal?.removeEventListener('abort', stop);
+			resolvePromise(value);
+		};
+		child.on('error', (error) => {
+			settle({ code: null, output: `${output()}\n${error.message}` });
+		});
+		child.on('close', (code) => {
+			settle({ code, output: output() });
+		});
+	});
+}
+
+async function runGate(
+	definition: GateDefinition,
+	context: GateContext,
+): Promise<GateResult> {
+	const id = definition.id;
+	const module =
+		definition.scope === 'module' ? { module: context.module.directory } : {};
+	const startedAt = Date.now();
+	if (definition.inspect) {
+		const result = await definition.inspect(context);
+		return {
+			id,
+			...module,
+			status: result.passed ? 'passed' : 'failed',
+			durationMs: Date.now() - startedAt,
+			command: definition.summary,
+			output: result.output,
+		};
+	}
+	const invocation = definition.command(context);
+	if (!invocation) {
+		return {
+			id,
+			...module,
+			status: 'skipped',
+			durationMs: 0,
+			command: '',
+			output: 'This gate does not apply to the session.',
+		};
+	}
+	const printable = `${invocation.command} ${invocation.args.join(' ')}`;
+	if (invocation.command.includes('/')) {
+		try {
+			await access(invocation.command);
+		} catch {
+			return {
+				id,
+				...module,
+				status: 'skipped',
+				durationMs: 0,
+				command: printable,
+				output: `${invocation.command} is not installed in this session workspace. The module's package.json must declare it as a devDependency.`,
+			};
+		}
+	}
+	const result = await runProcess(
+		invocation.command,
+		invocation.args,
+		invocation.cwd,
+		context.signal,
+	);
+	return {
+		id,
+		...module,
+		status: result.code === 0 ? 'passed' : 'failed',
+		durationMs: Date.now() - startedAt,
+		command: printable,
+		output: result.output.trim(),
+	};
+}
+
+export interface RunGatesInput {
+	readonly workspaceRoot: string;
+	readonly paths: SessionPaths;
+	readonly session: SandboxSession;
+	readonly gates: readonly GateId[];
+	/* The draft modules to gate; every module of the session by default. A turn
+	   passes the ones that changed, so an untouched module is not re-checked. */
+	readonly modules?: readonly SessionModule[];
+	/* Stopping a turn must stop its gates. Without this a spawned gate outlives
+	   the abort and the session stays busy until the gate's own budget expires. */
+	readonly signal?: AbortSignal | undefined;
+}
+
+/* Workspace gates run once; module gates run once per draft module, so a
+   session that touches several modules reports each of them. */
+export async function runGates(
+	input: RunGatesInput,
+): Promise<readonly GateResult[]> {
+	const results: GateResult[] = [];
+	const modules = input.modules ?? input.session.modules;
+	for (const id of input.gates) {
+		const definition = GATE_DEFINITIONS.find((gate) => gate.id === id)!;
+		const targets =
+			definition.scope === 'workspace' ? modules.slice(0, 1) : modules;
+		for (const module of targets) {
+			/* A stopped turn runs no further gates. The one already spawned is
+			   killed through the same signal. */
+			if (input.signal?.aborted) return results;
+			results.push(
+				await runGate(definition, {
+					workspaceRoot: input.workspaceRoot,
+					paths: input.paths,
+					session: input.session,
+					module,
+					modulePath: modulePathOf(input.paths, module.directory),
+					signal: input.signal,
+				}),
+			);
+		}
+	}
+	return results;
+}