@nseng-ai/harness-artifacts 0.1.2

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@nseng-ai/harness-artifacts",
+	"version": "0.1.2",
+	"type": "module",
+	"files": [
+		"src"
+	],
+	"engines": {
+		"node": ">=24.12.0",
+		"pnpm": ">=11.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./api": "./src/api.ts",
+		"./ns/commands/install": "./src/ns/commands/install.ts",
+		"./ns/commands/list": "./src/ns/commands/list.ts",
+		"./ns/commands/path": "./src/ns/commands/path.ts",
+		"./ns/commands/update": "./src/ns/commands/update.ts",
+		"./ns/preinstalled-catalog": "./src/ns/preinstalled-catalog.ts"
+	},
+	"dependencies": {
+		"@nseng-ai/capability-kit": "0.1.2",
+		"@nseng-ai/clinkr": "0.1.2",
+		"@nseng-ai/foundation": "0.1.2",
+		"@nseng-ai/kernel": "0.1.2",
+		"smol-toml": "^1.6.1",
+		"zod": "^4.4.3"
+	}
+}

package/src/api.ts

@@ -0,0 +1,190 @@
+/**
+ * Capability API for `@nseng-ai/harness-artifacts` — the shared home for
+ * harness-artifact conventions pushed down from `@nseng-ai/areg` (see the
+ * `skill-management-subsystem` Objective). Cross-package consumers import
+ * from this door only.
+ */
+
+export {
+	artifactProvisionName,
+	HARNESS_ARTIFACT_KINDS,
+	type AgentHarnessArtifactEntry,
+	type ExtensionBundleHarnessArtifactEntry,
+	type FirstPartyHarnessArtifactCatalog,
+	type FirstPartyHarnessArtifactSource,
+	type HarnessArtifactEntry,
+	type HarnessArtifactEntryBase,
+	type HarnessArtifactKind,
+	type HarnessArtifactSource,
+	type NpmModuleHarnessArtifactSource,
+	type SkillHarnessArtifactEntry,
+} from "./artifact-catalog.ts";
+export {
+	findFirstPartySkillArtifact,
+	listFirstPartySkillArtifacts,
+	NS_FIRST_PARTY_HARNESS_ARTIFACT_CATALOG,
+	type FirstPartySkillHarnessArtifact,
+} from "./first-party-catalog.ts";
+export {
+	nodeHarnessArtifactFileSystemGateway,
+	type HarnessArtifactFileSystemErrorInfo,
+	type HarnessArtifactFileSystemGateway,
+	type HarnessArtifactModuleDiscoveryGateway,
+	type ModuleDiscoveryDirectoryEntry,
+	type ModuleDiscoveryDirectoryState,
+	type ModuleDiscoveryPathState,
+	type OptionalFileState,
+	type OptionalTextFileState,
+} from "./filesystem.ts";
+export type { PathState, TextFileState } from "./fs-state.ts";
+export {
+	FIRST_PARTY_SKILL_CATALOG_SOURCE_UNAVAILABLE_MESSAGE,
+	FIRST_PARTY_SKILL_CATALOG_SOURCE_VERSION,
+	firstPartySkillProvisionPathContext,
+	provisionFirstPartySkill,
+	resolveFirstPartyCatalogSourceRoot,
+	type ProvisionFirstPartySkillOutcome,
+	type ProvisionFirstPartySkillRequest,
+} from "./first-party-skill-provisioning.ts";
+export {
+	ALL_HARNESS_IDS,
+	HARNESS_SCOPES,
+	HARNESS_SPECS,
+	normalizeHarnessId,
+	resolveHarnessArtifactPath,
+	resolveHarnessSkillRoot,
+	resolveHarnessSpec,
+	type HarnessBasePathSpec,
+	type HarnessId,
+	type HarnessPathContext,
+	type HarnessPathEnvironment,
+	type HarnessPathErrorInfo,
+	type HarnessScope,
+	type HarnessScopedPathSpec,
+	type HarnessSpec,
+	type ResolvedHarnessArtifactPath,
+	type ResolvedHarnessSkillRoot,
+} from "./harness-paths.ts";
+export {
+	normalizeHarnessSelection,
+	parseNsTomlHarnesses,
+	planNsTomlHarnessesWrite,
+	renderNsTomlHarnesses,
+	type NsTomlChange,
+	type NsTomlErrorCode,
+	type NsTomlErrorInfo,
+	type NsTomlHarnessesParseResult,
+	type NsTomlWritePlanResult,
+} from "./ns-toml.ts";
+export {
+	planHarnessArtifactReconcile,
+	reconcileReportSchema,
+	runHarnessArtifactReconcile,
+	type DesiredHarnessArtifact,
+	type HarnessManifestSnapshot,
+	type HarnessSelectionState,
+	type OrphanedManifestEntry,
+	type ReconcileArtifactOutcome,
+	type ReconcileErrorInfo,
+	type ReconcilePair,
+	type ReconcileReport,
+	type SkippedArtifactCollision,
+	type RunHarnessArtifactReconcileRequest,
+} from "./reconcile.ts";
+export {
+	discoverExtensionModuleHarnessArtifacts,
+	moduleArtifactDiscoveryDiagnosticSchema,
+	type DiscoverExtensionModuleHarnessArtifactsRequest,
+	type DiscoverExtensionModuleHarnessArtifactsResult,
+	MODULE_ARTIFACT_DISCOVERY_DIAGNOSTIC_CODES,
+	type ModuleArtifactDiscoveryDiagnostic,
+	type ModuleArtifactDiscoveryDiagnosticCode,
+	type ResolvedNpmModuleHarnessArtifactCatalog,
+} from "./module-artifact-discovery.ts";
+export {
+	isValidModuleArtifactRelativePath,
+	MODULE_ARTIFACT_DECLARATION_DIAGNOSTIC_CODES,
+	parseModuleArtifactDeclaration,
+	type ModuleArtifactDeclarationDiagnostic,
+	type ModuleArtifactDeclarationDiagnosticCode,
+	type ParseModuleArtifactDeclarationResult,
+} from "./module-artifact-declaration.ts";
+export {
+	applyHarnessArtifactProvision,
+	applyPreparedProvision,
+	INSTALL_MANIFEST_FILE_NAME,
+	installManifestPathForPlan,
+	prepareProvision,
+	previewHarnessArtifactProvision,
+	readInstallManifestAtRoot,
+	type ApplyPreparedProvisionOptions,
+	type HarnessArtifactProvisionAppliedOutcome,
+	type HarnessArtifactProvisionApplyOutcome,
+	type HarnessArtifactProvisionApplyResult,
+	type HarnessArtifactProvisionConflictOutcome,
+	type HarnessArtifactProvisionErrorInfo,
+	type HarnessArtifactProvisionPreview,
+	type HarnessArtifactProvisionRequest,
+	type PreparedHarnessArtifactProvision,
+} from "./provision-apply.ts";
+export {
+	buildInstallManifestData,
+	buildInstallManifestEntry,
+	buildProvisionPlan,
+	classifyProvisionDecisions,
+	contentHashForBytes,
+	contentHashForText,
+	installManifestKey,
+	provisionFileDecisionSchema,
+	provisionPlanFileSchema,
+	type BuildProvisionPlanInput,
+	type InstallManifestData,
+	type InstallManifestEntryData,
+	type InstallManifestFileData,
+	type InstallManifestSourceData,
+	type ProvisionDecisionErrorInfo,
+	type ProvisionDecisionSet,
+	type ProvisionFileDecision,
+	type ProvisionFileDecisionType,
+	type ProvisionPlan,
+	type ProvisionPlanErrorInfo,
+	type ProvisionPlanFile,
+	type ProvisionSourceFile,
+	type ProvisionSourceProvenance,
+	type ProvisionableHarnessArtifactEntry,
+	type TargetFileHashFact,
+} from "./provision-plan.ts";
+export {
+	parseSkillFrontmatterBlock,
+	parseSkillFrontmatterTopLevelLine,
+	isSkillFrontmatterTopLevelKey,
+	transformSkillFrontmatter,
+	type SkillFrontmatterData,
+	type SkillFrontmatterParseResult,
+	type SkillFrontmatterTopLevelLineParseResult,
+} from "./skill-frontmatter.ts";
+export {
+	agentsSkillMirrorRelativePath,
+	claudeSkillMirrorRelativePath,
+	classifySkillMirrorSymlinkState,
+	expectedAgentsSkillSymlinkTarget,
+	expectedClaudeSkillSymlinkTarget,
+	expectedMirrorTarget,
+	isAgentsSkillMirror,
+	isClaudeSkillMirror,
+	isSkillMirrorRelativePath,
+	parseSkillMirrorRelativePath,
+	type SkillMirrorKind,
+	type SkillMirrorRelativePathInfo,
+} from "./skill-mirror-conventions.ts";
+export {
+	parseInspectedLockfile,
+	parseLockfileData,
+	parseLockfileText,
+	SOURCE_TYPES,
+	type LockfileSkill,
+	type LockfileSkillData,
+	type SkillsLockfile,
+	type SkillsLockfileData,
+	type SourceType,
+} from "./skills-lockfile.ts";

package/src/artifact-catalog.ts

@@ -0,0 +1,65 @@
+export const HARNESS_ARTIFACT_KINDS = ["skill", "agent", "extension-bundle"] as const;
+
+export type HarnessArtifactKind = (typeof HARNESS_ARTIFACT_KINDS)[number];
+
+export interface HarnessArtifactEntryBase {
+	id: string;
+	name: string;
+	description: string;
+}
+
+export interface SkillHarnessArtifactEntry extends HarnessArtifactEntryBase {
+	kind: "skill";
+	skillName: string;
+	source: HarnessArtifactSource;
+}
+
+export interface AgentHarnessArtifactEntry extends HarnessArtifactEntryBase {
+	kind: "agent";
+	agentName: string;
+	source: FirstPartyHarnessArtifactSource;
+}
+
+export interface ExtensionBundleHarnessArtifactEntry extends HarnessArtifactEntryBase {
+	kind: "extension-bundle";
+	bundleName: string;
+	source: FirstPartyHarnessArtifactSource;
+}
+
+export type HarnessArtifactEntry =
+	| SkillHarnessArtifactEntry
+	| AgentHarnessArtifactEntry
+	| ExtensionBundleHarnessArtifactEntry;
+
+export interface FirstPartyHarnessArtifactSource {
+	type: "first-party";
+	packageName: string;
+	relativePath: string;
+}
+
+export interface NpmModuleHarnessArtifactSource {
+	type: "npm-module";
+	packageName: string;
+	relativePath: string;
+}
+
+export type HarnessArtifactSource =
+	| FirstPartyHarnessArtifactSource
+	| NpmModuleHarnessArtifactSource;
+
+export interface FirstPartyHarnessArtifactCatalog {
+	type: "first-party-catalog";
+	catalogId: string;
+	artifacts: readonly HarnessArtifactEntry[];
+}
+
+export function artifactProvisionName(artifact: HarnessArtifactEntry): string {
+	switch (artifact.kind) {
+		case "skill":
+			return artifact.skillName;
+		case "agent":
+			return artifact.agentName;
+		case "extension-bundle":
+			return artifact.bundleName;
+	}
+}

package/src/diagnostic-sort.ts

@@ -0,0 +1,14 @@
+export function sortDiagnosticsByKey<TDiagnostic>(
+	diagnostics: readonly TDiagnostic[],
+	keyFields: (diagnostic: TDiagnostic) => readonly (string | undefined)[],
+): readonly TDiagnostic[] {
+	return [...diagnostics].sort((left, right) =>
+		joinedDiagnosticSortKey(keyFields(left)).localeCompare(
+			joinedDiagnosticSortKey(keyFields(right)),
+		),
+	);
+}
+
+function joinedDiagnosticSortKey(fields: readonly (string | undefined)[]): string {
+	return fields.map((field) => field ?? "").join("\0");
+}

package/src/filesystem.ts

@@ -0,0 +1,181 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { errorCodeFromUnknown, formatErrorMessage } from "@nseng-ai/foundation/primitives";
+import { resultErr, resultOk, type Result } from "@nseng-ai/foundation/result";
+
+import { sortStrings } from "./sort.ts";
+
+export interface HarnessArtifactFileSystemErrorInfo {
+	code: "filesystem_error";
+	message: string;
+	details: { path: string; operation: "stat" | "list" | "read" | "write" };
+}
+
+export type OptionalFileState = { type: "missing" } | { type: "file"; bytes: Uint8Array };
+export type OptionalTextFileState = { type: "missing" } | { type: "file"; text: string };
+
+export type ModuleDiscoveryDirectoryState =
+	| { type: "missing" }
+	| { type: "file" }
+	| { type: "directory"; entries: readonly ModuleDiscoveryDirectoryEntry[] };
+
+export interface ModuleDiscoveryDirectoryEntry {
+	name: string;
+	type: "directory" | "file" | "other";
+}
+
+export type ModuleDiscoveryPathState =
+	| { type: "missing" }
+	| { type: "file" }
+	| { type: "directory" }
+	| { type: "other" };
+
+export interface HarnessArtifactFileSystemGateway {
+	listFiles(
+		rootPath: string,
+	): Promise<Result<readonly string[], HarnessArtifactFileSystemErrorInfo>>;
+	readOptionalFile(
+		path: string,
+	): Promise<Result<OptionalFileState, HarnessArtifactFileSystemErrorInfo>>;
+	writeFile(
+		path: string,
+		bytes: Uint8Array,
+	): Promise<Result<void, HarnessArtifactFileSystemErrorInfo>>;
+	readOptionalTextFile(
+		path: string,
+	): Promise<Result<OptionalTextFileState, HarnessArtifactFileSystemErrorInfo>>;
+	writeTextFile(
+		path: string,
+		text: string,
+	): Promise<Result<void, HarnessArtifactFileSystemErrorInfo>>;
+}
+
+export interface HarnessArtifactModuleDiscoveryGateway {
+	readDirectory(
+		path: string,
+	): Promise<Result<ModuleDiscoveryDirectoryState, HarnessArtifactFileSystemErrorInfo>>;
+	readOptionalTextFile(
+		path: string,
+	): Promise<Result<OptionalTextFileState, HarnessArtifactFileSystemErrorInfo>>;
+	pathState(
+		path: string,
+	): Promise<Result<ModuleDiscoveryPathState, HarnessArtifactFileSystemErrorInfo>>;
+}
+
+export const nodeHarnessArtifactFileSystemGateway: HarnessArtifactFileSystemGateway &
+	HarnessArtifactModuleDiscoveryGateway = {
+	async listFiles(rootPath) {
+		try {
+			return resultOk(await listFiles(rootPath));
+		} catch (error) {
+			return resultErr(fileSystemError(rootPath, "list", error));
+		}
+	},
+	async readOptionalFile(path) {
+		return withMissingAsOk({
+			path,
+			operation: "read",
+			run: async () => ({ type: "file", bytes: await readFile(path) }),
+		});
+	},
+	async writeFile(path, bytes) {
+		try {
+			await mkdir(dirname(path), { recursive: true });
+			await writeFile(path, bytes);
+			return resultOk(undefined);
+		} catch (error) {
+			return resultErr(fileSystemError(path, "write", error));
+		}
+	},
+	async readOptionalTextFile(path) {
+		const state = await nodeHarnessArtifactFileSystemGateway.readOptionalFile(path);
+		if (!state.ok) return state;
+		if (state.value.type === "missing") return resultOk({ type: "missing" });
+		return resultOk({ type: "file", text: new TextDecoder().decode(state.value.bytes) });
+	},
+	async writeTextFile(path, text) {
+		return nodeHarnessArtifactFileSystemGateway.writeFile(path, new TextEncoder().encode(text));
+	},
+	async readDirectory(path) {
+		return withMissingAsOk({
+			path,
+			operation: "list",
+			async run() {
+				const pathStat = await stat(path);
+				if (pathStat.isFile()) return { type: "file" } as const;
+				if (!pathStat.isDirectory()) return { type: "file" } as const;
+				const entries = await readdir(path, { withFileTypes: true });
+				return {
+					type: "directory",
+					entries: entries.map((entry) => ({
+						name: entry.name,
+						type: entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "other",
+					})),
+				} as const;
+			},
+		});
+	},
+	async pathState(path) {
+		return withMissingAsOk({
+			path,
+			operation: "stat",
+			async run() {
+				const pathStat = await stat(path);
+				if (pathStat.isDirectory()) return { type: "directory" } as const;
+				if (pathStat.isFile()) return { type: "file" } as const;
+				return { type: "other" } as const;
+			},
+		});
+	},
+};
+
+async function withMissingAsOk<T>(options: {
+	path: string;
+	operation: HarnessArtifactFileSystemErrorInfo["details"]["operation"];
+	run: () => Promise<T>;
+}): Promise<Result<T | { type: "missing" }, HarnessArtifactFileSystemErrorInfo>> {
+	try {
+		return resultOk(await options.run());
+	} catch (error) {
+		if (isNodeErrorCode(error, "ENOENT")) return resultOk({ type: "missing" });
+		return resultErr(fileSystemError(options.path, options.operation, error));
+	}
+}
+
+export function fileSystemError(
+	path: string,
+	operation: HarnessArtifactFileSystemErrorInfo["details"]["operation"],
+	error: unknown,
+): HarnessArtifactFileSystemErrorInfo {
+	return {
+		code: "filesystem_error",
+		message: `Filesystem ${operation} failed for ${path}: ${formatErrorMessage(error)}`,
+		details: { path, operation },
+	};
+}
+
+export function isNodeErrorCode(error: unknown, code: string): boolean {
+	return errorCodeFromUnknown(error) === code;
+}
+
+async function listFiles(rootPath: string): Promise<readonly string[]> {
+	return sortStrings(await walkFiles(rootPath, ""));
+}
+
+async function walkFiles(rootPath: string, relativePath: string): Promise<readonly string[]> {
+	const directory = relativePath === "" ? rootPath : join(rootPath, relativePath);
+	const entries = await readdir(directory, { withFileTypes: true });
+	const output: string[] = [];
+	for (const entry of entries) {
+		const entryRelativePath = relativePath === "" ? entry.name : join(relativePath, entry.name);
+		if (entry.isDirectory()) {
+			output.push(...(await walkFiles(rootPath, entryRelativePath)));
+		} else if (entry.isFile()) {
+			output.push(entryRelativePath);
+		} else {
+			throw new Error(`Unsupported non-file source path: ${join(rootPath, entryRelativePath)}`);
+		}
+	}
+	return output;
+}

package/src/first-party-catalog.ts

@@ -0,0 +1,44 @@
+import {
+	artifactProvisionName,
+	type FirstPartyHarnessArtifactCatalog,
+	type SkillHarnessArtifactEntry,
+} from "./artifact-catalog.ts";
+
+export const NS_FIRST_PARTY_HARNESS_ARTIFACT_CATALOG = {
+	type: "first-party-catalog",
+	catalogId: "ns-first-party",
+	artifacts: [
+		{
+			kind: "skill",
+			id: "objective-skill",
+			name: "Objective skill",
+			description: "Objective workflow grounding for ns Objective records.",
+			skillName: "objective",
+			source: {
+				type: "first-party",
+				packageName: "@nseng-ai/ns",
+				relativePath: "skills/objective",
+			},
+		},
+	],
+} as const satisfies FirstPartyHarnessArtifactCatalog;
+
+export type FirstPartySkillHarnessArtifact = Extract<
+	(typeof NS_FIRST_PARTY_HARNESS_ARTIFACT_CATALOG)["artifacts"][number],
+	SkillHarnessArtifactEntry
+>;
+
+export function listFirstPartySkillArtifacts(): readonly FirstPartySkillHarnessArtifact[] {
+	return NS_FIRST_PARTY_HARNESS_ARTIFACT_CATALOG.artifacts.filter(
+		(artifact) => artifact.kind === "skill",
+	);
+}
+
+export function findFirstPartySkillArtifact(
+	skill: string,
+): FirstPartySkillHarnessArtifact | undefined {
+	const normalized = skill.trim();
+	return listFirstPartySkillArtifacts().find(
+		(artifact) => artifact.id === normalized || artifactProvisionName(artifact) === normalized,
+	);
+}

package/src/first-party-skill-provisioning.ts

@@ -0,0 +1,162 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+
+import {
+	findFirstPartySkillArtifact,
+	listFirstPartySkillArtifacts,
+} from "./first-party-catalog.ts";
+import type { HarnessPathContext, HarnessPathEnvironment, HarnessScope } from "./harness-paths.ts";
+import {
+	applyPreparedProvision,
+	prepareProvision,
+	type HarnessArtifactFileSystemGateway,
+	type HarnessArtifactProvisionErrorInfo,
+} from "./provision-apply.ts";
+import type { ProvisionDecisionSet, ProvisionPlan } from "./provision-plan.ts";
+
+export const FIRST_PARTY_SKILL_CATALOG_SOURCE_VERSION = "static-catalog-v1";
+export const FIRST_PARTY_SKILL_CATALOG_SOURCE_UNAVAILABLE_MESSAGE =
+	"Could not locate the first-party ns skill catalog source root for provisioning.";
+
+export function resolveFirstPartyCatalogSourceRoot(): string | undefined {
+	let current = dirname(fileURLToPath(import.meta.url));
+	const sentinelPath = firstPartyCatalogSentinelPath();
+	if (sentinelPath === undefined) return undefined;
+	for (let index = 0; index < 12; index += 1) {
+		if (existsSync(join(current, sentinelPath))) return current;
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return undefined;
+}
+
+export interface ProvisionFirstPartySkillRequest {
+	skill: string;
+	harness: string;
+	scope: HarnessScope;
+	projectRoot: string;
+	homeDir?: string;
+	env: Record<string, string | undefined>;
+	isDryRun: boolean;
+	shouldForce: boolean;
+	/** Test seam: overrides the resolved first-party catalog source root. */
+	sourceRoot?: string;
+	/** Test seam: overrides the first-party catalog source version. */
+	sourceVersion?: string;
+	fs?: HarnessArtifactFileSystemGateway;
+}
+
+export type ProvisionFirstPartySkillOutcome =
+	| {
+			type: "provisioned";
+			mode: "dry-run" | "applied";
+			plan: ProvisionPlan;
+			decisions: ProvisionDecisionSet;
+			manifestPath: string;
+			writtenFiles: readonly string[];
+	  }
+	| {
+			type: "conflicted";
+			plan: ProvisionPlan;
+			decisions: ProvisionDecisionSet;
+			manifestPath: string;
+			conflictingFiles: readonly string[];
+	  }
+	| { type: "unknown-skill"; skill: string }
+	| { type: "catalog-source-unavailable"; message: string }
+	| { type: "error"; error: HarnessArtifactProvisionErrorInfo };
+
+/**
+ * Deep first-party skill provisioning operation: resolves the catalog source
+ * root, looks up the skill, prepares the provision once, and either previews
+ * (dry run) or applies it. Thin adapters (`ns skills install`, ns-init's
+ * `RealSkillMaterializer`) map these outcomes onto their own surfaces.
+ */
+export async function provisionFirstPartySkill(
+	request: ProvisionFirstPartySkillRequest,
+): Promise<ProvisionFirstPartySkillOutcome> {
+	const sourceRoot = request.sourceRoot ?? resolveFirstPartyCatalogSourceRoot();
+	if (sourceRoot === undefined) {
+		return {
+			type: "catalog-source-unavailable",
+			message: FIRST_PARTY_SKILL_CATALOG_SOURCE_UNAVAILABLE_MESSAGE,
+		};
+	}
+	const artifact = findFirstPartySkillArtifact(request.skill);
+	if (artifact === undefined) return { type: "unknown-skill", skill: request.skill };
+	const prepared = await prepareProvision({
+		artifact,
+		harness: request.harness,
+		scope: request.scope,
+		context: firstPartySkillProvisionPathContext({
+			projectRoot: request.projectRoot,
+			...optionalEntry("homeDir", request.homeDir),
+			env: request.env,
+		}),
+		sourceRoot,
+		sourceVersion: request.sourceVersion ?? FIRST_PARTY_SKILL_CATALOG_SOURCE_VERSION,
+		...optionalEntry("fs", request.fs),
+	});
+	if (!prepared.ok) return { type: "error", error: prepared.error };
+	if (request.isDryRun) {
+		return {
+			type: "provisioned",
+			mode: "dry-run",
+			plan: prepared.value.plan,
+			decisions: prepared.value.decisions,
+			manifestPath: prepared.value.manifestPath,
+			writtenFiles: [],
+		};
+	}
+	const applied = await applyPreparedProvision(prepared.value, {
+		shouldForce: request.shouldForce,
+	});
+	if (!applied.ok) return { type: "error", error: applied.error };
+	if (applied.value.outcome === "conflicted") {
+		return {
+			type: "conflicted",
+			plan: applied.value.plan,
+			decisions: applied.value.decisions,
+			manifestPath: applied.value.manifestPath,
+			conflictingFiles: applied.value.conflictingFiles,
+		};
+	}
+	return {
+		type: "provisioned",
+		mode: "applied",
+		plan: applied.value.plan,
+		decisions: applied.value.decisions,
+		manifestPath: applied.value.manifestPath,
+		writtenFiles: applied.value.writtenFiles,
+	};
+}
+
+export function firstPartySkillProvisionPathContext(input: {
+	projectRoot: string;
+	homeDir?: string;
+	env: Record<string, string | undefined>;
+}): HarnessPathContext {
+	return {
+		projectRoot: input.projectRoot,
+		...optionalEntry("homeDir", input.homeDir),
+		...optionalEntry("env", harnessPathEnvironment(input.env)),
+	};
+}
+
+function firstPartyCatalogSentinelPath(): string | undefined {
+	const artifact = listFirstPartySkillArtifacts()[0];
+	if (artifact === undefined) return undefined;
+	return join(artifact.source.relativePath, "SKILL.md");
+}
+
+function harnessPathEnvironment(
+	env: Record<string, string | undefined>,
+): HarnessPathEnvironment | undefined {
+	const claudeConfigDir = env.CLAUDE_CONFIG_DIR;
+	if (claudeConfigDir === undefined) return undefined;
+	return { CLAUDE_CONFIG_DIR: claudeConfigDir };
+}