@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/hermes-install.js

@@ -0,0 +1,641 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChildEnvironment = buildChildEnvironment;
+exports.validateHermesManifest = validateHermesManifest;
+exports.resolveHermesCommand = resolveHermesCommand;
+exports.installHermes = installHermes;
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const OFFICIAL_INSTALLER_PATHS = {
+    windows: 'scripts/install.ps1',
+    posix: 'scripts/install.sh',
+};
+const OFFICIAL_HERMES_REPOSITORY = 'https://github.com/NousResearch/hermes-agent.git';
+const USER_MEMORY_LIMIT = 1_375;
+const AGENT_MEMORY_LIMIT = 2_200;
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;
+const PROFILE_PATTERN = /^[a-z][a-z0-9_-]{0,62}$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+const REQUIRED_DISTRIBUTION_FILES = new Set(['distribution.yaml', 'SOUL.md', 'config.yaml', 'README.md']);
+const SECRET_PATTERNS = [
+    { label: 'private key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
+    { label: 'provider token', pattern: /\b(?:sk|ghp|github_pat|xox[baprs])-[-A-Za-z0-9_]{16,}\b/ },
+    {
+        label: 'credential assignment',
+        pattern: /\b(?:api[_-]?key|access[_-]?token|password|client[_-]?secret)\s*[:=]\s*["']?(?!redacted\b|placeholder\b|your[_-])[A-Za-z0-9_./+=-]{12,}/i,
+    },
+];
+function buildChildEnvironment(base, overlay = {}, unset = [], platform = process.platform) {
+    const childEnv = { ...base, ...overlay };
+    const removed = new Set(unset.map((key) => platform === 'win32' ? key.toUpperCase() : key));
+    for (const key of Object.keys(childEnv)) {
+        if (removed.has(platform === 'win32' ? key.toUpperCase() : key))
+            delete childEnv[key];
+    }
+    return childEnv;
+}
+const defaultRuntime = {
+    platform: process.platform,
+    arch: process.arch,
+    homeDir: (0, node_os_1.homedir)(),
+    localAppData: process.env.LOCALAPPDATA,
+    tempDir: (0, node_os_1.tmpdir)(),
+    now: () => new Date(),
+    log: (message) => console.log(message),
+    async download(url) {
+        const response = await fetch(url, { redirect: 'error' });
+        if (!response.ok)
+            throw new Error(`Official Hermes installer download failed (HTTP ${response.status}).`);
+        return Buffer.from(await response.arrayBuffer());
+    },
+    run(command, args, options) {
+        const childEnv = buildChildEnvironment(process.env, options?.env, options?.unsetEnv);
+        const result = (0, node_child_process_1.spawnSync)(command, args, {
+            stdio: options?.quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            shell: false,
+            env: childEnv,
+            encoding: 'utf8',
+            timeout: options?.timeoutMs,
+        });
+        return {
+            status: result.status,
+            error: result.error,
+            stdout: typeof result.stdout === 'string' ? result.stdout : undefined,
+            stderr: typeof result.stderr === 'string' ? result.stderr : undefined,
+        };
+    },
+};
+function assertPlainObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object.`);
+}
+function parseJsonWithOptionalBom(value, label) {
+    try {
+        return JSON.parse(value.startsWith('\uFEFF') ? value.slice(1) : value);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${error.message}`);
+    }
+}
+function assertDate(value, label) {
+    if (typeof value !== 'string' || !value || Number.isNaN(Date.parse(value)))
+        throw new Error(`${label} must be an ISO date.`);
+}
+function characterCount(value) {
+    return Array.from(value).length;
+}
+function assertNoSecret(content, filePath) {
+    for (const candidate of SECRET_PATTERNS) {
+        if (candidate.pattern.test(content)) {
+            throw new Error(`Hermes manifest ${filePath} appears to contain a ${candidate.label}. Enter credentials only in official Hermes setup.`);
+        }
+    }
+}
+function safeDistributionPath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!normalized || (0, node_path_1.isAbsolute)(filePath) || normalized.split('/').some((part) => !part || part === '..' || part === '.')) {
+        throw new Error(`Unsafe Hermes distribution path: ${filePath}`);
+    }
+    if (REQUIRED_DISTRIBUTION_FILES.has(normalized))
+        return normalized;
+    if (/^skills\/[a-z0-9][a-z0-9-]{0,62}\/SKILL\.md$/.test(normalized))
+        return normalized;
+    throw new Error(`Hermes distribution path is not allowed: ${filePath}`);
+}
+function safeSeedPath(filePath) {
+    if (filePath !== 'memories/USER.md' && filePath !== 'memories/MEMORY.md') {
+        throw new Error(`Hermes seed path is not allowed: ${filePath}`);
+    }
+    return filePath;
+}
+function validateHermesManifest(manifest) {
+    assertPlainObject(manifest, 'Hermes manifest');
+    if (manifest.schemaVersion !== 2)
+        throw new Error('Unsupported agent installer manifest. Update the Lattice CLI and try again.');
+    assertPlainObject(manifest.project, 'Hermes project');
+    if (!PROJECT_ID_PATTERN.test(manifest.project.id || ''))
+        throw new Error('Hermes installer manifest has an invalid project ID.');
+    if (typeof manifest.project.name !== 'string' || !manifest.project.name.trim())
+        throw new Error('Hermes installer manifest has an invalid project name.');
+    assertDate(manifest.project.createdAt, 'Hermes project createdAt');
+    assertPlainObject(manifest.install, 'Hermes install payload');
+    if (manifest.install.productType !== 'agent_setup' || manifest.install.runtime !== 'hermes') {
+        throw new Error('This project is not a Hermes agent setup. Use `lattice agent install --id <project-id>` to select its runtime automatically.');
+    }
+    assertPlainObject(manifest.install.release, 'Hermes release pin');
+    const release = manifest.install.release;
+    if (typeof release.tag !== 'string' || !/^v?[A-Za-z0-9][A-Za-z0-9.+-]{0,63}$/.test(release.tag))
+        throw new Error('Hermes release tag is invalid.');
+    if (release.packageVersion !== null && (typeof release.packageVersion !== 'string' || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(release.packageVersion))) {
+        throw new Error('Hermes package version is invalid.');
+    }
+    if (!COMMIT_PATTERN.test(release.commitSha))
+        throw new Error('Hermes release commit must be a full lowercase SHA.');
+    assertDate(release.publishedAt, 'Hermes release publishedAt');
+    assertDate(release.reviewedAt, 'Hermes release reviewedAt');
+    assertPlainObject(release.installScriptSha256, 'Hermes installer hashes');
+    if (!SHA256_PATTERN.test(release.installScriptSha256.windows) || !SHA256_PATTERN.test(release.installScriptSha256.posix)) {
+        throw new Error('Hermes installer hashes must be lowercase SHA-256 values.');
+    }
+    if (!PROFILE_PATTERN.test(manifest.install.profileName) || manifest.install.profileName === 'default') {
+        throw new Error('Hermes profile name must start with a lowercase letter, contain only lowercase letters, numbers, hyphens, or underscores, and cannot be "default".');
+    }
+    assertPlainObject(manifest.install.distributionFiles, 'Hermes distribution files');
+    for (const required of ['distribution.yaml', 'SOUL.md', 'config.yaml', 'README.md']) {
+        if (typeof manifest.install.distributionFiles[required] !== 'string')
+            throw new Error(`Hermes manifest is missing ${required}.`);
+    }
+    for (const [filePath, content] of Object.entries(manifest.install.distributionFiles)) {
+        safeDistributionPath(filePath);
+        if (typeof content !== 'string')
+            throw new Error(`Hermes distribution file is not text: ${filePath}`);
+        assertNoSecret(content, filePath);
+    }
+    assertPlainObject(manifest.install.localSeedFiles, 'Hermes local seed files');
+    for (const [filePath, content] of Object.entries(manifest.install.localSeedFiles)) {
+        safeSeedPath(filePath);
+        if (typeof content !== 'string')
+            throw new Error(`Hermes seed file is not text: ${filePath}`);
+        const limit = filePath === 'memories/USER.md' ? USER_MEMORY_LIMIT : AGENT_MEMORY_LIMIT;
+        if (characterCount(content) > limit)
+            throw new Error(`${filePath} exceeds Hermes' ${limit.toLocaleString('en-US')}-character limit.`);
+        assertNoSecret(content, filePath);
+    }
+    if (!Array.isArray(manifest.install.selectedChannels) || manifest.install.selectedChannels.some((item) => typeof item !== 'string' || !/^[a-z0-9_-]{1,40}$/.test(item))) {
+        throw new Error('Hermes selected channels are invalid.');
+    }
+    if (!['portal', 'byok', 'local', 'during_setup'].includes(manifest.install.providerSetup))
+        throw new Error('Hermes provider setup choice is invalid.');
+    if (!['local', 'docker', 'ssh', 'during_setup'].includes(manifest.install.terminalBackend))
+        throw new Error('Hermes terminal backend is invalid.');
+    if (typeof manifest.install.requestedGatewaySetup !== 'boolean')
+        throw new Error('Hermes gateway setup choice is invalid.');
+}
+function assertSupportedPlatform(runtime) {
+    if (!['win32', 'darwin', 'linux'].includes(runtime.platform)) {
+        throw new Error(`Hermes installation is not supported on ${runtime.platform}/${runtime.arch}. Use Windows 10/11, macOS, Linux, or WSL2.`);
+    }
+    if (!['x64', 'arm64'].includes(runtime.arch)) {
+        throw new Error(`Hermes installation is not supported on ${runtime.platform}/${runtime.arch}. Use an x64 or arm64 machine.`);
+    }
+}
+function resolveInside(root, relativePath) {
+    const target = (0, node_path_1.resolve)(root, relativePath);
+    const rel = (0, node_path_1.relative)((0, node_path_1.resolve)(root), target);
+    if (rel.startsWith('..') || (0, node_path_1.isAbsolute)(rel))
+        throw new Error(`Path escapes the managed directory: ${relativePath}`);
+    return target;
+}
+async function pathExists(filePath) {
+    try {
+        await node_fs_1.promises.lstat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function assertNoSymlinkPath(root, relativePath) {
+    let current = (0, node_path_1.resolve)(root);
+    for (const part of relativePath.replace(/\\/g, '/').split('/')) {
+        current = (0, node_path_1.join)(current, part);
+        try {
+            if ((await node_fs_1.promises.lstat(current)).isSymbolicLink())
+                throw new Error(`Refusing to write through symbolic link: ${current}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+}
+async function assertManagedPathHasNoSymlinks(root, target) {
+    const resolvedRoot = (0, node_path_1.resolve)(root);
+    const resolvedTarget = (0, node_path_1.resolve)(target);
+    const relativeTarget = (0, node_path_1.relative)(resolvedRoot, resolvedTarget);
+    if (relativeTarget.startsWith('..') || (0, node_path_1.isAbsolute)(relativeTarget)) {
+        throw new Error(`Managed target escapes its root: ${target}`);
+    }
+    try {
+        if ((await node_fs_1.promises.lstat(resolvedRoot)).isSymbolicLink()) {
+            throw new Error(`Refusing to use symbolic-link root: ${resolvedRoot}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await assertNoSymlinkPath(resolvedRoot, relativeTarget);
+}
+async function atomicWrite(filePath, content, mode = 0o600) {
+    await node_fs_1.promises.mkdir((0, node_path_1.dirname)(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.lattice-${process.pid}-${Date.now()}.tmp`;
+    await node_fs_1.promises.writeFile(temporary, content, { mode });
+    await node_fs_1.promises.rename(temporary, filePath);
+}
+async function writeExclusive(filePath, content, mode = 0o600) {
+    await node_fs_1.promises.mkdir((0, node_path_1.dirname)(filePath), { recursive: true, mode: 0o700 });
+    const handle = await node_fs_1.promises.open(filePath, 'wx', mode);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function snapshotFiles(root, paths, backupRoot) {
+    const existed = new Map();
+    for (const filePath of paths) {
+        await assertNoSymlinkPath(root, filePath);
+        const target = resolveInside(root, filePath);
+        const exists = await pathExists(target);
+        existed.set(filePath, exists);
+        if (exists) {
+            const backup = resolveInside(backupRoot, filePath);
+            await node_fs_1.promises.mkdir((0, node_path_1.dirname)(backup), { recursive: true, mode: 0o700 });
+            await node_fs_1.promises.copyFile(target, backup);
+        }
+    }
+    return { root, backupRoot, existed };
+}
+async function restoreSnapshot(snapshot) {
+    for (const [filePath, existed] of [...snapshot.existed.entries()].reverse()) {
+        const target = resolveInside(snapshot.root, filePath);
+        if (existed) {
+            await node_fs_1.promises.mkdir((0, node_path_1.dirname)(target), { recursive: true, mode: 0o700 });
+            await node_fs_1.promises.copyFile(resolveInside(snapshot.backupRoot, filePath), target);
+        }
+        else {
+            await node_fs_1.promises.rm(target, { force: true });
+        }
+    }
+}
+function sanitizeCommandDiagnostic(value) {
+    return String(value || '')
+        .replace(/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, '[redacted private key]')
+        .replace(/\b(Bearer\s+)[^\s]+/gi, '$1[redacted]')
+        .replace(/\b((?:api[_-]?key|access[_-]?token|password|client[_-]?secret|authorization)\s*[:=]\s*)["']?[^\s"']+/gi, '$1[redacted]')
+        .replace(/\b(?:sk|ghp|github_pat|xox[baprs])-[-A-Za-z0-9_]{12,}\b/g, '[redacted token]')
+        .trim()
+        .slice(-2_000);
+}
+function requireSuccess(runtime, command, args, label, quiet = false, env, controls) {
+    const result = runtime.run(command, args, { quiet, env, ...controls });
+    if (result.status !== 0) {
+        const detail = sanitizeCommandDiagnostic([result.error?.message, result.stderr].filter(Boolean).join('\n'));
+        const status = result.status === null ? '' : ` (exit ${result.status})`;
+        throw new Error(`${label} failed${status}${detail ? `: ${detail}` : ''}.`);
+    }
+    return { stdout: result.stdout, stderr: result.stderr };
+}
+function hermesVersionsFromOfficialHeaders(value) {
+    const versions = [];
+    for (const line of String(value || '').split(/\r?\n/)) {
+        const match = line.match(/^Hermes Agent v(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)(?=$|[\s(·])/);
+        if (match)
+            versions.push(match[1]);
+    }
+    return versions;
+}
+function formatHermesVersionStream(label, value) {
+    const detail = sanitizeCommandDiagnostic(value);
+    return `${label}: ${detail || '(empty)'}`;
+}
+async function resolveInstalledHermesGit(hermesHome, platform) {
+    if (platform !== 'win32')
+        return 'git';
+    const toolsDirectory = (0, node_path_1.join)(hermesHome, 'tools');
+    try {
+        const facts = parseJsonWithOptionalBom(await node_fs_1.promises.readFile((0, node_path_1.join)(toolsDirectory, 'facts.json'), 'utf8'), 'Hermes tool facts');
+        assertPlainObject(facts, 'Hermes tool facts');
+        assertPlainObject(facts.packages, 'Hermes tool packages');
+        const git = facts.packages.git;
+        if (git && typeof git === 'object' && !Array.isArray(git)) {
+            const entry = git.entry;
+            if (typeof entry === 'string' && entry) {
+                const managedGit = resolveInside(toolsDirectory, (0, node_path_1.join)(entry, 'cmd', 'git.exe'));
+                await assertManagedPathHasNoSymlinks(hermesHome, managedGit);
+                await node_fs_1.promises.access(managedGit, node_fs_1.constants.X_OK);
+                return managedGit;
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Hermes installed Git metadata is invalid: ${error.message}`);
+        }
+    }
+    return 'git';
+}
+async function resolveVerifiedHermesCommand(hermesHome, platform) {
+    const installDirectory = (0, node_path_1.join)(hermesHome, 'hermes-agent');
+    const managedCommand = (0, node_path_1.join)(installDirectory, '.hermes', 'bin', platform === 'win32' ? 'hermes.exe' : 'hermes');
+    await assertManagedPathHasNoSymlinks(installDirectory, managedCommand);
+    try {
+        const entry = await node_fs_1.promises.lstat(managedCommand);
+        if (!entry.isFile())
+            throw new Error(`Managed Hermes launcher is not a regular file: ${managedCommand}.`);
+        await node_fs_1.promises.access(managedCommand, node_fs_1.constants.X_OK);
+        return managedCommand;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Official Hermes installation did not publish its managed launcher: ${managedCommand}.`);
+        }
+        throw error;
+    }
+}
+const GIT_PROVENANCE_ENV_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
+const GIT_METADATA_TIMEOUT_MS = 15_000;
+const GIT_FETCH_TIMEOUT_MS = 90_000;
+// A fresh managed Python environment can take longer to initialize on native CI.
+const HERMES_VERSION_TIMEOUT_MS = 60_000;
+function requireExactGitOutput(runtime, gitCommand, installDirectory, args, expected, label, env) {
+    const output = requireSuccess(runtime, gitCommand, ['-C', installDirectory, ...args], label, true, { ...env, GIT_TERMINAL_PROMPT: '0' }, { timeoutMs: GIT_METADATA_TIMEOUT_MS, unsetEnv: [...GIT_PROVENANCE_ENV_KEYS] });
+    const observed = String(output.stdout || '').trim().toLowerCase();
+    if (observed !== expected.toLowerCase()) {
+        throw new Error(`${label} returned ${sanitizeCommandDiagnostic(observed) || '(empty)'}; expected ${expected}.`);
+    }
+}
+async function reconcileInstalledHermesRelease(release, hermesHome, setupRoot, backupDirectory, runtime, env) {
+    const installDirectory = (0, node_path_1.join)(hermesHome, 'hermes-agent');
+    await assertManagedPathHasNoSymlinks(hermesHome, installDirectory);
+    await assertNoSymlinkPath(installDirectory, 'install-stamp.json');
+    const gitCommand = await resolveInstalledHermesGit(hermesHome, runtime.platform);
+    const pinnedCommit = release.commitSha.toLowerCase();
+    requireExactGitOutput(runtime, gitCommand, installDirectory, ['rev-parse', '--verify', 'HEAD^{commit}'], pinnedCommit, 'Hermes checkout verification', env);
+    const gitEnv = { ...env, GIT_TERMINAL_PROMPT: '0' };
+    const metadataControls = { timeoutMs: GIT_METADATA_TIMEOUT_MS, unsetEnv: [...GIT_PROVENANCE_ENV_KEYS] };
+    requireSuccess(runtime, gitCommand, ['-C', installDirectory, 'diff', '--quiet', '--no-ext-diff', 'HEAD', '--'], 'Hermes tracked-source verification', true, gitEnv, metadataControls);
+    requireSuccess(runtime, gitCommand, ['-C', installDirectory, 'diff', '--cached', '--quiet', '--no-ext-diff', '--'], 'Hermes staged-source verification', true, gitEnv, metadataControls);
+    requireSuccess(runtime, gitCommand, [
+        '-C', installDirectory, 'fetch', '--no-tags', OFFICIAL_HERMES_REPOSITORY,
+        `refs/tags/${release.tag}:refs/tags/${release.tag}`,
+    ], 'Official Hermes release tag fetch', true, gitEnv, {
+        timeoutMs: GIT_FETCH_TIMEOUT_MS,
+        unsetEnv: [...GIT_PROVENANCE_ENV_KEYS],
+    });
+    requireExactGitOutput(runtime, gitCommand, installDirectory, ['rev-parse', '--verify', `refs/tags/${release.tag}^{commit}`], pinnedCommit, 'Hermes release tag verification', env);
+    requireExactGitOutput(runtime, gitCommand, installDirectory, ['rev-parse', '--verify', 'HEAD^{commit}'], pinnedCommit, 'Hermes checkout re-verification', env);
+    const stampPath = (0, node_path_1.join)(installDirectory, 'install-stamp.json');
+    let stamp;
+    let stampBytes;
+    try {
+        stampBytes = await node_fs_1.promises.readFile(stampPath);
+        const parsed = parseJsonWithOptionalBom(stampBytes.toString('utf8'), 'Hermes install stamp');
+        assertPlainObject(parsed, 'Hermes install stamp');
+        stamp = parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new Error(`Hermes install stamp is invalid: ${error.message}`);
+    }
+    if (String(stamp.commit || '').toLowerCase() !== pinnedCommit || stamp.source !== 'git' || stamp.updateMechanism !== 'self') {
+        throw new Error('Hermes install stamp does not describe the verified source checkout.');
+    }
+    if (stamp.schemaVersion !== 2 || stamp.payload !== 'bootstrap' || stamp.distribution !== null || stamp.tag !== null) {
+        throw new Error('Hermes install stamp is not a recognized source-generated identity.');
+    }
+    if (release.packageVersion && (stamp.baseVersion !== release.packageVersion
+        || stamp.displayVersion !== release.packageVersion
+        || stamp.distance !== 0)) {
+        const backupPath = (0, node_path_1.join)(backupDirectory, 'runtime-identity', 'install-stamp.json');
+        await assertManagedPathHasNoSymlinks(setupRoot, backupPath);
+        await writeExclusive(backupPath, stampBytes);
+        await node_fs_1.promises.rm(stampPath);
+        runtime.log(`Reconciled Hermes ${release.tag} source identity from its verified official tag.`);
+        return backupPath;
+    }
+    return null;
+}
+async function resolveHermesCommand(hermesHome, platform, explicitCommand) {
+    if (explicitCommand)
+        return explicitCommand;
+    const installDirectory = (0, node_path_1.join)(hermesHome, 'hermes-agent');
+    const candidates = platform === 'win32'
+        ? [
+            (0, node_path_1.join)(installDirectory, '.hermes', 'bin', 'hermes.exe'),
+            (0, node_path_1.join)(hermesHome, 'bin', 'hermes.exe'),
+            (0, node_path_1.join)(installDirectory, 'venv', 'Scripts', 'hermes.exe'),
+        ]
+        : [
+            (0, node_path_1.join)(installDirectory, '.hermes', 'bin', 'hermes'),
+            (0, node_path_1.join)(hermesHome, 'bin', 'hermes'),
+            (0, node_path_1.join)(installDirectory, 'venv', 'bin', 'hermes'),
+        ];
+    for (const candidate of candidates) {
+        try {
+            await node_fs_1.promises.access(candidate, node_fs_1.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Continue through the bounded official managed and legacy layouts.
+        }
+    }
+    throw new Error(`Hermes command was not published under the requested Hermes home: ${hermesHome}.`);
+}
+function buildResumeCommand(projectId, profileName) {
+    return `npx --yes latticeai@latest hermes install --id ${projectId} --profile-name ${profileName} --update-existing-profile`;
+}
+function sanitizeFailureStage(value) {
+    return value.replace(/[^a-z0-9_-]/gi, '-').slice(0, 80);
+}
+async function installHermes(manifest, options = {}, runtime = defaultRuntime) {
+    validateHermesManifest(manifest);
+    assertSupportedPlatform(runtime);
+    if (!options.dryRun && !options.skipHermesInstall && options.hermesCommand) {
+        throw new Error('An explicit Hermes command requires --skip-hermes-install; a managed official install must verify its own launcher.');
+    }
+    const profileName = options.profileName || manifest.install.profileName;
+    if (!PROFILE_PATTERN.test(profileName) || profileName === 'default')
+        throw new Error(`Unsafe Hermes profile name: ${profileName}`);
+    const hermesHome = (0, node_path_1.resolve)(options.hermesHome || process.env.HERMES_HOME || (runtime.platform === 'win32'
+        ? (0, node_path_1.join)(runtime.localAppData || (0, node_path_1.join)(runtime.homeDir, 'AppData', 'Local'), 'hermes')
+        : (0, node_path_1.join)(runtime.homeDir, '.hermes')));
+    const hermesEnv = { HERMES_HOME: hermesHome };
+    const setupRoot = (0, node_path_1.resolve)(runtime.homeDir, '.lattice', 'agent-setups', manifest.project.id);
+    const distributionDirectory = (0, node_path_1.join)(setupRoot, 'hermes-distribution');
+    const profileDirectory = (0, node_path_1.join)(hermesHome, 'profiles', profileName);
+    const timestamp = runtime.now().toISOString().replace(/[:.]/g, '-');
+    const backupDirectory = (0, node_path_1.join)(setupRoot, 'backups', timestamp);
+    const distributionFiles = Object.keys(manifest.install.distributionFiles).map(safeDistributionPath).sort();
+    const seedFiles = Object.keys(manifest.install.localSeedFiles).map(safeSeedPath).sort();
+    const resumeCommand = buildResumeCommand(manifest.project.id, profileName);
+    const receiptPath = (0, node_path_1.join)(setupRoot, 'receipt.json');
+    const receipt = {
+        schemaVersion: 1,
+        projectId: manifest.project.id,
+        runtime: 'hermes',
+        stage: options.dryRun ? 'planned' : 'installed',
+        release: {
+            tag: manifest.install.release.tag,
+            packageVersion: manifest.install.release.packageVersion,
+            commitSha: manifest.install.release.commitSha,
+        },
+        profileName,
+        distributionDirectory,
+        profileDirectory,
+        backupDirectory: options.dryRun ? null : backupDirectory,
+        runtimeIdentityBackup: null,
+        filesApplied: distributionFiles,
+        seedFilesApplied: seedFiles,
+        selectedChannels: [...manifest.install.selectedChannels],
+        dryRun: !!options.dryRun,
+        setupRequired: !!options.skipSetup,
+        modelCheckRequired: !!options.skipSetup || !!options.skipModelCheck,
+        gatewaySetupRequired: manifest.install.requestedGatewaySetup && (!!options.skipSetup || !!options.skipModelCheck || !!options.skipGatewaySetup),
+        resumeCommand,
+        completedAt: null,
+    };
+    if (options.dryRun) {
+        runtime.log(`Dry run: would install Hermes ${manifest.install.release.tag}, create profile ${profileName}, write ${distributionFiles.length} distribution files and ${seedFiles.length} local seed files.`);
+        return receipt;
+    }
+    await node_fs_1.promises.mkdir(setupRoot, { recursive: true, mode: 0o700 });
+    await atomicWrite(receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+    const snapshots = [];
+    let failedStage = 'runtime-install';
+    let temporaryScript;
+    let verifiedHermesCommand;
+    try {
+        if (!options.skipHermesInstall) {
+            const isWindows = runtime.platform === 'win32';
+            const installerPath = isWindows ? OFFICIAL_INSTALLER_PATHS.windows : OFFICIAL_INSTALLER_PATHS.posix;
+            const url = `https://raw.githubusercontent.com/NousResearch/hermes-agent/${manifest.install.release.commitSha}/${installerPath}`;
+            const expectedHash = isWindows
+                ? manifest.install.release.installScriptSha256.windows
+                : manifest.install.release.installScriptSha256.posix;
+            const installer = await runtime.download(url);
+            const actualHash = (0, node_crypto_1.createHash)('sha256').update(installer).digest('hex');
+            if (actualHash !== expectedHash)
+                throw new Error(`Hermes installer integrity check failed. Expected ${expectedHash}, received ${actualHash}. The script was not executed.`);
+            const scriptDirectory = (0, node_path_1.join)(runtime.tempDir, `lattice-hermes-${manifest.project.id}-${timestamp}`);
+            temporaryScript = (0, node_path_1.join)(scriptDirectory, isWindows ? 'install.ps1' : 'install.sh');
+            await atomicWrite(temporaryScript, installer, isWindows ? 0o600 : 0o700);
+            if (isWindows) {
+                requireSuccess(runtime, 'powershell.exe', [
+                    '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', temporaryScript,
+                    '-Commit', manifest.install.release.commitSha, '-NonInteractive', '-SkipSetup',
+                    '-HermesHome', hermesHome, '-InstallDir', (0, node_path_1.join)(hermesHome, 'hermes-agent'),
+                ], 'Official Hermes installation', false, hermesEnv);
+            }
+            else {
+                requireSuccess(runtime, 'bash', [
+                    temporaryScript, '--commit', manifest.install.release.commitSha,
+                    '--non-interactive', '--skip-setup', '--hermes-home', hermesHome,
+                    '--dir', (0, node_path_1.join)(hermesHome, 'hermes-agent'),
+                ], 'Official Hermes installation', false, hermesEnv);
+            }
+            failedStage = 'runtime-provenance';
+            receipt.runtimeIdentityBackup = await reconcileInstalledHermesRelease(manifest.install.release, hermesHome, setupRoot, backupDirectory, runtime, hermesEnv);
+            verifiedHermesCommand = await resolveVerifiedHermesCommand(hermesHome, runtime.platform);
+        }
+        failedStage = 'runtime-command';
+        const hermesCommand = verifiedHermesCommand
+            || await resolveHermesCommand(hermesHome, runtime.platform, options.hermesCommand);
+        failedStage = 'runtime-version';
+        const versionOutput = requireSuccess(runtime, hermesCommand, ['--version'], 'Hermes version check', true, hermesEnv, { timeoutMs: HERMES_VERSION_TIMEOUT_MS, unsetEnv: [...GIT_PROVENANCE_ENV_KEYS] });
+        const expectedVersion = manifest.install.release.packageVersion;
+        if (expectedVersion) {
+            const observedVersions = new Set([
+                ...hermesVersionsFromOfficialHeaders(versionOutput.stdout),
+                ...hermesVersionsFromOfficialHeaders(versionOutput.stderr),
+            ]);
+            if (observedVersions.size !== 1 || !observedVersions.has(expectedVersion)) {
+                const diagnostics = [
+                    formatHermesVersionStream('stdout', versionOutput.stdout),
+                    formatHermesVersionStream('stderr', versionOutput.stderr),
+                ].join('\n');
+                throw new Error(`Hermes version check returned an unexpected release. Expected ${expectedVersion}.\n${diagnostics}`);
+            }
+        }
+        failedStage = 'profile-conflict';
+        const existingProfile = runtime.run(hermesCommand, ['profile', 'show', profileName], { quiet: true, env: hermesEnv }).status === 0;
+        if (existingProfile && !options.updateExistingProfile) {
+            throw new Error(`Hermes profile "${profileName}" already exists. Re-run with --profile-name <new-name>, or review the generated files and explicitly use --update-existing-profile.`);
+        }
+        failedStage = 'backup';
+        await assertManagedPathHasNoSymlinks(setupRoot, distributionDirectory);
+        await assertManagedPathHasNoSymlinks(hermesHome, profileDirectory);
+        snapshots.push(await snapshotFiles(distributionDirectory, distributionFiles, (0, node_path_1.join)(backupDirectory, 'distribution')));
+        snapshots.push(await snapshotFiles(profileDirectory, [...distributionFiles, ...seedFiles], (0, node_path_1.join)(backupDirectory, 'profile')));
+        failedStage = 'distribution-write';
+        for (const filePath of distributionFiles) {
+            await atomicWrite(resolveInside(distributionDirectory, filePath), manifest.install.distributionFiles[filePath]);
+            runtime.log(`Prepared ${filePath}`);
+        }
+        failedStage = 'profile-install';
+        const profileArgs = ['profile', 'install', distributionDirectory, '--name', profileName, '--alias', '--yes'];
+        if (existingProfile && options.updateExistingProfile)
+            profileArgs.push('--force');
+        requireSuccess(runtime, hermesCommand, profileArgs, 'Hermes profile installation', false, hermesEnv);
+        failedStage = 'seed-files';
+        for (const filePath of seedFiles) {
+            await atomicWrite(resolveInside(profileDirectory, filePath), manifest.install.localSeedFiles[filePath]);
+            runtime.log(`Applied local ${filePath}`);
+        }
+        failedStage = 'config-check';
+        requireSuccess(runtime, hermesCommand, ['-p', profileName, 'config', 'check'], 'Hermes configuration check', false, hermesEnv);
+        if (!options.skipSetup) {
+            failedStage = 'provider-setup';
+            const setupArgs = ['-p', profileName, 'setup'];
+            if (manifest.install.providerSetup === 'portal')
+                setupArgs.push('--portal');
+            requireSuccess(runtime, hermesCommand, setupArgs, 'Official Hermes provider setup', false, hermesEnv);
+            receipt.stage = 'configured';
+            receipt.setupRequired = false;
+            if (!options.skipModelCheck) {
+                failedStage = 'model-check';
+                runtime.log('Running one brief Hermes model check. This may use a small amount of your selected provider quota.');
+                requireSuccess(runtime, hermesCommand, ['-p', profileName, 'chat', '-q', 'Reply with READY.'], 'Hermes model check', false, hermesEnv);
+                receipt.modelCheckRequired = false;
+            }
+        }
+        if (manifest.install.requestedGatewaySetup && !receipt.setupRequired && !receipt.modelCheckRequired && !options.skipGatewaySetup) {
+            failedStage = 'gateway-setup';
+            requireSuccess(runtime, hermesCommand, ['-p', profileName, 'gateway', 'setup'], 'Official Hermes gateway setup', false, hermesEnv);
+            requireSuccess(runtime, hermesCommand, ['-p', profileName, 'gateway', 'status'], 'Hermes gateway status', false, hermesEnv);
+            receipt.stage = 'connected';
+            receipt.gatewaySetupRequired = false;
+        }
+        // Doctor includes credential and provider checks. A deliberately staged
+        // installation must retain its valid profile and report the remaining work.
+        if (!receipt.setupRequired && !receipt.modelCheckRequired && !receipt.gatewaySetupRequired) {
+            failedStage = 'doctor';
+            requireSuccess(runtime, hermesCommand, ['doctor'], 'Hermes doctor', false, hermesEnv);
+        }
+        else {
+            runtime.log('Profile installed and configuration checked. Complete the remaining provider/model/gateway setup, then run hermes doctor. This setup is not yet verified.');
+        }
+        requireSuccess(runtime, hermesCommand, ['profile', 'show', profileName], 'Hermes profile verification', false, hermesEnv);
+        if (!receipt.setupRequired && !receipt.modelCheckRequired && !receipt.gatewaySetupRequired)
+            receipt.stage = 'verified';
+        receipt.completedAt = runtime.now().toISOString();
+        await atomicWrite(receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+        return receipt;
+    }
+    catch (error) {
+        for (const snapshot of [...snapshots].reverse())
+            await restoreSnapshot(snapshot);
+        receipt.stage = 'failed';
+        receipt.failedStage = sanitizeFailureStage(failedStage);
+        receipt.completedAt = runtime.now().toISOString();
+        await atomicWrite(receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${message} Lattice-owned distribution and seed files were restored to their pre-install state. Hermes runtime installation, profile registration or alias changes, provider or credential setup, model usage, and gateway or service changes are not automatically reverted; review them before retrying. Backup: ${backupDirectory}. Resume with: ${resumeCommand}`);
+    }
+    finally {
+        if (temporaryScript)
+            await node_fs_1.promises.rm((0, node_path_1.dirname)(temporaryScript), { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=hermes-install.js.map