@dfsramos/foreman 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { consoleUrl, parseCommand, USAGE } from './cli-args.js';
+import { loadConfig } from './config.js';
+import { isAlive, readLivePid, removePidFile } from './pidfile.js';
+import { LOG_FILE } from './paths.js';
+/** Start renames a log larger than this to foreman.log.1, replacing the previous one. */
+const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+const START_TIMEOUT_MS = 15_000;
+/** `status` exits with this when foreman is not running, as LSB init scripts do. */
+const EXIT_NOT_RUNNING = 3;
+async function fetchStatus(url) {
+    try {
+        const response = await fetch(`${url}/api/status`, { signal: AbortSignal.timeout(2000) });
+        return response.ok ? (await response.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tail(file, lines) {
+    return fs.readFileSync(file, 'utf8').split('\n').slice(-lines - 1).join('\n');
+}
+async function start(env, url) {
+    const running = readLivePid(env.dataDir);
+    if (running !== null) {
+        console.log(`foreman is already running (pid ${running}): ${url}`);
+        return 0;
+    }
+    removePidFile(env.dataDir);
+    fs.mkdirSync(env.dataDir, { recursive: true });
+    const log = path.join(env.dataDir, LOG_FILE);
+    if (fs.existsSync(log) && fs.statSync(log).size > LOG_ROTATE_BYTES)
+        fs.renameSync(log, `${log}.1`);
+    const fd = fs.openSync(log, 'a');
+    const startedAt = fs.statSync(log).size;
+    const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', fileURLToPath(import.meta.url), 'run'], {
+        detached: true,
+        stdio: ['ignore', fd, fd],
+        env: process.env,
+    });
+    fs.closeSync(fd);
+    let exited = false;
+    child.on('exit', () => {
+        exited = true;
+    });
+    child.unref();
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline && !exited) {
+        // The pid file appears only once the console is listening, so it tells this foreman from another on the same port.
+        if (readLivePid(env.dataDir) === child.pid && (await fetchStatus(url))) {
+            console.log(`foreman started (pid ${child.pid}): ${url}`);
+            console.log(`Log: ${log}`);
+            return 0;
+        }
+        await sleep(250);
+    }
+    const output = fs.readFileSync(log, 'utf8').slice(startedAt).trimEnd().split('\n').slice(-20).join('\n');
+    console.error(exited ? 'foreman exited while starting:' : `foreman did not answer on ${url} within ${START_TIMEOUT_MS / 1000} seconds:`);
+    if (output)
+        console.error(output);
+    console.error(`Log: ${log}`);
+    return 1;
+}
+async function stop(env, url, now) {
+    const pid = readLivePid(env.dataDir);
+    if (pid === null) {
+        console.log('foreman is not running');
+        return 0;
+    }
+    process.kill(pid, now ? 'SIGINT' : 'SIGTERM');
+    let reported = '';
+    while (isAlive(pid)) {
+        const status = await fetchStatus(url);
+        const runs = status?.activeRuns ?? [];
+        const message = runs.length > 0
+            ? `Waiting for ${runs.length} run(s) in progress: ${runs.map((run) => run.identifier).join(', ')}.${now ? '' : ' Use foreman stop --now to abort them.'}`
+            : '';
+        if (message && message !== reported)
+            console.log(message);
+        reported = message;
+        await sleep(reported ? 2000 : 250);
+    }
+    console.log('foreman stopped');
+    return 0;
+}
+async function status(env, url) {
+    const pid = readLivePid(env.dataDir);
+    if (pid === null) {
+        console.log('foreman is not running');
+        return EXIT_NOT_RUNNING;
+    }
+    const view = await fetchStatus(url);
+    if (!view) {
+        console.log(`foreman is running (pid ${pid}) but not answering on ${url}`);
+        return 1;
+    }
+    console.log(`foreman is running (pid ${pid}): ${url}`);
+    console.log(`Data: ${env.dataDir}`);
+    console.log(view.projects.length === 0 ? 'No projects yet.' : 'Projects:');
+    for (const project of view.projects) {
+        console.log(`  ${project.name}: ${project.state}${project.lastError ? ` (${project.lastError})` : ''}`);
+    }
+    if (view.activeRuns.length > 0) {
+        console.log('Runs in progress:');
+        for (const run of view.activeRuns) {
+            console.log(`  ${run.identifier}${run.projectName ? ` (${run.projectName})` : ''}: ${run.agent}, ${run.step}`);
+        }
+    }
+    return 0;
+}
+function logs(env, follow, lines) {
+    const log = path.join(env.dataDir, LOG_FILE);
+    if (!fs.existsSync(log)) {
+        console.error(`There is no log yet at ${log}. foreman start writes it; foreman run prints to the terminal instead.`);
+        return Promise.resolve(1);
+    }
+    if (!follow) {
+        process.stdout.write(`${tail(log, lines).trimEnd()}\n`);
+        return Promise.resolve(0);
+    }
+    return new Promise((resolve) => {
+        spawn('tail', ['-n', String(lines), '-F', log], { stdio: 'inherit' }).on('exit', (code) => resolve(code ?? 0));
+    });
+}
+async function main() {
+    if (process.platform === 'win32') {
+        console.error('foreman runs on Linux, macOS and WSL. On Windows, install it inside WSL.');
+        return 1;
+    }
+    const command = parseCommand(process.argv.slice(2));
+    if ('error' in command) {
+        console.error(`${command.error}\n\n${USAGE}`);
+        return 2;
+    }
+    if (command.command === 'help') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (command.command === 'version') {
+        const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(pkg.version);
+        return 0;
+    }
+    let env;
+    try {
+        env = loadConfig();
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        return 1;
+    }
+    const url = consoleUrl(env.host, env.port);
+    switch (command.command) {
+        case 'run': {
+            const { runDaemon } = await import('./daemon.js');
+            try {
+                await runDaemon(env);
+            }
+            catch (error) {
+                if (error.code !== 'EADDRINUSE')
+                    throw error;
+                console.error(`Port ${env.port} on ${env.host} is already in use. Set PORT in the environment or in ${path.join(env.dataDir, '.env')}.`);
+                return 1;
+            }
+            return -1; // The daemon keeps the process alive and exits it itself.
+        }
+        case 'start':
+            return start(env, url);
+        case 'stop':
+            return stop(env, url, command.now);
+        case 'status':
+            return status(env, url);
+        case 'logs':
+            return logs(env, command.follow, command.lines);
+    }
+}
+const code = await main();
+if (code >= 0)
+    process.exit(code);

package/dist/config.js

@@ -0,0 +1,102 @@
+import os from 'node:os';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { z } from 'zod';
+import { defaultDataDir, ENV_FILE } from './paths.js';
+export const DEFAULT_ALLOWED_TOOLS = 'Read,Glob,Grep,Edit,Write,Skill,Task,TodoWrite,Bash(git:*),Bash(gh pr:*),Bash(npm:*),Bash(npx:*),Bash(node:*)';
+export const POLL_INTERVAL_RANGE = { min: 10, max: 86_400 };
+export const AGENT_TIMEOUT_RANGE = { min: 1, max: 1440 };
+const stateName = z.string().trim().min(1, 'must not be empty');
+const pollInterval = z.coerce
+    .number()
+    .int('must be a whole number')
+    .min(POLL_INTERVAL_RANGE.min, `must be at least ${POLL_INTERVAL_RANGE.min}`)
+    .max(POLL_INTERVAL_RANGE.max, `must be at most ${POLL_INTERVAL_RANGE.max}`);
+const timeoutMinutes = z.coerce
+    .number()
+    .int('must be a whole number')
+    .min(AGENT_TIMEOUT_RANGE.min, `must be at least ${AGENT_TIMEOUT_RANGE.min}`)
+    .max(AGENT_TIMEOUT_RANGE.max, `must be at most ${AGENT_TIMEOUT_RANGE.max}`);
+// Projects live in the database. The process itself needs only where to listen and where to keep
+// its data; the remaining variables are read once, to seed the first project and the claude agent.
+const envSchema = z.object({
+    DATA_DIR: z.string().optional(),
+    HOST: z.string().default('127.0.0.1'),
+    PORT: z.coerce.number().int().min(1).max(65535).default(4310),
+    CLAUDE_BIN: z.string().default('claude'),
+    AGENT_ALLOWED_TOOLS: z.string().default(DEFAULT_ALLOWED_TOOLS).transform(parseToolList),
+    LINEAR_API_KEY: z.string().optional(),
+    LINEAR_TEAM_ID: z.string().optional(),
+    LINEAR_PROJECT_ID: z.string().optional(),
+    LINEAR_TARGET_STATE: stateName.default('Todo'),
+    LINEAR_IN_PROGRESS_STATE: stateName.default('In Progress'),
+    LINEAR_SUCCESS_STATE: stateName.default('In Review'),
+    POLL_INTERVAL_SECONDS: pollInterval.default(60),
+    REPO_PATH: z.string().optional(),
+    WORKTREE_ROOT: z.string().optional(),
+    AGENT_TIMEOUT_MINUTES: timeoutMinutes.default(30),
+    AUTOSTART: z.enum(['true', 'false']).default('false'),
+});
+export function parseToolList(value) {
+    return value
+        .split(',')
+        .map((tool) => tool.trim())
+        .filter((tool) => tool.length > 0);
+}
+const hostDefaults = () => ({ platform: process.platform, home: os.homedir() });
+/**
+ * Loads the configuration the way the command does: the data directory comes from the environment
+ * (or the platform default), then `.env` in that directory fills in what the environment leaves unset.
+ * A DATA_DIR in that `.env` is ignored, since the file could only be found once the directory was known.
+ * The values are written into `env` (by default `process.env`), so agents started by foreman inherit them,
+ * and DATA_DIR is set to the resolved absolute path, so a child foreman process uses the same directory.
+ */
+export function loadConfig(env = process.env, cwd = process.cwd(), defaults = hostDefaults()) {
+    const { dataDir } = loadEnv(env, cwd, defaults);
+    const fromFile = {};
+    dotenv.config({ path: path.join(dataDir, ENV_FILE), processEnv: fromFile, quiet: true });
+    for (const [key, value] of Object.entries(fromFile)) {
+        if (key !== 'DATA_DIR' && env[key] === undefined)
+            env[key] = value;
+    }
+    env.DATA_DIR = dataDir;
+    return loadEnv(env, cwd, defaults);
+}
+export function loadEnv(env, cwd = process.cwd(), defaults = hostDefaults()) {
+    // An empty value (`WORKTREE_ROOT=`) means "not set".
+    const present = Object.fromEntries(Object.entries(env).filter(([, value]) => value !== undefined && value.trim() !== ''));
+    const parsed = envSchema.safeParse(present);
+    if (!parsed.success) {
+        const lines = parsed.error.issues.map((issue) => `  ${issue.path.join('.')}: ${issue.message}`);
+        throw new Error(`Invalid configuration:\n${lines.join('\n')}`);
+    }
+    const e = parsed.data;
+    const dataDir = e.DATA_DIR ? path.resolve(cwd, e.DATA_DIR) : defaultDataDir(defaults.platform, env, defaults.home);
+    const legacy = e.LINEAR_API_KEY && e.LINEAR_TEAM_ID && e.LINEAR_PROJECT_ID && e.REPO_PATH
+        ? {
+            apiKey: e.LINEAR_API_KEY,
+            teamId: e.LINEAR_TEAM_ID,
+            projectId: e.LINEAR_PROJECT_ID,
+            targetState: e.LINEAR_TARGET_STATE,
+            inProgressState: e.LINEAR_IN_PROGRESS_STATE,
+            successState: e.LINEAR_SUCCESS_STATE,
+            pollIntervalSeconds: e.POLL_INTERVAL_SECONDS,
+            repoPath: path.resolve(cwd, e.REPO_PATH),
+            worktreeRoot: e.WORKTREE_ROOT ? path.resolve(cwd, e.WORKTREE_ROOT) : path.join(dataDir, 'worktrees'),
+            agentTimeoutMinutes: e.AGENT_TIMEOUT_MINUTES,
+            autostart: e.AUTOSTART === 'true',
+        }
+        : null;
+    return {
+        dataDir,
+        host: e.HOST,
+        port: e.PORT,
+        claudeBin: e.CLAUDE_BIN,
+        agentAllowedTools: e.AGENT_ALLOWED_TOOLS.length > 0 ? e.AGENT_ALLOWED_TOOLS : parseToolList(DEFAULT_ALLOWED_TOOLS),
+        legacy,
+    };
+}
+/** The environment as it may be logged: without the legacy project's API key. */
+export function redactEnv(env) {
+    return { ...env, legacy: env.legacy ? { ...env.legacy, apiKey: '[set]' } : null };
+}

package/dist/daemon.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createAvailability, loadAgentsConfig, resolveAgents } from './agent/config.js';
+import { runAgent } from './agent/process.js';
+import { ADAPTERS, checkSignIn } from './agent/registry.js';
+import { openDb } from './db.js';
+import { createGitApi } from './git/worktree.js';
+import { removePidFile, writePidFile } from './pidfile.js';
+import { migrateLegacy } from './projects.js';
+import { Runner } from './runner.js';
+import { buildApp } from './server/app.js';
+import { getSourceType } from './sources/registry.js';
+/**
+ * SIGTERM lets the runs in progress finish; SIGINT, or any signal during that wait, aborts them;
+ * a signal while aborting exits at once.
+ */
+export function nextShutdownAction(phase, signal) {
+    if (phase === 'aborting')
+        return 'exit';
+    if (phase === 'draining')
+        return 'abort';
+    return signal === 'SIGTERM' ? 'drain' : 'abort';
+}
+/** Aborting stops each agent within a bounded time, but nothing may keep the process alive indefinitely. */
+const ABORT_DEADLINE_MS = 30_000;
+/** Runs foreman in this process until a signal stops it. */
+export async function runDaemon(env) {
+    fs.mkdirSync(env.dataDir, { recursive: true });
+    const db = openDb(path.join(env.dataDir, 'foreman.db'));
+    const migrated = migrateLegacy(db, env);
+    if (migrated) {
+        console.log(`Created the project "${migrated.name}" from the settings in the environment; they can now be removed from .env.`);
+    }
+    const availability = createAvailability();
+    const runner = new Runner({
+        db,
+        git: createGitApi(),
+        runAgent,
+        getProjects: () => db.listProjects(),
+        createSource: (project) => {
+            const type = getSourceType(project.sourceType);
+            if (!type)
+                throw new Error(`Unknown source type "${project.sourceType}"`);
+            return type.create(project.sourceSettings, { repoPath: project.repoPath, dataDir: env.dataDir });
+        },
+        getAgents: () => resolveAgents(loadAgentsConfig(db, env), availability),
+        checkSignIn: (agent) => checkSignIn(agent.adapter, agent.bin),
+    });
+    const app = buildApp({ runner, db, env, availability });
+    let phase = 'running';
+    let closing = null;
+    // A drain that turns into an abort settles twice; the server and database close once.
+    const close = () => (closing ??= app.close().then(() => db.close()));
+    const settleAndExit = async () => {
+        try {
+            await runner.settled();
+            await close();
+            process.exit(0);
+        }
+        catch (error) {
+            console.error('Error during shutdown:', error);
+            process.exit(1);
+        }
+    };
+    const onSignal = (signal) => {
+        const action = nextShutdownAction(phase, signal);
+        if (action === 'exit') {
+            console.error(`Received ${signal} again; exiting immediately.`);
+            process.exit(1);
+        }
+        runner.stopAll();
+        if (action === 'drain') {
+            phase = 'draining';
+            const running = runner.getStatus().activeRunIds.length;
+            console.log(running > 0
+                ? `Received ${signal}; projects stopped, waiting for ${running} run(s) in progress. Send SIGINT to abort them.`
+                : `Received ${signal}; shutting down.`);
+        }
+        else {
+            phase = 'aborting';
+            const aborted = runner.abortAll();
+            console.log(`Received ${signal}; ${aborted > 0 ? `aborting ${aborted} run(s) in progress` : 'shutting down'}.`);
+            setTimeout(() => {
+                console.error('Shutdown timed out; exiting.');
+                process.exit(1);
+            }, ABORT_DEADLINE_MS).unref();
+        }
+        void settleAndExit();
+    };
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+    process.on('SIGINT', () => onSignal('SIGINT'));
+    await availability.refresh(loadAgentsConfig(db, env));
+    for (const adapter of ADAPTERS) {
+        const probe = availability.get(adapter.id);
+        console.log(`Agent ${adapter.id}: ${probe?.available ? `available (${probe.version ?? 'unknown version'})` : `not available (${probe?.error ?? 'not probed'})`}`);
+    }
+    await runner.recoverInterrupted();
+    await app.listen({ host: env.host, port: env.port });
+    writePidFile(env.dataDir, process.pid);
+    process.on('exit', () => removePidFile(env.dataDir));
+    console.log(`Foreman is listening on http://${env.host}:${env.port}`);
+    const projects = db.listProjects();
+    if (projects.length === 0)
+        console.log('No projects yet; add one on the Projects tab.');
+    for (const project of projects) {
+        const started = project.autostart && runner.startProject(project.id);
+        console.log(`Project "${project.name}": ${started ? 'started' : 'stopped'}`);
+    }
+}