Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { spawn } from '../lib/childProcess.js';
import { safeJSONParse } from '../lib/fileUtils.js';
import { GLAB_JSON_ARGS, withGlabJson } from '../lib/glabArgs.js';
import { withSpawnCwdEnv } from '../lib/spawnCwd.js';
// Mirrors execGh's DEFAULT_EXEC_GH_TIMEOUT_MS. `glab` hits the network, so a
// stalled call (hung keychain prompt, dead VPN) would otherwise leave the
// returned promise pending forever — wedging the scheduled job or, since #3358,
// the agent finalization that awaits an MR lookup before completing the run.
const DEFAULT_EXEC_GLAB_TIMEOUT_MS = 60000;
/**
* Execute a `glab` CLI command safely using spawn (no shell — injection-proof).
*
* Unlike `execGh` (github.js), this takes an explicit `cwd`: `glab` resolves the
* target project from the repo's git `origin` remote in the working directory, so
* it MUST run inside the repo checkout. Resolves to trimmed stdout on success and
* `null` on ANY failure (non-zero exit, spawn error, glab not installed, timeout)
* — callers treat null as "unavailable / transient", mirroring the
* `.catch(() => null)` pattern used around `execGh`. Mutation callers that need
* the original stderr contract can opt into rejection with `rejectOnError`.
*
* Most PortOS callers want JSON and go through `execGlabJson`, which owns the
* output flag (see lib/glabArgs.js). This is exported for the genuine non-JSON
* `glab` calls — mutations like `issue update --unlabel` / `issue note`, which
* return human text on success (see `blockedIssueReconcile.js`).
*
* @param {string[]} args - glab arguments (e.g. ['issue', 'list', '--output', 'json'])
* @param {string} cwd - repo root the glab command runs in
* @param {number} [timeoutMs] - kills the child and resolves null past this
* @param {object} [options]
* @param {NodeJS.ProcessEnv} [options.env] - Explicit forge credentials/environment
* @param {boolean} [options.rejectOnError=false] - Reject with stderr/timeout detail instead of resolving null
* @returns {Promise<string|null>}
*/
export function execGlab(args, cwd, timeoutMs = DEFAULT_EXEC_GLAB_TIMEOUT_MS, { env = null, rejectOnError = false } = {}) {
return new Promise((resolve, reject) => {
const child = spawn('glab', args, { cwd, shell: false, env: withSpawnCwdEnv(env || process.env, cwd) });
let stdout = '';
let stderr = '';
let settled = false;
// One settle path so the timeout can't resolve a promise `close` already
// settled, and so the timer is always cleared.
const done = (value, error = null) => {
if (settled) return;
settled = true;
clearTimeout(timer);
if (error && rejectOnError) reject(error);
else resolve(value);
};
const timer = setTimeout(() => {
// setTimeout callback boundary — a kill() throw here would be uncaught.
try { child.kill('SIGKILL'); } catch (err) { console.error(`❌ execGlab: failed to kill timed-out 'glab ${args.join(' ')}': ${err.message}`); }
console.error(`❌ execGlab: 'glab ${args.join(' ')}' timed out after ${timeoutMs}ms`);
done(null, new Error(`glab command timed out after ${timeoutMs}ms`));
}, timeoutMs);
child.stdout.on('data', (d) => { stdout += d.toString(); });
child.stderr.on('data', (d) => { stderr += d.toString(); });
child.on('close', (code) => {
if (code === 0) done(stdout.trim());
else done(null, new Error(stderr.trim() || `glab exited with code ${code}`));
});
child.on('error', (err) => done(null, new Error(`glab not available: ${err.message}`)));
});
}
/**
* Run a `glab … list` command and parse its JSON array. Three answers, not two —
* the absent-vs-empty split every caller needs (AGENTS.md):
*
* - `ok` — glab answered; `rows` is the (possibly empty) array.
* - `cli-failed` — we could not ask (non-zero exit: unauthenticated, no
* network, `glab` not installed, timed out).
* - `not-json` — glab answered at exit 0 with something that is not a JSON
* array, which means its output flags moved (lib/glabArgs.js)
* and NOT that the user is logged out. It gets its own reason
* so callers stop sending a working CLI to re-authenticate.
*
* `reason` is only meaningful when `rows` is null. `args` must NOT carry an
* output flag — this appends the one correct spelling.
*
* @param {string[]} args - glab arguments without the JSON output flag
* @param {string} cwd - repo root the glab command runs in
* @param {number} [timeoutMs]
* @returns {Promise<{rows: object[]|null, reason: 'ok'|'cli-failed'|'not-json'}>}
*/
export async function execGlabJson(args, cwd, timeoutMs = DEFAULT_EXEC_GLAB_TIMEOUT_MS) {
const raw = await execGlab(withGlabJson(args), cwd, timeoutMs);
if (raw === null) return { rows: null, reason: 'cli-failed' };
// The `null` default is load-bearing: safeJSONParse only applies its
// salvage-an-array-from-noisy-output affordance when the default IS an array,
// and that path yields `[]` for prose — so passing `[]` here would parse
// glab's human table into a trustworthy-looking empty list, re-creating the
// very bug this function exists to catch.
const rows = safeJSONParse(raw, null);
if (Array.isArray(rows)) return { rows, reason: 'ok' };
console.error(`❌ execGlabJson: 'glab ${args.join(' ')}' exited 0 without JSON — glab's output flags have changed; check 'glab ${args.slice(0, 2).join(' ')} --help'`);
return { rows: null, reason: 'not-json' };
}
/**
* Does a merge request exist for `branch`? The GitLab mirror of
* `github.js#findPullRequestForBranch` (#3358), with the same three answers
* rather than two: `found`, `none` (glab answered, none exist), `unavailable`
* (we could not ask). Collapsing the last into `none` is what lets a run that
* opened no MR be recorded as a success.
*
* `--all` widens past glab's opened-only default: an MR that was opened and
* later closed still proves the agent reached the forge, which is the question.
*
* @param {string} branch - source branch name
* @param {string} cwd - repo root (glab resolves the project from its cwd)
* @returns {Promise<{ status: 'found'|'none'|'unavailable', number: number|null, url: string|null, body: string|null, detail: string|null }>}
*/
export async function findMergeRequestForBranch(branch, cwd, { includeDraft = false } = {}) {
if (!branch || !cwd) return { status: 'unavailable', number: null, url: null, detail: 'no branch or repo path' };
const { rows, reason } = await execGlabJson(['mr', 'list', '--source-branch', branch, '--all', '-P', '1'], cwd);
// Both failure modes are "we could not ask" here — a zero-exit glab that
// emitted nothing parseable told us nothing either.
if (!rows) {
const detail = reason === 'not-json' ? 'glab returned unparseable output' : 'glab call failed';
return { status: 'unavailable', number: null, url: null, detail };
}
const mr = rows[0];
if (!mr) return { status: 'none', number: null, url: null, detail: null };
return { status: 'found', number: mr.iid ?? null, url: mr.web_url || null, body: typeof mr.description === 'string' ? mr.description : null, detail: mr.state || null, ...(includeDraft ? { isDraft: mr.draft === true || mr.work_in_progress === true } : {}) };
}
/**
* Read ONE merge request's state by iid — the GitLab mirror of
* `github.js#getPullRequestState`, with the same two-not-three-answers
* discipline: `known` is a real forge answer, `unavailable` means we could not
* ask (glab failed, not installed, or answered exit-0 without JSON), and a
* caller must never read `unavailable` as "not merged".
*
* `glab mr view <iid>` answers a single OBJECT (not a list), so this goes
* through `execGlab` + `safeJSONParse` rather than `execGlabJson`, whose
* array-only salvage would misread it. `--output json` is the one correct
* spelling (lib/glabArgs.js).
*
* @param {number|string} mrIid - the project-local MR iid
* @param {string} cwd - repo root glab resolves the project from
* @returns {Promise<{ status: 'known'|'unavailable', state: string|null, detail: string|null }>}
* `state` is upper-cased (`MERGED` / `OPENED` / `CLOSED`) when status is `known`.
*/
export async function getMergeRequestState(mrIid, cwd) {
if (!mrIid || !cwd) return { status: 'unavailable', state: null, detail: 'no MR reference or repo path' };
const raw = await execGlab(['mr', 'view', String(mrIid), ...GLAB_JSON_ARGS], cwd).catch(() => null);
if (raw === null) return { status: 'unavailable', state: null, detail: 'glab call failed' };
const parsed = safeJSONParse(raw, null);
const state = typeof parsed?.state === 'string' && parsed.state.trim() ? parsed.state.toUpperCase() : null;
// A zero-exit glab that emitted nothing parseable told us nothing.
if (!state) return { status: 'unavailable', state: null, detail: 'glab returned unparseable output' };
return { status: 'known', state, detail: null };
}