@vigolium/piolium 0.0.1

package/extensions/piolium/scheduler.ts

@@ -0,0 +1,212 @@
+/**
+ * Concurrency-capped FIFO scheduler used by every audit mode.
+ *
+ * Why this exists:
+ *   - Archon's Deep mode mandates a hard cap of 3 concurrently active
+ *     background sub-agents (deep.md "Swarm Burst Cap"). The cap is enforced
+ *     here so individual modes don't reinvent it.
+ *   - Each task gets its own AbortSignal so a long-running sub-agent can be
+ *     cancelled cleanly when the user aborts the audit.
+ *   - Per-task timeouts catch runaway model calls without stalling the whole
+ *     queue.
+ *
+ * The scheduler is intentionally tiny — no priority levels, no retries (let
+ * the caller decide policy), no work-stealing. It only does:
+ *
+ *   1. honour `maxConcurrent`
+ *   2. process tasks FIFO
+ *   3. propagate abort and timeout via AbortSignal
+ *
+ * Transcript dirs (`piolium/tmp/piolium/runs/<id>/`) are exposed as helpers
+ * so the agent runner (M2) writes to a stable, scheduler-known location.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface SchedulerOptions {
+	/** Maximum simultaneous in-flight tasks. Defaults to 3. */
+	maxConcurrent?: number;
+	/** External abort signal; aborting this aborts the scheduler and all tasks. */
+	signal?: AbortSignal;
+}
+
+export interface ScheduledTask<T> {
+	/** Stable identifier — surfaced in run dirs and logs. */
+	id: string;
+	/** Optional human label for status widgets. */
+	label?: string;
+	/** Per-task timeout in milliseconds. Omit for no timeout. */
+	timeoutMs?: number;
+	/**
+	 * Task body. Receives an AbortSignal that fires on either external abort
+	 * or timeout. Should reject promptly when the signal fires.
+	 */
+	run: (signal: AbortSignal) => Promise<T>;
+}
+
+export interface SchedulerStats {
+	maxConcurrent: number;
+	active: number;
+	pending: number;
+	completed: number;
+	failed: number;
+	aborted: boolean;
+}
+
+interface PendingEntry<T> {
+	task: ScheduledTask<T>;
+	resolve: (value: T) => void;
+	reject: (err: unknown) => void;
+}
+
+export class SchedulerAbortError extends Error {
+	constructor(message = "Scheduler aborted") {
+		super(message);
+		this.name = "SchedulerAbortError";
+	}
+}
+
+export class TaskTimeoutError extends Error {
+	constructor(
+		public readonly taskId: string,
+		public readonly timeoutMs: number,
+	) {
+		super(`Task ${taskId} timed out after ${timeoutMs}ms`);
+		this.name = "TaskTimeoutError";
+	}
+}
+
+export class Scheduler {
+	readonly maxConcurrent: number;
+	private active = 0;
+	private completed = 0;
+	private failed = 0;
+	private aborted = false;
+	private readonly queue: PendingEntry<unknown>[] = [];
+	private readonly inflight = new Set<AbortController>();
+	private readonly externalSignal?: AbortSignal;
+	private readonly externalAbortListener?: () => void;
+
+	constructor(opts: SchedulerOptions = {}) {
+		this.maxConcurrent = Math.max(1, opts.maxConcurrent ?? 3);
+		this.externalSignal = opts.signal;
+		if (this.externalSignal) {
+			if (this.externalSignal.aborted) {
+				this.aborted = true;
+			} else {
+				this.externalAbortListener = () => this.abort();
+				this.externalSignal.addEventListener("abort", this.externalAbortListener, { once: true });
+			}
+		}
+	}
+
+	enqueue<T>(task: ScheduledTask<T>): Promise<T> {
+		if (this.aborted) {
+			return Promise.reject(new SchedulerAbortError());
+		}
+		return new Promise<T>((resolve, reject) => {
+			this.queue.push({
+				task: task as ScheduledTask<unknown>,
+				resolve: resolve as (v: unknown) => void,
+				reject,
+			});
+			this.pump();
+		});
+	}
+
+	/**
+	 * Convenience: enqueue many tasks and wait for all settlements (mirrors
+	 * Promise.allSettled). The cap still applies — only `maxConcurrent` are
+	 * in-flight at once even when callers pass a giant array.
+	 */
+	async runBatch<T>(tasks: ScheduledTask<T>[]): Promise<PromiseSettledResult<T>[]> {
+		return Promise.allSettled(tasks.map((t) => this.enqueue(t)));
+	}
+
+	abort(): void {
+		if (this.aborted) return;
+		this.aborted = true;
+		// Reject everything still queued so callers stop waiting.
+		const drain = this.queue.splice(0, this.queue.length);
+		for (const entry of drain) entry.reject(new SchedulerAbortError());
+		// Cancel everything currently running.
+		for (const ctrl of this.inflight) ctrl.abort(new SchedulerAbortError());
+	}
+
+	stats(): SchedulerStats {
+		return {
+			maxConcurrent: this.maxConcurrent,
+			active: this.active,
+			pending: this.queue.length,
+			completed: this.completed,
+			failed: this.failed,
+			aborted: this.aborted,
+		};
+	}
+
+	dispose(): void {
+		this.abort();
+		if (this.externalSignal && this.externalAbortListener) {
+			this.externalSignal.removeEventListener("abort", this.externalAbortListener);
+		}
+	}
+
+	private pump(): void {
+		while (!this.aborted && this.active < this.maxConcurrent && this.queue.length > 0) {
+			const entry = this.queue.shift();
+			if (!entry) break;
+			void this.runEntry(entry);
+		}
+	}
+
+	private async runEntry(entry: PendingEntry<unknown>): Promise<void> {
+		this.active++;
+		const ctrl = new AbortController();
+		this.inflight.add(ctrl);
+		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+		if (entry.task.timeoutMs && entry.task.timeoutMs > 0) {
+			const timeoutMs = entry.task.timeoutMs;
+			timeoutHandle = setTimeout(() => {
+				ctrl.abort(new TaskTimeoutError(entry.task.id, timeoutMs));
+			}, timeoutMs);
+		}
+		try {
+			const result = await entry.task.run(ctrl.signal);
+			this.completed++;
+			entry.resolve(result);
+		} catch (err) {
+			this.failed++;
+			// Surface the timeout reason as the rejected error so callers can
+			// distinguish abort from "task threw on its own".
+			if (ctrl.signal.aborted && ctrl.signal.reason instanceof TaskTimeoutError) {
+				entry.reject(ctrl.signal.reason);
+			} else {
+				entry.reject(err);
+			}
+		} finally {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			this.inflight.delete(ctrl);
+			this.active--;
+			this.pump();
+		}
+	}
+}
+
+/**
+ * Path conventions for per-task transcript directories. Modes use these to
+ * keep raw subagent output isolated from final artifacts under `piolium/`.
+ */
+export function getRunsRoot(cwd: string): string {
+	return join(cwd, "piolium", "tmp", "piolium", "runs");
+}
+
+export function getRunDir(cwd: string, runId: string): string {
+	return join(getRunsRoot(cwd), runId);
+}
+
+export function ensureRunDir(cwd: string, runId: string): string {
+	const dir = getRunDir(cwd, runId);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	return dir;
+}

package/extensions/piolium/secrets.ts

@@ -0,0 +1,368 @@
+/**
+ * Q1 secrets scanner.
+ *
+ * Tries `trufflehog`, then `gitleaks`, then a regex-grep fallback. Each
+ * finding is materialised as `piolium/findings-draft/q1-<NNN>-<slug>.md` so
+ * later phases (consolidation, finalisation) can pick them up using the same
+ * conventions as the upstream archon-audit pipeline.
+ *
+ * Tool detection is best-effort: when a binary isn't on PATH the next
+ * fallback is tried and a note is left in the phase summary. We never throw
+ * just because a tool is missing — that's expected on slim CI runners.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type SecretsBackend = "trufflehog" | "gitleaks" | "grep" | "none";
+
+export interface SecretFinding {
+	id: string;
+	slug: string;
+	severity: "high" | "medium" | "low";
+	title: string;
+	file: string;
+	line?: number;
+	rule?: string;
+	excerpt?: string;
+	source: SecretsBackend;
+}
+
+export interface SecretsScanResult {
+	backend: SecretsBackend;
+	findings: SecretFinding[];
+	notes: string[];
+	draftPaths: string[];
+}
+
+export const Q1_SECRETS_SUMMARY = "piolium/attack-surface/lite-q1-summary.md";
+
+function which(bin: string): boolean {
+	try {
+		const res = spawnSync("command", ["-v", bin], { stdio: "ignore", shell: true });
+		return res.status === 0;
+	} catch {
+		return false;
+	}
+}
+
+function safeExec(file: string, args: string[], cwd: string): string | undefined {
+	try {
+		return execFileSync(file, args, {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+			maxBuffer: 64 * 1024 * 1024,
+		});
+	} catch (err) {
+		const e = err as NodeJS.ErrnoException & { stdout?: string };
+		// Many secret-scanning tools exit non-zero specifically *because* they
+		// found something — they still print results to stdout.
+		if (typeof e.stdout === "string" && e.stdout.length > 0) return e.stdout;
+		return undefined;
+	}
+}
+
+function slugify(text: string): string {
+	return (
+		text
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "")
+			.slice(0, 60) || "secret"
+	);
+}
+
+function severityFromRule(rule: string): "high" | "medium" | "low" {
+	const lower = rule.toLowerCase();
+	if (
+		lower.includes("private") ||
+		lower.includes("aws") ||
+		lower.includes("gcp") ||
+		lower.includes("azure")
+	)
+		return "high";
+	if (lower.includes("token") || lower.includes("api") || lower.includes("password"))
+		return "medium";
+	return "low";
+}
+
+interface TruffleHogRecord {
+	DetectorName?: string;
+	Verified?: boolean;
+	Raw?: string;
+	SourceMetadata?: {
+		Data?: {
+			Filesystem?: { file?: string; line?: number };
+			Git?: { file?: string; line?: number };
+		};
+	};
+}
+
+function parseTrufflehog(stdout: string): SecretFinding[] {
+	const findings: SecretFinding[] = [];
+	let counter = 0;
+	for (const line of stdout.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		try {
+			const rec = JSON.parse(line) as TruffleHogRecord;
+			const detector = rec.DetectorName ?? "unknown";
+			const fsMeta = rec.SourceMetadata?.Data?.Filesystem;
+			const gitMeta = rec.SourceMetadata?.Data?.Git;
+			const file = fsMeta?.file ?? gitMeta?.file ?? "(unknown)";
+			const lineNum = fsMeta?.line ?? gitMeta?.line;
+			counter++;
+			const id = `q1-${String(counter).padStart(3, "0")}`;
+			findings.push({
+				id,
+				slug: slugify(`${detector}-${file}`),
+				severity: rec.Verified ? "high" : severityFromRule(detector),
+				title: `${detector} secret detected (${rec.Verified ? "verified" : "unverified"})`,
+				file,
+				...(lineNum ? { line: lineNum } : {}),
+				rule: detector,
+				...(rec.Raw ? { excerpt: rec.Raw.slice(0, 200) } : {}),
+				source: "trufflehog",
+			});
+		} catch {
+			// non-JSON lines (banners, errors) are ignored
+		}
+	}
+	return findings;
+}
+
+interface GitleaksRecord {
+	Description?: string;
+	File?: string;
+	StartLine?: number;
+	Match?: string;
+	RuleID?: string;
+	Secret?: string;
+}
+
+function parseGitleaks(stdout: string): SecretFinding[] {
+	let arr: GitleaksRecord[];
+	try {
+		arr = JSON.parse(stdout) as GitleaksRecord[];
+		if (!Array.isArray(arr)) return [];
+	} catch {
+		return [];
+	}
+	return arr.map((r, i) => {
+		const counter = i + 1;
+		const file = r.File ?? "(unknown)";
+		const rule = r.RuleID ?? r.Description ?? "gitleaks-rule";
+		return {
+			id: `q1-${String(counter).padStart(3, "0")}`,
+			slug: slugify(`${rule}-${file}`),
+			severity: severityFromRule(rule),
+			title: r.Description ?? "gitleaks finding",
+			file,
+			...(r.StartLine ? { line: r.StartLine } : {}),
+			rule,
+			...(r.Match ? { excerpt: r.Match.slice(0, 200) } : {}),
+			source: "gitleaks" as const,
+		};
+	});
+}
+
+const GREP_PATTERNS: Array<{ rule: string; regex: RegExp; severity: "high" | "medium" | "low" }> = [
+	{
+		rule: "aws-access-key-id",
+		regex: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g,
+		severity: "high",
+	},
+	{
+		rule: "private-key-pem",
+		regex: /-----BEGIN (?:RSA|EC|DSA|OPENSSH|PRIVATE) (?:PRIVATE )?KEY-----/g,
+		severity: "high",
+	},
+	{
+		rule: "github-token",
+		regex: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g,
+		severity: "high",
+	},
+	{
+		rule: "slack-token",
+		regex: /\bxox[baprs]-[A-Za-z0-9-]{10,48}\b/g,
+		severity: "medium",
+	},
+	{
+		rule: "generic-api-key",
+		regex: /(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"][A-Za-z0-9+/=_-]{16,}['"]/gi,
+		severity: "low",
+	},
+];
+
+const GREP_INCLUDE = [
+	"*.ts",
+	"*.tsx",
+	"*.js",
+	"*.jsx",
+	"*.py",
+	"*.go",
+	"*.rs",
+	"*.rb",
+	"*.java",
+	"*.kt",
+	"*.cs",
+	"*.php",
+	"*.sh",
+	"*.bash",
+	"*.env",
+	"*.yml",
+	"*.yaml",
+	"*.toml",
+	"*.ini",
+	"*.cfg",
+	"*.conf",
+	"*.json",
+];
+
+function runGrepFallback(cwd: string): SecretFinding[] {
+	const findings: SecretFinding[] = [];
+	let counter = 0;
+	for (const { rule, regex, severity } of GREP_PATTERNS) {
+		const args = [
+			"-rEn",
+			"--binary-files=without-match",
+			"--exclude-dir=node_modules",
+			"--exclude-dir=.git",
+			"--exclude-dir=vendor",
+			"--exclude-dir=dist",
+			"--exclude-dir=build",
+			"--exclude-dir=piolium",
+			...GREP_INCLUDE.flatMap((g) => ["--include", g]),
+			regex.source,
+			".",
+		];
+		const stdout = safeExec("grep", args, cwd);
+		if (!stdout) continue;
+		for (const line of stdout.split(/\r?\n/)) {
+			if (!line.trim()) continue;
+			// Format: ./path/to/file:42:matched text
+			const m = line.match(/^(?:\.\/)?(.+?):(\d+):(.*)$/);
+			if (!m) continue;
+			const file = m[1] ?? "(unknown)";
+			const lineNum = Number(m[2]);
+			const excerpt = (m[3] ?? "").trim().slice(0, 200);
+			counter++;
+			findings.push({
+				id: `q1-${String(counter).padStart(3, "0")}`,
+				slug: slugify(`${rule}-${file}`),
+				severity,
+				title: `${rule} match`,
+				file,
+				...(Number.isFinite(lineNum) ? { line: lineNum } : {}),
+				rule,
+				...(excerpt ? { excerpt } : {}),
+				source: "grep" as const,
+			});
+		}
+	}
+	return findings;
+}
+
+function findingMarkdown(f: SecretFinding): string {
+	return [
+		"---",
+		`id: ${f.id}`,
+		"phase: Q1",
+		`slug: ${f.slug}`,
+		`severity: ${f.severity}`,
+		`source: ${f.source}`,
+		`rule: ${f.rule ?? "(none)"}`,
+		"---",
+		"",
+		`# ${f.title}`,
+		"",
+		`- File: \`${f.file}\``,
+		f.line ? `- Line: ${f.line}` : "",
+		f.excerpt ? "" : "",
+		f.excerpt ? `## Excerpt\n\n\`\`\`\n${f.excerpt}\n\`\`\`` : "",
+		"",
+		"## Notes",
+		"",
+		"This is a draft finding produced by the Q1 secrets scan. Confirm by inspecting the file in context.",
+		"",
+	]
+		.filter((s) => s !== "")
+		.join("\n");
+}
+
+export function findingsDraftDir(cwd: string): string {
+	return join(cwd, "piolium", "findings-draft");
+}
+
+export function runQ1SecretsScan(cwd: string): SecretsScanResult {
+	const notes: string[] = [];
+	let backend: SecretsBackend = "none";
+	let findings: SecretFinding[] = [];
+
+	if (which("trufflehog")) {
+		notes.push("Backend: trufflehog (filesystem mode).");
+		const out = safeExec(
+			"trufflehog",
+			["filesystem", "--json", "--no-update", "--exclude-paths=piolium", "."],
+			cwd,
+		);
+		if (out) {
+			findings = parseTrufflehog(out);
+			backend = "trufflehog";
+		} else {
+			notes.push("trufflehog returned no output — falling back.");
+		}
+	}
+	if (backend === "none" && which("gitleaks")) {
+		notes.push("Backend: gitleaks (no-git mode).");
+		const tmp = join(cwd, "piolium", "tmp", "piolium", "gitleaks.json");
+		mkdirSync(join(cwd, "piolium", "tmp", "piolium"), { recursive: true });
+		safeExec(
+			"gitleaks",
+			["detect", "--source", ".", "--no-git", "--report-format", "json", "--report-path", tmp],
+			cwd,
+		);
+		if (existsSync(tmp)) {
+			try {
+				const txt = require("node:fs").readFileSync(tmp, "utf8") as string;
+				findings = parseGitleaks(txt);
+				backend = "gitleaks";
+			} catch {
+				notes.push("gitleaks report unreadable.");
+			}
+		}
+	}
+	if (backend === "none") {
+		notes.push("Backend: regex grep fallback (no trufflehog or gitleaks on PATH).");
+		findings = runGrepFallback(cwd);
+		backend = "grep";
+	}
+
+	const draftDir = findingsDraftDir(cwd);
+	mkdirSync(draftDir, { recursive: true });
+	const draftPaths: string[] = [];
+	for (const f of findings) {
+		const path = join(draftDir, `${f.id}-${f.slug}.md`);
+		writeFileSync(path, findingMarkdown(f));
+		draftPaths.push(path);
+	}
+
+	// Summary placeholder so the gate has something to read even when no
+	// findings surface — distinguishes "scan ran, clean" from "scan never ran".
+	const summaryPath = join(cwd, Q1_SECRETS_SUMMARY);
+	mkdirSync(join(cwd, "piolium", "attack-surface"), { recursive: true });
+	writeFileSync(
+		summaryPath,
+		[
+			"# Q1 Secrets Scan",
+			"",
+			`Backend: ${backend}`,
+			`Findings: ${findings.length}`,
+			notes.length > 0 ? `\nNotes:\n${notes.map((n) => `- ${n}`).join("\n")}` : "",
+			"",
+		].join("\n"),
+	);
+
+	return { backend, findings, notes, draftPaths };
+}