@refleet-it/runner 0.1.186

package/dist/fleet/loop.js

@@ -0,0 +1,128 @@
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { detectAgents } from '../detect.js';
+import { FleetApi } from './api.js';
+import { executeJob } from './execute.js';
+import { createGitRunner } from './git.js';
+import { claimAndRunJob } from './job.js';
+import { createLogger } from './log.js';
+function positiveInt(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function commaList(value) {
+    return (value ?? '')
+        .split(',')
+        .map(item => item.trim())
+        .filter(item => '' !== item);
+}
+function shortHostname() {
+    const name = hostname().split('.')[0];
+    return name && '' !== name ? name : 'local-runner';
+}
+/**
+ * The Docker image pins WORKSPACE_CACHE_DIR to /workspace/cache (its mounted volume);
+ * an npm install has no such mount, so it defaults to the XDG cache dir — the same
+ * ~/.cache convention the login config already follows with ~/.config.
+ */
+function defaultCacheDir(env) {
+    const xdgCacheHome = env.XDG_CACHE_HOME;
+    const base = xdgCacheHome && '' !== xdgCacheHome ? xdgCacheHome : join(homedir(), '.cache');
+    return join(base, 'refleet', 'workspace');
+}
+export function fleetOptionsFromEnv(env, credentials) {
+    return {
+        apiUrl: credentials.apiUrl,
+        apiKey: credentials.apiKey,
+        runnerName: env.RUNNER_NAME && '' !== env.RUNNER_NAME ? env.RUNNER_NAME : shortHostname(),
+        heartbeatIntervalSeconds: positiveInt(env.HEARTBEAT_INTERVAL_SECONDS, 30),
+        pollIntervalSeconds: positiveInt(env.POLL_INTERVAL_SECONDS, 10),
+        cacheDir: env.WORKSPACE_CACHE_DIR && '' !== env.WORKSPACE_CACHE_DIR ? env.WORKSPACE_CACHE_DIR : defaultCacheDir(env),
+        cacheMaxSizeMb: positiveInt(env.WORKSPACE_CACHE_MAX_SIZE_MB, 5120),
+        availableModels: {
+            claude: commaList(env.CLAUDE_AVAILABLE_MODELS),
+            kiro: commaList(env.KIRO_AVAILABLE_MODELS),
+        },
+    };
+}
+/**
+ * One identity per detected engine, each registering as its own Runner
+ * (`<name>-<engine>`) scoped to just that engine — see
+ * DoctrineRunnerJobRepository::CLAIM_NEXT_SQL, which filters claims by engine. A host
+ * with both claude and kiro shows up as two independent Runners instead of one that
+ * silently mixes both.
+ */
+export function identityFor(options, engine) {
+    return {
+        name: `${options.runnerName}-${engine}`,
+        supportedModes: ['ai'],
+        supportedEngines: [engine],
+        supportedModels: options.availableModels[engine] ?? [],
+    };
+}
+export function sleep(ms, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        }
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+/** Heartbeats and claims until `signal` aborts; a job in progress is finished first. */
+export async function pollLoop(deps, timing, signal, sleepFn = sleep, now = Date.now) {
+    const heartbeatMs = timing.heartbeatIntervalSeconds * 1000;
+    let lastHeartbeat = null;
+    deps.log(`polling for jobs every ${String(timing.pollIntervalSeconds)}s`);
+    while (!signal.aborted) {
+        if (null === lastHeartbeat || now() - lastHeartbeat >= heartbeatMs) {
+            await deps.api.heartbeat(deps.identity);
+            lastHeartbeat = now();
+        }
+        await claimAndRunJob(deps);
+        await sleepFn(timing.pollIntervalSeconds * 1000, signal);
+    }
+}
+export class FleetStartupError extends Error {
+}
+/**
+ * Detects the installed agent CLIs, registers one Runner per engine and polls until
+ * `signal` aborts. Rejects as soon as any engine's loop dies of an unexpected error
+ * (Docker's `restart: unless-stopped` or a systemd unit brings the whole process
+ * back), rather than silently continuing with fewer runners than were detected.
+ */
+export async function runFleet(options, signal, deps = {}) {
+    const env = deps.env ?? process.env;
+    const startupLog = createLogger(options.runnerName, deps.logWrite);
+    const detected = (deps.detect ?? detectAgents)();
+    if (0 === detected.length) {
+        throw new FleetStartupError('no supported agent CLI (claude/kiro-cli) found on PATH');
+    }
+    startupLog(`detected agent CLIs: ${detected.map(agent => agent.engine).join(' ')}`);
+    if (detected.some(agent => 'claude' === agent.engine) && !env.ANTHROPIC_API_KEY) {
+        startupLog('WARNING: claude was detected but ANTHROPIC_API_KEY is not set — claude-engine jobs will fail until it is.');
+    }
+    const git = deps.git ?? createGitRunner();
+    const loops = detected.map(agent => {
+        const identity = identityFor(options, agent.engine);
+        const log = createLogger(identity.name, deps.logWrite);
+        const workspace = { cacheDir: options.cacheDir, maxSizeMb: options.cacheMaxSizeMb, git, log };
+        const jobDeps = {
+            api: new FleetApi(options.apiUrl, options.apiKey, log, deps.fetchFn),
+            identity,
+            workspace,
+            execute: deps.execute ?? executeJob,
+            log,
+            fetchFn: deps.fetchFn,
+        };
+        log(`registering as ${identity.name} against ${options.apiUrl}`);
+        return pollLoop(jobDeps, options, signal);
+    });
+    await Promise.all(loops);
+}

package/dist/fleet/workspace.js

@@ -0,0 +1,124 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitAuthConfig } from './git.js';
+import { createMergeRequest } from './gitlab.js';
+const LAST_USED_MARKER = '.slipway-last-used';
+function directorySizeBytes(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += directorySizeBytes(path);
+        }
+        else if (entry.isFile()) {
+            try {
+                total += statSync(path).size;
+            }
+            catch {
+                // deleted between readdir and stat — a size estimate is all the cap needs
+            }
+        }
+    }
+    return total;
+}
+export function cacheSizeMb(cacheDir) {
+    return Math.ceil(directorySizeBytes(cacheDir) / (1024 * 1024));
+}
+function touchMarker(repoDir) {
+    const marker = join(repoDir, LAST_USED_MARKER);
+    if (existsSync(marker)) {
+        const now = new Date();
+        utimesSync(marker, now, now);
+    }
+    else {
+        writeFileSync(marker, '');
+    }
+}
+function markerMtime(repoDir) {
+    const marker = join(repoDir, LAST_USED_MARKER);
+    if (!existsSync(marker)) {
+        touchMarker(repoDir);
+    }
+    return statSync(marker).mtimeMs;
+}
+/**
+ * Per-project checkout cache: a long-lived runner reuses one working copy per project
+ * (fetch + hard reset instead of a full clone on every job), bounded by total size
+ * rather than project count — least-recently-used checkouts go first once the cap is
+ * hit. Keyed by GitLab externalId alone since one runner talks to one GitLab instance.
+ */
+export function evictLruUntilUnderCap(workspace) {
+    if (!existsSync(workspace.cacheDir)) {
+        return;
+    }
+    while (cacheSizeMb(workspace.cacheDir) >= workspace.maxSizeMb) {
+        const checkouts = readdirSync(workspace.cacheDir, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => join(workspace.cacheDir, entry.name));
+        if (0 === checkouts.length) {
+            return;
+        }
+        const oldest = checkouts.reduce((a, b) => (markerMtime(b) < markerMtime(a) ? b : a));
+        workspace.log(`workspace cache over ${String(workspace.maxSizeMb)}MB, evicting ${oldest}`);
+        rmSync(oldest, { recursive: true, force: true });
+    }
+}
+function excludeMarkerFromGit(repoDir) {
+    const excludeFile = join(repoDir, '.git', 'info', 'exclude');
+    const existing = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf8') : '';
+    if (existing.split('\n').includes(LAST_USED_MARKER)) {
+        return;
+    }
+    mkdirSync(join(repoDir, '.git', 'info'), { recursive: true });
+    appendFileSync(excludeFile, `${LAST_USED_MARKER}\n`);
+}
+/** Returns the ready-to-use working directory; throws (GitError) when any git step fails. */
+export async function syncRepo(workspace, credentials, project) {
+    const repoDir = join(workspace.cacheDir, project.externalId);
+    const auth = gitAuthConfig(credentials.accessToken);
+    if (existsSync(join(repoDir, '.git'))) {
+        workspace.log(`reusing cached checkout for ${project.path}`);
+        await workspace.git([...auth, 'fetch', '--prune', 'origin'], repoDir);
+        await workspace.git(['checkout', '-f', project.defaultBranch], repoDir);
+        await workspace.git(['reset', '--hard', `origin/${project.defaultBranch}`], repoDir);
+        await workspace.git(['clean', '-fdx'], repoDir);
+    }
+    else {
+        mkdirSync(workspace.cacheDir, { recursive: true });
+        evictLruUntilUnderCap(workspace);
+        workspace.log(`cloning ${project.path} (first use on this runner)`);
+        const cloneUrl = `${credentials.baseUrl.replace(/\/+$/, '')}/${project.path}.git`;
+        await workspace.git([...auth, 'clone', '--origin', 'origin', cloneUrl, repoDir]);
+    }
+    touchMarker(repoDir);
+    excludeMarkerFromGit(repoDir);
+    return repoDir;
+}
+/**
+ * Commits whatever the job changed, force-pushes it to a branch deterministic per shift
+ * target (so a retried job overwrites its own previous attempt instead of piling up
+ * branches) and opens a merge request. Returns null when there was nothing to commit —
+ * a change job that legitimately decided no change was needed. Throws when commit,
+ * push or MR creation fails, which the caller treats as a job failure rather than
+ * leaving the target MERGE_REQUEST_OPEN with no real merge request behind it.
+ */
+export async function publishChange(workspace, credentials, repoDir, project, shiftTargetId, title, description, fetchFn = fetch) {
+    const branchName = `slipway/change-${shiftTargetId}`;
+    await workspace.git(['add', '-A'], repoDir);
+    const staged = await workspace.git(['diff', '--cached', '--name-only'], repoDir);
+    if ('' === staged.stdout.trim()) {
+        workspace.log('job produced no file changes, skipping branch/MR creation');
+        return null;
+    }
+    await workspace.git(['-c', 'user.name=Slipway', '-c', 'user.email=slipway@localhost', 'commit', '-m', title], repoDir);
+    await workspace.git([...gitAuthConfig(credentials.accessToken), 'push', '--force', 'origin', `HEAD:refs/heads/${branchName}`], repoDir);
+    const mergeRequestUrl = await createMergeRequest(credentials, project.externalId, { sourceBranch: branchName, targetBranch: project.defaultBranch, title, description }, fetchFn);
+    return { branchName, mergeRequestUrl };
+}

package/dist/prompt.js

@@ -0,0 +1,110 @@
+const CTRL_C = String.fromCharCode(3);
+const BACKSPACE = String.fromCharCode(8);
+const DELETE = String.fromCharCode(127);
+function stripTrailingCr(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+/**
+ * Deliberately not `node:readline/promises`: its `question()` attaches a one-shot
+ * 'line' listener per call, but the interface starts consuming stdin as soon as
+ * it's constructed — when a whole multi-line answer set is already sitting in a
+ * pipe (piped/test input, not a human typing live), the first chunk gets parsed and
+ * emitted as 'line' events before a listener exists for the 2nd/3rd question, and
+ * those lines are silently lost (confirmed by hand: a second `rl.question()` call
+ * hung forever after piping 3 lines in one go). This hand-rolled buffer only ever
+ * attaches a listener while a read is actually pending, so nothing can be dropped.
+ */
+export function createPrompter(input = process.stdin, output = process.stdout) {
+    let buffer = '';
+    function takeBufferedLine() {
+        const newlineIndex = buffer.indexOf('\n');
+        if (-1 === newlineIndex) {
+            return null;
+        }
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        return stripTrailingCr(line);
+    }
+    function readLine() {
+        const buffered = takeBufferedLine();
+        if (null !== buffered) {
+            return Promise.resolve(buffered);
+        }
+        return new Promise(resolve => {
+            const cleanup = () => {
+                input.removeListener('data', onData);
+                input.removeListener('end', onEnd);
+            };
+            const onData = (chunk) => {
+                buffer += chunk.toString('utf8');
+                const line = takeBufferedLine();
+                if (null !== line) {
+                    cleanup();
+                    resolve(line);
+                }
+            };
+            const onEnd = () => {
+                cleanup();
+                const rest = buffer;
+                buffer = '';
+                resolve(stripTrailingCr(rest));
+            };
+            input.on('data', onData);
+            input.on('end', onEnd);
+        });
+    }
+    async function question(text) {
+        output.write(text);
+        return (await readLine()).trim();
+    }
+    async function questionHidden(text) {
+        if (!input.isTTY) {
+            return question(text);
+        }
+        return readMasked(text, input, output);
+    }
+    function close() {
+        input.pause();
+    }
+    return { question, questionHidden, close };
+}
+function readMasked(text, input, output) {
+    output.write(text);
+    return new Promise(resolve => {
+        let value = '';
+        const cleanup = () => {
+            input.setRawMode(false);
+            input.pause();
+            input.removeListener('data', onData);
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString('utf8')) {
+                if (CTRL_C === char) {
+                    cleanup();
+                    output.write('\n');
+                    process.exit(130);
+                }
+                else if ('\r' === char || '\n' === char) {
+                    cleanup();
+                    output.write('\n');
+                    resolve(value);
+                    return;
+                }
+                else if (DELETE === char || BACKSPACE === char) {
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                        output.write(`${BACKSPACE} ${BACKSPACE}`);
+                    }
+                }
+                else {
+                    value += char;
+                    output.write('*');
+                }
+            }
+        };
+        input.setRawMode(true);
+        input.resume();
+        input.setEncoding('utf8');
+        input.on('data', onData);
+    });
+}

package/dist/run.js

@@ -0,0 +1,77 @@
+import { resolveBackend } from './fleet/execute.js';
+/**
+ * `node run.js --engine <claude|kiro> --workdir <dir> --kind <qualification|change>
+ * [--model <id>]`, prompt on stdin, final agent text on stdout, non-zero exit on
+ * failure. The fleet loop calls the backends in-process (see fleet/execute.ts); this
+ * standalone form is kept for running a single prompt by hand against a checkout.
+ */
+export function parseArgs(argv) {
+    let engine;
+    let workdir;
+    let kind;
+    let model;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--engine':
+                engine = argv[++i];
+                break;
+            case '--workdir':
+                workdir = argv[++i];
+                break;
+            case '--kind':
+                kind = argv[++i];
+                break;
+            case '--model':
+                model = argv[++i];
+                break;
+            default:
+                throw new Error(`unknown argument: ${String(arg)}`);
+        }
+    }
+    if ('claude' !== engine && 'kiro' !== engine) {
+        throw new Error(`--engine must be "claude" or "kiro", got: ${String(engine)}`);
+    }
+    if (!workdir) {
+        throw new Error('--workdir is required');
+    }
+    if ('qualification' !== kind && 'change' !== kind) {
+        throw new Error(`--kind must be "qualification" or "change", got: ${String(kind)}`);
+    }
+    return { engine, workdir, kind, model };
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const prompt = (await readStdin()).trim();
+    if ('' === prompt) {
+        process.stderr.write('run: no prompt provided on stdin\n');
+        process.exitCode = 1;
+        return;
+    }
+    const backend = resolveBackend(args.engine);
+    const opts = { cwd: args.workdir, kind: args.kind, model: args.model };
+    try {
+        const result = await backend.execute(prompt, opts);
+        process.stdout.write(result.output);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`run: ${args.engine} execution failed: ${message}\n`);
+        process.exitCode = 1;
+    }
+}
+function isMainModule() {
+    return undefined !== process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+}
+if (isMainModule()) {
+    void main();
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@refleet-it/runner",
+  "version": "0.1.186",
+  "description": "Refleet fleet runner: claims code-modernisation jobs from the Refleet API and runs them through Claude Code or Kiro on your own machine.",
+  "keywords": [
+    "refleet",
+    "runner",
+    "claude-code",
+    "kiro",
+    "gitlab",
+    "code-modernisation"
+  ],
+  "homepage": "https://refleet.it",
+  "bugs": {
+    "url": "https://gitlab.com/slipway1/slipway/-/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/slipway1/slipway.git",
+    "directory": "runner/agent"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "refleet-runner": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "!dist/**/test-support.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "prepack": "npm run build",
+    "test": "npm run build && cd dist && node --test",
+    "login": "node dist/cli.js login",
+    "logout": "node dist/cli.js logout",
+    "whoami": "node dist/cli.js whoami",
+    "start": "node dist/cli.js run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}