@nseng-ai/areg 0.1.1

package/src/operations/pi-replacement.ts

@@ -0,0 +1,33 @@
+import { commandBackedSkillSurface } from "@nseng-ai/command-backed-skill-registry";
+
+export interface PiReplacementFacts {
+	verifiedSurfaces: readonly string[];
+}
+
+export interface PiReplacementVerification {
+	verified: boolean;
+	surface?: string;
+}
+
+export function verifyPiReplacement(
+	skillName: string,
+	facts: PiReplacementFacts,
+): PiReplacementVerification {
+	const surface = commandBackedSkillSurface(skillName);
+	if (surface === undefined) return { verified: false };
+	return { verified: facts.verifiedSurfaces.includes(surface), surface };
+}
+
+export function formatReplacementLabel(replacement: PiReplacementVerification): string {
+	const prefix = replacement.verified ? "replacement-verified" : "replacement-missing";
+	return replacement.surface === undefined ? prefix : `${prefix}:${replacement.surface}`;
+}
+
+export function replacementAdvice(skillName: string, surface: string | undefined): string {
+	const expected = surface === undefined ? "a replacement Pi command" : `/${surface}`;
+	return [
+		`Skill '${skillName}' would hide /skill:${skillName} in Pi, but ${expected} is not verified.`,
+		`Add a replacement command that resolves '${skillName}' with shared skill lookup / areg skill find semantics, then reads the returned preferred SKILL.md path because native Pi skill discovery will exclude /skill:${skillName}.`,
+		"Add tests proving the command works while the backing skill is excluded.",
+	].join(" ");
+}

package/src/operations/pi-settings.ts

@@ -0,0 +1,60 @@
+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 { rejectTextState, validateOptionalDirectoryState } from "./file-state.ts";
+
+export interface PiSettingsData {
+	text: string | undefined;
+	data: Record<string, unknown> | undefined;
+	exclusions: readonly string[];
+}
+
+export type ParsePiSettingsResult = Result<PiSettingsData>;
+
+export function parsePiSettings(
+	piDir: AregPathState,
+	settings: AregTextFileState,
+): ParsePiSettingsResult {
+	const piDirectory = validateOptionalDirectoryState({
+		pathLabel: ".pi",
+		state: piDir,
+		action: "inspect Pi settings",
+	});
+	if (!piDirectory.ok) return piDirectory;
+	if (settings.type === "missing")
+		return { ok: true, value: { text: undefined, data: undefined, exclusions: [] } };
+	if (settings.type !== "file")
+		return rejectTextState({
+			pathLabel: ".pi/settings.json",
+			state: settings,
+			action: "inspect Pi settings",
+			unreadableMode: "not-file",
+		});
+	let data: unknown;
+	try {
+		data = JSON.parse(settings.text);
+	} catch (error) {
+		return err({
+			code: "pi_settings_invalid_json",
+			message: `Invalid JSON in .pi/settings.json: ${formatErrorMessage(error)}.`,
+		});
+	}
+	if (!isRecord(data))
+		return err({
+			code: "pi_settings_not_object",
+			message: ".pi/settings.json must contain a JSON object.",
+		});
+	if (data.skills === undefined)
+		return { ok: true, value: { text: settings.text, data, exclusions: [] } };
+	if (!isStringArray(data.skills))
+		return err({
+			code: "pi_settings_skills_not_string_array",
+			message: ".pi/settings.json field 'skills' must be an array of strings.",
+		});
+	return { ok: true, value: { text: settings.text, data, exclusions: data.skills } };
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}

package/src/operations/project-agents.ts

@@ -0,0 +1,115 @@
+import { formatErrorMessage, isRecord } from "@nseng-ai/foundation/primitives";
+import { err, type Result } from "@nseng-ai/foundation/result";
+import { parse } from "smol-toml";
+
+import type { AregTextFileState } from "../gateways.ts";
+import { rejectTextState } from "./file-state.ts";
+
+export const DEFAULT_AGENTS = ["codex", "claude-code"] as const;
+
+export function resolveProjectAgents(input: {
+	explicitAgents: readonly string[];
+	nsToml: AregTextFileState;
+	aregJson: AregTextFileState;
+}): Result<string[]> {
+	if (input.explicitAgents.length > 0) return { ok: true, value: [...input.explicitAgents] };
+	const nsAgents = parseNsAregAgentsFromState(input.nsToml);
+	if (!nsAgents.ok) return nsAgents;
+	if (nsAgents.value.length > 0) return nsAgents;
+	const legacyAgents = parseLegacyAregJsonAgentsFromState(input.aregJson);
+	if (!legacyAgents.ok) return legacyAgents;
+	if (legacyAgents.value.length > 0) return legacyAgents;
+	return { ok: true, value: [...DEFAULT_AGENTS] };
+}
+
+export function parseNsAregAgents(text: string, pathLabel = "ns.toml"): Result<string[]> {
+	let data: unknown;
+	try {
+		data = parse(text);
+	} catch (error) {
+		return err({
+			code: "ns_toml_invalid",
+			message: `Invalid TOML in ${pathLabel}: ${formatErrorMessage(error)}`,
+		});
+	}
+	if (!isRecord(data)) return { ok: true, value: [] };
+	const areg = data.areg;
+	if (areg === undefined) return { ok: true, value: [] };
+	if (!isRecord(areg))
+		return err({
+			code: "ns_toml_invalid",
+			message: `[areg] in ${pathLabel} must be a TOML table.`,
+		});
+	const agents = areg.agents;
+	if (agents === undefined) return { ok: true, value: [] };
+	if (!Array.isArray(agents))
+		return err({
+			code: "ns_toml_invalid",
+			message: `${pathLabel} [areg].agents must be a string array.`,
+		});
+	if (agents.length === 0) return { ok: true, value: [] };
+	return validateNonEmptyStringList(agents, {
+		code: "ns_toml_invalid",
+		message: `${pathLabel} [areg].agents must be a non-empty string list.`,
+	});
+}
+
+export function parseLegacyAregJsonAgents(text: string): Result<string[]> {
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		return err({
+			code: "areg_json_invalid",
+			message: `Invalid JSON in areg.json: ${formatErrorMessage(error)}`,
+		});
+	}
+	if (!isRecord(data))
+		return err({ code: "areg_json_invalid", message: "areg.json must contain a JSON object." });
+	const agents = data.agents;
+	if (!Array.isArray(agents) || agents.length === 0)
+		return err({
+			code: "areg_agents_invalid",
+			message: "areg.json field `agents` must be a non-empty string list.",
+		});
+	return validateNonEmptyStringList(agents, {
+		code: "areg_agents_invalid",
+		message: "areg.json field `agents` must be a non-empty string list.",
+	});
+}
+
+function validateNonEmptyStringList(
+	agents: readonly unknown[],
+	invalid: { code: string; message: string },
+): Result<string[]> {
+	const result: string[] = [];
+	for (const agent of agents) {
+		if (typeof agent !== "string" || agent.trim().length === 0) return err(invalid);
+		result.push(agent);
+	}
+	return { ok: true, value: result };
+}
+
+function parseNsAregAgentsFromState(state: AregTextFileState): Result<string[]> {
+	if (state.type === "missing") return { ok: true, value: [] };
+	if (state.type !== "file")
+		return rejectTextState({
+			pathLabel: "ns.toml",
+			state,
+			description: "ns.toml",
+			action: "manage it",
+		});
+	return parseNsAregAgents(state.text, "ns.toml");
+}
+
+function parseLegacyAregJsonAgentsFromState(state: AregTextFileState): Result<string[]> {
+	if (state.type === "missing") return { ok: true, value: [] };
+	if (state.type !== "file")
+		return rejectTextState({
+			pathLabel: "areg.json",
+			state,
+			description: "areg.json",
+			action: "manage it",
+		});
+	return parseLegacyAregJsonAgents(state.text);
+}

package/src/operations/project-inspection.ts

@@ -0,0 +1,165 @@
+import type { AregCliContext } from "../context.ts";
+import type {
+	AregCheckPairingDirectory,
+	AregCheckSkillInspection,
+	AregInstructionFilesInspection,
+	AregPathState,
+	AregProjectBaseInspection,
+	AregReplacementInspection,
+	AregSkillKindSkillInspection,
+	AregSkillNameInventory,
+	AregTextFileState,
+} from "../gateways.ts";
+import { uniqueSortedStrings } from "../sort.ts";
+import { parseInspectedLockfile } from "./lockfile.ts";
+
+export interface AregProjectInspectionFacts extends AregProjectBaseInspection {
+	piDir: AregPathState;
+	piSettings: AregTextFileState;
+	replacement: AregReplacementInspection;
+	skillInventory: AregSkillNameInventory;
+}
+
+export interface AregCheckProjectInspection {
+	projectDir: string;
+	projectPathState: AregPathState;
+	lockfile: AregTextFileState;
+	skillsDirectoryNames: readonly string[];
+	agentsSkillNames: readonly string[];
+	excludedSkillNames: readonly string[];
+	piDir: AregPathState;
+	piSettings: AregTextFileState;
+	replacement: AregReplacementInspection;
+	skills: readonly AregCheckSkillInspection[];
+	pairingDirectories: readonly AregCheckPairingDirectory[];
+}
+
+export interface AregSkillKindProjectInspection {
+	projectDir: string;
+	projectPathState: AregPathState;
+	piDir: AregPathState;
+	piSettings: AregTextFileState;
+	replacement: AregReplacementInspection;
+	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,
+): Promise<AregProjectInspectionFacts> {
+	const base = await ctx.project.inspectProjectBase({ cwd: ctx.cwd, projectPath, env: ctx.env });
+	const piArtifacts = await ctx.project.inspectPiArtifacts({
+		projectDir: base.projectDir,
+		env: ctx.env,
+	});
+	const skillInventory = await ctx.project.inspectSkillNameInventory({
+		projectDir: base.projectDir,
+		env: ctx.env,
+	});
+	return {
+		...base,
+		piDir: piArtifacts.piDir,
+		piSettings: piArtifacts.piSettings,
+		replacement: piArtifacts.replacement,
+		skillInventory,
+	};
+}
+
+export async function inspectCheckProject(
+	ctx: AregCliContext,
+	projectPath: string,
+): Promise<AregCheckProjectInspection> {
+	const facts = await collectProjectInspectionFacts(ctx, projectPath);
+	const excludedSkillNames = await ctx.project.readLocallyExcludedSkillNames({
+		projectDir: facts.projectDir,
+		env: ctx.env,
+	});
+	const lockfileResult = parseInspectedLockfile(facts);
+	const lockfileSkillNames = lockfileResult.ok
+		? lockfileResult.value.skills.map((skill) => skill.name)
+		: [];
+	const skillNames = uniqueSortedStrings([
+		...lockfileSkillNames,
+		...facts.skillInventory.skillsDirectoryNames,
+		...facts.skillInventory.agentsSkillNames,
+		...facts.skillInventory.claudeSkillNames,
+	]);
+	return {
+		projectDir: facts.projectDir,
+		projectPathState: facts.projectPathState,
+		lockfile: facts.lockfile,
+		skillsDirectoryNames: facts.skillInventory.skillsDirectoryNames,
+		agentsSkillNames: facts.skillInventory.agentsSkillNames,
+		excludedSkillNames,
+		piDir: facts.piDir,
+		piSettings: facts.piSettings,
+		replacement: facts.replacement,
+		skills: await collectCheckSkillInspections(ctx, facts.projectDir, skillNames),
+		pairingDirectories: await ctx.project.inspectPairingDirectories({
+			projectDir: facts.projectDir,
+			env: ctx.env,
+		}),
+	};
+}
+
+export async function inspectSkillKindProject(
+	ctx: AregCliContext,
+	projectPath: string,
+): Promise<AregSkillKindProjectInspection> {
+	const facts = await collectProjectInspectionFacts(ctx, projectPath);
+	return {
+		projectDir: facts.projectDir,
+		projectPathState: facts.projectPathState,
+		piDir: facts.piDir,
+		piSettings: facts.piSettings,
+		replacement: facts.replacement,
+		skills: await collectSkillKindInspections(
+			ctx,
+			facts.projectDir,
+			facts.skillInventory.skillKindNames,
+		),
+	};
+}
+
+export async function collectCheckSkillInspections(
+	ctx: AregCliContext,
+	projectDir: string,
+	skillNames: readonly string[],
+): Promise<readonly AregCheckSkillInspection[]> {
+	return await collectSkillInspections(skillNames, (skillName) =>
+		ctx.project.inspectCheckSkill({ projectDir, skillName, env: ctx.env }),
+	);
+}
+
+export async function collectSkillKindInspections(
+	ctx: AregCliContext,
+	projectDir: string,
+	skillNames: readonly string[],
+): Promise<readonly AregSkillKindSkillInspection[]> {
+	return await collectSkillInspections(skillNames, (skillName) =>
+		ctx.project.inspectSkillKindSkill({ projectDir, skillName, env: ctx.env }),
+	);
+}
+
+async function collectSkillInspections<T>(
+	skillNames: readonly string[],
+	inspect: (skillName: string) => Promise<T>,
+): Promise<readonly T[]> {
+	const skills: T[] = [];
+	for (const skillName of skillNames) skills.push(await inspect(skillName));
+	return skills;
+}