freestyle-sync 0.1.9 → 0.1.11

package/README.md

@@ -1,46 +1,12 @@
 # Freestyle Sync
 
-Sync your current directory, it's dependencies, and your agent context into a remote runtime. Freestyle VMs support snapshots so only changes are uploaded on later runs.
+Offload any development environment to a VM with 1 command. Authentication, agent context, and dependencies are automatically handled.
 
 ```
 npx freestyle-sync
 ```
 
-Freestyle VMs are the default provider. You can sync into a local Apple container on macOS with the Apple `container` CLI installed:
-
-```sh
-npx freestyle-sync --provider apple-container --apple-container-image ubuntu:24.04
-```
-
-Use `--vm-id <container-name-or-id>` to reuse an existing Apple container. Snapshot caching is only available with the Freestyle provider.
-
-Use the SDK when embedding sync inside another CLI/app (no required `freestyle-sync.config.ts` or cache file):
-
-```ts
-import { defineConfig, sync, type SyncCache } from "freestyle-sync";
-import { gitAuthPlugin } from "@freestyle-sync/auth-git";
-import { nodeNpmPlugin } from "@freestyle-sync/node-npm";
-
-let cache: SyncCache | undefined;
-
-const result = await sync({
-    config: defineConfig({
-        plugins: [gitAuthPlugin(), nodeNpmPlugin()],
-    }),
-    options: {
-        projectRoot: process.cwd(),
-        autoSsh: false,
-    },
-    cache,
-    onCacheUpdate(nextCache) {
-        cache = nextCache;
-    },
-});
-
-console.log("synced runtime", result.vmId);
-```
-
-freestyle-sync creates `freestyle-sync.config.mjs` on first run and installs the config dependencies into your project as dev dependencies. Remove the generated config or dependencies if you want to reset it later.
+On it's first run, freestyle-sync creates `freestyle-sync.config.mjs` and configures a large set of default plugins. Plugins help sync parts of your development environment that require more complex logic than just copying the current directory's files.
 
 ```js
 import { defineConfig } from "freestyle-sync";
@@ -57,8 +23,11 @@ import { githubCliAuthPlugin } from "@freestyle-sync/auth-github-cli";
 import { npmAuthPlugin } from "@freestyle-sync/auth-npm";
 import { sshAuthPlugin } from "@freestyle-sync/auth-ssh";
 import { yarnAuthPlugin } from "@freestyle-sync/auth-yarn";
+import { nextjsPlugin } from "@freestyle-sync/nextjs";
 import { nodeNpmPlugin } from "@freestyle-sync/node-npm";
+import { rustPlugin } from "@freestyle-sync/rust";
 import { shellHistoryPlugin } from "@freestyle-sync/shell-history";
+import { vitePlugin } from "@freestyle-sync/vite";
 
 export default defineConfig({
     plugins: [
@@ -73,10 +42,70 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
         shellHistoryPlugin(),
     ],
 });
-```
+```
+
+You can exclude folders and include additional local paths. Include paths may point outside the project directory; they are copied into the remote project at the configured relative target.
+
+```js
+export default defineConfig({
+    sync: {
+        exclude: ["dist", ".turbo"],
+        include: [
+            { source: "../shared-config", target: "shared-config" },
+        ],
+    }
+});
+```
+
+The default Node/framework/runtime plugins avoid uploading generated dependency and build output folders:
+
+```js
+nodeNpmPlugin() // excludes node_modules and installs frozen dependencies remotely
+nextjsPlugin()  // excludes .next
+vitePlugin()    // excludes dist, build, and .vite
+rustPlugin()    // excludes target, installs Rust/Cargo, and runs cargo fetch
+```
+
+You can keep uploading those generated folders when needed:
+
+```js
+nodeNpmPlugin({ syncNodeModules: true })
+nextjsPlugin({ syncNextDir: true })
+vitePlugin({ syncBuildOutput: true })
+rustPlugin({ syncTargetDir: true })
+```
+
+If you're integrating freestyle-sync into your own toolchain, you can use it as an sdk and take full control over how configuration and cache is stored.
+
+```ts
+import { defineConfig, sync, type SyncCache } from "freestyle-sync";
+import { gitAuthPlugin } from "@freestyle-sync/auth-git";
+import { nodeNpmPlugin } from "@freestyle-sync/node-npm";
+
+let cache: SyncCache | undefined;
+
+const result = await sync({
+    config: defineConfig({
+        plugins: [gitAuthPlugin(), nodeNpmPlugin()],
+    }),
+    options: {
+        projectRoot: process.cwd(),
+        autoSsh: false,
+    },
+    cache,
+    onCacheUpdate(nextCache) {
+        cache = nextCache;
+    },
+});
+
+console.log("synced runtime", result.vmId);
+```

package/dist/src/main.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import type { CliOptions, PushvmConfig, VmProviderName } from "./plugin-api.ts";
+export * from "./plugin-api.ts";
+type FileKind = "file" | "symlink";
+type FileDigest = {
+    hash: string;
+    kind: FileKind;
+    mode: number;
+    size: number;
+};
+type CacheFile = {
+    version: number;
+    projectRoot: string;
+    remoteProjectDir: string;
+    provider?: VmProviderName;
+    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;
+};
+export type SyncCache = CacheFile;
+export type SyncPluginPreferences = PluginPreferences;
+export type SyncSdkOptions = {
+    config: PushvmConfig;
+    options?: Partial<CliOptions>;
+    cache?: SyncCache;
+    pluginPreferences?: SyncPluginPreferences;
+    onCacheUpdate?(cache: SyncCache): Promise<void> | void;
+};
+export type SyncSdkResult = {
+    vmId?: string;
+    cache: SyncCache;
+    snapshotId?: string;
+};
+export declare function sync(sdkOptions: SyncSdkOptions): Promise<SyncSdkResult>;

package/dist/src/main.js

@@ -10,7 +10,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import "dotenv/config";
 import { createHash } from "node:crypto";
 import { createReadStream, realpathSync } from "node:fs";
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readlink, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -47,8 +47,11 @@ const DEFAULT_CONFIG_DEPENDENCIES = [
     { name: "@freestyle-sync/auth-npm", spec: "@freestyle-sync/auth-npm@latest" },
     { name: "@freestyle-sync/auth-ssh", spec: "@freestyle-sync/auth-ssh@latest" },
     { name: "@freestyle-sync/auth-yarn", spec: "@freestyle-sync/auth-yarn@latest" },
+    { name: "@freestyle-sync/nextjs", spec: "@freestyle-sync/nextjs@latest" },
     { name: "@freestyle-sync/node-npm", spec: "@freestyle-sync/node-npm@latest" },
+    { name: "@freestyle-sync/rust", spec: "@freestyle-sync/rust@latest" },
     { name: "@freestyle-sync/shell-history", spec: "@freestyle-sync/shell-history@latest" },
+    { name: "@freestyle-sync/vite", spec: "@freestyle-sync/vite@latest" },
 ];
 const pluginUtils = {
     checkedExec,
@@ -182,7 +185,8 @@ export async function sync(sdkOptions) {
     progress.step("Scanning project files");
     const cache = currentCache;
     const base = cacheBaseForSync(options, cache);
-    const projectEntries = await scanProject(options.projectRoot, options.includeGitDir);
+    const projectSyncConfig = await resolveProjectSyncConfig(options);
+    const projectEntries = await scanProject(options.projectRoot, options.includeGitDir, projectSyncConfig);
     const projectCurrent = digestMap(projectEntries);
     const projectChanges = diffEntries(projectEntries, base.projectFiles);
     progress.step("Detecting auth and agent context");
@@ -374,8 +378,11 @@ import { githubCliAuthPlugin } from "@freestyle-sync/auth-github-cli";
 import { npmAuthPlugin } from "@freestyle-sync/auth-npm";
 import { sshAuthPlugin } from "@freestyle-sync/auth-ssh";
 import { yarnAuthPlugin } from "@freestyle-sync/auth-yarn";
+import { nextjsPlugin } from "@freestyle-sync/nextjs";
 import { nodeNpmPlugin } from "@freestyle-sync/node-npm";
+import { rustPlugin } from "@freestyle-sync/rust";
 import { shellHistoryPlugin } from "@freestyle-sync/shell-history";
+import { vitePlugin } from "@freestyle-sync/vite";
 import { defineConfig } from "freestyle-sync";
 
 export default defineConfig({
@@ -391,6 +398,9 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
@@ -413,8 +423,11 @@ import { githubCliAuthPlugin } from "@freestyle-sync/auth-github-cli";
 import { npmAuthPlugin } from "@freestyle-sync/auth-npm";
 import { sshAuthPlugin } from "@freestyle-sync/auth-ssh";
 import { yarnAuthPlugin } from "@freestyle-sync/auth-yarn";
+import { nextjsPlugin } from "@freestyle-sync/nextjs";
 import { nodeNpmPlugin } from "@freestyle-sync/node-npm";
+import { rustPlugin } from "@freestyle-sync/rust";
 import { shellHistoryPlugin } from "@freestyle-sync/shell-history";
+import { vitePlugin } from "@freestyle-sync/vite";
 import { defineConfig } from "freestyle-sync";
 
 export default defineConfig({
@@ -430,6 +443,9 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
@@ -719,23 +735,92 @@ async function writeCache(cachePath, cache) {
     await mkdir(path.dirname(cachePath), { recursive: true });
     await writeFile(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
 }
-async function scanProject(projectRoot, includeGitDir) {
-    const entries = [];
-    await walk(projectRoot, "", entries, {
+async function resolveProjectSyncConfig(options) {
+    const configs = [];
+    if (config.sync)
+        configs.push(config.sync);
+    for (const plugin of plugins) {
+        const pluginConfig = await plugin.configureProjectSync?.({ options, utils: pluginUtils });
+        if (pluginConfig)
+            configs.push(pluginConfig);
+    }
+    return {
+        exclude: configs.flatMap((projectConfig) => projectConfig.exclude ?? []).map(normalizeProjectPattern),
+        include: configs.flatMap((projectConfig) => normalizeProjectIncludes(options.projectRoot, projectConfig.include ?? [])),
+    };
+}
+function normalizeProjectIncludes(projectRoot, includes) {
+    return includes.map((include) => {
+        const source = typeof include === "string" ? include : include.source;
+        const target = typeof include === "string" ? undefined : include.target;
+        const resolvedSource = path.resolve(projectRoot, source);
+        return {
+            source: resolvedSource,
+            target: normalizeProjectPattern(target ?? path.basename(resolvedSource)),
+        };
+    });
+}
+function normalizeProjectPattern(value) {
+    const normalized = path.posix.normalize(value.replace(/\\/g, "/")).replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!normalized || normalized === ".") {
+        throw new Error("project sync paths must not be empty");
+    }
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new Error(`project sync paths must stay inside the remote project: ${value}`);
+    }
+    return normalized;
+}
+async function scanProject(projectRoot, includeGitDir, syncConfig) {
+    const entriesByPath = new Map();
+    const rootEntries = [];
+    await walk(projectRoot, "", rootEntries, {
         skipDirectory(relativePath, name) {
             if (!includeGitDir && relativePath === ".git")
                 return true;
-            return false;
+            return shouldSkipProjectDirectory(relativePath, name, syncConfig.exclude);
         },
     });
-    return entries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    upsertProjectEntries(entriesByPath, rootEntries);
+    for (const include of syncConfig.include) {
+        upsertProjectEntries(entriesByPath, await scanProjectInclude(include, syncConfig.exclude));
+    }
+    return Array.from(entriesByPath.values()).sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+async function scanProjectInclude(include, exclude) {
+    const stats = await lstat(include.source).catch((error) => {
+        throw new Error(`project sync include does not exist: ${include.source} (${error instanceof Error ? error.message : String(error)})`);
+    });
+    if (stats.isFile() || stats.isSymbolicLink()) {
+        return [await digestEntry(include.source, include.target)];
+    }
+    if (!stats.isDirectory()) {
+        return [];
+    }
+    const entries = [];
+    await walk(include.source, "", entries, {
+        mapRelativePath(relativePath) {
+            return `${include.target}/${relativePath}`;
+        },
+        skipDirectory(relativePath, name) {
+            return shouldSkipProjectDirectory(relativePath, name, exclude);
+        },
+    });
+    return entries;
+}
+function upsertProjectEntries(entriesByPath, entries) {
+    for (const entry of entries)
+        entriesByPath.set(entry.relativePath, entry);
+}
+function shouldSkipProjectDirectory(relativePath, name, exclude) {
+    return exclude.some((excludedPath) => relativePath === excludedPath || name === excludedPath);
 }
 async function walk(root, relativePath, entries, options) {
     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 localRelativePath = toPosix(childRelativePath);
+        const normalizedRelativePath = options.mapRelativePath?.(localRelativePath) ?? localRelativePath;
         const childAbsolutePath = path.join(root, childRelativePath);
         if (dirent.isDirectory()) {
             if (options.skipDirectory(normalizedRelativePath, dirent.name)) {
@@ -1387,7 +1472,7 @@ async function ensureRemoteBase(vm, remoteProjectDir) {
 async function syncProject(vm, vmId, options, changes) {
     if (changes.changed.length > 0) {
         console.log(`VM ${vmId}: uploading ${changes.changed.length} changed project files...`);
-        const archive = await createProjectArchive(options.projectRoot, changes.changed);
+        const archive = await createProjectArchive(changes.changed);
         try {
             await uploadArchiveInChunks(vm, vmId, archive, "/tmp/freestyle-sync-project.tgz", "project");
             await checkedExec(vm, `mkdir -p ${shellQuote(options.remoteProjectDir)} && tar --no-same-owner --no-same-permissions -xzf /tmp/freestyle-sync-project.tgz -C ${shellQuote(options.remoteProjectDir)} && rm -f /tmp/freestyle-sync-project.tgz`);
@@ -1511,12 +1596,14 @@ async function runInstall(vm, projectRoot, remoteProjectDir) {
     await checkedExec(vm, `cd ${shellQuote(remoteProjectDir)} && ${installCommand}`, 20 * 60 * 1000);
 }
 async function detectInstallCommand(projectRoot) {
+    if (await exists(path.join(projectRoot, "bun.lock")) || await exists(path.join(projectRoot, "bun.lockb")))
+        return "bun install --frozen-lockfile";
     if (await exists(path.join(projectRoot, "pnpm-lock.yaml")))
-        return "corepack enable && pnpm install";
+        return "corepack enable && pnpm install --frozen-lockfile";
     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";
+        return "corepack enable && yarn_version=$(yarn --version) && case \"$yarn_version\" in 1.*) yarn install --frozen-lockfile ;; *) yarn install --immutable ;; esac";
+    if (await exists(path.join(projectRoot, "package-lock.json")) || await exists(path.join(projectRoot, "npm-shrinkwrap.json")))
+        return "npm ci";
     if (await exists(path.join(projectRoot, "requirements.txt")))
         return "python3 -m pip install -r requirements.txt";
     if (await exists(path.join(projectRoot, "pyproject.toml")))
@@ -1527,12 +1614,23 @@ async function detectInstallCommand(projectRoot) {
         return "go mod download";
     return undefined;
 }
-async function createProjectArchive(projectRoot, entries) {
+async function createProjectArchive(entries) {
     const tempDir = await mkdtemp(path.join(tmpdir(), "freestyle-sync-"));
-    const listPath = path.join(tempDir, "files.list");
+    const stagingDir = path.join(tempDir, "staging");
     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]);
+    await mkdir(stagingDir, { recursive: true });
+    for (const entry of entries) {
+        const destination = path.join(stagingDir, ...entry.relativePath.split("/"));
+        await mkdir(path.dirname(destination), { recursive: true });
+        if (entry.kind === "symlink") {
+            await symlink(await readlink(entry.absolutePath), destination);
+        }
+        else {
+            await copyFile(entry.absolutePath, destination);
+            await chmod(destination, entry.mode);
+        }
+    }
+    await createTar(["--no-xattrs", "-czf", archivePath, "-C", stagingDir, "."]);
     return archivePath;
 }
 async function createContextArchive(entries) {
@@ -1567,11 +1665,13 @@ async function uploadArchiveInChunks(vm, vmId, archivePath, remoteArchivePath, l
     const width = String(chunkCount - 1).length;
     const canRenderInlineProgress = process.stdout.isTTY;
     const logEvery = Math.max(1, Math.ceil(chunkCount / 4));
+    const chunkManifest = [];
     let index = 0;
     for await (const chunk of createReadStream(archivePath, { highWaterMark: ARCHIVE_CHUNK_BYTES })) {
-        const chunkName = `${String(index).padStart(width, "0")}.chunk.b64`;
+        const chunkName = `${String(index).padStart(width, "0")}.chunk`;
         const content = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        await vm.fs.writeTextFile(`${chunkDir}/${chunkName}`, content.toString("base64"));
+        chunkManifest.push(`${chunkName} ${content.length}`);
+        await vm.fs.writeFile(`${chunkDir}/${chunkName}`, content);
         const uploadedChunks = index + 1;
         if (chunkCount > 1) {
             const progressMessage = `VM ${vmId}: uploaded ${uploadedChunks}/${chunkCount} ${label} archive chunks`;
@@ -1587,14 +1687,63 @@ async function uploadArchiveInChunks(vm, vmId, archivePath, remoteArchivePath, l
         }
         index += 1;
     }
+    if (archiveSize > 0) {
+        await vm.fs.writeTextFile(`${chunkDir}/manifest`, `${chunkManifest.join("\n")}\n`);
+    }
     await checkedExec(vm, archiveSize === 0
         ? `: > ${shellQuote(remoteArchivePath)} && rm -rf ${shellQuote(chunkDir)}`
         : [
             "set -e",
-            `rm -f ${shellQuote(remoteArchivePath)}`,
-            `for chunk in ${shellQuote(chunkDir)}/*.chunk.b64; do`,
-            `    base64 -d "$chunk" >> ${shellQuote(remoteArchivePath)}`,
+            `chunk_dir=${shellQuote(chunkDir)}`,
+            `remote_archive=${shellQuote(remoteArchivePath)}`,
+            `manifest="$chunk_dir/manifest"`,
+            "deadline=$(( $(date +%s) + 60 ))",
+            "while :; do",
+            "    validation_error=",
+            "    validated_chunks=0",
+            "    if [ ! -f \"$manifest\" ]; then",
+            "        validation_error='missing chunk manifest'",
+            "    else",
+            "        actual_chunks=$(find \"$chunk_dir\" -maxdepth 1 -type f -name '*.chunk' | wc -l | tr -d '[:space:]')",
+            `        if [ "$actual_chunks" != ${shellQuote(String(chunkCount))} ]; then`,
+            `            validation_error="expected ${chunkCount} chunks, found $actual_chunks"`,
+            "        else",
+            "            while IFS=' ' read -r chunk_name expected_size; do",
+            "                [ -n \"$chunk_name\" ] || continue",
+            "                chunk_path=\"$chunk_dir/$chunk_name\"",
+            "                if [ ! -f \"$chunk_path\" ]; then",
+            "                    validation_error=\"missing chunk $chunk_name\"",
+            "                    break",
+            "                fi",
+            "                actual_chunk_size=$(wc -c < \"$chunk_path\" | tr -d '[:space:]')",
+            "                if [ \"$actual_chunk_size\" != \"$expected_size\" ]; then",
+            "                    validation_error=\"chunk $chunk_name expected $expected_size bytes, got $actual_chunk_size\"",
+            "                    break",
+            "                fi",
+            "                validated_chunks=$((validated_chunks + 1))",
+            "            done < \"$manifest\"",
+            `            if [ "$validated_chunks" != ${shellQuote(String(chunkCount))} ] && [ -z "$validation_error" ]; then`,
+            `                validation_error="expected ${chunkCount} manifest entries, found $validated_chunks"`,
+            "            fi",
+            "        fi",
+            "    fi",
+            "    if [ -z \"$validation_error\" ]; then",
+            "        break",
+            "    fi",
+            "    if [ \"$(date +%s)\" -ge \"$deadline\" ]; then",
+            `        rm -f ${shellQuote(remoteArchivePath)}`,
+            `        rm -rf ${shellQuote(chunkDir)}`,
+            `        echo ${shellQuote(`archive chunk validation failed for ${label}`)} >&2`,
+            "        echo \"$validation_error\" >&2",
+            "        exit 1",
+            "    fi",
+            "    sleep 1",
             "done",
+            `rm -f ${shellQuote(remoteArchivePath)}`,
+            "while IFS=' ' read -r chunk_name expected_size; do",
+            "    [ -n \"$chunk_name\" ] || continue",
+            "    cat \"$chunk_dir/$chunk_name\" >> \"$remote_archive\"",
+            "done < \"$manifest\"",
             `actual_size=$(wc -c < ${shellQuote(remoteArchivePath)} | tr -d '[:space:]')`,
             `actual_hash=$(sha256sum ${shellQuote(remoteArchivePath)} | awk '{print $1}')`,
             `if [ "$actual_size" != ${shellQuote(String(archiveSize))} ] || [ "$actual_hash" != ${shellQuote(archiveHash)} ]; then`,
@@ -1605,7 +1754,7 @@ async function uploadArchiveInChunks(vm, vmId, archivePath, remoteArchivePath, l
             "    exit 1",
             "fi",
             `rm -rf ${shellQuote(chunkDir)}`,
-        ].join("\n"));
+        ].join("\n"), 5 * 60 * MS_PER_SECOND);
 }
 async function mkdirRemote(vm, directories) {
     for (const chunk of chunkArray(directories, 50)) {

package/dist/src/plugin-api.d.ts

@@ -0,0 +1,127 @@
+export type VmProviderName = "freestyle" | "apple-container";
+export type CliOptions = {
+    projectRoot: string;
+    cachePath: string;
+    remoteProjectDir: string;
+    provider: VmProviderName;
+    name: string;
+    vmId?: string;
+    appleContainerImage: string;
+    idleTimeoutSeconds?: number;
+    yes: boolean;
+    dryRun: boolean;
+    disablePlugins: string[];
+    enablePlugins: string[];
+    resetPluginPrefs: boolean;
+    listPlugins: boolean;
+    includeAuth: boolean;
+    includeAgentContext: boolean;
+    includeGitDir: boolean;
+    includeAllCopilotWorkspaces: boolean;
+    snapshot: boolean;
+    skipSync: boolean;
+    install: boolean;
+    autoSsh: boolean;
+    envKeys: string[];
+};
+export type ContextCandidate = {
+    source: string;
+    remoteRoot: string;
+    label: string;
+    sensitive: boolean;
+    preferenceKey: string;
+    promptLabel: string;
+};
+export type RemoteVm = {
+    exec(args: {
+        command: string;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout?: string | null;
+        stderr?: string | null;
+        statusCode?: number | null;
+    }>;
+    fs: {
+        writeFile(path: string, content: Buffer): Promise<void>;
+        writeTextFile(path: string, content: string): Promise<void>;
+    };
+};
+export type UploadArchiveInChunks = (vm: RemoteVm, vmId: string, archivePath: string, remoteArchivePath: string, label: string) => Promise<void>;
+export type ExecFileAsync = (file: string, args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type PushvmPluginUtils = {
+    checkedExec(vm: RemoteVm, command: string, timeoutMs?: number): Promise<{
+        stdout?: string | null;
+        stderr?: string | null;
+        statusCode?: number | null;
+    }>;
+    createTar(args: string[]): Promise<void>;
+    uploadArchiveInChunks: UploadArchiveInChunks;
+    execFileAsync: ExecFileAsync;
+    shellQuote(value: string): string;
+    md5(value: string): string;
+    delay(ms: number): Promise<void>;
+};
+export type PushvmPluginContext = {
+    options: CliOptions;
+    utils: PushvmPluginUtils;
+};
+export type RemoteHookContext = PushvmPluginContext & {
+    vm: RemoteVm;
+    vmId: string;
+};
+export type EditorScheme = string;
+export type EditorHookContext = RemoteHookContext & {
+    scheme: EditorScheme;
+    remoteWorkspaceUri: string;
+};
+export type ConnectHookContext = RemoteHookContext & {
+    contextCandidates: ContextCandidate[];
+    runBeforeOpenRemoteEditor(args: {
+        scheme: EditorScheme;
+        remoteWorkspaceUri: string;
+    }): Promise<string[]>;
+    runAfterOpenRemoteEditor(args: {
+        scheme: EditorScheme;
+        remoteWorkspaceUri: string;
+    }): Promise<string[]>;
+};
+export type ProjectSyncInclude = string | {
+    source: string;
+    target?: string;
+};
+export type ProjectSyncConfig = {
+    exclude?: string[];
+    include?: ProjectSyncInclude[];
+};
+export type PushvmPlugin = {
+    name: string;
+    collectEnvironment?(context: PushvmPluginContext): Record<string, string>;
+    discoverContextCandidates?(context: PushvmPluginContext): Promise<ContextCandidate[]> | ContextCandidate[];
+    configureProjectSync?(context: PushvmPluginContext): Promise<ProjectSyncConfig | void> | ProjectSyncConfig | void;
+    shouldSkipContextDirectory?(relativePath: string, name: string): boolean;
+    isProtectedRemotePath?(remotePath: string): boolean;
+    afterProjectSync?(context: RemoteHookContext): Promise<void> | void;
+    afterContextSync?(context: RemoteHookContext & {
+        changedRemotePaths: string[];
+    }): Promise<void> | void;
+    beforeSnapshot?(context: RemoteHookContext): Promise<void> | void;
+    afterSync?(context: RemoteHookContext & {
+        contextCandidates: ContextCandidate[];
+    }): Promise<string[] | void> | string[] | void;
+    connect?(context: ConnectHookContext): Promise<boolean | void> | boolean | void;
+    beforeOpenRemoteEditor?(context: EditorHookContext & {
+        contextCandidates: ContextCandidate[];
+    }): Promise<string[] | void> | string[] | void;
+    afterOpenRemoteEditor?(context: EditorHookContext & {
+        contextCandidates: ContextCandidate[];
+    }): Promise<string[] | void> | string[] | void;
+};
+export type PushvmConfig = {
+    plugins: PushvmPlugin[];
+    sync?: ProjectSyncConfig;
+};
+export declare function definePlugin(plugin: PushvmPlugin): PushvmPlugin;
+export declare function defineConfig(config: PushvmConfig): PushvmConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freestyle-sync",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "main": "dist/src/main.js",
   "exports": {
@@ -25,7 +25,9 @@
     "publish": "npm run check && npm run build && npm run publish:workspaces && npm run publish:root",
     "publish:root": "node scripts/publish-root.mjs",
     "publish:workspaces": "node scripts/publish-workspaces.mjs",
-    "start": "node src/main.ts"
+    "start": "node src/main.ts",
+    "version:patch": "node scripts/version-workspaces.mjs patch",
+    "version:workspaces": "node scripts/version-workspaces.mjs"
   },
   "dependencies": {
     "dotenv": "^17.4.2",