playcanvas-agent-bridge-cli 0.6.2 → 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.
package/dist/cli.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env bun
2
2
  import { activeTools, installTools, TOOLS_ROOT } from "./processing/tools.js";
3
3
  import { spawn } from "node:child_process";
4
- import { realpathSync } from "node:fs";
4
+ import { existsSync, realpathSync } from "node:fs";
5
5
  import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
6
6
  import { createConnection } from "node:net";
7
7
  import { homedir } from "node:os";
@@ -12,6 +12,8 @@ import { createDaemonServer } from "./daemon/server.js";
12
12
  import { FrontendError, getFrontendStatus, installFrontend, listFrontends, removeFrontend, useFrontend, } from "./frontend/store.js";
13
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";
14
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";
15
17
  function parseArgs(argv) {
16
18
  const parsed = { _: [], flags: {} };
17
19
  for (let index = 0; index < argv.length; index += 1) {
@@ -90,7 +92,7 @@ export function diagnoseDaemonConnection(error, port = DEFAULT_PORT) {
90
92
  nextAction: "Retry from an execution context with local-loopback permission.",
91
93
  };
92
94
  }
93
- if (code === "ECONNREFUSED") {
95
+ if (code === "ECONNREFUSED" || code === "ConnectionRefused" || code === "FailedToOpenSocket") {
94
96
  return {
95
97
  code: "DAEMON_NOT_LISTENING",
96
98
  message: `No pcbridge daemon is listening on ${DEFAULT_HOST}:${port}.`,
@@ -388,13 +390,15 @@ function bunVersionSupported(version) {
388
390
  const [major, minor] = version.split(".").map(Number);
389
391
  return major > 1 || (major === 1 && minor >= 4);
390
392
  }
391
- async function doctor() {
393
+ async function doctor(args = { _: ["doctor"], flags: {} }) {
392
394
  const session = await readSessionIfExists();
393
395
  const checks = [];
394
396
  const nextActions = [];
395
397
  const bunVersion = process.versions.bun;
396
398
  let daemonOk = false;
399
+ let daemonVersion = null;
397
400
  let connectedExtensionVersionsOk = true;
401
+ let connectedVersions = [];
398
402
  checks.push({
399
403
  name: "bun",
400
404
  ok: !!bunVersion && bunVersionSupported(bunVersion),
@@ -407,7 +411,7 @@ async function doctor() {
407
411
  try {
408
412
  const health = await fetchDaemon("/health");
409
413
  const daemonData = health.ok ? objectJson(health.data, "daemon health") : null;
410
- const daemonVersion = daemonData && typeof daemonData.version === "string"
414
+ daemonVersion = daemonData && typeof daemonData.version === "string"
411
415
  ? daemonData.version
412
416
  : null;
413
417
  daemonOk = health.ok && daemonVersion === VERSION;
@@ -488,9 +492,9 @@ async function doctor() {
488
492
  try {
489
493
  const targets = await fetchDaemon("/targets");
490
494
  if (targets.ok && Array.isArray(targets.data)) {
491
- const connectedVersions = targets.data
495
+ connectedVersions = targets.data
492
496
  .map((target) => (target && typeof target === "object" && !Array.isArray(target) ? target.extensionVersion : null))
493
- .filter(Boolean);
497
+ .filter((item) => typeof item === "string" && Boolean(item));
494
498
  const mismatched = connectedVersions.filter((version) => version !== VERSION);
495
499
  connectedExtensionVersionsOk = mismatched.length === 0;
496
500
  checks.push({
@@ -510,6 +514,35 @@ async function doctor() {
510
514
  catch {
511
515
  // Daemon reachability is already reported above.
512
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
+ }
513
546
  return ok({
514
547
  version: VERSION,
515
548
  healthy: !!bunVersion && bunVersionSupported(bunVersion) &&
@@ -519,6 +552,7 @@ async function doctor() {
519
552
  connectedExtensionVersionsOk,
520
553
  configDir: CONFIG_DIR,
521
554
  checks,
555
+ updates: updates,
522
556
  nextActions,
523
557
  });
524
558
  }
@@ -566,6 +600,7 @@ async function runDaemon(args, workspaceRoot, restarted) {
566
600
  port,
567
601
  token: session.token,
568
602
  workspaceRoot,
603
+ enableBackgroundUpdateCheck: process.env.PCBRIDGE_DISABLE_BACKGROUND_UPDATE_CHECK !== "1",
569
604
  log: (message) => daemonLog(args, message),
570
605
  });
571
606
  try {
@@ -602,6 +637,47 @@ async function runDaemon(args, workspaceRoot, restarted) {
602
637
  process.off("SIGINT", handleSigint);
603
638
  process.off("SIGTERM", handleSigterm);
604
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
+ }
605
681
  }
606
682
  function isPortListening(port) {
607
683
  return new Promise((resolveListening) => {
@@ -703,7 +779,7 @@ async function daemon(args) {
703
779
  return;
704
780
  }
705
781
  }
706
- await runDaemon(args, workspaceRoot, subcommand === "restart");
782
+ await runDaemon(args, workspaceRoot, subcommand === "restart" || flagBool(args, "restarted"));
707
783
  }
708
784
  else if (subcommand === "stop") {
709
785
  print(await stopDaemon());
@@ -835,6 +911,38 @@ function openChromeExtensions() {
835
911
  }
836
912
  }
837
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
+ }
838
946
  const agent = flagString(args, "agent", "codex") || "codex";
839
947
  const supportedAgents = new Set(["codex", "claude", "cursor", "windsurf"]);
840
948
  if (agent !== "all" && !supportedAgents.has(agent)) {
@@ -849,37 +957,17 @@ async function installSkill(args) {
849
957
  return fail("INVALID_REQUEST", "install-skill --path requires one explicit agent, not --agent all.");
850
958
  }
851
959
  const customParent = customPath ? resolve(customPath) : null;
852
- const root = await findPackageRoot();
853
- const installed = [];
854
- const agents = agent === "all" ? ["codex", "claude", "cursor", "windsurf"] : [agent];
855
- for (const item of agents) {
856
- if (item === "codex") {
857
- const dest = customParent || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
858
- const source = join(root, "skills", "codex", "playcanvas-agent-bridge-cli");
859
- const target = join(dest, "playcanvas-agent-bridge-cli");
860
- await copyDir(source, target, { clean: true });
861
- installed.push({ agent: item, path: target });
862
- }
863
- else if (item === "claude") {
864
- const target = join(customParent || join(homedir(), ".claude", "skills"), "playcanvas-agent-bridge-cli");
865
- await copyDir(join(root, "skills", "claude", "playcanvas-agent-bridge-cli"), target, {
866
- clean: true,
867
- });
868
- installed.push({ agent: item, path: target });
869
- }
870
- else if (item === "cursor") {
871
- const target = join(customParent || join(homedir(), ".cursor", "rules"), "playcanvas-agent-bridge-cli.mdc");
872
- await mkdir(dirname(target), { recursive: true });
873
- await writeFile(target, await readFile(join(root, "skills", "cursor", "playcanvas-agent-bridge-cli.mdc")));
874
- installed.push({ agent: item, path: target });
875
- }
876
- else if (item === "windsurf") {
877
- const target = join(customParent || join(homedir(), ".windsurf", "rules"), "playcanvas-agent-bridge-cli.md");
878
- await mkdir(dirname(target), { recursive: true });
879
- await writeFile(target, await readFile(join(root, "skills", "windsurf", "playcanvas-agent-bridge-cli.md")));
880
- installed.push({ agent: item, path: target });
881
- }
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);
882
969
  }
970
+ await recordInstalledSkills(targets).catch(() => undefined);
883
971
  return ok(installed);
884
972
  }
885
973
  async function handleEntity(args) {
@@ -1602,32 +1690,100 @@ async function handleWorkspace(args) {
1602
1690
  }
1603
1691
  return fail("UNKNOWN_COMMAND", `Unknown workspace command: ${subcommand}`);
1604
1692
  }
1605
- async function handleBuilder(args) {
1606
- const subcommand = args._[1] || "status";
1607
- if (subcommand === "start" || subcommand === "build") {
1608
- const templateAssetId = flagString(args, "asset") ||
1609
- flagString(args, "asset-id") ||
1610
- flagString(args, "id");
1611
- if (!templateAssetId) {
1612
- return fail("INVALID_REQUEST", "builder start requires --asset <templateAssetId>.");
1613
- }
1614
- 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)}`, {
1615
1704
  method: "POST",
1616
1705
  body: JSON.stringify({
1617
- target: flagString(args, "target", "current") || "current",
1618
- templateAssetId,
1619
- suffix: flagString(args, "suffix") || "",
1620
- prefix: flagString(args, "prefix") || "",
1706
+ ...(target ? { target } : {}),
1707
+ params: objectJson(params, "plugin params"),
1621
1708
  }),
1622
1709
  });
1623
1710
  }
1624
- if (subcommand === "status") {
1625
- const jobId = flagString(args, "job") || flagString(args, "id");
1626
- if (!jobId)
1627
- return fail("INVALID_REQUEST", "builder status requires --job <jobId>.");
1628
- 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
+ }));
1743
+ }
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
+ });
1629
1770
  }
1630
- return fail("UNKNOWN_COMMAND", `Unknown builder command: ${subcommand}`);
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}`);
1631
1787
  }
1632
1788
  async function handleProcessing(args) {
1633
1789
  const action = args._[1] || "status";
@@ -1695,12 +1851,111 @@ async function handleImportJob(args) {
1695
1851
  }
1696
1852
  return fail("IMPORT_WAIT_TIMEOUT", "Task is still pending; query the same job before submitting another.");
1697
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}`);
1952
+ }
1698
1953
  function help(group = "overview") {
1699
1954
  const groups = {
1700
1955
  overview: [
1701
1956
  "pcbridge help core",
1702
1957
  "pcbridge help workspace",
1703
- "pcbridge help builder",
1958
+ "pcbridge help plugin",
1704
1959
  "pcbridge help processing",
1705
1960
  "pcbridge help import",
1706
1961
  "pcbridge help frontend",
@@ -1719,6 +1974,8 @@ function help(group = "overview") {
1719
1974
  ],
1720
1975
  core: [
1721
1976
  "pcbridge doctor",
1977
+ "pcbridge update [--check] [--plugins] [--no-reload-tabs]",
1978
+ "pcbridge update status [--refresh]",
1722
1979
  "pcbridge install-extension",
1723
1980
  "pcbridge install-skill --agent codex|claude|cursor|windsurf|all [--path <parent_directory>]",
1724
1981
  "--path is allowed only with one agent and appends the standard skill/rule name.",
@@ -1758,11 +2015,17 @@ function help(group = "overview") {
1758
2015
  "Complete means server publication. --sync-workspace separately waits for local metadata synchronization.",
1759
2016
  "New files use the existing asset upload command; model uploads create the same import jobs.",
1760
2017
  ],
1761
- builder: [
1762
- "pcbridge builder start --target editor:<sceneId> --asset <template_asset_id> [--suffix '-${time}'] [--prefix assets]",
1763
- "pcbridge builder status --job <build_job_id>",
1764
- "Template assets also show a pcbridge Tiny Builder panel in the PlayCanvas Editor.",
1765
- "S3 settings come from the project .env, then the workspace-root .env; files upload directly without a ZIP.",
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.",
1766
2029
  ],
1767
2030
  frontend: [
1768
2031
  "pcbridge frontend install [latest|playcanvas-editor-v<version>-r<revision>] [--no-activate]",
@@ -1896,83 +2159,115 @@ async function main() {
1896
2159
  return;
1897
2160
  }
1898
2161
  try {
2162
+ let envelope;
1899
2163
  if (command !== "help" && args._[1] === "help") {
1900
- print(help(command));
2164
+ envelope = help(command);
1901
2165
  }
1902
2166
  else if (command === "help" || command === "--help" || command === "-h") {
1903
- print(help(args._[1] || "overview"));
2167
+ envelope = help(args._[1] || "overview");
1904
2168
  }
1905
2169
  else if (command === "doctor") {
1906
- print(await doctor());
2170
+ envelope = await doctor(args);
2171
+ }
2172
+ else if (command === "update" || command === "updates") {
2173
+ envelope = await handleUpdate(args);
1907
2174
  }
1908
2175
  else if (command === "install-extension") {
1909
- print(await installExtension(args));
2176
+ envelope = await installExtension(args);
1910
2177
  }
1911
2178
  else if (command === "install-skill") {
1912
- print(await installSkill(args));
2179
+ envelope = await installSkill(args);
1913
2180
  }
1914
2181
  else if (command === "processing") {
1915
- print(await handleProcessing(args));
2182
+ envelope = await handleProcessing(args);
1916
2183
  }
1917
2184
  else if (command === "import") {
1918
- print(await handleImportJob(args));
2185
+ envelope = await handleImportJob(args);
1919
2186
  }
1920
2187
  else if (command === "frontend") {
1921
- print(await handleFrontend(args));
2188
+ envelope = await handleFrontend(args);
1922
2189
  }
1923
2190
  else if (command === "targets") {
1924
- print(await fetchDaemon("/targets"));
2191
+ envelope = await fetchDaemon("/targets");
1925
2192
  }
1926
2193
  else if (command === "target") {
1927
- print(await handleTarget(args));
2194
+ envelope = await handleTarget(args);
1928
2195
  }
1929
2196
  else if (command === "workspace") {
1930
- print(await handleWorkspace(args));
2197
+ envelope = await handleWorkspace(args);
1931
2198
  }
1932
- else if (command === "builder" || command === "build") {
1933
- print(await handleBuilder(args));
2199
+ else if (command === "plugin" || command === "plugins") {
2200
+ envelope = await handlePlugin(args);
1934
2201
  }
1935
2202
  else if (command === "eval") {
1936
2203
  const commandArgs = await readJsonFlag(args, "args-json");
1937
- print(await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args")));
2204
+ envelope = await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args"));
1938
2205
  }
1939
2206
  else if (command === "entity") {
1940
- print(await handleEntity(args));
2207
+ envelope = await handleEntity(args);
1941
2208
  }
1942
2209
  else if (command === "asset") {
1943
- print(await handleAsset(args));
2210
+ envelope = await handleAsset(args);
1944
2211
  }
1945
2212
  else if (command === "material") {
1946
- print(await handleMaterial(args));
2213
+ envelope = await handleMaterial(args);
1947
2214
  }
1948
2215
  else if (command === "template") {
1949
- print(await handleTemplate(args));
2216
+ envelope = await handleTemplate(args);
1950
2217
  }
1951
2218
  else if (command === "script") {
1952
- print(await handleScript(args));
2219
+ envelope = await handleScript(args);
1953
2220
  }
1954
2221
  else if (command === "scene") {
1955
- print(await handleScene(args));
2222
+ envelope = await handleScene(args);
1956
2223
  }
1957
2224
  else if (command === "store") {
1958
- print(await handleStore(args));
2225
+ envelope = await handleStore(args);
1959
2226
  }
1960
2227
  else if (command === "launch") {
1961
- print(await handleLaunch(args));
2228
+ envelope = await handleLaunch(args);
1962
2229
  }
1963
2230
  else if (command === "viewport") {
1964
- print(await handleViewport(args));
2231
+ envelope = await handleViewport(args);
1965
2232
  }
1966
2233
  else if (command === "logs" || command === "log") {
1967
- print(await handleLogs(args));
2234
+ envelope = await handleLogs(args);
1968
2235
  }
1969
2236
  else if (command === "version" || command === "--version" || command === "-v") {
1970
- print(ok({ version: VERSION }));
2237
+ envelope = ok({ version: VERSION });
1971
2238
  }
1972
2239
  else {
1973
- print(fail("UNKNOWN_COMMAND", `Unknown command: ${command}`));
2240
+ envelope = fail("UNKNOWN_COMMAND", `Unknown command: ${command}`);
1974
2241
  process.exitCode = 1;
1975
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);
1976
2271
  }
1977
2272
  catch (error) {
1978
2273
  if (error instanceof DaemonConnectionError) {