@gaodes/pi-gitlab 0.3.0

package/src/commands/gitlab-doctor.ts

@@ -0,0 +1,228 @@
+/**
+ * /gitlab-doctor — diagnostics and interactive setup for pi-gitlab.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { checkSetup } from "../config/guard.js";
+import { loadConfig, writeConfig } from "../config/loader.js";
+import { getApiHost } from "../lib/env.js";
+
+const MIN_GLAB_VERSION = "1.40.0";
+
+interface Check {
+	label: string;
+	status: "pass" | "fail" | "warn" | "info";
+	detail: string;
+}
+
+function versionSatisfies(installed: string, required: string): boolean {
+	const [majI = 0, minI = 0, patI = 0] = installed
+		.split(".")
+		.map((n) => Number(n) || 0);
+	const [majR = 0, minR = 0, patR = 0] = required
+		.split(".")
+		.map((n) => Number(n) || 0);
+	if (majI > majR) return true;
+	if (majI < majR) return false;
+	if (minI > minR) return true;
+	if (minI < minR) return false;
+	return patI >= patR;
+}
+
+export async function runDoctor(pi: ExtensionAPI, cwd?: string): Promise<Check[]> {
+	const checks: Check[] = [];
+
+	try {
+		const { stdout } = await pi.exec("glab", ["--version"]);
+		const versionMatch = stdout.match(/glab ([\d.]+)/);
+		if (!versionMatch) {
+			checks.push({
+				label: "glab CLI",
+				status: "fail",
+				detail: `Unexpected --version output: ${stdout.trim()}`,
+			});
+		} else {
+			const installed = versionMatch[1];
+			const ok = versionSatisfies(installed, MIN_GLAB_VERSION);
+			checks.push({
+				label: "glab CLI version",
+				status: ok ? "pass" : "fail",
+				detail: ok
+					? `glab ${installed} (meets minimum ${MIN_GLAB_VERSION})`
+					: `glab ${installed} — below minimum ${MIN_GLAB_VERSION}. Run: brew upgrade glab`,
+			});
+		}
+	} catch {
+		checks.push({
+			label: "glab CLI",
+			status: "fail",
+			detail: "glab not found in PATH. Install from: https://gitlab.com/gitlab-org/cli#installation",
+		});
+	}
+
+	try {
+		const { stdout, code } = await pi.exec("glab", ["auth", "status"]);
+		checks.push({
+			label: "glab auth",
+			status: code === 0 ? "pass" : "fail",
+			detail:
+				code === 0
+					? (stdout.trim().split("\n")[0] ?? "Authenticated")
+					: "Not authenticated. Run `glab auth login` to authenticate.",
+		});
+	} catch (err) {
+		checks.push({
+			label: "glab auth",
+			status: "fail",
+			detail: `glab auth status check failed: ${String(err)}`,
+		});
+	}
+
+	const apiHost = getApiHost();
+	try {
+		const { code, stderr } = await pi.exec("glab", [
+			"api",
+			"version",
+			"--hostname",
+			apiHost,
+		]);
+		checks.push({
+			label: `GitLab API (${apiHost})`,
+			status: code === 0 ? "pass" : "fail",
+			detail:
+				code === 0
+					? `API is reachable at ${apiHost}`
+					: `API request failed: ${stderr.trim()}`,
+		});
+	} catch (err) {
+		checks.push({
+			label: `GitLab API (${apiHost})`,
+			status: "fail",
+			detail: `Could not reach ${apiHost}: ${String(err)}`,
+		});
+	}
+
+	const setupStatus = checkSetup(cwd);
+	const hasToken = !setupStatus.missingToken;
+	const hasExplicitConfig = !setupStatus.missingConfig;
+
+	checks.push({
+		label: "pi-gitlab token",
+		status: hasToken ? "pass" : "fail",
+		detail: hasToken
+			? `Token sourced from ${setupStatus.config.tokenEnv} environment variable`
+			: `No token found. Set ${setupStatus.config.tokenEnv} in your shell or .env.1pass.`,
+	});
+
+	checks.push({
+		label: "pi-gitlab config key",
+		status: hasExplicitConfig ? "pass" : "fail",
+		detail: hasExplicitConfig
+			? "pi-gitlab configuration key found in prime-settings.json"
+			: "Missing pi-gitlab configuration key in prime-settings.json",
+	});
+
+	checks.push({
+		label: "pi-gitlab ready",
+		status: setupStatus.ready ? "pass" : "fail",
+		detail: setupStatus.ready
+			? "All checks passed — pi-gitlab tools are available."
+			: "Configuration incomplete — tools remain blocked until setup completes.",
+	});
+
+	return checks;
+}
+
+async function runSetupWizard(ctx: ExtensionContext): Promise<boolean> {
+	const current = loadConfig(ctx.cwd);
+	const proceed = await ctx.ui.confirm(
+		"Run pi-gitlab setup wizard?",
+		"pi-gitlab tools are blocked until config + token are valid. Start guided setup now?",
+	);
+	if (!proceed) return false;
+
+	const hostname =
+		(await ctx.ui.input("GitLab hostname", current.hostname)) ?? current.hostname;
+	const sshHostname =
+		(await ctx.ui.input("GitLab SSH hostname", current.sshHostname)) ??
+		current.sshHostname;
+	const sshPortRaw =
+		(await ctx.ui.input("GitLab SSH port", String(current.sshPort))) ??
+		String(current.sshPort);
+	const tokenEnv =
+		(await ctx.ui.input("Token environment variable name", current.tokenEnv)) ??
+		current.tokenEnv;
+	const defaultProjectPathInput =
+		(await ctx.ui.input(
+			"Default project path (optional)",
+			current.defaultProjectPath ?? "",
+		)) ?? "";
+
+	const sshPort = Number(sshPortRaw);
+	if (!Number.isInteger(sshPort) || sshPort <= 0) {
+		ctx.ui.notify("Invalid SSH port. Setup cancelled.", "error");
+		return false;
+	}
+
+	const defaultProjectPath = defaultProjectPathInput.trim() || null;
+
+	const confirm = await ctx.ui.confirm(
+		"Save pi-gitlab configuration?",
+		`Host: ${hostname}\nSSH: ${sshHostname}:${sshPort}\nToken env: ${tokenEnv}\nDefault project: ${defaultProjectPath ?? "(none)"}`,
+	);
+	if (!confirm) return false;
+
+	writeConfig({
+		hostname,
+		sshHostname,
+		sshPort,
+		tokenEnv,
+		defaultProjectPath,
+	});
+
+	ctx.ui.notify("Saved pi-gitlab configuration to global prime-settings.json", "info");
+
+	if (!process.env[tokenEnv] || process.env[tokenEnv]?.trim().length === 0) {
+		ctx.ui.notify(
+			`Token variable ${tokenEnv} is not set in the current environment. Set it (or load via .env.1pass) before using tools.`,
+			"warning",
+		);
+	}
+
+	return true;
+}
+
+export async function gitlabDoctorCommand(
+	_args: unknown,
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+): Promise<void> {
+	let checks = await runDoctor(pi, ctx.cwd);
+	let status = checkSetup(ctx.cwd);
+
+	if (!status.ready) {
+		const configured = await runSetupWizard(ctx);
+		if (configured) {
+			checks = await runDoctor(pi, ctx.cwd);
+			status = checkSetup(ctx.cwd);
+		}
+	}
+
+	const lines: string[] = [];
+	for (const check of checks) {
+		const icon =
+			check.status === "pass" ? "✅" : check.status === "warn" ? "⚠️" : "❌";
+		lines.push(`${icon} **${check.label}**\n   ${check.detail}`);
+	}
+
+	if (!status.ready) {
+		lines.push(
+			"\n⚠️ **Setup incomplete**\n   Tools remain blocked until both token and `pi-gitlab` config are valid.",
+		);
+	}
+
+	ctx.ui.notify(lines.join("\n\n"), "info");
+}

package/src/config/guard.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./loader.js";
+import type { PiGitlabConfig } from "./types.js";
+
+export interface SetupStatus {
+	ready: boolean;
+	missingToken: boolean;
+	missingConfig: boolean;
+	config: PiGitlabConfig;
+	issues: string[];
+}
+
+/**
+ * Check prerequisites for the pi-gitlab extension.
+ *
+ * Returns ready=true only when both PI_GITLAB_TOKEN is set AND the
+ * pi-gitlab key exists in prime-settings.json (global or project).
+ *
+ * The key alone is not enough; the extension intentionally blocks
+ * until the config is explicitly present. Auto-seeding remains
+ * available only inside explicit setup/doctor flows.
+ *
+ * If ready=false, the extension entry should block all tool usage
+ * and start the interactive setup wizard.
+ */
+export function checkSetup(cwd?: string): SetupStatus {
+	const config = loadConfig(cwd);
+	const issues: string[] = [];
+
+	const tokenValue = process.env[config.tokenEnv];
+	const missingToken = !tokenValue || tokenValue.trim().length === 0;
+
+	const hasExplicitConfig =
+		hasPiGitlabKeyInGlobal() || hasPiGitlabKeyInProject(cwd);
+	const missingConfig = !hasExplicitConfig;
+
+	if (missingToken) {
+		issues.push(
+			`Environment variable ${config.tokenEnv} is not set. ` +
+				`Set it or run the setup wizard.`,
+		);
+	}
+
+	if (missingConfig) {
+		issues.push(
+			`No pi-gitlab configuration found in prime-settings.json. ` +
+				`Run the setup wizard to create one.`,
+		);
+	}
+
+	return {
+		ready: !missingToken && !missingConfig,
+		missingToken,
+		missingConfig,
+		config,
+		issues,
+	};
+}
+
+function hasPiGitlabKeyInGlobal(): boolean {
+	try {
+		const path = join(homedir(), ".pi", "agent", "prime-settings.json");
+		if (!existsSync(path)) return false;
+		const raw = readFileSync(path, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		return (
+			parsed !== null &&
+			typeof parsed === "object" &&
+			!Array.isArray(parsed) &&
+			"pi-gitlab" in parsed
+		);
+	} catch {
+		return false;
+	}
+}
+
+function hasPiGitlabKeyInProject(cwd?: string): boolean {
+	if (!cwd) return false;
+
+	try {
+		const path = join(cwd, ".pi", "prime-settings.json");
+		if (!existsSync(path)) return false;
+		const raw = readFileSync(path, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		return (
+			parsed !== null &&
+			typeof parsed === "object" &&
+			!Array.isArray(parsed) &&
+			"pi-gitlab" in parsed
+		);
+	} catch {
+		return false;
+	}
+}

package/src/config/loader.ts

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { PiGitlabConfig } from "./types.js";
+import { DEFAULT_CONFIG } from "./types.js";
+
+const GLOBAL_SETTINGS_PATH = join(
+	homedir(),
+	".pi",
+	"agent",
+	"prime-settings.json",
+);
+
+function cloneDefaults(): PiGitlabConfig {
+	return JSON.parse(JSON.stringify(DEFAULT_CONFIG)) as PiGitlabConfig;
+}
+
+function applyOverlay(
+	base: PiGitlabConfig,
+	overlay: Record<string, unknown>,
+): void {
+	if (typeof overlay.hostname === "string")
+		base.hostname = overlay.hostname as string;
+	if (typeof overlay.sshHostname === "string")
+		base.sshHostname = overlay.sshHostname as string;
+	if (typeof overlay.sshPort === "number")
+		base.sshPort = overlay.sshPort as number;
+	if (typeof overlay.apiBase === "string")
+		base.apiBase = overlay.apiBase as string;
+	if (overlay.tokenRef !== undefined)
+		base.tokenRef = overlay.tokenRef as string | null;
+	if (typeof overlay.tokenEnv === "string")
+		base.tokenEnv = overlay.tokenEnv as string;
+	if (
+		typeof overlay.defaultProjectId === "number" ||
+		overlay.defaultProjectId === null
+	)
+		base.defaultProjectId = overlay.defaultProjectId as number | null;
+	if (
+		typeof overlay.defaultProjectPath === "string" ||
+		overlay.defaultProjectPath === null
+	)
+		base.defaultProjectPath = overlay.defaultProjectPath as string | null;
+	if (overlay.render && typeof overlay.render === "object") {
+		const r = overlay.render as Record<string, unknown>;
+		if (typeof r.tableMaxRows === "number")
+			base.render.tableMaxRows = r.tableMaxRows as number;
+		if (typeof r.diffMaxLines === "number")
+			base.render.diffMaxLines = r.diffMaxLines as number;
+		if (typeof r.logTailLines === "number")
+			base.render.logTailLines = r.logTailLines as number;
+	}
+	if (overlay.safety && typeof overlay.safety === "object") {
+		const s = overlay.safety as Record<string, unknown>;
+		if (typeof s.requireConfirmForDelete === "boolean")
+			base.safety.requireConfirmForDelete =
+				s.requireConfirmForDelete as boolean;
+		if (typeof s.previewMutatingApiCalls === "boolean")
+			base.safety.previewMutatingApiCalls =
+				s.previewMutatingApiCalls as boolean;
+		if (typeof s.redactJobLogsByDefault === "boolean")
+			base.safety.redactJobLogsByDefault = s.redactJobLogsByDefault as boolean;
+		if (typeof s.forcePushReprotectAlways === "boolean")
+			base.safety.forcePushReprotectAlways =
+				s.forcePushReprotectAlways as boolean;
+		if (typeof s.minGlabVersion === "string")
+			base.safety.minGlabVersion = s.minGlabVersion as string;
+	}
+}
+
+export function loadConfig(cwd?: string): PiGitlabConfig {
+	const base = cloneDefaults();
+
+	if (existsSync(GLOBAL_SETTINGS_PATH)) {
+		try {
+			const raw = readFileSync(GLOBAL_SETTINGS_PATH, "utf-8");
+			const parsed = JSON.parse(raw) as Record<string, unknown>;
+			if (parsed["pi-gitlab"] && typeof parsed["pi-gitlab"] === "object") {
+				applyOverlay(base, parsed["pi-gitlab"] as Record<string, unknown>);
+			}
+		} catch {
+			// malformed file — keep defaults
+		}
+	}
+
+	if (cwd) {
+		const projectSettings = join(cwd, ".pi", "prime-settings.json");
+		if (existsSync(projectSettings)) {
+			try {
+				const raw = readFileSync(projectSettings, "utf-8");
+				const parsed = JSON.parse(raw) as Record<string, unknown>;
+				if (parsed["pi-gitlab"] && typeof parsed["pi-gitlab"] === "object") {
+					applyOverlay(base, parsed["pi-gitlab"] as Record<string, unknown>);
+				}
+			} catch {
+				// malformed project overlay — ignored
+			}
+		}
+	}
+
+	return base;
+}
+
+function readGlobalSettings(): Record<string, unknown> {
+	if (!existsSync(GLOBAL_SETTINGS_PATH)) return {};
+	try {
+		return JSON.parse(readFileSync(GLOBAL_SETTINGS_PATH, "utf-8")) as Record<
+			string,
+			unknown
+		>;
+	} catch {
+		return {};
+	}
+}
+
+function writeGlobalSettings(payload: Record<string, unknown>): void {
+	const dir = join(homedir(), ".pi", "agent");
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(
+		GLOBAL_SETTINGS_PATH,
+		`${JSON.stringify(payload, null, 2)}\n`,
+		"utf-8",
+	);
+}
+
+export function ensureConfig(): void {
+	const existing = readGlobalSettings();
+	if (existing["pi-gitlab"] !== undefined) return;
+
+	const defaults = cloneDefaults();
+	writeGlobalSettings({
+		...existing,
+		"pi-gitlab": {
+			hostname: defaults.hostname,
+			sshHostname: defaults.sshHostname,
+			sshPort: defaults.sshPort,
+			apiBase: defaults.apiBase,
+			tokenRef: defaults.tokenRef,
+			tokenEnv: defaults.tokenEnv,
+			defaultProjectId: defaults.defaultProjectId,
+			defaultProjectPath: defaults.defaultProjectPath,
+			render: { ...defaults.render },
+			safety: { ...defaults.safety },
+		},
+	});
+}
+
+export function writeConfig(overrides: Partial<PiGitlabConfig>): PiGitlabConfig {
+	const existing = readGlobalSettings();
+	const base = cloneDefaults();
+	if (existing["pi-gitlab"] && typeof existing["pi-gitlab"] === "object") {
+		applyOverlay(base, existing["pi-gitlab"] as Record<string, unknown>);
+	}
+
+	const merged: PiGitlabConfig = {
+		...base,
+		...overrides,
+		render: { ...base.render, ...(overrides.render ?? {}) },
+		safety: { ...base.safety, ...(overrides.safety ?? {}) },
+	};
+
+	writeGlobalSettings({
+		...existing,
+		"pi-gitlab": merged,
+	});
+
+	return merged;
+}
+
+export { GLOBAL_SETTINGS_PATH };

package/src/config/types.ts

@@ -0,0 +1,57 @@
+/** Config shape for the pi-gitlab key in prime-settings.json */
+export interface PiGitlabConfig {
+	hostname: string;
+	sshHostname: string;
+	sshPort: number;
+	apiBase: string;
+	tokenRef: string | null;
+	tokenEnv: string;
+	defaultProjectId: number | null;
+	defaultProjectPath: string | null;
+	render: {
+		tableMaxRows: number;
+		diffMaxLines: number;
+		logTailLines: number;
+	};
+	safety: {
+		requireConfirmForDelete: boolean;
+		previewMutatingApiCalls: boolean;
+		redactJobLogsByDefault: boolean;
+		forcePushReprotectAlways: boolean;
+		minGlabVersion: string;
+	};
+}
+
+export const DEFAULT_CONFIG: PiGitlabConfig = {
+	hostname: "gitlab.elches.dev",
+	sshHostname: "gitlab-ssh.elches.dev",
+	sshPort: 2222,
+	apiBase: "https://gitlab.elches.dev/api/v4",
+	tokenRef: null,
+	tokenEnv: "PI_GITLAB_TOKEN",
+	defaultProjectId: null,
+	defaultProjectPath: null,
+	render: {
+		tableMaxRows: 25,
+		diffMaxLines: 400,
+		logTailLines: 200,
+	},
+	safety: {
+		requireConfirmForDelete: true,
+		previewMutatingApiCalls: true,
+		redactJobLogsByDefault: true,
+		forcePushReprotectAlways: true,
+		minGlabVersion: "1.40.0",
+	},
+};
+
+export interface ProjectCacheEntry {
+	id: number;
+	pathWithNamespace: string;
+	resolvedAt: string;
+}
+
+export interface ProjectCache {
+	version: 1;
+	entries: Record<string, ProjectCacheEntry>;
+}

package/src/events/resourcesDiscover.ts

@@ -0,0 +1,27 @@
+/**
+ * resources_discover handler for pi-gitlab.
+ *
+ * Registers the package's in-package skills directory so Pi's skill
+ * system discovers and exposes them.
+ *
+ * Skills live at `<package-root>/skills/` and are discovered from there.
+ * Each skill directory contains a SKILL.md with YAML frontmatter.
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Resolve the skills/ directory path relative to the package root. */
+export function getSkillsDir(): string {
+	// src/events/resourcesDiscover.ts → package root
+	const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+	const packageRoot = path.join(extensionDir, "..", "..");
+	return path.join(packageRoot, "skills");
+}
+
+/** Return value for the resources_discover event — exposes skillPaths to Pi. */
+export function registerResourcesDiscover(): { skillPaths: string[] } {
+	return {
+		skillPaths: [getSkillsDir()],
+	};
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * pi-gitlab — Pi extension for GitLab workflows via glab CLI.
+ *
+ * Phase 1 read-only tools:
+ *   gitlab_project_resolve  — resolve project path to numeric ID
+ *   gitlab_mr_list          — list merge requests
+ *   gitlab_mr_view          — view a single MR
+ *   gitlab_issue_list       — list issues
+ *   gitlab_pipeline_status  — show pipeline status
+ *   gitlab_job_logs         — fetch job logs
+ *   gitlab_api              — generic glab API wrapper
+ *
+ * Phase 2 mutating tools (require confirm:true):
+ *   gitlab_mr_create        — create a merge request
+ *   gitlab_mr_merge         — merge a merge request
+ *   gitlab_issue_create     — create an issue
+ *   gitlab_issue_close      — close an issue
+ *   gitlab_pipeline_run     — trigger a pipeline
+ *
+ * Phase 3 advanced tools:
+ *   gitlab_release_list     — list releases
+ *   gitlab_release_view     — view a single release
+ *   gitlab_release_create   — create a release (confirm:true)
+ *   gitlab_mr_bulk_approve  — bulk-approve MRs (confirm:true)
+ *   gitlab_force_push_safe  — safe force push with branch protection lifecycle (confirm:true)
+ *
+ * Commands:
+ *   /gitlab-doctor — diagnostic check for glab, auth, API, and config
+ *
+ * Configuration lives in prime-settings.json key `pi-gitlab`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { gitlabDoctorCommand } from "./commands/gitlab-doctor.js";
+import { registerResourcesDiscover } from "./events/resourcesDiscover.js";
+import { registerGitlabApi } from "./tools/gitlab_api.js";
+import { registerGitlabForcePushSafe } from "./tools/gitlab_force_push_safe.js";
+import { registerGitlabIssueClose } from "./tools/gitlab_issue_close.js";
+import { registerGitlabIssueCreate } from "./tools/gitlab_issue_create.js";
+import { registerGitlabIssueList } from "./tools/gitlab_issue_list.js";
+import { registerGitlabJobLogs } from "./tools/gitlab_job_logs.js";
+import { registerGitlabMrBulkApprove } from "./tools/gitlab_mr_bulk_approve.js";
+import { registerGitlabMrCreate } from "./tools/gitlab_mr_create.js";
+import { registerGitlabMrList } from "./tools/gitlab_mr_list.js";
+import { registerGitlabMrMerge } from "./tools/gitlab_mr_merge.js";
+import { registerGitlabMrView } from "./tools/gitlab_mr_view.js";
+import { registerGitlabPipelineRun } from "./tools/gitlab_pipeline_run.js";
+import { registerGitlabPipelineStatus } from "./tools/gitlab_pipeline_status.js";
+import { registerGitlabProjectResolve } from "./tools/gitlab_project_resolve.js";
+import { registerGitlabReleaseCreate } from "./tools/gitlab_release_create.js";
+import { registerGitlabReleaseList } from "./tools/gitlab_release_list.js";
+import { registerGitlabReleaseView } from "./tools/gitlab_release_view.js";
+
+export default function piGitlab(pi: ExtensionAPI) {
+	// Expose in-package skills
+	pi.on("resources_discover", () => registerResourcesDiscover());
+
+	// Diagnostic command
+	pi.registerCommand("gitlab-doctor", {
+		description:
+			"Run diagnostics for glab CLI, GitLab auth, API connectivity, and pi-gitlab config",
+		handler: (args, ctx) => gitlabDoctorCommand(args, ctx, pi),
+	});
+
+	// Phase 1 read-only tools
+	registerGitlabProjectResolve(pi);
+	registerGitlabMrList(pi);
+	registerGitlabMrView(pi);
+	registerGitlabIssueList(pi);
+	registerGitlabPipelineStatus(pi);
+	registerGitlabJobLogs(pi);
+	registerGitlabApi(pi);
+
+	// Phase 2 mutating tools (all require confirm:true)
+	registerGitlabMrCreate(pi);
+	registerGitlabMrMerge(pi);
+	registerGitlabIssueCreate(pi);
+	registerGitlabIssueClose(pi);
+	registerGitlabPipelineRun(pi);
+
+	// Phase 3 advanced tools
+	registerGitlabReleaseList(pi);
+	registerGitlabReleaseView(pi);
+	registerGitlabReleaseCreate(pi);
+	registerGitlabMrBulkApprove(pi);
+	registerGitlabForcePushSafe(pi);
+}