@nseng-ai/harness-artifacts 0.1.2

package/src/skill-frontmatter.ts

@@ -0,0 +1,151 @@
+import {
+	splitMarkdownFrontmatter,
+	stripLineEnding,
+} from "@nseng-ai/foundation/markdown-frontmatter";
+import { err, type Result } from "@nseng-ai/foundation/result";
+
+const FRONTMATTER_KEY_RE = /^(?<key>[A-Za-z0-9_-]+):(?<value>.*)$/u;
+
+export interface SkillFrontmatterData {
+	fields: Readonly<Record<string, string>>;
+	keys: ReadonlySet<string>;
+}
+
+export type SkillFrontmatterParseResult = Result<SkillFrontmatterData>;
+
+export type SkillFrontmatterTopLevelLineParseResult =
+	| { type: "key"; key: string; value: string }
+	| { type: "not_top_level" }
+	| { type: "invalid"; line: string };
+
+export function parseSkillFrontmatterBlock(text: string): SkillFrontmatterParseResult {
+	const split = splitMarkdownFrontmatter(text);
+	if (split.type === "not_found")
+		return err({
+			code: "frontmatter_missing_opening_delimiter",
+			message: "missing opening frontmatter delimiter '---'",
+		});
+	if (split.type === "missing_closing_fence")
+		return err({
+			code: "frontmatter_missing_closing_delimiter",
+			message: "missing closing frontmatter delimiter '---'",
+		});
+
+	const lines = split.block.frontmatterLinesWithEndings.map(stripLineEnding);
+	const fields: Record<string, string> = {};
+	const keys = new Set<string>();
+	let currentKey: string | undefined;
+	let currentValues: string[] = [];
+	function flushCurrent(): void {
+		if (currentKey === undefined) return;
+		let rawValue = currentValues
+			.filter((value) => value.length > 0)
+			.join(" ")
+			.trim();
+		if (
+			rawValue.length >= 2 &&
+			rawValue[0] === rawValue.at(-1) &&
+			(rawValue[0] === '"' || rawValue[0] === "'")
+		)
+			rawValue = rawValue.slice(1, -1);
+		fields[currentKey] = rawValue;
+	}
+	for (const line of lines) {
+		const stripped = line.trim();
+		if (stripped.length === 0) continue;
+		if (stripped.startsWith("#")) continue;
+		const parsedLine = parseSkillFrontmatterTopLevelLine(line);
+		if (parsedLine.type === "key") {
+			flushCurrent();
+			if (keys.has(parsedLine.key))
+				return err({
+					code: "frontmatter_duplicate_key",
+					message: `duplicate frontmatter key: ${JSON.stringify(parsedLine.key)}`,
+				});
+			currentKey = parsedLine.key;
+			keys.add(currentKey);
+			currentValues = [];
+			const inlineValue = parsedLine.value.trim();
+			if (inlineValue.length > 0) currentValues.push(inlineValue);
+			continue;
+		}
+		if (parsedLine.type === "invalid")
+			return err({
+				code: "frontmatter_invalid_line",
+				message: `invalid frontmatter line: ${JSON.stringify(parsedLine.line)}`,
+			});
+		if (currentKey === undefined)
+			return err({
+				code: "frontmatter_invalid_line",
+				message: `invalid frontmatter line: ${JSON.stringify(line)}`,
+			});
+		currentValues.push(line.trim());
+	}
+	flushCurrent();
+	return { ok: true, value: { fields, keys } };
+}
+
+export function parseSkillFrontmatterTopLevelLine(
+	line: string,
+): SkillFrontmatterTopLevelLineParseResult {
+	const content = stripLineEnding(line);
+	if (content.trim().length === 0) return { type: "not_top_level" };
+	if (content.trim().startsWith("#")) return { type: "not_top_level" };
+	if (content.startsWith(" ") || content.startsWith("\t")) return { type: "not_top_level" };
+	const match = FRONTMATTER_KEY_RE.exec(content);
+	if (match?.groups === undefined) return { type: "invalid", line: content };
+	return { type: "key", key: match.groups.key ?? "", value: match.groups.value ?? "" };
+}
+
+export function isSkillFrontmatterTopLevelKey(line: string, key: string): boolean {
+	const parsed = parseSkillFrontmatterTopLevelLine(line);
+	return parsed.type === "key" && parsed.key === key;
+}
+
+export function transformSkillFrontmatter(
+	text: string,
+	pathLabel: string,
+	desired: Readonly<Record<string, string | undefined>>,
+): Result<string> {
+	const parsed = parseSkillFrontmatterBlock(text);
+	if (!parsed.ok)
+		return {
+			ok: false,
+			error: { ...parsed.error, message: `${pathLabel} ${parsed.error.message}` },
+		};
+
+	const split = splitMarkdownFrontmatter(text);
+	if (split.type !== "found")
+		return err({
+			code: "frontmatter_invalid_bounds",
+			message: `${pathLabel} invalid frontmatter bounds`,
+		});
+
+	const lines = [...split.block.linesWithEndings];
+	const nameIndex = lines.findIndex(
+		(line, index) =>
+			index > 0 && index < split.block.closingIndex && isSkillFrontmatterTopLevelKey(line, "name"),
+	);
+	if (nameIndex === -1)
+		return err({
+			code: "frontmatter_missing_name",
+			message: `${pathLabel} missing name field in frontmatter`,
+		});
+
+	const managedKeys = Object.keys(desired);
+	const kept = lines.filter(
+		(line, index) =>
+			index <= 0 ||
+			index >= split.block.closingIndex ||
+			!managedKeys.some((key) => isSkillFrontmatterTopLevelKey(line, key)),
+	);
+	const keptNameIndex = kept.findIndex(
+		(line, index) => index > 0 && isSkillFrontmatterTopLevelKey(line, "name"),
+	);
+	const additions = managedKeys.flatMap((key) => {
+		const value = desired[key];
+		return value === undefined ? [] : [`${key}: ${value}${split.block.lineEnding}`];
+	});
+	kept.splice(keptNameIndex + 1, 0, ...additions);
+	return { ok: true, value: kept.join("") };
+}

package/src/skill-mirror-conventions.ts

@@ -0,0 +1,128 @@
+import type { ErrorInfo } from "@nseng-ai/foundation/result";
+
+import type { PathState } from "./fs-state.ts";
+
+export function expectedAgentsSkillSymlinkTarget(skillName: string): string {
+	return `../../skills/${skillName}`;
+}
+
+export function expectedClaudeSkillSymlinkTarget(skillName: string): string {
+	return `../../.agents/skills/${skillName}`;
+}
+
+export function isAgentsSkillMirror(pathState: PathState, skillName: string): boolean {
+	return (
+		pathState.type === "symlink" && pathState.target === expectedAgentsSkillSymlinkTarget(skillName)
+	);
+}
+
+export function isClaudeSkillMirror(pathState: PathState, 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: PathState | undefined,
+	description: string,
+	target: string,
+): ErrorInfo | 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/skills-lockfile.ts

@@ -0,0 +1,107 @@
+import { formatErrorMessage, formatZodIssue, optionalEntry } from "@nseng-ai/foundation/primitives";
+import { resultErr, type Result } from "@nseng-ai/foundation/result";
+import { z } from "zod";
+
+import type { TextFileState } from "./fs-state.ts";
+import { sortStrings } from "./sort.ts";
+
+export const SOURCE_TYPES = ["local", "github", "git", "gitlab"] as const;
+
+export type SourceType = (typeof SOURCE_TYPES)[number];
+
+export interface LockfileSkillData {
+	source: string;
+	sourceType: SourceType;
+	computedHash: string;
+	skillPath?: string;
+}
+
+export interface LockfileSkill extends LockfileSkillData {
+	name: string;
+}
+
+export interface SkillsLockfileData {
+	version: 1;
+	skills: Record<string, LockfileSkillData>;
+}
+
+export interface SkillsLockfile {
+	version: 1;
+	skills: readonly LockfileSkill[];
+}
+
+const lockfileSkillSchema: z.ZodType<LockfileSkillData> = z
+	.object({
+		source: z.string(),
+		sourceType: z.enum(SOURCE_TYPES),
+		computedHash: z.string(),
+		skillPath: z.string().optional(),
+	})
+	.transform(
+		(skill): LockfileSkillData => ({
+			source: skill.source,
+			sourceType: skill.sourceType,
+			computedHash: skill.computedHash,
+			...optionalEntry("skillPath", skill.skillPath),
+		}),
+	);
+
+const skillsLockfileSchema: z.ZodType<SkillsLockfileData> = z.object({
+	version: z.literal(1),
+	skills: z.record(z.string(), lockfileSkillSchema),
+});
+
+export function parseLockfileData(data: unknown): Result<SkillsLockfile> {
+	const result = skillsLockfileSchema.safeParse(data);
+	if (!result.success)
+		return invalidLockfile(
+			formatZodIssue(result.error.issues[0], {
+				rootPath: "$",
+				pathPrefix: "$.",
+				fallback: "invalid lockfile",
+			}),
+		);
+	const lockfileData = result.data as SkillsLockfileData;
+	const skills: LockfileSkill[] = [];
+	for (const name of sortStrings(Object.keys(lockfileData.skills))) {
+		const skill = lockfileData.skills[name];
+		if (skill === undefined) continue;
+		skills.push({
+			name,
+			source: skill.source,
+			sourceType: skill.sourceType,
+			computedHash: skill.computedHash,
+			...optionalEntry("skillPath", skill.skillPath),
+		});
+	}
+	return { ok: true, value: { version: 1, skills } };
+}
+
+export function parseLockfileText(text: string): Result<SkillsLockfile> {
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		return resultErr({
+			code: "lockfile_invalid_json",
+			message: `Invalid JSON in skills-lock.json: ${formatErrorMessage(error)}`,
+		});
+	}
+	return parseLockfileData(data);
+}
+
+export function parseInspectedLockfile(input: {
+	projectDir: string;
+	lockfile: TextFileState;
+}): Result<SkillsLockfile> {
+	if (input.lockfile.type !== "file")
+		return resultErr({
+			code: "lockfile_missing",
+			message: `skills-lock.json not found in ${input.projectDir}. Is this an areg project?`,
+		});
+	return parseLockfileText(input.lockfile.text);
+}
+
+function invalidLockfile(reason: string): Result<SkillsLockfile> {
+	return resultErr({ code: "lockfile_invalid", message: `Invalid skills-lock.json: ${reason}.` });
+}

package/src/sort.ts

@@ -0,0 +1,3 @@
+export function sortStrings(values: readonly string[]): string[] {
+	return [...values].sort();
+}