@agimon-ai/po-domain 0.0.0-alpha.0

package/dist/pluginMaterializer-C8IZ1PSY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginMaterializer-C8IZ1PSY.cjs","names":["spawn","path","fs","poHomeDirectory","isRemotePluginSource","findPluginManifestPath"],"sources":["../src/services/pluginMaterializer/index.ts"],"sourcesContent":["import { spawn } from 'node:child_process';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport {\n  findPluginManifestPath,\n  type GitPluginSource,\n  isRemotePluginSource,\n  type NpmPluginSource,\n  type PluginEntry,\n  type PluginManifestMetadata,\n  type PluginSkillDiscovery,\n} from '@agimon-ai/po-config/domains';\nimport { poHomeDirectory } from '@agimon-ai/po-core/piSettings';\n\nconst AGENT_PLUGIN_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';\nconst INSTALL_MARKER = '.po-plugin.json';\nconst INSTALL_MARKER_VERSION = 1;\nconst OUTPUT_LIMIT = 64 * 1024;\n/** The staging project that declares the one npm plugin being installed. */\nconst STAGING_PACKAGE_NAME = 'po-plugin-staging';\nconst LATEST_TAG = 'latest';\n\ninterface CommandOptions {\n  cwd?: string;\n  environment?: NodeJS.ProcessEnv;\n}\n\ninterface InstallMarker {\n  version: number;\n  source: GitPluginSource | NpmPluginSource;\n}\n\ninterface InspectedPluginManifest {\n  skillDiscovery: PluginSkillDiscovery;\n  manifest: PluginManifestMetadata;\n}\n\nexport interface PluginSourceMaterializers {\n  git: (source: GitPluginSource, workspace: string) => Promise<string>;\n  npm: (source: NpmPluginSource, workspace: string) => Promise<string>;\n}\n\nexport interface PluginMaterializerOptions {\n  materializers?: Partial<PluginSourceMaterializers>;\n}\n\nfunction appendOutput(current: string, chunk: Buffer): string {\n  const next = current + chunk.toString('utf8');\n  return next.length <= OUTPUT_LIMIT ? next : next.slice(-OUTPUT_LIMIT);\n}\n\nfunction runCommand(command: string, args: string[], options: CommandOptions = {}): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = spawn(command, args, {\n      cwd: options.cwd,\n      env: options.environment ?? process.env,\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n    let stdout = '';\n    let stderr = '';\n    child.stdout.on('data', (chunk: Buffer) => {\n      stdout = appendOutput(stdout, chunk);\n    });\n    child.stderr.on('data', (chunk: Buffer) => {\n      stderr = appendOutput(stderr, chunk);\n    });\n    child.once('error', (error) => {\n      reject(new Error(`Failed to run ${command}: ${error.message}`, { cause: error }));\n    });\n    child.once('close', (code, signal) => {\n      if (code === 0) {\n        resolve(stdout.trim());\n        return;\n      }\n      const outcome = signal ? `signal ${signal}` : `exit code ${code ?? 'unknown'}`;\n      const details = stderr.trim() || stdout.trim();\n      reject(new Error(`${command} ${args.join(' ')} failed with ${outcome}${details ? `\\n${details}` : ''}`));\n    });\n  });\n}\n\nfunction assertContained(root: string, candidate: string, label: string): void {\n  const relative = path.relative(root, candidate);\n  if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) return;\n  throw new Error(`${label} resolves outside ${root}`);\n}\n\nasync function materializeGitSource(source: GitPluginSource, workspace: string): Promise<string> {\n  const checkout = path.join(workspace, 'checkout');\n  const pluginRoot = source.path ? path.resolve(checkout, source.path) : checkout;\n  if (source.path) assertContained(checkout, pluginRoot, 'Git plugin path');\n  const cloneArgs = ['clone', '--filter=blob:none'];\n  if (source.path) cloneArgs.push('--sparse', '--no-checkout');\n  cloneArgs.push(source.url, checkout);\n  const environment = { ...process.env, GIT_TERMINAL_PROMPT: '0' };\n  await runCommand('git', cloneArgs, { environment });\n\n  if (source.path) {\n    await runCommand('git', ['sparse-checkout', 'set', '--no-cone', '--', source.path], {\n      cwd: checkout,\n      environment,\n    });\n  }\n  if (source.sha) {\n    await runCommand('git', ['checkout', source.sha], { cwd: checkout, environment });\n    const checkedOutSha = await runCommand('git', ['rev-parse', 'HEAD'], { cwd: checkout, environment });\n    if (checkedOutSha.toLowerCase() !== source.sha.toLowerCase()) {\n      throw new Error(`Checked out Git SHA ${checkedOutSha} does not match requested SHA ${source.sha}`);\n    }\n  } else if (source.ref) {\n    await runCommand('git', ['checkout', source.ref], { cwd: checkout, environment });\n  } else if (source.path) {\n    await runCommand('git', ['checkout'], { cwd: checkout, environment });\n  }\n\n  return pluginRoot;\n}\n\n/**\n * Installs an npm plugin into the staging workspace with upm: a one-dependency\n * project, never a spawned package manager. upm runs no lifecycle scripts, and\n * its store is Po's shared `<po home>/store`.\n */\nasync function materializeNpmSource(source: NpmPluginSource, workspace: string): Promise<string> {\n  const prefix = path.join(workspace, 'npm');\n  await fs.promises.mkdir(prefix, { recursive: true });\n  await fs.promises.writeFile(\n    path.join(prefix, 'package.json'),\n    `${JSON.stringify(\n      { name: STAGING_PACKAGE_NAME, private: true, dependencies: { [source.package]: source.version ?? LATEST_TAG } },\n      null,\n      2,\n    )}\\n`,\n  );\n  // Loaded on demand so upm stays off the path of every plugin that is already cached.\n  const { installRuntimePackages } = await import('@agimon-ai/po-core/runtimePackages');\n  await installRuntimePackages({\n    dir: prefix,\n    poHome: poHomeDirectory(),\n    ...(source.registry ? { registry: source.registry } : {}),\n  });\n  const pluginRoot = path.resolve(prefix, 'node_modules', ...source.package.split('/'));\n  assertContained(path.join(prefix, 'node_modules'), pluginRoot, 'npm plugin package');\n  // upm links each package into node_modules; the copy reads the linked directory.\n  return fs.promises.realpath(pluginRoot);\n}\n\nconst DEFAULT_MATERIALIZERS: PluginSourceMaterializers = {\n  git: materializeGitSource,\n  npm: materializeNpmSource,\n};\n\nasync function pathType(target: string): Promise<'directory' | 'missing' | 'other'> {\n  try {\n    const stat = await fs.promises.lstat(target);\n    return stat.isDirectory() ? 'directory' : 'other';\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n}\n\nfunction optionalManifestString(manifest: Record<string, unknown>, key: string): string | undefined {\n  const value = manifest[key];\n  return typeof value === 'string' && value.trim() ? value.trim() : undefined;\n}\n\nfunction validatePluginManifest(pluginRoot: string, manifestPath: string): InspectedPluginManifest {\n  try {\n    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as unknown;\n    if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {\n      throw new Error('manifest must contain a JSON object');\n    }\n    const record = manifest as Record<string, unknown>;\n    const agentPluginSchema =\n      manifestPath === path.join(pluginRoot, 'plugin.json') && record.$schema === AGENT_PLUGIN_SCHEMA\n        ? AGENT_PLUGIN_SCHEMA\n        : undefined;\n    const name = optionalManifestString(record, 'name');\n    const version = optionalManifestString(record, 'version');\n    const description = optionalManifestString(record, 'description');\n    return {\n      skillDiscovery: agentPluginSchema ? 'direct-children' : 'recursive',\n      manifest: {\n        path: manifestPath,\n        ...(name ? { name } : {}),\n        ...(version ? { version } : {}),\n        ...(description ? { description } : {}),\n        ...(agentPluginSchema ? { agentPluginSchema } : {}),\n      },\n    };\n  } catch (error) {\n    throw new Error(\n      `Invalid plugin manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`,\n      {\n        cause: error,\n      },\n    );\n  }\n}\n\nasync function inspectInstallation(entry: PluginEntry): Promise<InspectedPluginManifest | false> {\n  const type = await pathType(entry.directory);\n  if (type === 'missing') return false;\n  if (type !== 'directory') throw new Error(`Remote plugin cache path is not a directory: ${entry.directory}`);\n  if (!entry.source || !isRemotePluginSource(entry.source)) {\n    throw new Error(`Remote plugin entry is missing its source: ${entry.name ?? entry.directory}`);\n  }\n\n  let marker: InstallMarker;\n  try {\n    marker = JSON.parse(\n      await fs.promises.readFile(path.join(entry.directory, INSTALL_MARKER), 'utf8'),\n    ) as InstallMarker;\n  } catch (error) {\n    throw new Error(`Remote plugin cache is not managed by Po: ${entry.directory}`, { cause: error });\n  }\n  if (marker.version !== INSTALL_MARKER_VERSION || JSON.stringify(marker.source) !== JSON.stringify(entry.source)) {\n    throw new Error(`Remote plugin cache metadata does not match ${entry.name ?? entry.directory}: ${entry.directory}`);\n  }\n  const manifestPath = findPluginManifestPath(entry.directory);\n  if (!manifestPath) {\n    throw new Error(`Remote plugin cache is missing a supported plugin manifest: ${entry.directory}`);\n  }\n  return validatePluginManifest(entry.directory, manifestPath);\n}\n\nasync function copyPluginSource(sourceRoot: string, destination: string): Promise<void> {\n  if ((await pathType(sourceRoot)) !== 'directory') {\n    throw new Error(`Materialized plugin source is not a directory: ${sourceRoot}`);\n  }\n  await fs.promises.cp(sourceRoot, destination, {\n    recursive: true,\n    filter: (candidate) => path.basename(candidate) !== '.git',\n  });\n}\n\nfunction isRenameRace(error: unknown): boolean {\n  const code = (error as NodeJS.ErrnoException).code;\n  return code === 'EEXIST' || code === 'ENOTEMPTY';\n}\n\nasync function installRemotePlugin(entry: PluginEntry, materializers: PluginSourceMaterializers): Promise<PluginEntry> {\n  if (!entry.source || !isRemotePluginSource(entry.source)) return entry;\n  const existingManifest = await inspectInstallation(entry);\n  if (existingManifest) return { ...entry, ...existingManifest };\n\n  const parent = path.dirname(entry.directory);\n  await fs.promises.mkdir(parent, { recursive: true, mode: 0o700 });\n  if ((await pathType(parent)) !== 'directory') {\n    throw new Error(`Remote plugin cache root is not a directory: ${parent}`);\n  }\n  await fs.promises.chmod(parent, 0o700);\n  const workspace = await fs.promises.mkdtemp(path.join(parent, '.plugin-staging-'));\n  const installation = path.join(workspace, 'installation');\n  try {\n    const sourceRoot =\n      entry.source.type === 'git'\n        ? await materializers.git(entry.source, workspace)\n        : await materializers.npm(entry.source, workspace);\n    await copyPluginSource(sourceRoot, installation);\n    const manifestPath = findPluginManifestPath(installation);\n    if (!manifestPath) {\n      throw new Error(`Remote plugin ${entry.name ?? entry.directory} does not contain a supported plugin manifest`);\n    }\n    validatePluginManifest(installation, manifestPath);\n    const markerPath = path.join(installation, INSTALL_MARKER);\n    if ((await pathType(markerPath)) !== 'missing') {\n      throw new Error(`Remote plugin contains reserved cache metadata path: ${INSTALL_MARKER}`);\n    }\n    const marker: InstallMarker = { version: INSTALL_MARKER_VERSION, source: entry.source };\n    await fs.promises.writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\\n`, {\n      flag: 'wx',\n      mode: 0o600,\n    });\n    try {\n      await fs.promises.rename(installation, entry.directory);\n    } catch (error) {\n      if (!isRenameRace(error)) throw error;\n      await fs.promises.rm(installation, { recursive: true, force: true });\n      const racedManifest = await inspectInstallation(entry);\n      if (!racedManifest) throw new Error(`Remote plugin installation race left no cache: ${entry.directory}`);\n      return { ...entry, ...racedManifest };\n    }\n    const installedManifest = await inspectInstallation(entry);\n    if (!installedManifest) throw new Error(`Remote plugin installation left no cache: ${entry.directory}`);\n    return { ...entry, ...installedManifest };\n  } catch (error) {\n    throw new Error(\n      `Failed to install remote plugin ${entry.name ?? entry.directory}: ${error instanceof Error ? error.message : String(error)}`,\n      {\n        cause: error,\n      },\n    );\n  } finally {\n    await fs.promises.rm(workspace, { recursive: true, force: true });\n  }\n}\n\n/** Downloads selected remote plugins once into their content-addressed cache directories. */\nexport async function materializePluginEntries(\n  entries: readonly PluginEntry[],\n  options: PluginMaterializerOptions = {},\n): Promise<PluginEntry[]> {\n  const materializers: PluginSourceMaterializers = {\n    git: options.materializers?.git ?? DEFAULT_MATERIALIZERS.git,\n    npm: options.materializers?.npm ?? DEFAULT_MATERIALIZERS.npm,\n  };\n  return Promise.all(entries.map((entry) => installRemotePlugin(entry, materializers)));\n}\n"],"mappings":"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"}

package/dist/pluginMaterializer-D9-oDF-b.mjs

@@ -0,0 +1,259 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findPluginManifestPath, isRemotePluginSource } from "@agimon-ai/po-config/domains";
+import { spawn } from "node:child_process";
+import { poHomeDirectory } from "@agimon-ai/po-core/piSettings";
+//#region src/services/pluginMaterializer/index.ts
+const AGENT_PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+const INSTALL_MARKER = ".po-plugin.json";
+const INSTALL_MARKER_VERSION = 1;
+const OUTPUT_LIMIT = 65536;
+/** The staging project that declares the one npm plugin being installed. */
+const STAGING_PACKAGE_NAME = "po-plugin-staging";
+const LATEST_TAG = "latest";
+function appendOutput(current, chunk) {
+	const next = current + chunk.toString("utf8");
+	return next.length <= OUTPUT_LIMIT ? next : next.slice(-65536);
+}
+function runCommand(command, args, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			env: options.environment ?? process.env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			stdout = appendOutput(stdout, chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr = appendOutput(stderr, chunk);
+		});
+		child.once("error", (error) => {
+			reject(new Error(`Failed to run ${command}: ${error.message}`, { cause: error }));
+		});
+		child.once("close", (code, signal) => {
+			if (code === 0) {
+				resolve(stdout.trim());
+				return;
+			}
+			const outcome = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+			const details = stderr.trim() || stdout.trim();
+			reject(/* @__PURE__ */ new Error(`${command} ${args.join(" ")} failed with ${outcome}${details ? `\n${details}` : ""}`));
+		});
+	});
+}
+function assertContained(root, candidate, label) {
+	const relative = path.relative(root, candidate);
+	if (relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative)) return;
+	throw new Error(`${label} resolves outside ${root}`);
+}
+async function materializeGitSource(source, workspace) {
+	const checkout = path.join(workspace, "checkout");
+	const pluginRoot = source.path ? path.resolve(checkout, source.path) : checkout;
+	if (source.path) assertContained(checkout, pluginRoot, "Git plugin path");
+	const cloneArgs = ["clone", "--filter=blob:none"];
+	if (source.path) cloneArgs.push("--sparse", "--no-checkout");
+	cloneArgs.push(source.url, checkout);
+	const environment = {
+		...process.env,
+		GIT_TERMINAL_PROMPT: "0"
+	};
+	await runCommand("git", cloneArgs, { environment });
+	if (source.path) await runCommand("git", [
+		"sparse-checkout",
+		"set",
+		"--no-cone",
+		"--",
+		source.path
+	], {
+		cwd: checkout,
+		environment
+	});
+	if (source.sha) {
+		await runCommand("git", ["checkout", source.sha], {
+			cwd: checkout,
+			environment
+		});
+		const checkedOutSha = await runCommand("git", ["rev-parse", "HEAD"], {
+			cwd: checkout,
+			environment
+		});
+		if (checkedOutSha.toLowerCase() !== source.sha.toLowerCase()) throw new Error(`Checked out Git SHA ${checkedOutSha} does not match requested SHA ${source.sha}`);
+	} else if (source.ref) await runCommand("git", ["checkout", source.ref], {
+		cwd: checkout,
+		environment
+	});
+	else if (source.path) await runCommand("git", ["checkout"], {
+		cwd: checkout,
+		environment
+	});
+	return pluginRoot;
+}
+/**
+* Installs an npm plugin into the staging workspace with upm: a one-dependency
+* project, never a spawned package manager. upm runs no lifecycle scripts, and
+* its store is Po's shared `<po home>/store`.
+*/
+async function materializeNpmSource(source, workspace) {
+	const prefix = path.join(workspace, "npm");
+	await fs.promises.mkdir(prefix, { recursive: true });
+	await fs.promises.writeFile(path.join(prefix, "package.json"), `${JSON.stringify({
+		name: STAGING_PACKAGE_NAME,
+		private: true,
+		dependencies: { [source.package]: source.version ?? LATEST_TAG }
+	}, null, 2)}\n`);
+	const { installRuntimePackages } = await import("@agimon-ai/po-core/runtimePackages");
+	await installRuntimePackages({
+		dir: prefix,
+		poHome: poHomeDirectory(),
+		...source.registry ? { registry: source.registry } : {}
+	});
+	const pluginRoot = path.resolve(prefix, "node_modules", ...source.package.split("/"));
+	assertContained(path.join(prefix, "node_modules"), pluginRoot, "npm plugin package");
+	return fs.promises.realpath(pluginRoot);
+}
+const DEFAULT_MATERIALIZERS = {
+	git: materializeGitSource,
+	npm: materializeNpmSource
+};
+async function pathType(target) {
+	try {
+		return (await fs.promises.lstat(target)).isDirectory() ? "directory" : "other";
+	} catch (error) {
+		if (error.code === "ENOENT") return "missing";
+		throw error;
+	}
+}
+function optionalManifestString(manifest, key) {
+	const value = manifest[key];
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function validatePluginManifest(pluginRoot, manifestPath) {
+	try {
+		const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+		if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) throw new Error("manifest must contain a JSON object");
+		const record = manifest;
+		const agentPluginSchema = manifestPath === path.join(pluginRoot, "plugin.json") && record.$schema === AGENT_PLUGIN_SCHEMA ? AGENT_PLUGIN_SCHEMA : void 0;
+		const name = optionalManifestString(record, "name");
+		const version = optionalManifestString(record, "version");
+		const description = optionalManifestString(record, "description");
+		return {
+			skillDiscovery: agentPluginSchema ? "direct-children" : "recursive",
+			manifest: {
+				path: manifestPath,
+				...name ? { name } : {},
+				...version ? { version } : {},
+				...description ? { description } : {},
+				...agentPluginSchema ? { agentPluginSchema } : {}
+			}
+		};
+	} catch (error) {
+		throw new Error(`Invalid plugin manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+async function inspectInstallation(entry) {
+	const type = await pathType(entry.directory);
+	if (type === "missing") return false;
+	if (type !== "directory") throw new Error(`Remote plugin cache path is not a directory: ${entry.directory}`);
+	if (!entry.source || !isRemotePluginSource(entry.source)) throw new Error(`Remote plugin entry is missing its source: ${entry.name ?? entry.directory}`);
+	let marker;
+	try {
+		marker = JSON.parse(await fs.promises.readFile(path.join(entry.directory, INSTALL_MARKER), "utf8"));
+	} catch (error) {
+		throw new Error(`Remote plugin cache is not managed by Po: ${entry.directory}`, { cause: error });
+	}
+	if (marker.version !== INSTALL_MARKER_VERSION || JSON.stringify(marker.source) !== JSON.stringify(entry.source)) throw new Error(`Remote plugin cache metadata does not match ${entry.name ?? entry.directory}: ${entry.directory}`);
+	const manifestPath = findPluginManifestPath(entry.directory);
+	if (!manifestPath) throw new Error(`Remote plugin cache is missing a supported plugin manifest: ${entry.directory}`);
+	return validatePluginManifest(entry.directory, manifestPath);
+}
+async function copyPluginSource(sourceRoot, destination) {
+	if (await pathType(sourceRoot) !== "directory") throw new Error(`Materialized plugin source is not a directory: ${sourceRoot}`);
+	await fs.promises.cp(sourceRoot, destination, {
+		recursive: true,
+		filter: (candidate) => path.basename(candidate) !== ".git"
+	});
+}
+function isRenameRace(error) {
+	const code = error.code;
+	return code === "EEXIST" || code === "ENOTEMPTY";
+}
+async function installRemotePlugin(entry, materializers) {
+	if (!entry.source || !isRemotePluginSource(entry.source)) return entry;
+	const existingManifest = await inspectInstallation(entry);
+	if (existingManifest) return {
+		...entry,
+		...existingManifest
+	};
+	const parent = path.dirname(entry.directory);
+	await fs.promises.mkdir(parent, {
+		recursive: true,
+		mode: 448
+	});
+	if (await pathType(parent) !== "directory") throw new Error(`Remote plugin cache root is not a directory: ${parent}`);
+	await fs.promises.chmod(parent, 448);
+	const workspace = await fs.promises.mkdtemp(path.join(parent, ".plugin-staging-"));
+	const installation = path.join(workspace, "installation");
+	try {
+		await copyPluginSource(entry.source.type === "git" ? await materializers.git(entry.source, workspace) : await materializers.npm(entry.source, workspace), installation);
+		const manifestPath = findPluginManifestPath(installation);
+		if (!manifestPath) throw new Error(`Remote plugin ${entry.name ?? entry.directory} does not contain a supported plugin manifest`);
+		validatePluginManifest(installation, manifestPath);
+		const markerPath = path.join(installation, INSTALL_MARKER);
+		if (await pathType(markerPath) !== "missing") throw new Error(`Remote plugin contains reserved cache metadata path: ${INSTALL_MARKER}`);
+		const marker = {
+			version: INSTALL_MARKER_VERSION,
+			source: entry.source
+		};
+		await fs.promises.writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+		try {
+			await fs.promises.rename(installation, entry.directory);
+		} catch (error) {
+			if (!isRenameRace(error)) throw error;
+			await fs.promises.rm(installation, {
+				recursive: true,
+				force: true
+			});
+			const racedManifest = await inspectInstallation(entry);
+			if (!racedManifest) throw new Error(`Remote plugin installation race left no cache: ${entry.directory}`);
+			return {
+				...entry,
+				...racedManifest
+			};
+		}
+		const installedManifest = await inspectInstallation(entry);
+		if (!installedManifest) throw new Error(`Remote plugin installation left no cache: ${entry.directory}`);
+		return {
+			...entry,
+			...installedManifest
+		};
+	} catch (error) {
+		throw new Error(`Failed to install remote plugin ${entry.name ?? entry.directory}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	} finally {
+		await fs.promises.rm(workspace, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Downloads selected remote plugins once into their content-addressed cache directories. */
+async function materializePluginEntries(entries, options = {}) {
+	const materializers = {
+		git: options.materializers?.git ?? DEFAULT_MATERIALIZERS.git,
+		npm: options.materializers?.npm ?? DEFAULT_MATERIALIZERS.npm
+	};
+	return Promise.all(entries.map((entry) => installRemotePlugin(entry, materializers)));
+}
+//#endregion
+export { materializePluginEntries as t };
+
+//# sourceMappingURL=pluginMaterializer-D9-oDF-b.mjs.map

package/dist/pluginMaterializer-D9-oDF-b.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginMaterializer-D9-oDF-b.mjs","names":[],"sources":["../src/services/pluginMaterializer/index.ts"],"sourcesContent":["import { spawn } from 'node:child_process';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport {\n  findPluginManifestPath,\n  type GitPluginSource,\n  isRemotePluginSource,\n  type NpmPluginSource,\n  type PluginEntry,\n  type PluginManifestMetadata,\n  type PluginSkillDiscovery,\n} from '@agimon-ai/po-config/domains';\nimport { poHomeDirectory } from '@agimon-ai/po-core/piSettings';\n\nconst AGENT_PLUGIN_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';\nconst INSTALL_MARKER = '.po-plugin.json';\nconst INSTALL_MARKER_VERSION = 1;\nconst OUTPUT_LIMIT = 64 * 1024;\n/** The staging project that declares the one npm plugin being installed. */\nconst STAGING_PACKAGE_NAME = 'po-plugin-staging';\nconst LATEST_TAG = 'latest';\n\ninterface CommandOptions {\n  cwd?: string;\n  environment?: NodeJS.ProcessEnv;\n}\n\ninterface InstallMarker {\n  version: number;\n  source: GitPluginSource | NpmPluginSource;\n}\n\ninterface InspectedPluginManifest {\n  skillDiscovery: PluginSkillDiscovery;\n  manifest: PluginManifestMetadata;\n}\n\nexport interface PluginSourceMaterializers {\n  git: (source: GitPluginSource, workspace: string) => Promise<string>;\n  npm: (source: NpmPluginSource, workspace: string) => Promise<string>;\n}\n\nexport interface PluginMaterializerOptions {\n  materializers?: Partial<PluginSourceMaterializers>;\n}\n\nfunction appendOutput(current: string, chunk: Buffer): string {\n  const next = current + chunk.toString('utf8');\n  return next.length <= OUTPUT_LIMIT ? next : next.slice(-OUTPUT_LIMIT);\n}\n\nfunction runCommand(command: string, args: string[], options: CommandOptions = {}): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = spawn(command, args, {\n      cwd: options.cwd,\n      env: options.environment ?? process.env,\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n    let stdout = '';\n    let stderr = '';\n    child.stdout.on('data', (chunk: Buffer) => {\n      stdout = appendOutput(stdout, chunk);\n    });\n    child.stderr.on('data', (chunk: Buffer) => {\n      stderr = appendOutput(stderr, chunk);\n    });\n    child.once('error', (error) => {\n      reject(new Error(`Failed to run ${command}: ${error.message}`, { cause: error }));\n    });\n    child.once('close', (code, signal) => {\n      if (code === 0) {\n        resolve(stdout.trim());\n        return;\n      }\n      const outcome = signal ? `signal ${signal}` : `exit code ${code ?? 'unknown'}`;\n      const details = stderr.trim() || stdout.trim();\n      reject(new Error(`${command} ${args.join(' ')} failed with ${outcome}${details ? `\\n${details}` : ''}`));\n    });\n  });\n}\n\nfunction assertContained(root: string, candidate: string, label: string): void {\n  const relative = path.relative(root, candidate);\n  if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) return;\n  throw new Error(`${label} resolves outside ${root}`);\n}\n\nasync function materializeGitSource(source: GitPluginSource, workspace: string): Promise<string> {\n  const checkout = path.join(workspace, 'checkout');\n  const pluginRoot = source.path ? path.resolve(checkout, source.path) : checkout;\n  if (source.path) assertContained(checkout, pluginRoot, 'Git plugin path');\n  const cloneArgs = ['clone', '--filter=blob:none'];\n  if (source.path) cloneArgs.push('--sparse', '--no-checkout');\n  cloneArgs.push(source.url, checkout);\n  const environment = { ...process.env, GIT_TERMINAL_PROMPT: '0' };\n  await runCommand('git', cloneArgs, { environment });\n\n  if (source.path) {\n    await runCommand('git', ['sparse-checkout', 'set', '--no-cone', '--', source.path], {\n      cwd: checkout,\n      environment,\n    });\n  }\n  if (source.sha) {\n    await runCommand('git', ['checkout', source.sha], { cwd: checkout, environment });\n    const checkedOutSha = await runCommand('git', ['rev-parse', 'HEAD'], { cwd: checkout, environment });\n    if (checkedOutSha.toLowerCase() !== source.sha.toLowerCase()) {\n      throw new Error(`Checked out Git SHA ${checkedOutSha} does not match requested SHA ${source.sha}`);\n    }\n  } else if (source.ref) {\n    await runCommand('git', ['checkout', source.ref], { cwd: checkout, environment });\n  } else if (source.path) {\n    await runCommand('git', ['checkout'], { cwd: checkout, environment });\n  }\n\n  return pluginRoot;\n}\n\n/**\n * Installs an npm plugin into the staging workspace with upm: a one-dependency\n * project, never a spawned package manager. upm runs no lifecycle scripts, and\n * its store is Po's shared `<po home>/store`.\n */\nasync function materializeNpmSource(source: NpmPluginSource, workspace: string): Promise<string> {\n  const prefix = path.join(workspace, 'npm');\n  await fs.promises.mkdir(prefix, { recursive: true });\n  await fs.promises.writeFile(\n    path.join(prefix, 'package.json'),\n    `${JSON.stringify(\n      { name: STAGING_PACKAGE_NAME, private: true, dependencies: { [source.package]: source.version ?? LATEST_TAG } },\n      null,\n      2,\n    )}\\n`,\n  );\n  // Loaded on demand so upm stays off the path of every plugin that is already cached.\n  const { installRuntimePackages } = await import('@agimon-ai/po-core/runtimePackages');\n  await installRuntimePackages({\n    dir: prefix,\n    poHome: poHomeDirectory(),\n    ...(source.registry ? { registry: source.registry } : {}),\n  });\n  const pluginRoot = path.resolve(prefix, 'node_modules', ...source.package.split('/'));\n  assertContained(path.join(prefix, 'node_modules'), pluginRoot, 'npm plugin package');\n  // upm links each package into node_modules; the copy reads the linked directory.\n  return fs.promises.realpath(pluginRoot);\n}\n\nconst DEFAULT_MATERIALIZERS: PluginSourceMaterializers = {\n  git: materializeGitSource,\n  npm: materializeNpmSource,\n};\n\nasync function pathType(target: string): Promise<'directory' | 'missing' | 'other'> {\n  try {\n    const stat = await fs.promises.lstat(target);\n    return stat.isDirectory() ? 'directory' : 'other';\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n}\n\nfunction optionalManifestString(manifest: Record<string, unknown>, key: string): string | undefined {\n  const value = manifest[key];\n  return typeof value === 'string' && value.trim() ? value.trim() : undefined;\n}\n\nfunction validatePluginManifest(pluginRoot: string, manifestPath: string): InspectedPluginManifest {\n  try {\n    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as unknown;\n    if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {\n      throw new Error('manifest must contain a JSON object');\n    }\n    const record = manifest as Record<string, unknown>;\n    const agentPluginSchema =\n      manifestPath === path.join(pluginRoot, 'plugin.json') && record.$schema === AGENT_PLUGIN_SCHEMA\n        ? AGENT_PLUGIN_SCHEMA\n        : undefined;\n    const name = optionalManifestString(record, 'name');\n    const version = optionalManifestString(record, 'version');\n    const description = optionalManifestString(record, 'description');\n    return {\n      skillDiscovery: agentPluginSchema ? 'direct-children' : 'recursive',\n      manifest: {\n        path: manifestPath,\n        ...(name ? { name } : {}),\n        ...(version ? { version } : {}),\n        ...(description ? { description } : {}),\n        ...(agentPluginSchema ? { agentPluginSchema } : {}),\n      },\n    };\n  } catch (error) {\n    throw new Error(\n      `Invalid plugin manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`,\n      {\n        cause: error,\n      },\n    );\n  }\n}\n\nasync function inspectInstallation(entry: PluginEntry): Promise<InspectedPluginManifest | false> {\n  const type = await pathType(entry.directory);\n  if (type === 'missing') return false;\n  if (type !== 'directory') throw new Error(`Remote plugin cache path is not a directory: ${entry.directory}`);\n  if (!entry.source || !isRemotePluginSource(entry.source)) {\n    throw new Error(`Remote plugin entry is missing its source: ${entry.name ?? entry.directory}`);\n  }\n\n  let marker: InstallMarker;\n  try {\n    marker = JSON.parse(\n      await fs.promises.readFile(path.join(entry.directory, INSTALL_MARKER), 'utf8'),\n    ) as InstallMarker;\n  } catch (error) {\n    throw new Error(`Remote plugin cache is not managed by Po: ${entry.directory}`, { cause: error });\n  }\n  if (marker.version !== INSTALL_MARKER_VERSION || JSON.stringify(marker.source) !== JSON.stringify(entry.source)) {\n    throw new Error(`Remote plugin cache metadata does not match ${entry.name ?? entry.directory}: ${entry.directory}`);\n  }\n  const manifestPath = findPluginManifestPath(entry.directory);\n  if (!manifestPath) {\n    throw new Error(`Remote plugin cache is missing a supported plugin manifest: ${entry.directory}`);\n  }\n  return validatePluginManifest(entry.directory, manifestPath);\n}\n\nasync function copyPluginSource(sourceRoot: string, destination: string): Promise<void> {\n  if ((await pathType(sourceRoot)) !== 'directory') {\n    throw new Error(`Materialized plugin source is not a directory: ${sourceRoot}`);\n  }\n  await fs.promises.cp(sourceRoot, destination, {\n    recursive: true,\n    filter: (candidate) => path.basename(candidate) !== '.git',\n  });\n}\n\nfunction isRenameRace(error: unknown): boolean {\n  const code = (error as NodeJS.ErrnoException).code;\n  return code === 'EEXIST' || code === 'ENOTEMPTY';\n}\n\nasync function installRemotePlugin(entry: PluginEntry, materializers: PluginSourceMaterializers): Promise<PluginEntry> {\n  if (!entry.source || !isRemotePluginSource(entry.source)) return entry;\n  const existingManifest = await inspectInstallation(entry);\n  if (existingManifest) return { ...entry, ...existingManifest };\n\n  const parent = path.dirname(entry.directory);\n  await fs.promises.mkdir(parent, { recursive: true, mode: 0o700 });\n  if ((await pathType(parent)) !== 'directory') {\n    throw new Error(`Remote plugin cache root is not a directory: ${parent}`);\n  }\n  await fs.promises.chmod(parent, 0o700);\n  const workspace = await fs.promises.mkdtemp(path.join(parent, '.plugin-staging-'));\n  const installation = path.join(workspace, 'installation');\n  try {\n    const sourceRoot =\n      entry.source.type === 'git'\n        ? await materializers.git(entry.source, workspace)\n        : await materializers.npm(entry.source, workspace);\n    await copyPluginSource(sourceRoot, installation);\n    const manifestPath = findPluginManifestPath(installation);\n    if (!manifestPath) {\n      throw new Error(`Remote plugin ${entry.name ?? entry.directory} does not contain a supported plugin manifest`);\n    }\n    validatePluginManifest(installation, manifestPath);\n    const markerPath = path.join(installation, INSTALL_MARKER);\n    if ((await pathType(markerPath)) !== 'missing') {\n      throw new Error(`Remote plugin contains reserved cache metadata path: ${INSTALL_MARKER}`);\n    }\n    const marker: InstallMarker = { version: INSTALL_MARKER_VERSION, source: entry.source };\n    await fs.promises.writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\\n`, {\n      flag: 'wx',\n      mode: 0o600,\n    });\n    try {\n      await fs.promises.rename(installation, entry.directory);\n    } catch (error) {\n      if (!isRenameRace(error)) throw error;\n      await fs.promises.rm(installation, { recursive: true, force: true });\n      const racedManifest = await inspectInstallation(entry);\n      if (!racedManifest) throw new Error(`Remote plugin installation race left no cache: ${entry.directory}`);\n      return { ...entry, ...racedManifest };\n    }\n    const installedManifest = await inspectInstallation(entry);\n    if (!installedManifest) throw new Error(`Remote plugin installation left no cache: ${entry.directory}`);\n    return { ...entry, ...installedManifest };\n  } catch (error) {\n    throw new Error(\n      `Failed to install remote plugin ${entry.name ?? entry.directory}: ${error instanceof Error ? error.message : String(error)}`,\n      {\n        cause: error,\n      },\n    );\n  } finally {\n    await fs.promises.rm(workspace, { recursive: true, force: true });\n  }\n}\n\n/** Downloads selected remote plugins once into their content-addressed cache directories. */\nexport async function materializePluginEntries(\n  entries: readonly PluginEntry[],\n  options: PluginMaterializerOptions = {},\n): Promise<PluginEntry[]> {\n  const materializers: PluginSourceMaterializers = {\n    git: options.materializers?.git ?? DEFAULT_MATERIALIZERS.git,\n    npm: options.materializers?.npm ?? DEFAULT_MATERIALIZERS.npm,\n  };\n  return Promise.all(entries.map((entry) => installRemotePlugin(entry, materializers)));\n}\n"],"mappings":"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"}

package/dist/plugins.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_pluginMaterializer = require("./pluginMaterializer-C8IZ1PSY.cjs");
+exports.materializePluginEntries = require_pluginMaterializer.materializePluginEntries;

package/dist/plugins.d.mts

@@ -0,0 +1,14 @@
+import { GitPluginSource, NpmPluginSource, PluginEntry } from "@agimon-ai/po-config/domains";
+//#region src/services/pluginMaterializer/index.d.ts
+interface PluginSourceMaterializers {
+  git: (source: GitPluginSource, workspace: string) => Promise<string>;
+  npm: (source: NpmPluginSource, workspace: string) => Promise<string>;
+}
+interface PluginMaterializerOptions {
+  materializers?: Partial<PluginSourceMaterializers>;
+}
+/** Downloads selected remote plugins once into their content-addressed cache directories. */
+export declare function materializePluginEntries(entries: readonly PluginEntry[], options?: PluginMaterializerOptions): Promise<PluginEntry[]>;
+//#endregion
+export type { PluginMaterializerOptions, PluginSourceMaterializers };
+//# sourceMappingURL=plugins.d.mts.map

package/dist/plugins.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.mts","names":[],"sources":["../src/services/pluginMaterializer/index.ts"],"mappings":";;UAsCiB;EACf,MAAM,QAAQ,iBAAiB,sBAAsB;EACrD,MAAM,QAAQ,iBAAiB,sBAAsB;;UAGtC;EACf,gBAAgB,QAAQ;;;wBAiQJ,yBACpB,kBAAkB,eAClB,UAAS,4BACR,QAAQ"}

package/dist/plugins.mjs

@@ -0,0 +1,2 @@
+import { t as materializePluginEntries } from "./pluginMaterializer-D9-oDF-b.mjs";
+export { materializePluginEntries };