@nseng-ai/harness-artifacts 0.1.2

package/src/fs-state.ts

@@ -0,0 +1,22 @@
+/**
+ * Filesystem inspection states shared by harness-artifact convention checks.
+ *
+ * Moved from `@nseng-ai/areg` (`AregPathState` / `AregTextFileState`) so the
+ * harness-artifact subsystem and areg speak one vocabulary for "what is at
+ * this path".
+ */
+
+export type PathState =
+	| { type: "missing" }
+	| { type: "file" }
+	| { type: "directory" }
+	| { type: "symlink"; target: string }
+	| { type: "other" };
+
+export type TextFileState =
+	| { type: "missing" }
+	| { type: "file"; text: string }
+	| { type: "directory" }
+	| { type: "symlink"; target: string }
+	| { type: "other" }
+	| { type: "unreadable"; message: string };

package/src/harness-paths.ts

@@ -0,0 +1,217 @@
+import { join } from "node:path";
+
+import { resultErr, resultOk, type Result } from "@nseng-ai/foundation/result";
+
+import type { HarnessArtifactKind } from "./artifact-catalog.ts";
+
+export const HARNESS_SCOPES = ["project", "user"] as const;
+
+export type HarnessScope = (typeof HARNESS_SCOPES)[number];
+
+export interface HarnessPathEnvironment {
+	readonly CLAUDE_CONFIG_DIR?: string;
+}
+
+export interface HarnessPathContext {
+	projectRoot: string;
+	homeDir?: string;
+	env?: HarnessPathEnvironment;
+}
+
+export interface HarnessSpecData {
+	id: string;
+	aliases: readonly string[];
+	skillRoots: HarnessScopedPathSpec;
+}
+
+export interface HarnessScopedPathSpec {
+	project: HarnessBasePathSpec;
+	user: HarnessBasePathSpec;
+}
+
+export type HarnessBasePathSpec =
+	| { type: "project"; relativePath: string }
+	| { type: "home"; relativePath: string }
+	| {
+			type: "env-or-home";
+			envName: keyof HarnessPathEnvironment;
+			homeRelativePath: string;
+	  };
+
+export interface ResolvedHarnessSkillRoot {
+	harness: HarnessId;
+	rootPath: string;
+}
+
+export interface ResolvedHarnessArtifactPath {
+	harness: HarnessId;
+	scope: HarnessScope;
+	kind: "skill";
+	rootPath: string;
+	artifactPath: string;
+}
+
+export type HarnessPathErrorInfo =
+	| { code: "unknown_harness"; message: string; details: { input: string } }
+	| {
+			code: "unsupported_artifact_kind";
+			message: string;
+			details: { harness: HarnessId; kind: HarnessArtifactKind };
+	  }
+	| {
+			code: "missing_home_directory";
+			message: string;
+			details: { harness: HarnessId; scope: "user" };
+	  };
+
+export const HARNESS_SPECS = [
+	{
+		id: "claude-code",
+		aliases: ["claude"],
+		skillRoots: {
+			project: { type: "project", relativePath: ".claude/skills" },
+			user: {
+				type: "env-or-home",
+				envName: "CLAUDE_CONFIG_DIR",
+				homeRelativePath: ".claude/skills",
+			},
+		},
+	},
+	{
+		id: "codex",
+		aliases: [],
+		skillRoots: {
+			project: { type: "project", relativePath: ".agents/skills" },
+			user: { type: "home", relativePath: ".agents/skills" },
+		},
+	},
+	{
+		id: "pi",
+		aliases: ["pi-dev"],
+		skillRoots: {
+			project: { type: "project", relativePath: ".pi/skills" },
+			user: { type: "home", relativePath: ".pi/agent/skills" },
+		},
+	},
+] as const satisfies readonly HarnessSpecData[];
+
+export type HarnessId = (typeof HARNESS_SPECS)[number]["id"];
+export type HarnessSpec = (typeof HARNESS_SPECS)[number];
+
+const HARNESS_SPEC_BY_ID: ReadonlyMap<HarnessId, HarnessSpec> = new Map(
+	HARNESS_SPECS.map((spec) => [spec.id, spec]),
+);
+
+export const ALL_HARNESS_IDS: readonly HarnessId[] = HARNESS_SPECS.map((spec) => spec.id);
+
+export function normalizeHarnessId(input: string): Result<HarnessId, HarnessPathErrorInfo> {
+	const normalized = input.trim().toLowerCase();
+	for (const spec of HARNESS_SPECS) {
+		const aliases: readonly string[] = spec.aliases;
+		if (spec.id === normalized || aliases.includes(normalized)) return resultOk(spec.id);
+	}
+	return resultErr({
+		code: "unknown_harness",
+		message: `Unknown harness ${JSON.stringify(input)}. Supported harnesses: ${ALL_HARNESS_IDS.join(", ")}.`,
+		details: { input },
+	});
+}
+
+export function resolveHarnessSpec(input: string): Result<HarnessSpec, HarnessPathErrorInfo> {
+	const harness = normalizeHarnessId(input);
+	if (!harness.ok) return harness;
+	const spec = HARNESS_SPEC_BY_ID.get(harness.value);
+	if (spec === undefined) {
+		throw new Error(
+			`Harness spec missing for normalized harness ${JSON.stringify(harness.value)}.`,
+		);
+	}
+	return resultOk(spec);
+}
+
+export function resolveHarnessSkillRoot(input: {
+	harness: string;
+	scope: HarnessScope;
+	context: HarnessPathContext;
+}): Result<ResolvedHarnessSkillRoot, HarnessPathErrorInfo> {
+	const spec = resolveHarnessSpec(input.harness);
+	if (!spec.ok) return spec;
+	const basePathSpec = spec.value.skillRoots[input.scope];
+	if (input.scope === "user" && needsHomeDirectory(basePathSpec, input.context)) {
+		return resultErr({
+			code: "missing_home_directory",
+			message: `${spec.value.id} user-scope provisioning requires a home directory. Set HOME or pass NsExtensionApi.homeDir.`,
+			details: { harness: spec.value.id, scope: "user" },
+		});
+	}
+	return resultOk({
+		harness: spec.value.id,
+		rootPath: resolveBasePath(basePathSpec, input.context),
+	});
+}
+
+export function resolveHarnessArtifactPath(input: {
+	harness: string;
+	scope: HarnessScope;
+	kind: HarnessArtifactKind;
+	artifactName: string;
+	context: HarnessPathContext;
+}): Result<ResolvedHarnessArtifactPath, HarnessPathErrorInfo> {
+	const root = resolveHarnessSkillRoot(input);
+	if (!root.ok) return root;
+	if (input.kind !== "skill") {
+		return resultErr({
+			code: "unsupported_artifact_kind",
+			message: `${root.value.harness} does not support provisioning ${input.kind} artifacts in the steelthread path table yet.`,
+			details: { harness: root.value.harness, kind: input.kind },
+		});
+	}
+	return resultOk({
+		harness: root.value.harness,
+		scope: input.scope,
+		kind: "skill",
+		rootPath: root.value.rootPath,
+		artifactPath: join(root.value.rootPath, input.artifactName),
+	});
+}
+
+function needsHomeDirectory(spec: HarnessBasePathSpec, context: HarnessPathContext): boolean {
+	return spec.type !== "project" && resolvedUserScopeBasePath(spec, context) === undefined;
+}
+
+function resolveBasePath(spec: HarnessBasePathSpec, context: HarnessPathContext): string {
+	switch (spec.type) {
+		case "project":
+			return join(context.projectRoot, spec.relativePath);
+		case "home":
+		case "env-or-home": {
+			const basePath = resolvedUserScopeBasePath(spec, context);
+			if (basePath === undefined) {
+				throw new Error(
+					"Harness user-scope path resolution reached home fallback without a home directory.",
+				);
+			}
+			return basePath;
+		}
+	}
+}
+
+function resolvedUserScopeBasePath(
+	spec: Exclude<HarnessBasePathSpec, { type: "project" }>,
+	context: HarnessPathContext,
+): string | undefined {
+	if (spec.type === "env-or-home") {
+		const configured = context.env?.[spec.envName];
+		if (isPresent(configured)) return join(configured, "skills");
+		return joinPresent(context.homeDir, spec.homeRelativePath);
+	}
+	return joinPresent(context.homeDir, spec.relativePath);
+}
+
+function joinPresent(basePath: string | undefined, relativePath: string): string | undefined {
+	return isPresent(basePath) ? join(basePath, relativePath) : undefined;
+}
+
+function isPresent(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== "";
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./api.ts";

package/src/module-artifact-declaration.ts

@@ -0,0 +1,273 @@
+import { formatErrorMessage, formatZodIssue } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import type { SkillHarnessArtifactEntry } from "./artifact-catalog.ts";
+import { sortDiagnosticsByKey } from "./diagnostic-sort.ts";
+
+export const MODULE_ARTIFACT_DECLARATION_DIAGNOSTIC_CODES = [
+	"module_artifact_package_json_invalid",
+	"module_artifact_package_name_invalid",
+	"module_artifact_declarations_not_array",
+	"module_artifact_declaration_invalid",
+	"module_artifact_kind_unsupported",
+	"module_artifact_name_invalid",
+	"module_artifact_path_invalid",
+	"module_artifact_duplicate_name",
+] as const;
+
+export type ModuleArtifactDeclarationDiagnosticCode =
+	(typeof MODULE_ARTIFACT_DECLARATION_DIAGNOSTIC_CODES)[number];
+
+export interface ModuleArtifactDeclarationDiagnostic {
+	code: ModuleArtifactDeclarationDiagnosticCode;
+	message: string;
+	path?: string;
+	artifactName?: string;
+}
+
+export type ParseModuleArtifactDeclarationResult =
+	| {
+			ok: true;
+			packageName: string;
+			version: string;
+			artifacts: readonly SkillHarnessArtifactEntry[];
+			diagnostics: readonly ModuleArtifactDeclarationDiagnostic[];
+	  }
+	| {
+			ok: false;
+			diagnostics: readonly ModuleArtifactDeclarationDiagnostic[];
+	  };
+
+interface RawSkillDeclaration {
+	kind: "skill";
+	name: unknown;
+	path: unknown;
+	description?: unknown;
+}
+
+const packageJsonSchema = z.looseObject({
+	name: z.string(),
+	version: z.string().optional(),
+	ns: z.looseObject({ harnessArtifacts: z.unknown().optional() }).optional(),
+});
+
+const declarationObjectSchema = z.looseObject({
+	kind: z.string(),
+	name: z.unknown().optional(),
+	path: z.unknown().optional(),
+	description: z.unknown().optional(),
+});
+
+export function parseModuleArtifactDeclaration(
+	packageJsonText: string,
+): ParseModuleArtifactDeclarationResult {
+	let data: unknown;
+	try {
+		data = JSON.parse(packageJsonText);
+	} catch (error) {
+		return {
+			ok: false,
+			diagnostics: [
+				{
+					code: "module_artifact_package_json_invalid",
+					message: `Package manifest is not valid JSON: ${formatErrorMessage(error)}`,
+				},
+			],
+		};
+	}
+
+	const packageJson = packageJsonSchema.safeParse(data);
+	if (!packageJson.success || packageJson.data.name.trim() === "") {
+		return {
+			ok: false,
+			diagnostics: [
+				{
+					code: "module_artifact_package_name_invalid",
+					message: packageJson.success
+						? "Package manifest name must be a non-empty string."
+						: `Package manifest name must be a string: ${formatZodIssue(
+								packageJson.error.issues[0],
+								{
+									rootPath: "$",
+									pathPrefix: "$.",
+									fallback: "invalid package manifest",
+								},
+							)}`,
+				},
+			],
+		};
+	}
+
+	const packageName = packageJson.data.name;
+	const version = packageJson.data.version ?? "unversioned";
+	const declarations = packageJson.data.ns?.harnessArtifacts;
+	if (declarations === undefined) return emptyCatalog(packageName, version);
+	if (!Array.isArray(declarations)) {
+		return emptyCatalog(packageName, version, [
+			{
+				code: "module_artifact_declarations_not_array",
+				message: "Package manifest ns.harnessArtifacts must be an array.",
+			},
+		]);
+	}
+
+	return parseDeclarations({
+		packageName,
+		version,
+		declarations,
+	});
+}
+
+function emptyCatalog(
+	packageName: string,
+	version: string,
+	diagnostics: readonly ModuleArtifactDeclarationDiagnostic[] = [],
+): ParseModuleArtifactDeclarationResult {
+	return {
+		ok: true,
+		packageName,
+		version,
+		artifacts: [],
+		diagnostics,
+	};
+}
+
+function parseDeclarations(options: {
+	packageName: string;
+	version: string;
+	declarations: readonly unknown[];
+}): ParseModuleArtifactDeclarationResult {
+	const diagnostics: ModuleArtifactDeclarationDiagnostic[] = [];
+	const artifacts: SkillHarnessArtifactEntry[] = [];
+	const duplicateNames = duplicateDeclarationNames(options.declarations);
+	for (const declaration of options.declarations) {
+		const parsed = declarationObjectSchema.safeParse(declaration);
+		if (!parsed.success) {
+			diagnostics.push({
+				code: "module_artifact_declaration_invalid",
+				message: "Harness artifact declarations must be objects with a string kind.",
+			});
+			continue;
+		}
+
+		if (parsed.data.kind !== "skill") {
+			diagnostics.push({
+				code: "module_artifact_kind_unsupported",
+				message: `Harness artifact kind ${JSON.stringify(parsed.data.kind)} is not supported for provisioning in this slice.`,
+			});
+			continue;
+		}
+
+		const skillDeclaration: RawSkillDeclaration = {
+			kind: "skill",
+			name: parsed.data.name,
+			path: parsed.data.path,
+			...(parsed.data.description === undefined ? {} : { description: parsed.data.description }),
+		};
+		const artifact = parseSkillDeclaration({
+			packageName: options.packageName,
+			declaration: skillDeclaration,
+			duplicateNames,
+		});
+		if (artifact.ok) {
+			artifacts.push(artifact.artifact);
+		} else {
+			diagnostics.push(...artifact.diagnostics);
+		}
+	}
+
+	return {
+		ok: true,
+		packageName: options.packageName,
+		version: options.version,
+		artifacts: [...artifacts].sort((left, right) => left.id.localeCompare(right.id)),
+		diagnostics: sortDeclarationDiagnostics(diagnostics),
+	};
+}
+
+function parseSkillDeclaration(options: {
+	packageName: string;
+	declaration: RawSkillDeclaration;
+	duplicateNames: ReadonlySet<string>;
+}):
+	| { ok: true; artifact: SkillHarnessArtifactEntry }
+	| { ok: false; diagnostics: readonly ModuleArtifactDeclarationDiagnostic[] } {
+	const diagnostics: ModuleArtifactDeclarationDiagnostic[] = [];
+	const name = readNonEmptyString(options.declaration.name);
+	if (name === undefined) {
+		diagnostics.push({
+			code: "module_artifact_name_invalid",
+			message: "Skill harness artifact declaration name must be a non-empty string.",
+		});
+	}
+	const relativePath = readNonEmptyString(options.declaration.path);
+	if (relativePath === undefined || !isValidModuleArtifactRelativePath(relativePath)) {
+		diagnostics.push({
+			code: "module_artifact_path_invalid",
+			message:
+				"Skill harness artifact declaration path must be a relative POSIX path inside the package.",
+			...(relativePath === undefined ? {} : { path: relativePath }),
+			...(name === undefined ? {} : { artifactName: name }),
+		});
+	}
+	if (name !== undefined && options.duplicateNames.has(name)) {
+		diagnostics.push({
+			code: "module_artifact_duplicate_name",
+			message: `Skill harness artifact declaration name ${JSON.stringify(name)} appears more than once in this package.`,
+			artifactName: name,
+		});
+	}
+	if (diagnostics.length > 0 || name === undefined || relativePath === undefined) {
+		return { ok: false, diagnostics };
+	}
+	const description = readNonEmptyString(options.declaration.description);
+	return {
+		ok: true,
+		artifact: {
+			kind: "skill",
+			id: `${options.packageName}:${name}`,
+			name,
+			description: description ?? `Skill declared by ${options.packageName}.`,
+			skillName: name,
+			source: {
+				type: "npm-module",
+				packageName: options.packageName,
+				relativePath,
+			},
+		},
+	};
+}
+
+export function isValidModuleArtifactRelativePath(relativePath: string): boolean {
+	if (relativePath === "" || relativePath.startsWith("/") || relativePath.includes("\\")) {
+		return false;
+	}
+	const segments = relativePath.split("/");
+	return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
+function duplicateDeclarationNames(declarations: readonly unknown[]): ReadonlySet<string> {
+	const names: string[] = [];
+	for (const declaration of declarations) {
+		const parsed = declarationObjectSchema.safeParse(declaration);
+		if (!parsed.success || parsed.data.kind !== "skill") continue;
+		const name = readNonEmptyString(parsed.data.name);
+		if (name !== undefined) names.push(name);
+	}
+	return new Set(names.filter((name, index) => names.indexOf(name) !== index));
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function sortDeclarationDiagnostics(
+	diagnostics: readonly ModuleArtifactDeclarationDiagnostic[],
+): readonly ModuleArtifactDeclarationDiagnostic[] {
+	return sortDiagnosticsByKey(diagnostics, (diagnostic) => [
+		diagnostic.artifactName,
+		diagnostic.path,
+		diagnostic.code,
+		diagnostic.message,
+	]);
+}