@gaodes/pi-gitlab 0.3.0

package/src/lib/confirm.ts

@@ -0,0 +1,47 @@
+/**
+ * Confirmation UX for mutating tools.
+ *
+ * Pattern:
+ *   1. Tool builds a preview string describing the mutation.
+ *   2. If `dryRun: true` → return preview only.
+ *   3. If `confirm: true` → execute the mutation.
+ *   4. Otherwise → return an error asking the user to set `confirm: true`.
+ */
+
+export interface ConfirmResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}
+
+export function requireConfirm(
+	preview: string,
+	params: { dryRun?: boolean; confirm?: boolean },
+): ConfirmResult | null {
+	if (params.dryRun) {
+		return {
+			content: [
+				{
+					type: "text",
+					text: `🔍 Preview\n\n${preview}\n\n_Set \`confirm: true\` to execute._`,
+				},
+			],
+			details: { success: true, preview, dryRun: true },
+		};
+	}
+
+	if (!params.confirm) {
+		return {
+			content: [
+				{
+					type: "text",
+					text:
+						`⚠️ Mutating operation requires confirmation.\n\n${preview}\n\n` +
+						`Set \`confirm: true\` to proceed, or \`dryRun: true\` to preview only.`,
+				},
+			],
+			details: { success: false, error: "confirmation_required", preview },
+		};
+	}
+
+	return null;
+}

package/src/lib/env.ts

@@ -0,0 +1,48 @@
+/**
+ * Environment / config helpers for pi-gitlab.
+ *
+ * Phase 1 hard guard: tools must block until both PI_GITLAB_TOKEN and
+ * pi-gitlab config are present. Auto-seeding is intentionally
+ * removed from extension load; seeding now lives in explicit doctor/setup flows.
+ */
+
+import { checkSetup } from "../config/guard.js";
+import {
+	GLOBAL_SETTINGS_PATH,
+	ensureConfig,
+	loadConfig,
+} from "../config/loader.js";
+
+export { GLOBAL_SETTINGS_PATH, ensureConfig, loadConfig };
+
+// ---------------------------------------------------------------------------
+// Token access
+// ---------------------------------------------------------------------------
+
+/** Get the effective GitLab token from env or config. */
+export function getToken(): string | undefined {
+	const config = loadConfig();
+	const envKey = config.tokenEnv || "PI_GITLAB_TOKEN";
+	const val = process.env[envKey];
+	return val?.trim() ? val.trim() : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Derived helpers
+// ---------------------------------------------------------------------------
+
+/** Returns the effective API hostname from config (or GITLAB_HOST env override). */
+export function getApiHost(): string {
+	if (process.env.GITLAB_HOST) return process.env.GITLAB_HOST;
+	return loadConfig().hostname;
+}
+
+/** Returns the SSH hostname for git remotes. */
+export function getSshHost(): string {
+	return loadConfig().sshHostname;
+}
+
+/** Returns the SSH port for git remotes. */
+export function getSshPort(): number {
+	return loadConfig().sshPort;
+}

package/src/lib/errors.ts

@@ -0,0 +1,156 @@
+// ---------------------------------------------------------------------------
+// GlabError — pre-existing, used by lib/glab.ts
+// ---------------------------------------------------------------------------
+
+/** Structured error for glab CLI invocation failures. */
+export class GlabError extends Error {
+	constructor(
+		message: string,
+		public readonly code: GlabErrorCode,
+		public readonly cause?: unknown,
+		public readonly stderr?: string,
+		public readonly exitCode?: number,
+	) {
+		super(message);
+		this.name = "GlabError";
+	}
+}
+
+export enum GlabErrorCode {
+	NOT_FOUND = "NOT_FOUND",
+	EXEC_FAILED = "EXEC_FAILED",
+	PARSE_FAILED = "PARSE_FAILED",
+	VERSION_TOO_OLD = "VERSION_TOO_OLD",
+	AUTH_FAILED = "AUTH_FAILED",
+	NETWORK_ERROR = "NETWORK_ERROR",
+	API_ERROR = "API_ERROR",
+	UNKNOWN = "UNKNOWN",
+}
+
+/** Map a glab process error to a GlabError. */
+export function mapGlabError(
+	err: unknown,
+	stderr?: string,
+	exitCode?: number,
+): GlabError {
+	if (err instanceof GlabError) return err;
+
+	const message = err instanceof Error ? err.message : String(err);
+
+	if (message.includes("command not found") || message.includes("ENOENT")) {
+		return new GlabError(
+			"glab CLI not found. Install glab >= 1.40.0 or run /gitlab-doctor.",
+			GlabErrorCode.NOT_FOUND,
+			err,
+			stderr,
+			exitCode,
+		);
+	}
+
+	if (stderr) {
+		if (
+			stderr.includes("401") ||
+			stderr.includes("403") ||
+			stderr.includes("unauthorized") ||
+			stderr.includes("authentication required")
+		) {
+			return new GlabError(
+				"GitLab authentication failed. Check PI_GITLAB_TOKEN.",
+				GlabErrorCode.AUTH_FAILED,
+				err,
+				stderr,
+				exitCode,
+			);
+		}
+		if (
+			stderr.includes("404") ||
+			stderr.includes("not found") ||
+			stderr.includes("Could not resolve")
+		) {
+			return new GlabError(
+				`GitLab API error: ${stderr.slice(0, 300)}`,
+				GlabErrorCode.API_ERROR,
+				err,
+				stderr,
+				exitCode,
+			);
+		}
+		if (
+			stderr.includes("ETIMEDOUT") ||
+			stderr.includes("ECONNREFUSED") ||
+			stderr.includes("timeout") ||
+			stderr.includes("getaddrinfo")
+		) {
+			return new GlabError(
+				`GitLab network error: ${stderr.slice(0, 300)}`,
+				GlabErrorCode.NETWORK_ERROR,
+				err,
+				stderr,
+				exitCode,
+			);
+		}
+	}
+
+	return new GlabError(message, GlabErrorCode.UNKNOWN, err, stderr, exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// SetupRequiredError — Phase 1C: setup guard integration
+// ---------------------------------------------------------------------------
+
+import { checkSetup } from "../config/guard.js";
+
+/**
+ * Error thrown when GitLab is not configured.
+ * Caught at the tool level; results in an actionable message to the agent.
+ */
+export class SetupRequiredError extends Error {
+	readonly type = "SetupRequiredError";
+	constructor(message: string) {
+		super(message);
+		this.name = "SetupRequiredError";
+	}
+}
+
+/**
+ * Guard: throws SetupRequiredError if GitLab is not fully configured.
+ * Call at the top of each tool's execute() function.
+ *
+ * Phase 1 hard guard — blocks tool usage until both the token and
+ * explicit pi-gitlab config exist in prime-settings.json.
+ * Auto-seeding is intentionally removed from extension load; use
+ * /gitlab-doctor or explicit setup flows first.
+ */
+export function requireSetup(cwd?: string): void {
+	const status = checkSetup(cwd);
+	if (status.ready) return;
+
+	const message =
+		"GitLab is not configured for pi-gitlab. " +
+		"Run the `/gitlab-doctor` command to see what needs to be set up, " +
+		"then follow the guided setup to add your GitLab host and token to `prime-settings.json`.";
+
+	throw new SetupRequiredError(message);
+}
+
+/**
+ * Returns a tool-error result when GitLab has not been configured.
+ * Use in tool execute() when requireSetup() would throw.
+ */
+export function setupRequiredResult(): {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+} {
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text:
+					"GitLab is not configured. " +
+					"Run `/gitlab-doctor` to see what needs to be set up, " +
+					"then follow the guided setup to add your GitLab host and token to `prime-settings.json`.",
+			},
+		],
+		details: { success: false, error: "setup_required" },
+	};
+}

package/src/lib/gitRemoteParse.ts

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function getGitRemoteProjectPath(
+	cwd?: string,
+): Promise<string | undefined> {
+	try {
+		const { stdout } = await execFileAsync(
+			"git",
+			["remote", "get-url", "origin"],
+			{ cwd },
+		);
+		return parseGitUrl(stdout.trim());
+	} catch {
+		return undefined;
+	}
+}
+
+export function parseGitUrl(url: string): string | undefined {
+	if (url.startsWith("git@")) {
+		const idx = url.indexOf(":");
+		if (idx === -1) return undefined;
+		let path = url.slice(idx + 1);
+		// Strip SSH port prefix if present: git@host:2222/path
+		if (/^\d+\//.test(path)) {
+			path = path.replace(/^\d+\//, "");
+		}
+		return path.replace(/\.git$/, "");
+	}
+	if (url.startsWith("http")) {
+		try {
+			const u = new URL(url);
+			return u.pathname.replace(/^\//, "").replace(/\.git$/, "");
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}

package/src/lib/glab.ts

@@ -0,0 +1,34 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function glab(args: string[], cwd?: string): Promise<unknown> {
+	try {
+		const { stdout, stderr } = await execFileAsync("glab", args, {
+			cwd,
+			encoding: "utf-8",
+			maxBuffer: 10 * 1024 * 1024,
+			env: process.env,
+		});
+
+		if (stderr?.trim() && !stdout.trim()) {
+			throw new Error(stderr.trim());
+		}
+
+		const text = stdout.trim();
+		if (!text) return {};
+		try {
+			return JSON.parse(text);
+		} catch {
+			return text;
+		}
+	} catch (err: unknown) {
+		const message =
+			(err as { stderr?: string; stdout?: string; message?: string })?.stderr ||
+			(err as { stderr?: string; stdout?: string; message?: string })?.stdout ||
+			(err as { message?: string })?.message ||
+			"glab command failed";
+		throw new Error(String(message).trim());
+	}
+}

package/src/lib/pagination.ts

@@ -0,0 +1,3 @@
+export function limitRows<T>(rows: T[], maxRows: number): T[] {
+	return rows.slice(0, maxRows);
+}

package/src/lib/projectCache.ts

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ProjectCache } from "../config/types.js";
+
+const CACHE_DIR = join(homedir(), ".pi", "agent", "cache", "pi-gitlab");
+const CACHE_PATH = join(CACHE_DIR, "projects.json");
+
+function readCache(): ProjectCache {
+	if (!existsSync(CACHE_PATH)) {
+		return { version: 1, entries: {} };
+	}
+	try {
+		const raw = readFileSync(CACHE_PATH, "utf-8");
+		return JSON.parse(raw) as ProjectCache;
+	} catch {
+		return { version: 1, entries: {} };
+	}
+}
+
+function writeCache(cache: ProjectCache): void {
+	mkdirSync(CACHE_DIR, { recursive: true });
+	writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2));
+}
+
+export function getCachedId(pathWithNamespace: string): number | undefined {
+	const cache = readCache();
+	return cache.entries[pathWithNamespace]?.id;
+}
+
+export function setCachedId(pathWithNamespace: string, id: number): void {
+	const cache = readCache();
+	cache.entries[pathWithNamespace] = {
+		id,
+		pathWithNamespace,
+		resolvedAt: new Date().toISOString(),
+	};
+	writeCache(cache);
+}

package/src/lib/projectFallback.ts

@@ -0,0 +1,19 @@
+import { loadConfig } from "../config/loader.js";
+import { getGitRemoteProjectPath } from "./gitRemoteParse.js";
+
+export async function resolveProject(
+	project?: string,
+	cwd?: string,
+): Promise<string> {
+	if (project) return project;
+
+	const gitPath = await getGitRemoteProjectPath(cwd);
+	if (gitPath) return gitPath;
+
+	const config = loadConfig(cwd);
+	if (config.defaultProjectPath) return config.defaultProjectPath;
+
+	throw new Error(
+		"No project specified and could not determine default from git remote or settings.",
+	);
+}

package/src/lib/redact.ts

@@ -0,0 +1,24 @@
+const PATTERNS: Array<{ regex: RegExp; replacement: string }> = [
+	{ regex: /token=[\w-]+/gi, replacement: "token=***REDACTED***" },
+	{ regex: /Bearer\s+[\w-]+/gi, replacement: "Bearer ***REDACTED***" },
+	{ regex: /password=[^\s&]+/gi, replacement: "password=***REDACTED***" },
+	{ regex: /secret=[^\s&]+/gi, replacement: "secret=***REDACTED***" },
+	{ regex: /key=[A-Za-z0-9+/=]{20,}/gi, replacement: "key=***REDACTED***" },
+	{
+		regex: /AWS_ACCESS_KEY_ID=[A-Z0-9]{20}/gi,
+		replacement: "AWS_ACCESS_KEY_ID=***REDACTED***",
+	},
+	{
+		regex: /AWS_SECRET_ACCESS_KEY=[A-Za-z0-9/+=]{40}/gi,
+		replacement: "AWS_SECRET_ACCESS_KEY=***REDACTED***",
+	},
+	{ regex: /glpat-[a-zA-Z0-9-]{20}/g, replacement: "***REDACTED***" },
+	{ regex: /ghp_[a-zA-Z0-9]{36}/g, replacement: "***REDACTED***" },
+];
+
+export function redact(text: string): string {
+	return PATTERNS.reduce(
+		(acc, { regex, replacement }) => acc.replace(regex, replacement),
+		text,
+	);
+}

package/src/lib/resolveProjectId.ts

@@ -0,0 +1,37 @@
+import { glab } from "./glab.js";
+import { getCachedId, setCachedId } from "./projectCache.js";
+
+export async function resolveProjectId(
+	project: string,
+	force = false,
+): Promise<number> {
+	const numeric = Number(project);
+	if (!Number.isNaN(numeric) && numeric > 0) {
+		try {
+			await glab(["api", `projects/${numeric}`]);
+			return numeric;
+		} catch {
+			throw new Error(`Project ID ${numeric} not found or not accessible.`);
+		}
+	}
+
+	if (!force) {
+		const cached = getCachedId(project);
+		if (cached) return cached;
+	}
+
+	const lastSegment = project.split("/").pop() ?? project;
+	const results = (await glab([
+		"api",
+		"--paginate",
+		`projects?search=${encodeURIComponent(lastSegment)}&per_page=100`,
+	])) as Array<{ id: number; path_with_namespace: string }>;
+
+	const match = results.find((r) => r.path_with_namespace === project);
+	if (!match) {
+		throw new Error(`Project '${project}' not found.`);
+	}
+
+	setCachedId(project, match.id);
+	return match.id;
+}

package/src/lib/schemas.ts

@@ -0,0 +1,16 @@
+import { Type } from "typebox";
+
+export const OptionalProject = Type.Optional(
+	Type.String({
+		description:
+			"Project path (e.g. 'agents/primecodex/packages/pi-gitlab') or numeric ID. Optional — falls back to CWD git remote, then settings default.",
+	}),
+);
+
+export const MaxRows = Type.Optional(
+	Type.Number({
+		default: 25,
+		maximum: 200,
+		description: "Maximum rows to return.",
+	}),
+);

package/src/tools/IMPLEMENTATION-NOTE-1B.md

@@ -0,0 +1,33 @@
+# Phase 1B Implementation Note
+
+## Files implemented
+- `src/lib/glab.ts` — glab CLI wrapper with JSON parsing and error handling
+- `src/lib/env.ts` — token/config helpers (fixed broken `ensureConfig` import from parallel edit)
+- `src/lib/projectCache.ts` — atomic read/write cache at `~/.pi/agent/cache/pi-gitlab/projects.json`
+- `src/lib/gitRemoteParse.ts` — parse git remote URL to namespace/path
+- `src/lib/projectFallback.ts` — resolve project from arg → git remote → settings default
+- `src/lib/resolveProjectId.ts` — path → numeric ID via cache + paginated glab search
+- `src/lib/pagination.ts` — client-side row limiting
+- `src/lib/redact.ts` — regex-based secret redaction for job logs
+- `src/lib/schemas.ts` — shared TypeBox parameter schemas
+- `src/tools/gitlab_project_resolve.ts` — resolve + cache project ID
+- `src/tools/gitlab_mr_list.ts` — filtered MR list with markdown table output
+- `src/tools/gitlab_mr_view.ts` — MR metadata, discussions, optional diff
+- `src/tools/gitlab_issue_list.ts` — filtered issue list with markdown table output
+- `src/tools/gitlab_pipeline_status.ts` — pipeline + optional job status
+- `src/tools/gitlab_job_logs.ts` — tail + redaction of CI job trace
+- `src/tools/gitlab_api.ts` — raw passthrough with `:project` substitution; DELETE gated by `confirm:true`
+
+## Design decisions
+- All list tools use `glab api --paginate` with `per_page=100` then client-side `limitRows()` to respect `maxRows` param.
+- All tools return `{ content: [{type: "text", text: markdown}], details: { success: true, ... } }` for Pi consumption.
+- `gitlab_api` converts `body` into `-f key=value` args; nested values are JSON-stringified. Mutating verbs show a preview line.
+- `gitlab_job_logs` fetches `/jobs/:id/trace` which returns plain text; `redact()` applies before tail truncation.
+- No wiring/index/command/events/skills were edited per task constraint.
+
+## Known limitations
+- `gitlab_api` body handling via `-f` is best-effort for flat objects; complex nested bodies may need manual `glab api` invocation.
+- `gitlab_mr_view` diff truncation is hard-limited to 2000 chars per file; no paging.
+
+## Pre-existing errors (not in scope)
+- `src/index.ts` and `src/commands/gitlab-doctor.ts` have compile errors from Phase 1A/1C parallel work.

package/src/tools/gitlab_api.ts

@@ -0,0 +1,146 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { requireSetup, setupRequiredResult } from "../lib/errors.js";
+import { glab } from "../lib/glab.js";
+import { resolveProject } from "../lib/projectFallback.js";
+import { resolveProjectId } from "../lib/resolveProjectId.js";
+
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+export function registerGitlabApi(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "gitlab_api",
+		label: "GitLab API Passthrough",
+		description:
+			"Raw glab api passthrough with automatic numeric-project-ID resolution. Mutating methods require explicit confirmation.",
+		parameters: Type.Object(
+			{
+				method: Type.Optional(
+					Type.Union(
+						[
+							Type.Literal("GET"),
+							Type.Literal("POST"),
+							Type.Literal("PUT"),
+							Type.Literal("PATCH"),
+							Type.Literal("DELETE"),
+						],
+						{ default: "GET" },
+					),
+				),
+				endpoint: Type.String({
+					description:
+						"Endpoint with optional ':project' placeholder. Use numeric IDs for other path segments.",
+				}),
+				project: Type.Optional(
+					Type.String({
+						description: "Required if endpoint contains ':project'.",
+					}),
+				),
+				body: Type.Optional(Type.Object({}, { additionalProperties: true })),
+				query: Type.Optional(Type.Object({}, { additionalProperties: true })),
+				confirm: Type.Optional(
+					Type.Boolean({
+						description:
+							"Explicit confirmation flag required for mutating methods (POST/PUT/PATCH/DELETE).",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		async execute(
+			_toolCallId,
+			params,
+			_signal,
+			_onUpdate,
+			ctx: ExtensionContext,
+		) {
+			try {
+				requireSetup(ctx.cwd);
+			} catch {
+				return setupRequiredResult();
+			}
+			const method = params.method ?? "GET";
+			const isMutating = MUTATING_METHODS.has(method);
+
+			if (isMutating && params.confirm !== true) {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								"⚠️ Mutating GitLab API calls require explicit `confirm: true`. " +
+								"Set confirm:true to proceed, or use GET for read-only requests.",
+						},
+					],
+					details: { success: false, error: "confirmation_required" },
+				};
+			}
+
+			let endpoint = params.endpoint;
+
+			if (endpoint.includes(":project")) {
+				if (!params.project) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "Endpoint contains `:project` but no `project` parameter was provided.",
+							},
+						],
+						details: { success: false, error: "missing_project" },
+					};
+				}
+				const cwd = ctx.cwd;
+				const projectPath = await resolveProject(params.project, cwd);
+				const projectId = await resolveProjectId(projectPath);
+				endpoint = endpoint.replace(":project", String(projectId));
+			}
+
+			if (params.query && Object.keys(params.query).length > 0) {
+				const qs = new URLSearchParams();
+				for (const [k, v] of Object.entries(params.query)) {
+					if (v !== undefined) qs.set(k, String(v));
+				}
+				endpoint = `${endpoint}${endpoint.includes("?") ? "&" : "?"}${qs.toString()}`;
+			}
+
+			const args = ["api"];
+			if (method !== "GET") {
+				args.push("-X", method);
+			}
+			if (params.body && Object.keys(params.body).length > 0) {
+				for (const [k, v] of Object.entries(params.body)) {
+					if (v === undefined) continue;
+					args.push(
+						"-f",
+						`${k}=${typeof v === "string" ? v : JSON.stringify(v)}`,
+					);
+				}
+			}
+			args.push(endpoint);
+
+			const result = await glab(args);
+
+			const text =
+				typeof result === "string" ? result : JSON.stringify(result, null, 2);
+
+			const preview =
+				isMutating && method !== "DELETE"
+					? `**${method}** \`${endpoint}\`\n\n`
+					: "";
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `${preview}\`\`\`json\n${text.slice(0, 3000)}\n\`\`\``,
+					},
+				],
+				details: { success: true, method, endpoint, result },
+			};
+		},
+	});
+}