tapeo-cli 0.0.0-stage → 0.4.0

package/shared/sync.mjs

@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import { chmod, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const sha256 = (content) => createHash("sha256").update(content, "utf8").digest("hex");
+
+export function safeSourcePath(value) {
+  return typeof value === "string" && value.length <= 512 && value.length > 0 && !value.startsWith("/") && !value.includes("\\")
+    && !value.split("/").some((part) => !part || part === "." || part === "..")
+    && !value.startsWith("generated/") && !value.startsWith("signoff/") && value !== ".git" && !value.startsWith(".git/") && value !== ".tapeo" && !value.startsWith(".tapeo/");
+}
+
+async function exists(file) { try { await stat(file); return true; } catch (error) { if (error?.code === "ENOENT") return false; throw error; } }
+
+/** A local symlink must not redirect a project file outside the chosen folder. */
+export async function localTarget(directory, projectPath) {
+  let target = path.resolve(directory);
+  for (const part of projectPath.split("/")) {
+    target = path.join(target, part);
+    try { if ((await lstat(target)).isSymbolicLink()) throw new Error(`Refusing symlink in project path: ${projectPath}`); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+  return target;
+}
+
+/** Preserve a remote revision beside the local edit so a conflict is resolvable offline. */
+async function saveRemoteCopy(client, projectId, directory, projectPath) {
+  const { file } = await client.file(projectId, projectPath);
+  const suffix = file.sha256 || sha256(file.content);
+  const relative = `.tapeo/conflicts/${projectPath}.${suffix.slice(0, 12)}.server`;
+  const destination = await localTarget(directory, relative);
+  await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+  await writeFile(destination, file.content, { encoding: "utf8", mode: 0o600 });
+  return relative;
+}
+
+export async function readState(directory) {
+  const state = JSON.parse(await readFile(await localTarget(directory, ".tapeo/state.json"), "utf8"));
+  if (!state || state.version !== 1 || typeof state.projectId !== "string" || typeof state.files !== "object") throw new Error("Invalid .tapeo/state.json.");
+  return state;
+}
+
+/** Creating a second project must never silently replace this folder's binding. */
+export async function assertUnbound(directory) {
+  try {
+    const state = await readState(directory);
+    throw new Error(`This folder already belongs to Tapeo project ${state.projectId}. Choose another folder.`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+async function writeState(directory, state) {
+  const destination = await localTarget(directory, ".tapeo/state.json");
+  await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+  await writeFile(destination, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+}
+
+/** Pull editable source text; leave local changes untouched and report conflicts. */
+export async function pullProject(client, projectId, directory) {
+  const { files } = await client.project(projectId);
+  const state = await readState(directory).catch((error) => { if (error.code === "ENOENT") return { version: 1, serverUrl: client.serverUrl, projectId, files: {} }; throw error; });
+  if (state.projectId !== projectId || state.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo project or server.");
+  const pulled = [], skipped = [], conflicts = [], remoteCopies = {};
+  for (const remote of files) {
+    if (!safeSourcePath(remote.path) || Number(remote.sizeBytes ?? 0) > 2 * 1024 * 1024) { skipped.push(remote.path); continue; }
+    const destination = await localTarget(directory, remote.path);
+    const tracked = state.files[remote.path];
+    if (await exists(destination)) {
+      const local = await readFile(destination, "utf8");
+      const localSha = sha256(local);
+      if (remote.contentSha256 && localSha === remote.contentSha256) {
+        state.files[remote.path] = { sha256: localSha, language: remote.language };
+        continue;
+      }
+      if (!tracked || localSha !== tracked.sha256) {
+        conflicts.push(remote.path);
+        if (remote.contentSha256 && remote.contentSha256 !== tracked?.sha256) {
+          remoteCopies[remote.path] = await saveRemoteCopy(client, projectId, directory, remote.path);
+        }
+        continue;
+      }
+    }
+    if (tracked?.sha256 === remote.contentSha256 && await exists(destination)) continue;
+    const { file } = await client.file(projectId, remote.path);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, file.content, "utf8");
+    state.files[remote.path] = { sha256: file.sha256, language: file.language };
+    pulled.push(remote.path);
+  }
+  await writeState(directory, state);
+  return { pulled, skipped, conflicts, remoteCopies };
+}
+
+/** Push one explicitly named file; a 409 means the server changed since pull. */
+export async function pushProjectFile(client, directory, projectPath) {
+  if (!safeSourcePath(projectPath)) throw new Error("Use a safe project-relative source path.");
+  const state = await readState(directory);
+  if (state.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo server.");
+  const content = await readFile(await localTarget(directory, projectPath), "utf8");
+  if (Buffer.byteLength(content, "utf8") > 2 * 1024 * 1024) throw new Error("Local edits are limited to 2 MB per file.");
+  const base = state.files[projectPath]?.sha256 ?? null;
+  let result;
+  try {
+    result = await client.saveFile(state.projectId, projectPath, content, base, state.files[projectPath]?.language ?? languageFor(projectPath));
+  } catch (error) {
+    if (error?.status === 409) {
+      let location = "";
+      try { location = await saveRemoteCopy(client, state.projectId, directory, projectPath); }
+      catch { /* A second failed request must never hide the original conflict. */ }
+      throw new Error(`Server file changed. Your local edit is untouched.${location ? ` Compare it with ${location}, then resolve and pull again.` : " Fetch the server copy and resolve before retrying."}`);
+    }
+    throw error;
+  }
+  state.files[projectPath] = { sha256: result.sha256, language: state.files[projectPath]?.language ?? languageFor(projectPath) };
+  await writeState(directory, state);
+  return result;
+}
+
+/** Source files a local folder can add to a project. Other files (builds, editor caches) stay local. */
+export const SOURCE_EXTENSIONS = [".sv", ".svh", ".v", ".vh", ".vhd", ".vhdl", ".sdc", ".tcl", ".xdc", ".hex", ".mem", ".c", ".h", ".s", ".S", ".ld", ".py", ".md", ".txt", ".json", ".yaml", ".yml", ".f", ".lib"];
+const SKIPPED_DIRECTORIES = new Set(["generated", "signoff", "node_modules", "build", "dist", "obj_dir", "sim_build"]);
+const MAX_EDIT_BYTES = 2 * 1024 * 1024;
+
+async function sourceFiles(root, relative = "") {
+  const found = [];
+  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || entry.isSymbolicLink()) continue;
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) { if (!(relative === "" && SKIPPED_DIRECTORIES.has(entry.name)) && entry.name !== "node_modules") found.push(...await sourceFiles(root, child)); }
+    else if (entry.isFile() && SOURCE_EXTENSIONS.includes(path.extname(entry.name)) && safeSourcePath(child)) found.push(child);
+  }
+  return found;
+}
+
+/**
+ * What changed in a bound folder since the last pull or push: modified and
+ * deleted tracked files, and new source files (by extension, outside
+ * generated/, signoff/, hidden folders, and build folders).
+ */
+export async function localChanges(directory) {
+  const state = await readState(directory);
+  const modified = [], deleted = [], added = [], tooLarge = [];
+  for (const [projectPath, tracked] of Object.entries(state.files)) {
+    const target = await localTarget(directory, projectPath);
+    if (!await exists(target)) { deleted.push(projectPath); continue; }
+    if (sha256(await readFile(target, "utf8")) !== tracked.sha256) modified.push(projectPath);
+  }
+  for (const candidate of await sourceFiles(path.resolve(directory))) {
+    if (state.files[candidate]) continue;
+    if ((await stat(await localTarget(directory, candidate))).size > MAX_EDIT_BYTES) tooLarge.push(candidate);
+    else added.push(candidate);
+  }
+  return { projectId: state.projectId, serverUrl: state.serverUrl, modified: modified.sort(), added: added.sort(), deleted: deleted.sort(), tooLarge: tooLarge.sort() };
+}
+
+const LANGUAGES = { ".sv": "systemverilog", ".svh": "systemverilog", ".v": "verilog", ".vh": "verilog", ".vhd": "vhdl", ".vhdl": "vhdl", ".tcl": "tcl", ".sdc": "tcl", ".xdc": "tcl", ".c": "c", ".h": "c", ".s": "asm", ".S": "asm", ".py": "python", ".md": "markdown", ".json": "json", ".yaml": "yaml", ".yml": "yaml" };
+/** The language recorded for a new file, from its extension. */
+export function languageFor(projectPath) { return LANGUAGES[path.extname(projectPath)] ?? "plaintext"; }
+
+/**
+ * Push every modified and new file. Each file is checked against the server
+ * separately, so one conflict does not stop the rest. Deleted files are only
+ * reported: deleting on the server is an explicit `rm`.
+ */
+export async function pushChanges(client, directory) {
+  const changes = await localChanges(directory);
+  const saved = [], conflicts = [], failed = [];
+  for (const projectPath of [...changes.modified, ...changes.added]) {
+    try { saved.push((await pushProjectFile(client, directory, projectPath)).path); }
+    catch (error) {
+      if (/Server file changed/.test(error.message)) conflicts.push({ path: projectPath, message: error.message });
+      else if (error?.status === 401 || error?.status === 0) throw error;
+      else failed.push({ path: projectPath, message: error.message });
+    }
+  }
+  return { saved, conflicts, failed, deletedLocally: changes.deleted, tooLarge: changes.tooLarge };
+}
+
+/** Delete a tracked file on the server (only the version last pulled) and locally. */
+export async function removeProjectFile(client, directory, projectPath) {
+  if (!safeSourcePath(projectPath)) throw new Error("Use a safe project-relative source path.");
+  const state = await readState(directory);
+  if (state.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo server.");
+  const tracked = state.files[projectPath];
+  if (!tracked) throw new Error(`${projectPath} is not tracked in this folder. Pull the project first.`);
+  try { await client.deleteFile(state.projectId, projectPath, tracked.sha256); }
+  catch (error) {
+    if (error?.status === 409) throw new Error(`Server file changed since your last pull, so it was not deleted. Pull it and decide.`);
+    if (error?.status !== 404) throw error;
+  }
+  await rm(await localTarget(directory, projectPath), { force: true });
+  delete state.files[projectPath];
+  await writeState(directory, state);
+}
+
+/** Rename a file: the new path is added on the server, then the old one is deleted. */
+export async function moveProjectFile(client, directory, from, to) {
+  if (!safeSourcePath(from) || !safeSourcePath(to)) throw new Error("Use safe project-relative source paths.");
+  if (from === to) throw new Error("The new path is the same as the old one.");
+  const state = await readState(directory);
+  if (!state.files[from]) throw new Error(`${from} is not tracked in this folder. Pull the project first.`);
+  if (state.files[to]) throw new Error(`${to} already exists in the project.`);
+  const source = await localTarget(directory, from);
+  const destination = await localTarget(directory, to);
+  if (await exists(destination)) throw new Error(`${to} already exists locally.`);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await rename(source, destination);
+  // Keep the old file's language for the new path.
+  const language = state.files[from].language ?? languageFor(to);
+  try {
+    const content = await readFile(destination, "utf8");
+    const result = await client.saveFile(state.projectId, to, content, null, language);
+    state.files[to] = { sha256: result.sha256, language };
+    await writeState(directory, state);
+  } catch (error) {
+    await rename(destination, source).catch(() => undefined);
+    throw error;
+  }
+  try {
+    await client.deleteFile(state.projectId, from, state.files[from].sha256);
+  } catch (error) {
+    throw new Error(`${to} was added, but ${from} could not be removed on the server: ${error.message}`);
+  }
+  delete state.files[from];
+  await writeState(directory, state);
+}
+
+const OUTPUT_PREFIXES = ["generated/", "signoff/"];
+/** Default size limit for `pull --outputs`; larger outputs (a layout) are listed for an explicit download. */
+export const MAX_OUTPUT_BYTES = 25 * 1024 * 1024;
+
+async function writeReadOnly(destination, bytes) {
+  await mkdir(path.dirname(destination), { recursive: true });
+  await rm(destination, { force: true });
+  await writeFile(destination, bytes, { mode: 0o444 });
+  await chmod(destination, 0o444);
+}
+
+/**
+ * Download tool outputs (generated/ and signoff/) read-only, for reading
+ * reports, netlists, and layouts locally. They are never pushed back; a
+ * later pull refreshes only the ones that changed.
+ */
+export async function pullOutputs(client, projectId, directory, { maxBytes = MAX_OUTPUT_BYTES } = {}) {
+  const state = await readState(directory);
+  if (state.projectId !== projectId || state.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo project or server.");
+  const { files } = await client.project(projectId);
+  state.outputs ??= {};
+  const downloaded = [], unchanged = [], skipped = [];
+  for (const remote of files) {
+    if (!OUTPUT_PREFIXES.some((prefix) => remote.path.startsWith(prefix))) continue;
+    if (Number(remote.sizeBytes ?? 0) > maxBytes) { skipped.push({ path: remote.path, sizeBytes: Number(remote.sizeBytes) }); continue; }
+    const destination = await localTarget(directory, remote.path);
+    if (remote.contentSha256 && state.outputs[remote.path]?.sha256 === remote.contentSha256 && await exists(destination)) { unchanged.push(remote.path); continue; }
+    const { bytes } = await client.rawFile(projectId, remote.path);
+    await writeReadOnly(destination, bytes);
+    state.outputs[remote.path] = { sha256: remote.contentSha256 ?? null };
+    downloaded.push(remote.path);
+  }
+  await writeState(directory, state);
+  return { downloaded, unchanged, skipped };
+}
+
+/** Download one project file (any size, text or binary) to a local path. */
+export async function downloadFile(client, projectId, projectPath, destination) {
+  const { bytes } = await client.rawFile(projectId, projectPath);
+  await mkdir(path.dirname(path.resolve(destination)), { recursive: true });
+  await writeFile(destination, bytes);
+  return { path: projectPath, bytes: bytes.length, destination };
+}
+
+/** Design files a new design can start from: the browser's upload types and limits (20 files, 300 KB). */
+export const DESIGN_EXTENSIONS = [".v", ".sv", ".vh", ".svh", ".vhd", ".vhdl", ".sdc", ".tcl", ".hex", ".mem"];
+export async function designFilesFrom(directory, { maxFiles = 20, maxBytes = 300 * 1024 } = {}) {
+  const files = [];
+  let total = 0;
+  for (const candidate of await sourceFiles(path.resolve(directory))) {
+    if (!DESIGN_EXTENSIONS.includes(path.extname(candidate))) continue;
+    const content = await readFile(await localTarget(directory, candidate), "utf8");
+    total += Buffer.byteLength(content, "utf8");
+    files.push({ path: candidate, content });
+  }
+  if (files.length > maxFiles) throw new Error(`Found ${files.length} design files; start from at most ${maxFiles}.`);
+  if (total > maxBytes) throw new Error(`Design files total ${Math.ceil(total / 1024)} KB; the limit is ${maxBytes / 1024} KB.`);
+  return files;
+}