@nseng-ai/areg 0.1.1

package/src/operations/skillx.ts

@@ -0,0 +1,305 @@
+import { failure, negative, ok, type ClinkrExit, ClinkrGroup } from "@nseng-ai/clinkr";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import type { AregCliContext } from "../context.ts";
+import type { AregSkillxInstalledSkill } from "../gateways.ts";
+import { sortStrings } from "../sort.ts";
+
+const SKILLX_FORMAT_VALUES = ["url", "skill-flag", "plain", "repo-only"] as const;
+const REPO_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+export const skillxParseRequestSchema = z.object({
+	inputText: z.string().describe("GitHub URL, owner/repo, or owner/repo plus skill selector."),
+});
+
+export const skillxListRequestSchema = z.object({
+	repo: z.string().describe("GitHub repository in owner/repo form."),
+});
+
+export const skillxFetchRequestSchema = z.object({
+	repo: z.string().describe("GitHub repository in owner/repo form."),
+	skill: z.string().optional().describe("Specific skill name to select after installation."),
+});
+
+export const skillxCleanupRequestSchema = z.object({
+	dir: z.string().describe("Transient skillx workspace directory to remove."),
+});
+
+const skillxFormatSchema = z.enum(SKILLX_FORMAT_VALUES);
+
+const parseSuccessSchema = z.object({
+	success: z.literal(true),
+	repo: z.string(),
+	skill: z.string().nullable(),
+	format: skillxFormatSchema,
+});
+
+const parseFailureSchema = z.object({
+	success: z.literal(false),
+	error: z.string(),
+});
+
+export const skillxParseResultSchema = z.union([parseSuccessSchema, parseFailureSchema]);
+
+const listSuccessSchema = z.object({
+	success: z.literal(true),
+	repo: z.string(),
+	skills: z.array(z.string()),
+});
+
+const listFailureSchema = z.object({
+	success: z.literal(false),
+	error: z.string(),
+	hint: z.string().optional(),
+});
+
+export const skillxListResultSchema = z.union([listSuccessSchema, listFailureSchema]);
+
+const fetchSelectedSuccessSchema = z.object({
+	success: z.literal(true),
+	repo: z.string(),
+	skill: z.string(),
+	tmpDir: z.string(),
+	skillDir: z.string(),
+	skillMd: z.string(),
+	files: z.array(z.string()),
+	needsSelection: z.literal(false).optional(),
+});
+
+const fetchSelectionSuccessSchema = z.object({
+	success: z.literal(true),
+	repo: z.string(),
+	skill: z.null(),
+	tmpDir: z.string(),
+	skillDir: z.null(),
+	skillMd: z.null(),
+	files: z.null(),
+	needsSelection: z.literal(true),
+	availableSkills: z.array(z.string()),
+});
+
+const fetchFailureSchema = z.object({
+	success: z.literal(false),
+	error: z.string(),
+	tmpDir: z.null(),
+});
+
+export const skillxFetchResultSchema = z.union([
+	fetchSelectedSuccessSchema,
+	fetchSelectionSuccessSchema,
+	fetchFailureSchema,
+]);
+
+const cleanupSuccessSchema = z.object({
+	success: z.literal(true),
+	removed: z.string(),
+});
+
+const cleanupFailureSchema = z.object({
+	success: z.literal(false),
+	error: z.string(),
+});
+
+export const skillxCleanupResultSchema = z.union([cleanupSuccessSchema, cleanupFailureSchema]);
+
+export type SkillxParseRequest = z.infer<typeof skillxParseRequestSchema>;
+export type SkillxListRequest = z.infer<typeof skillxListRequestSchema>;
+export type SkillxFetchRequest = z.infer<typeof skillxFetchRequestSchema>;
+export type SkillxCleanupRequest = z.infer<typeof skillxCleanupRequestSchema>;
+export type SkillxParseResult = z.infer<typeof skillxParseResultSchema>;
+export type SkillxListResult = z.infer<typeof skillxListResultSchema>;
+export type SkillxFetchResult = z.infer<typeof skillxFetchResultSchema>;
+export type SkillxCleanupResult = z.infer<typeof skillxCleanupResultSchema>;
+
+export function buildSkillxGroup(): ClinkrGroup<AregCliContext> {
+	const group = new ClinkrGroup<AregCliContext>({
+		name: "skillx",
+		description: "Skillx helper operations.",
+	});
+	group.command({
+		name: "parse",
+		description: "Parse a skill source selector.",
+		schema: skillxParseRequestSchema,
+		positionals: { inputText: { position: 0 } },
+		resultSchema: skillxParseResultSchema,
+		handler: runSkillxParse,
+	});
+	group.command({
+		name: "list",
+		description: "List skills in a GitHub repository skills/ directory.",
+		schema: skillxListRequestSchema,
+		resultSchema: skillxListResultSchema,
+		handler: runSkillxList,
+	});
+	group.command({
+		name: "fetch",
+		description: "Fetch skills into a transient workspace for agent reading.",
+		schema: skillxFetchRequestSchema,
+		resultSchema: skillxFetchResultSchema,
+		handler: runSkillxFetch,
+	});
+	group.command({
+		name: "cleanup",
+		description: "Remove a transient skillx workspace.",
+		schema: skillxCleanupRequestSchema,
+		resultSchema: skillxCleanupResultSchema,
+		handler: runSkillxCleanup,
+	});
+	return group;
+}
+
+export function parseSkillInput(raw: string): SkillxParseResult {
+	const input = raw.trim();
+	if (input.length === 0) return parseError("Empty input");
+	const urlResult = parseGithubUrl(input);
+	if (urlResult !== undefined) return urlResult;
+	const parts = input.split(/\s+/u);
+	const [repo, second, third, ...rest] = parts;
+	if (repo === undefined || !isRepo(repo))
+		return parseError(`Could not extract owner/repo from input: ${JSON.stringify(input)}`);
+	if ((second === "--skill" || second === "-s") && third !== undefined && rest.length === 0) {
+		return { success: true, repo, skill: third, format: "skill-flag" };
+	}
+	if (second === undefined) return { success: true, repo, skill: null, format: "repo-only" };
+	if (third === undefined && isSkillName(second))
+		return { success: true, repo, skill: second, format: "plain" };
+	return parseError(`Could not extract owner/repo from input: ${JSON.stringify(input)}`);
+}
+
+export async function runSkillxParse(
+	_ctx: AregCliContext,
+	request: SkillxParseRequest,
+): Promise<ClinkrExit<SkillxParseResult>> {
+	const result = parseSkillInput(request.inputText);
+	if (result.success) return ok(result);
+	return negative(result.error, { data: result });
+}
+
+export async function runSkillxList(
+	ctx: AregCliContext,
+	request: SkillxListRequest,
+): Promise<ClinkrExit<SkillxListResult>> {
+	const tool = await ctx.host.checkTool({ tool: "gh", cwd: ctx.cwd, env: ctx.env });
+	if (tool.type === "missing") return failure("missing-tool", tool.message);
+	const result = await ctx.github.listSkillDirectoryNames({ repo: request.repo, env: ctx.env });
+	if (result.type === "ok") {
+		return ok({ success: true, repo: request.repo, skills: sortStrings(result.skillNames) });
+	}
+	if (result.type === "missing") {
+		const error = `No skills directory found in ${request.repo}`;
+		return negative(error, {
+			data: {
+				success: false,
+				error,
+				hint: "Check that the repo exists and has a skills/ directory",
+			},
+		});
+	}
+	if (result.type === "auth-error") {
+		return failure("github-auth-failed", `Authentication error accessing ${request.repo}`);
+	}
+	return failure("github-gateway-failed", result.error.message);
+}
+
+export async function runSkillxFetch(
+	ctx: AregCliContext,
+	request: SkillxFetchRequest,
+): Promise<ClinkrExit<SkillxFetchResult>> {
+	const tool = await ctx.host.checkTool({ tool: "npx", cwd: ctx.cwd, env: ctx.env });
+	if (tool.type === "missing") return failure("missing-tool", tool.message);
+	const install = await ctx.skillxWorkspace.installIntoWorkspace({
+		sourceRepo: request.repo,
+		...optionalEntry("skillName", request.skill),
+		cwd: ctx.cwd,
+		env: ctx.env,
+	});
+	if (install.type === "error") return failure("skill-install-failed", install.error.message);
+	const workspaceRoot = install.workspace.workspaceRoot;
+	const installedSkills = sortedInstalledSkills(install.workspace.installedSkills);
+	if (installedSkills.length === 0) return fetchNegative("No skills were installed");
+	if (request.skill === undefined && installedSkills.length > 1) {
+		return ok({
+			success: true,
+			repo: request.repo,
+			skill: null,
+			tmpDir: workspaceRoot,
+			skillDir: null,
+			skillMd: null,
+			files: null,
+			needsSelection: true,
+			availableSkills: installedSkills.map((skill) => skill.name),
+		});
+	}
+	const selected =
+		request.skill === undefined
+			? installedSkills[0]
+			: installedSkills.find((skill) => skill.name === request.skill);
+	if (selected === undefined) {
+		await ctx.skillxWorkspace.cleanupWorkspace({ workspaceRoot });
+		const base = `Skill '${request.skill}' was not found in installed skills`;
+		return fetchNegative(base);
+	}
+	return ok({
+		success: true,
+		repo: request.repo,
+		skill: selected.name,
+		tmpDir: workspaceRoot,
+		skillDir: selected.directory,
+		skillMd: selected.skillFile,
+		files: sortStrings(selected.relativeFiles),
+		needsSelection: false,
+	});
+}
+
+export async function runSkillxCleanup(
+	ctx: AregCliContext,
+	request: SkillxCleanupRequest,
+): Promise<ClinkrExit<SkillxCleanupResult>> {
+	const cleanup = await ctx.skillxWorkspace.cleanupWorkspace({ workspaceRoot: request.dir });
+	if (cleanup.ok) return ok({ success: true, removed: request.dir });
+	return failure("cleanup-failed", cleanup.error.message);
+}
+
+function parseGithubUrl(input: string): z.infer<typeof parseSuccessSchema> | undefined {
+	let url: URL;
+	try {
+		url = new URL(input);
+	} catch {
+		return undefined;
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
+	if (url.hostname !== "github.com" && url.hostname !== "www.github.com") return undefined;
+	const segments = url.pathname.split("/").filter((part) => part.length > 0);
+	const owner = segments[0];
+	const repoName = segments[1];
+	if (owner === undefined || repoName === undefined || !isRepo(`${owner}/${repoName}`))
+		return undefined;
+	const skillsIndex = segments.indexOf("skills");
+	const skill = skillsIndex === -1 ? null : (segments[skillsIndex + 1] ?? null);
+	return { success: true, repo: `${owner}/${repoName}`, skill, format: "url" };
+}
+
+function isRepo(value: string): boolean {
+	return REPO_PATTERN.test(value);
+}
+
+function isSkillName(value: string): boolean {
+	return value.length > 0 && !value.includes("/") && !value.includes("@") && !value.startsWith("-");
+}
+
+function parseError(error: string): SkillxParseResult {
+	return { success: false, error };
+}
+
+function fetchNegative(error: string): ClinkrExit<SkillxFetchResult> {
+	return negative(error, { data: { success: false, error, tmpDir: null } });
+}
+
+function sortedInstalledSkills(
+	skills: readonly AregSkillxInstalledSkill[],
+): AregSkillxInstalledSkill[] {
+	return skills
+		.map((skill) => ({ ...skill, relativeFiles: sortStrings(skill.relativeFiles) }))
+		.sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/operations/toml-section.ts

@@ -0,0 +1,53 @@
+export function renderAregSection(agents: readonly string[]): string {
+	return `[areg]\nagents = ${JSON.stringify([...agents])}\n`;
+}
+
+export function replaceOrAppendAregSection(content: string, agents: readonly string[]): string {
+	const lines = content.split(/(?<=\n)/u);
+	if (lines.length === 1 && lines[0] === "") lines.pop();
+	const start = aregSectionStart(lines);
+	if (start === undefined) return appendTomlSection(content, renderAregSection(agents));
+	const end = tomlSectionEnd(lines, start);
+	let replacement = renderAregSection(agents);
+	if (end < lines.length) replacement += "\n";
+	lines.splice(
+		start,
+		end - start,
+		...(replacement.match(/.*(?:\n|$)/gu)?.filter((line) => line.length > 0) ?? []),
+	);
+	return lines.join("");
+}
+
+function appendTomlSection(content: string, section: string): string {
+	if (content.length === 0) return section;
+	if (content.endsWith("\n\n")) return `${content}${section}`;
+	if (content.endsWith("\n")) return `${content}\n${section}`;
+	return `${content}\n\n${section}`;
+}
+
+function aregSectionStart(lines: readonly string[]): number | undefined {
+	for (let index = 0; index < lines.length; index += 1) {
+		if (tomlTableName(lines[index] ?? "") === "areg") return index;
+	}
+	return undefined;
+}
+
+function tomlSectionEnd(lines: readonly string[], start: number): number {
+	for (let index = start + 1; index < lines.length; index += 1) {
+		if (tomlTableName(lines[index] ?? "") !== null) return index;
+	}
+	return lines.length;
+}
+
+function tomlTableName(line: string): string | null {
+	const stripped = line.trim();
+	if (stripped.startsWith("[[")) {
+		const closingIndex = stripped.indexOf("]]", 2);
+		if (closingIndex < 0) return null;
+		return stripped.slice(2, closingIndex).trim();
+	}
+	if (!stripped.startsWith("[")) return null;
+	const closingIndex = stripped.indexOf("]");
+	if (closingIndex < 0) return null;
+	return stripped.slice(1, closingIndex).trim();
+}

package/src/operations/update-skills.ts

@@ -0,0 +1,325 @@
+import { failure, ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import type { Result } from "@nseng-ai/foundation/result";
+import { z } from "zod";
+
+import type { AregCliContext } from "../context.ts";
+import type { AregErrorInfo, AregGithubSkillFileResult } from "../gateways.ts";
+import { sortStrings } from "../sort.ts";
+import { parseInspectedLockfile, type LockfileSkill } from "./lockfile.ts";
+import { resolveProjectAgents } from "./project-agents.ts";
+
+const updateStatusSchema = z.enum(["planned", "updated", "failed"]);
+
+const selectedUpdateSchema = z.object({
+	skill: z.string(),
+	source: z.string(),
+});
+
+const attemptedUpdateSchema = selectedUpdateSchema.extend({
+	status: updateStatusSchema,
+	error: z.string().optional(),
+});
+
+export const updateSkillsRequestSchema = z.object({
+	path: z.string().default(".").describe("Project directory containing skills-lock.json."),
+	skill: z.array(z.string()).default([]).describe("Skill name to update; repeatable."),
+	source: z
+		.array(z.string())
+		.default([])
+		.describe("Only update skills whose lockfile source matches; repeatable."),
+	agent: z.array(z.string()).default([]).describe("Agent directory to populate; repeatable."),
+	dryRun: z
+		.boolean()
+		.default(false)
+		.describe("Print planned updates without source preflight or npx calls."),
+});
+
+export const updateSkillsResultSchema = z.object({
+	ok: z.boolean(),
+	projectDir: z.string(),
+	agents: z.array(z.string()),
+	dryRun: z.boolean(),
+	selectedUpdates: z.array(selectedUpdateSchema),
+	attemptedUpdates: z.array(attemptedUpdateSchema),
+	failureCount: z.number().int().nonnegative(),
+});
+
+export type UpdateSkillsRequest = z.infer<typeof updateSkillsRequestSchema>;
+export type UpdateSkillsResult = z.infer<typeof updateSkillsResultSchema>;
+interface SelectedUpdate extends z.infer<typeof selectedUpdateSchema> {
+	skillPath?: string;
+}
+
+type AttemptedUpdate = z.infer<typeof attemptedUpdateSchema>;
+
+type PreflightOutcome = { ok: true } | { ok: false; code: string; message: string };
+type GithubPreflightFailure =
+	| { type: "missing" | "auth-error"; message: string }
+	| { type: "error"; error: AregErrorInfo };
+
+export async function runUpdateSkills(
+	ctx: AregCliContext,
+	request: UpdateSkillsRequest,
+): Promise<ClinkrExit<UpdateSkillsResult>> {
+	const inspection = await ctx.project.inspectProjectBase({
+		cwd: ctx.cwd,
+		projectPath: request.path,
+		env: ctx.env,
+	});
+	if (inspection.projectPathState.type !== "directory") {
+		return failure("invalid-project", `${inspection.projectDir} is not a directory`);
+	}
+
+	const lockfileResult = parseInspectedLockfile(inspection);
+	if (!lockfileResult.ok) return failure("lockfile-invalid", lockfileResult.error.message);
+
+	const selection = selectGithubUpdates(lockfileResult.value.skills, request);
+	if (!selection.ok) return failure("invalid-selection", selection.error.message);
+	const selectedUpdates = selection.value;
+
+	if (selectedUpdates.length === 0)
+		return ok(emptyReport(inspection.projectDir, request.dryRun, true));
+
+	const agentsResult = resolveProjectAgents({
+		explicitAgents: request.agent,
+		nsToml: inspection.nsToml,
+		aregJson: inspection.aregJson,
+	});
+	if (!agentsResult.ok) return failure("agent-resolution-failed", agentsResult.error.message);
+	const agents = agentsResult.value;
+
+	if (!request.dryRun) {
+		const gh = await ctx.host.checkTool({ tool: "gh", cwd: inspection.projectDir, env: ctx.env });
+		if (gh.type === "missing") return failure("missing-tool", gh.message);
+		const preflight = await preflightSelectedUpdates(ctx, selectedUpdates);
+		if (!preflight.ok) return failure("skill-source-preflight-failed", preflight.error.message);
+		const npx = await ctx.host.checkTool({ tool: "npx", cwd: inspection.projectDir, env: ctx.env });
+		if (npx.type === "missing") return failure("missing-tool", npx.message);
+	}
+
+	const attemptedUpdates: AttemptedUpdate[] = [];
+	for (const update of selectedUpdates) {
+		if (request.dryRun) {
+			attemptedUpdates.push({ ...publicSelectedUpdate(update), status: "planned" });
+			continue;
+		}
+		const result = await ctx.npxSkills.addSkills({
+			sourceRepo: update.source,
+			skillNames: [update.skill],
+			targetAgents: agents,
+			cwd: inspection.projectDir,
+			env: ctx.env,
+		});
+		if (result.type === "ok") {
+			attemptedUpdates.push({ ...publicSelectedUpdate(update), status: "updated" });
+			continue;
+		}
+		attemptedUpdates.push({
+			...publicSelectedUpdate(update),
+			status: "failed",
+			error: result.error.message,
+		});
+	}
+
+	const finalReport = report({
+		projectDir: inspection.projectDir,
+		agents,
+		dryRun: request.dryRun,
+		selectedUpdates,
+		attemptedUpdates,
+	});
+	if (finalReport.failureCount > 0)
+		return failure("skill-update-failed", formatFailureMessage(finalReport));
+	return ok(finalReport);
+}
+
+export function renderUpdateSkills(result: UpdateSkillsResult): string {
+	if (result.selectedUpdates.length === 0)
+		return "No github-sourced skills match. Nothing to update.";
+	const suffix = result.dryRun ? " [dry-run]" : "";
+	const lines = [
+		`Updating ${result.selectedUpdates.length} skill(s) with agents ${result.agents.join(", ")}${suffix}:`,
+	];
+	for (const update of result.attemptedUpdates) {
+		lines.push(`  ${update.skill}  <-  ${update.source}`);
+		if (update.status === "failed") lines.push(`    FAILED: ${update.error ?? "unknown error"}`);
+	}
+	if (result.dryRun)
+		lines.push("", `Planned: ${result.attemptedUpdates.length} skill(s). No changes made.`);
+	else lines.push("", `Updated ${result.attemptedUpdates.length} skill(s).`);
+	return lines.join("\n");
+}
+
+function selectGithubUpdates(
+	skills: readonly LockfileSkill[],
+	request: UpdateSkillsRequest,
+): Result<readonly SelectedUpdate[]> {
+	const githubEntries = new Map<string, { source: string; skillPath?: string }>();
+	for (const skill of skills) {
+		if (skill.sourceType === "github") {
+			githubEntries.set(skill.name, {
+				source: skill.source,
+				...(skill.skillPath === undefined ? {} : { skillPath: skill.skillPath }),
+			});
+		}
+	}
+
+	const requestedSkills = new Set(request.skill);
+	if (requestedSkills.size > 0) {
+		const unknown = sortStrings([...requestedSkills].filter((skill) => !githubEntries.has(skill)));
+		if (unknown.length > 0)
+			return {
+				ok: false,
+				error: {
+					code: "skill_not_found",
+					message: `Skill(s) not found in lockfile (or not github-sourced): ${unknown.join(", ")}`,
+				},
+			};
+	}
+
+	const requestedSources = new Set(request.source);
+	const updates: SelectedUpdate[] = [];
+	for (const skill of sortStrings([...githubEntries.keys()])) {
+		const entry = githubEntries.get(skill);
+		if (entry === undefined) continue;
+		if (requestedSkills.size > 0 && !requestedSkills.has(skill)) continue;
+		if (requestedSources.size > 0 && !requestedSources.has(entry.source)) continue;
+		updates.push({
+			skill,
+			source: entry.source,
+			...(entry.skillPath === undefined ? {} : { skillPath: entry.skillPath }),
+		});
+	}
+	return { ok: true, value: updates };
+}
+
+async function preflightSelectedUpdates(
+	ctx: AregCliContext,
+	selectedUpdates: readonly SelectedUpdate[],
+): Promise<Result<undefined>> {
+	const failures: string[] = [];
+	for (const update of selectedUpdates) {
+		const result = await preflightSelectedUpdate(ctx, update);
+		if (!result.ok) failures.push(result.error.message);
+	}
+	if (failures.length === 0) return { ok: true, value: undefined };
+	return {
+		ok: false,
+		error: {
+			code: "skill_source_preflight_failed",
+			message: `Source preflight failed before updating skills:\n${failures
+				.map((message) => `  - ${message}`)
+				.join("\n")}`,
+		},
+	};
+}
+
+async function preflightSelectedUpdate(
+	ctx: AregCliContext,
+	update: SelectedUpdate,
+): Promise<Result<undefined>> {
+	if (update.skillPath !== undefined) {
+		const result = await ctx.github.checkSkillFile({
+			repo: update.source,
+			path: update.skillPath,
+			env: ctx.env,
+		});
+		return preflightOutcomeResult(update, normalizeSkillFilePreflightResult(result));
+	}
+
+	const result = await ctx.github.listSkillDirectoryNames({ repo: update.source, env: ctx.env });
+	if (result.type === "ok") {
+		if (result.skillNames.includes(update.skill)) return { ok: true, value: undefined };
+		return preflightOutcomeResult(update, {
+			ok: false,
+			code: "skill_source_preflight_failed",
+			message: "not found in skills directory before update",
+		});
+	}
+	return preflightOutcomeResult(update, normalizeGithubPreflightFailure(result));
+}
+
+function normalizeSkillFilePreflightResult(result: AregGithubSkillFileResult): PreflightOutcome {
+	if (result.type === "found") return { ok: true };
+	return normalizeGithubPreflightFailure(result);
+}
+
+function normalizeGithubPreflightFailure(result: GithubPreflightFailure): PreflightOutcome {
+	switch (result.type) {
+		case "missing":
+		case "auth-error":
+			return {
+				ok: false,
+				code: "skill_source_preflight_failed",
+				message: result.message,
+			};
+		case "error":
+			return {
+				ok: false,
+				code: result.error.code,
+				message: result.error.message,
+			};
+	}
+}
+
+function preflightOutcomeResult(
+	update: SelectedUpdate,
+	outcome: PreflightOutcome,
+): Result<undefined> {
+	if (outcome.ok) return { ok: true, value: undefined };
+	return {
+		ok: false,
+		error: {
+			code: outcome.code,
+			message: `${update.skill} from ${update.source}: ${outcome.message}`,
+		},
+	};
+}
+
+function report(input: {
+	ok?: boolean;
+	projectDir: string;
+	agents: readonly string[];
+	dryRun: boolean;
+	selectedUpdates: readonly SelectedUpdate[];
+	attemptedUpdates: readonly AttemptedUpdate[];
+}): UpdateSkillsResult {
+	const failures = input.attemptedUpdates.filter((update) => update.status === "failed");
+	return {
+		ok: input.ok ?? failures.length === 0,
+		projectDir: input.projectDir,
+		agents: [...input.agents],
+		dryRun: input.dryRun,
+		selectedUpdates: input.selectedUpdates.map(publicSelectedUpdate),
+		attemptedUpdates: input.attemptedUpdates.map((update) => ({ ...update })),
+		failureCount: failures.length,
+	};
+}
+
+function publicSelectedUpdate(update: SelectedUpdate): z.infer<typeof selectedUpdateSchema> {
+	return { skill: update.skill, source: update.source };
+}
+
+function emptyReport(projectDir: string, dryRun: boolean, isOk: boolean): UpdateSkillsResult {
+	return report({
+		ok: isOk,
+		projectDir,
+		agents: [],
+		dryRun,
+		selectedUpdates: [],
+		attemptedUpdates: [],
+	});
+}
+
+function formatFailureMessage(result: UpdateSkillsResult): string {
+	const failed = result.attemptedUpdates.filter((update) => update.status === "failed");
+	const lines = [
+		`${failed.length} skill(s) failed to update: ${failed.map((update) => update.skill).join(", ")}`,
+	];
+	for (const update of failed)
+		lines.push(
+			`  ${update.skill}  <-  ${update.source}`,
+			`    FAILED: ${update.error ?? "unknown error"}`,
+		);
+	return lines.join("\n");
+}

package/src/real-gateways.ts

@@ -0,0 +1,6 @@
+export { RealAregProjectGateway } from "./gateways/project-gateway.ts";
+export { RealAregGithubGateway } from "./gateways/github-gateway.ts";
+export { RealAregHostGateway } from "./gateways/host-gateway.ts";
+export { buildNpxSkillsAddArgs, RealAregNpxSkillsGateway } from "./gateways/npx-skills-gateway.ts";
+export { RealAregPromptGateway } from "./gateways/prompt-gateway.ts";
+export { RealAregSkillxWorkspaceGateway } from "./gateways/skillx-workspace-gateway.ts";