@nseng-ai/areg 0.1.1

package/src/gateways/command-constants.ts

@@ -0,0 +1 @@
+export const COMMAND_TIMEOUT_MS = 60_000;

package/src/gateways/errors.ts

@@ -0,0 +1,5 @@
+import type { AregErrorInfo } from "../gateways.ts";
+
+export function errorInfo(code: string, message: string, displayCommand?: string): AregErrorInfo {
+	return displayCommand === undefined ? { code, message } : { code, message, displayCommand };
+}

package/src/gateways/fs-utils.ts

@@ -0,0 +1,26 @@
+import { lstat, readlink } from "node:fs/promises";
+
+import { errorCodeFromUnknown, isPathInside } from "@nseng-ai/foundation/primitives";
+
+import type { AregPathState } from "../gateways.ts";
+
+export async function inspectPath(candidate: string): Promise<AregPathState> {
+	try {
+		const info = await lstat(candidate);
+		if (info.isSymbolicLink()) return { type: "symlink", target: await readlink(candidate) };
+		if (info.isDirectory()) return { type: "directory" };
+		if (info.isFile()) return { type: "file" };
+		return { type: "other" };
+	} catch (error) {
+		if (isNodeErrorCode(error, "ENOENT")) return { type: "missing" };
+		return { type: "other" };
+	}
+}
+
+export function isPathAtOrBelow(candidate: string, root: string): boolean {
+	return isPathInside(root, candidate);
+}
+
+export function isNodeErrorCode(error: unknown, code: string): boolean {
+	return errorCodeFromUnknown(error) === code;
+}

package/src/gateways/github-gateway.ts

@@ -0,0 +1,111 @@
+import {
+	formatCommand,
+	formatCommandResultFailure,
+	runCommand,
+	stripTerminalEscapes,
+	type CommandRunner,
+} from "@nseng-ai/foundation/exec";
+
+import type {
+	AregGithubGateway,
+	AregGithubSkillFileResult,
+	AregGithubSkillListResult,
+} from "../gateways.ts";
+import { COMMAND_TIMEOUT_MS } from "./command-constants.ts";
+import { errorInfo } from "./errors.ts";
+
+export class RealAregGithubGateway implements AregGithubGateway {
+	private readonly runner: CommandRunner;
+
+	constructor(options: { runner?: CommandRunner } = {}) {
+		this.runner = options.runner ?? runCommand;
+	}
+
+	async listSkillDirectoryNames(options: {
+		repo: string;
+		ref?: string;
+		env: NodeJS.ProcessEnv;
+	}): Promise<AregGithubSkillListResult> {
+		const resource = githubContentsResource(options.repo, "skills", options.ref);
+		const args = ["api", resource, "--jq", ".[].name"];
+		const displayCommand = formatCommand("gh", args);
+		const result = await this.runner("gh", args, { env: options.env, timeout: COMMAND_TIMEOUT_MS });
+		if (result.code === 0) {
+			return {
+				type: "ok",
+				skillNames: result.stdout
+					.split("\n")
+					.map((line) => line.trim())
+					.filter((line) => line.length > 0),
+			};
+		}
+		return classifyGithubFailure({
+			result,
+			args,
+			displayCommand,
+			missingMessage: `No skills directory found in ${options.repo}`,
+			authMessage: `Authentication error accessing ${options.repo}`,
+		});
+	}
+
+	async checkSkillFile(options: {
+		repo: string;
+		path: string;
+		ref?: string;
+		env: NodeJS.ProcessEnv;
+	}): Promise<AregGithubSkillFileResult> {
+		const resource = githubContentsResource(options.repo, options.path, options.ref);
+		const args = ["api", resource, "--jq", ".type"];
+		const displayCommand = formatCommand("gh", args);
+		const result = await this.runner("gh", args, { env: options.env, timeout: COMMAND_TIMEOUT_MS });
+		if (result.code === 0) return { type: "found" };
+		return classifyGithubFailure({
+			result,
+			args,
+			displayCommand,
+			missingMessage: `Skill file not found in ${options.repo}: ${options.path}`,
+			authMessage: `Authentication error accessing ${options.repo}`,
+		});
+	}
+}
+
+interface GithubFailureInput {
+	result: Awaited<ReturnType<CommandRunner>>;
+	args: readonly string[];
+	displayCommand: string;
+	missingMessage: string;
+	authMessage: string;
+}
+
+function githubContentsResource(repo: string, path: string, ref: string | undefined): string {
+	const normalizedPath = path
+		.split("/")
+		.filter((part) => part.length > 0)
+		.map(encodeURIComponent)
+		.join("/");
+	const resource = `repos/${repo}/contents/${normalizedPath}`;
+	if (ref === undefined) return resource;
+	return `${resource}?ref=${encodeURIComponent(ref)}`;
+}
+
+function classifyGithubFailure(
+	input: GithubFailureInput,
+):
+	| { type: "missing"; message: string }
+	| { type: "auth-error"; message: string }
+	| { type: "error"; error: ReturnType<typeof errorInfo> } {
+	const combined = stripTerminalEscapes(
+		`${input.result.stdout}\n${input.result.stderr}`,
+	).toLowerCase();
+	if (combined.includes("404")) return { type: "missing", message: input.missingMessage };
+	if (combined.includes("401") || combined.includes("403"))
+		return { type: "auth-error", message: input.authMessage };
+	return {
+		type: "error",
+		error: errorInfo(
+			input.result.startupError === undefined ? "gh-failed" : "gh-startup-failed",
+			formatCommandResultFailure("gh api failed", "gh", input.args, input.result),
+			input.displayCommand,
+		),
+	};
+}

package/src/gateways/host-gateway.ts

@@ -0,0 +1,35 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+import type { AregHostGateway, AregHostToolName, AregToolCheckResult } from "../gateways.ts";
+
+export class RealAregHostGateway implements AregHostGateway {
+	async checkTool(options: {
+		tool: AregHostToolName;
+		cwd: string;
+		env: NodeJS.ProcessEnv;
+	}): Promise<AregToolCheckResult> {
+		const pathValue = options.env.PATH ?? "";
+		for (const directory of pathValue.split(path.delimiter)) {
+			if (directory.length === 0) continue;
+			const candidate = path.join(directory, options.tool);
+			if (await isExecutable(candidate))
+				return { type: "found", tool: options.tool, path: candidate };
+		}
+		return {
+			type: "missing",
+			tool: options.tool,
+			message: `Required host tool is missing: ${options.tool}`,
+		};
+	}
+}
+
+async function isExecutable(candidate: string): Promise<boolean> {
+	try {
+		await access(candidate, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/gateways/mutation-policy.ts

@@ -0,0 +1,94 @@
+import type { AregProjectMutationPolicy } from "../gateways.ts";
+
+interface AregProjectMutationPolicyDescriptor {
+	policy: AregProjectMutationPolicy;
+	isAllowedRelativePath(relativePath: string): boolean;
+	refusedTargetCode: string;
+	shouldCheckUnsupportedFirst: boolean;
+	unsupportedMessage(relativePath: string, description: string): string;
+	unsafeMessage(relativePath: string, description: string): string;
+	outsideMessage(relativePath: string, description: string): string;
+	symlinkCode: string;
+	notFileCode: string;
+	parentSymlinkCode: string;
+	parentNotDirectoryCode: string;
+	parentMissingCode: string;
+	parentCreateFailedCode: string;
+	writeFailedCode: string;
+}
+
+const INIT_MUTATION_POLICY = {
+	policy: "init",
+	isAllowedRelativePath: isAllowedInitRelativePath,
+	refusedTargetCode: "init-write-target-refused",
+	shouldCheckUnsupportedFirst: true,
+	unsupportedMessage: (relativePath) =>
+		`Refusing to write unsupported init target: ${relativePath}`,
+	unsafeMessage: (relativePath) => `Refusing to write unsafe init target: ${relativePath}`,
+	outsideMessage: (relativePath) => `Refusing to write outside project root: ${relativePath}`,
+	symlinkCode: "init-symlink",
+	notFileCode: "init-not-file",
+	parentSymlinkCode: "init-parent-symlink",
+	parentNotDirectoryCode: "init-parent-not-directory",
+	parentMissingCode: "init-parent-missing",
+	parentCreateFailedCode: "init-parent-create-failed",
+	writeFailedCode: "init-write-failed",
+} satisfies AregProjectMutationPolicyDescriptor;
+
+const SKILL_KIND_MUTATION_POLICY = {
+	policy: "skill-kind",
+	isAllowedRelativePath: isAllowedSkillKindRelativePath,
+	refusedTargetCode: "skill-kind-target-refused",
+	shouldCheckUnsupportedFirst: false,
+	unsupportedMessage: (candidate, description) =>
+		`Refusing to manage unsupported ${description} target: ${candidate}`,
+	unsafeMessage: (candidate, description) =>
+		`Refusing to manage unsafe ${description} target: ${candidate}`,
+	outsideMessage: (candidate, description) =>
+		`Refusing to manage ${description} outside project root: ${candidate}`,
+	symlinkCode: "skill-kind-symlink",
+	notFileCode: "skill-kind-not-file",
+	parentSymlinkCode: "skill-kind-parent-symlink",
+	parentNotDirectoryCode: "skill-kind-parent-not-directory",
+	parentMissingCode: "skill-kind-parent-missing",
+	parentCreateFailedCode: "skill-kind-parent-create-failed",
+	writeFailedCode: "skill-kind-write-failed",
+} satisfies AregProjectMutationPolicyDescriptor;
+
+export function getAregProjectMutationPolicyDescriptor(
+	policy: AregProjectMutationPolicy,
+): AregProjectMutationPolicyDescriptor {
+	switch (policy) {
+		case "init":
+			return INIT_MUTATION_POLICY;
+		case "skill-kind":
+			return SKILL_KIND_MUTATION_POLICY;
+	}
+}
+
+function isAllowedInitRelativePath(relativePath: string): boolean {
+	return ["ns.toml", "AGENTS.md", "CLAUDE.md", ".claude/settings.local.json"].includes(
+		relativePath,
+	);
+}
+
+function isAllowedSkillKindRelativePath(relativePath: string): boolean {
+	if (relativePath === ".pi/settings.json") return true;
+	const parts = relativePath.split("/");
+	return (
+		isAllowedSkillKindRelativePathParts(parts, 1) || isAllowedSkillKindRelativePathParts(parts, 2)
+	);
+}
+
+function isAllowedSkillKindRelativePathParts(parts: readonly string[], rootLength: 1 | 2): boolean {
+	const isLocalRoot = rootLength === 1 && parts[0] === "skills";
+	const isVendoredRoot = rootLength === 2 && parts[0] === ".agents" && parts[1] === "skills";
+	if (!isLocalRoot && !isVendoredRoot) return false;
+	return (
+		(parts.length === rootLength + 2 && parts[rootLength + 1] === "SKILL.md") ||
+		(parts.length === rootLength + 3 &&
+			parts[rootLength + 1] === "agents" &&
+			parts[rootLength + 2] === "openai.yaml") ||
+		(parts.length === rootLength + 2 && parts[rootLength + 1] === "agents")
+	);
+}

package/src/gateways/npx-skills-gateway.ts

@@ -0,0 +1,53 @@
+import {
+	formatCommand,
+	formatCommandResultFailure,
+	runCommand,
+	type CommandRunner,
+} from "@nseng-ai/foundation/exec";
+
+import type {
+	AregNpxSkillsAddRequest,
+	AregNpxSkillsAddResult,
+	AregNpxSkillsGateway,
+} from "../gateways.ts";
+import { COMMAND_TIMEOUT_MS } from "./command-constants.ts";
+import { errorInfo } from "./errors.ts";
+
+export class RealAregNpxSkillsGateway implements AregNpxSkillsGateway {
+	private readonly runner: CommandRunner;
+
+	constructor(options: { runner?: CommandRunner } = {}) {
+		this.runner = options.runner ?? runCommand;
+	}
+
+	async addSkills(request: AregNpxSkillsAddRequest): Promise<AregNpxSkillsAddResult> {
+		const args = buildNpxSkillsAddArgs(request);
+		const displayCommand = formatCommand("npx", args);
+		const result = await this.runner("npx", args, {
+			cwd: request.cwd,
+			env: request.env,
+			timeout: COMMAND_TIMEOUT_MS,
+		});
+		if (result.code === 0) return { type: "ok" };
+		return {
+			type: "error",
+			error: errorInfo(
+				result.startupError === undefined ? "npx-failed" : "npx-startup-failed",
+				formatCommandResultFailure("npx skills add failed", "npx", args, result),
+				displayCommand,
+			),
+		};
+	}
+}
+
+export function buildNpxSkillsAddArgs(request: AregNpxSkillsAddRequest): string[] {
+	const args = ["skills", "add", request.sourceRepo];
+	for (const skillName of request.skillNames) {
+		args.push("--skill", skillName);
+	}
+	for (const agent of request.targetAgents) {
+		args.push("--agent", agent);
+	}
+	args.push("-y");
+	return args;
+}

package/src/gateways/project-fs.ts

@@ -0,0 +1,320 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
+
+import type { AregErrorInfo, AregProjectMutationPolicy, AregTextFileState } from "../gateways.ts";
+import {
+	classifySkillMirrorSymlinkState,
+	expectedMirrorTarget,
+} from "../operations/skill-mirror-conventions.ts";
+import { errorInfo } from "./errors.ts";
+import { inspectPath, isPathAtOrBelow } from "./fs-utils.ts";
+import { getAregProjectMutationPolicyDescriptor } from "./mutation-policy.ts";
+
+export { inspectPath, isNodeErrorCode } from "./fs-utils.ts";
+
+export function toProjectPath(projectRoot: string, relativePath: string): string {
+	return path.join(projectRoot, ...relativePath.split("/"));
+}
+
+interface ResolveAllowedWriteTargetOptions {
+	policy: AregProjectMutationPolicy;
+	projectRoot: string;
+	relativePath: string;
+	description: string;
+}
+
+interface ValidateTextWriteTargetOptions {
+	policy: AregProjectMutationPolicy;
+	target: string;
+	projectRoot: string;
+	description: string;
+	shouldCreateParent: boolean;
+}
+
+type WriteTargetValidationResult = { ok: true } | { ok: false; error: AregErrorInfo };
+
+export async function inspectTextFile(candidate: string): Promise<AregTextFileState> {
+	const pathState = await inspectPath(candidate);
+	if (
+		pathState.type === "missing" ||
+		pathState.type === "directory" ||
+		pathState.type === "symlink" ||
+		pathState.type === "other"
+	)
+		return pathState;
+	try {
+		return { type: "file", text: await readFile(candidate, "utf8") };
+	} catch (error) {
+		return { type: "unreadable", message: formatErrorMessage(error) };
+	}
+}
+
+export async function resolveExistingDirectory(
+	candidate: string,
+	description: string,
+): Promise<{ type: "ok"; value: string } | { type: "error"; error: AregErrorInfo }> {
+	const state = await inspectPath(candidate);
+	if (state.type === "symlink")
+		return {
+			type: "error",
+			error: errorInfo(
+				"init-symlink",
+				`${description} at ${candidate} is a symlink; refusing to manage it.`,
+			),
+		};
+	if (state.type !== "directory")
+		return {
+			type: "error",
+			error: errorInfo("init-not-directory", `${candidate} exists but is not a directory.`),
+		};
+	try {
+		return { type: "ok", value: await realpath(candidate) };
+	} catch (error) {
+		return {
+			type: "error",
+			error: errorInfo(
+				"init-realpath-failed",
+				`Could not resolve ${description} at ${candidate}: ${formatErrorMessage(error)}`,
+			),
+		};
+	}
+}
+
+export function resolveAllowedWriteTarget(
+	options: ResolveAllowedWriteTargetOptions,
+): { type: "ok"; value: string } | { type: "error"; error: AregErrorInfo } {
+	const descriptor = getAregProjectMutationPolicyDescriptor(options.policy);
+	if (
+		descriptor.shouldCheckUnsupportedFirst &&
+		!descriptor.isAllowedRelativePath(options.relativePath)
+	) {
+		return {
+			type: "error",
+			error: errorInfo(
+				descriptor.refusedTargetCode,
+				descriptor.unsupportedMessage(options.relativePath, options.description),
+			),
+		};
+	}
+	if (path.isAbsolute(options.relativePath) || options.relativePath.split("/").includes("..")) {
+		return {
+			type: "error",
+			error: errorInfo(
+				descriptor.refusedTargetCode,
+				descriptor.unsafeMessage(options.relativePath, options.description),
+			),
+		};
+	}
+	if (
+		!descriptor.shouldCheckUnsupportedFirst &&
+		!descriptor.isAllowedRelativePath(options.relativePath)
+	) {
+		return {
+			type: "error",
+			error: errorInfo(
+				descriptor.refusedTargetCode,
+				descriptor.unsupportedMessage(options.relativePath, options.description),
+			),
+		};
+	}
+	const target = toProjectPath(options.projectRoot, options.relativePath);
+	const relative = path.relative(options.projectRoot, target);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) {
+		return {
+			type: "error",
+			error: errorInfo(
+				descriptor.refusedTargetCode,
+				descriptor.outsideMessage(options.relativePath, options.description),
+			),
+		};
+	}
+	return { type: "ok", value: target };
+}
+
+export async function validateWriteTarget(
+	options: ValidateTextWriteTargetOptions,
+): Promise<WriteTargetValidationResult> {
+	const descriptor = getAregProjectMutationPolicyDescriptor(options.policy);
+	const targetState = await inspectPath(options.target);
+	if (targetState.type === "symlink")
+		return {
+			ok: false,
+			error: errorInfo(
+				descriptor.symlinkCode,
+				`${options.description} at ${options.target} is a symlink; refusing to manage it.`,
+			),
+		};
+	if (targetState.type === "directory" || targetState.type === "other")
+		return {
+			ok: false,
+			error: errorInfo(descriptor.notFileCode, `${options.target} exists but is not a file.`),
+		};
+	if (targetState.type === "file")
+		return await requirePathAtOrBelow(options.target, options.projectRoot, options.description);
+	const parent = await nearestExistingParent(
+		options.target,
+		options.projectRoot,
+		descriptor.parentMissingCode,
+	);
+	if (parent.type === "error") return { ok: false, error: parent.error };
+	const parentState = await inspectPath(parent.value);
+	if (parentState.type === "symlink")
+		return {
+			ok: false,
+			error: errorInfo(
+				descriptor.parentSymlinkCode,
+				`Parent directory at ${parent.value} is a symlink; refusing to manage it.`,
+			),
+		};
+	if (parentState.type !== "directory")
+		return {
+			ok: false,
+			error: errorInfo(
+				descriptor.parentNotDirectoryCode,
+				`${parent.value} exists but is not a directory.`,
+			),
+		};
+	const parentCheck = await requirePathAtOrBelow(
+		parent.value,
+		options.projectRoot,
+		"Parent directory",
+	);
+	if (!parentCheck.ok) return parentCheck;
+	if (!options.shouldCreateParent && path.dirname(options.target) !== parent.value) {
+		return {
+			ok: false,
+			error: errorInfo(
+				descriptor.parentMissingCode,
+				`Parent directory at ${path.dirname(options.target)} does not exist.`,
+			),
+		};
+	}
+	return { ok: true };
+}
+
+export async function validateSkillKindDeleteTarget(
+	target: string,
+	projectRoot: string,
+	description: string,
+): Promise<WriteTargetValidationResult> {
+	const targetState = await inspectPath(target);
+	if (targetState.type === "missing")
+		return {
+			ok: false,
+			error: errorInfo("skill-kind-delete-missing", `${description} at ${target} does not exist.`),
+		};
+	if (targetState.type === "symlink")
+		return {
+			ok: false,
+			error: errorInfo(
+				"skill-kind-symlink",
+				`${description} at ${target} is a symlink; refusing to delete it.`,
+			),
+		};
+	if (targetState.type !== "file")
+		return {
+			ok: false,
+			error: errorInfo("skill-kind-not-file", `${target} exists but is not a file.`),
+		};
+	return await requirePathAtOrBelow(target, projectRoot, description);
+}
+
+/**
+ * Validates a skill-mirror symlink deletion target. This is intentionally
+ * narrower than the skill-kind write/delete path policy: only exact
+ * `.agents/skills/<name>` / `.claude/skills/<name>` symlinks pointing at the
+ * convention target are deletable, and containment is checked through the
+ * parent directory's realpath (not through the link itself).
+ */
+export async function validateSkillKindDeleteSymlinkTarget(
+	target: string,
+	projectRoot: string,
+	relativePath: string,
+	description: string,
+): Promise<WriteTargetValidationResult> {
+	const expectedTarget = expectedMirrorTarget(relativePath);
+	if (expectedTarget !== undefined) {
+		const parentCheck = await requirePathAtOrBelow(
+			path.dirname(target),
+			projectRoot,
+			"Parent directory",
+		);
+		if (!parentCheck.ok) return parentCheck;
+	}
+	const state = expectedTarget === undefined ? undefined : await inspectPath(target);
+	const failure = classifySkillMirrorSymlinkState(relativePath, state, description, target);
+	return failure === undefined ? { ok: true } : { ok: false, error: failure };
+}
+
+export async function validateSkillKindRemoveDirTarget(
+	target: string,
+	projectRoot: string,
+	description: string,
+): Promise<{ ok: true; exists: boolean } | { ok: false; error: AregErrorInfo }> {
+	const targetState = await inspectPath(target);
+	if (targetState.type === "missing") return { ok: true, exists: false };
+	if (targetState.type === "symlink")
+		return {
+			ok: false,
+			error: errorInfo(
+				"skill-kind-symlink",
+				`${description} at ${target} is a symlink; refusing to remove it.`,
+			),
+		};
+	if (targetState.type !== "directory")
+		return {
+			ok: false,
+			error: errorInfo("skill-kind-not-directory", `${target} exists but is not a directory.`),
+		};
+	const pathCheck = await requirePathAtOrBelow(target, projectRoot, description);
+	if (!pathCheck.ok) return pathCheck;
+	return { ok: true, exists: true };
+}
+
+async function nearestExistingParent(
+	target: string,
+	projectRoot: string,
+	parentMissingCode: string,
+): Promise<{ type: "ok"; value: string } | { type: "error"; error: AregErrorInfo }> {
+	let current = path.dirname(target);
+	while (current !== projectRoot) {
+		const state = await inspectPath(current);
+		if (state.type !== "missing") return { type: "ok", value: current };
+		const parent = path.dirname(current);
+		if (parent === current)
+			return {
+				type: "error",
+				error: errorInfo(parentMissingCode, `Parent directory at ${current} does not exist.`),
+			};
+		current = parent;
+	}
+	return { type: "ok", value: projectRoot };
+}
+
+async function requirePathAtOrBelow(
+	candidate: string,
+	projectRoot: string,
+	description: string,
+): Promise<WriteTargetValidationResult> {
+	try {
+		const resolved = await realpath(candidate);
+		if (isPathAtOrBelow(resolved, projectRoot)) return { ok: true };
+		return {
+			ok: false,
+			error: errorInfo(
+				"init-outside-project",
+				`${description} at ${candidate} resolves outside ${projectRoot}; refusing to manage it.`,
+			),
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorInfo(
+				"init-realpath-failed",
+				`Could not resolve ${description} at ${candidate}: ${formatErrorMessage(error)}`,
+			),
+		};
+	}
+}