playcanvas-agent-bridge-cli 0.2.1 → 0.3.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.
package/dist/cli.js CHANGED
@@ -3,11 +3,12 @@ import { spawn } from "node:child_process";
3
3
  import { realpathSync } from "node:fs";
4
4
  import { readFile, writeFile, mkdir } from "node:fs/promises";
5
5
  import { homedir } from "node:os";
6
- import { basename, dirname, extname, join } from "node:path";
6
+ import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
- import { CONFIG_DIR, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
8
+ import { CONFIG_DIR, DEFAULT_FRONTEND_PORT, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
9
9
  import { createDaemonServer } from "./daemon/server.js";
10
- import { assetDeleteSnippet, assetFolderEnsureSnippet, assetGetSnippet, assetListSnippet, assetUploadSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateSnippet, entityDeleteSnippet, entityGetSnippet, entityListSnippet, entityPatchSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, } from "./snippets.js";
10
+ import { FrontendError, getFrontendStatus, installFrontend, listFrontends, removeFrontend, useFrontend, } from "./frontend/store.js";
11
+ import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateCreateSnippet, } from "./snippets.js";
11
12
  import { fail, ok } from "./shared/protocol.js";
12
13
  function parseArgs(argv) {
13
14
  const parsed = { _: [], flags: {} };
@@ -210,6 +211,46 @@ function objectJson(value, label) {
210
211
  }
211
212
  return value;
212
213
  }
214
+ function uploadSpecFromJson(value, label) {
215
+ const data = objectJson(value, label);
216
+ const file = typeof data.file === "string" ? data.file : "";
217
+ if (!file) {
218
+ throw new Error(`${label}.file is required.`);
219
+ }
220
+ return {
221
+ key: typeof data.key === "string" ? data.key : undefined,
222
+ file,
223
+ name: typeof data.name === "string" ? data.name : undefined,
224
+ filename: typeof data.filename === "string" ? data.filename : undefined,
225
+ type: typeof data.type === "string" ? data.type : undefined,
226
+ mime: typeof data.mime === "string" ? data.mime : undefined,
227
+ folder: typeof data.folder === "string" ? data.folder : undefined,
228
+ folderId: typeof data.folderId === "string" || typeof data.folderId === "number"
229
+ ? String(data.folderId)
230
+ : undefined,
231
+ preload: typeof data.preload === "boolean" ? data.preload : undefined,
232
+ };
233
+ }
234
+ function resolveManifestFile(manifestPath, file) {
235
+ return isAbsolute(file) ? file : resolve(dirname(manifestPath), file);
236
+ }
237
+ async function uploadAsset(args, spec) {
238
+ const fileBuffer = await readFile(spec.file);
239
+ const type = spec.type || inferAssetType(spec.file);
240
+ if (!type)
241
+ return fail("INVALID_REQUEST", `asset upload requires --type for ${spec.file}.`);
242
+ const filename = spec.filename || basename(spec.file);
243
+ return rpcCall(args, "bridge:uploadAsset", {
244
+ base64: fileBuffer.toString("base64"),
245
+ mime: spec.mime || inferMime(spec.file),
246
+ name: spec.name || nameFromFile(spec.file),
247
+ filename,
248
+ type,
249
+ folder: spec.folder || null,
250
+ folderId: spec.folderId || null,
251
+ preload: spec.preload !== false,
252
+ }, 120000);
253
+ }
213
254
  async function doctor() {
214
255
  const session = await readSessionIfExists();
215
256
  const checks = [];
@@ -241,18 +282,72 @@ async function doctor() {
241
282
  });
242
283
  nextActions.push("Run pcbridge daemon start in a terminal.");
243
284
  }
285
+ const frontend = await getFrontendStatus();
286
+ checks.push({
287
+ name: "frontend",
288
+ ok: frontend.ready,
289
+ activeRelease: frontend.activeRelease,
290
+ installedCount: frontend.installed.length,
291
+ message: frontend.ready
292
+ ? `Frontend ${frontend.activeRelease} is ready.`
293
+ : "No active custom Editor frontend is installed.",
294
+ });
295
+ if (!frontend.ready) {
296
+ nextActions.push("Run pcbridge frontend install latest.");
297
+ }
244
298
  const extensionExists = Boolean(session) && (await pathExists(EXTENSION_INSTALL_DIR));
299
+ let generatedExtensionVersion = null;
300
+ if (extensionExists) {
301
+ try {
302
+ const manifest = JSON.parse(await readFile(join(EXTENSION_INSTALL_DIR, "manifest.json"), "utf8"));
303
+ generatedExtensionVersion = manifest.version || null;
304
+ }
305
+ catch {
306
+ generatedExtensionVersion = null;
307
+ }
308
+ }
245
309
  checks.push({
246
310
  name: "extension",
247
- ok: extensionExists,
311
+ ok: extensionExists && generatedExtensionVersion === VERSION,
248
312
  path: EXTENSION_INSTALL_DIR,
249
- message: extensionExists
250
- ? "Generated unpacked extension directory exists."
251
- : "Generated unpacked extension directory was not found.",
313
+ version: generatedExtensionVersion,
314
+ expectedVersion: VERSION,
315
+ message: extensionExists && generatedExtensionVersion === VERSION
316
+ ? "Generated unpacked extension directory exists and matches package version."
317
+ : extensionExists
318
+ ? "Generated unpacked extension version does not match package version."
319
+ : "Generated unpacked extension directory was not found.",
252
320
  });
253
321
  if (!extensionExists) {
254
322
  nextActions.push("Run pcbridge install-extension and load the printed directory in Chrome.");
255
323
  }
324
+ else if (generatedExtensionVersion !== VERSION) {
325
+ nextActions.push("Run pcbridge install-extension --no-open, then reload the unpacked extension in Chrome.");
326
+ }
327
+ try {
328
+ const targets = await fetchDaemon("/targets");
329
+ if (targets.ok && Array.isArray(targets.data)) {
330
+ const connectedVersions = targets.data
331
+ .map((target) => (target && typeof target === "object" && !Array.isArray(target) ? target.extensionVersion : null))
332
+ .filter(Boolean);
333
+ const mismatched = connectedVersions.filter((version) => version !== VERSION);
334
+ checks.push({
335
+ name: "connected-extension-version",
336
+ ok: mismatched.length === 0,
337
+ versions: connectedVersions,
338
+ expectedVersion: VERSION,
339
+ message: mismatched.length
340
+ ? "One or more connected PlayCanvas tabs are using an older extension version."
341
+ : "Connected extension versions match the package version.",
342
+ });
343
+ if (mismatched.length) {
344
+ nextActions.push("Reload the unpacked extension and refresh the PlayCanvas Editor or Launch tab.");
345
+ }
346
+ }
347
+ }
348
+ catch {
349
+ // Daemon reachability is already reported above.
350
+ }
256
351
  return ok({
257
352
  version: VERSION,
258
353
  configDir: CONFIG_DIR,
@@ -299,6 +394,7 @@ async function daemon(args) {
299
394
  host: DEFAULT_HOST,
300
395
  port: session.port || DEFAULT_PORT,
301
396
  extensionPath: EXTENSION_INSTALL_DIR,
397
+ frontend: await server.frontend.status(),
302
398
  }));
303
399
  }
304
400
  else if (subcommand === "status") {
@@ -315,6 +411,70 @@ async function daemon(args) {
315
411
  process.exitCode = 1;
316
412
  }
317
413
  }
414
+ async function handleFrontend(args) {
415
+ const subcommand = args._[1] || "status";
416
+ try {
417
+ if (subcommand === "install" || subcommand === "update") {
418
+ const requestedRelease = subcommand === "update" ? "latest" : args._[2] || "latest";
419
+ const installed = await installFrontend(requestedRelease, {
420
+ activate: !flagBool(args, "no-activate"),
421
+ });
422
+ const status = await getFrontendStatus();
423
+ return ok({
424
+ release: installed.manifest.release,
425
+ editorVersion: installed.manifest.editorVersion,
426
+ sourceCommit: installed.manifest.sourceCommit,
427
+ path: installed.path,
428
+ alreadyInstalled: installed.alreadyInstalled,
429
+ active: status.activeRelease === installed.manifest.release,
430
+ nextActions: [
431
+ "Run pcbridge daemon start if it is not already running.",
432
+ "Use the extension popup on a playcanvas.com Editor tab to select the custom frontend.",
433
+ ],
434
+ });
435
+ }
436
+ if (subcommand === "list") {
437
+ return ok(await listFrontends());
438
+ }
439
+ if (subcommand === "status") {
440
+ try {
441
+ return await fetchDaemon("/frontend/status");
442
+ }
443
+ catch {
444
+ return ok({
445
+ ...(await getFrontendStatus()),
446
+ server: {
447
+ host: DEFAULT_HOST,
448
+ port: DEFAULT_FRONTEND_PORT,
449
+ listening: false,
450
+ error: "Daemon is not reachable.",
451
+ },
452
+ });
453
+ }
454
+ }
455
+ if (subcommand === "use") {
456
+ const release = args._[2];
457
+ if (!release) {
458
+ return fail("INVALID_REQUEST", "frontend use requires a release name.");
459
+ }
460
+ return ok(await useFrontend(release));
461
+ }
462
+ if (subcommand === "remove") {
463
+ const release = args._[2];
464
+ if (!release) {
465
+ return fail("INVALID_REQUEST", "frontend remove requires a release name.");
466
+ }
467
+ return ok(await removeFrontend(release));
468
+ }
469
+ return fail("UNKNOWN_COMMAND", `Unknown frontend command: ${subcommand}`);
470
+ }
471
+ catch (error) {
472
+ if (error instanceof FrontendError) {
473
+ return fail(error.code, error.message);
474
+ }
475
+ throw error;
476
+ }
477
+ }
318
478
  async function installExtension(args) {
319
479
  const session = await readOrCreateSession();
320
480
  const root = await findPackageRoot();
@@ -338,7 +498,7 @@ async function installExtension(args) {
338
498
  "Enable Developer Mode in Chrome.",
339
499
  "Click Load unpacked.",
340
500
  `Select ${EXTENSION_INSTALL_DIR}.`,
341
- "Open or refresh a PlayCanvas Editor tab, then run pcbridge daemon start.",
501
+ "Open or refresh a PlayCanvas Editor or Launch tab, then run pcbridge daemon start.",
342
502
  ],
343
503
  });
344
504
  }
@@ -407,6 +567,7 @@ async function handleEntity(args) {
407
567
  return listEnvelope(await rpcEval(args, entityListSnippet(), {
408
568
  name: flagString(args, "name") || null,
409
569
  component: flagString(args, "component") || null,
570
+ tag: flagString(args, "tag") || null,
410
571
  limit: Number(flagString(args, "limit", "50")),
411
572
  offset: Number(flagString(args, "offset", "0")),
412
573
  full: flagBool(args, "full"),
@@ -425,12 +586,56 @@ async function handleEntity(args) {
425
586
  const data = JSON.parse(await readFile(file, "utf8"));
426
587
  return rpcEval(args, entityCreateSnippet(), { data });
427
588
  }
589
+ if (subcommand === "create-many") {
590
+ const file = flagString(args, "json");
591
+ if (!file)
592
+ return fail("INVALID_REQUEST", "entity create-many requires --json <file>.");
593
+ const data = JSON.parse(await readFile(file, "utf8"));
594
+ const entities = Array.isArray(data)
595
+ ? data
596
+ : objectJson(data, "entity create-many data").entities;
597
+ return rpcEval(args, entityCreateManySnippet(), { entities: entities || [] }, 30000);
598
+ }
428
599
  if (subcommand === "patch") {
429
600
  const id = flagString(args, "id");
430
601
  if (!id)
431
602
  return fail("INVALID_REQUEST", "entity patch requires --id.");
432
603
  return rpcEval(args, entityPatchSnippet(), { id, sets: parseSets(flagList(args, "set")) });
433
604
  }
605
+ if (subcommand === "patch-many") {
606
+ const file = flagString(args, "json");
607
+ if (!file)
608
+ return fail("INVALID_REQUEST", "entity patch-many requires --json <file>.");
609
+ const data = JSON.parse(await readFile(file, "utf8"));
610
+ const edits = Array.isArray(data)
611
+ ? data
612
+ : objectJson(data, "entity patch-many data").edits;
613
+ return rpcEval(args, entityPatchManySnippet(), { edits: edits || [] }, 30000);
614
+ }
615
+ if (subcommand === "duplicate") {
616
+ const ids = flagList(args, "id");
617
+ const id = flagString(args, "id");
618
+ if (!ids.length && !id)
619
+ return fail("INVALID_REQUEST", "entity duplicate requires --id.");
620
+ return rpcEval(args, entityDuplicateSnippet(), {
621
+ ids: ids,
622
+ id: id || null,
623
+ rename: !flagBool(args, "no-rename"),
624
+ select: !flagBool(args, "no-select"),
625
+ });
626
+ }
627
+ if (subcommand === "reparent") {
628
+ const id = flagString(args, "id");
629
+ const parent = flagString(args, "parent");
630
+ if (!id || !parent)
631
+ return fail("INVALID_REQUEST", "entity reparent requires --id and --parent.");
632
+ return rpcEval(args, entityReparentSnippet(), {
633
+ id,
634
+ parent,
635
+ index: flagString(args, "index") === undefined ? null : Number(flagString(args, "index")),
636
+ preserveTransform: !flagBool(args, "no-preserve-transform"),
637
+ });
638
+ }
434
639
  if (subcommand === "delete") {
435
640
  const ids = flagList(args, "id");
436
641
  const id = flagString(args, "id");
@@ -452,13 +657,42 @@ async function handleEntity(args) {
452
657
  data: objectJson(data, "component data"),
453
658
  });
454
659
  }
660
+ if (subcommand === "add-components") {
661
+ const id = flagString(args, "id");
662
+ const data = await readJsonFlag(args, "json");
663
+ if (!id || data === undefined) {
664
+ return fail("INVALID_REQUEST", "entity add-components requires --id and --json <file>.");
665
+ }
666
+ return rpcEval(args, entityAddComponentsSnippet(), {
667
+ id,
668
+ components: objectJson(data, "components"),
669
+ });
670
+ }
455
671
  if (subcommand === "remove-component") {
456
672
  const id = flagString(args, "id");
673
+ const components = flagList(args, "component");
457
674
  const component = flagString(args, "component");
458
- if (!id || !component) {
675
+ if (!id || (!components.length && !component)) {
459
676
  return fail("INVALID_REQUEST", "entity remove-component requires --id and --component.");
460
677
  }
461
- return rpcEval(args, entityRemoveComponentSnippet(), { id, component });
678
+ if (components.length > 1) {
679
+ return rpcEval(args, entityRemoveComponentsSnippet(), {
680
+ id,
681
+ components: components,
682
+ });
683
+ }
684
+ return rpcEval(args, entityRemoveComponentSnippet(), { id, component: component || components[0] });
685
+ }
686
+ if (subcommand === "remove-components") {
687
+ const id = flagString(args, "id");
688
+ const components = flagList(args, "component");
689
+ if (!id || !components.length) {
690
+ return fail("INVALID_REQUEST", "entity remove-components requires --id and at least one --component.");
691
+ }
692
+ return rpcEval(args, entityRemoveComponentsSnippet(), {
693
+ id,
694
+ components: components,
695
+ });
462
696
  }
463
697
  if (subcommand === "set-material") {
464
698
  const id = flagString(args, "id");
@@ -495,6 +729,7 @@ async function handleAsset(args) {
495
729
  return listEnvelope(await rpcEval(args, assetListSnippet(), {
496
730
  name: flagString(args, "name") || null,
497
731
  type: flagString(args, "type") || null,
732
+ tag: flagString(args, "tag") || null,
498
733
  limit: Number(flagString(args, "limit", "50")),
499
734
  offset: Number(flagString(args, "offset", "0")),
500
735
  full: flagBool(args, "full"),
@@ -506,31 +741,93 @@ async function handleAsset(args) {
506
741
  return fail("INVALID_REQUEST", "asset get requires --id.");
507
742
  return rpcEval(args, assetGetSnippet(), { id, full: flagBool(args, "full") });
508
743
  }
744
+ if (subcommand === "create") {
745
+ const file = flagString(args, "json");
746
+ if (!file)
747
+ return fail("INVALID_REQUEST", "asset create requires --json <file>.");
748
+ const data = JSON.parse(await readFile(file, "utf8"));
749
+ const assets = Array.isArray(data)
750
+ ? data
751
+ : objectJson(data, "asset create data").assets || [data];
752
+ return rpcEval(args, assetCreateManySnippet(), { assets }, 60000);
753
+ }
509
754
  if (subcommand === "folder" && args._[2] === "ensure") {
510
755
  const path = flagString(args, "path");
511
756
  if (!path)
512
757
  return fail("INVALID_REQUEST", "asset folder ensure requires --path.");
513
758
  return rpcEval(args, assetFolderEnsureSnippet(), { path });
514
759
  }
760
+ if (subcommand === "instantiate") {
761
+ const ids = flagList(args, "id");
762
+ const id = flagString(args, "id");
763
+ if (!ids.length && !id)
764
+ return fail("INVALID_REQUEST", "asset instantiate requires --id.");
765
+ return rpcEval(args, assetInstantiateTemplateSnippet(), {
766
+ ids: ids,
767
+ id: id || null,
768
+ }, 60000);
769
+ }
515
770
  if (subcommand === "upload") {
516
771
  const file = flagString(args, "file");
517
772
  if (!file)
518
773
  return fail("INVALID_REQUEST", "asset upload requires --file.");
519
- const fileBuffer = await readFile(file);
520
- const type = flagString(args, "type") || inferAssetType(file);
521
- if (!type)
522
- return fail("INVALID_REQUEST", "asset upload requires --type for this file.");
523
- const filename = flagString(args, "filename") || basename(file);
524
- return rpcEval(args, assetUploadSnippet(), {
525
- base64: fileBuffer.toString("base64"),
526
- mime: flagString(args, "mime") || inferMime(file),
527
- name: flagString(args, "name") || nameFromFile(file),
528
- filename,
529
- type,
530
- folder: flagString(args, "folder") || null,
531
- folderId: flagString(args, "folder-id") || null,
774
+ return uploadAsset(args, {
775
+ file,
776
+ type: flagString(args, "type"),
777
+ mime: flagString(args, "mime"),
778
+ name: flagString(args, "name"),
779
+ filename: flagString(args, "filename"),
780
+ folder: flagString(args, "folder"),
781
+ folderId: flagString(args, "folder-id"),
532
782
  preload: !flagBool(args, "no-preload"),
533
- }, 120000);
783
+ });
784
+ }
785
+ if (subcommand === "upload-many") {
786
+ const manifestPath = flagString(args, "json");
787
+ if (!manifestPath)
788
+ return fail("INVALID_REQUEST", "asset upload-many requires --json <file>.");
789
+ const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
790
+ const rawItems = Array.isArray(manifest)
791
+ ? manifest
792
+ : objectJson(manifest, "asset upload-many manifest").assets;
793
+ const items = Array.isArray(rawItems) ? rawItems : [];
794
+ if (!items.length) {
795
+ return fail("INVALID_REQUEST", "asset upload-many manifest must contain a non-empty assets array.");
796
+ }
797
+ const uploads = [];
798
+ const errors = [];
799
+ for (let index = 0; index < items.length; index += 1) {
800
+ const spec = uploadSpecFromJson(items[index], `assets[${index}]`);
801
+ spec.file = resolveManifestFile(manifestPath, spec.file);
802
+ const result = await uploadAsset(args, spec);
803
+ uploads.push({
804
+ index,
805
+ key: spec.key || null,
806
+ file: spec.file,
807
+ name: spec.name || nameFromFile(spec.file),
808
+ result: result,
809
+ });
810
+ if (!result.ok) {
811
+ errors.push({
812
+ index,
813
+ file: spec.file,
814
+ error: result.error,
815
+ });
816
+ }
817
+ }
818
+ if (errors.length) {
819
+ return fail("UPLOAD_MANY_FAILED", `${errors.length} of ${items.length} uploads failed.`, {
820
+ affected: items.length - errors.length,
821
+ failed: errors.length,
822
+ }, { uploads, errors });
823
+ }
824
+ return ok({
825
+ affected: uploads.length,
826
+ uploads,
827
+ }, {
828
+ affected: uploads.length,
829
+ failed: 0,
830
+ });
534
831
  }
535
832
  if (subcommand === "delete") {
536
833
  const ids = flagList(args, "id");
@@ -560,10 +857,74 @@ async function handleMaterial(args) {
560
857
  preload: !flagBool(args, "no-preload"),
561
858
  }, 30000);
562
859
  }
860
+ if (subcommand === "patch") {
861
+ const assetId = flagString(args, "asset-id") || flagString(args, "id");
862
+ if (!assetId)
863
+ return fail("INVALID_REQUEST", "material patch requires --asset-id.");
864
+ const data = (await readJsonFlag(args, "json")) ??
865
+ (flagString(args, "data") ? parseJsonValue(flagString(args, "data") || "{}") : {});
866
+ return rpcEval(args, materialPatchSnippet(), {
867
+ assetId,
868
+ data: objectJson(data, "material data"),
869
+ sets: parseSets(flagList(args, "set")),
870
+ });
871
+ }
872
+ if (subcommand === "set-diffuse") {
873
+ const assetId = flagString(args, "asset-id") || flagString(args, "id");
874
+ const color = flagString(args, "color");
875
+ if (!assetId || !color)
876
+ return fail("INVALID_REQUEST", "material set-diffuse requires --asset-id and --color.");
877
+ return rpcEval(args, materialPatchSnippet(), {
878
+ assetId,
879
+ data: { diffuse: parseJsonValue(color) },
880
+ sets: [],
881
+ });
882
+ }
563
883
  return fail("UNKNOWN_COMMAND", `Unknown material command: ${subcommand || ""}`);
564
884
  }
885
+ async function handleTemplate(args) {
886
+ const subcommand = args._[1];
887
+ if (subcommand === "create") {
888
+ const entityId = flagString(args, "entity-id") || flagString(args, "id");
889
+ if (!entityId)
890
+ return fail("INVALID_REQUEST", "template create requires --entity-id.");
891
+ return rpcEval(args, templateCreateSnippet(), {
892
+ entityId,
893
+ name: flagString(args, "name") || null,
894
+ folder: flagString(args, "folder") || null,
895
+ folderId: flagString(args, "folder-id") || null,
896
+ preload: !flagBool(args, "no-preload"),
897
+ }, 60000);
898
+ }
899
+ if (subcommand === "instantiate") {
900
+ const ids = flagList(args, "id");
901
+ const id = flagString(args, "id");
902
+ if (!ids.length && !id)
903
+ return fail("INVALID_REQUEST", "template instantiate requires --id.");
904
+ return rpcEval(args, assetInstantiateTemplateSnippet(), {
905
+ ids: ids,
906
+ id: id || null,
907
+ }, 60000);
908
+ }
909
+ return fail("UNKNOWN_COMMAND", `Unknown template command: ${subcommand || ""}`);
910
+ }
565
911
  async function handleScript(args) {
566
912
  const subcommand = args._[1];
913
+ if (subcommand === "upsert") {
914
+ const filename = flagString(args, "filename") || (flagString(args, "file") ? basename(flagString(args, "file") || "") : undefined);
915
+ const file = flagString(args, "file");
916
+ if (!filename || !file) {
917
+ return fail("INVALID_REQUEST", "script upsert requires --filename and --file.");
918
+ }
919
+ return rpcEval(args, scriptUpsertSnippet(), {
920
+ filename,
921
+ text: await readFile(file, "utf8"),
922
+ folder: flagString(args, "folder") || null,
923
+ folderId: flagString(args, "folder-id") || null,
924
+ preload: !flagBool(args, "no-preload"),
925
+ parse: flagBool(args, "parse"),
926
+ }, 60000);
927
+ }
567
928
  if (subcommand === "create") {
568
929
  const filename = flagString(args, "filename") || (flagString(args, "file") ? basename(flagString(args, "file") || "") : undefined);
569
930
  const file = flagString(args, "file");
@@ -597,8 +958,74 @@ async function handleScript(args) {
597
958
  }
598
959
  return fail("UNKNOWN_COMMAND", `Unknown script command: ${subcommand || ""}`);
599
960
  }
961
+ async function handleScene(args) {
962
+ const subcommand = args._[1];
963
+ if (subcommand === "settings" && (args._[2] || "get") === "get") {
964
+ return rpcEval(args, sceneSettingsGetSnippet());
965
+ }
966
+ if (subcommand === "settings" && args._[2] === "patch") {
967
+ const data = (await readJsonFlag(args, "json")) ?? {};
968
+ const sets = parseSets(flagList(args, "set"));
969
+ if (!Object.keys(objectJson(data, "scene settings")).length && !sets.length) {
970
+ return fail("INVALID_REQUEST", "scene settings patch requires --json <file> or --set path=value.");
971
+ }
972
+ return rpcEval(args, sceneSettingsPatchSnippet(), {
973
+ settings: objectJson(data, "scene settings"),
974
+ sets,
975
+ });
976
+ }
977
+ return fail("UNKNOWN_COMMAND", `Unknown scene command: ${[subcommand, args._[2]].filter(Boolean).join(" ")}`);
978
+ }
979
+ async function handleStore(args) {
980
+ const subcommand = args._[1] || "search";
981
+ if (subcommand === "search") {
982
+ const search = flagString(args, "search") || flagString(args, "q");
983
+ if (!search)
984
+ return fail("INVALID_REQUEST", "store search requires --search.");
985
+ return rpcEval(args, storeSearchSnippet(), {
986
+ search,
987
+ order: flagString(args, "order") || null,
988
+ skip: Number(flagString(args, "skip", "0")),
989
+ limit: Number(flagString(args, "limit", "20")),
990
+ }, 30000);
991
+ }
992
+ if (subcommand === "get") {
993
+ const id = flagString(args, "id");
994
+ if (!id)
995
+ return fail("INVALID_REQUEST", "store get requires --id.");
996
+ return rpcEval(args, storeGetSnippet(), { id }, 30000);
997
+ }
998
+ if (subcommand === "download") {
999
+ const id = flagString(args, "id");
1000
+ const name = flagString(args, "name");
1001
+ const license = await readJsonFlag(args, "license-json");
1002
+ if (!id || !name || license === undefined) {
1003
+ return fail("INVALID_REQUEST", "store download requires --id, --name, and --license-json.");
1004
+ }
1005
+ return rpcEval(args, storeDownloadSnippet(), {
1006
+ id,
1007
+ name,
1008
+ license: objectJson(license, "license"),
1009
+ folderId: flagString(args, "folder-id") || null,
1010
+ }, 120000);
1011
+ }
1012
+ return fail("UNKNOWN_COMMAND", `Unknown store command: ${subcommand}`);
1013
+ }
600
1014
  async function handleViewport(args) {
601
1015
  const subcommand = args._[1];
1016
+ if (subcommand === "focus") {
1017
+ const ids = flagList(args, "id");
1018
+ const id = flagString(args, "id");
1019
+ if (!ids.length && !id)
1020
+ return fail("INVALID_REQUEST", "viewport focus requires --id.");
1021
+ return rpcCall(args, "bridge:focusViewport", {
1022
+ ids: ids,
1023
+ id: id || null,
1024
+ view: flagString(args, "view") || null,
1025
+ yaw: flagString(args, "yaw") === undefined ? null : Number(flagString(args, "yaw")),
1026
+ pitch: flagString(args, "pitch") === undefined ? null : Number(flagString(args, "pitch")),
1027
+ });
1028
+ }
602
1029
  if (subcommand !== "capture") {
603
1030
  return fail("UNKNOWN_COMMAND", `Unknown viewport command: ${subcommand || ""}`);
604
1031
  }
@@ -622,27 +1049,154 @@ async function handleViewport(args) {
622
1049
  }
623
1050
  return raw;
624
1051
  }
625
- function usage() {
626
- return ok({
627
- usage: [
1052
+ async function handleLogs(args) {
1053
+ const subcommand = args._[1] || "get";
1054
+ if (subcommand === "get" || subcommand === "list") {
1055
+ return listEnvelope(await rpcCall(args, "bridge:getLogs", {
1056
+ level: flagString(args, "level") || null,
1057
+ limit: Number(flagString(args, "limit", "100")),
1058
+ offset: flagString(args, "offset") === undefined ? null : Number(flagString(args, "offset")),
1059
+ since: flagString(args, "since") || null,
1060
+ }));
1061
+ }
1062
+ if (subcommand === "clear") {
1063
+ return rpcCall(args, "bridge:clearLogs");
1064
+ }
1065
+ return fail("UNKNOWN_COMMAND", `Unknown logs command: ${subcommand}`);
1066
+ }
1067
+ function help(group = "overview") {
1068
+ const groups = {
1069
+ overview: [
1070
+ "pcbridge help core",
1071
+ "pcbridge help frontend",
1072
+ "pcbridge help entity",
1073
+ "pcbridge help asset",
1074
+ "pcbridge help material",
1075
+ "pcbridge help template",
1076
+ "pcbridge help script",
1077
+ "pcbridge help scene",
1078
+ "pcbridge help store",
1079
+ "pcbridge help viewport",
1080
+ "pcbridge help launch",
1081
+ "pcbridge help logs",
1082
+ "pcbridge help eval",
1083
+ ],
1084
+ core: [
628
1085
  "pcbridge doctor",
629
1086
  "pcbridge install-extension",
630
1087
  "pcbridge install-skill --agent codex|claude|cursor|windsurf|all",
631
1088
  "pcbridge daemon start",
632
1089
  "pcbridge daemon status",
633
1090
  "pcbridge targets",
634
- "pcbridge eval --target current --code \"return location.href\"",
635
- "pcbridge entity list --target current",
636
- "pcbridge asset list --target current --type script",
637
- "pcbridge asset upload --target current --file ./texture.png --folder \"AI Agent Bridge/Textures\"",
638
- "pcbridge material create --target current --name Mat --diffuse-map <asset_id>",
639
- "pcbridge script create --target current --filename controller.js --file ./controller.js",
1091
+ "pcbridge version",
1092
+ ],
1093
+ frontend: [
1094
+ "pcbridge frontend install [latest|playcanvas-editor-v<version>-r<revision>] [--no-activate]",
1095
+ "pcbridge frontend update",
1096
+ "pcbridge frontend status",
1097
+ "pcbridge frontend list",
1098
+ "pcbridge frontend use playcanvas-editor-v<version>-r<revision>",
1099
+ "pcbridge frontend remove playcanvas-editor-v<version>-r<revision>",
1100
+ "The active frontend is served from http://localhost:3487 while the daemon is running.",
1101
+ ],
1102
+ entity: [
1103
+ "pcbridge entity list --target current --limit 50 [--name Player] [--component render] [--tag enemy] [--full]",
1104
+ "pcbridge entity get --target current --id <resource_id> [--full]",
1105
+ "pcbridge entity create --target current --json ./entity.json",
1106
+ "pcbridge entity create-many --target current --json ./entities.json",
1107
+ "pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'",
1108
+ "pcbridge entity patch-many --target current --json ./edits.json",
1109
+ "pcbridge entity duplicate --target current --id <resource_id>",
1110
+ "pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id> [--index 0] [--no-preserve-transform]",
1111
+ "pcbridge entity add-component --target current --id <resource_id> --component render --data '{\"type\":\"box\"}'",
1112
+ "pcbridge entity add-components --target current --id <resource_id> --json ./components.json",
1113
+ "pcbridge entity remove-component --target current --id <resource_id> --component render",
640
1114
  "pcbridge entity set-material --target current --id <resource_id> --material-id <asset_id>",
641
- "pcbridge entity add-script --target current --id <resource_id> --script-name controller",
642
- "pcbridge viewport capture --target current --out ./tmp/viewport.png",
1115
+ "pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes-json ./attrs.json",
1116
+ "pcbridge entity delete --target current --id <resource_id>",
1117
+ ],
1118
+ asset: [
1119
+ "pcbridge asset list --target current [--type script] [--name controller] [--tag ui] [--limit 50] [--full]",
1120
+ "pcbridge asset get --target current --id <asset_id> [--full]",
1121
+ "pcbridge asset create --target current --json ./assets.json",
1122
+ "pcbridge asset folder ensure --target current --path \"AI Agent Bridge/Task/Textures\"",
1123
+ "pcbridge asset upload --target current --file ./texture.png --folder \"AI Agent Bridge/Task/Textures\"",
1124
+ "pcbridge asset upload-many --target current --json ./upload-manifest.json",
1125
+ "pcbridge asset instantiate --target current --id <template_asset_id>",
1126
+ "pcbridge asset delete --target current --id <asset_id>",
643
1127
  ],
1128
+ material: [
1129
+ "pcbridge material create --target current --name Mat --diffuse-map <texture_asset_id>",
1130
+ "pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'",
1131
+ "pcbridge material patch --target current --asset-id <asset_id> --json ./material-data.json",
1132
+ "pcbridge material set-diffuse --target current --asset-id <asset_id> --color '[1,0,0]'",
1133
+ ],
1134
+ template: [
1135
+ "pcbridge template create --target current --entity-id <resource_id> --name TemplateName --folder \"AI Agent Bridge/Task/Templates\"",
1136
+ "pcbridge template instantiate --target current --id <template_asset_id>",
1137
+ ],
1138
+ script: [
1139
+ "pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder \"AI Agent Bridge/Task/Scripts\" [--parse]",
1140
+ "pcbridge script create --target current --filename controller.js --file ./controller.js",
1141
+ "pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js",
1142
+ "pcbridge script parse --target current --asset-id <asset_id>",
1143
+ ],
1144
+ scene: [
1145
+ "pcbridge scene settings get --target current",
1146
+ "pcbridge scene settings patch --target current --json ./scene-settings.json",
1147
+ "pcbridge scene settings patch --target current --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
1148
+ ],
1149
+ store: [
1150
+ "pcbridge store search --target current --search vehicle --limit 20",
1151
+ "pcbridge store get --target current --id <store_asset_id>",
1152
+ "pcbridge store download --target current --id <store_asset_id> --name AssetName --license-json ./license.json",
1153
+ ],
1154
+ viewport: [
1155
+ "pcbridge viewport capture --target current --out ./tmp/viewport.png [--format png|webp]",
1156
+ "pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png [--format png|webp]",
1157
+ "pcbridge viewport focus --target current --id <resource_id> [--view perspective|top|bottom|front|back|left|right]",
1158
+ ],
1159
+ launch: [
1160
+ "pcbridge targets",
1161
+ "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }\"",
1162
+ "pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png [--format png|webp]",
1163
+ "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1164
+ "pcbridge logs clear --target launch:<sceneId>",
1165
+ "Use --target tab:<id> when multiple Launch tabs are open for the same scene.",
1166
+ ],
1167
+ logs: [
1168
+ "pcbridge logs get --target current [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1169
+ "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1170
+ "pcbridge logs clear --target current",
1171
+ "pcbridge logs clear --target launch:<sceneId>",
1172
+ ],
1173
+ log: [
1174
+ "pcbridge logs get --target current [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1175
+ "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1176
+ "pcbridge logs clear --target current",
1177
+ "pcbridge logs clear --target launch:<sceneId>",
1178
+ ],
1179
+ eval: [
1180
+ "Use eval for custom Editor/Engine workflows, PlayCanvas Launch debugging, large multi-step scene edits, exploratory API inspection, and operations not yet structured.",
1181
+ "pcbridge eval --target current --code \"return { href: location.href, hasEditor: !!editor }\"",
1182
+ "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }\"",
1183
+ "pcbridge eval --target current --file ./task.js",
1184
+ "pcbridge eval --target current --file ./task.js --args-json ./task-args.json",
1185
+ "pcbridge eval --target current --stdin",
1186
+ ],
1187
+ };
1188
+ const commands = groups[group];
1189
+ if (!commands) {
1190
+ return fail("UNKNOWN_HELP_TOPIC", `Unknown help topic: ${group}.`, undefined, Object.keys(groups));
1191
+ }
1192
+ return ok({
1193
+ topic: group,
1194
+ commands,
644
1195
  });
645
1196
  }
1197
+ function usage() {
1198
+ return help("overview");
1199
+ }
646
1200
  async function main() {
647
1201
  const args = parseArgs(process.argv.slice(2));
648
1202
  const command = args._[0] || "help";
@@ -651,8 +1205,11 @@ async function main() {
651
1205
  return;
652
1206
  }
653
1207
  try {
654
- if (command === "help" || command === "--help" || command === "-h") {
655
- print(usage());
1208
+ if (command !== "help" && args._[1] === "help") {
1209
+ print(help(command));
1210
+ }
1211
+ else if (command === "help" || command === "--help" || command === "-h") {
1212
+ print(help(args._[1] || "overview"));
656
1213
  }
657
1214
  else if (command === "doctor") {
658
1215
  print(await doctor());
@@ -663,11 +1220,15 @@ async function main() {
663
1220
  else if (command === "install-skill") {
664
1221
  print(await installSkill(args));
665
1222
  }
1223
+ else if (command === "frontend") {
1224
+ print(await handleFrontend(args));
1225
+ }
666
1226
  else if (command === "targets") {
667
1227
  print(await fetchDaemon("/targets"));
668
1228
  }
669
1229
  else if (command === "eval") {
670
- print(await rpcEval(args, await readCode(args)));
1230
+ const commandArgs = await readJsonFlag(args, "args-json");
1231
+ print(await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args")));
671
1232
  }
672
1233
  else if (command === "entity") {
673
1234
  print(await handleEntity(args));
@@ -678,12 +1239,24 @@ async function main() {
678
1239
  else if (command === "material") {
679
1240
  print(await handleMaterial(args));
680
1241
  }
1242
+ else if (command === "template") {
1243
+ print(await handleTemplate(args));
1244
+ }
681
1245
  else if (command === "script") {
682
1246
  print(await handleScript(args));
683
1247
  }
1248
+ else if (command === "scene") {
1249
+ print(await handleScene(args));
1250
+ }
1251
+ else if (command === "store") {
1252
+ print(await handleStore(args));
1253
+ }
684
1254
  else if (command === "viewport") {
685
1255
  print(await handleViewport(args));
686
1256
  }
1257
+ else if (command === "logs" || command === "log") {
1258
+ print(await handleLogs(args));
1259
+ }
687
1260
  else if (command === "version" || command === "--version" || command === "-v") {
688
1261
  print(ok({ version: VERSION }));
689
1262
  }