playcanvas-agent-bridge-cli 0.6.1 → 0.7.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.
Files changed (42) hide show
  1. package/README.md +148 -31
  2. package/README.zh-CN.md +137 -33
  3. package/dist/cli.js +514 -95
  4. package/dist/config.js +23 -1
  5. package/dist/daemon/server.js +336 -28
  6. package/dist/daemon/target-registry.js +3 -0
  7. package/dist/plugins/host.js +260 -0
  8. package/dist/plugins/store.js +567 -0
  9. package/dist/processing/manager.js +265 -0
  10. package/dist/processing/tools.js +97 -0
  11. package/dist/snippets.js +27 -0
  12. package/dist/updates.js +475 -0
  13. package/dist/workspace/json-sync.js +821 -0
  14. package/dist/workspace/manager.js +1973 -326
  15. package/extension/icons/icon-128.png +0 -0
  16. package/extension/icons/icon-16.png +0 -0
  17. package/extension/icons/icon-256.png +0 -0
  18. package/extension/icons/icon-32.png +0 -0
  19. package/extension/icons/icon-48.png +0 -0
  20. package/extension/isolated.js +59 -2
  21. package/extension/main.js +770 -275
  22. package/extension/manifest.json +60 -10
  23. package/extension/popup.html +115 -3
  24. package/extension/popup.js +398 -14
  25. package/extension/service-worker.js +221 -4
  26. package/package.json +18 -18
  27. package/plugins/index.json +14 -0
  28. package/plugins/tinyapp-builder/node/builder.js +589 -0
  29. package/plugins/tinyapp-builder/node/index.js +30 -0
  30. package/plugins/tinyapp-builder/package.json +13 -0
  31. package/plugins/tinyapp-builder/page/editor.js +249 -0
  32. package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
  33. package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
  34. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +99 -43
  35. package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
  36. package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
  37. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +89 -62
  38. package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
  39. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +69 -33
  40. package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
  41. package/skills/windsurf/playcanvas-agent-bridge-cli.md +68 -33
  42. package/dist/builder/manager.js +0 -564
package/dist/cli.js CHANGED
@@ -1,6 +1,7 @@
1
- #!/usr/bin/env node
1
+ #!/usr/bin/env bun
2
+ import { activeTools, installTools, TOOLS_ROOT } from "./processing/tools.js";
2
3
  import { spawn } from "node:child_process";
3
- import { realpathSync } from "node:fs";
4
+ import { existsSync, realpathSync } from "node:fs";
4
5
  import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
5
6
  import { createConnection } from "node:net";
6
7
  import { homedir } from "node:os";
@@ -9,8 +10,10 @@ import { fileURLToPath } from "node:url";
9
10
  import { CONFIG_DIR, DEFAULT_FRONTEND_PORT, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
10
11
  import { createDaemonServer } from "./daemon/server.js";
11
12
  import { FrontendError, getFrontendStatus, installFrontend, listFrontends, removeFrontend, useFrontend, } from "./frontend/store.js";
12
- 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, templateApplySnippet, templateCreateSnippet, templateOverridesSnippet, } from "./snippets.js";
13
+ 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, sceneManageSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateApplySnippet, templateCreateSnippet, templateOverridesSnippet, } from "./snippets.js";
13
14
  import { fail, ok } from "./shared/protocol.js";
15
+ import { parsePluginSource, PLUGIN_ID_PATTERN, PluginError, PluginStore, summarizePlugin, } from "./plugins/store.js";
16
+ import { compactUpdatesMeta, detectInstalledSkills, executeOneClickUpdate, formatHumanUpdateHint, getUpdateReport, recordInstalledSkills, } from "./updates.js";
14
17
  function parseArgs(argv) {
15
18
  const parsed = { _: [], flags: {} };
16
19
  for (let index = 0; index < argv.length; index += 1) {
@@ -89,7 +92,7 @@ export function diagnoseDaemonConnection(error, port = DEFAULT_PORT) {
89
92
  nextAction: "Retry from an execution context with local-loopback permission.",
90
93
  };
91
94
  }
92
- if (code === "ECONNREFUSED") {
95
+ if (code === "ECONNREFUSED" || code === "ConnectionRefused" || code === "FailedToOpenSocket") {
93
96
  return {
94
97
  code: "DAEMON_NOT_LISTENING",
95
98
  message: `No pcbridge daemon is listening on ${DEFAULT_HOST}:${port}.`,
@@ -285,6 +288,8 @@ function listEnvelope(raw) {
285
288
  }
286
289
  function inferAssetType(path) {
287
290
  const ext = extname(path).toLowerCase();
291
+ if ([".glb", ".fbx", ".obj"].includes(ext))
292
+ return "scene";
288
293
  if ([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tga"].includes(ext))
289
294
  return "texture";
290
295
  if ([".mp3", ".wav", ".ogg", ".m4a"].includes(ext))
@@ -381,18 +386,24 @@ async function uploadAsset(args, spec) {
381
386
  preload: spec.preload !== false,
382
387
  }, 120000);
383
388
  }
384
- async function doctor() {
389
+ function bunVersionSupported(version) {
390
+ const [major, minor] = version.split(".").map(Number);
391
+ return major > 1 || (major === 1 && minor >= 4);
392
+ }
393
+ async function doctor(args = { _: ["doctor"], flags: {} }) {
385
394
  const session = await readSessionIfExists();
386
395
  const checks = [];
387
396
  const nextActions = [];
388
- const major = Number(process.versions.node.split(".", 1)[0]);
397
+ const bunVersion = process.versions.bun;
389
398
  let daemonOk = false;
399
+ let daemonVersion = null;
390
400
  let connectedExtensionVersionsOk = true;
401
+ let connectedVersions = [];
391
402
  checks.push({
392
- name: "node",
393
- ok: major >= 20,
394
- version: process.version,
395
- message: major >= 20 ? "Node version is supported." : "Node 20 or newer is required.",
403
+ name: "bun",
404
+ ok: !!bunVersion && bunVersionSupported(bunVersion),
405
+ version: bunVersion || process.version,
406
+ message: bunVersion && bunVersionSupported(bunVersion) ? "Bun version is supported." : "Bun 1.4.0 or newer is required.",
396
407
  });
397
408
  if (!session) {
398
409
  nextActions.push("Run pcbridge install-extension to create a local session token.");
@@ -400,7 +411,7 @@ async function doctor() {
400
411
  try {
401
412
  const health = await fetchDaemon("/health");
402
413
  const daemonData = health.ok ? objectJson(health.data, "daemon health") : null;
403
- const daemonVersion = daemonData && typeof daemonData.version === "string"
414
+ daemonVersion = daemonData && typeof daemonData.version === "string"
404
415
  ? daemonData.version
405
416
  : null;
406
417
  daemonOk = health.ok && daemonVersion === VERSION;
@@ -481,9 +492,9 @@ async function doctor() {
481
492
  try {
482
493
  const targets = await fetchDaemon("/targets");
483
494
  if (targets.ok && Array.isArray(targets.data)) {
484
- const connectedVersions = targets.data
495
+ connectedVersions = targets.data
485
496
  .map((target) => (target && typeof target === "object" && !Array.isArray(target) ? target.extensionVersion : null))
486
- .filter(Boolean);
497
+ .filter((item) => typeof item === "string" && Boolean(item));
487
498
  const mismatched = connectedVersions.filter((version) => version !== VERSION);
488
499
  connectedExtensionVersionsOk = mismatched.length === 0;
489
500
  checks.push({
@@ -503,15 +514,45 @@ async function doctor() {
503
514
  catch {
504
515
  // Daemon reachability is already reported above.
505
516
  }
517
+ const refreshUpdates = flagBool(args, "refresh");
518
+ const updates = await getUpdateReport({
519
+ refresh: refreshUpdates,
520
+ allowNetwork: refreshUpdates,
521
+ daemonVersion,
522
+ connectedExtensionVersions: connectedVersions,
523
+ });
524
+ checks.push({
525
+ name: "updates",
526
+ ok: !updates.hasUpdates,
527
+ checkedAt: updates.checkedAt,
528
+ latestVersion: updates.core.latestVersion,
529
+ updateAvailable: updates.core.updateAvailable,
530
+ outdatedPlugins: updates.plugins
531
+ .filter((item) => item.updateAvailable)
532
+ .map((item) => ({
533
+ id: item.id,
534
+ currentVersion: item.currentVersion,
535
+ latestVersion: item.latestVersion,
536
+ compatible: item.compatible,
537
+ })),
538
+ message: updates.hasUpdates
539
+ ? formatHumanUpdateHint(updates)?.replace(/^\[pcbridge\]\s*/, "") || "Updates are available."
540
+ : "pcbridge and installed plugins are up to date.",
541
+ });
542
+ for (const action of updates.nextActions) {
543
+ if (!nextActions.includes(action))
544
+ nextActions.push(action);
545
+ }
506
546
  return ok({
507
547
  version: VERSION,
508
- healthy: major >= 20 &&
548
+ healthy: !!bunVersion && bunVersionSupported(bunVersion) &&
509
549
  daemonOk &&
510
550
  extensionExists &&
511
551
  generatedExtensionVersion === VERSION &&
512
552
  connectedExtensionVersionsOk,
513
553
  configDir: CONFIG_DIR,
514
554
  checks,
555
+ updates: updates,
515
556
  nextActions,
516
557
  });
517
558
  }
@@ -559,6 +600,7 @@ async function runDaemon(args, workspaceRoot, restarted) {
559
600
  port,
560
601
  token: session.token,
561
602
  workspaceRoot,
603
+ enableBackgroundUpdateCheck: process.env.PCBRIDGE_DISABLE_BACKGROUND_UPDATE_CHECK !== "1",
562
604
  log: (message) => daemonLog(args, message),
563
605
  });
564
606
  try {
@@ -595,6 +637,47 @@ async function runDaemon(args, workspaceRoot, restarted) {
595
637
  process.off("SIGINT", handleSigint);
596
638
  process.off("SIGTERM", handleSigterm);
597
639
  }
640
+ if (server.restartRequested) {
641
+ const cliEntry = process.env.PCBRIDGE_UPDATE_CLI_PATH ||
642
+ (process.argv[1] && existsSync(process.argv[1])
643
+ ? process.argv[1]
644
+ : fileURLToPath(import.meta.url));
645
+ const childArgs = [
646
+ cliEntry,
647
+ "daemon",
648
+ "start",
649
+ "--workspace",
650
+ workspaceRoot,
651
+ "--restarted",
652
+ ...(flagBool(args, "json") ? ["--json"] : []),
653
+ ];
654
+ const replacement = spawn(process.execPath, childArgs, {
655
+ cwd: workspaceRoot,
656
+ env: process.env,
657
+ stdio: "inherit",
658
+ });
659
+ const forwardSignal = (signal) => {
660
+ if (replacement.exitCode === null)
661
+ replacement.kill(signal);
662
+ };
663
+ const onInt = () => forwardSignal("SIGINT");
664
+ const onTerm = () => forwardSignal("SIGTERM");
665
+ process.on("SIGINT", onInt);
666
+ process.on("SIGTERM", onTerm);
667
+ await new Promise((resolveChild) => {
668
+ replacement.once("exit", (code) => {
669
+ if (code !== null && code !== 0)
670
+ process.exitCode = code;
671
+ resolveChild();
672
+ });
673
+ replacement.once("error", () => {
674
+ process.exitCode = 1;
675
+ resolveChild();
676
+ });
677
+ });
678
+ process.off("SIGINT", onInt);
679
+ process.off("SIGTERM", onTerm);
680
+ }
598
681
  }
599
682
  function isPortListening(port) {
600
683
  return new Promise((resolveListening) => {
@@ -696,7 +779,7 @@ async function daemon(args) {
696
779
  return;
697
780
  }
698
781
  }
699
- await runDaemon(args, workspaceRoot, subcommand === "restart");
782
+ await runDaemon(args, workspaceRoot, subcommand === "restart" || flagBool(args, "restarted"));
700
783
  }
701
784
  else if (subcommand === "stop") {
702
785
  print(await stopDaemon());
@@ -828,6 +911,38 @@ function openChromeExtensions() {
828
911
  }
829
912
  }
830
913
  async function installSkill(args) {
914
+ const root = await findPackageRoot();
915
+ const installed = [];
916
+ async function installOneTarget(targetItem) {
917
+ const { agent: item, customParent } = targetItem;
918
+ for (const skill of ["playcanvas-agent-bridge-cli", "pcbridge-plugin-authoring"]) {
919
+ if (item === "codex" || item === "claude") {
920
+ const parent = customParent || (item === "codex"
921
+ ? join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills")
922
+ : join(homedir(), ".claude", "skills"));
923
+ const target = join(parent, skill);
924
+ await copyDir(join(root, "skills", item, skill), target, { clean: true });
925
+ installed.push({ agent: item, path: target });
926
+ }
927
+ else {
928
+ const file = `${skill}.${item === "cursor" ? "mdc" : "md"}`;
929
+ const target = join(customParent || join(homedir(), `.${item}`, "rules"), file);
930
+ await mkdir(dirname(target), { recursive: true });
931
+ await writeFile(target, await readFile(join(root, "skills", item, file)));
932
+ installed.push({ agent: item, path: target });
933
+ }
934
+ }
935
+ }
936
+ if (flagBool(args, "refresh-installed")) {
937
+ const targets = await detectInstalledSkills();
938
+ for (const targetItem of targets) {
939
+ await installOneTarget(targetItem);
940
+ }
941
+ if (targets.length > 0) {
942
+ await recordInstalledSkills(targets).catch(() => undefined);
943
+ }
944
+ return ok(installed);
945
+ }
831
946
  const agent = flagString(args, "agent", "codex") || "codex";
832
947
  const supportedAgents = new Set(["codex", "claude", "cursor", "windsurf"]);
833
948
  if (agent !== "all" && !supportedAgents.has(agent)) {
@@ -842,37 +957,17 @@ async function installSkill(args) {
842
957
  return fail("INVALID_REQUEST", "install-skill --path requires one explicit agent, not --agent all.");
843
958
  }
844
959
  const customParent = customPath ? resolve(customPath) : null;
845
- const root = await findPackageRoot();
846
- const installed = [];
847
- const agents = agent === "all" ? ["codex", "claude", "cursor", "windsurf"] : [agent];
848
- for (const item of agents) {
849
- if (item === "codex") {
850
- const dest = customParent || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
851
- const source = join(root, "skills", "codex", "playcanvas-agent-bridge-cli");
852
- const target = join(dest, "playcanvas-agent-bridge-cli");
853
- await copyDir(source, target, { clean: true });
854
- installed.push({ agent: item, path: target });
855
- }
856
- else if (item === "claude") {
857
- const target = join(customParent || join(homedir(), ".claude", "skills"), "playcanvas-agent-bridge-cli");
858
- await copyDir(join(root, "skills", "claude", "playcanvas-agent-bridge-cli"), target, {
859
- clean: true,
860
- });
861
- installed.push({ agent: item, path: target });
862
- }
863
- else if (item === "cursor") {
864
- const target = join(customParent || join(homedir(), ".cursor", "rules"), "playcanvas-agent-bridge-cli.mdc");
865
- await mkdir(dirname(target), { recursive: true });
866
- await writeFile(target, await readFile(join(root, "skills", "cursor", "playcanvas-agent-bridge-cli.mdc")));
867
- installed.push({ agent: item, path: target });
868
- }
869
- else if (item === "windsurf") {
870
- const target = join(customParent || join(homedir(), ".windsurf", "rules"), "playcanvas-agent-bridge-cli.md");
871
- await mkdir(dirname(target), { recursive: true });
872
- await writeFile(target, await readFile(join(root, "skills", "windsurf", "playcanvas-agent-bridge-cli.md")));
873
- installed.push({ agent: item, path: target });
874
- }
960
+ const agents = (agent === "all"
961
+ ? ["codex", "claude", "cursor", "windsurf"]
962
+ : [agent]);
963
+ const targets = agents.map((item) => ({
964
+ agent: item,
965
+ customParent,
966
+ }));
967
+ for (const targetItem of targets) {
968
+ await installOneTarget(targetItem);
875
969
  }
970
+ await recordInstalledSkills(targets).catch(() => undefined);
876
971
  return ok(installed);
877
972
  }
878
973
  async function handleEntity(args) {
@@ -1341,6 +1436,15 @@ async function handleScript(args) {
1341
1436
  }
1342
1437
  async function handleScene(args) {
1343
1438
  const subcommand = args._[1];
1439
+ if (["list", "create", "open"].includes(subcommand)) {
1440
+ const name = flagString(args, "name");
1441
+ const id = flagString(args, "id");
1442
+ if (subcommand === "create" && !name)
1443
+ return fail("INVALID_REQUEST", "scene create requires --name.");
1444
+ if (subcommand === "open" && !id)
1445
+ return fail("INVALID_REQUEST", "scene open requires --id.");
1446
+ return rpcEval(args, sceneManageSnippet(), { action: subcommand, name: name || null, id: id || null }, 60000);
1447
+ }
1344
1448
  if (subcommand === "settings" && (args._[2] || "get") === "get") {
1345
1449
  return rpcEval(args, sceneSettingsGetSnippet());
1346
1450
  }
@@ -1551,9 +1655,24 @@ async function handleWorkspace(args) {
1551
1655
  rootDirectory: data.rootDirectory || null,
1552
1656
  projectDirectory: data.projectDirectory || null,
1553
1657
  assetsDirectory: data.assetsDirectory || null,
1658
+ scenesDirectory: data.scenesDirectory || null,
1554
1659
  tmpDirectory: data.tmpDirectory || null,
1555
1660
  });
1556
1661
  }
1662
+ if (subcommand === "settings") {
1663
+ const rawLimit = flagString(args, "eager-max-mb") || flagString(args, "limit-mb");
1664
+ if (!rawLimit) {
1665
+ return fetchDaemon("/workspace/settings");
1666
+ }
1667
+ const mb = Number(rawLimit);
1668
+ if (!Number.isFinite(mb) || mb < 1 || mb > 10) {
1669
+ return fail("INVALID_REQUEST", "workspace settings --eager-max-mb must be between 1 and 10.");
1670
+ }
1671
+ return fetchDaemon("/workspace/settings", {
1672
+ method: "POST",
1673
+ body: JSON.stringify({ eagerMaxMb: Math.round(mb) }),
1674
+ });
1675
+ }
1557
1676
  if (subcommand === "sync") {
1558
1677
  return fetchDaemon("/workspace/sync", {
1559
1678
  method: "POST",
@@ -1571,39 +1690,274 @@ async function handleWorkspace(args) {
1571
1690
  }
1572
1691
  return fail("UNKNOWN_COMMAND", `Unknown workspace command: ${subcommand}`);
1573
1692
  }
1574
- async function handleBuilder(args) {
1575
- const subcommand = args._[1] || "status";
1576
- if (subcommand === "start" || subcommand === "build") {
1577
- const templateAssetId = flagString(args, "asset") ||
1578
- flagString(args, "asset-id") ||
1579
- flagString(args, "id");
1580
- if (!templateAssetId) {
1581
- return fail("INVALID_REQUEST", "builder start requires --asset <templateAssetId>.");
1582
- }
1583
- return fetchDaemon("/builder/jobs", {
1693
+ async function handlePlugin(args) {
1694
+ const subcommand = args._[1] || "list";
1695
+ const id = args._[2];
1696
+ if (subcommand === "call") {
1697
+ const action = args._[3];
1698
+ if (!id || !action)
1699
+ return fail("INVALID_REQUEST", "plugin call requires <id> <action>.");
1700
+ const inline = flagString(args, "params");
1701
+ const params = inline === undefined ? await readJsonFlag(args, "params-json") : parseJsonValue(inline);
1702
+ const target = flagString(args, "target");
1703
+ return fetchDaemon(`/plugins/${id}/actions/${encodeURIComponent(action)}`, {
1584
1704
  method: "POST",
1585
1705
  body: JSON.stringify({
1586
- target: flagString(args, "target", "current") || "current",
1587
- templateAssetId,
1588
- suffix: flagString(args, "suffix") || "",
1589
- prefix: flagString(args, "prefix") || "",
1706
+ ...(target ? { target } : {}),
1707
+ params: objectJson(params, "plugin params"),
1590
1708
  }),
1591
1709
  });
1592
1710
  }
1593
- if (subcommand === "status") {
1594
- const jobId = flagString(args, "job") || flagString(args, "id");
1595
- if (!jobId)
1596
- return fail("INVALID_REQUEST", "builder status requires --job <jobId>.");
1597
- return fetchDaemon(`/builder/jobs/${encodeURIComponent(jobId)}`);
1711
+ // Management falls back to the on-disk registry so a plugin that breaks daemon startup can still be disabled.
1712
+ const store = new PluginStore(join(CONFIG_DIR, "plugins"));
1713
+ const manage = async (path, body, offline) => {
1714
+ try {
1715
+ return await fetchDaemon(path, body === null ? {} : { method: "POST", body: JSON.stringify(body) });
1716
+ }
1717
+ catch (error) {
1718
+ if (!(error instanceof DaemonConnectionError) || error.diagnosis.code !== "DAEMON_NOT_LISTENING")
1719
+ throw error;
1720
+ }
1721
+ try {
1722
+ return ok(await offline());
1723
+ }
1724
+ catch (error) {
1725
+ if (error instanceof PluginError)
1726
+ return fail(error.code, error.message);
1727
+ throw error;
1728
+ }
1729
+ };
1730
+ const summary = async (pluginId) => {
1731
+ const [plugin, catalog] = await Promise.all([
1732
+ store.get(pluginId),
1733
+ store.catalog(),
1734
+ ]);
1735
+ return summarizePlugin(plugin, catalog);
1736
+ };
1737
+ if (subcommand === "list") {
1738
+ const refresh = flagBool(args, "refresh");
1739
+ return manage(`/plugins${refresh ? "?refresh=1" : ""}`, null, async () => ({
1740
+ plugins: await store.summaries({ refresh }),
1741
+ available: await store.available({ refresh }),
1742
+ }));
1598
1743
  }
1599
- return fail("UNKNOWN_COMMAND", `Unknown builder command: ${subcommand}`);
1744
+ if (subcommand === "add") {
1745
+ if (!id) {
1746
+ return fail("INVALID_REQUEST", "plugin add requires an official name, github:owner/repo[/subdir][#ref], or a directory.");
1747
+ }
1748
+ const source = id.startsWith("github:") || PLUGIN_ID_PATTERN.test(id) ? id : resolve(id);
1749
+ const link = flagBool(args, "link");
1750
+ return manage("/plugins/add", { source, link }, async () => summarizePlugin(await store.add(parsePluginSource(source, link)), await store.catalog()));
1751
+ }
1752
+ if (subcommand === "update" && (flagBool(args, "all") || id === "all")) {
1753
+ return manage("/plugins/update-all", {}, async () => (await store.updateAll()));
1754
+ }
1755
+ if (!id)
1756
+ return fail("INVALID_REQUEST", `plugin ${subcommand} requires a plugin id.`);
1757
+ if (subcommand === "info") {
1758
+ const listed = await handlePlugin({ _: ["plugin", "list"], flags: {} });
1759
+ if (!listed.ok)
1760
+ return listed;
1761
+ const plugin = objectJson(listed.data, "plugin list").plugins
1762
+ .find((item) => item.id === id);
1763
+ return plugin ? ok(plugin) : fail("PLUGIN_NOT_FOUND", `Plugin ${id} is not installed.`);
1764
+ }
1765
+ if (subcommand === "enable" || subcommand === "disable") {
1766
+ return manage(`/plugins/${id}/${subcommand}`, {}, async () => {
1767
+ await store.setEnabled(id, subcommand === "enable");
1768
+ return summary(id);
1769
+ });
1770
+ }
1771
+ if (subcommand === "remove") {
1772
+ return manage(`/plugins/${id}/remove`, {}, async () => {
1773
+ await store.remove(id);
1774
+ return { id, removed: true };
1775
+ });
1776
+ }
1777
+ if (subcommand === "update") {
1778
+ return manage(`/plugins/${id}/update`, {}, async () => {
1779
+ const { previousVersion } = await store.update(id);
1780
+ return { ...await summary(id), previousVersion };
1781
+ });
1782
+ }
1783
+ if (subcommand === "reload") {
1784
+ return fetchDaemon(`/plugins/${id}/reload`, { method: "POST", body: "{}" });
1785
+ }
1786
+ return fail("UNKNOWN_COMMAND", `Unknown plugin command: ${subcommand}`);
1787
+ }
1788
+ async function handleProcessing(args) {
1789
+ const action = args._[1] || "status";
1790
+ if (action === "install") {
1791
+ const source = args._[2];
1792
+ if (!source)
1793
+ return fail("INVALID_REQUEST", "processing install requires a trusted release manifest path or HTTPS URL.");
1794
+ return ok(await installTools(source));
1795
+ }
1796
+ if (action === "enable" || action === "disable") {
1797
+ await mkdir(TOOLS_ROOT, { recursive: true });
1798
+ if (action === "enable")
1799
+ await activeTools();
1800
+ const memoryMb = Number(flagString(args, "memory-mb", "1024"));
1801
+ const timeoutMs = Number(flagString(args, "timeout-ms", "600000"));
1802
+ if (!Number.isInteger(memoryMb) || memoryMb < 64 || memoryMb > 1024 || !Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
1803
+ return fail("INVALID_REQUEST", "memory-mb must be 64..1024; timeout-ms must be 1000..600000.");
1804
+ const settings = { enabled: action === "enable", memoryBytes: memoryMb * 1024 * 1024, timeoutMs };
1805
+ await writeFile(join(TOOLS_ROOT, "settings.json"), JSON.stringify(settings));
1806
+ return ok(settings);
1807
+ }
1808
+ if (action === "status")
1809
+ return fetchDaemon("/processing/capabilities", { method: "POST", body: JSON.stringify({ target: flagString(args, "target", "current") }) });
1810
+ return fail("UNKNOWN_COMMAND", `Unknown processing command: ${action}`);
1811
+ }
1812
+ async function handleImportJob(args) {
1813
+ const action = args._[1] || "list";
1814
+ const id = flagString(args, "job");
1815
+ if (["status", "cancel", "retry", "wait"].includes(action) && !id)
1816
+ return fail("INVALID_REQUEST", "--job is required.");
1817
+ const params = { action, jobId: id || null };
1818
+ if (action === "submit") {
1819
+ const assetId = flagString(args, "asset");
1820
+ const kind = flagString(args, "kind", "model");
1821
+ if (!assetId || !["model", "texture"].includes(kind || ""))
1822
+ return fail("INVALID_REQUEST", "submit requires --asset and --kind model|texture.");
1823
+ params.assetId = assetId;
1824
+ params.kind = kind || "model";
1825
+ params.options = objectJson(await readJsonFlag(args, "json"), "import options");
1826
+ }
1827
+ if (action !== "wait")
1828
+ return rpcCall(args, "bridge:importJob", params);
1829
+ const timeout = readTimeoutMs(args, 120000);
1830
+ if (timeout === null)
1831
+ return invalidTimeoutEnvelope();
1832
+ const deadline = Date.now() + timeout;
1833
+ while (Date.now() < deadline) {
1834
+ const result = await rpcCall(args, "bridge:importJob", { action: "status", jobId: id }, 15000, false);
1835
+ if (!result.ok)
1836
+ return result;
1837
+ const job = result.data;
1838
+ if (["failed", "cancelled"].includes(String(job.status)))
1839
+ return fail("IMPORT_" + String(job.status).toUpperCase(), String(job.error || job.status), undefined, job);
1840
+ if (job.status === "complete") {
1841
+ let workspace = { state: "not-requested" };
1842
+ if (flagBool(args, "sync-workspace")) {
1843
+ const synced = await fetchDaemon("/workspace/sync", { method: "POST", body: JSON.stringify({ target: flagString(args, "target", "current") }) });
1844
+ if (!synced.ok)
1845
+ return synced;
1846
+ workspace = synced.data;
1847
+ }
1848
+ return ok({ job, published: true, workspace });
1849
+ }
1850
+ await new Promise(resolve => setTimeout(resolve, 500));
1851
+ }
1852
+ return fail("IMPORT_WAIT_TIMEOUT", "Task is still pending; query the same job before submitting another.");
1853
+ }
1854
+ async function waitForDaemonHealth(timeoutMs = 10000) {
1855
+ const deadline = Date.now() + timeoutMs;
1856
+ await new Promise((resolveWait) => setTimeout(resolveWait, 80));
1857
+ while (Date.now() < deadline) {
1858
+ try {
1859
+ const health = await fetchDaemon("/health");
1860
+ if (health.ok)
1861
+ return true;
1862
+ }
1863
+ catch {
1864
+ // Keep waiting while the replacement daemon starts up.
1865
+ }
1866
+ await new Promise((resolveWait) => setTimeout(resolveWait, 60));
1867
+ }
1868
+ return false;
1869
+ }
1870
+ async function handleUpdate(args) {
1871
+ const subcommand = args._[1] || (flagBool(args, "check") ? "check" : "apply");
1872
+ let daemonVersion = null;
1873
+ let connectedVersions = [];
1874
+ let daemonReachable = false;
1875
+ try {
1876
+ const health = await fetchDaemon("/health");
1877
+ if (health.ok) {
1878
+ daemonReachable = true;
1879
+ const data = objectJson(health.data, "daemon health");
1880
+ if (typeof data.version === "string")
1881
+ daemonVersion = data.version;
1882
+ }
1883
+ const targets = await fetchDaemon("/targets");
1884
+ if (targets.ok && Array.isArray(targets.data)) {
1885
+ connectedVersions = targets.data
1886
+ .map((t) => (t && typeof t === "object" && !Array.isArray(t) ? t.extensionVersion : null))
1887
+ .filter((v) => typeof v === "string" && Boolean(v));
1888
+ }
1889
+ }
1890
+ catch {
1891
+ // Offline daemon is handled below.
1892
+ }
1893
+ if (subcommand === "status" || subcommand === "check") {
1894
+ const refresh = subcommand === "check" || flagBool(args, "refresh") || flagBool(args, "check");
1895
+ if (daemonReachable) {
1896
+ try {
1897
+ return await fetchDaemon(`/updates?refresh=${refresh ? "1" : "0"}`);
1898
+ }
1899
+ catch {
1900
+ // Fall back to direct report below.
1901
+ }
1902
+ }
1903
+ const report = await getUpdateReport({
1904
+ refresh,
1905
+ allowNetwork: true,
1906
+ daemonVersion,
1907
+ connectedExtensionVersions: connectedVersions,
1908
+ });
1909
+ return ok(report);
1910
+ }
1911
+ if (subcommand === "apply") {
1912
+ try {
1913
+ const result = await executeOneClickUpdate({
1914
+ includePlugins: flagBool(args, "plugins"),
1915
+ reloadTabs: !flagBool(args, "no-reload-tabs"),
1916
+ daemonVersion,
1917
+ connectedExtensionVersions: connectedVersions,
1918
+ reloadConnectedExtension: daemonReachable
1919
+ ? async (reloadTabs) => {
1920
+ const res = await fetchDaemon("/extension/reload", {
1921
+ method: "POST",
1922
+ body: JSON.stringify({ reloadTabs }),
1923
+ });
1924
+ return res.ok && Boolean(res.data?.reloaded);
1925
+ }
1926
+ : undefined,
1927
+ restartDaemon: daemonReachable
1928
+ ? async () => {
1929
+ const res = await fetchDaemon("/restart", { method: "POST" });
1930
+ if (!res.ok)
1931
+ return false;
1932
+ return waitForDaemonHealth(10000);
1933
+ }
1934
+ : undefined,
1935
+ updatePlugins: daemonReachable
1936
+ ? async () => {
1937
+ const res = await fetchDaemon("/plugins/update-all", { method: "POST" });
1938
+ if (!res.ok)
1939
+ throw new PluginError(res.error.code, res.error.message);
1940
+ return res.data;
1941
+ }
1942
+ : undefined,
1943
+ });
1944
+ return ok(result);
1945
+ }
1946
+ catch (error) {
1947
+ const code = error.code;
1948
+ return fail(typeof code === "string" ? code : "UPDATE_FAILED", error instanceof Error ? error.message : String(error));
1949
+ }
1950
+ }
1951
+ return fail("UNKNOWN_COMMAND", `Unknown update command: ${subcommand}`);
1600
1952
  }
1601
1953
  function help(group = "overview") {
1602
1954
  const groups = {
1603
1955
  overview: [
1604
1956
  "pcbridge help core",
1605
1957
  "pcbridge help workspace",
1606
- "pcbridge help builder",
1958
+ "pcbridge help plugin",
1959
+ "pcbridge help processing",
1960
+ "pcbridge help import",
1607
1961
  "pcbridge help frontend",
1608
1962
  "pcbridge help target",
1609
1963
  "pcbridge help entity",
@@ -1620,6 +1974,8 @@ function help(group = "overview") {
1620
1974
  ],
1621
1975
  core: [
1622
1976
  "pcbridge doctor",
1977
+ "pcbridge update [--check] [--plugins] [--no-reload-tabs]",
1978
+ "pcbridge update status [--refresh]",
1623
1979
  "pcbridge install-extension",
1624
1980
  "pcbridge install-skill --agent codex|claude|cursor|windsurf|all [--path <parent_directory>]",
1625
1981
  "--path is allowed only with one agent and appends the standard skill/rule name.",
@@ -1639,15 +1995,37 @@ function help(group = "overview") {
1639
1995
  workspace: [
1640
1996
  "pcbridge workspace status --target editor:<sceneId>",
1641
1997
  "pcbridge workspace path --target editor:<sceneId>",
1998
+ "pcbridge workspace settings [--eager-max-mb <1..10>]",
1642
1999
  "pcbridge workspace sync --target editor:<sceneId>",
1643
2000
  "pcbridge workspace pull --target editor:<sceneId> --asset <assetId>",
1644
2001
  "daemon start/restart uses --workspace when provided, otherwise the current directory.",
1645
2002
  ],
1646
- builder: [
1647
- "pcbridge builder start --target editor:<sceneId> --asset <template_asset_id> [--suffix '-${time}'] [--prefix assets]",
1648
- "pcbridge builder status --job <build_job_id>",
1649
- "Template assets also show a pcbridge Tiny Builder panel in the PlayCanvas Editor.",
1650
- "S3 settings come from the project .env, then the workspace-root .env; files upload directly without a ZIP.",
2003
+ processing: [
2004
+ "pcbridge processing install <trusted-release.json-path-or-https-url>",
2005
+ "pcbridge processing enable [--memory-mb 1024] [--timeout-ms 600000]",
2006
+ "pcbridge processing disable",
2007
+ "pcbridge processing status --target editor:<sceneId>",
2008
+ "Selfhost only. Tools are opt-in; unavailable local compute falls back to server.",
2009
+ ],
2010
+ import: [
2011
+ "pcbridge import submit --asset <source_asset_id> --kind model|texture [--json options.json] --target editor:<sceneId>",
2012
+ "pcbridge import list --target editor:<sceneId>",
2013
+ "pcbridge import status|cancel|retry --job <id> --target editor:<sceneId>",
2014
+ "pcbridge import wait --job <id> [--timeout-ms 120000] [--sync-workspace] --target editor:<sceneId>",
2015
+ "Complete means server publication. --sync-workspace separately waits for local metadata synchronization.",
2016
+ "New files use the existing asset upload command; model uploads create the same import jobs.",
2017
+ ],
2018
+ plugin: [
2019
+ "pcbridge plugin list [--refresh]",
2020
+ "pcbridge plugin info <id>",
2021
+ "pcbridge plugin add <official-name> | github:<owner>/<repo>[/<subdir>][#<ref>] | <directory> [--link]",
2022
+ "pcbridge plugin enable|disable|remove|update <id>",
2023
+ "pcbridge plugin update --all",
2024
+ "pcbridge plugin reload <id>",
2025
+ "pcbridge plugin call <id> <action> [--target editor:<sceneId>] [--params '<json>' | --params-json ./params.json]",
2026
+ "list shows installed plugins, their actions, activation errors, and official plugins available to add.",
2027
+ "--link uses a local directory in place for development; reload re-reads its files without reinstalling.",
2028
+ "Plugins run with full local and page access. Add only plugins you trust.",
1651
2029
  ],
1652
2030
  frontend: [
1653
2031
  "pcbridge frontend install [latest|playcanvas-editor-v<version>-r<revision>] [--no-activate]",
@@ -1709,6 +2087,9 @@ function help(group = "overview") {
1709
2087
  ],
1710
2088
  scene: [
1711
2089
  "pcbridge scene settings get --target editor:<sceneId>",
2090
+ "pcbridge scene list --target editor:<sceneId>",
2091
+ "pcbridge scene create --name <name> --target editor:<sceneId>",
2092
+ "pcbridge scene open --id <sceneId> --target editor:<sceneId>",
1712
2093
  "pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json",
1713
2094
  "pcbridge scene settings patch --target editor:<sceneId> --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
1714
2095
  ],
@@ -1778,77 +2159,115 @@ async function main() {
1778
2159
  return;
1779
2160
  }
1780
2161
  try {
2162
+ let envelope;
1781
2163
  if (command !== "help" && args._[1] === "help") {
1782
- print(help(command));
2164
+ envelope = help(command);
1783
2165
  }
1784
2166
  else if (command === "help" || command === "--help" || command === "-h") {
1785
- print(help(args._[1] || "overview"));
2167
+ envelope = help(args._[1] || "overview");
1786
2168
  }
1787
2169
  else if (command === "doctor") {
1788
- print(await doctor());
2170
+ envelope = await doctor(args);
2171
+ }
2172
+ else if (command === "update" || command === "updates") {
2173
+ envelope = await handleUpdate(args);
1789
2174
  }
1790
2175
  else if (command === "install-extension") {
1791
- print(await installExtension(args));
2176
+ envelope = await installExtension(args);
1792
2177
  }
1793
2178
  else if (command === "install-skill") {
1794
- print(await installSkill(args));
2179
+ envelope = await installSkill(args);
2180
+ }
2181
+ else if (command === "processing") {
2182
+ envelope = await handleProcessing(args);
2183
+ }
2184
+ else if (command === "import") {
2185
+ envelope = await handleImportJob(args);
1795
2186
  }
1796
2187
  else if (command === "frontend") {
1797
- print(await handleFrontend(args));
2188
+ envelope = await handleFrontend(args);
1798
2189
  }
1799
2190
  else if (command === "targets") {
1800
- print(await fetchDaemon("/targets"));
2191
+ envelope = await fetchDaemon("/targets");
1801
2192
  }
1802
2193
  else if (command === "target") {
1803
- print(await handleTarget(args));
2194
+ envelope = await handleTarget(args);
1804
2195
  }
1805
2196
  else if (command === "workspace") {
1806
- print(await handleWorkspace(args));
2197
+ envelope = await handleWorkspace(args);
1807
2198
  }
1808
- else if (command === "builder" || command === "build") {
1809
- print(await handleBuilder(args));
2199
+ else if (command === "plugin" || command === "plugins") {
2200
+ envelope = await handlePlugin(args);
1810
2201
  }
1811
2202
  else if (command === "eval") {
1812
2203
  const commandArgs = await readJsonFlag(args, "args-json");
1813
- print(await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args")));
2204
+ envelope = await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args"));
1814
2205
  }
1815
2206
  else if (command === "entity") {
1816
- print(await handleEntity(args));
2207
+ envelope = await handleEntity(args);
1817
2208
  }
1818
2209
  else if (command === "asset") {
1819
- print(await handleAsset(args));
2210
+ envelope = await handleAsset(args);
1820
2211
  }
1821
2212
  else if (command === "material") {
1822
- print(await handleMaterial(args));
2213
+ envelope = await handleMaterial(args);
1823
2214
  }
1824
2215
  else if (command === "template") {
1825
- print(await handleTemplate(args));
2216
+ envelope = await handleTemplate(args);
1826
2217
  }
1827
2218
  else if (command === "script") {
1828
- print(await handleScript(args));
2219
+ envelope = await handleScript(args);
1829
2220
  }
1830
2221
  else if (command === "scene") {
1831
- print(await handleScene(args));
2222
+ envelope = await handleScene(args);
1832
2223
  }
1833
2224
  else if (command === "store") {
1834
- print(await handleStore(args));
2225
+ envelope = await handleStore(args);
1835
2226
  }
1836
2227
  else if (command === "launch") {
1837
- print(await handleLaunch(args));
2228
+ envelope = await handleLaunch(args);
1838
2229
  }
1839
2230
  else if (command === "viewport") {
1840
- print(await handleViewport(args));
2231
+ envelope = await handleViewport(args);
1841
2232
  }
1842
2233
  else if (command === "logs" || command === "log") {
1843
- print(await handleLogs(args));
2234
+ envelope = await handleLogs(args);
1844
2235
  }
1845
2236
  else if (command === "version" || command === "--version" || command === "-v") {
1846
- print(ok({ version: VERSION }));
2237
+ envelope = ok({ version: VERSION });
1847
2238
  }
1848
2239
  else {
1849
- print(fail("UNKNOWN_COMMAND", `Unknown command: ${command}`));
2240
+ envelope = fail("UNKNOWN_COMMAND", `Unknown command: ${command}`);
1850
2241
  process.exitCode = 1;
1851
2242
  }
2243
+ if (command !== "help" &&
2244
+ command !== "--help" &&
2245
+ command !== "-h" &&
2246
+ command !== "version" &&
2247
+ command !== "--version" &&
2248
+ command !== "-v" &&
2249
+ command !== "install-extension" &&
2250
+ command !== "install-skill") {
2251
+ try {
2252
+ const cachedReport = await getUpdateReport({ allowNetwork: false });
2253
+ const updatesMeta = compactUpdatesMeta(cachedReport);
2254
+ if (updatesMeta) {
2255
+ envelope = {
2256
+ ...envelope,
2257
+ meta: { ...(envelope.meta || {}), updates: updatesMeta },
2258
+ };
2259
+ if (process.stderr.isTTY && !flagBool(args, "json") && command !== "update" && command !== "updates") {
2260
+ const hint = formatHumanUpdateHint(cachedReport);
2261
+ if (hint)
2262
+ process.stderr.write(`${hint}\n`);
2263
+ }
2264
+ }
2265
+ }
2266
+ catch {
2267
+ // Never fail a CLI command due to update metadata inspection.
2268
+ }
2269
+ }
2270
+ print(envelope);
1852
2271
  }
1853
2272
  catch (error) {
1854
2273
  if (error instanceof DaemonConnectionError) {