@evo-dev/core 0.0.1-alpha

package/src/pack/index.ts

@@ -0,0 +1,779 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { type ProtectedZoneFinding, checkProtectedZonePaths } from "../protected-zones/index.ts";
+
+export type PackAssetKind = "skills" | "agents" | "workflows" | "hooks" | "docs";
+
+export interface PackManifest {
+  id: string;
+  version: string;
+  name: string;
+  description: string;
+  publisher?: string;
+  license?: string;
+  compatibility: {
+    evodev: string;
+    targets: string[];
+  };
+  assets: Record<PackAssetKind, string[]>;
+  permissions: PackPermissions;
+  install: {
+    guide: string;
+    requiresConfirmation: boolean;
+    supportsDryRun: boolean;
+    backupPolicy: string;
+    mergePolicy: string;
+  };
+  verify: {
+    guide: string;
+    requiredChecks: string[];
+  };
+  customizations: {
+    guide: string;
+    userPath: string;
+    projectPath: string;
+  };
+  protectedZones?: {
+    neverInclude?: string[];
+    neverWrite?: string[];
+  };
+  observability: {
+    metadataOnly: true;
+    logEvents: string[];
+  };
+  uninstall: {
+    supported: boolean;
+    deleteUserContent: boolean;
+    requiresDryRun: boolean;
+    requiresConfirmation: boolean;
+  };
+}
+
+export interface PackPermissions {
+  writesUserConfig?: boolean;
+  writesProjectFiles?: boolean;
+  usesHooks?: boolean;
+  usesNetwork?: boolean;
+  publishes?: boolean;
+  deletesFiles?: boolean;
+  spawnsAgents?: boolean;
+  writesMemory?: boolean;
+  readsSourceContent?: boolean;
+  readsProjectMetadata?: boolean;
+}
+
+export interface PackAssetRef {
+  kind: PackAssetKind;
+  path: string;
+  absolutePath: string;
+}
+
+export type PackValidationSeverity = "error" | "warning";
+
+export interface PackValidationFinding {
+  severity: PackValidationSeverity;
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface PackValidationResult {
+  ok: boolean;
+  packRoot: string;
+  manifestPath: string;
+  source: string;
+  manifest?: PackManifest;
+  assets: PackAssetRef[];
+  scannedPaths: string[];
+  protectedZoneFindings: ProtectedZoneFinding[];
+  findings: PackValidationFinding[];
+}
+
+export type PackInstallActionKind = "create" | "skip-existing" | "merge-with-backup" | "error";
+
+export interface PackInstallAction {
+  action: PackInstallActionKind;
+  sourcePath: string;
+  targetPath: string;
+  reason: string;
+}
+
+export interface PackInstallDryRunPlan {
+  validation: PackValidationResult;
+  plannedWrites: PackInstallAction[];
+  plannedRegistryUpdates: string[];
+  plannedSettingsUpdates: string[];
+  permissions: Required<PackPermissions>;
+  riskyCapabilities: string[];
+  verificationPlan: string[];
+  uninstallPlan: string[];
+  blockers: string[];
+  warnings: string[];
+}
+
+const ASSET_KINDS: PackAssetKind[] = ["skills", "agents", "workflows", "hooks", "docs"];
+const MANIFEST_FILE_NAME = "PACK.json";
+const RISKY_PERMISSION_LABELS: Record<keyof PackPermissions, string> = {
+  writesUserConfig: "writes user-level EvoDev or Code Agent configuration",
+  writesProjectFiles: "writes project files",
+  usesHooks: "installs or enables hooks",
+  usesNetwork: "uses network or remote services",
+  publishes: "publishes packages or artifacts",
+  deletesFiles: "deletes files",
+  spawnsAgents: "spawns agents",
+  writesMemory: "writes memory or knowledge",
+  readsSourceContent: "reads source content",
+  readsProjectMetadata: "reads project metadata",
+};
+const FIRST_SLICE_DENIED_PERMISSIONS: Array<keyof PackPermissions> = [
+  "writesProjectFiles",
+  "usesHooks",
+  "usesNetwork",
+  "publishes",
+  "deletesFiles",
+  "writesMemory",
+  "readsSourceContent",
+];
+
+export async function validatePack(packPath: string): Promise<PackValidationResult> {
+  if (isRemotePackInput(packPath)) {
+    throw new Error("Only local pack directories are supported in I6.");
+  }
+  const packRoot = await resolvePackRoot(packPath);
+  const manifestPath = join(packRoot, MANIFEST_FILE_NAME);
+  const findings: PackValidationFinding[] = [];
+  let manifest: PackManifest | undefined;
+  let assets: PackAssetRef[] = [];
+  let scannedPaths: string[] = [];
+
+  try {
+    manifest = parsePackManifest(JSON.parse(await readFile(manifestPath, "utf8")));
+  } catch (error) {
+    findings.push({
+      severity: "error",
+      code: "manifest-invalid",
+      message: formatError(error),
+      path: MANIFEST_FILE_NAME,
+    });
+  }
+
+  if (manifest !== undefined) {
+    assets = manifestAssetRefs(manifest, packRoot, findings);
+    await validateReferencedAssets(assets, findings);
+    validatePermissionBoundaries(manifest, findings);
+    validateGuideReferences(manifest, assets, findings);
+  }
+
+  try {
+    scannedPaths = await collectPackRelativePaths(packRoot);
+  } catch (error) {
+    findings.push({ severity: "error", code: "scan-failed", message: formatError(error) });
+  }
+
+  const protectedZoneFindings = checkProtectedZonePaths(scannedPaths).findings;
+  for (const finding of protectedZoneFindings) {
+    findings.push({
+      severity: "error",
+      code: `protected-zone:${finding.ruleId}`,
+      message: finding.reason,
+      path: finding.path,
+    });
+  }
+
+  return {
+    ok: findings.every((finding) => finding.severity !== "error"),
+    packRoot,
+    manifestPath,
+    source: packRoot,
+    manifest,
+    assets,
+    scannedPaths,
+    protectedZoneFindings,
+    findings,
+  };
+}
+
+export async function planPackInstallDryRun(
+  input: string | { packDir: string; homeDir?: string },
+): Promise<PackInstallDryRunPlan> {
+  const packPath = typeof input === "string" ? input : input.packDir;
+  const homePrefix = typeof input === "string" ? "~" : (input.homeDir ?? "~");
+  const displayEvodevRoot = `${homePrefix.replace(/\/$/, "")}/.evodev`;
+  const validation = await validatePack(packPath);
+  const manifest = validation.manifest;
+  const plannedWrites: PackInstallAction[] = [];
+  const warnings: string[] = [];
+  const blockers = validation.findings
+    .filter((finding) => finding.severity === "error")
+    .map(
+      (finding) => `${finding.code}${finding.path ? ` ${finding.path}` : ""}: ${finding.message}`,
+    );
+
+  if (manifest === undefined) {
+    blockers.push("Cannot plan install because PACK.json is invalid or missing.");
+  } else {
+    const permissions = normalizePackPermissions(manifest.permissions);
+    if (!permissions.writesUserConfig) {
+      warnings.push("Pack does not declare writesUserConfig; dry-run only reports source assets.");
+    }
+    for (const asset of validation.assets) {
+      plannedWrites.push({
+        action: "create",
+        sourcePath: asset.path,
+        targetPath: `${displayEvodevRoot}/PACKS/${manifest.id}/${asset.path}`,
+        reason: "dry-run planned pack asset write; no files are written",
+      });
+    }
+  }
+
+  const permissions = normalizePackPermissions(manifest?.permissions ?? {});
+  return {
+    validation,
+    plannedWrites,
+    plannedRegistryUpdates:
+      manifest === undefined
+        ? []
+        : [`dry-run metadata merge for registry.packs.${manifest.id}; no registry file is written`],
+    plannedSettingsUpdates:
+      manifest === undefined
+        ? []
+        : [`dry-run settings compatibility review for ${manifest.id}; no settings file is written`],
+    permissions,
+    riskyCapabilities: riskyCapabilities(permissions),
+    verificationPlan: manifest?.verify.requiredChecks ?? [],
+    uninstallPlan:
+      manifest === undefined
+        ? []
+        : [
+            "dry-run-first uninstall required",
+            "confirmation required before future uninstall",
+            "deleteUserContent=false; customizations and user content must be preserved",
+          ],
+    blockers,
+    warnings,
+  };
+}
+
+export function parsePackManifest(value: unknown): PackManifest {
+  if (!isRecord(value)) throw new Error("Pack manifest must be an object.");
+
+  const manifest = value as Record<string, unknown>;
+  validateManifestTopLevelFields(manifest);
+  const id = requireString(manifest, "id");
+  const version = requireString(manifest, "version");
+  const name = requireString(manifest, "name");
+  const description = requireString(manifest, "description");
+  const publisher = optionalString(manifest, "publisher");
+  const license = optionalString(manifest, "license");
+  const compatibility = requireRecord(manifest, "compatibility");
+  const assets = parseAssets(requireRecord(manifest, "assets"));
+  const permissions = parsePermissions(manifest.permissions);
+  const install = requireRecord(manifest, "install");
+  const verify = requireRecord(manifest, "verify");
+  const customizations = requireRecord(manifest, "customizations");
+  const observability = requireRecord(manifest, "observability");
+  const uninstall = requireRecord(manifest, "uninstall");
+
+  validateCompatibilityTargets(id, requireStringArray(compatibility, "targets"));
+  validateProtectedZoneDeclarations(manifest.protectedZones);
+
+  if (observability.metadataOnly !== true) {
+    throw new Error(`Pack manifest ${id} must declare observability.metadataOnly=true.`);
+  }
+  if (uninstall.deleteUserContent !== false) {
+    throw new Error(`Pack manifest ${id} must declare uninstall.deleteUserContent=false.`);
+  }
+
+  return {
+    id,
+    version,
+    name,
+    description,
+    publisher,
+    license,
+    compatibility: {
+      evodev: requireString(compatibility, "evodev"),
+      targets: requireStringArray(compatibility, "targets"),
+    },
+    assets,
+    permissions,
+    install: {
+      guide: requireString(install, "guide"),
+      requiresConfirmation: requireBoolean(install, "requiresConfirmation"),
+      supportsDryRun: requireBoolean(install, "supportsDryRun"),
+      backupPolicy: requireString(install, "backupPolicy"),
+      mergePolicy: requireString(install, "mergePolicy"),
+    },
+    verify: {
+      guide: requireString(verify, "guide"),
+      requiredChecks: requireStringArray(verify, "requiredChecks"),
+    },
+    customizations: {
+      guide: requireString(customizations, "guide"),
+      userPath: requireString(customizations, "userPath"),
+      projectPath: requireString(customizations, "projectPath"),
+    },
+    protectedZones: isRecord(manifest.protectedZones)
+      ? {
+          neverInclude: optionalStringArray(manifest.protectedZones, "neverInclude"),
+          neverWrite: optionalStringArray(manifest.protectedZones, "neverWrite"),
+        }
+      : undefined,
+    observability: {
+      metadataOnly: true,
+      logEvents: requireStringArray(observability, "logEvents"),
+    },
+    uninstall: {
+      supported: requireBoolean(uninstall, "supported"),
+      deleteUserContent: false,
+      requiresDryRun: requireBoolean(uninstall, "requiresDryRun"),
+      requiresConfirmation: requireBoolean(uninstall, "requiresConfirmation"),
+    },
+  };
+}
+
+export function normalizePackPermissions(permissions: PackPermissions): Required<PackPermissions> {
+  return {
+    writesUserConfig: permissions.writesUserConfig === true,
+    writesProjectFiles: permissions.writesProjectFiles === true,
+    usesHooks: permissions.usesHooks === true,
+    usesNetwork: permissions.usesNetwork === true,
+    publishes: permissions.publishes === true,
+    deletesFiles: permissions.deletesFiles === true,
+    spawnsAgents: permissions.spawnsAgents === true,
+    writesMemory: permissions.writesMemory === true,
+    readsSourceContent: permissions.readsSourceContent === true,
+    readsProjectMetadata: permissions.readsProjectMetadata === true,
+  };
+}
+
+export function formatPackValidation(result: PackValidationResult): string {
+  const manifest = result.manifest;
+  return [
+    "EvoDev pack validate",
+    "",
+    `Pack root: ${result.packRoot}`,
+    `Status: ${result.ok ? "PASS" : "FAIL"}`,
+    manifest === undefined
+      ? "Pack: unknown"
+      : `Pack: ${manifest.id}@${manifest.version} (${manifest.name})`,
+    `Assets: ${result.assets.length}`,
+    `Scanned paths: ${result.scannedPaths.length}`,
+    `Protected-zone blockers: ${result.protectedZoneFindings.length}`,
+    "",
+    "Findings:",
+    ...(result.findings.length === 0
+      ? ["  - none"]
+      : result.findings.map(
+          (finding) =>
+            `  - ${finding.severity.toUpperCase()} ${finding.code}${finding.path ? ` ${finding.path}` : ""}: ${finding.message}`,
+        )),
+  ].join("\n");
+}
+
+export function formatPackInstallDryRun(plan: PackInstallDryRunPlan): string {
+  const manifest = plan.validation.manifest;
+  return [
+    "EvoDev pack install dry-run",
+    "",
+    manifest === undefined
+      ? "Pack: unknown"
+      : `Pack: ${manifest.id}@${manifest.version} (${manifest.name})`,
+    "Mode: dry-run (no writes)",
+    `Status: ${plan.blockers.length === 0 ? "PASS" : "FAIL"}`,
+    "",
+    `Source: ${plan.validation.source}`,
+    "",
+    "Asset inventory:",
+    ...formatAssetInventory(plan.validation.assets),
+    "Asset files:",
+    ...formatAssetFiles(plan.validation.assets),
+    "",
+    "Planned writes:",
+    ...(plan.plannedWrites.length === 0
+      ? ["  - none"]
+      : plan.plannedWrites.map(
+          (write) =>
+            `  - ${write.action}: ${write.sourcePath} -> ${write.targetPath} (${write.reason})`,
+        )),
+    "",
+    "Planned registry/settings metadata:",
+    ...(plan.plannedRegistryUpdates.length === 0
+      ? ["  - registry: none"]
+      : plan.plannedRegistryUpdates.map((update) => `  - registry: ${update}`)),
+    ...(plan.plannedSettingsUpdates.length === 0
+      ? ["  - settings: none"]
+      : plan.plannedSettingsUpdates.map((update) => `  - settings: ${update}`)),
+    "",
+    "Permissions:",
+    ...Object.entries(plan.permissions).map(([key, value]) => `  - ${key}: ${value}`),
+    "",
+    "Risky capabilities:",
+    ...(plan.riskyCapabilities.length === 0
+      ? ["  - none"]
+      : plan.riskyCapabilities.map((capability) => `  - ${capability}`)),
+    "",
+    "Protected-zone results:",
+    ...(plan.validation.protectedZoneFindings.length === 0
+      ? ["  - PASS"]
+      : plan.validation.protectedZoneFindings.map(
+          (finding) => `  - BLOCKER ${finding.ruleId} ${finding.path}: ${finding.reason}`,
+        )),
+    "",
+    "Verification plan:",
+    ...(plan.verificationPlan.length === 0
+      ? ["  - none"]
+      : plan.verificationPlan.map((check) => `  - ${check}`)),
+    "",
+    "Uninstall plan:",
+    ...(plan.uninstallPlan.length === 0
+      ? ["  - none"]
+      : plan.uninstallPlan.map((step) => `  - ${step}`)),
+    "",
+    "Warnings:",
+    ...(plan.warnings.length === 0
+      ? ["  - none"]
+      : plan.warnings.map((warning) => `  - ${warning}`)),
+    "",
+    "Blockers:",
+    ...(plan.blockers.length === 0
+      ? ["  - none"]
+      : plan.blockers.map((blocker) => `  - ${blocker}`)),
+  ].join("\n");
+}
+
+async function resolvePackRoot(packPath: string): Promise<string> {
+  const pathStat = await stat(packPath);
+  if (pathStat.isDirectory()) return packPath;
+  throw new Error(`Pack path must be a local directory: ${packPath}`);
+}
+
+function manifestAssetRefs(
+  manifest: PackManifest,
+  packRoot: string,
+  findings: PackValidationFinding[],
+): PackAssetRef[] {
+  const refs: PackAssetRef[] = [];
+  for (const kind of ASSET_KINDS) {
+    for (const assetPath of manifest.assets[kind]) {
+      const pathFinding = validatePackRelativePath(assetPath, packRoot);
+      if (pathFinding !== undefined) {
+        findings.push({ ...pathFinding, path: assetPath });
+        continue;
+      }
+      refs.push({ kind, path: assetPath, absolutePath: join(packRoot, assetPath) });
+    }
+  }
+  return refs;
+}
+
+async function validateReferencedAssets(
+  assets: PackAssetRef[],
+  findings: PackValidationFinding[],
+): Promise<void> {
+  for (const asset of assets) {
+    try {
+      const assetStat = await stat(asset.absolutePath);
+      if (!assetStat.isFile()) {
+        findings.push({
+          severity: "error",
+          code: "asset-not-file",
+          message: "Referenced asset must be a file.",
+          path: asset.path,
+        });
+      }
+    } catch (error) {
+      if (isEnoent(error)) {
+        findings.push({
+          severity: "error",
+          code: "asset-missing",
+          message: "Referenced asset file does not exist.",
+          path: asset.path,
+        });
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+function validatePermissionBoundaries(
+  manifest: PackManifest,
+  findings: PackValidationFinding[],
+): void {
+  const permissions = normalizePackPermissions(manifest.permissions);
+  for (const permission of FIRST_SLICE_DENIED_PERMISSIONS) {
+    if (permissions[permission]) {
+      findings.push({
+        severity: "error",
+        code: "permission-denied-first-slice",
+        message: `${permission} is outside I6 local validate/install dry-run scope.`,
+      });
+    }
+  }
+  if (manifest.assets.hooks.length > 0 && !permissions.usesHooks) {
+    findings.push({
+      severity: "error",
+      code: "permission-asset-mismatch",
+      message: "Pack declares hook assets but usesHooks permission is false.",
+    });
+  }
+  if (!manifest.install.requiresConfirmation || !manifest.install.supportsDryRun) {
+    findings.push({
+      severity: "error",
+      code: "install-policy-invalid",
+      message: "Pack install must require confirmation and support dry-run.",
+    });
+  }
+  if (!manifest.uninstall.requiresDryRun || !manifest.uninstall.requiresConfirmation) {
+    findings.push({
+      severity: "error",
+      code: "uninstall-policy-invalid",
+      message: "Pack uninstall must require dry-run and confirmation.",
+    });
+  }
+}
+
+function validateGuideReferences(
+  manifest: PackManifest,
+  assets: PackAssetRef[],
+  findings: PackValidationFinding[],
+): void {
+  const docsAssetPaths = new Set(
+    assets.filter((asset) => asset.kind === "docs").map((asset) => asset.path),
+  );
+  for (const guide of [
+    manifest.install.guide,
+    manifest.verify.guide,
+    manifest.customizations.guide,
+  ]) {
+    if (!docsAssetPaths.has(guide)) {
+      findings.push({
+        severity: "error",
+        code: "guide-not-declared",
+        message: "Guide file must be listed in assets.docs.",
+        path: guide,
+      });
+    }
+  }
+}
+
+async function collectPackRelativePaths(packRoot: string, dir = packRoot): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const paths: string[] = [];
+  for (const entry of entries) {
+    const absolutePath = join(dir, entry.name);
+    const relativePath = normalizeRelativePath(relative(packRoot, absolutePath));
+    paths.push(relativePath);
+    if (entry.isDirectory()) {
+      paths.push(...(await collectPackRelativePaths(packRoot, absolutePath)));
+    }
+  }
+  return paths.sort();
+}
+
+function validatePackRelativePath(
+  path: string,
+  packRoot: string,
+): PackValidationFinding | undefined {
+  if (path.length === 0) {
+    return { severity: "error", code: "path-empty", message: "Path must not be empty." };
+  }
+  if (path.includes("\0")) {
+    return { severity: "error", code: "path-invalid", message: "Path must not contain NUL bytes." };
+  }
+  if (isAbsolute(path) || path.startsWith("~")) {
+    return {
+      severity: "error",
+      code: "path-absolute",
+      message: "Path must be relative to pack root.",
+    };
+  }
+  const normalized = normalizeRelativePath(path);
+  if (normalized.split("/").includes("..")) {
+    return {
+      severity: "error",
+      code: "path-traversal",
+      message: "Path must not escape pack root.",
+    };
+  }
+  const absolute = join(packRoot, normalized);
+  const rel = relative(packRoot, absolute);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    return {
+      severity: "error",
+      code: "path-traversal",
+      message: "Path must stay inside pack root.",
+    };
+  }
+  return undefined;
+}
+
+function riskyCapabilities(permissions: Required<PackPermissions>): string[] {
+  return (Object.entries(permissions) as Array<[keyof PackPermissions, boolean]>)
+    .filter(([, value]) => value)
+    .map(([permission]) => RISKY_PERMISSION_LABELS[permission]);
+}
+
+function formatAssetInventory(assets: PackAssetRef[]): string[] {
+  if (assets.length === 0) return ["  - none"];
+  const counts = new Map<PackAssetKind, number>();
+  for (const kind of ASSET_KINDS) counts.set(kind, 0);
+  for (const asset of assets) counts.set(asset.kind, (counts.get(asset.kind) ?? 0) + 1);
+  return ASSET_KINDS.map((kind) => `  - ${kind}: ${counts.get(kind) ?? 0}`);
+}
+
+function formatAssetFiles(assets: PackAssetRef[]): string[] {
+  if (assets.length === 0) return ["  - none"];
+  return assets.map((asset) => `  - ${asset.kind}: ${asset.path}`);
+}
+
+function parseAssets(value: Record<string, unknown>): Record<PackAssetKind, string[]> {
+  const knownKinds = new Set(ASSET_KINDS);
+  for (const key of Object.keys(value)) {
+    if (!knownKinds.has(key as PackAssetKind)) {
+      throw new Error(`Pack manifest contains unknown asset kind: ${key}`);
+    }
+  }
+  return {
+    skills: optionalStringArray(value, "skills") ?? [],
+    agents: optionalStringArray(value, "agents") ?? [],
+    workflows: optionalStringArray(value, "workflows") ?? [],
+    hooks: optionalStringArray(value, "hooks") ?? [],
+    docs: optionalStringArray(value, "docs") ?? [],
+  };
+}
+
+function parsePermissions(value: unknown): PackPermissions {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error("Pack manifest permissions must be an object.");
+  const permissions: PackPermissions = {};
+  const knownKeys = new Set(Object.keys(RISKY_PERMISSION_LABELS));
+  for (const key of Object.keys(value)) {
+    if (!knownKeys.has(key)) throw new Error(`Pack manifest contains unknown permission: ${key}`);
+  }
+  for (const key of Object.keys(RISKY_PERMISSION_LABELS) as Array<keyof PackPermissions>) {
+    if (value[key] !== undefined) permissions[key] = requireBoolean(value, key);
+  }
+  return permissions;
+}
+
+function optionalString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Pack manifest field must be a non-empty string: ${key}`);
+  }
+  return value;
+}
+
+function requireString(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Pack manifest missing string field: ${key}`);
+  }
+  return value;
+}
+
+function requireBoolean(record: Record<string, unknown>, key: string): boolean {
+  const value = record[key];
+  if (typeof value !== "boolean") throw new Error(`Pack manifest missing boolean field: ${key}`);
+  return value;
+}
+
+function requireRecord(record: Record<string, unknown>, key: string): Record<string, unknown> {
+  const value = record[key];
+  if (!isRecord(value)) throw new Error(`Pack manifest missing object field: ${key}`);
+  return value;
+}
+
+function requireStringArray(record: Record<string, unknown>, key: string): string[] {
+  const value = record[key];
+  if (
+    !Array.isArray(value) ||
+    value.some((item) => typeof item !== "string" || item.length === 0)
+  ) {
+    throw new Error(`Pack manifest missing string array field: ${key}`);
+  }
+  return value;
+}
+
+function optionalStringArray(record: Record<string, unknown>, key: string): string[] | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (
+    !Array.isArray(value) ||
+    value.some((item) => typeof item !== "string" || item.length === 0)
+  ) {
+    throw new Error(`Pack manifest field must be a string array: ${key}`);
+  }
+  return value;
+}
+
+function validateManifestTopLevelFields(manifest: Record<string, unknown>): void {
+  const knownFields = new Set([
+    "id",
+    "version",
+    "name",
+    "description",
+    "publisher",
+    "license",
+    "compatibility",
+    "assets",
+    "permissions",
+    "install",
+    "verify",
+    "customizations",
+    "protectedZones",
+    "observability",
+    "uninstall",
+  ]);
+  for (const key of Object.keys(manifest)) {
+    if (!knownFields.has(key)) throw new Error(`Pack manifest contains unknown field: ${key}`);
+  }
+}
+
+function validateCompatibilityTargets(packId: string, targets: string[]): void {
+  if (targets.length === 0)
+    throw new Error(`Pack manifest ${packId} must declare at least one target.`);
+  const supportedTargets = new Set(["claude"]);
+  for (const target of targets) {
+    if (!supportedTargets.has(target)) {
+      throw new Error(`Pack manifest ${packId} declares unsupported target: ${target}`);
+    }
+  }
+}
+
+function validateProtectedZoneDeclarations(value: unknown): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) throw new Error("Pack manifest protectedZones must be an object.");
+  const knownFields = new Set(["neverInclude", "neverWrite"]);
+  for (const key of Object.keys(value)) {
+    if (!knownFields.has(key))
+      throw new Error(`Pack manifest protectedZones contains unknown field: ${key}`);
+  }
+  optionalStringArray(value, "neverInclude");
+  optionalStringArray(value, "neverWrite");
+}
+
+function isRemotePackInput(packPath: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(packPath);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeRelativePath(path: string): string {
+  return path.split(sep).join("/").replace(/^\.\//, "");
+}
+
+function isEnoent(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}