Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
import * as vscode from "vscode";
import { spawn, type ChildProcess } from "node:child_process";
import { Commands, MIN_SERVER_VERSION } from "../constants";
import type { RepowiseContext } from "../core/context";
import { isLoopbackUrl, type ServeLock } from "@repowise-dev/types/serve-lock";
import { isPidAlive, readLockfile } from "../core/lockfile";
import type { HealthResult } from "../core/api";
/**
* How long to wait for a freshly spawned server to bind a port, write its
* lockfile, and finish its synchronous startup (DB + embedder init) before we
* declare the start a failure. The server does this work before accepting any
* traffic, so the poll has to be patient.
*/
const START_TIMEOUT_MS = 60_000;
/** Initial poll interval; doubles up to the cap after each miss. */
const POLL_START_MS = 250;
const POLL_MAX_MS = 2_000;
/** Grace period before escalating a stop from a polite kill to a forced one. */
const KILL_GRACE_MS = 3_000;
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
/**
* Compares two dotted numeric versions, ignoring any prerelease suffix
* (`1.2.3-rc1` compares as `1.2.3`). Returns <0, 0, or >0. Deliberately tiny:
* server versions are simple numeric triples, so a full semver dependency
* would be overkill here.
*/
function compareVersions(a: string, b: string): number {
const parse = (v: string): number[] =>
(v.split("-")[0] ?? "")
.split(".")
.map((seg) => Number.parseInt(seg, 10) || 0);
const pa = parse(a);
const pb = parse(b);
const len = Math.max(pa.length, pb.length);
for (let i = 0; i < len; i++) {
const da = pa[i] ?? 0;
const db = pb[i] ?? 0;
if (da !== db) return da < db ? -1 : 1;
}
return 0;
}
/**
* Server lifecycle: discovering the running server from its lockfile, health
* probing, and starting/stopping `repowise serve --no-ui`. The start/stop
* commands are owned by this module. All discovery/probe work is deferred off
* the activation hot path and driven reactively by lockfile-change events; the
* module never polls while healthy.
*/
export function registerServerManager(ctx: RepowiseContext): vscode.Disposable {
/** The server process we spawned, or null when we own none. */
let owned: ChildProcess | null = null;
/** True while a start attempt is in flight, to guard against double-spawn. */
let starting = false;
/** Show the version-too-old warning at most once per session. */
let warnedVersionLow = false;
/** Set on dispose so in-flight polls abandon their work. */
let disposed = false;
/** Subscription to lockfile-change events; recreated after a rescan. */
let watcherSub: vscode.Disposable | null = null;
const isConnected = (): boolean =>
ctx.getExtensionState() === "ready" && ctx.api.getBaseUrl() !== null;
/** Subscribe to lockfile-change events for the current repo root, once. */
function ensureWatcher(): void {
if (watcherSub) return;
const watcher = ctx.events();
if (!watcher) return;
watcherSub = watcher.onDidChange((kind) => {
// A server started or stopped out of band rewrites the lockfile.
if (kind === "lockfileChanged") void discover({ rescan: false });
});
}
/** Split spawned-process output into per-line log entries. */
function logServeOutput(buf: Buffer, level: "debug" | "info"): void {
const text = buf.toString().replace(/\r?\n$/, "");
if (!text) return;
for (const line of text.split(/\r?\n/)) {
if (level === "debug") ctx.log.debug(`serve: ${line}`);
else ctx.log.info(`serve: ${line}`);
}
}
/**
* Commits the shared API client to a verified-healthy server and settles the
* editor into the ready/connected state, or flags a too-old server.
*/
async function onConnected(
repoRoot: string,
url: string,
health: HealthResult,
): Promise<void> {
ctx.api.setBaseUrl(url);
if (compareVersions(health.version, MIN_SERVER_VERSION) < 0) {
// The server is up but predates the store shape this build can read.
ctx.setExtensionState("server-down");
ctx.setStatusBarState("version-low");
if (!warnedVersionLow) {
warnedVersionLow = true;
void vscode.window.showWarningMessage(
`The Repowise server (${health.version}) is older than this extension supports (${MIN_SERVER_VERSION}). Upgrade with: pip install --upgrade repowise`,
);
}
return;
}
// A missing repo record is not fatal: staying connected still serves the
// workspace, so log it and carry on. Set before the ready flip so state
// listeners read a settled repo.
const repo = await ctx.api.resolveRepo(repoRoot);
if (!repo) {
ctx.log.warn(`Could not resolve a repo id for ${repoRoot}; staying connected.`);
}
ctx.setRepo(repo);
ctx.setExtensionState("ready");
ctx.setStatusBarState("connected", { version: health.version, url });
}
/**
* Deferred discovery: locate the server from its lockfile, probe it, and
* settle into the matching state. Auto-starts only when the setting grants
* standing consent. `rescan` re-detects workspace folders (and invalidates
* the freshness watcher), so re-runs triggered by the watcher pass false.
*/
async function discover(opts: { rescan: boolean }): Promise<void> {
if (disposed || starting) return;
if (!vscode.workspace.isTrusted) {
// No filesystem or process work in an untrusted workspace.
ctx.setStatusBarState("untrusted");
return;
}
if (opts.rescan) {
// Rescanning disposes the freshness watcher this root was bound to, so
// drop the now-dead subscription and rebuild it below.
watcherSub?.dispose();
watcherSub = null;
ctx.rescanWorkspace();
}
const ws = ctx.workspace;
if (!ws.repoRoot || !ws.lockfilePath) {
ctx.setExtensionState("no-index");
ctx.setStatusBarState("no-index");
return;
}
ensureWatcher();
// The pid gate is not redundant with the probe: a dead writer's port can
// be re-bound by an unrelated server that answers /health convincingly.
const lock = await readLocalLockfile(ws.lockfilePath);
if (lock && isPidAlive(lock.pid)) {
const health = await ctx.api.checkHealth(lock.url);
if (health) {
await onConnected(ws.repoRoot, lock.url, health);
return;
}
} else if (lock) {
ctx.log.debug(`Ignoring stale lockfile (pid ${lock.pid} is gone).`);
}
// No lockfile, or a present-but-stale one whose server no longer answers.
ctx.setExtensionState("server-down");
ctx.setStatusBarState("server-down");
// Standing consent only: "always" starts silently; "ask"/"never" wait for
// the user to click the status bar or a welcome-view action.
if (ctx.config.autoStart() === "always") {
void startFlow({ silent: true });
}
}
/**
* The lockfile, unless its url points off this machine: the file sits in the
* repo, so a cloned repo can name any host. Such a lock is ignored and the
* normal start/connect path runs.
*/
async function readLocalLockfile(path: string): Promise<ServeLock | null> {
const lock = await readLockfile(path);
if (lock && !isLoopbackUrl(lock.url)) {
ctx.log.warn("Ignoring serve.lock.json: its url is not a loopback address.");
return null;
}
return lock;
}
/**
* Polls for the lockfile to appear and its server to answer /health, backing
* off between attempts. Re-reads the lockfile every pass so a port the server
* auto-bumped is picked up. Returns null on timeout, dispose, or abort.
*/
async function pollForHealth(
lockfilePath: string,
aborted: () => boolean,
): Promise<{ url: string; health: HealthResult } | null> {
const deadline = Date.now() + START_TIMEOUT_MS;
let delay = POLL_START_MS;
while (Date.now() < deadline) {
if (disposed || aborted()) return null;
// Pid-gated so the poll cannot adopt a stale lockfile (and whatever
// re-bound its port) in the window before our child overwrites it.
const lock = await readLocalLockfile(lockfilePath);
if (lock && isPidAlive(lock.pid)) {
const health = await ctx.api.checkHealth(lock.url);
if (health) return { url: lock.url, health };
}
await sleep(delay);
delay = Math.min(delay * 2, POLL_MAX_MS);
}
return null;
}
/**
* Starts the local server. An explicit command invocation is consent by
* itself; the auto path passes `silent` and suppresses toasts. Adopts an
* already-running server rather than spawning a duplicate.
*/
async function startFlow(opts: { silent: boolean }): Promise<void> {
if (disposed || starting) return;
// Claim the in-flight slot before the first await so two overlapping
// invocations (a double-click, or command plus welcome view) cannot both
// reach the spawn.
starting = true;
try {
await startFlowLocked(opts);
} finally {
starting = false;
}
}
async function startFlowLocked(opts: { silent: boolean }): Promise<void> {
const ws = ctx.workspace;
if (!ws.repoRoot || !ws.lockfilePath) {
if (!opts.silent) {
void vscode.window.showWarningMessage(
"No Repowise index found in this workspace.",
);
}
return;
}
if (isConnected()) {
if (!opts.silent) {
void vscode.window.showInformationMessage(
"The Repowise server is already running.",
);
}
return;
}
// A healthy server may already be up (started outside the editor, or by a
// prior session). Adopt it instead of spawning a second one. Pid-gated:
// never adopt through a dead writer's lockfile.
const existing = await readLocalLockfile(ws.lockfilePath);
if (existing && isPidAlive(existing.pid)) {
const health = await ctx.api.checkHealth(existing.url);
if (health) {
await onConnected(ws.repoRoot, existing.url, health);
return;
}
}
ctx.setStatusBarState("connecting");
ctx.log.info("Starting the local Repowise server...");
const args = ["serve", "--no-ui"];
const port = ctx.config.serverPort();
if (port !== null) args.push("--port", String(port));
let child: ChildProcess;
try {
child = spawn(ctx.cli.executable, args, {
cwd: ws.repoRoot,
shell: false,
windowsHide: true,
});
} catch (err) {
await handleStartFailure(err, opts, null);
return;
}
owned = child;
let enoent = false;
child.on("error", (err: Error) => {
if ((err as NodeJS.ErrnoException).code === "ENOENT") enoent = true;
ctx.log.error(`server process error: ${String(err)}`);
});
child.stdout?.on("data", (b: Buffer) => logServeOutput(b, "debug"));
child.stderr?.on("data", (b: Buffer) => logServeOutput(b, "info"));
child.on("exit", (code, signal) => {
ctx.log.info(`server process exited (code ${code ?? "null"}, signal ${signal ?? "null"})`);
if (owned === child) owned = null;
});
const result = await pollForHealth(ws.lockfilePath, () => enoent);
if (result) {
await onConnected(ws.repoRoot, result.url, result.health);
return;
}
if (enoent) {
// The CLI itself is missing; nothing was actually launched to clean up.
await handleStartFailure(new Error("repowise CLI not found"), opts, null);
return;
}
// Spawned but never became healthy: clean up the process we own so it does
// not linger, then surface the failure.
await handleStartFailure(
new Error("server did not become healthy in time"),
opts,
child,
);
}
/**
* Common failure handling for a start attempt. A missing CLI points at Check
* Setup and flags the extension as not-installed; a start timeout offers the
* log. `toKill` is the process we own and should tear down (null when none
* was launched).
*/
async function handleStartFailure(
err: unknown,
opts: { silent: boolean },
toKill: ChildProcess | null,
): Promise<void> {
ctx.log.error(`failed to start server: ${String(err)}`);
if (toKill) {
killTree(toKill);
if (owned === toKill) owned = null;
}
const isEnoent =
err instanceof Error &&
(err.message.includes("not found") ||
(err as NodeJS.ErrnoException).code === "ENOENT");
if (isEnoent) {
ctx.setExtensionState("not-installed");
ctx.setStatusBarState("server-down");
if (!opts.silent) {
const choice = await vscode.window.showErrorMessage(
"Could not find the repowise CLI. Check your Repowise setup.",
"Check Setup",
);
if (choice === "Check Setup") {
void vscode.commands.executeCommand(Commands.checkSetup);
}
}
return;
}
ctx.setExtensionState("server-down");
ctx.setStatusBarState("server-down");
if (!opts.silent) {
const choice = await vscode.window.showErrorMessage(
"The Repowise server did not start in time.",
"Show Log",
);
if (choice === "Show Log") ctx.log.show();
}
}
/**
* Terminates a process we spawned, including its children. On Windows a
* polite kill often leaves the CLI's child tree alive, so escalate to
* `taskkill /T /F` after a grace period; elsewhere fall back from SIGTERM to
* SIGKILL.
*/
function killTree(child: ChildProcess): void {
const pid = child.pid;
const stillAlive = (): boolean =>
child.exitCode === null && child.signalCode === null;
if (process.platform === "win32") {
// The CLI on PATH is a launcher exe whose real work happens in a child
// process tree. Killing only the launcher leaves the server running, so
// always take down the whole tree by pid; there is no graceful signal on
// Windows to try first.
if (pid === undefined) {
child.kill();
return;
}
try {
spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
shell: false,
windowsHide: true,
});
} catch (err) {
ctx.log.debug(`taskkill failed: ${String(err)}`);
child.kill();
}
return;
}
child.kill("SIGTERM");
setTimeout(() => {
if (stillAlive()) child.kill("SIGKILL");
}, KILL_GRACE_MS);
}
/** Stops only a server this extension started. */
function stopServer(): void {
if (!owned) {
const message = isConnected()
? "Repowise is connected to a server it did not start, so it will not stop it."
: "No Repowise server started by this extension is running.";
void vscode.window.showInformationMessage(message);
return;
}
const child = owned;
owned = null;
killTree(child);
ctx.api.setBaseUrl(null);
ctx.setExtensionState("server-down");
ctx.setStatusBarState("server-down");
ctx.log.info("Stopped the local Repowise server.");
}
/** In-flight guard and cooldown for connection-failure rechecks. */
let rechecking = false;
let lastRecheckAt = 0;
/**
* A data request failed at the network level while we believed we were
* connected. Re-probe once (cooldown-limited): a healthy probe means a
* transient blip; a dead one re-runs discovery, which settles into
* server-down and restores the Start Server affordances.
*/
async function recheckConnection(): Promise<void> {
if (disposed || rechecking || !isConnected()) return;
const now = Date.now();
if (now - lastRecheckAt < 5_000) return;
rechecking = true;
lastRecheckAt = now;
try {
const url = ctx.api.getBaseUrl();
if (!url) return;
const health = await ctx.api.checkHealth(url);
if (health || disposed) return;
ctx.log.info("Server stopped answering; re-running discovery.");
await discover({ rescan: false });
} finally {
rechecking = false;
}
}
ctx.api.onConnectionFailure(() => void recheckConnection());
const disposables: vscode.Disposable[] = [
vscode.commands.registerCommand(Commands.startServer, () =>
// An explicit invocation is its own consent, so never silent.
void startFlow({ silent: false }),
),
vscode.commands.registerCommand(Commands.stopServer, () => stopServer()),
// Granting trust unlocks the deferred discovery we skipped while untrusted.
vscode.workspace.onDidGrantWorkspaceTrust(() => void discover({ rescan: true })),
// A folder set change (extension.ts already rescans) means a new primary
// root: re-detect and rebind the watcher.
vscode.workspace.onDidChangeWorkspaceFolders(() =>
void discover({ rescan: true }),
),
];
// First discovery runs off the activation hot path (this also lazily creates
// the freshness watcher, which must never happen during activate()).
const timer = setTimeout(() => void discover({ rescan: true }), 1_500);
disposables.push({ dispose: () => clearTimeout(timer) });
return {
dispose(): void {
disposed = true;
watcherSub?.dispose();
watcherSub = null;
if (owned) {
killTree(owned);
owned = null;
}
for (const d of disposables) d.dispose();
},
};
}