freestyle-sync 0.1.10 → 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,6 +42,9 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
@@ -81,7 +53,7 @@ export default defineConfig({
 });
 ```
 
-Project sync 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.
+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({
@@ -90,15 +62,50 @@ export default defineConfig({
         include: [
             { source: "../shared-config", target: "shared-config" },
         ],
-    },
-    plugins: [
-        nodeNpmPlugin(),
-    ],
+    }
 });
 ```
 
-`nodeNpmPlugin()` excludes `node_modules` from upload by default and installs dependencies on the remote runtime using the project lockfile: `pnpm install --frozen-lockfile`, Yarn `--frozen-lockfile`/`--immutable`, or `npm ci`. To keep the previous behavior of syncing `node_modules` and only repairing native/workspace packages remotely, use:
+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

@@ -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,
@@ -375,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({
@@ -392,6 +398,9 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
@@ -414,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({
@@ -431,6 +443,9 @@ export default defineConfig({
         azureAuthPlugin(),
         gcloudAuthPlugin(),
         nodeNpmPlugin(),
+        nextjsPlugin(),
+        vitePlugin(),
+        rustPlugin(),
         claudeAgentPlugin(),
         codexAgentPlugin(),
         copilotAgentPlugin(),
@@ -1581,6 +1596,8 @@ 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 --frozen-lockfile";
     if (await exists(path.join(projectRoot, "yarn.lock")))
@@ -1648,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`;
@@ -1668,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`,
@@ -1686,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.10",
+  "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",