freestyle-sync 0.1.0

package/src/main.ts

@@ -0,0 +1,1136 @@
+#!/usr/bin/env node
+import "dotenv/config"
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { freestyle } from "freestyle";
+import config from "../freestyle-sync.config.ts";
+import type { CliOptions, ContextCandidate, PushvmPluginUtils, RemoteVm } from "./plugin-api.ts";
+export * from "./plugin-api.ts";
+
+const execFileAsync = promisify(execFile);
+
+const CACHE_VERSION = 1;
+const PLUGIN_PREFERENCES_VERSION = 1;
+const ARCHIVE_CHUNK_CHARS = 1024 * 1024;
+let plugins = config.plugins;
+const pluginUtils: PushvmPluginUtils = {
+    checkedExec,
+    createTar,
+    uploadArchiveInChunks,
+    execFileAsync,
+    shellQuote,
+    md5,
+    delay,
+};
+
+type FileKind = "file" | "symlink";
+
+type FileDigest = {
+    hash: string;
+    kind: FileKind;
+    mode: number;
+    size: number;
+};
+
+type LocalEntry = FileDigest & {
+    absolutePath: string;
+    relativePath: string;
+};
+
+type CacheFile = {
+    version: number;
+    projectRoot: string;
+    remoteProjectDir: string;
+    vmId?: string;
+    snapshotId?: string;
+    projectFiles: Record<string, FileDigest>;
+    contextFiles: Record<string, FileDigest>;
+    snapshotProjectFiles?: Record<string, FileDigest>;
+    snapshotContextFiles?: Record<string, FileDigest>;
+    envHash?: string;
+    snapshotEnvHash?: string;
+    updatedAt?: string;
+};
+
+type PluginPreferences = {
+    version: number;
+    disabledPlugins: string[];
+    updatedAt?: string;
+};
+
+type ContextEntry = LocalEntry & {
+    remotePath: string;
+    label: string;
+    sensitive: boolean;
+};
+
+type SyncResult = {
+    uploaded: number;
+    removed: number;
+    unchanged: number;
+};
+
+class Progress {
+    private current = 0;
+    private readonly total: number;
+
+    constructor(total: number) {
+        this.total = total;
+    }
+
+    step(message: string) {
+        this.current += 1;
+        console.log(`[${this.current}/${this.total}] ${message}`);
+    }
+}
+
+main().catch((error) => {
+    console.error(`vmpush: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});
+
+async function main() {
+    const options = await parseArgs(process.argv.slice(2));
+    const pluginPreferences = await updatePluginPreferences(options);
+    plugins = activePlugins(pluginPreferences, options);
+    if (options.listPlugins) {
+        printPlugins(pluginPreferences, options);
+        return;
+    }
+    const progress = new Progress(options.dryRun ? 2 : options.install ? 12 : 11);
+
+    if (options.dryRun) {
+        console.log("vmpush dry run");
+    }
+
+    progress.step("Scanning project files");
+    const cache = await readCache(options.cachePath, options);
+    const base = cacheBaseForSync(options, cache);
+    const projectEntries = await scanProject(options.projectRoot, options.includeGitDir);
+    const projectCurrent = digestMap(projectEntries);
+    const projectChanges = diffEntries(projectEntries, base.projectFiles);
+
+    progress.step("Detecting auth and agent context");
+    let envExports = collectPluginEnvironment(options);
+    let contextCandidates = await discoverPluginContextCandidates(options);
+    const envHash = hashString(renderEnvFile(envExports));
+
+    const contextEntries = await scanContextCandidates(contextCandidates);
+    const contextCurrent = digestMapByRemotePath(contextEntries);
+    const contextChanges = diffContextEntries(contextEntries, base.contextFiles);
+
+    printPlan(options, projectChanges, contextChanges, envExports, cache);
+
+    if (options.dryRun) {
+        return;
+    }
+
+    progress.step("Preparing Freestyle VM");
+    const { vm, vmId } = await getOrCreateVm(options, cache.snapshotId);
+    console.log(`Uploading to VM: ${vmId}`);
+
+    progress.step(`Uploading project changes to ${vmId}`);
+    await ensureRemoteBase(vm, options.remoteProjectDir);
+    const projectResult = await syncProject(vm, vmId, options, projectChanges);
+
+    progress.step(`Running remote fixups on ${vmId}`);
+    await runRemoteFixups(vm, vmId, options);
+
+    progress.step(`Uploading auth/context changes to ${vmId}`);
+    const contextResult = await syncContext(vm, vmId, contextChanges);
+    await runAfterContextSyncPlugins(vm, vmId, options, contextChanges.changed.map((entry) => entry.remotePath));
+
+    progress.step(`Installing environment files on ${vmId}`);
+    await installEnvironment(vm, envExports, envHash, base.envHash);
+
+    progress.step(`Writing resume metadata on ${vmId}`);
+    await writeRemoteResumeFiles(vm, options, vmId, envExports);
+    await hardenRemoteRoot(vm);
+
+    if (options.install) {
+        progress.step(`Running install command on ${vmId}`);
+        await runInstall(vm, options.projectRoot, options.remoteProjectDir);
+    }
+
+    let snapshotId = cache.snapshotId;
+    let snapshotProjectFiles = cache.snapshotProjectFiles;
+    let snapshotContextFiles = cache.snapshotContextFiles;
+    let snapshotEnvHash = cache.snapshotEnvHash;
+    if (options.snapshot) {
+        progress.step(`Creating snapshot cache for ${vmId}`);
+        await runBeforeSnapshotPlugins(vm, vmId, options);
+        try {
+            const snapshot = await vm.snapshot({ name: `vmpush-${path.basename(options.projectRoot)}-${Date.now()}` });
+            snapshotId = snapshot.snapshotId;
+            snapshotProjectFiles = projectCurrent;
+            snapshotContextFiles = contextCurrent;
+            snapshotEnvHash = envHash;
+        } catch (error) {
+            console.warn(`Snapshot cache skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    } else {
+        progress.step("Skipping snapshot cache");
+    }
+
+    progress.step("Saving local sync cache");
+    await writeCache(options.cachePath, {
+        version: CACHE_VERSION,
+        projectRoot: options.projectRoot,
+        remoteProjectDir: options.remoteProjectDir,
+        vmId,
+        snapshotId,
+        projectFiles: projectCurrent,
+        contextFiles: contextCurrent,
+        snapshotProjectFiles,
+        snapshotContextFiles,
+        envHash,
+        snapshotEnvHash,
+        updatedAt: new Date().toISOString(),
+    });
+
+    progress.step(`Running post-sync plugins for ${vmId}`);
+    const postSyncMessages = await runAfterSyncPlugins(vm, vmId, options, contextCandidates);
+
+    console.log("");
+    console.log(`VM ready: ${vmId}`);
+    console.log(`Project: ${options.remoteProjectDir}`);
+    console.log(`Project files: ${projectResult.uploaded} uploaded, ${projectResult.removed} removed, ${projectResult.unchanged} unchanged`);
+    console.log(`Context files: ${contextResult.uploaded} uploaded, ${contextResult.unchanged} unchanged`);
+    if (snapshotId) {
+        console.log(`Snapshot cache: ${snapshotId}`);
+    }
+    for (const message of postSyncMessages) console.log(message);
+    console.log(`SSH: npx freestyle vm ssh ${vmId}`);
+    if (options.autoSsh) {
+        const connected = await runConnectPlugins(vm, vmId, options, contextCandidates);
+        if (!connected) await sshIntoVm(vmId);
+    }
+}
+
+async function parseArgs(args: string[]): Promise<CliOptions> {
+    const options: CliOptions = {
+        projectRoot: process.cwd(),
+        cachePath: "",
+        remoteProjectDir: "",
+        name: "",
+        yes: false,
+        dryRun: false,
+        disablePlugins: [],
+        enablePlugins: [],
+        resetPluginPrefs: false,
+        listPlugins: false,
+        includeAuth: true,
+        includeAgentContext: true,
+        includeGitDir: true,
+        includeAllCopilotWorkspaces: false,
+        snapshot: true,
+        install: false,
+        autoSsh: true,
+        envKeys: [],
+    };
+
+    const positional: string[] = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        } else if (arg === "--yes" || arg === "-y") {
+            options.yes = true;
+        } else if (arg === "--dry-run") {
+            options.dryRun = true;
+        } else if (arg === "--disable-plugin") {
+            options.disablePlugins.push(readOptionValue(args, ++index, arg));
+        } else if (arg === "--enable-plugin") {
+            options.enablePlugins.push(readOptionValue(args, ++index, arg));
+        } else if (arg === "--reset-plugin-prefs" || arg === "--reset-context-prefs") {
+            options.resetPluginPrefs = true;
+        } else if (arg === "--list-plugins") {
+            options.listPlugins = true;
+        } else if (arg === "--no-auth") {
+            options.includeAuth = false;
+        } else if (arg === "--no-agent-context") {
+            options.includeAgentContext = false;
+        } else if (arg === "--no-git-dir") {
+            options.includeGitDir = false;
+        } else if (arg === "--all-copilot-workspaces") {
+            options.includeAllCopilotWorkspaces = true;
+        } else if (arg === "--no-snapshot" || arg === "--skip-snapshot") {
+            options.snapshot = false;
+        } else if (arg === "--install") {
+            options.install = true;
+        } else if (arg === "--no-ssh") {
+            options.autoSsh = false;
+        } else if (arg === "--vm-id") {
+            options.vmId = readOptionValue(args, ++index, arg);
+        } else if (arg === "--name") {
+            options.name = readOptionValue(args, ++index, arg);
+        } else if (arg === "--remote-dir") {
+            options.remoteProjectDir = normalizeRemotePath(readOptionValue(args, ++index, arg));
+        } else if (arg === "--cache") {
+            options.cachePath = path.resolve(readOptionValue(args, ++index, arg));
+        } else if (arg === "--idle-timeout") {
+            options.idleTimeoutSeconds = Number(readOptionValue(args, ++index, arg));
+            if (!Number.isInteger(options.idleTimeoutSeconds) || options.idleTimeoutSeconds < 1) {
+                throw new Error("--idle-timeout must be a positive integer");
+            }
+        } else if (arg === "--include-env") {
+            options.envKeys.push(readOptionValue(args, ++index, arg));
+        } else if (arg.startsWith("--")) {
+            throw new Error(`unknown option: ${arg}`);
+        } else {
+            positional.push(arg);
+        }
+    }
+
+    if (positional.length > 1) {
+        throw new Error("expected at most one project path");
+    }
+
+    options.projectRoot = path.resolve(positional[0] ?? options.projectRoot);
+    const projectStats = await stat(options.projectRoot).catch(() => null);
+    if (!projectStats?.isDirectory()) {
+        throw new Error(`project path is not a directory: ${options.projectRoot}`);
+    }
+
+    const projectName = sanitizeName(path.basename(options.projectRoot));
+    options.name ||= `vmpush-${projectName}`;
+    options.remoteProjectDir ||= defaultRemoteProjectDir(options.projectRoot);
+    options.cachePath ||= path.join(options.projectRoot, ".freestyle-sync", "cache.json");
+
+    return options;
+}
+
+function printHelp() {
+    console.log(`vmpush uploads the current project into a Freestyle VM.
+
+Usage:
+	vmpush [project-dir] [options]
+
+Options:
+	--vm-id <id>             Sync into an existing Freestyle VM.
+	--name <name>            Name for a newly created VM. Defaults to vmpush-<project>.
+    --remote-dir <path>      Remote project directory. Defaults to the local absolute path.
+    --cache <path>           Snapshot/hash cache path. Defaults to .freestyle-sync/cache.json.
+	--include-env <name>     Always copy an environment variable. Repeatable.
+    --disable-plugin <name>  Disable a plugin for this project and save the preference. Repeatable.
+    --enable-plugin <name>   Re-enable a previously disabled plugin and save the preference. Repeatable.
+    --reset-plugin-prefs     Clear saved plugin enable/disable preferences.
+    --list-plugins           Show configured plugins and whether they are enabled.
+	--install                Run detected dependency install command after sync.
+    --no-ssh                 Do not automatically open VS Code/Cursor or SSH after sync.
+	--idle-timeout <seconds> Set VM idle timeout when creating/starting.
+    --no-auth                Disable auth plugins for this run.
+    --no-agent-context       Disable agent context plugins for this run.
+	--no-git-dir             Exclude the local .git directory from project sync.
+    --all-copilot-workspaces Include Copilot chat state for every VS Code workspace.
+    --no-snapshot, --skip-snapshot
+                             Do not snapshot the VM after sync.
+	--dry-run                Show what would sync without creating or changing a VM.
+    -y, --yes                Deprecated; accepted for compatibility.
+	-h, --help               Show this help.
+`);
+}
+
+function readOptionValue(args: string[], index: number, option: string) {
+    const value = args[index];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${option} requires a value`);
+    }
+    return value;
+}
+
+async function readCache(cachePath: string, options: CliOptions): Promise<CacheFile> {
+    try {
+        const parsed = JSON.parse(await readFile(cachePath, "utf8")) as CacheFile;
+        if (parsed.version === CACHE_VERSION && parsed.projectRoot === options.projectRoot && parsed.remoteProjectDir === options.remoteProjectDir) {
+            return {
+                ...parsed,
+                projectFiles: parsed.projectFiles ?? {},
+                contextFiles: parsed.contextFiles ?? {},
+                snapshotProjectFiles: parsed.snapshotProjectFiles,
+                snapshotContextFiles: parsed.snapshotContextFiles,
+            };
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+            console.warn(`Ignoring unreadable cache ${cachePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    return {
+        version: CACHE_VERSION,
+        projectRoot: options.projectRoot,
+        remoteProjectDir: options.remoteProjectDir,
+        projectFiles: {},
+        contextFiles: {},
+    };
+}
+
+function cacheBaseForSync(options: CliOptions, cache: CacheFile): { projectFiles: Record<string, FileDigest>; contextFiles: Record<string, FileDigest>; envHash?: string } {
+    if (options.vmId && options.vmId === cache.vmId) {
+        return {
+            projectFiles: cache.projectFiles,
+            contextFiles: cache.contextFiles,
+            envHash: cache.envHash,
+        };
+    }
+
+    if (!options.vmId && cache.snapshotId) {
+        return {
+            projectFiles: cache.snapshotProjectFiles ?? {},
+            contextFiles: cache.snapshotContextFiles ?? {},
+            envHash: cache.snapshotEnvHash,
+        };
+    }
+
+    return { projectFiles: {}, contextFiles: {} };
+}
+
+async function writeCache(cachePath: string, cache: CacheFile) {
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+
+async function scanProject(projectRoot: string, includeGitDir: boolean): Promise<LocalEntry[]> {
+    const entries: LocalEntry[] = [];
+    await walk(projectRoot, "", entries, {
+        skipDirectory(relativePath, name) {
+            if (!includeGitDir && relativePath === ".git") return true;
+            return false;
+        },
+    });
+    return entries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+async function walk(
+    root: string,
+    relativePath: string,
+    entries: LocalEntry[],
+    options: { skipDirectory(relativePath: string, name: string): boolean },
+) {
+    const absolutePath = path.join(root, relativePath);
+    const dir = await import("node:fs/promises").then((fs) => fs.readdir(absolutePath, { withFileTypes: true }));
+
+    for (const dirent of dir) {
+        const childRelativePath = relativePath ? path.join(relativePath, dirent.name) : dirent.name;
+        const normalizedRelativePath = toPosix(childRelativePath);
+        const childAbsolutePath = path.join(root, childRelativePath);
+
+        if (dirent.isDirectory()) {
+            if (options.skipDirectory(normalizedRelativePath, dirent.name)) {
+                continue;
+            }
+            await walk(root, childRelativePath, entries, options);
+            continue;
+        }
+
+        if (dirent.isFile() || dirent.isSymbolicLink()) {
+            entries.push(await digestEntry(childAbsolutePath, normalizedRelativePath));
+        }
+    }
+}
+
+async function digestEntry(absolutePath: string, relativePath: string): Promise<LocalEntry> {
+    const stats = await import("node:fs/promises").then((fs) => fs.lstat(absolutePath));
+    if (stats.isSymbolicLink()) {
+        const target = await import("node:fs/promises").then((fs) => fs.readlink(absolutePath));
+        return {
+            absolutePath,
+            relativePath,
+            kind: "symlink",
+            mode: stats.mode,
+            size: target.length,
+            hash: hashString(`symlink:${target}`),
+        };
+    }
+
+    return {
+        absolutePath,
+        relativePath,
+        kind: "file",
+        mode: stats.mode,
+        size: stats.size,
+        hash: await hashFile(absolutePath),
+    };
+}
+
+function digestMap(entries: LocalEntry[]): Record<string, FileDigest> {
+    return Object.fromEntries(entries.map((entry) => [entry.relativePath, stripLocal(entry)]));
+}
+
+function digestMapByRemotePath(entries: ContextEntry[]): Record<string, FileDigest> {
+    return Object.fromEntries(entries.map((entry) => [entry.remotePath, stripLocal(entry)]));
+}
+
+function stripLocal(entry: LocalEntry): FileDigest {
+    return {
+        hash: entry.hash,
+        kind: entry.kind,
+        mode: entry.mode,
+        size: entry.size,
+    };
+}
+
+function diffEntries(entries: LocalEntry[], previous: Record<string, FileDigest>) {
+    const changed = entries.filter((entry) => previous[entry.relativePath]?.hash !== entry.hash);
+    const currentKeys = new Set(entries.map((entry) => entry.relativePath));
+    const removed = Object.keys(previous).filter((relativePath) => !currentKeys.has(relativePath));
+    return { changed, removed, unchanged: entries.length - changed.length };
+}
+
+function diffContextEntries(entries: ContextEntry[], previous: Record<string, FileDigest>) {
+    const changed = entries.filter((entry) => previous[entry.remotePath]?.hash !== entry.hash);
+    const currentKeys = new Set(entries.map((entry) => entry.remotePath));
+    const removed = Object.keys(previous).filter((remotePath) => !currentKeys.has(remotePath) && !isProtectedRemotePath(remotePath));
+    return { changed, removed, unchanged: entries.length - changed.length };
+}
+
+function collectPluginEnvironment(options: CliOptions) {
+    const env: Record<string, string> = {};
+    for (const plugin of plugins) {
+        Object.assign(env, plugin.collectEnvironment?.({ options, utils: pluginUtils }) ?? {});
+    }
+    return env;
+}
+
+async function discoverPluginContextCandidates(options: CliOptions) {
+    const candidates: ContextCandidate[] = [];
+    for (const plugin of plugins) {
+        const discovered = await plugin.discoverContextCandidates?.({ options, utils: pluginUtils });
+        if (discovered) candidates.push(...discovered);
+    }
+    return dedupeContextCandidates(candidates);
+}
+
+function shouldSkipContextDirectory(relativePath: string, name: string) {
+    return plugins.some((plugin) => plugin.shouldSkipContextDirectory?.(relativePath, name));
+}
+
+function isProtectedRemotePath(remotePath: string) {
+    return plugins.some((plugin) => plugin.isProtectedRemotePath?.(remotePath));
+}
+
+function dedupeContextCandidates(candidates: ContextCandidate[]) {
+    const seen = new Set<string>();
+    return candidates.filter((candidate) => {
+        const key = `${candidate.source}\0${candidate.remoteRoot}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+}
+
+async function scanContextCandidates(candidates: ContextCandidate[]): Promise<ContextEntry[]> {
+    const entries: ContextEntry[] = [];
+    for (const candidate of candidates) {
+        const stats = await import("node:fs/promises").then((fs) => fs.lstat(candidate.source));
+        if (stats.isFile()) {
+            const local = await digestEntry(candidate.source, path.basename(candidate.source));
+            entries.push({
+                ...local,
+                remotePath: candidate.remoteRoot,
+                label: candidate.label,
+                sensitive: candidate.sensitive,
+            });
+        } else if (stats.isDirectory()) {
+            const candidateEntries: LocalEntry[] = [];
+            await walk(candidate.source, "", candidateEntries, {
+                skipDirectory(relativePath, name) {
+                    return shouldSkipContextDirectory(relativePath, name);
+                },
+            });
+            for (const local of candidateEntries) {
+                if (local.kind === "symlink") continue;
+                const remotePath = `${candidate.remoteRoot}/${local.relativePath}`;
+                if (isProtectedRemotePath(remotePath)) continue;
+                entries.push({
+                    ...local,
+                    remotePath,
+                    label: candidate.label,
+                    sensitive: candidate.sensitive,
+                });
+            }
+        }
+    }
+    return entries.sort((left, right) => left.remotePath.localeCompare(right.remotePath));
+}
+
+async function updatePluginPreferences(options: CliOptions): Promise<PluginPreferences> {
+    const preferencesPath = getPluginPreferencesPath(options);
+    const preferences = options.resetPluginPrefs ? emptyPluginPreferences() : await readPluginPreferences(preferencesPath);
+    let changed = options.resetPluginPrefs;
+    const disabledPlugins = new Set<string>();
+
+    for (const savedName of preferences.disabledPlugins) {
+        const canonicalName = maybeResolvePluginSelector(savedName);
+        disabledPlugins.add(canonicalName ?? savedName);
+        if (canonicalName && canonicalName !== savedName) changed = true;
+    }
+
+    for (const selector of options.enablePlugins) {
+        const name = resolvePluginSelector(selector);
+        if (disabledPlugins.delete(name)) changed = true;
+    }
+
+    for (const selector of options.disablePlugins) {
+        const name = resolvePluginSelector(selector);
+        if (!disabledPlugins.has(name)) {
+            disabledPlugins.add(name);
+            changed = true;
+        }
+    }
+
+    const next = { version: PLUGIN_PREFERENCES_VERSION, disabledPlugins: [...disabledPlugins].sort(), updatedAt: preferences.updatedAt };
+    if (changed) await writePluginPreferences(preferencesPath, next);
+    return next;
+}
+
+function activePlugins(preferences: PluginPreferences, options: CliOptions) {
+    const disabled = new Set(preferences.disabledPlugins);
+    return config.plugins.filter((plugin) => {
+        if (disabled.has(plugin.name)) return false;
+        if (!options.includeAuth && plugin.name.startsWith("@freestyle-sync/auth-")) return false;
+        if (!options.includeAgentContext && plugin.name.startsWith("@freestyle-sync/agent-")) return false;
+        return true;
+    });
+}
+
+function printPlugins(preferences: PluginPreferences, options: CliOptions) {
+    const enabled = new Set(activePlugins(preferences, options).map((plugin) => plugin.name));
+    console.log(`Plugin preferences: ${getPluginPreferencesPath(options)}`);
+    for (const plugin of config.plugins) {
+        const runtimeDisabled = (!options.includeAuth && plugin.name.startsWith("@freestyle-sync/auth-")) || (!options.includeAgentContext && plugin.name.startsWith("@freestyle-sync/agent-"));
+        const savedDisabled = preferences.disabledPlugins.includes(plugin.name);
+        const status = enabled.has(plugin.name) ? "enabled" : savedDisabled ? "disabled (saved)" : runtimeDisabled ? "disabled (this run)" : "disabled";
+        console.log(`${status.padEnd(19)} ${plugin.name}`);
+    }
+}
+
+function resolvePluginSelector(selector: string) {
+    const match = maybeResolvePluginSelector(selector);
+    if (match) return match;
+    const matches = config.plugins.filter((plugin) => pluginSelectorAliases(plugin.name).includes(selector));
+    if (matches.length > 1) throw new Error(`ambiguous plugin selector ${selector}: ${matches.map((plugin) => plugin.name).join(", ")}`);
+    throw new Error(`unknown plugin ${selector}. Run --list-plugins to see configured plugins.`);
+}
+
+function maybeResolvePluginSelector(selector: string) {
+    const matches = config.plugins.filter((plugin) => pluginSelectorAliases(plugin.name).includes(selector));
+    if (matches.length === 1) return matches[0].name;
+    if (matches.length > 1) throw new Error(`ambiguous plugin selector ${selector}: ${matches.map((plugin) => plugin.name).join(", ")}`);
+    return undefined;
+}
+
+function pluginSelectorAliases(name: string) {
+    const aliases = new Set([name]);
+    const withoutScope = name.split("/").pop();
+    if (withoutScope) aliases.add(withoutScope);
+    if (name.startsWith("@freestyle-sync/") && withoutScope) {
+        aliases.add(`@freestyle/sync-plugin-${withoutScope}`);
+        aliases.add(`@pushvm/plugin-${withoutScope}`);
+        aliases.add(`sync-plugin-${withoutScope}`);
+        aliases.add(`plugin-${withoutScope}`);
+    }
+    if (withoutScope?.startsWith("sync-plugin-")) aliases.add(withoutScope.slice("sync-plugin-".length));
+    if (withoutScope?.startsWith("plugin-")) aliases.add(withoutScope.slice("plugin-".length));
+    return [...aliases];
+}
+
+function emptyPluginPreferences(): PluginPreferences {
+    return { version: PLUGIN_PREFERENCES_VERSION, disabledPlugins: [] };
+}
+
+function getPluginPreferencesPath(options: CliOptions) {
+    return path.join(path.dirname(options.cachePath), "plugin-preferences.json");
+}
+
+async function readPluginPreferences(preferencesPath: string): Promise<PluginPreferences> {
+    try {
+        const parsed = JSON.parse(await readFile(preferencesPath, "utf8")) as PluginPreferences;
+        if (parsed.version === PLUGIN_PREFERENCES_VERSION) {
+            return {
+                version: PLUGIN_PREFERENCES_VERSION,
+                disabledPlugins: Array.isArray(parsed.disabledPlugins) ? parsed.disabledPlugins.filter((name) => typeof name === "string") : [],
+                updatedAt: parsed.updatedAt,
+            };
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+            console.warn(`Ignoring unreadable plugin preferences ${preferencesPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return emptyPluginPreferences();
+}
+
+async function writePluginPreferences(preferencesPath: string, preferences: PluginPreferences) {
+    await mkdir(path.dirname(preferencesPath), { recursive: true });
+    await writeFile(preferencesPath, `${JSON.stringify({ ...preferences, updatedAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
+}
+
+function printPlan(
+    options: CliOptions,
+    projectChanges: ReturnType<typeof diffEntries>,
+    contextChanges: ReturnType<typeof diffContextEntries>,
+    envExports: Record<string, string>,
+    cache: CacheFile,
+) {
+    const source = options.vmId ? `existing VM ${options.vmId}` : cache.snapshotId ? `snapshot ${cache.snapshotId}` : "a new VM";
+    console.log(`Syncing ${options.projectRoot} to ${source}`);
+    console.log(`Remote project: ${options.remoteProjectDir}`);
+    console.log(`Project files: ${projectChanges.changed.length} changed, ${projectChanges.removed.length} removed, ${projectChanges.unchanged} unchanged`);
+    console.log(`Context files: ${contextChanges.changed.length} changed, ${contextChanges.removed.length} removed, ${contextChanges.unchanged} unchanged`);
+    console.log(`Estimated upload: ${formatBytes(totalEntrySize(projectChanges.changed))} project, ${formatBytes(totalEntrySize(contextChanges.changed))} context`);
+    if (Object.keys(envExports).length > 0) {
+        console.log(`Environment exports: ${Object.keys(envExports).length}`);
+    }
+}
+
+function totalEntrySize(entries: LocalEntry[]) {
+    return entries.reduce((total, entry) => total + entry.size, 0);
+}
+
+async function getOrCreateVm(options: CliOptions, snapshotId?: string) {
+    if (options.vmId) {
+        const { vm } = await freestyle.vms.get({ vmId: options.vmId });
+        await vm.start(options.idleTimeoutSeconds ? { idleTimeoutSeconds: options.idleTimeoutSeconds } : undefined);
+        return { vm, vmId: options.vmId };
+    }
+
+    console.log(snapshotId ? `Creating VM from snapshot ${snapshotId}...` : "Creating Freestyle VM...");
+    const result = await freestyle.vms.create({
+        name: options.name,
+        snapshotId: snapshotId ?? undefined,
+        idleTimeoutSeconds: options.idleTimeoutSeconds,
+    });
+    return { vm: result.vm, vmId: result.vmId };
+}
+
+async function ensureRemoteBase(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], remoteProjectDir: string) {
+    await checkedExec(vm, `mkdir -p ${shellQuote(remoteProjectDir)} /root/.freestyle-sync`);
+}
+
+async function syncProject(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    changes: ReturnType<typeof diffEntries>,
+): Promise<SyncResult> {
+    if (changes.changed.length > 0) {
+        console.log(`VM ${vmId}: uploading ${changes.changed.length} changed project files...`);
+        const archive = await createProjectArchive(options.projectRoot, changes.changed);
+        try {
+            await uploadArchiveInChunks(vm, vmId, archive, "/tmp/vmpush-project.tgz", "project");
+            await checkedExec(vm, `mkdir -p ${shellQuote(options.remoteProjectDir)} && tar --no-same-owner --no-same-permissions -xzf /tmp/vmpush-project.tgz -C ${shellQuote(options.remoteProjectDir)} && rm -f /tmp/vmpush-project.tgz`);
+        } finally {
+            await rm(path.dirname(archive), { recursive: true, force: true });
+        }
+    }
+
+    if (changes.removed.length > 0) {
+        console.log(`VM ${vmId}: removing ${changes.removed.length} deleted project files...`);
+        const removeList = Buffer.from(changes.removed.join("\0") + "\0");
+        await vm.fs.writeFile("/tmp/vmpush-remove-list", removeList);
+        await checkedExec(vm, `cd ${shellQuote(options.remoteProjectDir)} && xargs -0 rm -f -- < /tmp/vmpush-remove-list && rm -f /tmp/vmpush-remove-list`);
+    }
+
+    return {
+        uploaded: changes.changed.length,
+        removed: changes.removed.length,
+        unchanged: changes.unchanged,
+    };
+}
+
+async function runRemoteFixups(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], vmId: string, options: CliOptions) {
+    for (const plugin of plugins) {
+        if (!plugin.afterProjectSync) continue;
+        try {
+            await plugin.afterProjectSync({ vm: vm as RemoteVm, vmId, options, utils: pluginUtils });
+        } catch (error) {
+            console.warn(`Remote fixup ${plugin.name} skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+
+async function runAfterContextSyncPlugins(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    changedRemotePaths: string[],
+) {
+    for (const plugin of plugins) {
+        if (!plugin.afterContextSync) continue;
+        await plugin.afterContextSync({ vm: vm as RemoteVm, vmId, options, utils: pluginUtils, changedRemotePaths });
+    }
+}
+
+async function runAfterSyncPlugins(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    contextCandidates: ContextCandidate[],
+) {
+    const messages: string[] = [];
+    for (const plugin of plugins) {
+        const result = await plugin.afterSync?.({ vm: vm as RemoteVm, vmId, options, utils: pluginUtils, contextCandidates });
+        if (result) messages.push(...result);
+    }
+    return messages;
+}
+
+async function runBeforeSnapshotPlugins(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], vmId: string, options: CliOptions) {
+    for (const plugin of plugins) {
+        if (!plugin.beforeSnapshot) continue;
+        try {
+            await plugin.beforeSnapshot({ vm: vm as RemoteVm, vmId, options, utils: pluginUtils });
+        } catch (error) {
+            console.warn(`Snapshot preparation ${plugin.name} skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+
+async function syncContext(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], vmId: string, changes: ReturnType<typeof diffContextEntries>): Promise<SyncResult> {
+    if (changes.removed.length > 0) {
+        console.log(`VM ${vmId}: removing ${changes.removed.length} deleted auth/context files...`);
+        await checkedExec(vm, changes.removed.map((remotePath) => `rm -f -- ${shellQuote(remotePath)}`).join("\n"));
+    }
+
+    if (changes.changed.length === 0) {
+        return { uploaded: 0, removed: changes.removed.length, unchanged: changes.unchanged };
+    }
+
+    console.log(`VM ${vmId}: uploading ${changes.changed.length} changed auth/context files...`);
+    const archive = await createContextArchive(changes.changed);
+    try {
+        await uploadArchiveInChunks(vm, vmId, archive, "/tmp/vmpush-context.tgz", "context");
+        await checkedExec(vm, "tar --no-same-owner --no-same-permissions -xzf /tmp/vmpush-context.tgz -C / && rm -f /tmp/vmpush-context.tgz");
+    } finally {
+        await rm(path.dirname(archive), { recursive: true, force: true });
+    }
+    return { uploaded: changes.changed.length, removed: changes.removed.length, unchanged: changes.unchanged };
+}
+
+async function installEnvironment(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    envExports: Record<string, string>,
+    envHash: string,
+    previousHash?: string,
+) {
+    if (Object.keys(envExports).length === 0 || envHash === previousHash) return;
+    await checkedExec(vm, "mkdir -p /root/.freestyle-sync");
+    await vm.fs.writeTextFile("/root/.freestyle-sync/env.sh", renderEnvFile(envExports));
+    await checkedExec(
+        vm,
+        "chmod 700 /root/.freestyle-sync && chmod 600 /root/.freestyle-sync/env.sh && grep -qxF 'test -f /root/.freestyle-sync/env.sh && . /root/.freestyle-sync/env.sh' /root/.profile || printf '\n%s\n' 'test -f /root/.freestyle-sync/env.sh && . /root/.freestyle-sync/env.sh' >> /root/.profile",
+    );
+}
+
+async function writeRemoteResumeFiles(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    options: CliOptions,
+    vmId: string,
+    envExports: Record<string, string>,
+) {
+    const manifest = {
+        vmId,
+        project: options.remoteProjectDir,
+        syncedAt: new Date().toISOString(),
+        env: Object.keys(envExports).sort(),
+        installCommand: await detectInstallCommand(options.projectRoot),
+    };
+    await checkedExec(vm, `mkdir -p ${shellQuote(`${options.remoteProjectDir}/.freestyle-sync`)} /root/.freestyle-sync`);
+    await vm.fs.writeTextFile(`${options.remoteProjectDir}/.freestyle-sync/remote.json`, `${JSON.stringify(manifest, null, 2)}\n`);
+    await vm.fs.writeTextFile(
+        "/root/.freestyle-sync/resume.sh",
+        `#!/usr/bin/env bash
+set -euo pipefail
+test -f /root/.freestyle-sync/env.sh && . /root/.freestyle-sync/env.sh
+cd ${shellQuote(options.remoteProjectDir)}
+exec "$SHELL" -l
+`,
+    );
+    await vm.fs.writeTextFile("/root/.freestyle-sync/profile.sh", renderRemoteProfile(options.remoteProjectDir));
+    await checkedExec(
+        vm,
+        "chmod 700 /root/.freestyle-sync && chmod +x /root/.freestyle-sync/resume.sh && chmod 600 /root/.freestyle-sync/profile.sh && grep -qxF 'test -f /root/.freestyle-sync/profile.sh && . /root/.freestyle-sync/profile.sh' /root/.profile || printf '\n%s\n' 'test -f /root/.freestyle-sync/profile.sh && . /root/.freestyle-sync/profile.sh' >> /root/.profile",
+    );
+}
+
+function renderRemoteProfile(remoteProjectDir: string) {
+    return `# Generated by freestyle-sync. Loaded by /root/.profile.
+test -f /root/.freestyle-sync/env.sh && . /root/.freestyle-sync/env.sh
+if [ -d ${shellQuote(remoteProjectDir)} ]; then
+    cd ${shellQuote(remoteProjectDir)}
+fi
+`;
+}
+
+async function runInstall(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], projectRoot: string, remoteProjectDir: string) {
+    const installCommand = await detectInstallCommand(projectRoot);
+    if (!installCommand) {
+        console.log("No dependency install command detected.");
+        return;
+    }
+    console.log(`Running install: ${installCommand}`);
+    await checkedExec(vm, `cd ${shellQuote(remoteProjectDir)} && ${installCommand}`, 20 * 60 * 1000);
+}
+
+async function detectInstallCommand(projectRoot: string) {
+    if (await exists(path.join(projectRoot, "pnpm-lock.yaml"))) return "corepack enable && pnpm install";
+    if (await exists(path.join(projectRoot, "yarn.lock"))) return "corepack enable && yarn install";
+    if (await exists(path.join(projectRoot, "package-lock.json"))) return "npm install";
+    if (await exists(path.join(projectRoot, "requirements.txt"))) return "python3 -m pip install -r requirements.txt";
+    if (await exists(path.join(projectRoot, "pyproject.toml"))) return "python3 -m pip install -e .";
+    if (await exists(path.join(projectRoot, "Cargo.toml"))) return "cargo fetch";
+    if (await exists(path.join(projectRoot, "go.mod"))) return "go mod download";
+    return undefined;
+}
+
+async function createProjectArchive(projectRoot: string, entries: LocalEntry[]) {
+    const tempDir = await mkdtemp(path.join(tmpdir(), "vmpush-"));
+    const listPath = path.join(tempDir, "files.list");
+    const archivePath = path.join(tempDir, "project.tgz");
+    await writeFile(listPath, Buffer.from(entries.map((entry) => entry.relativePath).join("\0") + "\0"));
+    await createTar(["--null", "--no-xattrs", "-T", listPath, "-czf", archivePath, "-C", projectRoot]);
+    return archivePath;
+}
+
+async function createContextArchive(entries: ContextEntry[]) {
+    const tempDir = await mkdtemp(path.join(tmpdir(), "vmpush-context-"));
+    const stagingDir = path.join(tempDir, "staging");
+    const archivePath = path.join(tempDir, "context.tgz");
+    await mkdir(stagingDir, { recursive: true });
+
+    for (const entry of entries) {
+        const relativeRemotePath = entry.remotePath.replace(/^\/+/, "");
+        const destination = path.join(stagingDir, ...relativeRemotePath.split("/"));
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, await readFile(entry.absolutePath));
+    }
+
+    await createTar(["--no-xattrs", "-czf", archivePath, "-C", stagingDir, "."]);
+    return archivePath;
+}
+
+async function createTar(args: string[]) {
+    await execFileAsync("tar", args, {
+        env: {
+            ...process.env,
+            COPYFILE_DISABLE: "1",
+        },
+    });
+}
+
+async function uploadArchiveInChunks(
+    vm: RemoteVm,
+    vmId: string,
+    archivePath: string,
+    remoteArchivePath: string,
+    label: string,
+) {
+    const archive = await readFile(archivePath);
+    const encoded = archive.toString("base64");
+    const chunkCount = Math.max(1, Math.ceil(encoded.length / ARCHIVE_CHUNK_CHARS));
+    const chunkDir = `/tmp/vmpush-${label}-${Date.now()}.chunks`;
+
+    console.log(`VM ${vmId}: streaming ${formatBytes(archive.length)} ${label} archive in ${chunkCount} chunk${chunkCount === 1 ? "" : "s"}...`);
+    await checkedExec(vm, `rm -rf ${shellQuote(chunkDir)} && mkdir -p ${shellQuote(chunkDir)}`);
+
+    const width = String(chunkCount - 1).length;
+    for (let index = 0; index < chunkCount; index += 1) {
+        const start = index * ARCHIVE_CHUNK_CHARS;
+        const chunk = encoded.slice(start, start + ARCHIVE_CHUNK_CHARS);
+        const chunkName = `${String(index).padStart(width, "0")}.b64`;
+        await vm.fs.writeTextFile(`${chunkDir}/${chunkName}`, chunk);
+        if (chunkCount > 1 && ((index + 1) % 10 === 0 || index + 1 === chunkCount)) {
+            console.log(`VM ${vmId}: uploaded ${index + 1}/${chunkCount} ${label} archive chunks`);
+        }
+    }
+
+    await checkedExec(
+        vm,
+        `cat ${shellQuote(chunkDir)}/*.b64 | base64 -d > ${shellQuote(remoteArchivePath)} && rm -rf ${shellQuote(chunkDir)}`,
+    );
+}
+
+async function mkdirRemote(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"], directories: string[]) {
+    for (const chunk of chunkArray(directories, 50)) {
+        await checkedExec(vm, `mkdir -p ${chunk.map(shellQuote).join(" ")}`);
+    }
+}
+
+async function hardenRemoteRoot(vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"]): Promise<void> {
+    await checkedExec(vm, "chown root:root /root && chmod 700 /root");
+}
+
+async function checkedExec(vm: RemoteVm, command: string, timeoutMs?: number) {
+    const result = await vm.exec({ command, timeoutMs });
+    if (result.statusCode && result.statusCode !== 0) {
+        throw new Error(`remote command failed (${result.statusCode}): ${command}\n${result.stderr ?? result.stdout ?? ""}`);
+    }
+    return result;
+}
+
+async function runBeforeOpenRemoteEditorPlugins(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    scheme: "vscode" | "cursor",
+    remoteWorkspaceUri: string,
+    contextCandidates: ContextCandidate[],
+) {
+    const messages: string[] = [];
+    for (const plugin of plugins) {
+        const result = await plugin.beforeOpenRemoteEditor?.({
+            vm: vm as RemoteVm,
+            vmId,
+            options,
+            utils: pluginUtils,
+            scheme,
+            remoteWorkspaceUri,
+            contextCandidates,
+        });
+        if (result) messages.push(...result);
+    }
+    return messages;
+}
+
+async function runAfterOpenRemoteEditorPlugins(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    scheme: "vscode" | "cursor",
+    remoteWorkspaceUri: string,
+    contextCandidates: ContextCandidate[],
+) {
+    const messages: string[] = [];
+    for (const plugin of plugins) {
+        const result = await plugin.afterOpenRemoteEditor?.({
+            vm: vm as RemoteVm,
+            vmId,
+            options,
+            utils: pluginUtils,
+            scheme,
+            remoteWorkspaceUri,
+            contextCandidates,
+        });
+        if (result) messages.push(...result);
+    }
+    return messages;
+}
+
+async function runConnectPlugins(
+    vm: Awaited<ReturnType<typeof getOrCreateVm>>["vm"],
+    vmId: string,
+    options: CliOptions,
+    contextCandidates: ContextCandidate[],
+) {
+    for (const plugin of plugins) {
+        const handled = await plugin.connect?.({
+            vm: vm as RemoteVm,
+            vmId,
+            options,
+            utils: pluginUtils,
+            contextCandidates,
+            runBeforeOpenRemoteEditor: ({ scheme, remoteWorkspaceUri }) => runBeforeOpenRemoteEditorPlugins(vm, vmId, options, scheme, remoteWorkspaceUri, contextCandidates),
+            runAfterOpenRemoteEditor: ({ scheme, remoteWorkspaceUri }) => runAfterOpenRemoteEditorPlugins(vm, vmId, options, scheme, remoteWorkspaceUri, contextCandidates),
+        });
+        if (handled) return true;
+    }
+    return false;
+}
+
+async function sshIntoVm(vmId: string) {
+    console.log(`Connecting to VM ${vmId}...`);
+    const exitCode = await new Promise<number | null>((resolve, reject) => {
+        const child = spawn("npx", ["freestyle", "vm", "ssh", vmId], { stdio: "inherit" });
+        child.on("error", reject);
+        child.on("exit", (code) => resolve(code));
+    });
+    if (exitCode && exitCode !== 0) {
+        throw new Error(`ssh exited with status ${exitCode}`);
+    }
+}
+
+async function hashFile(filePath: string): Promise<string> {
+    const hash = createHash("sha256");
+    await new Promise<void>((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("error", reject);
+        stream.on("end", resolve);
+    });
+    return hash.digest("hex");
+}
+
+function hashString(value: string): string {
+    return createHash("sha256").update(value).digest("hex");
+}
+
+function md5(value: string): string {
+    return createHash("md5").update(value).digest("hex");
+}
+
+function renderEnvFile(envExports: Record<string, string>) {
+    const lines = ["# Generated by vmpush. Contains local auth tokens."];
+    for (const key of Object.keys(envExports).sort()) {
+        lines.push(`export ${key}=${shellQuote(envExports[key])}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+
+function shellQuote(value: string): string {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function normalizeRemotePath(value: string): string {
+    const normalized = path.posix.normalize(value.replace(/\\/g, "/"));
+    if (!normalized.startsWith("/")) {
+        throw new Error("--remote-dir must be an absolute VM path");
+    }
+    return normalized;
+}
+
+function defaultRemoteProjectDir(projectRoot: string): string {
+    return normalizeRemotePath(toPosix(projectRoot));
+}
+
+function sanitizeName(value: string): string {
+    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+
+function toPosix(value: string) {
+    return value.split(path.sep).join(path.posix.sep);
+}
+
+function formatBytes(bytes: number) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+async function delay(ms: number) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function exists(filePath: string) {
+    try {
+        await stat(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function chunkArray<T>(items: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}