playcanvas-agent-bridge-cli 0.3.0 → 0.4.2

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.
package/dist/snippets.js CHANGED
@@ -485,7 +485,7 @@ if (existing) {
485
485
  ...attributes
486
486
  });
487
487
  } else {
488
- entity.addScript(scriptName, {
488
+ await entity.addScript(scriptName, {
489
489
  attributes,
490
490
  history: true
491
491
  });
@@ -495,11 +495,15 @@ if (!order.includes(scriptName)) {
495
495
  order.push(scriptName);
496
496
  entity.set("components.script.order", order);
497
497
  }
498
+ const installed = entity.get("components.script.scripts." + scriptName);
499
+ if (!installed) {
500
+ throw new Error("Script was not attached: " + scriptName);
501
+ }
498
502
  return {
499
503
  entity: readEntity(entity),
500
504
  scriptName,
501
505
  scriptAsset: scriptAsset ? readAsset(scriptAsset) : null,
502
- script: entity.get("components.script.scripts." + scriptName)
506
+ script: installed
503
507
  };
504
508
  `;
505
509
  }
@@ -714,6 +718,280 @@ return {
714
718
  };
715
719
  `;
716
720
  }
721
+ const templateApplyHelpers = `
722
+ function templateError(code, message, details) {
723
+ const error = new Error(message);
724
+ error.code = code;
725
+ error.details = details || {};
726
+ return error;
727
+ }
728
+
729
+ function templateObserver(entity) {
730
+ return entity.observer || entity;
731
+ }
732
+
733
+ function templateOverrides(entity) {
734
+ const value = editor.call("templates:computeFilteredOverrides", templateObserver(entity));
735
+ if (Array.isArray(value)) return { count: value.length, value };
736
+ if (value && typeof value === "object") {
737
+ const parts = ["conflicts", "addedEntities", "deletedEntities"];
738
+ const componentCount = parts.reduce(
739
+ (total, key) => total + (Array.isArray(value[key]) ? value[key].length : 0),
740
+ 0
741
+ );
742
+ if (Number.isFinite(Number(value.totalOverrides))) {
743
+ if (Number(value.totalOverrides) !== componentCount) {
744
+ throw templateError(
745
+ "TEMPLATE_OVERRIDE_COUNT_MISMATCH",
746
+ "Template override total does not match its component arrays for entity " +
747
+ entity.get("resource_id") + ".",
748
+ { totalOverrides: Number(value.totalOverrides), componentCount }
749
+ );
750
+ }
751
+ return {
752
+ count: Number(value.totalOverrides),
753
+ value,
754
+ componentCount,
755
+ countMismatch: false
756
+ };
757
+ }
758
+ if (parts.some((key) => Array.isArray(value[key]))) {
759
+ return { count: componentCount, value, componentCount, countMismatch: false };
760
+ }
761
+ }
762
+ if (value && Array.isArray(value.overrides)) {
763
+ return { count: value.overrides.length, value: value.overrides };
764
+ }
765
+ if (value && Number.isFinite(Number(value.length))) {
766
+ return { count: Number(value.length), value };
767
+ }
768
+ throw templateError(
769
+ "TEMPLATE_OVERRIDES_UNREADABLE",
770
+ "Editor returned an unsupported Template overrides shape for entity " +
771
+ entity.get("resource_id") + ".",
772
+ { value: serialize(value, { maxDepth: 3, maxArray: 20, maxKeys: 30 }) }
773
+ );
774
+ }
775
+
776
+ function templateReadback(entity) {
777
+ const templateId = entity.get("template_id");
778
+ const asset = templateId
779
+ ? editor.api.globals.assets.get(Number(templateId))
780
+ : null;
781
+ if (!asset || asset.get("type") !== "template") {
782
+ throw new Error("Template asset not found for entity: " + entity.get("resource_id"));
783
+ }
784
+
785
+ const entities = asset.get("data.entities") || {};
786
+ const entries = Array.isArray(entities)
787
+ ? entities.map((value, index) => [String(index), value])
788
+ : Object.entries(entities);
789
+ const entityIds = new Set(entries.map(([id]) => String(id)));
790
+ const rootEntry = entries.find(([, value]) => {
791
+ const parent = value && typeof value === "object" ? value.parent : null;
792
+ return parent === null || parent === undefined || !entityIds.has(String(parent));
793
+ });
794
+
795
+ return {
796
+ templateId: asset.get("id"),
797
+ templateName: asset.get("name"),
798
+ templateRootId: rootEntry ? rootEntry[0] : null,
799
+ storedRootEnabled: rootEntry && rootEntry[1] && typeof rootEntry[1] === "object"
800
+ ? rootEntry[1].enabled ?? null
801
+ : null,
802
+ sourceEnabled: entity.get("enabled")
803
+ };
804
+ }
805
+
806
+ async function waitForTemplateOverrides(entity, deadline, intervalMs) {
807
+ let last = templateOverrides(entity);
808
+ while (Date.now() <= deadline) {
809
+ const remainingMs = deadline - Date.now();
810
+ if (remainingMs <= 0) break;
811
+ const waitMs = Math.min(intervalMs, remainingMs);
812
+ if (last.count === 0) {
813
+ await new Promise((resolve) => setTimeout(resolve, waitMs));
814
+ const confirmed = templateOverrides(entity);
815
+ if (confirmed.count === 0) return confirmed;
816
+ last = confirmed;
817
+ } else {
818
+ await new Promise((resolve) => setTimeout(resolve, waitMs));
819
+ last = templateOverrides(entity);
820
+ }
821
+ }
822
+ throw templateError(
823
+ "TEMPLATE_OBSERVER_NOT_CONVERGED",
824
+ "Template pipeline completed, but overrides did not converge for entity " +
825
+ entity.get("resource_id") + " (remaining: " + last.count + ").",
826
+ { entityId: entity.get("resource_id"), remainingOverrides: last.count }
827
+ );
828
+ }
829
+
830
+ async function waitForTemplateCallback(promise, entity, deadline) {
831
+ const remainingMs = deadline - Date.now();
832
+ if (remainingMs <= 0) {
833
+ throw templateError(
834
+ "TEMPLATE_CALLBACK_TIMEOUT",
835
+ "Timed out waiting for Template pipeline callback for entity " + entity.get("resource_id") + ".",
836
+ { entityId: entity.get("resource_id"), stateUnknown: true }
837
+ );
838
+ }
839
+ let timer;
840
+ try {
841
+ return await Promise.race([
842
+ promise,
843
+ new Promise((_, reject) => {
844
+ timer = setTimeout(() => reject(templateError(
845
+ "TEMPLATE_CALLBACK_TIMEOUT",
846
+ "Timed out waiting for Template pipeline callback for entity " +
847
+ entity.get("resource_id") + ".",
848
+ { entityId: entity.get("resource_id"), stateUnknown: true }
849
+ )), remainingMs);
850
+ })
851
+ ]);
852
+ } finally {
853
+ clearTimeout(timer);
854
+ }
855
+ }
856
+
857
+ async function applyTemplate(entity, deadline, intervalMs) {
858
+ const startedAt = Date.now();
859
+ const beforeReadback = templateReadback(entity);
860
+ const beforeState = templateOverrides(entity);
861
+ const enabledOverride = JSON.stringify(
862
+ serialize(beforeState.value, { maxDepth: 4, maxArray: 100, maxKeys: 100 })
863
+ ).includes("enabled");
864
+ let callback = null;
865
+ let callResult = null;
866
+
867
+ if (beforeState.count > 0) {
868
+ let resolveCallback;
869
+ const callbackPromise = new Promise((resolve) => {
870
+ resolveCallback = resolve;
871
+ });
872
+ callResult = editor.call(
873
+ "templates:apply",
874
+ templateObserver(entity),
875
+ (...values) => resolveCallback(values)
876
+ );
877
+ if (callResult !== true) {
878
+ throw templateError(
879
+ "TEMPLATE_APPLY_REJECTED",
880
+ "Editor rejected Template apply for entity " + entity.get("resource_id") + ".",
881
+ { entityId: entity.get("resource_id"), accepted: false }
882
+ );
883
+ }
884
+ const callbackValues = await waitForTemplateCallback(callbackPromise, entity, deadline);
885
+ callback = serialize(callbackValues, { maxDepth: 3, maxArray: 20, maxKeys: 30 });
886
+ }
887
+
888
+ const afterState = beforeState.count > 0
889
+ ? await waitForTemplateOverrides(entity, deadline, intervalMs)
890
+ : beforeState;
891
+ const readback = templateReadback(entity);
892
+ if (String(readback.templateId) !== String(beforeReadback.templateId)) {
893
+ throw templateError(
894
+ "TEMPLATE_ID_CHANGED",
895
+ "Template id changed while applying entity " + entity.get("resource_id") + ".",
896
+ { beforeTemplateId: beforeReadback.templateId, afterTemplateId: readback.templateId }
897
+ );
898
+ }
899
+ return {
900
+ entityId: entity.get("resource_id"),
901
+ templateId: readback.templateId,
902
+ templateName: readback.templateName,
903
+ before: beforeState.count,
904
+ after: afterState.count,
905
+ applied: beforeState.count > 0,
906
+ accepted: beforeState.count > 0 ? true : null,
907
+ callbackReceived: beforeState.count > 0,
908
+ observerVerified: afterState.count === 0,
909
+ verified: afterState.count === 0,
910
+ completionSignal: beforeState.count > 0 ? "pipeline-callback-and-overrides" : "no-overrides",
911
+ verificationScope: "current-editor-observer",
912
+ reloadPersistenceChecked: false,
913
+ durationMs: Date.now() - startedAt,
914
+ sourceEnabled: readback.sourceEnabled,
915
+ storedRootEnabled: readback.storedRootEnabled,
916
+ templateRootId: readback.templateRootId,
917
+ enabledOverride,
918
+ warnings: enabledOverride
919
+ ? ["The applied overrides include enabled state; confirm this was not temporary preview state."]
920
+ : [],
921
+ callResult: serialize(callResult, { maxDepth: 2, maxArray: 10, maxKeys: 20 }),
922
+ callback
923
+ };
924
+ }
925
+ `;
926
+ export function templateOverridesSnippet() {
927
+ return `
928
+ ${templateApplyHelpers}
929
+ const args = command.args || {};
930
+ const entity = editor.api.globals.entities.get(args.entityId || args.id);
931
+ if (!entity) {
932
+ throw new Error("Template source entity not found: " + (args.entityId || args.id));
933
+ }
934
+ const state = templateOverrides(entity);
935
+ const readback = templateReadback(entity);
936
+ return {
937
+ entityId: entity.get("resource_id"),
938
+ templateId: readback.templateId,
939
+ templateName: readback.templateName,
940
+ count: state.count,
941
+ sourceEnabled: readback.sourceEnabled,
942
+ storedRootEnabled: readback.storedRootEnabled,
943
+ templateRootId: readback.templateRootId,
944
+ overrides: serialize(state.value, { maxDepth: 5, maxArray: 200, maxKeys: 200 })
945
+ };
946
+ `;
947
+ }
948
+ export function templateApplySnippet() {
949
+ return `
950
+ ${templateApplyHelpers}
951
+ const args = command.args || {};
952
+ const totalTimeoutMs = Number(args.waitTimeoutMs || command.timeoutMs || 15000);
953
+ const deadline = Date.now() + Math.max(100, totalTimeoutMs - 500);
954
+ const ids = Array.isArray(args.entityIds) && args.entityIds.length
955
+ ? args.entityIds
956
+ : [args.entityId || args.id];
957
+ const entitiesApi = editor.api.globals.entities;
958
+ if (editor.call("permissions:write") === false) {
959
+ throw templateError("WRITE_DENIED", "PlayCanvas Editor write permission is required.");
960
+ }
961
+ const entities = ids.map((id) => {
962
+ const entity = entitiesApi.get(id);
963
+ if (!entity) throw new Error("Template source entity not found: " + id);
964
+ templateReadback(entity);
965
+ templateOverrides(entity);
966
+ return entity;
967
+ });
968
+ const intervalMs = Math.max(10, Number(args.pollIntervalMs || 200));
969
+ const items = [];
970
+ for (const entity of entities) {
971
+ try {
972
+ items.push(await applyTemplate(entity, deadline, intervalMs));
973
+ } catch (error) {
974
+ const completedEntityIds = items.map((item) => item.entityId);
975
+ if (error && typeof error === "object") {
976
+ error.details = { ...(error.details || {}), completedEntityIds };
977
+ throw error;
978
+ }
979
+ throw templateError(
980
+ "TEMPLATE_APPLY_FAILED",
981
+ String(error),
982
+ { completedEntityIds }
983
+ );
984
+ }
985
+ }
986
+ return {
987
+ affected: items.filter((item) => item.applied).length,
988
+ verified: items.every((item) => item.verified),
989
+ verificationScope: "current-editor-observer",
990
+ reloadPersistenceChecked: false,
991
+ items
992
+ };
993
+ `;
994
+ }
717
995
  export function assetDeleteSnippet() {
718
996
  return `
719
997
  ${assetReader}
@@ -826,9 +1104,343 @@ return {
826
1104
  };
827
1105
  `;
828
1106
  }
1107
+ const scriptUpdateHelpers = `
1108
+ function scriptError(code, message, details) {
1109
+ const error = new Error(message);
1110
+ error.code = code;
1111
+ error.details = details || {};
1112
+ return error;
1113
+ }
1114
+
1115
+ async function withScriptDeadline(promise, deadline, code, message, details) {
1116
+ const remainingMs = deadline - Date.now();
1117
+ if (remainingMs <= 0) throw scriptError(code, message, details);
1118
+ let timer;
1119
+ try {
1120
+ return await Promise.race([
1121
+ promise,
1122
+ new Promise((_, reject) => {
1123
+ timer = setTimeout(() => reject(scriptError(code, message, details)), remainingMs);
1124
+ })
1125
+ ]);
1126
+ } finally {
1127
+ clearTimeout(timer);
1128
+ }
1129
+ }
1130
+
1131
+ function scriptBranchId() {
1132
+ return window.config?.self?.branch?.id || window.config?.branch?.id || null;
1133
+ }
1134
+
1135
+ function scriptFileSnapshot(asset) {
1136
+ const file = asset.get("file") || null;
1137
+ return {
1138
+ filename: asset.get("file.filename") || asset.get("name") || null,
1139
+ hash: asset.get("file.hash") || null,
1140
+ size: asset.get("file.size") || null,
1141
+ file
1142
+ };
1143
+ }
1144
+
1145
+ function scriptFileSignature(snapshot) {
1146
+ return JSON.stringify([snapshot?.filename || null, snapshot?.hash || null, snapshot?.size ?? null]);
1147
+ }
1148
+
1149
+ async function putScriptText(globals, asset, text, fallbackFilename, deadline) {
1150
+ const filename = asset.get("file.filename") || fallbackFilename || asset.get("name");
1151
+ const form = new FormData();
1152
+ form.append("filename", filename);
1153
+ form.append("file", new Blob([String(text || "")], { type: "text/javascript" }), filename);
1154
+ const branchId = scriptBranchId();
1155
+ if (branchId) form.append("branchId", String(branchId));
1156
+ const headers = {};
1157
+ if (globals.accessToken) headers.Authorization = "Bearer " + globals.accessToken;
1158
+ const response = await withScriptDeadline(
1159
+ fetch("/api/assets/" + asset.get("id"), { method: "PUT", headers, body: form }),
1160
+ deadline,
1161
+ "SCRIPT_UPDATE_TIMEOUT",
1162
+ "Timed out updating script asset " + asset.get("id") + ".",
1163
+ { assetId: String(asset.get("id")), stateUnknown: true }
1164
+ );
1165
+ const body = await withScriptDeadline(
1166
+ response.json().catch(() => ({})),
1167
+ deadline,
1168
+ "SCRIPT_UPDATE_TIMEOUT",
1169
+ "Timed out reading the update response for script asset " + asset.get("id") + ".",
1170
+ { assetId: String(asset.get("id")), stateUnknown: true }
1171
+ );
1172
+ if (!response.ok || body.error) {
1173
+ throw new Error(body.error || "Failed to update script asset.");
1174
+ }
1175
+ return body;
1176
+ }
1177
+
1178
+ async function readRemoteScriptText(globals, asset, filename, deadline) {
1179
+ const branchId = scriptBranchId();
1180
+ const params = new URLSearchParams();
1181
+ if (branchId) params.set("branchId", String(branchId));
1182
+ params.set("pcbridge", String(Date.now()));
1183
+ const headers = { "Cache-Control": "no-cache" };
1184
+ if (globals.accessToken) headers.Authorization = "Bearer " + globals.accessToken;
1185
+ const response = await withScriptDeadline(
1186
+ fetch(
1187
+ "/api/assets/" + encodeURIComponent(String(asset.get("id"))) +
1188
+ "/file/" + encodeURIComponent(String(filename)) + "?" + params.toString(),
1189
+ { headers, cache: "no-store" }
1190
+ ),
1191
+ deadline,
1192
+ "SCRIPT_READBACK_TIMEOUT",
1193
+ "Timed out reading script asset " + asset.get("id") + ".",
1194
+ { assetId: String(asset.get("id")) }
1195
+ );
1196
+ if (!response.ok) return null;
1197
+ return withScriptDeadline(
1198
+ response.text(),
1199
+ deadline,
1200
+ "SCRIPT_READBACK_TIMEOUT",
1201
+ "Timed out reading script content for asset " + asset.get("id") + ".",
1202
+ { assetId: String(asset.get("id")) }
1203
+ );
1204
+ }
1205
+
1206
+ async function waitForScriptFile(
1207
+ globals,
1208
+ asset,
1209
+ expectedText,
1210
+ fallbackFilename,
1211
+ beforeSignature,
1212
+ allowUnchangedSignature,
1213
+ deadline,
1214
+ intervalMs
1215
+ ) {
1216
+ let stableCount = 0;
1217
+ let previousSignature = null;
1218
+ let verifiedSignature = null;
1219
+ let last = scriptFileSnapshot(asset);
1220
+ while (Date.now() <= deadline) {
1221
+ last = scriptFileSnapshot(asset);
1222
+ const filename = last.file ? last.filename : fallbackFilename || last.filename;
1223
+ const signature = scriptFileSignature(last);
1224
+ const mutationObserved = allowUnchangedSignature || signature !== beforeSignature;
1225
+ if (
1226
+ mutationObserved &&
1227
+ last.file &&
1228
+ last.filename &&
1229
+ last.hash &&
1230
+ verifiedSignature !== signature &&
1231
+ filename
1232
+ ) {
1233
+ const remoteText = await readRemoteScriptText(globals, asset, filename, deadline).catch(() => null);
1234
+ if (remoteText === String(expectedText || "")) verifiedSignature = signature;
1235
+ }
1236
+ if (
1237
+ mutationObserved &&
1238
+ last.file &&
1239
+ last.filename &&
1240
+ last.hash &&
1241
+ verifiedSignature === signature
1242
+ ) {
1243
+ stableCount = signature === previousSignature ? stableCount + 1 : 1;
1244
+ if (stableCount >= 2) return { ...last, remoteContentVerified: true };
1245
+ } else {
1246
+ stableCount = 0;
1247
+ }
1248
+ previousSignature = signature;
1249
+ const remainingMs = deadline - Date.now();
1250
+ if (remainingMs <= 0) break;
1251
+ await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remainingMs)));
1252
+ }
1253
+ throw scriptError(
1254
+ "SCRIPT_FILE_NOT_CONVERGED",
1255
+ "Timed out waiting for script file metadata and remote content for asset " + asset.get("id") + ".",
1256
+ {
1257
+ assetId: String(asset.get("id")),
1258
+ beforeSignature,
1259
+ actualSignature: scriptFileSignature(last),
1260
+ remoteContentVerified: verifiedSignature === scriptFileSignature(last)
1261
+ }
1262
+ );
1263
+ }
1264
+
1265
+ async function parseScriptAsset(asset, deadline) {
1266
+ const remainingMs = deadline - Date.now();
1267
+ if (remainingMs <= 0) {
1268
+ const timeoutError = new Error("Timed out before parsing script asset " + asset.get("id") + ".");
1269
+ timeoutError.code = "SCRIPT_PARSE_CALLBACK_TIMEOUT";
1270
+ timeoutError.details = { assetId: String(asset.get("id")), parserCompleted: false };
1271
+ throw timeoutError;
1272
+ }
1273
+ let timer;
1274
+ const [error, data] = await new Promise((resolve, reject) => {
1275
+ timer = setTimeout(() => {
1276
+ const timeoutError = new Error("Timed out parsing script asset " + asset.get("id") + ".");
1277
+ timeoutError.code = "SCRIPT_PARSE_CALLBACK_TIMEOUT";
1278
+ timeoutError.details = { assetId: String(asset.get("id")), parserCompleted: false };
1279
+ reject(timeoutError);
1280
+ }, remainingMs);
1281
+ editor.call("scripts:parse", asset.observer, (...values) => {
1282
+ clearTimeout(timer);
1283
+ resolve(values);
1284
+ });
1285
+ });
1286
+ if (error) {
1287
+ const parseError = new Error(String(error));
1288
+ parseError.code = "SCRIPT_PARSE_FAILED";
1289
+ parseError.details = { assetId: String(asset.get("id")), parserCompleted: true };
1290
+ throw parseError;
1291
+ }
1292
+ return data || {};
1293
+ }
1294
+
1295
+ function stableScriptValue(value) {
1296
+ if (Array.isArray(value)) return value.map(stableScriptValue);
1297
+ if (value && typeof value === "object") {
1298
+ return Object.fromEntries(
1299
+ Object.keys(value).sort().map((key) => [key, stableScriptValue(value[key])])
1300
+ );
1301
+ }
1302
+ return value;
1303
+ }
1304
+
1305
+ function normalizedScriptMetadata(scripts) {
1306
+ return Object.keys(scripts || {}).sort().map((name) => {
1307
+ const definition = scripts[name] || {};
1308
+ return [name, {
1309
+ attributesOrder: Array.isArray(definition.attributesOrder)
1310
+ ? definition.attributesOrder.map(String)
1311
+ : [],
1312
+ attributes: stableScriptValue(definition.attributes || {})
1313
+ }];
1314
+ });
1315
+ }
1316
+
1317
+ function scriptParseFailures(diagnostics) {
1318
+ const scriptsInvalid = Array.isArray(diagnostics?.scriptsInvalid)
1319
+ ? diagnostics.scriptsInvalid
1320
+ : [];
1321
+ const attributesInvalid = Object.entries(diagnostics?.scripts || {}).flatMap(
1322
+ ([name, definition]) => Array.isArray(definition?.attributesInvalid) && definition.attributesInvalid.length
1323
+ ? [{ name, errors: definition.attributesInvalid }]
1324
+ : []
1325
+ );
1326
+ return { scriptsInvalid, attributesInvalid };
1327
+ }
1328
+
1329
+ function throwIfScriptParseInvalid(diagnostics, fileUpdated) {
1330
+ const failures = scriptParseFailures(diagnostics);
1331
+ if (!failures.scriptsInvalid.length && !failures.attributesInvalid.length) {
1332
+ if (diagnostics?.scripts && Object.keys(diagnostics.scripts).length > 0) return;
1333
+ throw scriptError(
1334
+ "SCRIPT_NO_DECLARATIONS",
1335
+ "Script parser returned no declarations.",
1336
+ {
1337
+ fileUpdated: Boolean(fileUpdated),
1338
+ parserCompleted: true,
1339
+ metadataApplied: false
1340
+ }
1341
+ );
1342
+ }
1343
+ const error = new Error("Script parse returned invalid scripts or attributes.");
1344
+ error.code = "SCRIPT_PARSE_INVALID";
1345
+ error.details = {
1346
+ ...failures,
1347
+ fileUpdated: Boolean(fileUpdated),
1348
+ parserCompleted: true,
1349
+ metadataApplied: false
1350
+ };
1351
+ throw error;
1352
+ }
1353
+
1354
+ async function waitForScriptMetadata(asset, expectedScripts, deadline, intervalMs) {
1355
+ const expected = JSON.stringify(normalizedScriptMetadata(expectedScripts || {}));
1356
+ let stableCount = 0;
1357
+ let last = asset.get("data.scripts") || {};
1358
+ while (Date.now() <= deadline) {
1359
+ last = asset.get("data.scripts") || {};
1360
+ if (JSON.stringify(normalizedScriptMetadata(last)) === expected) {
1361
+ stableCount += 1;
1362
+ if (stableCount >= 2) return last;
1363
+ } else {
1364
+ stableCount = 0;
1365
+ }
1366
+ const remainingMs = deadline - Date.now();
1367
+ if (remainingMs <= 0) break;
1368
+ await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remainingMs)));
1369
+ }
1370
+ const error = new Error(
1371
+ "Parsed script metadata did not converge for asset " + asset.get("id") + "."
1372
+ );
1373
+ error.code = "SCRIPT_METADATA_NOT_CONVERGED";
1374
+ error.details = {
1375
+ assetId: String(asset.get("id")),
1376
+ expected: normalizedScriptMetadata(expectedScripts || {}),
1377
+ actual: normalizedScriptMetadata(last || {})
1378
+ };
1379
+ throw error;
1380
+ }
1381
+
1382
+ function readScriptMetadata(scripts) {
1383
+ return Object.fromEntries(Object.entries(scripts || {}).map(([name, definition]) => [name, {
1384
+ attributesOrder: definition?.attributesOrder || null,
1385
+ attributesInvalid: definition?.attributesInvalid || null
1386
+ }]));
1387
+ }
1388
+
1389
+ async function finishScriptUpdate(globals, asset, text, fallbackFilename, args) {
1390
+ const startedAt = Number(args.updateStartedAt || Date.now());
1391
+ const timeoutMs = Math.max(100, Number(args.waitTimeoutMs || command.timeoutMs || 60000) - 500);
1392
+ const deadline = Number(args.updateDeadline || startedAt + timeoutMs);
1393
+ const intervalMs = Math.max(50, Number(args.pollIntervalMs || 500));
1394
+ let file = scriptFileSnapshot(asset);
1395
+ if (args.wait) {
1396
+ file = await waitForScriptFile(
1397
+ globals,
1398
+ asset,
1399
+ text,
1400
+ fallbackFilename,
1401
+ args.beforeFileSignature || null,
1402
+ Boolean(args.allowUnchangedFileSignature),
1403
+ deadline,
1404
+ intervalMs
1405
+ );
1406
+ }
1407
+
1408
+ let diagnostics = null;
1409
+ let scripts = asset.get("data.scripts") || {};
1410
+ if (args.parse) {
1411
+ diagnostics = await parseScriptAsset(asset, deadline);
1412
+ throwIfScriptParseInvalid(diagnostics, true);
1413
+ const parsedScripts = diagnostics.scripts || {};
1414
+ if (args.wait) {
1415
+ scripts = await waitForScriptMetadata(
1416
+ asset,
1417
+ parsedScripts,
1418
+ deadline,
1419
+ intervalMs
1420
+ );
1421
+ } else {
1422
+ scripts = parsedScripts;
1423
+ }
1424
+ }
1425
+
1426
+ return {
1427
+ asset: readAsset(asset),
1428
+ file,
1429
+ scripts,
1430
+ scriptMetadata: readScriptMetadata(scripts),
1431
+ parseDiagnostics: diagnostics
1432
+ ? Object.fromEntries(Object.entries(diagnostics).filter(([key]) => key !== "scripts"))
1433
+ : null,
1434
+ parsed: Boolean(args.parse),
1435
+ waited: Boolean(args.wait),
1436
+ durationMs: Date.now() - startedAt
1437
+ };
1438
+ }
1439
+ `;
829
1440
  export function scriptSetTextSnippet() {
830
1441
  return `
831
1442
  ${assetReader}
1443
+ ${scriptUpdateHelpers}
832
1444
  const args = command.args || {};
833
1445
  const globals = editor.api.globals;
834
1446
  const asset = globals.assets.get(Number(args.assetId));
@@ -838,29 +1450,39 @@ if (!asset) {
838
1450
  if (asset.get("type") !== "script") {
839
1451
  throw new Error("Asset is not a script: " + args.assetId);
840
1452
  }
841
- const filename = asset.get("file.filename") || asset.get("name");
842
- const form = new FormData();
843
- form.append("filename", filename);
844
- form.append("file", new Blob([String(args.text || "")], { type: "text/javascript" }), filename);
845
- const branchId = window.config?.self?.branch?.id || window.config?.branch?.id;
846
- if (branchId) {
847
- form.append("branchId", String(branchId));
848
- }
849
- const headers = {};
850
- if (globals.accessToken) {
851
- headers.Authorization = "Bearer " + globals.accessToken;
852
- }
853
- const response = await fetch("/api/assets/" + asset.get("id"), {
854
- method: "PUT",
855
- headers,
856
- body: form
857
- });
858
- const body = await response.json().catch(() => ({}));
859
- if (!response.ok || body.error) {
860
- throw new Error(body.error || "Failed to update script asset.");
861
- }
1453
+ const updateStartedAt = Date.now();
1454
+ const updateTimeoutMs = Math.max(
1455
+ 100,
1456
+ Number(args.waitTimeoutMs || command.timeoutMs || 60000) - 500
1457
+ );
1458
+ const updateArgs = {
1459
+ ...args,
1460
+ updateStartedAt,
1461
+ updateDeadline: updateStartedAt + updateTimeoutMs
1462
+ };
1463
+ const filename = asset.get("file.filename") || args.filename || asset.get("name");
1464
+ const beforeFile = scriptFileSnapshot(asset);
1465
+ let beforeRemoteText = null;
1466
+ if (args.wait && beforeFile.file && filename) {
1467
+ beforeRemoteText = await readRemoteScriptText(
1468
+ globals,
1469
+ asset,
1470
+ filename,
1471
+ updateArgs.updateDeadline
1472
+ ).catch(() => null);
1473
+ }
1474
+ updateArgs.beforeFileSignature = scriptFileSignature(beforeFile);
1475
+ updateArgs.allowUnchangedFileSignature = beforeRemoteText === String(args.text || "");
1476
+ const body = await putScriptText(
1477
+ globals,
1478
+ asset,
1479
+ args.text,
1480
+ filename,
1481
+ updateArgs.updateDeadline
1482
+ );
1483
+ const result = await finishScriptUpdate(globals, asset, args.text, filename, updateArgs);
862
1484
  return {
863
- asset: readAsset(asset),
1485
+ ...result,
864
1486
  response: body
865
1487
  };
866
1488
  `;
@@ -869,12 +1491,23 @@ export function scriptUpsertSnippet() {
869
1491
  return `
870
1492
  ${assetReader}
871
1493
  ${assetFolderHelpers}
1494
+ ${scriptUpdateHelpers}
872
1495
  const args = command.args || {};
873
1496
  const globals = editor.api.globals;
874
1497
  const assets = globals.assets;
875
1498
  if (!args.filename) {
876
1499
  throw new Error("filename is required.");
877
1500
  }
1501
+ const updateStartedAt = Date.now();
1502
+ const updateTimeoutMs = Math.max(
1503
+ 100,
1504
+ Number(args.waitTimeoutMs || command.timeoutMs || 60000) - 500
1505
+ );
1506
+ const updateArgs = {
1507
+ ...args,
1508
+ updateStartedAt,
1509
+ updateDeadline: updateStartedAt + updateTimeoutMs
1510
+ };
878
1511
  const folderResult = await resolveFolder(assets, args);
879
1512
  const folderId = folderResult.folder ? folderResult.folder.get("id") : null;
880
1513
  function isInTargetFolder(asset) {
@@ -882,7 +1515,7 @@ function isInTargetFolder(asset) {
882
1515
  const path = asset.get("path") || [];
883
1516
  return path[path.length - 1] === folderId;
884
1517
  }
885
- let asset = assets.list().find((candidate) =>
1518
+ const matches = assets.list().filter((candidate) =>
886
1519
  candidate.get("type") === "script" &&
887
1520
  isInTargetFolder(candidate) &&
888
1521
  (
@@ -890,54 +1523,61 @@ let asset = assets.list().find((candidate) =>
890
1523
  candidate.get("name") === args.filename
891
1524
  )
892
1525
  );
1526
+ if (!folderId && !args.folder && matches.length > 1) {
1527
+ throw new Error(
1528
+ "Multiple script assets match " + args.filename + ": " +
1529
+ matches.map((candidate) => candidate.get("id") + "@" + (candidate.get("path") || []).join("/")).join(", ") +
1530
+ ". Specify --folder or --folder-id."
1531
+ );
1532
+ }
1533
+ let asset = matches[0] || null;
893
1534
  let action = "updated";
1535
+ let responseBody = null;
894
1536
  if (!asset) {
895
- asset = await assets.createScript({
896
- filename: args.filename,
897
- text: String(args.text || ""),
898
- folder: folderResult.folder || undefined,
899
- preload: args.preload !== false
900
- });
1537
+ asset = await withScriptDeadline(
1538
+ assets.createScript({
1539
+ filename: args.filename,
1540
+ text: String(args.text || ""),
1541
+ folder: folderResult.folder || undefined,
1542
+ preload: args.preload !== false
1543
+ }),
1544
+ updateArgs.updateDeadline,
1545
+ "SCRIPT_CREATE_TIMEOUT",
1546
+ "Timed out creating script asset " + args.filename + ".",
1547
+ { filename: args.filename, stateUnknown: true }
1548
+ );
901
1549
  action = "created";
1550
+ updateArgs.beforeFileSignature = null;
1551
+ updateArgs.allowUnchangedFileSignature = false;
902
1552
  } else {
903
- const filename = asset.get("file.filename") || asset.get("name") || args.filename;
904
- const form = new FormData();
905
- form.append("filename", filename);
906
- form.append("file", new Blob([String(args.text || "")], { type: "text/javascript" }), filename);
907
- const branchId = window.config?.self?.branch?.id || window.config?.branch?.id;
908
- if (branchId) {
909
- form.append("branchId", String(branchId));
910
- }
911
- const headers = {};
912
- if (globals.accessToken) {
913
- headers.Authorization = "Bearer " + globals.accessToken;
914
- }
915
- const response = await fetch("/api/assets/" + asset.get("id"), {
916
- method: "PUT",
917
- headers,
918
- body: form
919
- });
920
- const body = await response.json().catch(() => ({}));
921
- if (!response.ok || body.error) {
922
- throw new Error(body.error || "Failed to update script asset.");
1553
+ const filename = asset.get("file.filename") || args.filename || asset.get("name");
1554
+ const beforeFile = scriptFileSnapshot(asset);
1555
+ let beforeRemoteText = null;
1556
+ if (args.wait && beforeFile.file && filename) {
1557
+ beforeRemoteText = await readRemoteScriptText(
1558
+ globals,
1559
+ asset,
1560
+ filename,
1561
+ updateArgs.updateDeadline
1562
+ ).catch(() => null);
923
1563
  }
1564
+ updateArgs.beforeFileSignature = scriptFileSignature(beforeFile);
1565
+ updateArgs.allowUnchangedFileSignature = beforeRemoteText === String(args.text || "");
1566
+ responseBody = await putScriptText(
1567
+ globals,
1568
+ asset,
1569
+ args.text,
1570
+ filename,
1571
+ updateArgs.updateDeadline
1572
+ );
924
1573
  }
925
1574
 
926
- let scripts = asset.get("data.scripts") || {};
927
- if (args.parse) {
928
- const [error, data] = await new Promise((resolve) => {
929
- editor.call("scripts:parse", asset.observer, (...values) => resolve(values));
930
- });
931
- if (error) {
932
- throw new Error(String(error));
933
- }
934
- scripts = data?.scripts || {};
935
- }
1575
+ const result = await finishScriptUpdate(globals, asset, args.text, args.filename, updateArgs);
936
1576
 
937
1577
  return {
938
1578
  action,
939
- asset: readAsset(asset),
940
- scripts,
1579
+ ...result,
1580
+ response: responseBody,
941
1581
  createdFolders: folderResult.created.map(readAsset)
942
1582
  };
943
1583
  `;
@@ -945,20 +1585,37 @@ return {
945
1585
  export function scriptParseSnippet() {
946
1586
  return `
947
1587
  ${assetReader}
1588
+ ${scriptUpdateHelpers}
948
1589
  const args = command.args || {};
949
1590
  const asset = editor.api.globals.assets.get(Number(args.assetId));
950
1591
  if (!asset) {
951
1592
  throw new Error("Asset not found: " + args.assetId);
952
1593
  }
953
- const [error, data] = await new Promise((resolve) => {
954
- editor.call("scripts:parse", asset.observer, (...values) => resolve(values));
955
- });
956
- if (error) {
957
- throw new Error(String(error));
1594
+ if (asset.get("type") !== "script") {
1595
+ throw new Error("Asset is not a script: " + args.assetId);
958
1596
  }
1597
+ const startedAt = Date.now();
1598
+ const timeoutMs = Math.max(100, Number(args.waitTimeoutMs || command.timeoutMs || 60000) - 500);
1599
+ const deadline = startedAt + timeoutMs;
1600
+ const intervalMs = Math.max(50, Number(args.pollIntervalMs || 500));
1601
+ const diagnostics = await parseScriptAsset(asset, deadline);
1602
+ throwIfScriptParseInvalid(diagnostics, false);
1603
+ const scripts = await waitForScriptMetadata(
1604
+ asset,
1605
+ diagnostics.scripts || {},
1606
+ deadline,
1607
+ intervalMs
1608
+ );
959
1609
  return {
960
1610
  asset: readAsset(asset),
961
- scripts: data?.scripts || {}
1611
+ scripts,
1612
+ scriptMetadata: readScriptMetadata(scripts),
1613
+ parseDiagnostics: Object.fromEntries(
1614
+ Object.entries(diagnostics).filter(([key]) => key !== "scripts")
1615
+ ),
1616
+ parsed: true,
1617
+ observerVerified: true,
1618
+ durationMs: Date.now() - startedAt
962
1619
  };
963
1620
  `;
964
1621
  }