@nseng-ai/areg 0.1.1 → 0.1.2

package/src/operations/skill-kind.ts

@@ -11,6 +11,7 @@ import { renderTextTable, type TextTableColumn } from "@nseng-ai/foundation/text
 import { z } from "zod";
 
 import type { AregCliContext } from "../context.ts";
+import { aregManifestSkillSourceViewSchema } from "./manifest-sources.ts";
 import { isPathStateError } from "./file-state.ts";
 import { inspectSkillKindProject } from "./project-inspection.ts";
 import { inspectResolvedProjectGitRoot } from "./project-resolution.ts";
@@ -73,6 +74,8 @@ const skillKindReplacementSchema = z.object({
 	advice: z.string().optional(),
 });
 
+const skillKindManifestSourceSchema = aregManifestSkillSourceViewSchema;
+
 const skillKindRecordSchema = z.object({
 	skill: z.string(),
 	kind: z.enum(INFERRED_SKILL_INVOCATION_KINDS),
@@ -81,6 +84,7 @@ const skillKindRecordSchema = z.object({
 	piExtension: z.enum(PI_EXTENSION_STATUSES),
 	artifacts: skillKindArtifactFactsSchema,
 	replacement: skillKindReplacementSchema,
+	manifestSources: z.array(skillKindManifestSourceSchema),
 	notes: z.array(z.string()),
 });
 
@@ -127,7 +131,7 @@ export const skillKindApplyRequestSchema = z.object({
 		.default(".")
 		.describe("Project directory or subdirectory to mutate (default: current directory)."),
 	dryRun: z.boolean().default(false).describe("Show planned edits without writing files."),
-	yes: z.boolean().default(false).describe("Approve deletion prompts for managed artifacts."),
+	yes: z.boolean().default(false).describe("Approve deletion prompts for harness overlays."),
 	kind: z.enum(SKILL_INVOCATION_KINDS).describe("Desired skill invocation kind."),
 	skills: z.array(z.string()).min(1).describe("Installed skill names or path-like skill specs."),
 });
@@ -193,7 +197,7 @@ export function buildSkillGroup(): ClinkrGroup<AregCliContext> {
 	skillGroup.command({
 		name: "apply",
 		description:
-			"Apply the managed artifacts for a skill invocation kind. This reconciles managed artifacts to the requested kind. The unlisted kind additionally deletes the .agents/skills and .claude/skills mirror symlinks so the skill disappears from every harness typeahead. It is not a historical undo system; use git to roll back exact previous file contents.",
+			"Apply the harness overlays for a skill invocation kind. This reconciles harness overlays to the requested kind. The unlisted kind additionally deletes the .agents/skills and .claude/skills mirror symlinks so the skill disappears from every harness typeahead. It is not a historical undo system; use git to roll back exact previous file contents.",
 		schema: skillKindApplyRequestSchema,
 		positionals: { kind: { position: 0 }, skills: { position: 1 } },
 		options: { yes: { short: "-y" } },
@@ -314,7 +318,6 @@ export async function runSkillKindApply(
 	const applyResult = await applyProjectMutationPlan({
 		ctx,
 		projectDir,
-		policy: "skill-kind",
 		writes: plans.flatMap(plannedWrites),
 		deletes: plans.flatMap(plannedDeletes),
 		deleteSymlinks: plans.flatMap(plannedDeleteSymlinks),
@@ -363,7 +366,8 @@ export function renderSkillKindList(
 	caps: RenderCapabilities = { canEmitAnsi: false },
 ): string {
 	if (result.skills.length === 0) return "No managed skills found.";
-	const includeNotes = result.skills.some((record) => record.notes.length > 0);
+	const hasSources = result.skills.some((record) => record.manifestSources.length > 0);
+	const shouldIncludeNotes = result.skills.some((record) => record.notes.length > 0);
 	const columns: TextTableColumn[] = [
 		{ header: "SKILL", style: "bold-cyan" },
 		{ header: "KIND" },
@@ -371,7 +375,8 @@ export function renderSkillKindList(
 		{ header: "NATIVE" },
 		{ header: "PI" },
 	];
-	if (includeNotes) columns.push({ header: "NOTES", style: "dim" });
+	if (hasSources) columns.push({ header: "SOURCES" });
+	if (shouldIncludeNotes) columns.push({ header: "NOTES", style: "dim" });
 	return renderTextTable({
 		columns,
 		rows: result.skills.map((record) => {
@@ -382,7 +387,8 @@ export function renderSkillKindList(
 				record.nativeDirect,
 				record.piExtension,
 			];
-			if (includeNotes) base.push(record.notes.join("; "));
+			if (hasSources) base.push(skillKindSourcesLabel(record));
+			if (shouldIncludeNotes) base.push(record.notes.join("; "));
 			return base;
 		}),
 		canEmitAnsi: caps.canEmitAnsi,
@@ -408,6 +414,14 @@ export function renderSkillKindShow(result: SkillKindShowResult): string {
 		`- .claude/skills mirror: ${presence(record.artifacts.claudeMirror)}`,
 		`- Pi replacement: ${record.replacement.label}`,
 	];
+	if (record.manifestSources.length > 0) {
+		lines.push("Manifest sources:");
+		for (const source of record.manifestSources) {
+			lines.push(
+				`- ${source.harness} ${source.manifestKey}: ${source.packageName}@${source.version} -> ${source.targetSkillRelativePath}`,
+			);
+		}
+	}
 	if (record.notes.length > 0) {
 		lines.push("Notes:");
 		for (const note of record.notes) lines.push(`- ${note}`);
@@ -472,26 +486,33 @@ function toSkillKindRecordResult(record: SkillKindRecord): SkillKindRecordResult
 			evidence: record.replacement.evidence,
 			advice: record.replacement.advice,
 		},
+		manifestSources: record.manifestSources.map((source) => ({ ...source })),
 		notes: [...record.notes],
 	};
 }
 
+function skillKindSourcesLabel(record: SkillKindRecordResult): string {
+	if (record.manifestSources.length === 0) return "";
+	const labels = new Set(record.manifestSources.map((source) => source.harness));
+	return ["manifest", ...labels].join(":");
+}
+
 function renderApplyOperation(
 	operation: SkillKindApplyResult["skills"][number]["operations"][number],
-	dryRun: boolean,
+	isDryRun: boolean,
 ): string | undefined {
 	if (!("isApplied" in operation)) return undefined;
 	switch (operation.type) {
 		case "write":
-			return `${dryRun ? "Would write" : "Wrote"} ${operation.path}`;
+			return `${isDryRun ? "Would write" : "Wrote"} ${operation.path}`;
 		case "skip":
-			return `${dryRun ? "Would skip" : "Skipped"} ${operation.path}: ${operation.reason ?? "already current"}`;
+			return `${isDryRun ? "Would skip" : "Skipped"} ${operation.path}: ${operation.reason ?? "already current"}`;
 		case "delete":
-			return `${dryRun ? "Would delete" : "Deleted"} ${operation.path}`;
+			return `${isDryRun ? "Would delete" : "Deleted"} ${operation.path}`;
 		case "delete-symlink":
-			return `${dryRun ? "Would delete symlink" : "Deleted symlink"} ${operation.path}`;
+			return `${isDryRun ? "Would delete symlink" : "Deleted symlink"} ${operation.path}`;
 		case "remove-empty-dir":
-			if (dryRun) return `Would remove ${operation.path} if empty`;
+			if (isDryRun) return `Would remove ${operation.path} if empty`;
 			return operation.isApplied ? `Removed ${operation.path}` : undefined;
 	}
 }
@@ -519,6 +540,7 @@ function emptyShowResult(projectDir: string, skillName: string): SkillKindShowRe
 				claudeMirror: false,
 			},
 			replacement: { verified: false, label: "replacement-missing" },
+			manifestSources: [],
 			notes: [],
 		},
 	};

package/src/sort.ts

@@ -1,7 +1,7 @@
-export function sortStrings(values: readonly string[]): string[] {
-	return [...values].sort();
+export function sortStringsLocaleAware(values: Iterable<string>): string[] {
+	return [...values].sort((left, right) => left.localeCompare(right));
 }
 
 export function uniqueSortedStrings(values: readonly string[]): string[] {
-	return sortStrings([...new Set(values)]);
+	return sortStringsLocaleAware(new Set(values));
 }

package/src/gateways/command-constants.ts

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

package/src/gateways/github-gateway.ts

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

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

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

@@ -1,53 +0,0 @@
-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/prompt-gateway.ts

@@ -1,21 +0,0 @@
-import readline from "node:readline/promises";
-
-import type { AregPromptGateway } from "../gateways.ts";
-
-export class RealAregPromptGateway implements AregPromptGateway {
-	async confirm(request: { message: string; defaultValue: boolean }): Promise<boolean> {
-		const suffix = request.defaultValue ? " [Y/n] " : " [y/N] ";
-		const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-		try {
-			while (true) {
-				const answer = (await rl.question(`${request.message}${suffix}`)).trim().toLowerCase();
-				if (answer.length === 0) return request.defaultValue;
-				if (answer === "y" || answer === "yes") return true;
-				if (answer === "n" || answer === "no") return false;
-				process.stdout.write("Please answer yes or no.\n");
-			}
-		} finally {
-			rl.close();
-		}
-	}
-}