freestyle-sync 0.1.4 → 0.1.5

package/README.md

@@ -6,8 +6,35 @@ Sync your current directory, it's dependencies, and your agent context into a VM
 npx freestyle-sync
 ```
 
-Configure complex sync behavior using plugins.
+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 VM", 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.
+
+```js
 import { defineConfig } from "freestyle-sync";
 import { claudeAgentPlugin } from "@freestyle-sync/agent-claude";
 import { codexAgentPlugin } from "@freestyle-sync/agent-codex";
@@ -44,5 +71,4 @@ export default defineConfig({
         shellHistoryPlugin(),
     ],
 });
-
 ```

package/dist/src/main.js

@@ -19,14 +19,31 @@ import { promisify } from "node:util";
 import { freestyle } from "freestyle";
 export * from "./plugin-api.js";
 const execFileAsync = promisify(execFile);
+const CLI_NAME = "freestyle-sync";
 const CACHE_VERSION = 1;
 const PLUGIN_PREFERENCES_VERSION = 1;
 const ARCHIVE_CHUNK_CHARS = 1024 * 1024;
 const MS_PER_SECOND = 1000;
 const USE_UNICODE_OUTPUT = process.stdout.isTTY && (process.env.TERM !== "dumb" || Boolean(process.env.TERM_PROGRAM));
 const USE_STYLED_OUTPUT = process.stdout.isTTY && process.env.NO_COLOR !== "1";
-let config = { plugins: [] };
-let plugins = config.plugins;
+const DEFAULT_CONFIG_DEPENDENCIES = [
+    { name: "freestyle-sync", spec: "freestyle-sync@latest" },
+    { name: "@freestyle-sync/agent-claude", spec: "@freestyle-sync/agent-claude@latest" },
+    { name: "@freestyle-sync/agent-codex", spec: "@freestyle-sync/agent-codex@latest" },
+    { name: "@freestyle-sync/agent-copilot", spec: "@freestyle-sync/agent-copilot@latest" },
+    { name: "@freestyle-sync/auth-aws", spec: "@freestyle-sync/auth-aws@latest" },
+    { name: "@freestyle-sync/auth-azure", spec: "@freestyle-sync/auth-azure@latest" },
+    { name: "@freestyle-sync/auth-docker", spec: "@freestyle-sync/auth-docker@latest" },
+    { name: "@freestyle-sync/auth-env", spec: "@freestyle-sync/auth-env@latest" },
+    { name: "@freestyle-sync/auth-gcloud", spec: "@freestyle-sync/auth-gcloud@latest" },
+    { name: "@freestyle-sync/auth-git", spec: "@freestyle-sync/auth-git@latest" },
+    { name: "@freestyle-sync/auth-github-cli", spec: "@freestyle-sync/auth-github-cli@latest" },
+    { 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/node-npm", spec: "@freestyle-sync/node-npm@latest" },
+    { name: "@freestyle-sync/shell-history", spec: "@freestyle-sync/shell-history@latest" },
+];
 const pluginUtils = {
     checkedExec,
     createTar,
@@ -36,6 +53,8 @@ const pluginUtils = {
     md5,
     delay,
 };
+let config = { plugins: [] };
+let plugins = config.plugins;
 class Progress {
     current = 0;
     total;
@@ -68,39 +87,66 @@ class Progress {
 }
 if (isDirectCliExecution()) {
     main().catch((error) => {
-        console.error(`vmpush: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`${CLI_NAME}: ${error instanceof Error ? error.message : String(error)}`);
         process.exitCode = 1;
     });
 }
 async function main() {
     const options = await parseArgs(process.argv.slice(2));
-    printHeading("vmpush");
-    config = await loadConfig(options.projectRoot);
+    const loadedConfig = await loadConfig(options.projectRoot);
+    await sync({
+        config: loadedConfig,
+        options,
+    });
+}
+export async function sync(sdkOptions) {
+    const options = await resolveCliOptions(sdkOptions.options);
+    printHeading(CLI_NAME);
+    config = sdkOptions.config;
     plugins = config.plugins;
-    const pluginPreferences = await updatePluginPreferences(options);
+    const pluginPreferences = await updatePluginPreferences(options, sdkOptions.pluginPreferences);
     plugins = activePlugins(pluginPreferences, options);
+    let currentCache = sdkOptions.cache ? normalizeCache(sdkOptions.cache, options) : await readCache(options.cachePath, options);
+    let resultVmId;
+    const saveCache = async (nextCache) => {
+        currentCache = nextCache;
+        if (sdkOptions.onCacheUpdate) {
+            await sdkOptions.onCacheUpdate(nextCache);
+            return;
+        }
+        if (!sdkOptions.cache) {
+            await writeCache(options.cachePath, nextCache);
+        }
+    };
     if (options.listPlugins) {
         printPlugins(pluginPreferences, options);
-        return;
+        return {
+            cache: currentCache,
+            snapshotId: currentCache.snapshotId,
+        };
     }
     if (options.dryRun) {
-        console.log("vmpush dry run");
+        console.log(`${CLI_NAME} dry run`);
     }
     if (options.skipSync) {
         const progress = new Progress(3);
         progress.step("Reading sync cache");
-        const cache = await readCache(options.cachePath, options);
+        const cache = currentCache;
         if (!options.vmId && !cache.snapshotId) {
-            console.warn("vmpush --skip-sync: no cached snapshot found. A new empty VM will be created. Run without --skip-sync first to create a snapshot.");
+            console.warn(`${CLI_NAME} --skip-sync: no cached snapshot found. A new empty VM will be created. Run without --skip-sync first to create a snapshot.`);
         }
         const source = options.vmId ? `existing VM ${options.vmId}` : cache.snapshotId ? `snapshot ${cache.snapshotId}` : "a new VM";
         console.log(`Skipping sync: creating VM from ${source}`);
         console.log(`Remote project: ${options.remoteProjectDir}`);
         if (options.dryRun) {
-            return;
+            return {
+                cache: currentCache,
+                snapshotId: currentCache.snapshotId,
+            };
         }
         progress.step("Preparing Freestyle VM");
         const { vm, vmId } = await getOrCreateVm(options, cache.snapshotId);
+        resultVmId = vmId;
         console.log(`Using VM: ${vmId}`);
         progress.step(`Running post-sync plugins for ${vmId}`);
         const contextCandidates = await discoverPluginContextCandidates(options);
@@ -119,11 +165,15 @@ async function main() {
             if (!connected)
                 await sshIntoVm(vmId);
         }
-        return;
+        return {
+            vmId,
+            cache: currentCache,
+            snapshotId: currentCache.snapshotId,
+        };
     }
     const progress = new Progress(options.dryRun ? 2 : options.install ? 12 : 11);
     progress.step("Scanning project files");
-    const cache = await readCache(options.cachePath, options);
+    const cache = currentCache;
     const base = cacheBaseForSync(options, cache);
     const projectEntries = await scanProject(options.projectRoot, options.includeGitDir);
     const projectCurrent = digestMap(projectEntries);
@@ -138,10 +188,14 @@ async function main() {
     printPlan(options, projectChanges, contextChanges, envExports, cache);
     if (options.dryRun) {
         progress.finish();
-        return;
+        return {
+            cache: currentCache,
+            snapshotId: currentCache.snapshotId,
+        };
     }
     progress.step("Preparing Freestyle VM");
     const { vm, vmId } = await getOrCreateVm(options, cache.snapshotId);
+    resultVmId = vmId;
     console.log(`Uploading to VM: ${vmId}`);
     progress.step(`Uploading project changes to ${vmId}`);
     await ensureRemoteBase(vm, options.remoteProjectDir);
@@ -175,14 +229,14 @@ async function main() {
         updatedAt: new Date().toISOString(),
     });
     progress.step("Saving local sync cache");
-    await writeCache(options.cachePath, buildSyncCache());
+    await saveCache(buildSyncCache());
     let snapshotPromise = null;
     if (options.snapshot) {
         progress.step(`Creating snapshot cache for ${vmId} in background`);
         snapshotPromise = (async () => {
             await runBeforeSnapshotPlugins(vm, vmId, options);
             try {
-                const snapshot = await vm.snapshot({ name: `vmpush-${path.basename(options.projectRoot)}-${Date.now()}` });
+                const snapshot = await vm.snapshot({ name: `${CLI_NAME}-${path.basename(options.projectRoot)}-${Date.now()}` });
                 return snapshot.snapshotId;
             }
             catch (error) {
@@ -219,10 +273,15 @@ async function main() {
     if (snapshotPromise) {
         const newSnapshotId = await snapshotPromise;
         if (newSnapshotId) {
-            await writeCache(options.cachePath, buildSyncCache({ snapshotId: newSnapshotId }));
+            await saveCache(buildSyncCache({ snapshotId: newSnapshotId }));
             console.log(`Snapshot cache saved: ${newSnapshotId}`);
         }
     }
+    return {
+        vmId: resultVmId,
+        cache: currentCache,
+        snapshotId: currentCache.snapshotId,
+    };
 }
 function isDirectCliExecution() {
     if (!process.argv[1])
@@ -235,11 +294,7 @@ function isDirectCliExecution() {
     }
 }
 async function loadConfig(projectRoot) {
-    const configPath = path.join(projectRoot, "freestyle-sync.config.ts");
-    if (!(await exists(configPath))) {
-        await writeFile(configPath, renderDefaultConfig(), "utf8");
-        console.log(`Created ${path.relative(process.cwd(), configPath) || path.basename(configPath)}`);
-    }
+    const configPath = await resolveConfigPath(projectRoot);
     const imported = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
     const loaded = imported.default;
     if (!loaded || !Array.isArray(loaded.plugins)) {
@@ -247,6 +302,90 @@ async function loadConfig(projectRoot) {
     }
     return loaded;
 }
+async function resolveConfigPath(projectRoot) {
+    const jsConfigPath = path.join(projectRoot, "freestyle-sync.config.mjs");
+    const tsConfigPath = path.join(projectRoot, "freestyle-sync.config.ts");
+    if (await exists(jsConfigPath)) {
+        if (await migrateBundledDefaultConfig(jsConfigPath)) {
+            await ensureDefaultConfigDependencies(projectRoot);
+        }
+        else if (await isDefaultGeneratedConfig(jsConfigPath)) {
+            await ensureDefaultConfigDependencies(projectRoot);
+        }
+        return jsConfigPath;
+    }
+    if (await exists(tsConfigPath)) {
+        if (await migrateLegacyDefaultConfig(tsConfigPath, jsConfigPath)) {
+            await ensureDefaultConfigDependencies(projectRoot);
+            return jsConfigPath;
+        }
+        return tsConfigPath;
+    }
+    await writeFile(jsConfigPath, renderDefaultConfig(), "utf8");
+    console.log(`Created ${path.relative(process.cwd(), jsConfigPath) || path.basename(jsConfigPath)}`);
+    await ensureDefaultConfigDependencies(projectRoot);
+    return jsConfigPath;
+}
+async function isDefaultGeneratedConfig(configPath) {
+    const contents = await readFile(configPath, "utf8").catch(() => "");
+    return contents.trim() === renderDefaultConfig().trim();
+}
+async function migrateBundledDefaultConfig(configPath) {
+    const contents = await readFile(configPath, "utf8").catch(() => "");
+    if (contents.trim() !== renderBundledDefaultConfig().trim())
+        return false;
+    await writeFile(configPath, renderDefaultConfig(), "utf8");
+    console.log(`Updated ${path.relative(process.cwd(), configPath) || path.basename(configPath)} to install plugin packages`);
+    return true;
+}
+async function migrateLegacyDefaultConfig(tsConfigPath, jsConfigPath) {
+    const contents = await readFile(tsConfigPath, "utf8").catch(() => "");
+    if (contents.trim() !== renderLegacyDefaultConfig().trim())
+        return false;
+    await writeFile(jsConfigPath, renderDefaultConfig(), "utf8");
+    await rm(tsConfigPath);
+    console.log(`Updated ${path.relative(process.cwd(), jsConfigPath) || path.basename(jsConfigPath)} to install plugin packages`);
+    return true;
+}
+function renderLegacyDefaultConfig() {
+    return `import { claudeAgentPlugin } from "@freestyle-sync/agent-claude";
+import { codexAgentPlugin } from "@freestyle-sync/agent-codex";
+import { copilotAgentPlugin } from "@freestyle-sync/agent-copilot";
+import { awsAuthPlugin } from "@freestyle-sync/auth-aws";
+import { azureAuthPlugin } from "@freestyle-sync/auth-azure";
+import { dockerAuthPlugin } from "@freestyle-sync/auth-docker";
+import { envAuthPlugin } from "@freestyle-sync/auth-env";
+import { gcloudAuthPlugin } from "@freestyle-sync/auth-gcloud";
+import { gitAuthPlugin } from "@freestyle-sync/auth-git";
+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 { nodeNpmPlugin } from "@freestyle-sync/node-npm";
+import { shellHistoryPlugin } from "@freestyle-sync/shell-history";
+import { defineConfig } from "freestyle-sync";
+
+export default defineConfig({
+    plugins: [
+        envAuthPlugin(),
+        gitAuthPlugin(),
+        sshAuthPlugin(),
+        githubCliAuthPlugin(),
+        npmAuthPlugin(),
+        yarnAuthPlugin(),
+        dockerAuthPlugin(),
+        awsAuthPlugin(),
+        azureAuthPlugin(),
+        gcloudAuthPlugin(),
+        nodeNpmPlugin(),
+        claudeAgentPlugin(),
+        codexAgentPlugin(),
+        copilotAgentPlugin(),
+        shellHistoryPlugin(),
+    ],
+});
+`;
+}
 function renderDefaultConfig() {
     return `import { claudeAgentPlugin } from "@freestyle-sync/agent-claude";
 import { codexAgentPlugin } from "@freestyle-sync/agent-codex";
@@ -286,28 +425,43 @@ export default defineConfig({
 });
 `;
 }
+function renderBundledDefaultConfig() {
+    return `export default {
+    plugins: "default",
+};
+`;
+}
+async function ensureDefaultConfigDependencies(projectRoot) {
+    const missing = [];
+    for (const dependency of DEFAULT_CONFIG_DEPENDENCIES) {
+        if (!(await isDependencyInstalled(projectRoot, dependency.name))) {
+            missing.push(dependency.spec);
+        }
+    }
+    if (missing.length === 0)
+        return;
+    const { command, args } = await dependencyInstallCommand(projectRoot, missing);
+    console.log(`Installing freestyle-sync config dependencies with ${command}...`);
+    try {
+        await execFileAsync(command, args, { cwd: projectRoot });
+    }
+    catch (error) {
+        const details = error && typeof error === "object" && "stderr" in error ? String(error.stderr ?? "") : String(error);
+        throw new Error(`failed to install freestyle-sync config dependencies: ${details.trim() || String(error)}`);
+    }
+}
+async function isDependencyInstalled(projectRoot, name) {
+    return exists(path.join(projectRoot, "node_modules", ...name.split("/"), "package.json"));
+}
+async function dependencyInstallCommand(projectRoot, specs) {
+    if (await exists(path.join(projectRoot, "pnpm-lock.yaml")))
+        return { command: "pnpm", args: ["add", "-D", ...specs] };
+    if (await exists(path.join(projectRoot, "yarn.lock")))
+        return { command: "yarn", args: ["add", "-D", ...specs] };
+    return { command: "npm", args: ["install", "--save-dev", ...specs] };
+}
 async function parseArgs(args) {
-    const options = {
-        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,
-        skipSync: false,
-        install: false,
-        autoSsh: true,
-        envKeys: [],
-    };
+    const options = defaultCliOptions();
     const positional = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -389,25 +543,65 @@ async function parseArgs(args) {
         throw new Error("expected at most one project path");
     }
     options.projectRoot = path.resolve(positional[0] ?? options.projectRoot);
+    return finalizeCliOptions(options);
+}
+async function resolveCliOptions(overrides) {
+    return finalizeCliOptions({
+        ...defaultCliOptions(),
+        ...overrides,
+        projectRoot: path.resolve(overrides?.projectRoot ?? process.cwd()),
+        disablePlugins: overrides?.disablePlugins ? [...overrides.disablePlugins] : [],
+        enablePlugins: overrides?.enablePlugins ? [...overrides.enablePlugins] : [],
+        envKeys: overrides?.envKeys ? [...overrides.envKeys] : [],
+    });
+}
+function defaultCliOptions() {
+    return {
+        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,
+        skipSync: false,
+        install: false,
+        autoSsh: true,
+        envKeys: [],
+    };
+}
+async function finalizeCliOptions(options) {
     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;
+    const remoteProjectDir = options.remoteProjectDir ? normalizeRemotePath(options.remoteProjectDir) : defaultRemoteProjectDir(options.projectRoot);
+    const cachePath = options.cachePath ? path.resolve(options.cachePath) : path.join(options.projectRoot, ".freestyle-sync", "cache.json");
+    return {
+        ...options,
+        name: options.name || `${CLI_NAME}-${projectName}`,
+        remoteProjectDir,
+        cachePath,
+    };
 }
 function printHelp() {
-    console.log(`vmpush uploads the current project into a Freestyle VM.
+    console.log(`${CLI_NAME} uploads the current project into a Freestyle VM.
 
 Usage:
-	vmpush [project-dir] [options]
+    ${CLI_NAME} [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>.
+    --name <name>            Name for a newly created VM. Defaults to ${CLI_NAME}-<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.
@@ -464,6 +658,18 @@ async function readCache(cachePath, options) {
         contextFiles: {},
     };
 }
+function normalizeCache(cache, options) {
+    return {
+        ...cache,
+        version: CACHE_VERSION,
+        projectRoot: options.projectRoot,
+        remoteProjectDir: options.remoteProjectDir,
+        projectFiles: cache.projectFiles ?? {},
+        contextFiles: cache.contextFiles ?? {},
+        snapshotProjectFiles: cache.snapshotProjectFiles ?? {},
+        snapshotContextFiles: cache.snapshotContextFiles ?? {},
+    };
+}
 function cacheBaseForSync(options, cache) {
     if (options.vmId && options.vmId === cache.vmId) {
         return {
@@ -632,10 +838,13 @@ async function scanContextCandidates(candidates) {
     }
     return entries.sort((left, right) => left.remotePath.localeCompare(right.remotePath));
 }
-async function updatePluginPreferences(options) {
+async function updatePluginPreferences(options, providedPreferences) {
     const preferencesPath = getPluginPreferencesPath(options);
-    const preferences = options.resetPluginPrefs ? emptyPluginPreferences() : await readPluginPreferences(preferencesPath);
-    let changed = options.resetPluginPrefs;
+    const usingProvidedPreferences = Boolean(providedPreferences);
+    const preferences = options.resetPluginPrefs
+        ? emptyPluginPreferences()
+        : normalizePluginPreferences(providedPreferences ?? await readPluginPreferences(preferencesPath));
+    let changed = options.resetPluginPrefs && !usingProvidedPreferences;
     const disabledPlugins = new Set();
     for (const savedName of preferences.disabledPlugins) {
         const canonicalName = maybeResolvePluginSelector(savedName);
@@ -656,7 +865,7 @@ async function updatePluginPreferences(options) {
         }
     }
     const next = { version: PLUGIN_PREFERENCES_VERSION, disabledPlugins: [...disabledPlugins].sort(), updatedAt: preferences.updatedAt };
-    if (changed)
+    if (changed && !usingProvidedPreferences)
         await writePluginPreferences(preferencesPath, next);
     return next;
 }
@@ -719,6 +928,13 @@ function pluginSelectorAliases(name) {
 function emptyPluginPreferences() {
     return { version: PLUGIN_PREFERENCES_VERSION, disabledPlugins: [] };
 }
+function normalizePluginPreferences(preferences) {
+    return {
+        version: PLUGIN_PREFERENCES_VERSION,
+        disabledPlugins: Array.isArray(preferences.disabledPlugins) ? preferences.disabledPlugins.filter((name) => typeof name === "string") : [],
+        updatedAt: preferences.updatedAt,
+    };
+}
 function getPluginPreferencesPath(options) {
     return path.join(path.dirname(options.cachePath), "plugin-preferences.json");
 }
@@ -726,11 +942,7 @@ async function readPluginPreferences(preferencesPath) {
     try {
         const parsed = JSON.parse(await readFile(preferencesPath, "utf8"));
         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,
-            };
+            return normalizePluginPreferences(parsed);
         }
     }
     catch (error) {
@@ -815,8 +1027,8 @@ async function syncProject(vm, vmId, options, changes) {
         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`);
+            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`);
         }
         finally {
             await rm(path.dirname(archive), { recursive: true, force: true });
@@ -825,8 +1037,8 @@ async function syncProject(vm, vmId, options, changes) {
     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`);
+        await vm.fs.writeFile("/tmp/freestyle-sync-remove-list", removeList);
+        await checkedExec(vm, `cd ${shellQuote(options.remoteProjectDir)} && xargs -0 rm -f -- < /tmp/freestyle-sync-remove-list && rm -f /tmp/freestyle-sync-remove-list`);
     }
     return {
         uploaded: changes.changed.length,
@@ -885,8 +1097,8 @@ async function syncContext(vm, vmId, changes) {
     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");
+        await uploadArchiveInChunks(vm, vmId, archive, "/tmp/freestyle-sync-context.tgz", "context");
+        await checkedExec(vm, "tar --no-same-owner --no-same-permissions -xzf /tmp/freestyle-sync-context.tgz -C / && rm -f /tmp/freestyle-sync-context.tgz");
     }
     finally {
         await rm(path.dirname(archive), { recursive: true, force: true });
@@ -954,7 +1166,7 @@ async function detectInstallCommand(projectRoot) {
     return undefined;
 }
 async function createProjectArchive(projectRoot, entries) {
-    const tempDir = await mkdtemp(path.join(tmpdir(), "vmpush-"));
+    const tempDir = await mkdtemp(path.join(tmpdir(), "freestyle-sync-"));
     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"));
@@ -962,7 +1174,7 @@ async function createProjectArchive(projectRoot, entries) {
     return archivePath;
 }
 async function createContextArchive(entries) {
-    const tempDir = await mkdtemp(path.join(tmpdir(), "vmpush-context-"));
+    const tempDir = await mkdtemp(path.join(tmpdir(), "freestyle-sync-context-"));
     const stagingDir = path.join(tempDir, "staging");
     const archivePath = path.join(tempDir, "context.tgz");
     await mkdir(stagingDir, { recursive: true });
@@ -987,17 +1199,29 @@ async function uploadArchiveInChunks(vm, vmId, archivePath, remoteArchivePath, l
     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`;
+    const chunkDir = `/tmp/freestyle-sync-${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;
+    const canRenderInlineProgress = process.stdout.isTTY;
+    const logEvery = Math.max(1, Math.ceil(chunkCount / 4));
     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`);
+        const uploadedChunks = index + 1;
+        if (chunkCount > 1) {
+            const progressMessage = `VM ${vmId}: uploaded ${uploadedChunks}/${chunkCount} ${label} archive chunks`;
+            if (canRenderInlineProgress) {
+                process.stdout.write(`\r${progressMessage}`);
+                if (uploadedChunks === chunkCount) {
+                    process.stdout.write("\n");
+                }
+            }
+            else if (uploadedChunks === 1 || uploadedChunks % logEvery === 0 || uploadedChunks === chunkCount) {
+                console.log(progressMessage);
+            }
         }
     }
     await checkedExec(vm, `cat ${shellQuote(chunkDir)}/*.b64 | base64 -d > ${shellQuote(remoteArchivePath)} && rm -rf ${shellQuote(chunkDir)}`);
@@ -1095,7 +1319,7 @@ function md5(value) {
     return createHash("md5").update(value).digest("hex");
 }
 function renderEnvFile(envExports) {
-    const lines = ["# Generated by vmpush. Contains local auth tokens."];
+    const lines = [`# Generated by ${CLI_NAME}. Contains local auth tokens.`];
     for (const key of Object.keys(envExports).sort()) {
         lines.push(`export ${key}=${shellQuote(envExports[key])}`);
     }
@@ -1115,7 +1339,28 @@ function defaultRemoteProjectDir(projectRoot) {
     return normalizeRemotePath(toPosix(projectRoot));
 }
 function sanitizeName(value) {
-    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+    const lower = value.toLowerCase();
+    let normalized = "";
+    let lastWasDash = false;
+    for (const character of lower) {
+        const isAlpha = character >= "a" && character <= "z";
+        const isDigit = character >= "0" && character <= "9";
+        const isAllowedPunctuation = character === "." || character === "_" || character === "-";
+        if (isAlpha || isDigit || isAllowedPunctuation) {
+            normalized += character;
+            lastWasDash = false;
+            continue;
+        }
+        if (!lastWasDash) {
+            normalized += "-";
+            lastWasDash = true;
+        }
+    }
+    while (normalized.startsWith("-"))
+        normalized = normalized.slice(1);
+    while (normalized.endsWith("-"))
+        normalized = normalized.slice(0, -1);
+    return normalized || "project";
 }
 function toPosix(value) {
     return value.split(path.sep).join(path.posix.sep);