sverka 0.2.23 → 0.2.25

package/dist/index.mjs

@@ -3,18 +3,21 @@ import * as nodeModule from "node:module";
 import { register } from "node:module";
 import process$1 from "node:process";
 import yargs from "yargs";
-import { constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { chmodSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { mkdir, open, readFile, realpath, writeFile } from "node:fs/promises";
 import { Entry, Pipeline, Project, ShellStep, collectConstructWarnings, manual, synthesize, validateGraph } from "@sverka/workflow";
 import { bindRunPlan, createPlanner } from "@sverka/sdk";
 import { DEFAULT_POLICY, createBuiltinResolver, evaluatePolicy, loadBaseline, normalizeSarif, serializeSarif, synthesizeCheckSteps } from "@sverka/verification";
-import { createDockerDriver, createEngine, createHostDriver } from "@sverka/runtime";
-import { spawnSync } from "node:child_process";
+import { AGENT_ENV, collectAgentWrites, createDockerDriver, createEngine, createFileCacheStore, createHostDriver, noAgentDriverError, resolveAgentDrivers, resolveAgentEngine } from "@sverka/runtime";
+import { execFileSync, spawnSync } from "node:child_process";
 import { watch } from "chokidar";
+import { homedir } from "node:os";
+import { createRemoteCacheStore, createRemoteCircuit, createRemoteSnapshotStore, createTieredCacheStore } from "@sverka/storage";
 import { compileGithub, compileGitlab } from "@sverka/compiler";
 import { z } from "zod";
+import { startHubServer } from "@sverka/hub";
 //#region src/types.ts
 /** Exit codes used by the CLI. */
 const ExitCode = {
@@ -190,17 +193,31 @@ async function registerConfigHooks() {
 /**
 * Find a sverka.config.ts or sverka.config.js file in the given root.
 * Returns the absolute path or null if not found.
+* Spec 37/54: when no config exists, fall back to `.sverka/*.md` files
+* (markdown authoring) — sorted, first file wins.
 */
 async function findConfig(root) {
 	for (const candidate of [
 		"sverka.config.ts",
+		"sverka.config.mts",
 		"sverka.config.js",
 		"sverka.config.mjs"
 	]) {
 		const path = join(root, candidate);
 		if (existsSync(path)) return path;
 	}
-	return null;
+	return findMarkdownConfig(root);
+}
+/** First `.sverka/*.md` file under root (sorted), or null. */
+function findMarkdownConfig(root) {
+	const dir = join(root, ".sverka");
+	let names;
+	try {
+		names = readdirSync(dir).filter((n) => n.endsWith(".md")).sort();
+	} catch {
+		return null;
+	}
+	return names.length > 0 ? join(dir, names[0]) : null;
 }
 /**
 * Resolve the effective config path from global flags.
@@ -236,6 +253,12 @@ function assertConstructLike(value) {
 async function loadConfig(configPath) {
 	const absPath = isAbsolute(configPath) ? configPath : resolve(process.cwd(), configPath);
 	if (!existsSync(absPath)) throw new CliError(`config not found: ${absPath}`, "MISSING_ARG", ExitCode.UsageError);
+	if (absPath.endsWith(".md")) try {
+		const { loadMarkdownFile } = await import("@sverka/sdk");
+		return await loadMarkdownFile(absPath);
+	} catch (e) {
+		throw new CliError(`failed to load config: ${e instanceof Error ? e.message : String(e)}`, "SDK_ERROR", ExitCode.RuntimeError, e);
+	}
 	let mod;
 	try {
 		await registerConfigHooks();
@@ -947,6 +970,119 @@ function watchLoop(opts) {
 	};
 }
 //#endregion
+//#region src/internal/hub.ts
+function configHome() {
+	const xdg = process.env["XDG_CONFIG_HOME"];
+	return typeof xdg === "string" && xdg !== "" ? xdg : join(homedir(), ".config");
+}
+function credentialsPath() {
+	return join(configHome(), "sverka", "credentials");
+}
+function readCredentials() {
+	try {
+		const text = readFileSync(credentialsPath(), "utf8");
+		const parsed = JSON.parse(text);
+		if (typeof parsed === "object" && parsed !== null) return parsed;
+	} catch {}
+	return {};
+}
+/**
+* Store a hub token at `~/.config/sverka/credentials` with mode 0600.
+* The file is a JSON map keyed by hub URL so multiple hubs coexist.
+*/
+function storeCredentials(url, token) {
+	const path = credentialsPath();
+	const hubs = {
+		...readCredentials().hubs ?? {},
+		[url]: token
+	};
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	writeFileSync(path, `${JSON.stringify({ hubs }, null, 2)}\n`, { mode: 384 });
+	chmodSync(path, 384);
+	return path;
+}
+function storedTokenFor(url) {
+	return readCredentials().hubs?.[url];
+}
+/** Read `.sverka/hub.json` when present. Malformed JSON is ignored. */
+function readHubFileConfig(root) {
+	const path = join(root, ".sverka", "hub.json");
+	if (!existsSync(path)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof parsed !== "object" || parsed === null) return {};
+		const outer = parsed;
+		const inner = typeof outer.remote === "object" && outer.remote !== null ? outer.remote : outer;
+		return {
+			url: typeof inner.url === "string" ? inner.url : void 0,
+			project: typeof inner.project === "string" ? inner.project : void 0,
+			enabled: inner.enabled === true,
+			cache: typeof inner.cache === "boolean" ? inner.cache : void 0,
+			upload: typeof inner.upload === "boolean" ? inner.upload : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/** Derive "owner/repo" from `git remote.origin.url`; falls back to the
+*  directory basename when there is no usable remote. */
+function projectSlug(root) {
+	try {
+		const url = execFileSync("git", [
+			"config",
+			"--get",
+			"remote.origin.url"
+		], {
+			cwd: root,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		const slug = (/^[^@]+@[^:]+:(.+)$/.exec(url)?.[1] ?? new URL(url).pathname).replace(/\.git$/, "").replace(/^\/+/, "");
+		if (slug !== "") return slug;
+	} catch {}
+	return basename(resolve(root));
+}
+function envString(name) {
+	const value = process.env[name];
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/** Canonical credential key — `sverka login` stores tokens under the URL
+*  with trailing slashes stripped; lookups must normalize identically. */
+function normalizeHubUrl(url) {
+	let end = url.length;
+	while (end > 0 && url.charCodeAt(end - 1) === 47) end--;
+	return url.slice(0, end);
+}
+/**
+* Resolve the effective hub connection for a root. Returns null when no
+* hub is configured at all (no url, no token anywhere) — the caller then
+* treats `--remote` as a usage error and a bare `run` stays local.
+*/
+function resolveHub(root) {
+	const file = readHubFileConfig(root);
+	const rawUrl = envString("SVERKA_HUB_URL") ?? file.url;
+	const url = rawUrl !== void 0 ? normalizeHubUrl(rawUrl) : void 0;
+	const token = envString("SVERKA_HUB_TOKEN") ?? (url !== void 0 ? storedTokenFor(url) : void 0);
+	if (url === void 0 || token === void 0) return null;
+	return {
+		config: {
+			url,
+			token,
+			project: file.project ?? projectSlug(root)
+		},
+		cache: file.cache ?? true,
+		upload: file.upload ?? true,
+		enabled: file.enabled === true
+	};
+}
+//#endregion
 //#region src/commands/run.ts
 /** Pure-argument guards — an invalid flag fails fast instead of surfacing
 *  as a recurring run failure inside the watch supervisor. */
@@ -968,6 +1104,7 @@ async function runCommand(args, global, output, start) {
 	if (detected !== void 0) output.errorLine(`no sverka.config — running ${detected.length} detected checks (${detected.join(", ")})`);
 	for (const warning of warnings) output.errorLine(`warning: ${warning}`);
 	const entryId = resolveEntryId(graph, args.entryId);
+	const remote = resolveRemote(args, global, output);
 	const plan = bindRunPlan({
 		graph,
 		entryId
@@ -975,10 +1112,13 @@ async function runCommand(args, global, output, start) {
 	const artifactDir = join(global.root, ".sverka", "artifacts");
 	const { events, runStatus, renderer } = await consumeEvents(createEngine({
 		drivers: buildDrivers(executor),
+		agentDrivers: resolveAgentDrivers(process$1.env),
 		maxConcurrent: args.jobs ?? 4
 	}), plan, {
 		workspace: global.root,
-		artifactDir
+		artifactDir,
+		cache: remote?.stores.cache,
+		snapshotStore: remote?.stores.snapshotStore
 	}, global, output, graph, args);
 	const durationMs = Date.now() - start;
 	const evaluation = await evaluateRun(fmt.evaluate, artifactDir, global, output, events, renderer, args, start);
@@ -994,6 +1134,7 @@ async function runCommand(args, global, output, start) {
 		...detected !== void 0 ? { detected } : {},
 		...args.report !== void 0 ? { report: args.report } : {}
 	}, events, output);
+	if (remote !== void 0 && remote.upload && report !== void 0) await uploadReportSafe(remote, report, entryId, findRunId(events), output);
 	await finalizeRenderer(fmt, renderer, args, global, output);
 	if (evaluation.collectionFailed) return evaluation.exitCode;
 	writeRunOutput({
@@ -1011,6 +1152,52 @@ async function runCommand(args, global, output, start) {
 	if (evaluation.exitCode !== 0) return evaluation.exitCode;
 	return exitCodeForStatus(runStatus);
 }
+/** Build the remote wiring for a run. `--remote` with no hub configured
+*  is a usage error naming `sverka login`; a hub.json-enabled run whose
+*  credentials are missing warns and runs local-only (degrade, don't
+*  fail). */
+function resolveRemote(args, global, output) {
+	const hub = resolveHub(global.root);
+	const requested = args.remote === true;
+	if (hub === null) {
+		if (requested) throw new CliError("--remote needs a hub: set SVERKA_HUB_URL + SVERKA_HUB_TOKEN, run `sverka login --hub <url> --token <t>`, or add .sverka/hub.json", "MISSING_ARG", ExitCode.UsageError);
+		if (readHubFileConfig(global.root).enabled === true) output.errorLine("warning: .sverka/hub.json enables remote runs but no hub credentials resolved — running local-only (see `sverka login`)");
+		return;
+	}
+	if (!requested && !hub.enabled) return void 0;
+	const circuit = createRemoteCircuit();
+	const remoteConfig = {
+		...hub.config,
+		circuit
+	};
+	const cache = hub.cache ? createTieredCacheStore({
+		local: createFileCacheStore({ cacheDir: join(global.root, ".sverka", "cache") }),
+		remote: createRemoteCacheStore(remoteConfig),
+		onWarn: (msg) => output.errorLine(`warning: ${msg}`)
+	}) : void 0;
+	return {
+		config: remoteConfig,
+		upload: hub.upload,
+		stores: {
+			...cache !== void 0 ? { cache } : {},
+			snapshotStore: createRemoteSnapshotStore(remoteConfig)
+		}
+	};
+}
+/** Upload the run report — warns `remote.upload-failed` and swallows the
+*  error per Spec 55 ("remote failures degrade to local + warn"). */
+async function uploadReportSafe(remote, report, entryId, runId, output) {
+	try {
+		const { uploadRunReport } = await import("@sverka/storage");
+		const result = await uploadRunReport(remote.config, report.payload, report.findingsList, {
+			entry: entryId,
+			...runId !== void 0 ? { runId } : {}
+		});
+		output.debug(`remote: uploaded run report as ${result.runId}`);
+	} catch (e) {
+		output.errorLine(`warning: remote.upload-failed: ${e instanceof Error ? e.message : String(e)}`);
+	}
+}
 /** Post-run: announce the HTML report path (sarif/web print their own),
 *  then keep interactive renderers mounted until the user quits. */
 async function finalizeRenderer(fmt, renderer, args, global, output) {
@@ -1090,7 +1277,9 @@ async function writeReportSafe(ctx, events, output) {
 		return {
 			html: artifacts.htmlPath,
 			json: join(artifacts.dir, "report.json"),
-			findings: artifacts.findingsCount
+			findings: artifacts.findingsCount,
+			payload: artifacts.payload,
+			findingsList: artifacts.findings
 		};
 	} catch (err) {
 		if (err instanceof CliError) throw err;
@@ -1198,7 +1387,9 @@ async function consumeEvents(engine, plan, ctx, global, output, graph, args) {
 	for await (const event of engine.run({
 		plan,
 		workspace: ctx.workspace,
-		artifactDir: ctx.artifactDir
+		artifactDir: ctx.artifactDir,
+		...ctx.cache !== void 0 ? { cache: ctx.cache } : {},
+		...ctx.snapshotStore !== void 0 ? { snapshotStore: ctx.snapshotStore } : {}
 	})) {
 		events.push(event);
 		renderer?.onEvent(event);
@@ -1464,11 +1655,14 @@ async function writeRunArtifacts(opts) {
 	const warnings = [];
 	const findings = await collectRunFindings(opts, warnings);
 	const htmlPath = await writeReportHtml(opts.reportPath !== void 0 ? resolveUnderRoot(opts.root, opts.reportPath) : join(dir, "report.html"), findings, warnings);
-	writeFileSync(join(dir, "report.json"), JSON.stringify(runReportPayload(opts, findings.length, warnings), null, 2), "utf-8");
+	const payload = runReportPayload(opts, findings.length, warnings);
+	writeFileSync(join(dir, "report.json"), JSON.stringify(payload, null, 2), "utf-8");
 	return {
 		dir,
 		htmlPath,
-		findingsCount: findings.length
+		findingsCount: findings.length,
+		payload,
+		findings
 	};
 }
 function exitCodeForStatus(runStatus) {
@@ -2265,6 +2459,336 @@ async function uiCommand(args, global, output, _start) {
 	}
 }
 //#endregion
+//#region src/commands/agent.ts
+const RESULT_FILE = "agent-result.json";
+const WRITES_FILE$1 = "sverka-writes.json";
+async function agentCommand(args, global, output, _start) {
+	const env = process$1.env;
+	const engine = resolveAgentEngine(env);
+	const prompt = env[AGENT_ENV.prompt];
+	if (prompt === void 0 || prompt === "") throw new CliError(`sverka agent: ${AGENT_ENV.prompt} is not set — the compiled agent job provides it`, "MISSING_ARG", ExitCode.UsageError);
+	const outDir = args.outputDir ?? global.root;
+	const mentions = parseMentionList(env[AGENT_ENV.mention]);
+	const commentBody = env["COMMENT_BODY"];
+	if (mentions.length > 0 && commentBody !== void 0 && !mentions.some((m) => commentBody.includes(m))) {
+		output.writeLine(`sverka agent: comment does not contain a configured mention (${mentions.join(", ")}) — skipping`);
+		await writeArtifacts(outDir, {
+			text: "",
+			finishReason: "stop"
+		});
+		return ExitCode.Success;
+	}
+	const driver = resolveAgentDrivers(env).find((d) => d.canExecute(engine));
+	if (driver === void 0) throw noAgentDriverError(engine, `sverka agent, engine '${engine}'`);
+	const model = env[AGENT_ENV.model];
+	const maxTokens = env[AGENT_ENV.maxTokens];
+	const request = {
+		engine,
+		prompt,
+		...model !== void 0 ? { model } : {},
+		...maxTokens !== void 0 ? { maxTokens: parseMaxTokens(maxTokens) } : {}
+	};
+	output.debug(`sverka agent: engine=${engine} driver=${driver.name}`);
+	const result = await driver.executeAgent(request);
+	if (result.finishReason === "error") {
+		output.errorLine("sverka agent: agent finished with reason 'error'");
+		return ExitCode.RuntimeError;
+	}
+	await writeArtifacts(outDir, result, collectAgentWrites(result));
+	if (result.text !== "") output.writeLine(result.text);
+	return ExitCode.Success;
+}
+/**
+* SVERKA_MENTION carries one mention string, or a JSON array when several
+* comment entries with different mentions reach the same job.
+*/
+function parseMentionList(raw) {
+	if (raw === void 0) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((m) => typeof m === "string")) return parsed;
+	} catch {}
+	return [raw];
+}
+function parseMaxTokens(raw) {
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n <= 0) throw new CliError(`sverka agent: ${AGENT_ENV.maxTokens} must be a positive integer, got '${raw}'`, "INVALID_FLAG", ExitCode.UsageError);
+	return n;
+}
+async function writeArtifacts(dir, result, writes = []) {
+	await writeFile(join(dir, RESULT_FILE), JSON.stringify(result, null, 2), "utf-8");
+	await writeFile(join(dir, WRITES_FILE$1), JSON.stringify({ writes }, null, 2), "utf-8");
+}
+//#endregion
+//#region src/commands/apply.ts
+const WRITES_FILE = "sverka-writes.json";
+const DECLARATIONS_ENV = "SVERKA_WRITE_DECLARATIONS";
+/** Write kinds `sverka apply` can execute. Everything else fails loudly. */
+const SUPPORTED_WRITE_KINDS = /* @__PURE__ */ new Set(["comment"]);
+async function applyCommand(args, global, output, _start) {
+	const provider = args.provider ?? detectProvider();
+	const writes = await loadWrites(args.file ?? join(global.root, WRITES_FILE));
+	const declarations = loadDeclarations();
+	const applied = [];
+	for (const write of writes) {
+		if (!declarations.some((d) => d.kind === write.kind)) throw new CliError(`sverka apply: write kind '${write.kind}' is not declared in permissions.write (declarations: ${declarations.map((d) => d.kind).join(", ") || "none"})`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+		if (!SUPPORTED_WRITE_KINDS.has(write.kind)) throw new CliError(`sverka apply: write kind '${write.kind}' is declared but not supported by sverka apply (supported: ${[...SUPPORTED_WRITE_KINDS].join(", ")})`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+		applied.push(await applyWrite(provider, write, declarations));
+	}
+	const summary = applied.length > 0 ? ` — ${applied.join("; ")}` : "";
+	output.writeLine(`sverka apply: applied ${applied.length} write(s) via ${provider}${summary}`);
+	return ExitCode.Success;
+}
+function detectProvider() {
+	if (process$1.env["GITLAB_CI"] !== void 0 || process$1.env["CI_API_V4_URL"]) return "gitlab";
+	if (process$1.env["GITHUB_ACTIONS"] !== void 0) return "github";
+	throw new CliError("sverka apply: --provider is required when CI provider cannot be detected (gitlab|github)", "MISSING_ARG", ExitCode.UsageError);
+}
+async function loadWrites(file) {
+	let raw;
+	try {
+		raw = await readFile(file, "utf-8");
+	} catch {
+		throw new CliError(`sverka apply: writes artifact not found: ${file} — the agent job must produce ${WRITES_FILE}`, "MISSING_ARG", ExitCode.RuntimeError);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new CliError(`sverka apply: ${WRITES_FILE} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	}
+	const items = extractWritesItems(parsed);
+	if (items === void 0) throw new CliError(`sverka apply: ${WRITES_FILE} must be an object with a 'writes' array`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	return items.map((item, i) => {
+		if (typeof item !== "object" || item === null || typeof item.kind !== "string") throw new CliError(`sverka apply: writes[${i}] must be an object with a string 'kind'`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+		return item;
+	});
+}
+/** The artifact is either a bare array or an object with a 'writes' array. */
+function extractWritesItems(parsed) {
+	if (Array.isArray(parsed)) return parsed;
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const w = parsed.writes;
+	return Array.isArray(w) ? w : void 0;
+}
+function loadDeclarations() {
+	const raw = process$1.env[DECLARATIONS_ENV];
+	if (raw === void 0 || raw === "") throw new CliError(`sverka apply: ${DECLARATIONS_ENV} is not set — the __apply job declares it from permissions.write`, "MISSING_ARG", ExitCode.RuntimeError);
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new CliError(`sverka apply: ${DECLARATIONS_ENV} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	}
+	if (!Array.isArray(parsed)) throw new CliError(`sverka apply: ${DECLARATIONS_ENV} must be a JSON array of write declarations`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	return parsed;
+}
+async function applyWrite(provider, write, declarations) {
+	if (write.kind === "comment") return provider === "gitlab" ? applyGitlabComment(write, declarations) : applyGithubComment(write);
+	throw new CliError(`sverka apply: write kind '${write.kind}' is not supported`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+}
+function requireBody(write) {
+	if (typeof write.body !== "string" || write.body === "") throw new CliError("sverka apply: comment write requires a non-empty 'body' string", "PACKAGE_ERROR", ExitCode.RuntimeError);
+	return write.body;
+}
+/**
+* The object kind a comment write targets. `write.on` wins when present
+* (and must be a known kind — anything else fails loudly rather than
+* silently falling back); otherwise the triggering context decides: a
+* forwarded MR_IID means the comment fired on a merge request.
+*/
+function resolveCommentTarget(write) {
+	if (write.on === "issue" || write.on === "merge_request") return write.on;
+	if (write.on !== void 0) throw new CliError(`sverka apply: comment write 'on' must be issue|merge_request, got '${JSON.stringify(write.on)}'`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	return process$1.env["MR_IID"] !== void 0 ? "merge_request" : "issue";
+}
+/**
+* Resolve the target iid for a comment write. When the triggering context
+* supplies an iid (the webhook forwarded MR_IID/ISSUE_IID), it wins — a
+* write.iid that disagrees is model output trying to redirect the comment
+* to another target, which fails loudly.
+*/
+function requireIid(write, envKeys) {
+	const contextRaw = envKeys.map((k) => process$1.env[k]).find((v) => v !== void 0 && v !== "");
+	if (contextRaw !== void 0) {
+		const ctx = Number(contextRaw);
+		if (!Number.isInteger(ctx) || ctx <= 0) throw new CliError(`sverka apply: context iid '${contextRaw}' is not a positive integer`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+		if (write.iid !== void 0 && Number(write.iid) !== ctx) throw new CliError(`sverka apply: write iid '${JSON.stringify(write.iid)}' does not match the triggering context iid ${ctx}`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+		return ctx;
+	}
+	if (write.iid === void 0) throw new CliError(`sverka apply: comment write needs a target iid (${envKeys.join(" or ")} env var, or an 'iid' field)`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	const n = Number(write.iid);
+	if (!Number.isInteger(n) || n <= 0) throw new CliError(`sverka apply: comment write iid must be a positive integer, got '${JSON.stringify(write.iid)}'`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	return n;
+}
+async function applyGitlabComment(write, declarations) {
+	const { api, project, token } = gitlabApplyEnv();
+	const body = requireBody(write);
+	const on = resolveCommentTarget(write);
+	if (!declarations.some((d) => d.kind === "comment" && d.target === on)) throw new CliError(`sverka apply: comment write targets '${on}' but no declaration declares it (declared comment targets: ${declarations.filter((d) => d.kind === "comment").map((d) => d.target).join(", ") || "none"})`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	const iid = requireIid(write, on === "merge_request" ? ["MR_IID"] : ["ISSUE_IID", "SVERKA_ISSUE_IID"]);
+	await postJson(`${api}${on === "merge_request" ? `/projects/${encodeURIComponent(project)}/merge_requests/${iid}/notes` : `/projects/${encodeURIComponent(project)}/issues/${iid}/notes`}`, token, { body }, "PRIVATE-TOKEN");
+	return `comment on ${on} !${iid}`;
+}
+/** Provider-supplied env for a GitLab apply call — all CI-controlled. */
+function gitlabApplyEnv() {
+	const env = process$1.env;
+	const api = env["CI_API_V4_URL"] ?? "https://gitlab.com/api/v4";
+	const project = env["CI_PROJECT_ID"];
+	if (project === void 0 || project === "") throw new CliError("sverka apply: CI_PROJECT_ID is not set — run inside a GitLab job or set it explicitly", "MISSING_ARG", ExitCode.RuntimeError);
+	const token = env["SVERKA_APPLY_TOKEN"] || env["GITLAB_TOKEN"];
+	if (token === void 0 || token === "") throw new CliError("sverka apply: SVERKA_APPLY_TOKEN is not set — scope it to the 'sverka-apply' environment (see engdocs/user/gitlab/agentic.md)", "MISSING_ARG", ExitCode.RuntimeError);
+	return {
+		api,
+		project,
+		token
+	};
+}
+async function applyGithubComment(write) {
+	const env = process$1.env;
+	const api = env["GITHUB_API_URL"] ?? "https://api.github.com";
+	const repo = env["GITHUB_REPOSITORY"];
+	if (repo === void 0 || repo === "") throw new CliError("sverka apply: GITHUB_REPOSITORY is not set — run inside a GitHub Actions job or set it explicitly", "MISSING_ARG", ExitCode.RuntimeError);
+	const token = env["SVERKA_APPLY_TOKEN"] || env["GH_TOKEN"] || env["GITHUB_TOKEN"];
+	if (token === void 0 || token === "") throw new CliError("sverka apply: GH_TOKEN/GITHUB_TOKEN is not set", "MISSING_ARG", ExitCode.RuntimeError);
+	const body = requireBody(write);
+	const issue = requireIid(write, ["SVERKA_ISSUE_IID", "ISSUE_IID"]);
+	await postJson(`${api}/repos/${repo}/issues/${issue}/comments`, token, { body }, "Bearer");
+	return `comment on issue #${issue}`;
+}
+async function postJson(url, token, body, auth) {
+	const headers = { "content-type": "application/json" };
+	if (auth === "PRIVATE-TOKEN") headers["PRIVATE-TOKEN"] = token;
+	else headers["authorization"] = `Bearer ${token}`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers,
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new CliError(`sverka apply: provider request failed (${res.status} ${res.url}): ${text.slice(0, 300)}`, "PACKAGE_ERROR", ExitCode.RuntimeError);
+	}
+}
+//#endregion
+//#region src/commands/login.ts
+async function loginCommand(args, _global, output, _start) {
+	const url = args.hub ?? process.env["SVERKA_HUB_URL"];
+	const token = args.token ?? process.env["SVERKA_HUB_TOKEN"];
+	if (url === void 0) throw new CliError("missing --hub <url> (or set SVERKA_HUB_URL)", "MISSING_ARG", ExitCode.UsageError);
+	if (!token) throw new CliError("missing --token <t> (or set SVERKA_HUB_TOKEN)", "MISSING_ARG", ExitCode.UsageError);
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new CliError(`--hub must be a URL, got "${url}"`, "INVALID_FLAG", ExitCode.UsageError);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new CliError(`--hub must be http(s), got "${parsed.protocol}"`, "INVALID_FLAG", ExitCode.UsageError);
+	const normalized = normalizeHubUrl(url);
+	const path = storeCredentials(normalized, token);
+	output.writeLine(`stored credentials for ${normalized} in ${path}`);
+	return ExitCode.Success;
+}
+//#endregion
+//#region src/commands/hub.ts
+async function hubCommand(args, global, output, _start) {
+	if (args.action !== "serve") throw new CliError(`unknown hub action "${args.action ?? ""}" (supported: serve)`, "UNKNOWN_COMMAND", ExitCode.UsageError);
+	if (args.port !== void 0 && (!Number.isInteger(args.port) || args.port < 0 || args.port > 65535)) throw new CliError("--port must be an integer in [0, 65535]", "INVALID_FLAG", ExitCode.UsageError);
+	const dataDir = args.data ?? `${global.root}/.sverka-hub`;
+	const server = await startHubServer({
+		dataDir,
+		...args.port !== void 0 ? { port: args.port } : {},
+		...args.host !== void 0 ? { host: args.host } : {}
+	});
+	output.writeLine(`sverka hub listening on ${server.url}`);
+	output.writeLine(`  data: ${server.dataDir}`);
+	output.writeLine(`  dashboard: ${server.url}/`);
+	output.writeLine("  (Ctrl+C to stop)");
+	await new Promise((done) => {
+		const stop = () => {
+			process.removeListener("SIGINT", stop);
+			process.removeListener("SIGTERM", stop);
+			done();
+		};
+		process.on("SIGINT", stop);
+		process.on("SIGTERM", stop);
+	});
+	await server.close();
+	return ExitCode.Success;
+}
+//#endregion
+//#region src/commands/runs.ts
+function listLocalRuns(root) {
+	const dir = join(root, ".sverka", "runs");
+	if (!existsSync(dir)) return [];
+	const rows = [];
+	for (const entry of readdirSync(dir)) {
+		const reportPath = join(dir, entry, "report.json");
+		if (!existsSync(reportPath)) continue;
+		let status = "unknown";
+		let findings = null;
+		try {
+			const data = JSON.parse(readFileSync(reportPath, "utf8")).data ?? {};
+			if (typeof data.status === "string") status = data.status;
+			if (typeof data.findings === "number") findings = data.findings;
+		} catch {}
+		rows.push({
+			runId: entry,
+			status,
+			findings,
+			mtimeMs: statSync(reportPath).mtimeMs
+		});
+	}
+	return rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+async function runsCommand(args, global, output, _start) {
+	if (args.remote === true) return remoteRuns(args, global, output);
+	return localRuns(args, global, output);
+}
+async function remoteRuns(args, global, output) {
+	const hub = resolveHub(global.root);
+	if (hub === null) throw new CliError("no hub configured — set SVERKA_HUB_URL + SVERKA_HUB_TOKEN, run `sverka login`, or add .sverka/hub.json", "MISSING_ARG", ExitCode.UsageError);
+	const { listRuns } = await import("@sverka/storage");
+	const runs = await listRuns(hub.config, { ...args.limit !== void 0 ? { limit: args.limit } : {} });
+	if (global.format === "json") {
+		output.writeLine(JSON.stringify({
+			command: "runs",
+			data: runs
+		}));
+		return ExitCode.Success;
+	}
+	if (runs.length === 0) {
+		output.writeLine(`no remote runs for ${hub.config.project} — run \`sverka run --remote\` to upload one`);
+		return ExitCode.Success;
+	}
+	output.writeLine(`remote runs for ${hub.config.project} (${hub.config.url})`);
+	for (const run of runs) {
+		const when = run.startedAt === null ? "—" : new Date(run.startedAt).toISOString().slice(0, 19) + "Z";
+		const duration = run.durationMs === null ? "—" : `${(run.durationMs / 1e3).toFixed(1)}s`;
+		output.writeLine(`  ${run.runId}  ${run.status.padEnd(9)} ${run.entry.padEnd(20)} ${when}  ${duration}  findings:${run.findingCounts.total}`);
+	}
+	return ExitCode.Success;
+}
+function localRuns(args, global, output) {
+	const shown = listLocalRuns(global.root).slice(0, args.limit ?? 20);
+	if (global.format === "json") {
+		output.writeLine(JSON.stringify({
+			command: "runs",
+			data: shown
+		}));
+		return ExitCode.Success;
+	}
+	if (shown.length === 0) {
+		output.writeLine("no runs recorded — run `sverka run` first");
+		return ExitCode.Success;
+	}
+	for (const run of shown) {
+		const when = new Date(run.mtimeMs).toISOString().slice(0, 19) + "Z";
+		output.writeLine(`  ${run.runId}  ${run.status.padEnd(9)} ${when}  findings:${run.findings ?? "—"}`);
+	}
+	return ExitCode.Success;
+}
+//#endregion
 //#region src/main.ts
 /** Build GlobalFlags from parsed yargs options. */
 function buildGlobalFlags(parsed) {
@@ -2334,6 +2858,10 @@ function addRunCommand(y) {
 		type: "boolean",
 		alias: "w",
 		describe: "Re-run on file changes (debounced 300ms)"
+	}).option("remote", {
+		type: "boolean",
+		default: false,
+		describe: "Remote hub run: remote cache + snapshot store + report upload"
 	});
 }
 /** Configure the plan subcommand options. */
@@ -2347,13 +2875,9 @@ function addPolicyCommand(y) {
 		demandOption: true
 	}).option("baseline", { type: "string" });
 }
-/** Configure the synth subcommand options. */
+/** Configure the synth subcommand options. Alias for compile — same flags. */
 function addSynthCommand(y) {
-	return y.option("target", {
-		type: "string",
-		demandOption: true,
-		choices: ["github", "gitlab"]
-	});
+	return addCompileCommand(y);
 }
 /** Configure the compile subcommand options. */
 function addCompileCommand(y) {
@@ -2407,6 +2931,45 @@ function addUiCommand(y) {
 		describe: "Host to bind"
 	});
 }
+/** Configure the login subcommand options. */
+function addLoginCommand(y) {
+	return y.option("hub", {
+		type: "string",
+		describe: "Hub base URL (or SVERKA_HUB_URL)"
+	}).option("token", {
+		type: "string",
+		describe: "Hub bearer token (or SVERKA_HUB_TOKEN)"
+	});
+}
+/** Configure the hub subcommand options. */
+function addHubCommand(y) {
+	return y.positional("action", {
+		type: "string",
+		choices: ["serve"],
+		describe: "hub action (serve)"
+	}).option("port", {
+		type: "number",
+		default: 7357,
+		describe: "Port to listen on"
+	}).option("host", {
+		type: "string",
+		describe: "Host to bind"
+	}).option("data", {
+		type: "string",
+		describe: "Data directory (default: .sverka-hub under --root)"
+	});
+}
+/** Configure the runs subcommand options. */
+function addRunsCommand(y) {
+	return y.option("remote", {
+		type: "boolean",
+		default: false,
+		describe: "List runs stored on the configured hub"
+	}).option("limit", {
+		type: "number",
+		describe: "Max runs to list"
+	});
+}
 function buildParser() {
 	return yargs([]).scriptName("sverka").version(cliVersion()).option("format", {
 		type: "string",
@@ -2433,7 +2996,17 @@ function buildParser() {
 		type: "boolean",
 		alias: "v",
 		default: false
-	}).command("init", "Create a sverka.config.ts", addInitCommand).command("validate", "Validate a sverka config").command("plan", "Bind Entry + inputs → Run Plan", addPlanCommand).command("graph", "Display the Definition Graph").command("run", "Execute the workflow locally", addRunCommand).command("discover", "Discover and display project context").command("check", "Resolve proposed checks → StepDefinitions").command("policy", "Evaluate findings against policy", addPolicyCommand).command("synth", "Alias for compile — compile to a target CI YAML", addSynthCommand).command("compile", "Compile to a target CI YAML", addCompileCommand).command("mcp-server", "Expose Sverka as an MCP server (stdio)").command("doctor", "Diagnose environment and dependencies").command("view [file]", "Open the latest run report, or view SARIF findings (TUI/HTML)", addViewCommand).command("ui", "Start local web dashboard server", addUiCommand).demandCommand(1, "No command given").strict().fail((msg, err) => {
+	}).command("init", "Create a sverka.config.ts", addInitCommand).command("validate", "Validate a sverka config").command("plan", "Bind Entry + inputs → Run Plan", addPlanCommand).command("graph", "Display the Definition Graph").command("run", "Execute the workflow locally", addRunCommand).command("discover", "Discover and display project context").command("check", "Resolve proposed checks → StepDefinitions").command("policy", "Evaluate findings against policy", addPolicyCommand).command("synth", "Alias for compile — compile to a target CI YAML", addSynthCommand).command("compile", "Compile to a target CI YAML", addCompileCommand).command("mcp-server", "Expose Sverka as an MCP server (stdio)").command("doctor", "Diagnose environment and dependencies").command("view [file]", "Open the latest run report, or view SARIF findings (TUI/HTML)", addViewCommand).command("ui", "Start local web dashboard server", addUiCommand).command("agent", "Run a single agent step from SVERKA_AGENT_* env (CI agent jobs)", (y) => y.option("output-dir", {
+		type: "string",
+		describe: "Directory for agent-result.json + sverka-writes.json (default: root)"
+	})).command("apply", "Validate + apply agent writes artifact (CI __apply jobs)", (y) => y.option("provider", {
+		type: "string",
+		choices: ["gitlab", "github"],
+		describe: "CI provider (auto-detected from CI env when omitted)"
+	}).option("file", {
+		type: "string",
+		describe: "Path to sverka-writes.json (default: <root>/sverka-writes.json)"
+	})).command("login", "Store hub credentials (~/.config/sverka/credentials)", addLoginCommand).command("hub <action>", "Self-hosted run hub (serve: cache + history + findings)", addHubCommand).command("runs", "List run history (local, or --remote)", addRunsCommand).demandCommand(1, "No command given").strict().fail((msg, err) => {
 		if (err) throw err;
 		throw new CliError(msg, "UNKNOWN_COMMAND", ExitCode.UsageError);
 	});
@@ -2455,6 +3028,11 @@ async function dispatch(command, parsed, global, output, start) {
 		case "doctor": return doctorCommand(global, output, start);
 		case "view": return dispatchView(parsed, global, output, start);
 		case "ui": return dispatchUi(parsed, global, output, start);
+		case "agent": return dispatchAgent(parsed, global, output, start);
+		case "apply": return dispatchApply(parsed, global, output, start);
+		case "login": return dispatchLogin(parsed, global, output, start);
+		case "hub": return dispatchHub(parsed, global, output, start);
+		case "runs": return dispatchRuns(parsed, global, output, start);
 		default: throw new CliError(`unknown command: ${command}`, "UNKNOWN_COMMAND", ExitCode.UsageError);
 	}
 }
@@ -2491,6 +3069,7 @@ function dispatchRun(parsed, global, output, start) {
 	if (parsed.tui === true) args.tui = true;
 	if (parsed.tui === false) args.tui = false;
 	if (parsed.watch === true) args.watch = true;
+	if (parsed.remote === true) args.remote = true;
 	return runCommand(args, global, output, start);
 }
 function dispatchPolicy(parsed, global, output, start) {
@@ -2499,7 +3078,11 @@ function dispatchPolicy(parsed, global, output, start) {
 	return policyCommand(args, global, output, start);
 }
 function dispatchSynth(parsed, global, output, start) {
-	return synthCommand({ target: parsed.target === "gitlab" ? "gitlab" : "github" }, global, output, start);
+	const args = { target: parsed.target === "gitlab" ? "gitlab" : "github" };
+	if (typeof parsed.output === "string") args.output = parsed.output;
+	if (typeof parsed.outputDir === "string") args.outputDir = parsed.outputDir;
+	if (parsed.pin === true) args.pin = true;
+	return synthCommand(args, global, output, start);
 }
 function dispatchCompile(parsed, global, output, start) {
 	const args = { target: parsed.target === "gitlab" ? "gitlab" : "github" };
@@ -2520,6 +3103,36 @@ function dispatchUi(parsed, global, output, start) {
 	if (typeof parsed.host === "string") args.host = parsed.host;
 	return uiCommand(args, global, output, start);
 }
+function dispatchAgent(parsed, global, output, start) {
+	const args = {};
+	if (typeof parsed.outputDir === "string") args.outputDir = parsed.outputDir;
+	return agentCommand(args, global, output, start);
+}
+function dispatchApply(parsed, global, output, start) {
+	const args = {};
+	if (parsed.provider === "gitlab" || parsed.provider === "github") args.provider = parsed.provider;
+	if (typeof parsed.file === "string") args.file = parsed.file;
+	return applyCommand(args, global, output, start);
+}
+function dispatchLogin(parsed, global, output, start) {
+	const args = {};
+	if (typeof parsed.hub === "string") args.hub = parsed.hub;
+	if (typeof parsed.token === "string") args.token = parsed.token;
+	return loginCommand(args, global, output, start);
+}
+function dispatchHub(parsed, global, output, start) {
+	const args = {};
+	if (typeof parsed.action === "string") args.action = parsed.action;
+	if (typeof parsed.port === "number") args.port = parsed.port;
+	if (typeof parsed.data === "string") args.data = parsed.data;
+	if (typeof parsed.host === "string") args.host = parsed.host;
+	return hubCommand(args, global, output, start);
+}
+function dispatchRuns(parsed, global, output, start) {
+	const args = { remote: parsed.remote === true };
+	if (typeof parsed.limit === "number") args.limit = parsed.limit;
+	return runsCommand(args, global, output, start);
+}
 /**
 * The main CLI entry point.
 * @param argv Command-line arguments (excluding node and script path).