@nseng-ai/harness-artifacts 0.1.2

package/src/ns/skills-install.ts

@@ -0,0 +1,141 @@
+import { failure, negative, ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import {
+	provisionFileDecisionSchema,
+	provisionFirstPartySkill,
+	type ProvisionDecisionSet,
+	type ProvisionFirstPartySkillOutcome,
+	type ProvisionPlan,
+} from "../api.ts";
+import {
+	provisionErrorExit,
+	skillsResolvedArtifactLocationSchema,
+	skillsTargetRequestSchema,
+	unknownSkillExit,
+	type SkillsCommandContext,
+} from "./skills-shared.ts";
+
+export const skillsInstallRequestSchema = skillsTargetRequestSchema.extend({
+	dryRun: z.boolean().default(false),
+	force: z.boolean().default(false),
+});
+
+export const skillsInstallResultSchema = skillsResolvedArtifactLocationSchema.extend({
+	mode: z.enum(["dry-run", "applied"]),
+	manifestPath: z.string(),
+	isForceRequired: z.boolean(),
+	decisions: z.array(provisionFileDecisionSchema),
+	writtenFiles: z.array(z.string()),
+});
+export type SkillsInstallResult = z.infer<typeof skillsInstallResultSchema>;
+
+export const skillsInstallConflictResultSchema = z.object({
+	manifestPath: z.string(),
+	conflictingFiles: z.array(z.string()),
+});
+export type SkillsInstallConflictResult = z.infer<typeof skillsInstallConflictResultSchema>;
+
+export const skillsInstallCommandResultSchema = z.union([
+	skillsInstallResultSchema,
+	skillsInstallConflictResultSchema,
+]);
+export type SkillsInstallCommandResult = z.infer<typeof skillsInstallCommandResultSchema>;
+
+export async function runSkillsInstall(
+	context: SkillsCommandContext,
+	request: z.output<typeof skillsInstallRequestSchema>,
+): Promise<ClinkrExit<SkillsInstallCommandResult>> {
+	const outcome = await provisionFirstPartySkill({
+		skill: request.skill,
+		harness: request.harness,
+		scope: request.scope,
+		projectRoot: context.projectRoot,
+		...optionalEntry("homeDir", context.homeDir),
+		env: context.env,
+		isDryRun: request.dryRun,
+		shouldForce: request.force,
+	});
+	switch (outcome.type) {
+		case "catalog-source-unavailable":
+			return failure("catalog-source-unavailable", outcome.message);
+		case "unknown-skill":
+			return unknownSkillExit(outcome.skill);
+		case "error":
+			return provisionErrorExit(outcome.error);
+		case "conflicted":
+			return installProvisionConflictExit(outcome);
+		case "provisioned":
+			return ok(
+				installResultFromPlan({
+					mode: outcome.mode,
+					plan: outcome.plan,
+					decisions: outcome.decisions,
+					manifestPath: outcome.manifestPath,
+					writtenFiles: outcome.writtenFiles,
+				}),
+			);
+	}
+}
+
+export function renderSkillsInstallHuman(result: SkillsInstallCommandResult): string {
+	if (!("mode" in result)) {
+		return `Provision refused: ${result.conflictingFiles.length} locally edited target file(s).\n`;
+	}
+	const lines = [
+		result.mode === "dry-run" ? "Provision preview" : "Provision applied",
+		`skill: ${result.skill}`,
+		`harness: ${result.harness}`,
+		`scope: ${result.scope}`,
+		`target path: ${result.targetArtifactPath}`,
+		`manifest: ${result.manifestPath}`,
+		`requires force: ${result.isForceRequired ? "yes" : "no"}`,
+		"decisions:",
+	];
+	for (const decision of result.decisions) {
+		lines.push(`- ${decision.type}: ${decision.file.relativePath} -> ${decision.file.targetPath}`);
+	}
+	if (result.mode === "applied") {
+		lines.push("written files:");
+		for (const file of result.writtenFiles) lines.push(`- ${file}`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+
+function installResultFromPlan(input: {
+	mode: SkillsInstallResult["mode"];
+	plan: ProvisionPlan;
+	decisions: ProvisionDecisionSet;
+	manifestPath: string;
+	writtenFiles: readonly string[];
+}): SkillsInstallResult {
+	return {
+		mode: input.mode,
+		skill: input.plan.provisionName,
+		artifactId: input.plan.artifactId,
+		harness: input.plan.harness,
+		scope: input.plan.scope,
+		targetRoot: input.plan.targetRoot,
+		targetArtifactPath: input.plan.targetArtifactPath,
+		manifestPath: input.manifestPath,
+		isForceRequired: input.decisions.isForceRequired,
+		decisions: [...input.decisions.files],
+		writtenFiles: [...input.writtenFiles],
+	};
+}
+
+function installProvisionConflictExit(
+	outcome: Extract<ProvisionFirstPartySkillOutcome, { type: "conflicted" }>,
+): ClinkrExit<SkillsInstallCommandResult> {
+	return negative(
+		`Provision refused: ${outcome.conflictingFiles.length} locally edited target file(s). Re-run with --force to overwrite them.`,
+		{
+			data: {
+				manifestPath: outcome.manifestPath,
+				conflictingFiles: [...outcome.conflictingFiles],
+			},
+		},
+	);
+}

package/src/ns/skills-list.ts

@@ -0,0 +1,43 @@
+import { ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import { z } from "zod";
+
+import { listFirstPartySkillArtifacts } from "../api.ts";
+
+export const skillsListRequestSchema = z.object({});
+
+export const skillsListResultSchema = z.object({
+	catalogId: z.string(),
+	skills: z.array(
+		z.object({
+			id: z.string(),
+			name: z.string(),
+			description: z.string(),
+			skillName: z.string(),
+			sourcePackage: z.string(),
+			sourceRelativePath: z.string(),
+		}),
+	),
+});
+export type SkillsListResult = z.infer<typeof skillsListResultSchema>;
+
+export function runSkillsList(): ClinkrExit<SkillsListResult> {
+	return ok({
+		catalogId: "ns-first-party",
+		skills: listFirstPartySkillArtifacts().map((artifact) => ({
+			id: artifact.id,
+			name: artifact.name,
+			description: artifact.description,
+			skillName: artifact.skillName,
+			sourcePackage: artifact.source.packageName,
+			sourceRelativePath: artifact.source.relativePath,
+		})),
+	});
+}
+
+export function renderSkillsListHuman(result: SkillsListResult): string {
+	const lines = [`ns first-party skills (${result.catalogId})`];
+	for (const skill of result.skills) {
+		lines.push(`- ${skill.skillName} (${skill.id}) — ${skill.description}`);
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/ns/skills-path.ts

@@ -0,0 +1,53 @@
+import { ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import { z } from "zod";
+
+import { findFirstPartySkillArtifact, resolveHarnessArtifactPath } from "../api.ts";
+import {
+	harnessPathErrorExit,
+	harnessResolutionContext,
+	skillsResolvedArtifactLocationSchema,
+	skillsTargetRequestSchema,
+	unknownSkillExit,
+	type SkillsCommandContext,
+} from "./skills-shared.ts";
+
+export const skillsPathRequestSchema = skillsTargetRequestSchema;
+
+export const skillsPathResultSchema = skillsResolvedArtifactLocationSchema;
+export type SkillsPathResult = z.infer<typeof skillsPathResultSchema>;
+
+export function runSkillsPath(
+	context: SkillsCommandContext,
+	request: z.output<typeof skillsPathRequestSchema>,
+): ClinkrExit<SkillsPathResult> {
+	const artifact = findFirstPartySkillArtifact(request.skill);
+	if (artifact === undefined) return unknownSkillExit(request.skill);
+	const resolvedPath = resolveHarnessArtifactPath({
+		harness: request.harness,
+		scope: request.scope,
+		kind: artifact.kind,
+		artifactName: artifact.skillName,
+		context: harnessResolutionContext(context),
+	});
+	if (!resolvedPath.ok) return harnessPathErrorExit(resolvedPath.error);
+	return ok({
+		skill: artifact.skillName,
+		artifactId: artifact.id,
+		harness: resolvedPath.value.harness,
+		scope: resolvedPath.value.scope,
+		targetRoot: resolvedPath.value.rootPath,
+		targetArtifactPath: resolvedPath.value.artifactPath,
+	});
+}
+
+export function renderSkillsPathHuman(result: SkillsPathResult): string {
+	return [
+		`skill: ${result.skill}`,
+		`artifact: ${result.artifactId}`,
+		`harness: ${result.harness}`,
+		`scope: ${result.scope}`,
+		`target root: ${result.targetRoot}`,
+		`target path: ${result.targetArtifactPath}`,
+		"",
+	].join("\n");
+}

package/src/ns/skills-shared.ts

@@ -0,0 +1,65 @@
+import { failure, negative, usageError, type ClinkrExit } from "@nseng-ai/clinkr";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import {
+	ALL_HARNESS_IDS,
+	firstPartySkillProvisionPathContext,
+	HARNESS_SCOPES,
+	type HarnessArtifactProvisionErrorInfo,
+	type HarnessPathErrorInfo,
+} from "../api.ts";
+
+export interface SkillsCommandContext {
+	cwd: string;
+	projectRoot: string;
+	homeDir?: string;
+	env: Record<string, string | undefined>;
+}
+
+export const skillsTargetRequestSchema = z.object({
+	skill: z.string().min(1),
+	harness: z.string().min(1),
+	scope: z.enum(HARNESS_SCOPES).default("project"),
+});
+
+export const skillsResolvedArtifactLocationSchema = z.object({
+	skill: z.string(),
+	artifactId: z.string(),
+	harness: z.enum(ALL_HARNESS_IDS),
+	scope: z.enum(HARNESS_SCOPES),
+	targetRoot: z.string(),
+	targetArtifactPath: z.string(),
+});
+
+export function harnessResolutionContext(context: SkillsCommandContext) {
+	return firstPartySkillProvisionPathContext({
+		projectRoot: context.projectRoot,
+		...optionalEntry("homeDir", context.homeDir),
+		env: context.env,
+	});
+}
+
+export function unknownSkillExit<T>(skill: string): ClinkrExit<T> {
+	return negative(`Unknown first-party ns skill ${JSON.stringify(skill)}.`);
+}
+
+export function provisionErrorExit<T>(error: HarnessArtifactProvisionErrorInfo): ClinkrExit<T> {
+	if (error.code === "unknown_harness") return harnessPathErrorExit(error);
+	return genericFailureExit(error);
+}
+
+export function harnessPathErrorExit<T>(error: HarnessPathErrorInfo): ClinkrExit<T> {
+	if (error.code === "unknown_harness") {
+		return usageError(error.message, { field: "harness", ...error.details });
+	}
+	return genericFailureExit(error);
+}
+
+function genericFailureExit<T>(error: {
+	code: string;
+	message: string;
+	details?: unknown;
+}): ClinkrExit<T> {
+	return failure(error.code.replaceAll("_", "-"), error.message, error.details);
+}

package/src/ns/update.ts

@@ -0,0 +1,99 @@
+import { failure, negative, ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import {
+	reconcileReportSchema,
+	runHarnessArtifactReconcile,
+	type ReconcileErrorInfo,
+} from "../api.ts";
+import type { SkillsCommandContext } from "./skills-shared.ts";
+
+export const nsUpdateRequestSchema = z.object({
+	dryRun: z.boolean().default(false),
+	force: z.boolean().default(false),
+});
+
+export const nsUpdateResultSchema = reconcileReportSchema;
+export type NsUpdateRequest = z.output<typeof nsUpdateRequestSchema>;
+export type NsUpdateResult = z.output<typeof nsUpdateResultSchema>;
+
+export async function runNsUpdate(
+	context: SkillsCommandContext,
+	request: NsUpdateRequest,
+): Promise<ClinkrExit<NsUpdateResult>> {
+	const baseRequest = {
+		projectRoot: context.projectRoot,
+		...optionalEntry("homeDir", context.homeDir),
+		env: context.env,
+		shouldForce: request.force,
+	};
+	if (request.dryRun || !request.force) {
+		const preview = await runHarnessArtifactReconcile({ ...baseRequest, isDryRun: true });
+		if (!preview.ok) return reconcileFailureExit(preview.error);
+		if (request.dryRun) return ok(preview.value);
+		if (preview.value.isForceRequired) {
+			return negative("Update refused: locally edited target files require --force.", {
+				data: preview.value,
+			});
+		}
+	}
+	const result = await runHarnessArtifactReconcile({ ...baseRequest, isDryRun: false });
+	if (!result.ok) return reconcileFailureExit(result.error);
+	if (result.value.skippedCollisions.length > 0) {
+		return negative("Update skipped colliding harness artifacts.", { data: result.value });
+	}
+	return ok(result.value);
+}
+
+export function renderNsUpdateHuman(result: NsUpdateResult): string {
+	const lines = [result.mode === "dry-run" ? "Update preview" : "Update applied"];
+	if (result.harnessSelection.type === "missing") {
+		lines.push(
+			"",
+			"No harness selection found in ns.toml — run `ns init` to select harnesses; refreshed manifest-tracked artifacts only.",
+		);
+	}
+	lines.push("", "artifacts:");
+	if (result.artifacts.length === 0) {
+		lines.push("- none");
+	} else {
+		for (const artifact of result.artifacts) {
+			lines.push(
+				`- ${artifact.action} ${artifact.skillName} (${artifact.harness}) -> ${artifact.targetArtifactPath}`,
+			);
+		}
+	}
+	if (result.orphans.length > 0) {
+		lines.push("", "orphans:");
+		for (const orphan of result.orphans) {
+			lines.push(
+				`- orphaned — source missing, files left in place: ${orphan.artifactId} (${orphan.harness})`,
+			);
+		}
+	}
+	if (result.skippedCollisions.length > 0) {
+		lines.push("", "skipped collisions:");
+		for (const collision of result.skippedCollisions) {
+			lines.push(`- ${collision.kind} ${collision.value}: ${collision.packages.join(", ")}`);
+		}
+	}
+	if (result.isForceRequired) lines.push("", "Conflicts found; re-run with --force to overwrite.");
+	lines.push(
+		"",
+		`summary: ${countArtifacts(result, "installed")} installed, ${countArtifacts(result, "refreshed")} refreshed, ${countArtifacts(result, "unchanged")} unchanged, ${countArtifacts(result, "conflicted")} conflicted, ${countArtifacts(result, "skipped")} skipped, ${result.orphans.length} orphaned, ${result.diagnostics.length} diagnostic(s)`,
+		"",
+	);
+	return lines.join("\n");
+}
+
+function reconcileFailureExit<T>(error: ReconcileErrorInfo): ClinkrExit<T> {
+	return failure(error.code.replaceAll("_", "-"), error.message, error.details);
+}
+
+function countArtifacts(
+	result: NsUpdateResult,
+	action: NsUpdateResult["artifacts"][number]["action"],
+): number {
+	return result.artifacts.filter((artifact) => artifact.action === action).length;
+}

package/src/ns-toml.ts

@@ -0,0 +1,195 @@
+import {
+	getProjectConfigSetting,
+	parseProjectConfigToml,
+	projectConfigErrorFromDiagnostics,
+	type ProjectConfigDiagnostic,
+	type SettingsSchema,
+} from "@nseng-ai/kernel/project-config/points";
+import { z } from "zod";
+
+import { ALL_HARNESS_IDS, type HarnessId } from "./harness-paths.ts";
+
+export type NsTomlHarnessesParseResult =
+	| { type: "ok"; harnesses: readonly HarnessId[] }
+	| { type: "missing" }
+	| { type: "error"; error: NsTomlErrorInfo };
+
+export type NsTomlWritePlanResult =
+	| { type: "ok"; content: string; change: NsTomlChange }
+	| { type: "error"; error: NsTomlErrorInfo };
+
+export type NsTomlChange = "created" | "appended" | "replaced" | "unchanged";
+
+export interface NsTomlErrorInfo {
+	code: NsTomlErrorCode;
+	message: string;
+}
+
+export type NsTomlErrorCode =
+	| "invalid-toml"
+	| "invalid-harnesses"
+	| "ambiguous-harnesses-assignment";
+
+const nsInitHarnessesSettingsSchema = {
+	path: ["harnesses"] as const,
+	schema: z.array(z.string()).nonempty(),
+	invalidMessage: ({ pathLabel }) =>
+		`${pathLabel} top-level harnesses must be a non-empty string array.`,
+} satisfies SettingsSchema<readonly string[]>;
+
+const nsInitHarnessesSettingsKey = nsInitHarnessesSettingsSchema.path.join(".");
+
+export function parseNsTomlHarnesses(
+	content: string,
+	pathLabel = "ns.toml",
+): NsTomlHarnessesParseResult {
+	const result = parseProjectConfigToml(content, {
+		pathLabel,
+		pointsTable: { mode: "skip" },
+		settingsSchemas: [nsInitHarnessesSettingsSchema],
+	});
+	if (!result.ok) return nsTomlErrorFromDiagnostics(result.diagnostics, pathLabel);
+	const harnesses = getProjectConfigSetting(result.config, nsInitHarnessesSettingsSchema);
+	if (harnesses === undefined) return { type: "missing" };
+	return normalizeHarnessSelection(harnesses);
+}
+
+export function renderNsTomlHarnesses(harnesses: readonly HarnessId[]): string {
+	return `harnesses = ${JSON.stringify([...harnesses])}\n`;
+}
+
+export function planNsTomlHarnessesWrite(options: {
+	content: string | undefined;
+	harnesses: readonly HarnessId[];
+}): NsTomlWritePlanResult {
+	const rendered = renderNsTomlHarnesses(options.harnesses);
+	if (options.content === undefined) return { type: "ok", content: rendered, change: "created" };
+
+	const existing = parseNsTomlHarnesses(options.content);
+	if (existing.type === "error") return existing;
+	if (existing.type === "ok" && sameHarnesses(existing.harnesses, options.harnesses)) {
+		return { type: "ok", content: options.content, change: "unchanged" };
+	}
+
+	const replacement = replaceTopLevelHarnessesAssignment(options.content, rendered);
+	if (replacement.type === "error") return replacement;
+	return {
+		type: "ok",
+		content: replacement.content,
+		change: existing.type === "ok" ? "replaced" : "appended",
+	};
+}
+
+export function normalizeHarnessSelection(
+	values: readonly string[],
+): { type: "ok"; harnesses: readonly HarnessId[] } | { type: "error"; error: NsTomlErrorInfo } {
+	const selected: HarnessId[] = [];
+	for (const value of values) {
+		if (!isHarnessId(value)) {
+			return {
+				type: "error",
+				error: {
+					code: "invalid-harnesses",
+					message: `Unknown harness ${JSON.stringify(value)}. Expected one of ${ALL_HARNESS_IDS.join(", ")}.`,
+				},
+			};
+		}
+		if (!selected.includes(value)) selected.push(value);
+	}
+	if (selected.length === 0) {
+		return {
+			type: "error",
+			error: { code: "invalid-harnesses", message: "At least one harness must be selected." },
+		};
+	}
+	return { type: "ok", harnesses: selected };
+}
+
+function nsTomlErrorFromDiagnostics(
+	diagnostics: readonly ProjectConfigDiagnostic[],
+	pathLabel: string,
+): NsTomlHarnessesParseResult {
+	const error = projectConfigErrorFromDiagnostics(diagnostics, {
+		invalidToml: "invalid-toml",
+		invalidSettingsByPath: { [nsInitHarnessesSettingsKey]: "invalid-harnesses" },
+		defaultCode: "invalid-toml",
+		defaultMessage: `${pathLabel}: invalid ns.toml`,
+		pathLabel,
+	});
+	return { type: "error", error: { code: error.code, message: error.message } };
+}
+
+function replaceTopLevelHarnessesAssignment(
+	content: string,
+	renderedHarnesses: string,
+): { type: "ok"; content: string } | { type: "error"; error: NsTomlErrorInfo } {
+	const lines = splitLines(content);
+	let tableStart = lines.findIndex((line) => tomlTableName(line) !== null);
+	if (tableStart < 0) tableStart = lines.length;
+
+	for (let index = 0; index < tableStart; index += 1) {
+		const line = lines[index] ?? "";
+		if (!/^\s*harnesses\s*=/u.test(line)) continue;
+		if (!line.includes("]")) {
+			return {
+				type: "error",
+				error: {
+					code: "ambiguous-harnesses-assignment",
+					message:
+						"Top-level ns.toml harnesses assignment must be a single-line array before it can be replaced.",
+				},
+			};
+		}
+		lines.splice(index, 1, renderedHarnesses);
+		return { type: "ok", content: lines.join("") };
+	}
+
+	if (tableStart < lines.length) {
+		const beforeTables = lines.slice(0, tableStart).join("");
+		const afterTables = lines.slice(tableStart).join("");
+		const separator =
+			beforeTables.length === 0 || beforeTables.endsWith("\n\n")
+				? ""
+				: beforeTables.endsWith("\n")
+					? "\n"
+					: "\n\n";
+		return {
+			type: "ok",
+			content: `${beforeTables}${separator}${renderedHarnesses}\n${afterTables}`,
+		};
+	}
+
+	return { type: "ok", content: appendTopLevelAssignment(content, renderedHarnesses) };
+}
+
+function appendTopLevelAssignment(content: string, assignment: string): string {
+	if (content.length === 0) return assignment;
+	if (content.endsWith("\n\n")) return `${content}${assignment}`;
+	if (content.endsWith("\n")) return `${content}\n${assignment}`;
+	return `${content}\n\n${assignment}`;
+}
+
+function splitLines(content: string): string[] {
+	return content.match(/.*(?:\n|$)/gu)?.filter((line) => line.length > 0) ?? [];
+}
+
+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();
+}
+
+function sameHarnesses(left: readonly HarnessId[], right: readonly HarnessId[]): boolean {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function isHarnessId(value: string): value is HarnessId {
+	return ALL_HARNESS_IDS.includes(value as HarnessId);
+}