@nseng-ai/areg 0.1.1 → 0.1.2

package/src/operations/manifest-sources.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+
+import type {
+	HarnessId,
+	HarnessScope,
+	PathState,
+	TextFileState,
+} from "@nseng-ai/harness-artifacts/api";
+
+export type AregManifestSourceType = "first-party" | "npm-module";
+
+export interface AregManifestSkillSourceProvenance {
+	type: AregManifestSourceType;
+	packageName: string;
+	relativePath: string;
+	version: string;
+}
+
+export interface AregManifestSkillSourceInspection {
+	skillName: string;
+	harness: HarnessId;
+	scope: HarnessScope;
+	manifestPath: string;
+	manifestKey: string;
+	provenance: AregManifestSkillSourceProvenance;
+	targetRootRelativePath: string;
+	targetSkillRelativePath: string;
+	skillDir: PathState;
+	skillMd: TextFileState;
+}
+
+export const aregManifestSkillSourceViewSchema = z.object({
+	harness: z.string(),
+	scope: z.string(),
+	manifestPath: z.string(),
+	manifestKey: z.string(),
+	sourceType: z.enum(["first-party", "npm-module"]),
+	packageName: z.string(),
+	sourceRelativePath: z.string(),
+	version: z.string(),
+	targetSkillRelativePath: z.string(),
+});
+
+export type AregManifestSkillSourceView = z.infer<typeof aregManifestSkillSourceViewSchema>;
+
+export function toManifestSkillSourceView(
+	source: AregManifestSkillSourceInspection,
+): AregManifestSkillSourceView {
+	return {
+		harness: source.harness,
+		scope: source.scope,
+		manifestPath: source.manifestPath,
+		manifestKey: source.manifestKey,
+		sourceType: source.provenance.type,
+		packageName: source.provenance.packageName,
+		sourceRelativePath: source.provenance.relativePath,
+		version: source.provenance.version,
+		targetSkillRelativePath: source.targetSkillRelativePath,
+	};
+}
+
+export function groupBySkillName(
+	sources: readonly AregManifestSkillSourceInspection[],
+): ReadonlyMap<string, readonly AregManifestSkillSourceInspection[]> {
+	const grouped = new Map<string, AregManifestSkillSourceInspection[]>();
+	for (const source of sources) {
+		const existing = grouped.get(source.skillName) ?? [];
+		existing.push(source);
+		grouped.set(source.skillName, existing);
+	}
+	return grouped;
+}
+
+export function manifestSourceViewsBySkillName(
+	sources: readonly AregManifestSkillSourceInspection[],
+): ReadonlyMap<string, readonly AregManifestSkillSourceView[]> {
+	return new Map(
+		[...groupBySkillName(sources)].map(([skillName, skillSources]) => [
+			skillName,
+			skillSources.map((source) => toManifestSkillSourceView(source)),
+		]),
+	);
+}
+
+export function isSkillKindLookupPath(relativePath: string): boolean {
+	return relativePath.startsWith("skills/") || relativePath.startsWith(".agents/skills/");
+}
+
+export function manifestSkillKindNames(
+	sources: readonly AregManifestSkillSourceInspection[],
+): readonly string[] {
+	return sources
+		.filter(
+			(source) =>
+				source.skillDir.type === "directory" &&
+				source.skillMd.type === "file" &&
+				isSkillKindLookupPath(source.targetSkillRelativePath),
+		)
+		.map((source) => source.skillName);
+}
+
+export type ManifestSkillSourceStatus = "ok" | "target-missing" | "md-missing";
+
+export function classifyManifestSkillSource(
+	source: AregManifestSkillSourceInspection,
+): ManifestSkillSourceStatus {
+	if (source.skillDir.type === "missing") return "target-missing";
+	if (source.skillMd.type === "missing") return "md-missing";
+	return "ok";
+}
+
+export type AregManifestInspectionError =
+	| { type: "manifest"; manifestPath: string; message: string }
+	| { type: "harness"; harness: HarnessId; message: string };
+
+export interface AregManifestSkillSourcesInspection {
+	sources: readonly AregManifestSkillSourceInspection[];
+	errors: readonly AregManifestInspectionError[];
+}

package/src/operations/pi-settings.ts

@@ -1,7 +1,7 @@
 import { formatErrorMessage, isRecord } from "@nseng-ai/foundation/primitives";
 import { err, type Result } from "@nseng-ai/foundation/result";
 
-import type { AregPathState, AregTextFileState } from "../gateways.ts";
+import type { PathState, TextFileState } from "@nseng-ai/harness-artifacts/api";
 import { rejectTextState, validateOptionalDirectoryState } from "./file-state.ts";
 
 export interface PiSettingsData {
@@ -12,10 +12,7 @@ export interface PiSettingsData {
 
 export type ParsePiSettingsResult = Result<PiSettingsData>;
 
-export function parsePiSettings(
-	piDir: AregPathState,
-	settings: AregTextFileState,
-): ParsePiSettingsResult {
+export function parsePiSettings(piDir: PathState, settings: TextFileState): ParsePiSettingsResult {
 	const piDirectory = validateOptionalDirectoryState({
 		pathLabel: ".pi",
 		state: piDir,

package/src/operations/project-inspection.ts

@@ -1,62 +1,54 @@
+import type { PathState, TextFileState } from "@nseng-ai/harness-artifacts/api";
+
 import type { AregCliContext } from "../context.ts";
 import type {
 	AregCheckPairingDirectory,
 	AregCheckSkillInspection,
-	AregInstructionFilesInspection,
-	AregPathState,
 	AregProjectBaseInspection,
 	AregReplacementInspection,
 	AregSkillKindSkillInspection,
 	AregSkillNameInventory,
-	AregTextFileState,
 } from "../gateways.ts";
+import {
+	manifestSkillKindNames,
+	type AregManifestSkillSourcesInspection,
+} from "./manifest-sources.ts";
 import { uniqueSortedStrings } from "../sort.ts";
-import { parseInspectedLockfile } from "./lockfile.ts";
+import { parseInspectedLockfile } from "@nseng-ai/harness-artifacts/api";
 
 export interface AregProjectInspectionFacts extends AregProjectBaseInspection {
-	piDir: AregPathState;
-	piSettings: AregTextFileState;
+	piDir: PathState;
+	piSettings: TextFileState;
 	replacement: AregReplacementInspection;
 	skillInventory: AregSkillNameInventory;
+	manifestSkillSources: AregManifestSkillSourcesInspection;
 }
 
 export interface AregCheckProjectInspection {
 	projectDir: string;
-	projectPathState: AregPathState;
-	lockfile: AregTextFileState;
+	projectPathState: PathState;
+	lockfile: TextFileState;
 	skillsDirectoryNames: readonly string[];
 	agentsSkillNames: readonly string[];
 	excludedSkillNames: readonly string[];
-	piDir: AregPathState;
-	piSettings: AregTextFileState;
+	piDir: PathState;
+	piSettings: TextFileState;
 	replacement: AregReplacementInspection;
+	manifestSkillSources: AregManifestSkillSourcesInspection;
 	skills: readonly AregCheckSkillInspection[];
 	pairingDirectories: readonly AregCheckPairingDirectory[];
 }
 
 export interface AregSkillKindProjectInspection {
 	projectDir: string;
-	projectPathState: AregPathState;
-	piDir: AregPathState;
-	piSettings: AregTextFileState;
+	projectPathState: PathState;
+	piDir: PathState;
+	piSettings: TextFileState;
 	replacement: AregReplacementInspection;
+	manifestSkillSources: AregManifestSkillSourcesInspection;
 	skills: readonly AregSkillKindSkillInspection[];
 }
 
-export type AregInitProjectInspection = AregProjectBaseInspection & AregInstructionFilesInspection;
-
-export async function inspectInitProject(
-	ctx: AregCliContext,
-	projectPath: string,
-): Promise<AregInitProjectInspection> {
-	const base = await ctx.project.inspectProjectBase({ cwd: ctx.cwd, projectPath, env: ctx.env });
-	const instructionFiles = await ctx.project.inspectInstructionFiles({
-		projectDir: base.projectDir,
-		env: ctx.env,
-	});
-	return { ...base, ...instructionFiles };
-}
-
 export async function collectProjectInspectionFacts(
 	ctx: AregCliContext,
 	projectPath: string,
@@ -70,12 +62,17 @@ export async function collectProjectInspectionFacts(
 		projectDir: base.projectDir,
 		env: ctx.env,
 	});
+	const manifestSkillSources = await ctx.project.inspectManifestSkillSources({
+		projectDir: base.projectDir,
+		env: ctx.env,
+	});
 	return {
 		...base,
 		piDir: piArtifacts.piDir,
 		piSettings: piArtifacts.piSettings,
 		replacement: piArtifacts.replacement,
 		skillInventory,
+		manifestSkillSources,
 	};
 }
 
@@ -92,11 +89,13 @@ export async function inspectCheckProject(
 	const lockfileSkillNames = lockfileResult.ok
 		? lockfileResult.value.skills.map((skill) => skill.name)
 		: [];
+	const manifestSkillNames = facts.manifestSkillSources.sources.map((source) => source.skillName);
 	const skillNames = uniqueSortedStrings([
 		...lockfileSkillNames,
 		...facts.skillInventory.skillsDirectoryNames,
 		...facts.skillInventory.agentsSkillNames,
 		...facts.skillInventory.claudeSkillNames,
+		...manifestSkillNames,
 	]);
 	return {
 		projectDir: facts.projectDir,
@@ -108,6 +107,7 @@ export async function inspectCheckProject(
 		piDir: facts.piDir,
 		piSettings: facts.piSettings,
 		replacement: facts.replacement,
+		manifestSkillSources: facts.manifestSkillSources,
 		skills: await collectCheckSkillInspections(ctx, facts.projectDir, skillNames),
 		pairingDirectories: await ctx.project.inspectPairingDirectories({
 			projectDir: facts.projectDir,
@@ -127,10 +127,14 @@ export async function inspectSkillKindProject(
 		piDir: facts.piDir,
 		piSettings: facts.piSettings,
 		replacement: facts.replacement,
+		manifestSkillSources: facts.manifestSkillSources,
 		skills: await collectSkillKindInspections(
 			ctx,
 			facts.projectDir,
-			facts.skillInventory.skillKindNames,
+			uniqueSortedStrings([
+				...facts.skillInventory.skillKindNames,
+				...manifestSkillKindNames(facts.manifestSkillSources.sources),
+			]),
 		),
 	};
 }

package/src/operations/project-mutations.ts

@@ -3,7 +3,6 @@ import type {
 	AregErrorInfo,
 	AregProjectGateway,
 	AregProjectManagedTargetRequest,
-	AregProjectMutationPolicy,
 	AregProjectMutationResult,
 } from "../gateways.ts";
 
@@ -29,34 +28,23 @@ interface ProjectDeleteSymlinkPlan {
 	description: string;
 }
 
-interface BaseApplyProjectMutationPlanRequest {
+interface ApplyProjectMutationPlanRequest {
 	ctx: AregCliContext;
 	projectDir: string;
 	writes: readonly ProjectTextWritePlan[];
+	deletes: readonly ProjectDeletePlan[];
+	deleteSymlinks: readonly ProjectDeleteSymlinkPlan[];
+	removeEmptyDirs: readonly ProjectRemoveEmptyDirPlan[];
 	execute?: boolean;
 }
 
-type ApplyProjectMutationPlanRequest =
-	| (BaseApplyProjectMutationPlanRequest & {
-			policy: Exclude<AregProjectMutationPolicy, "skill-kind">;
-	  })
-	| (BaseApplyProjectMutationPlanRequest & {
-			policy: "skill-kind";
-			deletes: readonly ProjectDeletePlan[];
-			deleteSymlinks: readonly ProjectDeleteSymlinkPlan[];
-			removeEmptyDirs: readonly ProjectRemoveEmptyDirPlan[];
-	  });
-
 export const PROJECT_FILE_MUTATION_OPERATION_TYPES = [
 	"write",
 	"delete",
 	"delete-symlink",
 	"remove-empty-dir",
 ] as const;
-export const PROJECT_MUTATION_OPERATION_TYPES = [
-	...PROJECT_FILE_MUTATION_OPERATION_TYPES,
-	"external",
-] as const;
+export const PROJECT_MUTATION_OPERATION_TYPES = [...PROJECT_FILE_MUTATION_OPERATION_TYPES] as const;
 export const PROJECT_MUTATION_OPERATION_STATUSES = [
 	"applied",
 	"failed",
@@ -211,7 +199,6 @@ function flattenProjectMutationPlan(
 			plan,
 		}),
 	);
-	if (request.policy !== "skill-kind") return writes;
 	const deletes = request.deletes.map(
 		(plan): DeleteOperation => ({
 			type: "delete",
@@ -248,7 +235,6 @@ const PROJECT_MUTATION_OPERATION_HANDLERS = {
 				content: operation.plan.content,
 				description: operation.plan.description,
 				createParent: operation.plan.createParent,
-				policy: request.policy,
 				env: request.ctx.env,
 			});
 		},
@@ -259,7 +245,6 @@ const PROJECT_MUTATION_OPERATION_HANDLERS = {
 				content: operation.plan.content,
 				description: operation.plan.description,
 				createParent: operation.plan.createParent,
-				policy: request.policy,
 				env: request.ctx.env,
 			});
 		},
@@ -339,7 +324,6 @@ function managedTargetRequest(
 		projectDir: request.projectDir,
 		relativePath: operation.plan.relativePath,
 		description: operation.plan.description,
-		policy: "skill-kind",
 		env: request.ctx.env,
 	};
 }

package/src/operations/project-resolution.ts

@@ -1,9 +1,9 @@
 import type { AregCliContext } from "../context.ts";
-import type { AregPathState } from "../gateways.ts";
+import type { PathState } from "@nseng-ai/harness-artifacts/api";
 
 export interface ProjectPathInspection {
 	projectDir: string;
-	projectPathState: AregPathState;
+	projectPathState: PathState;
 }
 
 export type ResolvedProjectGitRoot<TInspection extends ProjectPathInspection> =

package/src/operations/skill-find.ts

@@ -7,13 +7,18 @@ import {
 	skillLookupFileRelativePath,
 	skillLookupRootRank,
 	type SkillLookupRoot,
-} from "../skill-lookup.ts";
+} from "@nseng-ai/foundation/skill-lookup";
 import { z } from "zod";
 
 import type { AregCliContext } from "../context.ts";
 import type { AregSkillFindSkillInspection } from "../gateways.ts";
+import {
+	aregManifestSkillSourceViewSchema,
+	manifestSourceViewsBySkillName,
+	type AregManifestSkillSourceView,
+} from "./manifest-sources.ts";
 import { toProjectPath } from "../gateways/project-fs.ts";
-import { parseSkillFrontmatterBlock } from "./frontmatter.ts";
+import { parseSkillFrontmatterBlock } from "@nseng-ai/harness-artifacts/api";
 import { inspectResolvedProjectGitRoot } from "./project-resolution.ts";
 
 const skillFindRootSchema = z.enum(SKILL_LOOKUP_ROOTS);
@@ -25,6 +30,8 @@ const skillFindWarningSchema = z.object({
 	path: z.string(),
 });
 
+const skillFindManifestSourceSchema = aregManifestSkillSourceViewSchema;
+
 const skillFindMatchSchema = z.object({
 	name: z.string(),
 	root: skillFindRootSchema,
@@ -37,6 +44,7 @@ const skillFindMatchSchema = z.object({
 	frontmatterName: z.string().optional(),
 	description: z.string().optional(),
 	shouldDisableModelInvocation: z.boolean().optional(),
+	manifestSources: z.array(skillFindManifestSourceSchema).optional(),
 	warnings: z.array(skillFindWarningSchema).optional(),
 });
 
@@ -103,13 +111,18 @@ export async function runSkillFind(
 	if (resolved.type === "error") return failure("project-inspection-failed", resolved.message);
 	const projectDir = resolved.projectDir;
 	const inspection = await ctx.project.inspectSkillFindRoots({ projectDir, env: ctx.env });
+	const manifestSources = await ctx.project.inspectManifestSkillSources({
+		projectDir,
+		env: ctx.env,
+	});
+	const manifestSourceViews = manifestSourceViewsBySkillName(manifestSources.sources);
 	const searchedRoots = buildSkillFindSearchedRoots(projectDir, request.skill);
 	const exactSkills = inspection.skills
 		.filter((skill) => skill.name === request.skill)
 		.toSorted(compareSkillFindInspection);
 	if (exactSkills.length > 0) {
 		const matches = exactSkills.map((skill, index) =>
-			toSkillFindMatch(projectDir, skill, index === 0),
+			toSkillFindMatch(projectDir, skill, index === 0, manifestSourceViews.get(skill.name)),
 		);
 		const preferred = matches[0];
 		if (preferred === undefined)
@@ -155,6 +168,7 @@ function toSkillFindMatch(
 	projectDir: string,
 	skill: AregSkillFindSkillInspection,
 	isPreferred: boolean,
+	manifestSources: readonly AregManifestSkillSourceView[] | undefined,
 ): SkillFindMatch {
 	const skillFileRelativePath = skillLookupFileRelativePath(skill.root, skill.name);
 	const skillFilePath = toProjectPath(projectDir, skillFileRelativePath);
@@ -169,6 +183,7 @@ function toSkillFindMatch(
 		basePath: toProjectPath(projectDir, skill.baseRelativePath),
 		skillFilePath,
 		...frontmatter.fields,
+		...(manifestSources === undefined ? {} : { manifestSources: [...manifestSources] }),
 		...(frontmatter.warnings.length === 0 ? {} : { warnings: frontmatter.warnings }),
 	};
 }
@@ -280,6 +295,11 @@ function renderSkillFindSuccess(result: SkillFindSuccessResult): string {
 	for (const match of result.matches) {
 		const marker = hasDuplicates ? (match.isPreferred ? "* " : "  ") : "";
 		lines.push(`  ${marker}${match.skillFileRelativePath}`);
+		for (const source of match.manifestSources ?? []) {
+			lines.push(
+				`    manifest: ${source.harness} ${source.manifestKey} ${source.packageName}@${source.version}`,
+			);
+		}
 	}
 	return lines.join("\n");
 }

package/src/operations/skill-kind-apply-plan.ts

@@ -13,7 +13,7 @@ import {
 	claudeSkillMirrorRelativePath,
 	expectedAgentsSkillSymlinkTarget,
 	expectedClaudeSkillSymlinkTarget,
-} from "./skill-mirror-conventions.ts";
+} from "@nseng-ai/harness-artifacts/api";
 import { parsePiSettings, type PiSettingsData } from "./pi-settings.ts";
 import {
 	PROJECT_FILE_MUTATION_OPERATION_TYPES,
@@ -416,7 +416,7 @@ export function deletionPrompt(plan: SkillKindApplyPlan): string {
 		.filter(isDeletionOperation)
 		.map((operation) => `- ${operation.relativePath}`)
 		.join("\n");
-	return `Apply ${plan.kind} to ${plan.skill} will delete managed artifacts:\n${paths}\nContinue?`;
+	return `Apply ${plan.kind} to ${plan.skill} will delete harness overlays:\n${paths}\nContinue?`;
 }
 
 function isDeletionOperation(operation: PlannedApplyOperation): boolean {

package/src/operations/skill-kind-frontmatter.ts

@@ -1,6 +1,6 @@
 import type { Result } from "@nseng-ai/foundation/result";
 
-import { transformSkillFrontmatter } from "./frontmatter.ts";
+import { transformSkillFrontmatter } from "@nseng-ai/harness-artifacts/api";
 import {
 	DISABLE_MODEL_INVOCATION_KEY,
 	KIND_PROPERTIES,

package/src/operations/skill-kind-inference.ts

@@ -1,8 +1,15 @@
 import { err, type Result } from "@nseng-ai/foundation/result";
 
 import type { AregSkillKindSkillInspection } from "../gateways.ts";
-import { sortStrings } from "../sort.ts";
-import { parseSkillFrontmatterBlock, type SkillFrontmatterData } from "./frontmatter.ts";
+import { sortStringsLocaleAware } from "../sort.ts";
+import {
+	manifestSourceViewsBySkillName,
+	type AregManifestSkillSourceView,
+} from "./manifest-sources.ts";
+import {
+	parseSkillFrontmatterBlock,
+	type SkillFrontmatterData,
+} from "@nseng-ai/harness-artifacts/api";
 import {
 	formatReplacementLabel,
 	replacementAdvice,
@@ -90,6 +97,8 @@ export interface SkillKindReplacementInfo {
 	advice?: string;
 }
 
+export type SkillKindManifestSourceInfo = AregManifestSkillSourceView;
+
 export interface SkillKindRecord {
 	skill: string;
 	kind: InferredSkillInvocationKind;
@@ -98,6 +107,7 @@ export interface SkillKindRecord {
 	piExtension: PiExtensionStatus;
 	artifacts: SkillKindArtifactFacts;
 	replacement: SkillKindReplacementInfo;
+	manifestSources: readonly SkillKindManifestSourceInfo[];
 	notes: readonly string[];
 }
 
@@ -164,6 +174,7 @@ export function inferSkillKindRecord(options: {
 		piExtension: piExtensionStatus(kind, artifacts, options.replacement),
 		artifacts,
 		replacement,
+		manifestSources: [],
 		notes: buildNotes({
 			skillName: options.skillName,
 			kind,
@@ -188,6 +199,9 @@ export function buildSkillKindRecords(
 	const piSettings = parsePiSettings(inspection.piDir, inspection.piSettings);
 	if (!piSettings.ok) return piSettings;
 	const records: SkillKindRecord[] = [];
+	const manifestSourceViews = manifestSourceViewsBySkillName(
+		inspection.manifestSkillSources.sources,
+	);
 	for (const skill of sortSkills(inspection.skills)) {
 		const readiness = validateInspectableSkill(skill);
 		if (!readiness.ok) return readiness;
@@ -202,17 +216,19 @@ export function buildSkillKindRecords(
 		);
 		if (!frontmatter.ok) return frontmatter;
 		const replacement = verifyPiReplacement(skill.name, inspection.replacement);
-		records.push(
-			inferSkillKindRecord({
-				skillName: skill.name,
-				frontmatter: frontmatter.value,
-				hasCodexSidecar: skill.openaiPolicy.type === "file",
-				isPiExcluded: piSettings.value.exclusions.includes(`-skills/${skill.name}`),
-				hasAgentsMirror: skill.agentsPath.type !== "missing",
-				hasClaudeMirror: skill.claudePath.type !== "missing",
-				replacement,
-			}),
-		);
+		const record = inferSkillKindRecord({
+			skillName: skill.name,
+			frontmatter: frontmatter.value,
+			hasCodexSidecar: skill.openaiPolicy.type === "file",
+			isPiExcluded: piSettings.value.exclusions.includes(`-skills/${skill.name}`),
+			hasAgentsMirror: skill.agentsPath.type !== "missing",
+			hasClaudeMirror: skill.claudePath.type !== "missing",
+			replacement,
+		});
+		records.push({
+			...record,
+			manifestSources: manifestSourceViews.get(skill.name) ?? [],
+		});
 	}
 	return { ok: true, value: records };
 }
@@ -385,7 +401,7 @@ function sortSkills(
 	skills: readonly AregSkillKindSkillInspection[],
 ): readonly AregSkillKindSkillInspection[] {
 	const byName = new Map(skills.map((skill) => [skill.name, skill]));
-	return sortStrings([...byName.keys()])
+	return sortStringsLocaleAware([...byName.keys()])
 		.map((name) => byName.get(name))
 		.filter((skill): skill is AregSkillKindSkillInspection => skill !== undefined);
 }