playcanvas-agent-bridge-cli 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { existsSync } from "node:fs";
3
3
  import { watch } from "node:fs";
4
- import { copyFile, lstat, mkdir, readFile, readdir, rename, rmdir, stat, writeFile, } from "node:fs/promises";
4
+ import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile, } from "node:fs/promises";
5
5
  import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
6
6
  const PROJECT_FILE = "pcbridge.project.json";
7
7
  const LEGACY_INDEX_FILE = join(".pcbridge", "asset-index.json");
@@ -30,6 +30,12 @@ function manifestLocalPath(value) {
30
30
  }
31
31
  return join(...parts.slice(1));
32
32
  }
33
+ function localFolderParts(localPath) {
34
+ if (!localPath)
35
+ return [];
36
+ const parent = dirname(localPath);
37
+ return parent === "." ? [] : parent.split(sep).filter(Boolean);
38
+ }
33
39
  export function safeWorkspaceName(value, fallback) {
34
40
  const safe = value
35
41
  .normalize("NFKC")
@@ -49,10 +55,17 @@ export function safeAssetName(value, fallback) {
49
55
  .slice(0, 120);
50
56
  return safe || fallback;
51
57
  }
52
- function collisionName(filename, id) {
58
+ function collisionName(filename, type, id) {
53
59
  const extension = extname(filename);
54
60
  const stem = extension ? filename.slice(0, -extension.length) : filename;
55
- return `${stem}~${id}${extension}`;
61
+ const safeType = safeAssetName(type, "asset").replaceAll(" ", "-").toLocaleLowerCase();
62
+ return `${stem}.__pc_${safeType}_${id}${extension}`;
63
+ }
64
+ function pathNameKey(value) {
65
+ return value.normalize("NFKC").toLocaleLowerCase();
66
+ }
67
+ function resourceKey(filename) {
68
+ return pathNameKey(filename);
56
69
  }
57
70
  function asObject(value) {
58
71
  if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -65,6 +78,23 @@ function isDerivedAsset(asset) {
65
78
  asset.source_asset_id !== null &&
66
79
  asset.source_asset_id !== "";
67
80
  }
81
+ function assetRole(asset) {
82
+ if (isDerivedAsset(asset))
83
+ return "derived";
84
+ return asset.source ? "source" : "standalone";
85
+ }
86
+ async function mapWithConcurrency(values, limit, operation) {
87
+ const results = new Array(values.length);
88
+ let cursor = 0;
89
+ const worker = async () => {
90
+ while (cursor < values.length) {
91
+ const index = cursor++;
92
+ results[index] = await operation(values[index], index);
93
+ }
94
+ };
95
+ await Promise.all(Array.from({ length: Math.min(limit, values.length) }, () => worker()));
96
+ return results;
97
+ }
68
98
  async function atomicWrite(path, value) {
69
99
  await mkdir(dirname(path), { recursive: true });
70
100
  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
@@ -210,9 +240,8 @@ export class WorkspaceManager {
210
240
  record.targetInfo = info;
211
241
  record.connected = true;
212
242
  await this.#sync(record, true);
213
- const assets = [];
214
- for (const rawId of assetIds) {
215
- const id = String(rawId);
243
+ const ids = [...new Set(assetIds.map(String))];
244
+ const assets = await mapWithConcurrency(ids, 4, async (id) => {
216
245
  const entry = record.index.entries[id];
217
246
  if (!entry)
218
247
  throw new Error(`Asset ${id} is not present in the workspace catalog.`);
@@ -222,22 +251,23 @@ export class WorkspaceManager {
222
251
  if (entry.localPath && !existsSync(this.#assetPath(record, entry.localPath))) {
223
252
  await this.#downloadAsset(record, entry);
224
253
  }
225
- let preparedPath = entry.localPath ? this.#assetPath(record, entry.localPath) : null;
226
- let preparedHash = entry.localHash;
227
- if (!preparedPath && entry.filename && entry.remoteFileHash) {
228
- const cached = await this.#prepareCachedAsset(record, entry);
229
- preparedPath = cached.path;
230
- preparedHash = cached.hash;
254
+ const preparedPath = entry.localPath ? this.#assetPath(record, entry.localPath) : null;
255
+ const preparedHash = entry.localHash;
256
+ if (!preparedPath && entry.filename) {
257
+ throw new Error(`Asset ${id} has a remote file but no local assets projection.`);
258
+ }
259
+ if (preparedPath && entry.filename) {
260
+ await this.#removeLegacyResource(this.#legacyCachedFilePath(record, entry.id, entry.filename));
231
261
  }
232
- assets.push({
262
+ return {
233
263
  id,
234
264
  name: entry.name,
235
265
  type: entry.type,
236
266
  filename: entry.filename,
237
267
  path: preparedPath,
238
268
  hash: preparedHash,
239
- });
240
- }
269
+ };
270
+ });
241
271
  await this.#persist(record);
242
272
  return {
243
273
  projectDirectory: record.directory,
@@ -245,6 +275,103 @@ export class WorkspaceManager {
245
275
  assets,
246
276
  };
247
277
  }
278
+ async prepareAssetResources(info, requests) {
279
+ if (!info.projectId)
280
+ throw new Error("The selected target has no project metadata.");
281
+ const record = this.#records.get(info.projectId);
282
+ if (!record)
283
+ throw new Error("The selected project workspace has not been initialized.");
284
+ record.targetId = info.id;
285
+ record.targetInfo = info;
286
+ record.connected = true;
287
+ const unique = new Map();
288
+ for (const request of requests) {
289
+ const assetId = String(request.assetId);
290
+ const key = `${assetId}\0${resourceKey(request.filename)}`;
291
+ const existing = unique.get(key);
292
+ if (existing && existing.url !== request.url) {
293
+ throw new Error(`Asset ${assetId} resource ${request.filename} has multiple remote URLs in one build.`);
294
+ }
295
+ unique.set(key, { ...request, assetId });
296
+ }
297
+ if (!unique.size)
298
+ return [];
299
+ const usedPaths = new Set();
300
+ for (const entry of Object.values(record.index.entries)) {
301
+ if (entry.localPath)
302
+ usedPaths.add(pathNameKey(toPosixPath(entry.localPath)));
303
+ for (const resource of Object.values(entry.resources)) {
304
+ usedPaths.add(pathNameKey(toPosixPath(resource.localPath)));
305
+ }
306
+ }
307
+ const preparedEntries = [];
308
+ const sorted = [...unique.values()].sort((left, right) => {
309
+ const assetDifference = left.assetId.localeCompare(right.assetId, undefined, { numeric: true });
310
+ return assetDifference || left.filename.localeCompare(right.filename);
311
+ });
312
+ for (const request of sorted) {
313
+ const entry = record.index.entries[request.assetId];
314
+ if (!entry)
315
+ throw new Error(`Asset ${request.assetId} is not present in the workspace catalog.`);
316
+ const key = resourceKey(request.filename);
317
+ const old = entry.resources[key];
318
+ if (old)
319
+ usedPaths.delete(pathNameKey(toPosixPath(old.localPath)));
320
+ const safeFilename = safeAssetName(request.filename, `resource-${entry.id}`);
321
+ const allocate = (filename) => join(...entry.localFolderPath, filename);
322
+ const occupied = (localPath) => {
323
+ const pathKey = pathNameKey(toPosixPath(localPath));
324
+ return usedPaths.has(pathKey) ||
325
+ (localPath !== old?.localPath && existsSync(this.#assetPath(record, localPath)));
326
+ };
327
+ let localPath = allocate(safeFilename);
328
+ if (occupied(localPath))
329
+ localPath = allocate(collisionName(safeFilename, "resource", entry.id));
330
+ let suffix = 2;
331
+ while (occupied(localPath)) {
332
+ localPath = allocate(collisionName(safeFilename, "resource", `${entry.id}_${suffix}`));
333
+ suffix += 1;
334
+ }
335
+ usedPaths.add(pathNameKey(toPosixPath(localPath)));
336
+ if (old?.localPath && old.localPath !== localPath && existsSync(this.#assetPath(record, old.localPath))) {
337
+ const oldPath = this.#assetPath(record, old.localPath);
338
+ const nextPath = this.#assetPath(record, localPath);
339
+ await mkdir(dirname(nextPath), { recursive: true });
340
+ await chmod(oldPath, 0o644).catch(() => undefined);
341
+ await rename(oldPath, nextPath);
342
+ }
343
+ const advertisedRemoteHash = request.hash || null;
344
+ const metadataUnchanged = old?.url === request.url &&
345
+ old.advertisedRemoteHash === advertisedRemoteHash;
346
+ const observedRemoteHash = metadataUnchanged ? old?.observedRemoteHash ?? null : null;
347
+ const resource = {
348
+ filename: request.filename,
349
+ url: request.url,
350
+ localPath,
351
+ advertisedRemoteHash,
352
+ observedRemoteHash,
353
+ remoteHash: observedRemoteHash || advertisedRemoteHash ||
354
+ (metadataUnchanged ? old?.remoteHash ?? null : null),
355
+ remoteFileSize: metadataUnchanged ? old?.remoteFileSize ?? null : null,
356
+ localHash: old?.localHash || null,
357
+ };
358
+ entry.resources[key] = resource;
359
+ preparedEntries.push({ entry, resource });
360
+ }
361
+ const prepared = await mapWithConcurrency(preparedEntries, 4, ({ entry, resource }) => this.#prepareAssetResourceContent(record, entry, resource));
362
+ await this.#persist(record);
363
+ const preparedByKey = new Map(prepared.map((resource) => [
364
+ `${resource.assetId}\0${resourceKey(resource.filename)}`,
365
+ resource,
366
+ ]));
367
+ return requests.map((request) => {
368
+ const preparedResource = preparedByKey.get(`${String(request.assetId)}\0${resourceKey(request.filename)}`);
369
+ if (!preparedResource) {
370
+ throw new Error(`Asset ${request.assetId} resource ${request.filename} was not prepared.`);
371
+ }
372
+ return preparedResource;
373
+ });
374
+ }
248
375
  async pullAsset(info, assetId) {
249
376
  if (!info.projectId)
250
377
  throw new Error("The selected target has no project metadata.");
@@ -279,12 +406,14 @@ export class WorkspaceManager {
279
406
  }
280
407
  const assetsDirectory = join(directory, "assets");
281
408
  const tmpDirectory = join(directory, "tmp");
409
+ const objectsDirectory = join(directory, ".pcbridge", "objects");
282
410
  await mkdir(assetsDirectory, { recursive: true });
283
411
  await mkdir(join(tmpDirectory, "scripts"), { recursive: true });
284
412
  await mkdir(join(tmpDirectory, "captures"), { recursive: true });
285
413
  await mkdir(join(tmpDirectory, "conflicts"), { recursive: true });
286
414
  await mkdir(join(tmpDirectory, "trash", "remote"), { recursive: true });
287
415
  await mkdir(join(directory, ".pcbridge"), { recursive: true });
416
+ await mkdir(objectsDirectory, { recursive: true });
288
417
  const manifest = await readJson(join(directory, PROJECT_FILE));
289
418
  const syncState = await readJson(join(directory, SYNC_STATE_FILE));
290
419
  const legacyPrimaryPath = join(directory, LEGACY_INDEX_FILE);
@@ -294,7 +423,7 @@ export class WorkspaceManager {
294
423
  const legacy = legacyPrimary?.schemaVersion === 1
295
424
  ? legacyPrimary
296
425
  : legacyBackup?.schemaVersion === 1 ? legacyBackup : null;
297
- const index = manifest?.schemaVersion === 2 && manifest.assets
426
+ const index = (manifest?.schemaVersion === 2 || manifest?.schemaVersion === 3) && manifest.assets
298
427
  ? this.#indexFromManifest(manifest, syncState, info)
299
428
  : await this.#indexFromLegacy(directory, legacy, info);
300
429
  const record = {
@@ -305,6 +434,7 @@ export class WorkspaceManager {
305
434
  directory,
306
435
  assetsDirectory,
307
436
  tmpDirectory,
437
+ objectsDirectory,
308
438
  targetId: info.id,
309
439
  targetInfo: info,
310
440
  connected: true,
@@ -417,32 +547,105 @@ export class WorkspaceManager {
417
547
  }
418
548
  #indexFromManifest(manifest, syncState, info) {
419
549
  const entries = {};
420
- for (const [id, asset] of Object.entries(manifest.assets || {})) {
550
+ for (const [id, rawAsset] of Object.entries(manifest.assets || {})) {
551
+ if (manifest.schemaVersion === 3 &&
552
+ rawAsset &&
553
+ typeof rawAsset === "object" &&
554
+ "remoteFile" in rawAsset &&
555
+ "origin" in rawAsset) {
556
+ const asset = rawAsset;
557
+ const localPath = manifestLocalPath(asset.local?.path);
558
+ const projectionPath = manifestLocalPath(asset.projectionPath || undefined);
559
+ const present = Boolean(localPath && asset.local?.present);
560
+ const state = asset.state === "remote-only" ? "indexed" : asset.state;
561
+ const advertisedSize = asset.remoteFile?.size.advertised ?? null;
562
+ const advertisedHash = asset.remoteFile?.hash.advertised || null;
563
+ const observedSize = asset.remoteFile?.size.observed ?? null;
564
+ const observedHash = asset.remoteFile?.hash.observed || null;
565
+ const resources = Object.fromEntries((asset.local?.resources || []).flatMap((resource) => {
566
+ const resourcePath = manifestLocalPath(resource.path);
567
+ if (!resourcePath)
568
+ return [];
569
+ return [[resourceKey(resource.filename), {
570
+ filename: resource.filename,
571
+ url: resource.url,
572
+ localPath: resourcePath,
573
+ advertisedRemoteHash: resource.hash.advertised,
574
+ observedRemoteHash: resource.hash.observed,
575
+ remoteHash: resource.hash.effective,
576
+ remoteFileSize: resource.size,
577
+ localHash: resource.present ? resource.hash.current : null,
578
+ }]];
579
+ }));
580
+ entries[id] = {
581
+ id,
582
+ name: asset.name,
583
+ type: asset.type,
584
+ role: asset.origin.role,
585
+ sourceAssetId: asset.origin.sourceAssetId,
586
+ writable: asset.local?.writable ?? asset.origin.role !== "derived",
587
+ remotePath: asset.folder ? asset.folder.split("/").filter(Boolean) : [],
588
+ localFolderPath: asset.type === "folder"
589
+ ? projectionPath?.split(sep).filter(Boolean) || []
590
+ : localFolderParts(localPath),
591
+ localPath,
592
+ filename: asset.remoteFile?.filename || null,
593
+ advertisedRemoteFileSize: advertisedSize,
594
+ advertisedRemoteFileHash: advertisedHash,
595
+ observedRemoteFileSize: observedSize,
596
+ observedRemoteFileHash: observedHash,
597
+ remoteFileSize: asset.remoteFile?.size.effective ?? observedSize ?? advertisedSize,
598
+ remoteFileHash: asset.remoteFile?.hash.effective || observedHash || advertisedHash,
599
+ localHash: asset.local?.hash.current || null,
600
+ lastSyncedHash: asset.local?.hash.base || null,
601
+ legacyLastSyncedSha256: syncState?.entries?.[id]?.legacyLastSyncedSha256,
602
+ pendingRemoteHash: syncState?.entries?.[id]?.pendingRemoteHash,
603
+ localFileSize: syncState?.entries?.[id]?.localFileSize ?? asset.local?.size ?? undefined,
604
+ localMtimeMs: syncState?.entries?.[id]?.localMtimeMs,
605
+ resources,
606
+ downloaded: present,
607
+ status: state,
608
+ error: asset.error,
609
+ };
610
+ continue;
611
+ }
612
+ const asset = rawAsset;
421
613
  const localPath = manifestLocalPath(asset.file?.path);
422
614
  const present = Boolean(localPath && asset.file?.present);
423
615
  const state = asset.state === "remote-only" ? "indexed" : asset.state;
616
+ const remoteFileSize = asset.file?.size ?? null;
617
+ const remoteFileHash = asset.file?.hash.remote || null;
424
618
  entries[id] = {
425
619
  id,
426
620
  name: asset.name,
427
621
  type: asset.type,
622
+ role: "standalone",
623
+ sourceAssetId: null,
624
+ writable: true,
428
625
  remotePath: asset.folder ? asset.folder.split("/").filter(Boolean) : [],
626
+ localFolderPath: localFolderParts(localPath),
429
627
  localPath,
430
628
  filename: asset.file?.filename || null,
431
- remoteFileSize: asset.file?.size ?? null,
432
- remoteFileHash: asset.file?.hash.remote || null,
629
+ advertisedRemoteFileSize: remoteFileSize,
630
+ advertisedRemoteFileHash: remoteFileHash,
631
+ observedRemoteFileSize: null,
632
+ observedRemoteFileHash: null,
633
+ remoteFileSize,
634
+ remoteFileHash,
433
635
  localHash: asset.file?.hash.local || null,
434
636
  lastSyncedHash: asset.file?.hash.base || null,
435
637
  legacyLastSyncedSha256: syncState?.entries?.[id]?.legacyLastSyncedSha256,
436
638
  pendingRemoteHash: syncState?.entries?.[id]?.pendingRemoteHash,
437
639
  localFileSize: syncState?.entries?.[id]?.localFileSize,
438
640
  localMtimeMs: syncState?.entries?.[id]?.localMtimeMs,
641
+ resources: {},
439
642
  downloaded: present,
440
643
  status: state,
441
644
  error: asset.error,
442
645
  };
443
646
  }
444
647
  return {
445
- schemaVersion: 2,
648
+ schemaVersion: 3,
446
649
  projectId: info.projectId || manifest.project?.id || "",
447
650
  branchId: info.branchId || manifest.activeBranch?.id || null,
448
651
  updatedAt: manifest.workspace?.updatedAt || new Date().toISOString(),
@@ -466,9 +669,17 @@ export class WorkspaceManager {
466
669
  id,
467
670
  name: old.name,
468
671
  type: old.type,
672
+ role: "standalone",
673
+ sourceAssetId: null,
674
+ writable: true,
469
675
  remotePath: old.remotePath || [],
676
+ localFolderPath: localPath ? localFolderParts(localPath) : old.remotePath || [],
470
677
  localPath,
471
678
  filename: old.filename || null,
679
+ advertisedRemoteFileSize: old.remoteFileSize ?? null,
680
+ advertisedRemoteFileHash: old.remoteFileHash || null,
681
+ observedRemoteFileSize: null,
682
+ observedRemoteFileHash: null,
472
683
  remoteFileSize: old.remoteFileSize ?? null,
473
684
  remoteFileHash: old.remoteFileHash || null,
474
685
  localHash,
@@ -477,13 +688,14 @@ export class WorkspaceManager {
477
688
  pendingRemoteHash: old.pendingRemoteHash,
478
689
  localFileSize: old.localFileSize,
479
690
  localMtimeMs: old.localMtimeMs,
691
+ resources: old.resources || {},
480
692
  downloaded: Boolean(localContent),
481
693
  status: old.status,
482
694
  error: old.error,
483
695
  };
484
696
  }
485
697
  return {
486
- schemaVersion: 2,
698
+ schemaVersion: 3,
487
699
  projectId: info.projectId || legacy?.projectId || "",
488
700
  branchId: info.branchId || legacy?.branchId || null,
489
701
  updatedAt: legacy?.updatedAt || new Date().toISOString(),
@@ -499,26 +711,69 @@ export class WorkspaceManager {
499
711
  const publicState = entry.status === "indexed" && entry.localPath && !present
500
712
  ? "remote-only"
501
713
  : entry.status;
714
+ const resources = Object.values(entry.resources)
715
+ .sort((left, right) => left.localPath.localeCompare(right.localPath))
716
+ .map((resource) => {
717
+ const resourcePresent = existsSync(this.#assetPath(record, resource.localPath));
718
+ return {
719
+ filename: resource.filename,
720
+ url: resource.url,
721
+ path: `assets/${toPosixPath(resource.localPath)}`,
722
+ present: resourcePresent,
723
+ writable: false,
724
+ size: resourcePresent ? resource.remoteFileSize : null,
725
+ hash: {
726
+ algorithm: "md5",
727
+ advertised: resource.advertisedRemoteHash,
728
+ observed: resource.observedRemoteHash,
729
+ effective: resource.remoteHash,
730
+ current: resourcePresent ? resource.localHash : null,
731
+ },
732
+ };
733
+ });
502
734
  const asset = {
503
735
  id: entry.id,
504
736
  name: entry.name,
505
737
  type: entry.type,
506
738
  folder: toPosixPath(entry.remotePath.join("/")),
507
- file: entry.localPath && entry.filename
739
+ projectionPath: entry.type === "folder"
740
+ ? entry.localFolderPath.length ? `assets/${toPosixPath(entry.localFolderPath.join("/"))}` : "assets"
741
+ : entry.localPath ? `assets/${toPosixPath(entry.localPath)}` : null,
742
+ origin: {
743
+ role: entry.role,
744
+ sourceAssetId: entry.sourceAssetId,
745
+ },
746
+ remoteFile: entry.filename
508
747
  ? {
509
748
  filename: entry.filename,
749
+ size: {
750
+ advertised: entry.advertisedRemoteFileSize,
751
+ observed: entry.observedRemoteFileSize,
752
+ effective: entry.remoteFileSize,
753
+ },
754
+ hash: {
755
+ algorithm: "md5",
756
+ advertised: entry.advertisedRemoteFileHash,
757
+ observed: entry.observedRemoteFileHash,
758
+ effective: entry.remoteFileHash,
759
+ },
760
+ }
761
+ : null,
762
+ local: entry.localPath
763
+ ? {
510
764
  path: `assets/${toPosixPath(entry.localPath)}`,
511
- size: entry.remoteFileSize,
512
765
  present,
766
+ writable: entry.writable,
767
+ size: entry.localFileSize ?? null,
513
768
  hash: {
514
769
  algorithm: "md5",
515
- remote: entry.remoteFileHash,
516
- local: entry.localHash,
770
+ current: entry.localHash,
517
771
  base: entry.lastSyncedHash,
518
- matches: entry.remoteFileHash && present && entry.localHash
772
+ matchesRemote: entry.remoteFileHash && present && entry.localHash
519
773
  ? entry.remoteFileHash === entry.localHash
520
774
  : null,
521
775
  },
776
+ ...(resources.length ? { resources } : {}),
522
777
  }
523
778
  : null,
524
779
  state: publicState,
@@ -554,7 +809,7 @@ export class WorkspaceManager {
554
809
  : record.lastSyncedAt;
555
810
  const manifest = {
556
811
  ...(existing || {}),
557
- schemaVersion: 2,
812
+ schemaVersion: 3,
558
813
  project: { id: record.projectId, name: record.projectName },
559
814
  activeBranch: { id: record.branchId, name: record.branchName },
560
815
  scenes,
@@ -686,7 +941,10 @@ export class WorkspaceManager {
686
941
  record.pendingLocalFiles.delete(path);
687
942
  }
688
943
  const known = new Set(Object.values(record.index.entries)
689
- .map((entry) => entry.localPath ? toPosixPath(entry.localPath) : null)
944
+ .flatMap((entry) => [
945
+ entry.localPath ? toPosixPath(entry.localPath) : null,
946
+ ...Object.values(entry.resources).map((resource) => toPosixPath(resource.localPath)),
947
+ ])
690
948
  .filter(Boolean));
691
949
  for (const path of record.pendingLocalFiles.keys())
692
950
  known.add(path);
@@ -719,7 +977,19 @@ export class WorkspaceManager {
719
977
  const parts = relativePath.split(/[\\/]/g);
720
978
  const filename = parts.pop() || "asset.bin";
721
979
  const folder = parts.join("/");
722
- const renamed = Object.values(record.index.entries).find((entry) => entry.type !== "folder" && entry.localPath && !existsSync(this.#assetPath(record, entry.localPath)) &&
980
+ const derived = Object.values(record.index.entries).find((entry) => entry.role === "derived" &&
981
+ (entry.localHash === contentHash || entry.lastSyncedHash === contentHash));
982
+ if (derived) {
983
+ const conflictPath = join(record.tmpDirectory, "conflicts", `${derived.id}-${safeWorkspaceName(filename, `asset-${derived.id}`)}.derived-local`);
984
+ await mkdir(dirname(conflictPath), { recursive: true });
985
+ await rename(path, conflictPath);
986
+ record.lastWarning =
987
+ `Ignored a moved or copied projection of derived Asset ${derived.id}; ` +
988
+ `the local copy was saved to ${relative(record.directory, conflictPath)}.`;
989
+ continue;
990
+ }
991
+ const renamed = Object.values(record.index.entries).find((entry) => entry.writable && entry.type !== "folder" && entry.localPath &&
992
+ !existsSync(this.#assetPath(record, entry.localPath)) &&
723
993
  entry.localHash === contentHash);
724
994
  if (renamed) {
725
995
  const renameResponse = await this.#requestTarget(record.targetId, "bridge:renameAsset", {
@@ -817,77 +1087,141 @@ export class WorkspaceManager {
817
1087
  return true;
818
1088
  }
819
1089
  async #applySnapshot(record, assets, force) {
1090
+ const previous = record.index.entries;
1091
+ const incomingIds = new Set(assets.map((asset) => String(asset.id)));
820
1092
  const folderAssets = assets
821
1093
  .filter((asset) => asset.type === "folder")
822
- .sort((left, right) => (left.path?.length || 0) - (right.path?.length || 0));
823
- const folderPaths = new Map();
1094
+ .sort((left, right) => {
1095
+ const depthDifference = (left.path?.length || 0) - (right.path?.length || 0);
1096
+ if (depthDifference)
1097
+ return depthDifference;
1098
+ return String(left.id).localeCompare(String(right.id), undefined, { numeric: true });
1099
+ });
1100
+ const localFolderPaths = new Map();
1101
+ const remoteFolderPaths = new Map();
824
1102
  const usedNames = new Map();
825
- const allocateName = (parent, rawName, id) => {
826
- const parentKey = parent.join("/").toLocaleLowerCase();
1103
+ for (const entry of Object.values(previous)) {
1104
+ if (!incomingIds.has(entry.id))
1105
+ continue;
1106
+ for (const resource of Object.values(entry.resources)) {
1107
+ const parentKey = pathNameKey(localFolderParts(resource.localPath).join("/"));
1108
+ const used = usedNames.get(parentKey) || new Set();
1109
+ used.add(pathNameKey(basename(resource.localPath)));
1110
+ usedNames.set(parentKey, used);
1111
+ }
1112
+ }
1113
+ const allocateName = (parent, rawName, type, id) => {
1114
+ const parentKey = pathNameKey(parent.join("/"));
827
1115
  const used = usedNames.get(parentKey) || new Set();
828
1116
  const safe = safeAssetName(rawName, `asset-${id}`);
829
- const key = safe.toLocaleLowerCase();
830
- const selected = used.has(key) ? collisionName(safe, id) : safe;
831
- used.add(selected.toLocaleLowerCase());
1117
+ const key = pathNameKey(safe);
1118
+ let selected = used.has(key) ? collisionName(safe, type, id) : safe;
1119
+ let suffix = 2;
1120
+ while (used.has(pathNameKey(selected))) {
1121
+ selected = collisionName(safe, type, `${id}_${suffix}`);
1122
+ suffix += 1;
1123
+ }
1124
+ used.add(pathNameKey(selected));
832
1125
  usedNames.set(parentKey, used);
833
1126
  return selected;
834
1127
  };
835
1128
  for (const folder of folderAssets) {
836
1129
  const parentIds = (folder.path || []).map(String);
837
- const parent = parentIds.length ? folderPaths.get(parentIds[parentIds.length - 1]) || [] : [];
838
- const name = allocateName(parent, folder.name, String(folder.id));
839
- const path = [...parent, name];
840
- folderPaths.set(String(folder.id), path);
841
- await mkdir(this.#assetPath(record, join(...path)), { recursive: true });
1130
+ const localParent = parentIds.length
1131
+ ? localFolderPaths.get(parentIds[parentIds.length - 1]) || []
1132
+ : [];
1133
+ const remoteParent = parentIds.length
1134
+ ? remoteFolderPaths.get(parentIds[parentIds.length - 1]) || []
1135
+ : [];
1136
+ const localName = allocateName(localParent, folder.name, "folder", String(folder.id));
1137
+ const localPath = [...localParent, localName];
1138
+ localFolderPaths.set(String(folder.id), localPath);
1139
+ remoteFolderPaths.set(String(folder.id), [...remoteParent, folder.name]);
1140
+ await mkdir(this.#assetPath(record, join(...localPath)), { recursive: true });
842
1141
  }
843
- const previous = record.index.entries;
844
1142
  const next = {};
845
- const staleDerivedPaths = [];
846
- const orderedAssets = [...assets].sort((left, right) => Number(isDerivedAsset(left)) - Number(isDerivedAsset(right)));
1143
+ const roleOrder = { source: 0, standalone: 1, derived: 2 };
1144
+ const orderedAssets = [...assets].sort((left, right) => {
1145
+ const roleDifference = roleOrder[assetRole(left)] - roleOrder[assetRole(right)];
1146
+ if (roleDifference)
1147
+ return roleDifference;
1148
+ return String(left.id).localeCompare(String(right.id), undefined, { numeric: true });
1149
+ });
847
1150
  for (const asset of orderedAssets) {
848
1151
  const id = String(asset.id);
849
1152
  const parentIds = (asset.path || []).map(String);
850
- const parent = parentIds.length ? folderPaths.get(parentIds[parentIds.length - 1]) || [] : [];
1153
+ const localParent = parentIds.length
1154
+ ? localFolderPaths.get(parentIds[parentIds.length - 1]) || []
1155
+ : [];
1156
+ const remoteParent = parentIds.length
1157
+ ? remoteFolderPaths.get(parentIds[parentIds.length - 1]) || []
1158
+ : [];
851
1159
  if (asset.type === "folder") {
852
1160
  next[id] = {
853
1161
  id,
854
1162
  name: asset.name,
855
1163
  type: asset.type,
856
- remotePath: folderPaths.get(id) || parent,
1164
+ role: "standalone",
1165
+ sourceAssetId: null,
1166
+ writable: false,
1167
+ remotePath: remoteFolderPaths.get(id) || [...remoteParent, asset.name],
1168
+ localFolderPath: localFolderPaths.get(id) || localParent,
857
1169
  localPath: null,
858
1170
  filename: null,
1171
+ advertisedRemoteFileSize: null,
1172
+ advertisedRemoteFileHash: null,
1173
+ observedRemoteFileSize: null,
1174
+ observedRemoteFileHash: null,
859
1175
  remoteFileSize: null,
860
1176
  remoteFileHash: null,
861
1177
  localHash: null,
862
1178
  lastSyncedHash: null,
863
1179
  localFileSize: undefined,
864
1180
  localMtimeMs: undefined,
1181
+ resources: {},
865
1182
  downloaded: false,
866
1183
  status: "indexed",
867
1184
  };
868
1185
  continue;
869
1186
  }
870
- const derived = isDerivedAsset(asset);
1187
+ const role = assetRole(asset);
1188
+ const derived = role === "derived";
1189
+ const sourceAssetId = derived ? String(asset.source_asset_id) : null;
871
1190
  const remoteFilename = asset.file?.filename || (asset.type === "script" ? asset.name : null);
872
- const localFilename = asset.source && asset.name ? asset.name : remoteFilename;
873
- const localName = !derived && localFilename ? allocateName(parent, localFilename, id) : null;
874
- const localPath = localName ? join(...parent, localName) : null;
1191
+ const localFilename = remoteFilename;
1192
+ const localName = localFilename ? allocateName(localParent, localFilename, asset.type, id) : null;
1193
+ const localPath = localName ? join(...localParent, localName) : null;
875
1194
  const old = previous[id];
1195
+ const advertisedRemoteFileSize = asset.file?.size ?? null;
1196
+ const advertisedRemoteFileHash = asset.file?.hash || null;
1197
+ const metadataUnchanged = old?.advertisedRemoteFileHash === advertisedRemoteFileHash &&
1198
+ old?.advertisedRemoteFileSize === advertisedRemoteFileSize;
1199
+ const observedRemoteFileSize = metadataUnchanged ? old?.observedRemoteFileSize ?? null : null;
1200
+ const observedRemoteFileHash = metadataUnchanged ? old?.observedRemoteFileHash ?? null : null;
876
1201
  const entry = {
877
1202
  id,
878
1203
  name: asset.name,
879
1204
  type: asset.type,
880
- remotePath: parent,
1205
+ role,
1206
+ sourceAssetId,
1207
+ writable: !derived,
1208
+ remotePath: remoteParent,
1209
+ localFolderPath: localParent,
881
1210
  localPath,
882
1211
  filename: remoteFilename,
883
- remoteFileSize: asset.file?.size ?? null,
884
- remoteFileHash: asset.file?.hash || null,
1212
+ advertisedRemoteFileSize,
1213
+ advertisedRemoteFileHash,
1214
+ observedRemoteFileSize,
1215
+ observedRemoteFileHash,
1216
+ remoteFileSize: observedRemoteFileSize ?? advertisedRemoteFileSize,
1217
+ remoteFileHash: observedRemoteFileHash || advertisedRemoteFileHash,
885
1218
  localHash: old?.localHash || null,
886
1219
  lastSyncedHash: old?.lastSyncedHash || null,
887
1220
  legacyLastSyncedSha256: old?.legacyLastSyncedSha256,
888
1221
  pendingRemoteHash: old?.pendingRemoteHash,
889
1222
  localFileSize: old?.localFileSize,
890
1223
  localMtimeMs: old?.localMtimeMs,
1224
+ resources: old?.resources || {},
891
1225
  downloaded: old?.downloaded || false,
892
1226
  status: old?.status || "indexed",
893
1227
  error: old?.error,
@@ -904,53 +1238,48 @@ export class WorkspaceManager {
904
1238
  if (!existsSync(newPath))
905
1239
  await rename(oldPath, newPath);
906
1240
  }
907
- if (derived) {
908
- // PlayCanvas generated Model/Container/Texture assets are outputs of a
909
- // source import (for example GLB). They are remote catalog entries,
910
- // not local source files and must never be uploaded back.
911
- entry.localPath = null;
912
- entry.downloaded = false;
913
- entry.localHash = null;
914
- entry.localFileSize = undefined;
915
- entry.localMtimeMs = undefined;
916
- entry.status = "indexed";
917
- delete entry.error;
918
- if (old?.localPath)
919
- staleDerivedPaths.push({ id, path: old.localPath });
1241
+ if (derived && localPath) {
1242
+ await this.#reconcileDerived(record, entry, old);
1243
+ if (existsSync(this.#assetPath(record, localPath))) {
1244
+ await chmod(this.#assetPath(record, localPath), 0o444).catch(() => undefined);
1245
+ }
920
1246
  }
921
1247
  else if (asset.type === "script" && localPath) {
1248
+ if (existsSync(this.#assetPath(record, localPath))) {
1249
+ await chmod(this.#assetPath(record, localPath), 0o644).catch(() => undefined);
1250
+ }
922
1251
  await this.#reconcileScript(record, entry, old, force);
923
1252
  }
924
1253
  else if (localPath) {
1254
+ if (existsSync(this.#assetPath(record, localPath))) {
1255
+ await chmod(this.#assetPath(record, localPath), 0o644).catch(() => undefined);
1256
+ }
925
1257
  await this.#reconcileBinary(record, entry, old);
926
1258
  }
927
1259
  if (asset.file && record.syncProgress)
928
1260
  record.syncProgress.completed += 1;
929
1261
  }
930
1262
  const deletionBatch = new Date().toISOString().replaceAll(":", "-");
931
- const activeLocalPaths = new Set(Object.values(next).map((entry) => entry.localPath).filter(Boolean));
932
- for (const stale of staleDerivedPaths) {
933
- if (activeLocalPaths.has(stale.path))
934
- continue;
935
- const source = this.#assetPath(record, stale.path);
936
- if (!existsSync(source))
937
- continue;
938
- const destination = join(record.tmpDirectory, "trash", "derived", deletionBatch, `${stale.id}-${safeWorkspaceName(basename(stale.path), `asset-${stale.id}`)}`);
939
- await mkdir(dirname(destination), { recursive: true });
940
- await rename(source, destination);
941
- }
942
1263
  for (const [id, old] of Object.entries(previous)) {
943
- if (next[id] || !old.localPath || !existsSync(this.#assetPath(record, old.localPath)))
1264
+ if (next[id])
944
1265
  continue;
945
- const source = this.#assetPath(record, old.localPath);
946
- const destination = join(record.tmpDirectory, "trash", "remote", deletionBatch, `${id}-${safeWorkspaceName(basename(old.localPath), `asset-${id}`)}`);
947
- await mkdir(dirname(destination), { recursive: true });
948
- await rename(source, destination);
1266
+ const deletedPaths = [
1267
+ old.localPath,
1268
+ ...Object.values(old.resources).map((resource) => resource.localPath),
1269
+ ].filter((path) => Boolean(path));
1270
+ for (const deletedPath of deletedPaths) {
1271
+ if (!existsSync(this.#assetPath(record, deletedPath)))
1272
+ continue;
1273
+ const source = this.#assetPath(record, deletedPath);
1274
+ const destination = join(record.tmpDirectory, "trash", "remote", deletionBatch, `${id}-${safeWorkspaceName(basename(deletedPath), `asset-${id}`)}`);
1275
+ await mkdir(dirname(destination), { recursive: true });
1276
+ await rename(source, destination);
1277
+ }
949
1278
  }
950
1279
  const obsoleteFolders = Object.entries(previous)
951
1280
  .filter(([id, old]) => old.type === "folder" &&
952
- (!next[id] || next[id].remotePath.join("/") !== old.remotePath.join("/")))
953
- .map(([, old]) => old.remotePath)
1281
+ (!next[id] || next[id].localFolderPath.join("/") !== old.localFolderPath.join("/")))
1282
+ .map(([, old]) => old.localFolderPath)
954
1283
  .sort((left, right) => right.length - left.length);
955
1284
  for (const folder of obsoleteFolders) {
956
1285
  if (!folder.length)
@@ -958,7 +1287,7 @@ export class WorkspaceManager {
958
1287
  await rmdir(this.#assetPath(record, join(...folder))).catch(() => undefined);
959
1288
  }
960
1289
  record.index = {
961
- schemaVersion: 2,
1290
+ schemaVersion: 3,
962
1291
  projectId: record.projectId,
963
1292
  branchId: record.branchId,
964
1293
  updatedAt: new Date().toISOString(),
@@ -998,23 +1327,232 @@ export class WorkspaceManager {
998
1327
  entry.localMtimeMs = info.mtimeMs;
999
1328
  entry.downloaded = true;
1000
1329
  }
1001
- async #readRemoteAsset(record, entry) {
1002
- const response = await this.#requestTarget(record.targetId, "bridge:readAssetFile", { assetId: entry.id }, 120000);
1003
- if (!response.ok)
1004
- throw new Error(response.error.message);
1005
- const data = asObject(response.data);
1006
- const base64 = typeof data.base64 === "string" ? data.base64 : "";
1007
- if (!base64)
1008
- throw new Error(`Asset ${entry.id} returned no file data.`);
1009
- const content = Buffer.from(base64, "base64");
1010
- const hash = hashContent(content);
1011
- if (entry.remoteFileHash && entry.remoteFileHash !== hash) {
1012
- throw new Error(`Asset ${entry.id} changed while it was being downloaded: ` +
1013
- `expected ${entry.remoteFileHash}, received ${hash}.`);
1014
- }
1015
- entry.remoteFileHash = hash;
1330
+ #objectPath(record, entry, hash) {
1331
+ const path = this.#withinRoot(join(record.objectsDirectory, safeAssetName(entry.id, "asset"), safeAssetName(hash, "unknown"), safeAssetName(entry.filename || entry.name, "file.bin")));
1332
+ if (path !== record.objectsDirectory && !path.startsWith(`${record.objectsDirectory}${sep}`)) {
1333
+ throw new Error(`Object path escapes workspace cache: ${path}`);
1334
+ }
1335
+ return path;
1336
+ }
1337
+ async #cachedObject(record, entry, hash) {
1338
+ if (!hash)
1339
+ return null;
1340
+ const path = this.#objectPath(record, entry, hash);
1341
+ if (!existsSync(path))
1342
+ return null;
1343
+ const content = await readFile(path);
1344
+ if (hashContent(content) !== hash)
1345
+ return null;
1346
+ return { path, content, hash };
1347
+ }
1348
+ async #storeObject(record, entry, content, hash) {
1349
+ const existing = await this.#cachedObject(record, entry, hash);
1350
+ if (existing)
1351
+ return existing.path;
1352
+ const path = this.#objectPath(record, entry, hash);
1353
+ await atomicWrite(path, content);
1354
+ return path;
1355
+ }
1356
+ #resourceObjectPath(record, entry, resource, hash) {
1357
+ const path = this.#withinRoot(join(record.objectsDirectory, safeAssetName(entry.id, "asset"), safeAssetName(hash, "unknown"), safeAssetName(resource.filename, "resource.bin")));
1358
+ if (path !== record.objectsDirectory && !path.startsWith(`${record.objectsDirectory}${sep}`)) {
1359
+ throw new Error(`Resource object path escapes workspace cache: ${path}`);
1360
+ }
1361
+ return path;
1362
+ }
1363
+ async #cachedResourceObject(record, entry, resource, hash) {
1364
+ if (!hash)
1365
+ return null;
1366
+ const path = this.#resourceObjectPath(record, entry, resource, hash);
1367
+ if (!existsSync(path))
1368
+ return null;
1369
+ const content = await readFile(path);
1370
+ if (hashContent(content) !== hash)
1371
+ return null;
1016
1372
  return { content, hash };
1017
1373
  }
1374
+ async #storeResourceObject(record, entry, resource, content, hash) {
1375
+ const cached = await this.#cachedResourceObject(record, entry, resource, hash);
1376
+ if (cached)
1377
+ return;
1378
+ await atomicWrite(this.#resourceObjectPath(record, entry, resource, hash), content);
1379
+ }
1380
+ async #materializeResource(record, resource, content, hash) {
1381
+ const path = this.#assetPath(record, resource.localPath);
1382
+ if (existsSync(path))
1383
+ await chmod(path, 0o644).catch(() => undefined);
1384
+ await atomicWrite(path, content);
1385
+ await chmod(path, 0o444).catch(() => undefined);
1386
+ resource.localHash = hash;
1387
+ resource.remoteFileSize = content.byteLength;
1388
+ return path;
1389
+ }
1390
+ #legacyCachedFilePath(record, assetId, filename) {
1391
+ return this.#withinRoot(join(record.tmpDirectory, "cache", "assets", safeAssetName(assetId, "asset"), safeAssetName(filename, "resource.bin")));
1392
+ }
1393
+ #legacyResourcePath(record, entry, resource) {
1394
+ return this.#legacyCachedFilePath(record, entry.id, resource.filename);
1395
+ }
1396
+ async #removeLegacyResource(path) {
1397
+ if (!existsSync(path))
1398
+ return;
1399
+ await unlink(path).catch(() => undefined);
1400
+ await rmdir(dirname(path)).catch(() => undefined);
1401
+ await rmdir(dirname(dirname(path))).catch(() => undefined);
1402
+ await rmdir(dirname(dirname(dirname(path)))).catch(() => undefined);
1403
+ }
1404
+ async #readRemoteResource(record, entry, resource) {
1405
+ const readOnce = async () => {
1406
+ const response = await this.#requestTarget(record.targetId, "bridge:readAssetResource", { assetId: entry.id, url: resource.url }, 120000);
1407
+ if (!response.ok)
1408
+ throw new Error(response.error.message);
1409
+ const data = asObject(response.data);
1410
+ const base64 = typeof data.base64 === "string" ? data.base64 : "";
1411
+ if (!base64) {
1412
+ throw new Error(`Asset ${entry.id} resource ${resource.filename} returned no data.`);
1413
+ }
1414
+ const content = Buffer.from(base64, "base64");
1415
+ return { content, hash: hashContent(content) };
1416
+ };
1417
+ const expectedHash = resource.remoteHash;
1418
+ let remote = await readOnce();
1419
+ if (expectedHash && expectedHash !== remote.hash) {
1420
+ const confirmed = await readOnce();
1421
+ if (confirmed.hash !== remote.hash) {
1422
+ throw new Error(`Asset ${entry.id} resource ${resource.filename} changed while it was being downloaded: ` +
1423
+ `expected ${expectedHash}, received ${remote.hash}, then ${confirmed.hash}.`);
1424
+ }
1425
+ record.lastWarning =
1426
+ `Asset ${entry.id} resource ${resource.filename} has stale PlayCanvas metadata ` +
1427
+ `(${expectedHash}); using stable downloaded content ${confirmed.hash}.`;
1428
+ remote = confirmed;
1429
+ }
1430
+ resource.observedRemoteHash = resource.advertisedRemoteHash !== remote.hash ? remote.hash : null;
1431
+ resource.remoteHash = remote.hash;
1432
+ resource.remoteFileSize = remote.content.byteLength;
1433
+ return remote;
1434
+ }
1435
+ async #prepareAssetResourceContent(record, entry, resource) {
1436
+ const path = this.#assetPath(record, resource.localPath);
1437
+ const localContent = existsSync(path) ? await readFile(path) : null;
1438
+ const localHash = localContent ? hashContent(localContent) : null;
1439
+ const localModified = Boolean(localHash && resource.localHash && localHash !== resource.localHash);
1440
+ if (localContent && (!resource.remoteHash || localHash === resource.remoteHash)) {
1441
+ resource.localHash = localHash;
1442
+ resource.remoteFileSize = localContent.byteLength;
1443
+ await chmod(path, 0o444).catch(() => undefined);
1444
+ if (resource.remoteHash) {
1445
+ await this.#storeResourceObject(record, entry, resource, localContent, resource.remoteHash);
1446
+ }
1447
+ return {
1448
+ assetId: entry.id,
1449
+ filename: resource.filename,
1450
+ url: resource.url,
1451
+ path,
1452
+ hash: localHash,
1453
+ };
1454
+ }
1455
+ const legacyPath = this.#legacyResourcePath(record, entry, resource);
1456
+ if (!localContent && existsSync(legacyPath)) {
1457
+ const legacyContent = await readFile(legacyPath);
1458
+ const legacyHash = hashContent(legacyContent);
1459
+ if (!resource.remoteHash || legacyHash === resource.remoteHash) {
1460
+ if (!resource.remoteHash) {
1461
+ resource.observedRemoteHash = legacyHash;
1462
+ resource.remoteHash = legacyHash;
1463
+ }
1464
+ await this.#storeResourceObject(record, entry, resource, legacyContent, legacyHash);
1465
+ const materialized = await this.#materializeResource(record, resource, legacyContent, legacyHash);
1466
+ await this.#removeLegacyResource(legacyPath);
1467
+ return {
1468
+ assetId: entry.id,
1469
+ filename: resource.filename,
1470
+ url: resource.url,
1471
+ path: materialized,
1472
+ hash: legacyHash,
1473
+ };
1474
+ }
1475
+ }
1476
+ if (localModified && localContent) {
1477
+ const conflictPath = join(record.tmpDirectory, "conflicts", `${entry.id}-${safeWorkspaceName(resource.filename, `resource-${entry.id}`)}.resource-local`);
1478
+ await mkdir(dirname(conflictPath), { recursive: true });
1479
+ await copyFile(path, conflictPath);
1480
+ record.lastWarning =
1481
+ `Ignored a local edit to managed build resource ${entry.id}/${resource.filename}; ` +
1482
+ `the local copy was saved to ${relative(record.directory, conflictPath)}.`;
1483
+ }
1484
+ const cached = await this.#cachedResourceObject(record, entry, resource, resource.remoteHash);
1485
+ if (cached) {
1486
+ const materialized = await this.#materializeResource(record, resource, cached.content, cached.hash);
1487
+ await this.#removeLegacyResource(legacyPath);
1488
+ return {
1489
+ assetId: entry.id,
1490
+ filename: resource.filename,
1491
+ url: resource.url,
1492
+ path: materialized,
1493
+ hash: cached.hash,
1494
+ };
1495
+ }
1496
+ const remote = await this.#readRemoteResource(record, entry, resource);
1497
+ await this.#storeResourceObject(record, entry, resource, remote.content, remote.hash);
1498
+ const materialized = await this.#materializeResource(record, resource, remote.content, remote.hash);
1499
+ await this.#removeLegacyResource(legacyPath);
1500
+ return {
1501
+ assetId: entry.id,
1502
+ filename: resource.filename,
1503
+ url: resource.url,
1504
+ path: materialized,
1505
+ hash: remote.hash,
1506
+ };
1507
+ }
1508
+ async #materializeObject(record, entry, content, hash) {
1509
+ if (!entry.localPath)
1510
+ throw new Error(`Asset ${entry.id} has no local projection path.`);
1511
+ const path = this.#assetPath(record, entry.localPath);
1512
+ if (existsSync(path))
1513
+ await chmod(path, 0o644).catch(() => undefined);
1514
+ await atomicWrite(path, content);
1515
+ await chmod(path, entry.writable ? 0o644 : 0o444).catch(() => undefined);
1516
+ await this.#recordLocalFile(record, entry, hash);
1517
+ return path;
1518
+ }
1519
+ async #readRemoteAsset(record, entry) {
1520
+ const readOnce = async () => {
1521
+ const response = await this.#requestTarget(record.targetId, "bridge:readAssetFile", { assetId: entry.id }, 120000);
1522
+ if (!response.ok)
1523
+ throw new Error(response.error.message);
1524
+ const data = asObject(response.data);
1525
+ const base64 = typeof data.base64 === "string" ? data.base64 : "";
1526
+ if (!base64)
1527
+ throw new Error(`Asset ${entry.id} returned no file data.`);
1528
+ const content = Buffer.from(base64, "base64");
1529
+ return { content, hash: hashContent(content) };
1530
+ };
1531
+ const expectedHash = entry.remoteFileHash;
1532
+ let remote = await readOnce();
1533
+ if (expectedHash && expectedHash !== remote.hash) {
1534
+ // Processed assets can expose stale metadata after their generated file has been replaced.
1535
+ // A second identical download distinguishes that case from an actively changing resource.
1536
+ const confirmed = await readOnce();
1537
+ if (confirmed.hash !== remote.hash) {
1538
+ throw new Error(`Asset ${entry.id} changed while it was being downloaded: ` +
1539
+ `expected ${expectedHash}, received ${remote.hash}, then ${confirmed.hash}.`);
1540
+ }
1541
+ record.lastWarning =
1542
+ `Asset ${entry.id} has stale PlayCanvas file metadata (${expectedHash}); ` +
1543
+ `using stable downloaded content ${confirmed.hash}.`;
1544
+ remote = confirmed;
1545
+ }
1546
+ entry.observedRemoteFileHash = entry.advertisedRemoteFileHash !== remote.hash
1547
+ ? remote.hash
1548
+ : null;
1549
+ entry.observedRemoteFileSize = entry.advertisedRemoteFileSize !== remote.content.byteLength
1550
+ ? remote.content.byteLength
1551
+ : null;
1552
+ entry.remoteFileSize = remote.content.byteLength;
1553
+ entry.remoteFileHash = remote.hash;
1554
+ return remote;
1555
+ }
1018
1556
  async #downloadAsset(record, entry) {
1019
1557
  if (!entry.localPath)
1020
1558
  throw new Error(`Asset ${entry.id} has no downloadable file.`);
@@ -1022,10 +1560,19 @@ export class WorkspaceManager {
1022
1560
  record.syncProgress.assetId = entry.id;
1023
1561
  record.syncProgress.action = "downloading";
1024
1562
  }
1025
- const remote = await this.#readRemoteAsset(record, entry);
1026
- const path = this.#assetPath(record, entry.localPath);
1027
- await atomicWrite(path, remote.content);
1028
- await this.#recordLocalFile(record, entry, remote.hash);
1563
+ const legacyPath = this.#legacyCachedFilePath(record, entry.id, entry.filename || entry.name);
1564
+ let legacy = null;
1565
+ if (existsSync(legacyPath)) {
1566
+ const content = await readFile(legacyPath);
1567
+ const hash = hashContent(content);
1568
+ if (entry.remoteFileHash && hash === entry.remoteFileHash)
1569
+ legacy = { content, hash };
1570
+ }
1571
+ const cached = legacy || await this.#cachedObject(record, entry, entry.remoteFileHash);
1572
+ const remote = cached || await this.#readRemoteAsset(record, entry);
1573
+ await this.#storeObject(record, entry, remote.content, remote.hash);
1574
+ const path = await this.#materializeObject(record, entry, remote.content, remote.hash);
1575
+ await this.#removeLegacyResource(legacyPath);
1029
1576
  entry.lastSyncedHash = remote.hash;
1030
1577
  entry.status = "synced";
1031
1578
  delete entry.legacyLastSyncedSha256;
@@ -1033,21 +1580,9 @@ export class WorkspaceManager {
1033
1580
  delete entry.error;
1034
1581
  return { path, size: remote.content.byteLength, hash: remote.hash };
1035
1582
  }
1036
- async #prepareCachedAsset(record, entry) {
1037
- if (!entry.filename)
1038
- throw new Error(`Asset ${entry.id} has no cacheable filename.`);
1039
- const path = join(record.tmpDirectory, "cache", "assets", safeAssetName(entry.id, "asset"), safeAssetName(entry.filename, "file.bin"));
1040
- if (existsSync(path)) {
1041
- const content = await readFile(path);
1042
- const hash = hashContent(content);
1043
- if (!entry.remoteFileHash || hash === entry.remoteFileHash)
1044
- return { path, hash };
1045
- }
1046
- const remote = await this.#readRemoteAsset(record, entry);
1047
- await atomicWrite(path, remote.content);
1048
- return { path, hash: remote.hash };
1049
- }
1050
1583
  async #uploadBinary(record, entry, content, localHash) {
1584
+ if (!entry.writable)
1585
+ throw new Error(`Derived Asset ${entry.id} is read-only.`);
1051
1586
  if (record.syncProgress) {
1052
1587
  record.syncProgress.assetId = entry.id;
1053
1588
  record.syncProgress.action = "uploading";
@@ -1086,6 +1621,50 @@ export class WorkspaceManager {
1086
1621
  `Local and remote asset files changed since the last sync. See ` +
1087
1622
  `${relative(record.directory, conflictBase)}.*`;
1088
1623
  }
1624
+ async #reconcileDerived(record, entry, old) {
1625
+ const local = await this.#localFileSnapshot(record, entry, old);
1626
+ if (!local) {
1627
+ if (old?.downloaded && entry.remoteFileHash) {
1628
+ const cached = await this.#cachedObject(record, entry, entry.remoteFileHash);
1629
+ if (cached) {
1630
+ await this.#materializeObject(record, entry, cached.content, cached.hash);
1631
+ entry.lastSyncedHash = cached.hash;
1632
+ entry.status = "synced";
1633
+ delete entry.error;
1634
+ return;
1635
+ }
1636
+ await this.#downloadAsset(record, entry);
1637
+ return;
1638
+ }
1639
+ entry.localHash = null;
1640
+ entry.localFileSize = undefined;
1641
+ entry.localMtimeMs = undefined;
1642
+ entry.downloaded = false;
1643
+ entry.status = "indexed";
1644
+ delete entry.error;
1645
+ return;
1646
+ }
1647
+ entry.localHash = local.hash;
1648
+ entry.localFileSize = local.size;
1649
+ entry.localMtimeMs = local.mtimeMs;
1650
+ entry.downloaded = true;
1651
+ if (entry.remoteFileHash && local.hash === entry.remoteFileHash) {
1652
+ entry.lastSyncedHash = local.hash;
1653
+ entry.status = "synced";
1654
+ delete entry.error;
1655
+ return;
1656
+ }
1657
+ const locallyModified = !old?.lastSyncedHash || local.hash !== old.lastSyncedHash;
1658
+ if (locallyModified && entry.localPath) {
1659
+ const conflictPath = join(record.tmpDirectory, "conflicts", `${entry.id}-${safeWorkspaceName(entry.filename || entry.name, `asset-${entry.id}`)}.derived-local`);
1660
+ await mkdir(dirname(conflictPath), { recursive: true });
1661
+ await copyFile(this.#assetPath(record, entry.localPath), conflictPath);
1662
+ record.lastWarning =
1663
+ `Ignored a local edit to derived Asset ${entry.id}; restored the generated PlayCanvas file. ` +
1664
+ `The local copy was saved to ${relative(record.directory, conflictPath)}.`;
1665
+ }
1666
+ await this.#downloadAsset(record, entry);
1667
+ }
1089
1668
  async #reconcileBinary(record, entry, old) {
1090
1669
  const local = await this.#localFileSnapshot(record, entry, old);
1091
1670
  const baseline = old?.lastSyncedHash || null;