@nseng-ai/areg 0.1.1 → 0.1.2

package/src/gateways/errors.ts

@@ -1,5 +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 };
+export function errorInfo(code: string, message: string): AregErrorInfo {
+	return { code, message };
 }

package/src/gateways/fs-utils.ts

@@ -2,9 +2,9 @@ import { lstat, readlink } from "node:fs/promises";
 
 import { errorCodeFromUnknown, isPathInside } from "@nseng-ai/foundation/primitives";
 
-import type { AregPathState } from "../gateways.ts";
+import type { PathState } from "@nseng-ai/harness-artifacts/api";
 
-export async function inspectPath(candidate: string): Promise<AregPathState> {
+export async function inspectPath(candidate: string): Promise<PathState> {
 	try {
 		const info = await lstat(candidate);
 		if (info.isSymbolicLink()) return { type: "symlink", target: await readlink(candidate) };

package/src/gateways/project-fs.ts

@@ -3,14 +3,14 @@ import path from "node:path";
 
 import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
 
-import type { AregErrorInfo, AregProjectMutationPolicy, AregTextFileState } from "../gateways.ts";
+import type { AregErrorInfo } from "../gateways.ts";
 import {
 	classifySkillMirrorSymlinkState,
 	expectedMirrorTarget,
-} from "../operations/skill-mirror-conventions.ts";
+	type TextFileState,
+} from "@nseng-ai/harness-artifacts/api";
 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";
 
@@ -19,14 +19,12 @@ export function toProjectPath(projectRoot: string, relativePath: string): string
 }
 
 interface ResolveAllowedWriteTargetOptions {
-	policy: AregProjectMutationPolicy;
 	projectRoot: string;
 	relativePath: string;
 	description: string;
 }
 
 interface ValidateTextWriteTargetOptions {
-	policy: AregProjectMutationPolicy;
 	target: string;
 	projectRoot: string;
 	description: string;
@@ -35,7 +33,7 @@ interface ValidateTextWriteTargetOptions {
 
 type WriteTargetValidationResult = { ok: true } | { ok: false; error: AregErrorInfo };
 
-export async function inspectTextFile(candidate: string): Promise<AregTextFileState> {
+export async function inspectTextFile(candidate: string): Promise<TextFileState> {
 	const pathState = await inspectPath(candidate);
 	if (
 		pathState.type === "missing" ||
@@ -60,14 +58,14 @@ export async function resolveExistingDirectory(
 		return {
 			type: "error",
 			error: errorInfo(
-				"init-symlink",
+				"project-root-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.`),
+			error: errorInfo("project-root-not-directory", `${candidate} exists but is not a directory.`),
 		};
 	try {
 		return { type: "ok", value: await realpath(candidate) };
@@ -75,7 +73,7 @@ export async function resolveExistingDirectory(
 		return {
 			type: "error",
 			error: errorInfo(
-				"init-realpath-failed",
+				"realpath-failed",
 				`Could not resolve ${description} at ${candidate}: ${formatErrorMessage(error)}`,
 			),
 		};
@@ -85,37 +83,21 @@ export async function resolveExistingDirectory(
 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),
+				"skill-kind-target-refused",
+				`Refusing to write ${options.description}: unsafe target ${options.relativePath}.`,
 			),
 		};
 	}
-	if (
-		!descriptor.shouldCheckUnsupportedFirst &&
-		!descriptor.isAllowedRelativePath(options.relativePath)
-	) {
+	if (!isSkillKindWritablePath(options.relativePath)) {
 		return {
 			type: "error",
 			error: errorInfo(
-				descriptor.refusedTargetCode,
-				descriptor.unsupportedMessage(options.relativePath, options.description),
+				"skill-kind-target-refused",
+				`Refusing to write ${options.description}: unsupported target ${options.relativePath}.`,
 			),
 		};
 	}
@@ -125,38 +107,44 @@ export function resolveAllowedWriteTarget(
 		return {
 			type: "error",
 			error: errorInfo(
-				descriptor.refusedTargetCode,
-				descriptor.outsideMessage(options.relativePath, options.description),
+				"skill-kind-target-refused",
+				`Refusing to write ${options.description}: target ${options.relativePath} resolves outside the project.`,
 			),
 		};
 	}
 	return { type: "ok", value: target };
 }
 
+const SKILL_KIND_WRITABLE_PATH_RE =
+	/^(?:skills|\.agents\/skills)\/[^/]+\/(?:SKILL\.md|agents(?:\/openai\.yaml)?)$/u;
+
+function isSkillKindWritablePath(relativePath: string): boolean {
+	return SKILL_KIND_WRITABLE_PATH_RE.test(relativePath) || relativePath === ".pi/settings.json";
+}
+
 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,
+				"skill-kind-symlink",
 				`${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.`),
+			error: errorInfo("skill-kind-not-file", `${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,
+		"skill-kind-parent-missing",
 	);
 	if (parent.type === "error") return { ok: false, error: parent.error };
 	const parentState = await inspectPath(parent.value);
@@ -164,7 +152,7 @@ export async function validateWriteTarget(
 		return {
 			ok: false,
 			error: errorInfo(
-				descriptor.parentSymlinkCode,
+				"skill-kind-parent-symlink",
 				`Parent directory at ${parent.value} is a symlink; refusing to manage it.`,
 			),
 		};
@@ -172,7 +160,7 @@ export async function validateWriteTarget(
 		return {
 			ok: false,
 			error: errorInfo(
-				descriptor.parentNotDirectoryCode,
+				"skill-kind-parent-not-directory",
 				`${parent.value} exists but is not a directory.`,
 			),
 		};
@@ -186,7 +174,7 @@ export async function validateWriteTarget(
 		return {
 			ok: false,
 			error: errorInfo(
-				descriptor.parentMissingCode,
+				"skill-kind-parent-missing",
 				`Parent directory at ${path.dirname(options.target)} does not exist.`,
 			),
 		};
@@ -304,7 +292,7 @@ async function requirePathAtOrBelow(
 		return {
 			ok: false,
 			error: errorInfo(
-				"init-outside-project",
+				"outside-project",
 				`${description} at ${candidate} resolves outside ${projectRoot}; refusing to manage it.`,
 			),
 		};
@@ -312,7 +300,7 @@ async function requirePathAtOrBelow(
 		return {
 			ok: false,
 			error: errorInfo(
-				"init-realpath-failed",
+				"realpath-failed",
 				`Could not resolve ${description} at ${candidate}: ${formatErrorMessage(error)}`,
 			),
 		};

package/src/gateways/project-gateway.ts

@@ -3,7 +3,6 @@ import { lstat, mkdir, readdir, realpath, rm, rmdir, unlink, writeFile } from "n
 import path from "node:path";
 
 import { RealGitGateway } from "@nseng-ai/capability-kit/git";
-import type { GitGateway } from "@nseng-ai/capability-kit/git";
 import { visibleCommandBackedReplacementSurfaces } from "@nseng-ai/command-backed-skill-registry";
 import { NodeCommandExecApi } from "@nseng-ai/foundation/exec";
 import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
@@ -13,13 +12,22 @@ import {
 	skillLookupDescriptorForSourceType,
 	skillLookupFileRelativePath,
 	type SkillLookupSourceType,
-} from "../skill-lookup.ts";
+} from "@nseng-ai/foundation/skill-lookup";
+import {
+	ALL_HARNESS_IDS,
+	INSTALL_MANIFEST_FILE_NAME,
+	readInstallManifestAtRoot,
+	resolveHarnessSkillRoot,
+	type InstallManifestEntryData,
+	type TextFileState,
+} from "@nseng-ai/harness-artifacts/api";
 
 import { AREG_SKILL_KIND_ROOT_DESCRIPTORS, skillKindDescriptorForSourceType } from "../gateways.ts";
 import type {
 	AregCheckPairingDirectory,
 	AregCheckSkillInspection,
 	AregErrorInfo,
+	AregGitGateway,
 	AregPiSkillInventoryInspection,
 	AregProjectFileDeleteRequest,
 	AregProjectGateway,
@@ -34,11 +42,9 @@ import type {
 	AregSkillKindResolveRequest,
 	AregSkillKindResolveResult,
 	AregSkillKindSkillInspection,
-	AregTextFileState,
 } from "../gateways.ts";
-import { sortStrings } from "../sort.ts";
+import { sortStringsLocaleAware } from "../sort.ts";
 import { errorInfo } from "./errors.ts";
-import { getAregProjectMutationPolicyDescriptor } from "./mutation-policy.ts";
 import {
 	inspectPath,
 	inspectTextFile,
@@ -51,6 +57,11 @@ import {
 	validateSkillKindRemoveDirTarget,
 	validateWriteTarget,
 } from "./project-fs.ts";
+import type {
+	AregManifestInspectionError,
+	AregManifestSkillSourceInspection,
+	AregManifestSkillSourcesInspection,
+} from "../operations/manifest-sources.ts";
 import { classifyResolvedSkillKindInspection } from "./skill-kind-classification.ts";
 
 const PI_GENERIC_REPLACEMENT_ADAPTER_RELATIVE_PATH = ".pi/extensions/backing-skill-commands.ts";
@@ -61,9 +72,9 @@ const PI_GENERIC_REPLACEMENT_PACKAGE_MODULE_RELATIVE_PATH =
 const AREG_VISIBLE_REPLACEMENT_SURFACES = visibleCommandBackedReplacementSurfaces();
 
 export class RealAregProjectGateway implements AregProjectGateway {
-	private readonly git: GitGateway;
+	private readonly git: AregGitGateway;
 
-	constructor(options: { git?: GitGateway } = {}) {
+	constructor(options: { git?: AregGitGateway } = {}) {
 		this.git = options.git ?? new RealGitGateway(new NodeCommandExecApi());
 	}
 
@@ -78,17 +89,6 @@ export class RealAregProjectGateway implements AregProjectGateway {
 		};
 	}
 
-	async inspectInstructionFiles(request: { projectDir: string; env: NodeJS.ProcessEnv }) {
-		return {
-			agentsMd: await inspectTextFile(path.join(request.projectDir, "AGENTS.md")),
-			claudeMd: await inspectTextFile(path.join(request.projectDir, "CLAUDE.md")),
-			claudeDir: await inspectPath(path.join(request.projectDir, ".claude")),
-			claudeSettings: await inspectTextFile(
-				path.join(request.projectDir, ".claude", "settings.local.json"),
-			),
-		};
-	}
-
 	async inspectPiArtifacts(request: { projectDir: string; env: NodeJS.ProcessEnv }) {
 		return {
 			piDir: await inspectPath(path.join(request.projectDir, ".pi")),
@@ -117,6 +117,13 @@ export class RealAregProjectGateway implements AregProjectGateway {
 		};
 	}
 
+	async inspectManifestSkillSources(request: {
+		projectDir: string;
+		env: NodeJS.ProcessEnv;
+	}): Promise<AregManifestSkillSourcesInspection> {
+		return inspectManifestSkillSources(request.projectDir, request.env);
+	}
+
 	async inspectSkillFindRoots(request: {
 		projectDir: string;
 		env: NodeJS.ProcessEnv;
@@ -192,7 +199,6 @@ export class RealAregProjectGateway implements AregProjectGateway {
 	async writeTextFile(request: AregProjectTextWriteRequest): Promise<AregProjectMutationResult> {
 		const target = await resolveWriteTextFileTarget(request);
 		if (target.type === "error") return { ok: false, error: target.error };
-		const policyDescriptor = getAregProjectMutationPolicyDescriptor(request.policy);
 		if (request.createParent) {
 			try {
 				await mkdir(path.dirname(target.value), { recursive: true });
@@ -200,13 +206,12 @@ export class RealAregProjectGateway implements AregProjectGateway {
 				return {
 					ok: false,
 					error: errorInfo(
-						policyDescriptor.parentCreateFailedCode,
+						"skill-kind-parent-create-failed",
 						`Failed to create ${path.dirname(target.value)}: ${formatErrorMessage(error)}`,
 					),
 				};
 			}
 			const revalidation = await validateWriteTarget({
-				policy: request.policy,
 				target: target.value,
 				projectRoot: target.projectRoot,
 				shouldCreateParent: request.createParent,
@@ -221,7 +226,7 @@ export class RealAregProjectGateway implements AregProjectGateway {
 			return {
 				ok: false,
 				error: errorInfo(
-					policyDescriptor.writeFailedCode,
+					"skill-kind-write-failed",
 					`Failed to write ${request.description} at ${target.value}: ${formatErrorMessage(error)}`,
 				),
 			};
@@ -294,7 +299,6 @@ async function resolveWriteTextFileTarget(
 	const target = await resolveProjectMutationTarget(request);
 	if (target.type === "error") return target;
 	const validation = await validateWriteTarget({
-		policy: request.policy,
 		target: target.value,
 		projectRoot: target.projectRoot,
 		shouldCreateParent: request.createParent,
@@ -361,7 +365,6 @@ async function resolveRemoveEmptyDirTarget(
 
 async function resolveProjectMutationTarget(request: {
 	projectDir: string;
-	policy: AregProjectTextWriteRequest["policy"];
 	relativePath: string;
 	description: string;
 }): Promise<
@@ -370,7 +373,6 @@ async function resolveProjectMutationTarget(request: {
 	const projectRoot = await resolveExistingDirectory(request.projectDir, "project root");
 	if (projectRoot.type === "error") return { type: "error", error: projectRoot.error };
 	const target = resolveAllowedWriteTarget({
-		policy: request.policy,
 		projectRoot: projectRoot.value,
 		relativePath: request.relativePath,
 		description: request.description,
@@ -444,7 +446,7 @@ async function listSkillKindNames(projectDir: string): Promise<string[]> {
 }
 
 function collectSortedUniqueNames(namesByRoot: readonly (readonly string[])[]): string[] {
-	return sortStrings([...new Set(namesByRoot.flat())]);
+	return sortStringsLocaleAware([...new Set(namesByRoot.flat())]);
 }
 
 async function listFirstPartySkillKindNames(projectDir: string): Promise<string[]> {
@@ -484,6 +486,71 @@ async function listVendoredSkillKindNames(projectDir: string): Promise<string[]>
 	).map((entry) => entry.name);
 }
 
+async function inspectManifestSkillSources(
+	projectDir: string,
+	env: NodeJS.ProcessEnv,
+): Promise<AregManifestSkillSourcesInspection> {
+	const sources: AregManifestSkillSourceInspection[] = [];
+	const errors: AregManifestInspectionError[] = [];
+	const context = { projectRoot: projectDir, homeDir: env.HOME ?? "", env };
+	for (const harness of ALL_HARNESS_IDS) {
+		const root = resolveHarnessSkillRoot({ harness, scope: "project", context });
+		if (!root.ok) {
+			errors.push({ type: "harness", harness, message: root.error.message });
+			continue;
+		}
+		const manifestPath = path.join(root.value.rootPath, INSTALL_MANIFEST_FILE_NAME);
+		const manifest = await readInstallManifestAtRoot({ targetRoot: root.value.rootPath });
+		if (!manifest.ok) {
+			errors.push({ type: "manifest", manifestPath, message: manifest.error.message });
+			continue;
+		}
+		for (const [manifestKey, entry] of Object.entries(manifest.value.artifacts)) {
+			if (entry.kind !== "skill") continue;
+			sources.push(
+				await inspectManifestSkillSource({ projectDir, manifestPath, manifestKey, entry }),
+			);
+		}
+	}
+	return { sources: sortManifestSkillSources(sources), errors };
+}
+
+interface InspectManifestSkillSourceOptions {
+	projectDir: string;
+	manifestPath: string;
+	manifestKey: string;
+	entry: InstallManifestEntryData;
+}
+
+async function inspectManifestSkillSource(
+	options: InspectManifestSkillSourceOptions,
+): Promise<AregManifestSkillSourceInspection> {
+	const { projectDir, manifestPath, manifestKey, entry } = options;
+	return {
+		skillName: entry.provisionName,
+		harness: entry.harness,
+		scope: entry.scope,
+		manifestPath,
+		manifestKey,
+		provenance: { ...entry.source },
+		targetRootRelativePath: path.relative(projectDir, entry.targetRoot),
+		targetSkillRelativePath: path.relative(projectDir, entry.targetArtifactPath),
+		skillDir: await inspectPath(entry.targetArtifactPath),
+		skillMd: await inspectTextFile(path.join(entry.targetArtifactPath, "SKILL.md")),
+	};
+}
+
+function sortManifestSkillSources(
+	sources: readonly AregManifestSkillSourceInspection[],
+): AregManifestSkillSourceInspection[] {
+	return [...sources].sort(
+		(left, right) =>
+			left.skillName.localeCompare(right.skillName) ||
+			left.harness.localeCompare(right.harness) ||
+			left.manifestKey.localeCompare(right.manifestKey),
+	);
+}
+
 async function inspectSkillFindRoots(projectDir: string): Promise<AregSkillFindSkillInspection[]> {
 	const skills: AregSkillFindSkillInspection[] = [];
 	for (const root of SKILL_LOOKUP_ROOT_DESCRIPTORS) {
@@ -517,7 +584,7 @@ interface ScanSkillRootOptions {
 interface ScannedSkillRootEntry {
 	name: string;
 	dirent: Dirent;
-	skillMd: AregTextFileState;
+	skillMd: TextFileState;
 }
 
 async function scanSkillRootEntries(
@@ -727,7 +794,7 @@ async function listChildNames(directory: string): Promise<string[]> {
 		const info = await lstat(directory);
 		if (!info.isDirectory()) return [];
 		const entries = await readdir(directory);
-		return sortStrings(entries.filter((entry) => entry !== ".DS_Store"));
+		return sortStringsLocaleAware(entries.filter((entry) => entry !== ".DS_Store"));
 	} catch (error) {
 		if (isNodeErrorCode(error, "ENOENT")) return [];
 		return [];
@@ -736,7 +803,7 @@ async function listChildNames(directory: string): Promise<string[]> {
 
 async function readLocallyExcludedSkillNames(options: {
 	projectDir: string;
-	git: GitGateway;
+	git: AregGitGateway;
 }): Promise<string[]> {
 	const gitPath = await options.git.gitPath({
 		cwd: options.projectDir,
@@ -754,7 +821,7 @@ async function readLocallyExcludedSkillNames(options: {
 			if (line.startsWith(prefix)) names.add(line.slice(prefix.length));
 		}
 	}
-	return sortStrings([...names]);
+	return sortStringsLocaleAware([...names]);
 }
 
 async function inspectPairingDirectories(projectDir: string): Promise<AregCheckPairingDirectory[]> {
@@ -784,7 +851,7 @@ async function inspectPairingDirectories(projectDir: string): Promise<AregCheckP
 				...(claude.type === "file" ? { claudeText: claude.text } : {}),
 			});
 		}
-		const subdirs = sortStrings(
+		const subdirs = sortStringsLocaleAware(
 			entries
 				.filter((entry) => entry.isDirectory())
 				.map((entry) => entry.name)