@nseng-ai/areg 0.1.1 → 0.1.2

package/src/operations/update-skills.ts

@@ -1,325 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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";

package/src/skill-lookup.ts

@@ -1,254 +0,0 @@
-import { lstat, realpath } from "node:fs/promises";
-import { dirname, join, parse, resolve } from "node:path";
-
-import { isPathInside } from "@nseng-ai/foundation/primitives";
-
-export const SKILL_LOOKUP_ROOT_DESCRIPTORS = [
-	{ root: "skills", sourceType: "repo" },
-	{ root: ".agents/skills", sourceType: "vendored" },
-	{ root: ".claude/skills", sourceType: "claude" },
-] as const satisfies ReadonlyArray<{ root: string; sourceType: string }>;
-
-export type SkillLookupRootDescriptor = (typeof SKILL_LOOKUP_ROOT_DESCRIPTORS)[number];
-export type SkillLookupRoot = SkillLookupRootDescriptor["root"];
-export type SkillLookupSourceType = SkillLookupRootDescriptor["sourceType"];
-
-export const SKILL_LOOKUP_ROOTS = SKILL_LOOKUP_ROOT_DESCRIPTORS.map(
-	(descriptor): SkillLookupRoot => descriptor.root,
-) as [SkillLookupRoot, ...SkillLookupRoot[]];
-export const SKILL_LOOKUP_SOURCE_TYPES = SKILL_LOOKUP_ROOT_DESCRIPTORS.map(
-	(descriptor): SkillLookupSourceType => descriptor.sourceType,
-) as [SkillLookupSourceType, ...SkillLookupSourceType[]];
-
-const SKILL_LOOKUP_DESCRIPTOR_BY_ROOT = new Map<SkillLookupRoot, SkillLookupRootDescriptor>(
-	SKILL_LOOKUP_ROOT_DESCRIPTORS.map((descriptor) => [descriptor.root, descriptor] as const),
-);
-const SKILL_LOOKUP_DESCRIPTOR_BY_SOURCE_TYPE = new Map<
-	SkillLookupSourceType,
-	SkillLookupRootDescriptor
->(SKILL_LOOKUP_ROOT_DESCRIPTORS.map((descriptor) => [descriptor.sourceType, descriptor] as const));
-const SKILL_LOOKUP_ROOT_RANKS = new Map<SkillLookupRoot, number>(
-	SKILL_LOOKUP_ROOT_DESCRIPTORS.map((descriptor, index) => [descriptor.root, index] as const),
-);
-
-export interface SkillLookupPathStat {
-	isFile(): boolean;
-	isDirectory(): boolean;
-	isSymbolicLink(): boolean;
-}
-
-export interface SkillLookupIo {
-	statPath?: (path: string) => Promise<SkillLookupPathStat>;
-}
-
-export interface SkillLookupSearchedRoot {
-	root: SkillLookupRoot;
-	sourceType: SkillLookupSourceType;
-	searchedRelativePath: string;
-	searchedPath: string;
-}
-
-export interface FoundSkillLookup {
-	type: "found";
-	root: SkillLookupRoot;
-	sourceType: SkillLookupSourceType;
-	baseRelativePath: string;
-	skillFileRelativePath: string;
-	basePath: string;
-	skillFilePath: string;
-}
-
-export interface MissingSkillLookup {
-	type: "missing";
-	searchedRoots: readonly SkillLookupSearchedRoot[];
-}
-
-export interface FailedSkillLookup {
-	type: "error";
-	message: string;
-	path: string;
-}
-
-export type SkillLookupResult = FoundSkillLookup | MissingSkillLookup | FailedSkillLookup;
-
-export interface ResolveExactSkillLookupOptions extends SkillLookupIo {
-	projectDir: string;
-	skillName: string;
-}
-
-export interface ResolveSkillLookupProjectRootOptions extends Pick<SkillLookupIo, "statPath"> {
-	cwd: string;
-}
-
-export function skillLookupDescriptorForRoot(root: SkillLookupRoot): SkillLookupRootDescriptor {
-	const descriptor = SKILL_LOOKUP_DESCRIPTOR_BY_ROOT.get(root);
-	if (descriptor === undefined) throw new Error(`Unknown skill lookup root: ${root}`);
-	return descriptor;
-}
-
-export function skillLookupDescriptorForSourceType(
-	sourceType: SkillLookupSourceType,
-): SkillLookupRootDescriptor {
-	const descriptor = SKILL_LOOKUP_DESCRIPTOR_BY_SOURCE_TYPE.get(sourceType);
-	if (descriptor === undefined) throw new Error(`Unknown skill lookup source type: ${sourceType}`);
-	return descriptor;
-}
-
-export function skillLookupRootRank(root: SkillLookupRoot): number {
-	return SKILL_LOOKUP_ROOT_RANKS.get(root) ?? SKILL_LOOKUP_ROOT_DESCRIPTORS.length;
-}
-
-export function skillLookupBaseRelativePath(root: SkillLookupRoot, skillName: string): string {
-	return `${root}/${skillName}`;
-}
-
-export function skillLookupFileRelativePath(root: SkillLookupRoot, skillName: string): string {
-	return `${skillLookupBaseRelativePath(root, skillName)}/SKILL.md`;
-}
-
-export function skillLookupIoOptions(options: SkillLookupIo): SkillLookupIo {
-	if (options.statPath === undefined) return {};
-	return { statPath: options.statPath };
-}
-
-export function buildSkillLookupSearchedRoots(
-	projectDir: string,
-	skillName: string,
-): SkillLookupSearchedRoot[] {
-	return SKILL_LOOKUP_ROOT_DESCRIPTORS.map((descriptor) => {
-		const searchedRelativePath = skillLookupFileRelativePath(descriptor.root, skillName);
-		return {
-			root: descriptor.root,
-			sourceType: descriptor.sourceType,
-			searchedRelativePath,
-			searchedPath: join(projectDir, descriptor.root, skillName, "SKILL.md"),
-		};
-	});
-}
-
-function defaultStatPath(path: string): Promise<SkillLookupPathStat> {
-	return lstat(path);
-}
-
-function defaultRealpathPath(path: string): Promise<string> {
-	return realpath(path);
-}
-
-function containmentErrorOrUndefined(options: {
-	base: string;
-	target: string;
-	skillFilePath: string;
-	projectDir: string;
-}): FailedSkillLookup | undefined {
-	if (isPathInside(options.base, options.target)) return undefined;
-	return {
-		type: "error",
-		message: `Backing skill path ${options.skillFilePath} resolves outside repository root ${options.projectDir}.`,
-		path: options.skillFilePath,
-	};
-}
-
-export async function resolveSkillLookupProjectRoot(
-	options: ResolveSkillLookupProjectRootOptions,
-): Promise<string> {
-	const statPath = options.statPath ?? defaultStatPath;
-	let current = resolve(options.cwd);
-	const root = parse(current).root;
-
-	while (true) {
-		if (await hasGitMarker(current, statPath)) return current;
-		if (current === root) {
-			throw new Error(`Could not find a Git repository root from ${options.cwd}.`);
-		}
-		current = dirname(current);
-	}
-}
-
-export async function resolveExactSkillLookup(
-	options: ResolveExactSkillLookupOptions,
-): Promise<SkillLookupResult> {
-	const statPath = options.statPath ?? defaultStatPath;
-	const projectDir = resolve(options.projectDir);
-	const realProjectDir = await defaultRealpathPath(projectDir);
-	const searchedRoots = buildSkillLookupSearchedRoots(projectDir, options.skillName);
-
-	for (const descriptor of SKILL_LOOKUP_ROOT_DESCRIPTORS) {
-		const baseRelativePath = skillLookupBaseRelativePath(descriptor.root, options.skillName);
-		const skillFileRelativePath = skillLookupFileRelativePath(descriptor.root, options.skillName);
-		const basePath = join(projectDir, descriptor.root, options.skillName);
-		const skillFilePath = join(basePath, "SKILL.md");
-		const normalizedSkillFilePath = resolve(skillFilePath);
-		const normalizedContainmentError = containmentErrorOrUndefined({
-			base: projectDir,
-			target: normalizedSkillFilePath,
-			skillFilePath,
-			projectDir,
-		});
-		if (normalizedContainmentError !== undefined) return normalizedContainmentError;
-
-		const skillStat = await statPathOrUndefined(statPath, skillFilePath);
-		if (skillStat === undefined || (!skillStat.isFile() && !skillStat.isSymbolicLink())) {
-			continue;
-		}
-		if (skillStat.isSymbolicLink()) {
-			return {
-				type: "error",
-				message: `Refusing to read symlinked backing skill at ${skillFilePath}.`,
-				path: skillFilePath,
-			};
-		}
-
-		let realSkillFilePath: string;
-		try {
-			realSkillFilePath = await defaultRealpathPath(skillFilePath);
-		} catch (error) {
-			return {
-				type: "error",
-				message: `Could not resolve backing skill path ${skillFilePath}: ${formatUnknownError(error)}`,
-				path: skillFilePath,
-			};
-		}
-		const realContainmentError = containmentErrorOrUndefined({
-			base: realProjectDir,
-			target: realSkillFilePath,
-			skillFilePath,
-			projectDir,
-		});
-		if (realContainmentError !== undefined) return realContainmentError;
-
-		return {
-			type: "found",
-			root: descriptor.root,
-			sourceType: descriptor.sourceType,
-			baseRelativePath,
-			skillFileRelativePath,
-			basePath,
-			skillFilePath,
-		};
-	}
-
-	return { type: "missing", searchedRoots };
-}
-
-async function hasGitMarker(
-	directory: string,
-	statPath: (path: string) => Promise<SkillLookupPathStat>,
-): Promise<boolean> {
-	const marker = await statPathOrUndefined(statPath, join(directory, ".git"));
-	return marker !== undefined && (marker.isDirectory() || marker.isFile());
-}
-
-async function statPathOrUndefined(
-	statPath: (path: string) => Promise<SkillLookupPathStat>,
-	path: string,
-): Promise<SkillLookupPathStat | undefined> {
-	try {
-		return await statPath(path);
-	} catch {
-		return undefined;
-	}
-}
-
-function formatUnknownError(error: unknown): string {
-	return error instanceof Error ? error.message : String(error);
-}