@nseng-ai/areg 0.1.1 → 0.1.2

package/src/operations/project-agents.ts

@@ -1,115 +0,0 @@
-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/skill-mirror-conventions.ts

@@ -1,126 +0,0 @@
-import type { AregErrorInfo, AregPathState } from "../gateways.ts";
-
-export function expectedAgentsSkillSymlinkTarget(skillName: string): string {
-	return `../../skills/${skillName}`;
-}
-
-export function expectedClaudeSkillSymlinkTarget(skillName: string): string {
-	return `../../.agents/skills/${skillName}`;
-}
-
-export function isAgentsSkillMirror(pathState: AregPathState, skillName: string): boolean {
-	return (
-		pathState.type === "symlink" && pathState.target === expectedAgentsSkillSymlinkTarget(skillName)
-	);
-}
-
-export function isClaudeSkillMirror(pathState: AregPathState, skillName: string): boolean {
-	return (
-		pathState.type === "symlink" && pathState.target === expectedClaudeSkillSymlinkTarget(skillName)
-	);
-}
-
-export function agentsSkillMirrorRelativePath(skillName: string): string {
-	return `.agents/skills/${skillName}`;
-}
-
-export function claudeSkillMirrorRelativePath(skillName: string): string {
-	return `.claude/skills/${skillName}`;
-}
-
-export type SkillMirrorKind = "agents" | "claude";
-
-export interface SkillMirrorRelativePathInfo {
-	mirrorKind: SkillMirrorKind;
-	skillName: string;
-	expectedTarget: string;
-}
-
-/**
- * Returns parsed mirror information for an exact areg-managed skill mirror
- * location, or undefined when the path is not a valid mirror path.
- */
-export function parseSkillMirrorRelativePath(
-	relativePath: string,
-): SkillMirrorRelativePathInfo | undefined {
-	const parts = relativePath.split("/");
-	if (parts.length !== 3 || parts[1] !== "skills") return undefined;
-	const skillName = parts[2];
-	if (skillName === undefined || !isPlainSkillNameSegment(skillName)) return undefined;
-	if (parts[0] === ".agents")
-		return {
-			mirrorKind: "agents",
-			skillName,
-			expectedTarget: expectedAgentsSkillSymlinkTarget(skillName),
-		};
-	if (parts[0] === ".claude")
-		return {
-			mirrorKind: "claude",
-			skillName,
-			expectedTarget: expectedClaudeSkillSymlinkTarget(skillName),
-		};
-	return undefined;
-}
-
-/**
- * Returns true when the relative path is exactly an areg-managed skill mirror
- * location: `.agents/skills/<name>` or `.claude/skills/<name>` with a plain
- * single-segment skill name.
- */
-export function isSkillMirrorRelativePath(relativePath: string): boolean {
-	return expectedMirrorTarget(relativePath) !== undefined;
-}
-
-/**
- * Returns the convention symlink target for a skill mirror relative path, or
- * undefined when the path is not a valid skill mirror location.
- */
-export function expectedMirrorTarget(relativePath: string): string | undefined {
-	return parseSkillMirrorRelativePath(relativePath)?.expectedTarget;
-}
-
-/**
- * Classifies a skill-mirror symlink deletion target against the delete contract,
- * returning the matching error or undefined when the target is a deletable
- * convention symlink. An undefined `state` is treated as missing so fixture-backed
- * callers share the same cascade as filesystem inspection.
- */
-export function classifySkillMirrorSymlinkState(
-	relativePath: string,
-	state: AregPathState | undefined,
-	description: string,
-	target: string,
-): AregErrorInfo | undefined {
-	const expectedTarget = expectedMirrorTarget(relativePath);
-	if (expectedTarget === undefined)
-		return {
-			code: "skill-kind-delete-symlink-refused",
-			message: `Refusing to delete ${description}: ${relativePath} is not a managed skill mirror path.`,
-		};
-	if (state === undefined || state.type === "missing")
-		return {
-			code: "skill-kind-delete-symlink-missing",
-			message: `${description} at ${target} does not exist.`,
-		};
-	if (state.type !== "symlink")
-		return {
-			code: "skill-kind-delete-symlink-not-symlink",
-			message: `${description} at ${target} is not a symlink; refusing to delete it.`,
-		};
-	if (state.target !== expectedTarget)
-		return {
-			code: "skill-kind-delete-symlink-wrong-target",
-			message: `${description} at ${target} points to ${state.target}, expected ${expectedTarget}; refusing to delete it.`,
-		};
-	return undefined;
-}
-
-function isPlainSkillNameSegment(segment: string): boolean {
-	return (
-		segment.length > 0 &&
-		segment !== "." &&
-		segment !== ".." &&
-		!segment.includes("/") &&
-		!segment.includes("\\")
-	);
-}

package/src/operations/skillx.ts

@@ -1,305 +0,0 @@
-import { failure, negative, ok, type ClinkrExit, ClinkrGroup } from "@nseng-ai/clinkr";
-import { optionalEntry } from "@nseng-ai/foundation/primitives";
-import { z } from "zod";
-
-import type { AregCliContext } from "../context.ts";
-import type { AregSkillxInstalledSkill } from "../gateways.ts";
-import { sortStrings } from "../sort.ts";
-
-const SKILLX_FORMAT_VALUES = ["url", "skill-flag", "plain", "repo-only"] as const;
-const REPO_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
-
-export const skillxParseRequestSchema = z.object({
-	inputText: z.string().describe("GitHub URL, owner/repo, or owner/repo plus skill selector."),
-});
-
-export const skillxListRequestSchema = z.object({
-	repo: z.string().describe("GitHub repository in owner/repo form."),
-});
-
-export const skillxFetchRequestSchema = z.object({
-	repo: z.string().describe("GitHub repository in owner/repo form."),
-	skill: z.string().optional().describe("Specific skill name to select after installation."),
-});
-
-export const skillxCleanupRequestSchema = z.object({
-	dir: z.string().describe("Transient skillx workspace directory to remove."),
-});
-
-const skillxFormatSchema = z.enum(SKILLX_FORMAT_VALUES);
-
-const parseSuccessSchema = z.object({
-	success: z.literal(true),
-	repo: z.string(),
-	skill: z.string().nullable(),
-	format: skillxFormatSchema,
-});
-
-const parseFailureSchema = z.object({
-	success: z.literal(false),
-	error: z.string(),
-});
-
-export const skillxParseResultSchema = z.union([parseSuccessSchema, parseFailureSchema]);
-
-const listSuccessSchema = z.object({
-	success: z.literal(true),
-	repo: z.string(),
-	skills: z.array(z.string()),
-});
-
-const listFailureSchema = z.object({
-	success: z.literal(false),
-	error: z.string(),
-	hint: z.string().optional(),
-});
-
-export const skillxListResultSchema = z.union([listSuccessSchema, listFailureSchema]);
-
-const fetchSelectedSuccessSchema = z.object({
-	success: z.literal(true),
-	repo: z.string(),
-	skill: z.string(),
-	tmpDir: z.string(),
-	skillDir: z.string(),
-	skillMd: z.string(),
-	files: z.array(z.string()),
-	needsSelection: z.literal(false).optional(),
-});
-
-const fetchSelectionSuccessSchema = z.object({
-	success: z.literal(true),
-	repo: z.string(),
-	skill: z.null(),
-	tmpDir: z.string(),
-	skillDir: z.null(),
-	skillMd: z.null(),
-	files: z.null(),
-	needsSelection: z.literal(true),
-	availableSkills: z.array(z.string()),
-});
-
-const fetchFailureSchema = z.object({
-	success: z.literal(false),
-	error: z.string(),
-	tmpDir: z.null(),
-});
-
-export const skillxFetchResultSchema = z.union([
-	fetchSelectedSuccessSchema,
-	fetchSelectionSuccessSchema,
-	fetchFailureSchema,
-]);
-
-const cleanupSuccessSchema = z.object({
-	success: z.literal(true),
-	removed: z.string(),
-});
-
-const cleanupFailureSchema = z.object({
-	success: z.literal(false),
-	error: z.string(),
-});
-
-export const skillxCleanupResultSchema = z.union([cleanupSuccessSchema, cleanupFailureSchema]);
-
-export type SkillxParseRequest = z.infer<typeof skillxParseRequestSchema>;
-export type SkillxListRequest = z.infer<typeof skillxListRequestSchema>;
-export type SkillxFetchRequest = z.infer<typeof skillxFetchRequestSchema>;
-export type SkillxCleanupRequest = z.infer<typeof skillxCleanupRequestSchema>;
-export type SkillxParseResult = z.infer<typeof skillxParseResultSchema>;
-export type SkillxListResult = z.infer<typeof skillxListResultSchema>;
-export type SkillxFetchResult = z.infer<typeof skillxFetchResultSchema>;
-export type SkillxCleanupResult = z.infer<typeof skillxCleanupResultSchema>;
-
-export function buildSkillxGroup(): ClinkrGroup<AregCliContext> {
-	const group = new ClinkrGroup<AregCliContext>({
-		name: "skillx",
-		description: "Skillx helper operations.",
-	});
-	group.command({
-		name: "parse",
-		description: "Parse a skill source selector.",
-		schema: skillxParseRequestSchema,
-		positionals: { inputText: { position: 0 } },
-		resultSchema: skillxParseResultSchema,
-		handler: runSkillxParse,
-	});
-	group.command({
-		name: "list",
-		description: "List skills in a GitHub repository skills/ directory.",
-		schema: skillxListRequestSchema,
-		resultSchema: skillxListResultSchema,
-		handler: runSkillxList,
-	});
-	group.command({
-		name: "fetch",
-		description: "Fetch skills into a transient workspace for agent reading.",
-		schema: skillxFetchRequestSchema,
-		resultSchema: skillxFetchResultSchema,
-		handler: runSkillxFetch,
-	});
-	group.command({
-		name: "cleanup",
-		description: "Remove a transient skillx workspace.",
-		schema: skillxCleanupRequestSchema,
-		resultSchema: skillxCleanupResultSchema,
-		handler: runSkillxCleanup,
-	});
-	return group;
-}
-
-export function parseSkillInput(raw: string): SkillxParseResult {
-	const input = raw.trim();
-	if (input.length === 0) return parseError("Empty input");
-	const urlResult = parseGithubUrl(input);
-	if (urlResult !== undefined) return urlResult;
-	const parts = input.split(/\s+/u);
-	const [repo, second, third, ...rest] = parts;
-	if (repo === undefined || !isRepo(repo))
-		return parseError(`Could not extract owner/repo from input: ${JSON.stringify(input)}`);
-	if ((second === "--skill" || second === "-s") && third !== undefined && rest.length === 0) {
-		return { success: true, repo, skill: third, format: "skill-flag" };
-	}
-	if (second === undefined) return { success: true, repo, skill: null, format: "repo-only" };
-	if (third === undefined && isSkillName(second))
-		return { success: true, repo, skill: second, format: "plain" };
-	return parseError(`Could not extract owner/repo from input: ${JSON.stringify(input)}`);
-}
-
-export async function runSkillxParse(
-	_ctx: AregCliContext,
-	request: SkillxParseRequest,
-): Promise<ClinkrExit<SkillxParseResult>> {
-	const result = parseSkillInput(request.inputText);
-	if (result.success) return ok(result);
-	return negative(result.error, { data: result });
-}
-
-export async function runSkillxList(
-	ctx: AregCliContext,
-	request: SkillxListRequest,
-): Promise<ClinkrExit<SkillxListResult>> {
-	const tool = await ctx.host.checkTool({ tool: "gh", cwd: ctx.cwd, env: ctx.env });
-	if (tool.type === "missing") return failure("missing-tool", tool.message);
-	const result = await ctx.github.listSkillDirectoryNames({ repo: request.repo, env: ctx.env });
-	if (result.type === "ok") {
-		return ok({ success: true, repo: request.repo, skills: sortStrings(result.skillNames) });
-	}
-	if (result.type === "missing") {
-		const error = `No skills directory found in ${request.repo}`;
-		return negative(error, {
-			data: {
-				success: false,
-				error,
-				hint: "Check that the repo exists and has a skills/ directory",
-			},
-		});
-	}
-	if (result.type === "auth-error") {
-		return failure("github-auth-failed", `Authentication error accessing ${request.repo}`);
-	}
-	return failure("github-gateway-failed", result.error.message);
-}
-
-export async function runSkillxFetch(
-	ctx: AregCliContext,
-	request: SkillxFetchRequest,
-): Promise<ClinkrExit<SkillxFetchResult>> {
-	const tool = await ctx.host.checkTool({ tool: "npx", cwd: ctx.cwd, env: ctx.env });
-	if (tool.type === "missing") return failure("missing-tool", tool.message);
-	const install = await ctx.skillxWorkspace.installIntoWorkspace({
-		sourceRepo: request.repo,
-		...optionalEntry("skillName", request.skill),
-		cwd: ctx.cwd,
-		env: ctx.env,
-	});
-	if (install.type === "error") return failure("skill-install-failed", install.error.message);
-	const workspaceRoot = install.workspace.workspaceRoot;
-	const installedSkills = sortedInstalledSkills(install.workspace.installedSkills);
-	if (installedSkills.length === 0) return fetchNegative("No skills were installed");
-	if (request.skill === undefined && installedSkills.length > 1) {
-		return ok({
-			success: true,
-			repo: request.repo,
-			skill: null,
-			tmpDir: workspaceRoot,
-			skillDir: null,
-			skillMd: null,
-			files: null,
-			needsSelection: true,
-			availableSkills: installedSkills.map((skill) => skill.name),
-		});
-	}
-	const selected =
-		request.skill === undefined
-			? installedSkills[0]
-			: installedSkills.find((skill) => skill.name === request.skill);
-	if (selected === undefined) {
-		await ctx.skillxWorkspace.cleanupWorkspace({ workspaceRoot });
-		const base = `Skill '${request.skill}' was not found in installed skills`;
-		return fetchNegative(base);
-	}
-	return ok({
-		success: true,
-		repo: request.repo,
-		skill: selected.name,
-		tmpDir: workspaceRoot,
-		skillDir: selected.directory,
-		skillMd: selected.skillFile,
-		files: sortStrings(selected.relativeFiles),
-		needsSelection: false,
-	});
-}
-
-export async function runSkillxCleanup(
-	ctx: AregCliContext,
-	request: SkillxCleanupRequest,
-): Promise<ClinkrExit<SkillxCleanupResult>> {
-	const cleanup = await ctx.skillxWorkspace.cleanupWorkspace({ workspaceRoot: request.dir });
-	if (cleanup.ok) return ok({ success: true, removed: request.dir });
-	return failure("cleanup-failed", cleanup.error.message);
-}
-
-function parseGithubUrl(input: string): z.infer<typeof parseSuccessSchema> | undefined {
-	let url: URL;
-	try {
-		url = new URL(input);
-	} catch {
-		return undefined;
-	}
-	if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
-	if (url.hostname !== "github.com" && url.hostname !== "www.github.com") return undefined;
-	const segments = url.pathname.split("/").filter((part) => part.length > 0);
-	const owner = segments[0];
-	const repoName = segments[1];
-	if (owner === undefined || repoName === undefined || !isRepo(`${owner}/${repoName}`))
-		return undefined;
-	const skillsIndex = segments.indexOf("skills");
-	const skill = skillsIndex === -1 ? null : (segments[skillsIndex + 1] ?? null);
-	return { success: true, repo: `${owner}/${repoName}`, skill, format: "url" };
-}
-
-function isRepo(value: string): boolean {
-	return REPO_PATTERN.test(value);
-}
-
-function isSkillName(value: string): boolean {
-	return value.length > 0 && !value.includes("/") && !value.includes("@") && !value.startsWith("-");
-}
-
-function parseError(error: string): SkillxParseResult {
-	return { success: false, error };
-}
-
-function fetchNegative(error: string): ClinkrExit<SkillxFetchResult> {
-	return negative(error, { data: { success: false, error, tmpDir: null } });
-}
-
-function sortedInstalledSkills(
-	skills: readonly AregSkillxInstalledSkill[],
-): AregSkillxInstalledSkill[] {
-	return skills
-		.map((skill) => ({ ...skill, relativeFiles: sortStrings(skill.relativeFiles) }))
-		.sort((left, right) => left.name.localeCompare(right.name));
-}

package/src/operations/toml-section.ts

@@ -1,53 +0,0 @@
-export function renderAregSection(agents: readonly string[]): string {
-	return `[areg]\nagents = ${JSON.stringify([...agents])}\n`;
-}
-
-export function replaceOrAppendAregSection(content: string, agents: readonly string[]): string {
-	const lines = content.split(/(?<=\n)/u);
-	if (lines.length === 1 && lines[0] === "") lines.pop();
-	const start = aregSectionStart(lines);
-	if (start === undefined) return appendTomlSection(content, renderAregSection(agents));
-	const end = tomlSectionEnd(lines, start);
-	let replacement = renderAregSection(agents);
-	if (end < lines.length) replacement += "\n";
-	lines.splice(
-		start,
-		end - start,
-		...(replacement.match(/.*(?:\n|$)/gu)?.filter((line) => line.length > 0) ?? []),
-	);
-	return lines.join("");
-}
-
-function appendTomlSection(content: string, section: string): string {
-	if (content.length === 0) return section;
-	if (content.endsWith("\n\n")) return `${content}${section}`;
-	if (content.endsWith("\n")) return `${content}\n${section}`;
-	return `${content}\n\n${section}`;
-}
-
-function aregSectionStart(lines: readonly string[]): number | undefined {
-	for (let index = 0; index < lines.length; index += 1) {
-		if (tomlTableName(lines[index] ?? "") === "areg") return index;
-	}
-	return undefined;
-}
-
-function tomlSectionEnd(lines: readonly string[], start: number): number {
-	for (let index = start + 1; index < lines.length; index += 1) {
-		if (tomlTableName(lines[index] ?? "") !== null) return index;
-	}
-	return lines.length;
-}
-
-function tomlTableName(line: string): string | null {
-	const stripped = line.trim();
-	if (stripped.startsWith("[[")) {
-		const closingIndex = stripped.indexOf("]]", 2);
-		if (closingIndex < 0) return null;
-		return stripped.slice(2, closingIndex).trim();
-	}
-	if (!stripped.startsWith("[")) return null;
-	const closingIndex = stripped.indexOf("]");
-	if (closingIndex < 0) return null;
-	return stripped.slice(1, closingIndex).trim();
-}