@cogineai/dearharness 0.1.0

package/dist/harness/install-verification.js

@@ -0,0 +1,117 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { normalizeInstallPath } from './install-plan.js';
+import { readInstallLockfile } from './lockfile.js';
+function resolveInside(root, relativeInput) {
+    if (path.isAbsolute(relativeInput)) {
+        throw new Error(`path must be relative: ${relativeInput}`);
+    }
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`path must stay inside ${root}: ${relativeInput}`);
+    }
+    return target;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function filesMatch(left, right) {
+    try {
+        return (await fs.readFile(left)).equals(await fs.readFile(right));
+    }
+    catch {
+        return false;
+    }
+}
+function compareLockfileField(issues, field, expected, actual) {
+    if (actual === expected)
+        return;
+    issues.push({ kind: 'lockfile_entry_field_mismatch', field, expected, actual });
+}
+function compareManagedPaths(issues, expected, actual) {
+    const normalizedExpected = expected.map(normalizeInstallPath);
+    const normalizedActual = actual.map(normalizeInstallPath);
+    if (JSON.stringify(normalizedActual) === JSON.stringify(normalizedExpected))
+        return;
+    issues.push({
+        kind: 'lockfile_entry_field_mismatch',
+        field: 'managedPaths',
+        expected: normalizedExpected,
+        actual: normalizedActual,
+    });
+}
+export async function verifyAppliedInstall(options) {
+    const issues = [];
+    const lockfileStatus = await readInstallLockfile(options.targetWorkspace);
+    if (!lockfileStatus.exists) {
+        issues.push({ kind: 'lockfile_missing' });
+    }
+    for (const error of lockfileStatus.errors) {
+        issues.push({ kind: 'lockfile_invalid', error });
+    }
+    const installedEntry = lockfileStatus.installed.find((entry) => entry.packageId === options.plannedLockfileEntry.packageId);
+    if (!installedEntry) {
+        issues.push({ kind: 'lockfile_entry_missing', packageId: options.plannedLockfileEntry.packageId });
+    }
+    else {
+        compareLockfileField(issues, 'packageType', options.plannedLockfileEntry.packageType, installedEntry.packageType);
+        compareLockfileField(issues, 'version', options.plannedLockfileEntry.version, installedEntry.version);
+        compareLockfileField(issues, 'manifestUrl', options.plannedLockfileEntry.manifestUrl, installedEntry.manifestUrl);
+        compareLockfileField(issues, 'sha256', options.plannedLockfileEntry.sha256, installedEntry.sha256);
+        compareLockfileField(issues, 'installedBy', options.plannedLockfileEntry.installedBy, installedEntry.installedBy);
+        compareManagedPaths(issues, options.plannedLockfileEntry.managedPaths, installedEntry.managedPaths);
+    }
+    const managedPaths = [];
+    for (const managedPath of options.plannedLockfileEntry.managedPaths) {
+        const normalizedPath = normalizeInstallPath(managedPath);
+        const ok = await pathExists(resolveInside(options.targetWorkspace, normalizedPath));
+        managedPaths.push({ path: normalizedPath, ok });
+        if (!ok) {
+            issues.push({ kind: 'managed_path_missing', path: normalizedPath });
+        }
+    }
+    const files = [];
+    for (const change of options.plannedChanges) {
+        const targetPath = resolveInside(options.targetWorkspace, change.path);
+        if (change.kind === 'delete') {
+            const ok = !(await pathExists(targetPath));
+            files.push({ path: change.path, kind: change.kind, ok });
+            if (!ok) {
+                issues.push({ kind: 'planned_delete_still_exists', path: change.path });
+            }
+            continue;
+        }
+        const targetExists = await pathExists(targetPath);
+        if (!targetExists) {
+            files.push({ path: change.path, kind: change.kind, ok: false });
+            issues.push({ kind: 'planned_file_missing', path: change.path, changeKind: change.kind });
+            continue;
+        }
+        const candidatePath = resolveInside(options.candidateWorkspace, change.path);
+        const ok = await filesMatch(candidatePath, targetPath);
+        files.push({ path: change.path, kind: change.kind, ok });
+        if (!ok) {
+            issues.push({ kind: 'planned_file_content_mismatch', path: change.path, changeKind: change.kind });
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        lockfile: installedEntry
+            ? {
+                exists: lockfileStatus.exists,
+                packageId: installedEntry.packageId,
+                managedPaths: installedEntry.managedPaths.map(normalizeInstallPath),
+            }
+            : null,
+        managedPaths,
+        files,
+        issues,
+    };
+}

package/dist/harness/lockfile.js

@@ -0,0 +1,83 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+function isInstalledPackage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.packageId === 'string' &&
+        (record.packageType === 'agent_harness' || record.packageType === 'skill_pack') &&
+        typeof record.version === 'string' &&
+        typeof record.manifestUrl === 'string' &&
+        typeof record.sha256 === 'string' &&
+        typeof record.installedAt === 'string' &&
+        typeof record.installedBy === 'string' &&
+        Array.isArray(record.managedPaths) &&
+        record.managedPaths.every((item) => typeof item === 'string'));
+}
+export async function readInstallLockfile(workspace) {
+    const lockPath = path.join(workspace, '.dearclaw', 'install-lock.json');
+    try {
+        const parsed = JSON.parse(await fs.readFile(lockPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                path: lockPath,
+                exists: true,
+                version: 1,
+                installed: [],
+                errors: ['install-lock.json must be a JSON object'],
+            };
+        }
+        const record = parsed;
+        const installed = Array.isArray(record.installed) ? record.installed.filter(isInstalledPackage) : [];
+        const errors = [];
+        if (record.version !== 1)
+            errors.push('install-lock.json version must be 1');
+        if (!Array.isArray(record.installed))
+            errors.push('install-lock.json installed must be an array');
+        if (Array.isArray(record.installed) && installed.length !== record.installed.length) {
+            errors.push('install-lock.json contains invalid installed package entries');
+        }
+        return { path: lockPath, exists: true, version: 1, installed, errors };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { path: lockPath, exists: false, version: 1, installed: [], errors: [] };
+        }
+        return {
+            path: lockPath,
+            exists: true,
+            version: 1,
+            installed: [],
+            errors: [`failed to parse install-lock.json: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+}
+export async function writeInstallLockfile(workspace, installed) {
+    const directory = path.join(workspace, '.dearclaw');
+    const lockPath = path.join(directory, 'install-lock.json');
+    await fs.mkdir(directory, { recursive: true });
+    const tempPath = path.join(directory, `.install-lock.json.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await fs.writeFile(tempPath, `${JSON.stringify({ version: 1, installed }, null, 2)}\n`);
+        await fs.rename(tempPath, lockPath);
+    }
+    finally {
+        await fs.rm(tempPath, { force: true });
+    }
+}
+export async function upsertInstallLockfileEntry(workspace, lockfile, entry, installedAt = new Date().toISOString()) {
+    if (lockfile.errors.length > 0) {
+        throw new Error(`cannot write install-lock.json with existing errors: ${lockfile.errors.join('; ')}`);
+    }
+    const installedEntry = {
+        ...entry,
+        installedAt,
+    };
+    const installed = [
+        ...lockfile.installed.filter((candidate) => candidate.packageId !== entry.packageId),
+        installedEntry,
+    ];
+    installed.sort((left, right) => left.packageId.localeCompare(right.packageId));
+    await writeInstallLockfile(workspace, installed);
+    return installedEntry;
+}

package/dist/harness/manifest.js

@@ -0,0 +1,491 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const MANIFEST_FILE = 'dearharness.manifest.json';
+const PACKAGE_TYPES = ['agent_harness', 'skill_pack'];
+const AGENT_ROLES = ['primary', 'specialist', 'support'];
+const ROUTING_MODES = ['primary_entry', 'internal_only', 'external_binding'];
+const WORKSPACE_FILE_ROLES = [
+    'agents',
+    'soul',
+    'user',
+    'tools',
+    'identity',
+    'memory',
+    'heartbeat',
+    'bootstrap',
+    'knowledge',
+    'other',
+];
+const MERGE_POLICIES = ['append_managed_block', 'preserve_existing', 'replace_if_absent', 'replace_managed_file'];
+const SKILL_INSTALL_SCOPES = ['agent_workspace', 'current_workspace', 'managed_global'];
+const SKILL_ACTIVATION_MODES = ['auto_discover', 'explicit_user_instruction', 'append_tools_guidance'];
+const PLUGIN_INSTALL_POLICIES = ['manual', 'preinstalled_required', 'unsupported'];
+const CONFIG_OPERATION_TYPES = [
+    'upsert_agent',
+    'set_agent_skills',
+    'bind_route',
+    'enable_agent_to_agent',
+    'merge_mcp_server',
+];
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isOneOf(values, value) {
+    return typeof value === 'string' && values.includes(value);
+}
+function isPackageType(value) {
+    return isOneOf(PACKAGE_TYPES, value);
+}
+function isValidId(value) {
+    return /^[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+function isSafeRelativeInput(value) {
+    if (value.length === 0 || value.includes('\0'))
+        return false;
+    const normalized = value.replace(/\\/g, '/');
+    if (normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized))
+        return false;
+    const parts = normalized.split('/').filter(Boolean);
+    return parts.length > 0 && !parts.includes('..');
+}
+function safeResolve(root, relativeInput) {
+    if (!isSafeRelativeInput(relativeInput) || path.isAbsolute(relativeInput))
+        return null;
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        return null;
+    return target;
+}
+function isPrivateWorkspaceTarget(target) {
+    const [head] = target.replace(/\\/g, '/').split('/').filter(Boolean);
+    return head === 'USER.md' || head === 'MEMORY.md' || head === 'memory';
+}
+function readStringArray(value, label, errors) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        errors.push(`${label} must be an array when present`);
+        return [];
+    }
+    const result = [];
+    for (const [index, item] of value.entries()) {
+        if (typeof item !== 'string' || item.length === 0) {
+            errors.push(`${label}[${index}] must be a non-empty string`);
+            continue;
+        }
+        result.push(item);
+    }
+    return result;
+}
+function createResult(root, manifestPath, errors, overrides = {}) {
+    return {
+        ok: errors.length === 0,
+        sourcePath: root,
+        manifestPath,
+        package: null,
+        agents: [],
+        workspaceFiles: [],
+        skills: [],
+        configOperations: [],
+        pluginRequirements: [],
+        ...overrides,
+        errors,
+    };
+}
+function readPackage(record, errors) {
+    const value = record.package;
+    if (!isRecord(value)) {
+        errors.push('package must be an object');
+        return null;
+    }
+    const id = value.id;
+    const type = value.type;
+    const version = value.version;
+    const displayName = value.display_name;
+    if (typeof id !== 'string' || !isValidId(id))
+        errors.push('package.id must be a lowercase package id');
+    if (!isPackageType(type))
+        errors.push(`package.type must be one of: ${PACKAGE_TYPES.join(', ')}`);
+    if (typeof version !== 'string' || version.length === 0)
+        errors.push('package.version must be a non-empty string');
+    if (typeof displayName !== 'string' || displayName.length === 0) {
+        errors.push('package.display_name must be a non-empty string');
+    }
+    if (typeof id !== 'string' || !isValidId(id) || !isPackageType(type) || typeof version !== 'string' || typeof displayName !== 'string') {
+        return null;
+    }
+    return { id, type, version, displayName };
+}
+function readComponents(record, errors) {
+    const components = record.components;
+    if (components === undefined)
+        return null;
+    if (!isRecord(components)) {
+        errors.push('components must be an object when present');
+        return null;
+    }
+    return components;
+}
+async function pathIsFile(target) {
+    try {
+        return (await fs.stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function readAgents(components, errors) {
+    const agents = components?.agents;
+    if (agents === undefined)
+        return [];
+    if (!Array.isArray(agents)) {
+        errors.push('components.agents must be an array when present');
+        return [];
+    }
+    const summaries = [];
+    for (const [index, rawAgent] of agents.entries()) {
+        if (!isRecord(rawAgent)) {
+            errors.push(`components.agents[${index}] must be an object`);
+            continue;
+        }
+        const id = rawAgent.id;
+        const name = rawAgent.name;
+        const role = rawAgent.role;
+        const workspace = rawAgent.workspace;
+        const agentDir = rawAgent.agent_dir;
+        if (typeof id !== 'string' || !isValidId(id))
+            errors.push(`components.agents[${index}].id must be a lowercase agent id`);
+        if (typeof name !== 'string' || name.length === 0)
+            errors.push(`components.agents[${index}].name must be a non-empty string`);
+        if (!isOneOf(AGENT_ROLES, role))
+            errors.push(`components.agents[${index}].role must be one of: ${AGENT_ROLES.join(', ')}`);
+        if (typeof workspace !== 'string' || !isSafeRelativeInput(workspace)) {
+            errors.push(`components.agents[${index}].workspace must be a safe relative path`);
+        }
+        if (agentDir !== undefined && (typeof agentDir !== 'string' || !isSafeRelativeInput(agentDir))) {
+            errors.push(`components.agents[${index}].agent_dir must be a safe relative path`);
+        }
+        const skills = readStringArray(rawAgent.skills, `components.agents[${index}].skills`, errors);
+        let routing;
+        if (rawAgent.routing !== undefined) {
+            if (!isRecord(rawAgent.routing)) {
+                errors.push(`components.agents[${index}].routing must be an object when present`);
+            }
+            else if (!isOneOf(ROUTING_MODES, rawAgent.routing.mode)) {
+                errors.push(`components.agents[${index}].routing.mode must be one of: ${ROUTING_MODES.join(', ')}`);
+            }
+            else {
+                routing = { mode: rawAgent.routing.mode };
+            }
+        }
+        const model = rawAgent.model;
+        if (model !== undefined && !isRecord(model)) {
+            errors.push(`components.agents[${index}].model must be an object when present`);
+        }
+        if (typeof id !== 'string' ||
+            !isValidId(id) ||
+            typeof name !== 'string' ||
+            name.length === 0 ||
+            !isOneOf(AGENT_ROLES, role) ||
+            typeof workspace !== 'string' ||
+            !isSafeRelativeInput(workspace) ||
+            (agentDir !== undefined && (typeof agentDir !== 'string' || !isSafeRelativeInput(agentDir)))) {
+            continue;
+        }
+        summaries.push({
+            id,
+            name,
+            role,
+            workspace,
+            ...(typeof agentDir === 'string' && isSafeRelativeInput(agentDir) ? { agentDir } : {}),
+            skills,
+            ...(routing ? { routing } : {}),
+            ...(isRecord(model) ? { model } : {}),
+        });
+    }
+    return summaries;
+}
+async function readWorkspaceFiles(root, components, errors) {
+    const workspaceFiles = components?.workspace_files;
+    if (workspaceFiles === undefined)
+        return [];
+    if (!Array.isArray(workspaceFiles)) {
+        errors.push('components.workspace_files must be an array when present');
+        return [];
+    }
+    const summaries = [];
+    for (const [index, rawFile] of workspaceFiles.entries()) {
+        if (!isRecord(rawFile)) {
+            errors.push(`components.workspace_files[${index}] must be an object`);
+            continue;
+        }
+        const id = rawFile.id;
+        const agentId = rawFile.agent_id;
+        const role = rawFile.role;
+        const source = rawFile.source;
+        const target = rawFile.target;
+        const mergePolicy = rawFile.merge_policy;
+        if (typeof id !== 'string' || !isValidId(id)) {
+            errors.push(`components.workspace_files[${index}].id must be a lowercase workspace file id`);
+        }
+        if (agentId !== undefined && (typeof agentId !== 'string' || !isValidId(agentId))) {
+            errors.push(`components.workspace_files[${index}].agent_id must be a lowercase agent id when present`);
+        }
+        if (!isOneOf(WORKSPACE_FILE_ROLES, role)) {
+            errors.push(`components.workspace_files[${index}].role must be one of: ${WORKSPACE_FILE_ROLES.join(', ')}`);
+        }
+        if (typeof source !== 'string' || source.length === 0) {
+            errors.push(`declared workspace file ${typeof id === 'string' ? id : index} source must be a non-empty string`);
+        }
+        if (typeof target !== 'string' || !isSafeRelativeInput(target)) {
+            errors.push(`declared workspace file ${typeof id === 'string' ? id : index} target must be a safe relative path`);
+        }
+        else if (isPrivateWorkspaceTarget(target)) {
+            errors.push(`workspace file ${typeof id === 'string' ? id : index} targets private OpenClaw content`);
+        }
+        if (!isOneOf(MERGE_POLICIES, mergePolicy)) {
+            errors.push(`components.workspace_files[${index}].merge_policy must be one of: ${MERGE_POLICIES.join(', ')}`);
+        }
+        if (typeof id !== 'string' ||
+            !isValidId(id) ||
+            !isOneOf(WORKSPACE_FILE_ROLES, role) ||
+            typeof source !== 'string' ||
+            source.length === 0 ||
+            typeof target !== 'string' ||
+            !isSafeRelativeInput(target) ||
+            isPrivateWorkspaceTarget(target) ||
+            !isOneOf(MERGE_POLICIES, mergePolicy)) {
+            continue;
+        }
+        const sourcePath = safeResolve(root, source);
+        if (!sourcePath) {
+            errors.push(`declared workspace file ${id} source must stay inside the harness source directory`);
+            continue;
+        }
+        if (!(await pathIsFile(sourcePath))) {
+            errors.push(`declared workspace file ${id} missing source file ${source}`);
+        }
+        summaries.push({
+            id,
+            ...(typeof agentId === 'string' && isValidId(agentId) ? { agentId } : {}),
+            role,
+            source,
+            target,
+            mergePolicy,
+        });
+    }
+    return summaries;
+}
+function readSkillActivation(index, rawSkill, errors) {
+    const activation = rawSkill.activation;
+    if (activation === undefined)
+        return undefined;
+    if (!isRecord(activation)) {
+        errors.push(`components.skills[${index}].activation must be an object when present`);
+        return undefined;
+    }
+    const mode = activation.mode;
+    if (!isOneOf(SKILL_ACTIVATION_MODES, mode)) {
+        errors.push(`components.skills[${index}].activation.mode must be one of: ${SKILL_ACTIVATION_MODES.join(', ')}`);
+        return undefined;
+    }
+    const usageHint = activation.usage_hint;
+    const toolsMdAppend = activation.tools_md_append;
+    if (usageHint !== undefined && typeof usageHint !== 'string') {
+        errors.push(`components.skills[${index}].activation.usage_hint must be a string when present`);
+    }
+    if (toolsMdAppend !== undefined && typeof toolsMdAppend !== 'string') {
+        errors.push(`components.skills[${index}].activation.tools_md_append must be a string when present`);
+    }
+    return {
+        mode,
+        ...(typeof usageHint === 'string' ? { usageHint } : {}),
+        ...(typeof toolsMdAppend === 'string' ? { toolsMdAppend } : {}),
+    };
+}
+async function readSkills(root, components, errors) {
+    const skills = components?.skills;
+    if (skills === undefined)
+        return [];
+    if (!Array.isArray(skills)) {
+        errors.push('components.skills must be an array when present');
+        return [];
+    }
+    const summaries = [];
+    for (const [index, rawSkill] of skills.entries()) {
+        if (!isRecord(rawSkill)) {
+            errors.push(`components.skills[${index}] must be an object`);
+            continue;
+        }
+        const id = rawSkill.id;
+        const source = rawSkill.source;
+        const entry = rawSkill.entry;
+        const installScope = rawSkill.install_scope;
+        if (typeof id !== 'string' || !isValidId(id)) {
+            errors.push(`components.skills[${index}].id must be a lowercase skill id`);
+            continue;
+        }
+        if (typeof source !== 'string' || source.length === 0) {
+            errors.push(`declared skill ${id} source must be a non-empty string`);
+            continue;
+        }
+        if (typeof entry !== 'string' || entry.length === 0) {
+            errors.push(`declared skill ${id} entry must be a non-empty string`);
+            continue;
+        }
+        if (installScope !== undefined && !isOneOf(SKILL_INSTALL_SCOPES, installScope)) {
+            errors.push(`declared skill ${id} install_scope must be one of: ${SKILL_INSTALL_SCOPES.join(', ')}`);
+        }
+        const agentIds = readStringArray(rawSkill.agent_ids, `components.skills[${index}].agent_ids`, errors);
+        const activation = readSkillActivation(index, rawSkill, errors);
+        const sourcePath = safeResolve(root, source);
+        if (!sourcePath) {
+            errors.push(`declared skill ${id} source must stay inside the harness source directory`);
+            continue;
+        }
+        const entryPath = safeResolve(sourcePath, entry);
+        if (!entryPath || !(await pathIsFile(entryPath))) {
+            errors.push(`declared skill ${id} missing entry file ${entry}`);
+        }
+        summaries.push({
+            id,
+            source,
+            entry,
+            ...(isOneOf(SKILL_INSTALL_SCOPES, installScope) ? { installScope } : {}),
+            agentIds,
+            ...(activation ? { activation } : {}),
+        });
+    }
+    return summaries;
+}
+function readPluginRequirements(record, errors) {
+    const requirements = record.requirements;
+    if (requirements === undefined)
+        return [];
+    if (!isRecord(requirements)) {
+        errors.push('requirements must be an object when present');
+        return [];
+    }
+    const plugins = requirements.plugins;
+    if (plugins === undefined)
+        return [];
+    if (!Array.isArray(plugins)) {
+        errors.push('requirements.plugins must be an array when present');
+        return [];
+    }
+    const summaries = [];
+    for (const [index, rawPlugin] of plugins.entries()) {
+        if (!isRecord(rawPlugin)) {
+            errors.push(`requirements.plugins[${index}] must be an object`);
+            continue;
+        }
+        const id = rawPlugin.id;
+        const required = rawPlugin.required;
+        const installPolicy = rawPlugin.install_policy;
+        const reason = rawPlugin.reason;
+        if (typeof id !== 'string' || !isValidId(id))
+            errors.push(`requirements.plugins[${index}].id must be a lowercase plugin id`);
+        if (typeof required !== 'boolean')
+            errors.push(`requirements.plugins[${index}].required must be a boolean`);
+        if (!isOneOf(PLUGIN_INSTALL_POLICIES, installPolicy)) {
+            errors.push(`requirements.plugins[${index}].install_policy must be one of: ${PLUGIN_INSTALL_POLICIES.join(', ')}`);
+        }
+        if (reason !== undefined && typeof reason !== 'string') {
+            errors.push(`requirements.plugins[${index}].reason must be a string when present`);
+        }
+        if (typeof id !== 'string' || !isValidId(id) || typeof required !== 'boolean' || !isOneOf(PLUGIN_INSTALL_POLICIES, installPolicy)) {
+            continue;
+        }
+        summaries.push({
+            id,
+            required,
+            installPolicy,
+            ...(typeof reason === 'string' ? { reason } : {}),
+        });
+    }
+    return summaries;
+}
+function readConfigOperations(record, errors) {
+    const install = record.install;
+    if (install === undefined)
+        return [];
+    if (!isRecord(install)) {
+        errors.push('install must be an object when present');
+        return [];
+    }
+    if (install.adapter !== undefined && typeof install.adapter !== 'string') {
+        errors.push('install.adapter must be a string when present');
+    }
+    const operations = install.config_operations;
+    if (operations === undefined)
+        return [];
+    if (!Array.isArray(operations)) {
+        errors.push('install.config_operations must be an array when present');
+        return [];
+    }
+    const summaries = [];
+    for (const [index, rawOperation] of operations.entries()) {
+        if (!isRecord(rawOperation)) {
+            errors.push(`install.config_operations[${index}] must be an object`);
+            continue;
+        }
+        const op = rawOperation.op;
+        if (!isOneOf(CONFIG_OPERATION_TYPES, op)) {
+            errors.push(typeof op === 'string' ? `unknown config operation ${op}` : `install.config_operations[${index}].op must be one of: ${CONFIG_OPERATION_TYPES.join(', ')}`);
+            continue;
+        }
+        const agentId = rawOperation.agent_id;
+        if (agentId !== undefined && (typeof agentId !== 'string' || !isValidId(agentId))) {
+            errors.push(`install.config_operations[${index}].agent_id must be a lowercase agent id when present`);
+        }
+        const optional = rawOperation.optional;
+        if (optional !== undefined && typeof optional !== 'boolean') {
+            errors.push(`install.config_operations[${index}].optional must be a boolean when present`);
+        }
+        summaries.push({
+            op,
+            ...(typeof agentId === 'string' && isValidId(agentId) ? { agentId } : {}),
+            optional: optional === true,
+            raw: rawOperation,
+        });
+    }
+    return summaries;
+}
+export async function validateHarnessSource(sourcePath) {
+    const root = path.resolve(sourcePath);
+    const manifestPath = path.join(root, MANIFEST_FILE);
+    const errors = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return createResult(root, manifestPath, [`missing ${MANIFEST_FILE}`]);
+        }
+        return createResult(root, manifestPath, [
+            `failed to parse ${MANIFEST_FILE}: ${error instanceof Error ? error.message : String(error)}`,
+        ]);
+    }
+    if (!isRecord(parsed)) {
+        return createResult(root, manifestPath, [`${MANIFEST_FILE} must contain a JSON object`]);
+    }
+    if (parsed.manifest_version !== 1)
+        errors.push('manifest_version must be 1');
+    const packageSummary = readPackage(parsed, errors);
+    const components = readComponents(parsed, errors);
+    const agents = readAgents(components, errors);
+    const workspaceFiles = await readWorkspaceFiles(root, components, errors);
+    const skills = await readSkills(root, components, errors);
+    const pluginRequirements = readPluginRequirements(parsed, errors);
+    const configOperations = readConfigOperations(parsed, errors);
+    return createResult(root, manifestPath, errors, {
+        package: packageSummary,
+        agents,
+        workspaceFiles,
+        skills,
+        configOperations,
+        pluginRequirements,
+    });
+}