playcanvas-agent-bridge-cli 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
Binary file
Binary file
Binary file
@@ -2,7 +2,7 @@
2
2
  "manifest_version": 3,
3
3
  "name": "PlayCanvas Agent Bridge",
4
4
  "description": "Connects open PlayCanvas Editor and Launch tabs to the local pcbridge daemon.",
5
- "version": "0.5.2",
5
+ "version": "0.6.0",
6
6
  "permissions": ["activeTab", "storage"],
7
7
  "host_permissions": [
8
8
  "http://playcanvas.com/*",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "playcanvas-agent-bridge-cli",
3
- "version": "0.5.2",
3
+ "version": "0.6.0",
4
4
  "description": "CLI-first local bridge for automating open PlayCanvas Editor tabs from AI coding agents.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -47,11 +47,16 @@
47
47
  },
48
48
  "dependencies": {
49
49
  "@aws-sdk/client-s3": "^3.1102.0",
50
+ "@babel/core": "^7.28.4",
51
+ "@babel/preset-env": "^7.28.3",
50
52
  "dotenv": "^17.4.2",
51
53
  "tar": "^7.5.22",
54
+ "terser": "^5.50.0",
52
55
  "ws": "^8.18.3"
53
56
  },
54
57
  "devDependencies": {
58
+ "@types/babel__core": "^7.20.5",
59
+ "@types/babel__preset-env": "^7.10.0",
55
60
  "@types/node": "^24.0.4",
56
61
  "@types/ws": "^8.18.1",
57
62
  "typescript": "5.8.3"
@@ -28,6 +28,24 @@ published custom Editor build. The extension popup switches between custom and o
28
28
  The popup remembers that choice per PlayCanvas project and applies it automatically on later
29
29
  project-picker and scene Editor navigations; change the remembered mode only through the popup.
30
30
 
31
+ ## Updating pcbridge
32
+
33
+ The CLI/daemon, copied agent skills, generated Chrome extension, and custom Editor frontend update
34
+ independently. For an explicit update request:
35
+
36
+ 1. Have the user stop the foreground daemon with Ctrl+C and preserve its working directory; no
37
+ `daemon stop` command exists.
38
+ 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
39
+ `pcbridge install-skill --agent all`.
40
+ 3. Run `pcbridge install-extension --no-open`; the user must click **Reload** in
41
+ `chrome://extensions` and refresh every open Editor/Launch tab.
42
+ 4. Restart the daemon from the same workspace root and verify `pcbridge doctor`.
43
+ 5. Use `pcbridge frontend update` plus `frontend status` for the separately published Editor build.
44
+ That update is read dynamically by a running daemon, but the user must refresh the Editor page
45
+ and choose **Use custom frontend** in the popup if official mode is selected.
46
+
47
+ Do not report completion before the required manual browser and daemon steps are confirmed.
48
+
31
49
  Use layered help to load only the command surface you need:
32
50
 
33
51
  ```bash
@@ -54,9 +72,9 @@ Workspace layout:
54
72
  ```text
55
73
  <workspace root>/<projectId>-<projectName>/
56
74
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # remote folder tree; scripts eager, binary file contents lazy
75
+ assets/ # collision-safe projection of the remote folder tree
58
76
  tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
- .pcbridge/ # internal state; do not edit
77
+ .pcbridge/ # internal state and object cache; do not edit
60
78
  ```
61
79
 
62
80
  Prefer local operations for file-backed Assets. Edit scripts under `assets/`; create files and
@@ -64,22 +82,28 @@ folders there to upload them through PlayCanvas processing; and rename or move l
64
82
  the same remote Asset ID. Deleting a local file only clears its local cache and does not delete the
65
83
  remote Asset. Use `asset delete --id <id>` only for intentional remote deletion. Scripts are eager,
66
84
  while binary contents are lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset
67
- <assetId>` before modifying a missing remote binary. Edit a source GLB rather than its generated
68
- Model/Container/material derivatives.
85
+ <assetId>` before modifying a missing remote binary. Generated GLB Model/Container/material Assets
86
+ and font atlases are lazy, read-only projections. Edit the source Asset; derivative edits or moves
87
+ are quarantined and restored from `.pcbridge/objects`, never uploaded.
69
88
 
70
89
  After local writes, wait for the watcher and poll `workspace status` until `synced`. A brief
71
90
  `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
72
91
  `tmp/conflicts/`, and never overwrite a conflict automatically. Local file
73
92
  arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
74
93
  unless the user explicitly asks to use a known external file.
75
- Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
76
- compare remote, local, and base MD5 values. Do not edit the managed asset catalog to request remote
77
- operations. Remote deletions are quarantined under `tmp/trash/remote/`, while true content
94
+ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path and
95
+ `projectionPath` is the unique local path. Inspect `origin`, `remoteFile`, and `local` for role,
96
+ advertised/observed/effective MD5, presence, writability, and current/base MD5. Only collisions gain
97
+ `.__pc_<type>_<assetId>`. Do not edit the managed catalog to request remote operations. Remote
98
+ deletions are quarantined under `tmp/trash/remote/`, while true content
78
99
  divergence remains under `tmp/conflicts/`.
79
100
 
80
101
  Selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
81
- dependencies, fills the workspace cache, and uploads individual S3 objects without a ZIP. Project
82
- `.env` overrides workspace-root `.env`; never expose credential values. CLI equivalents are
102
+ dependencies, materializes missing or remote-updated primary files, texture variants, and additional
103
+ font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
104
+ schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
105
+ internal content cache. Project `.env` overrides workspace-root `.env`; never expose credential
106
+ values. CLI equivalents are
83
107
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
84
108
  `pcbridge builder status --job <jobId>`.
85
109
 
@@ -37,6 +37,27 @@ frontend modes. Load focused help with `pcbridge help frontend`.
37
37
  The popup remembers that choice per PlayCanvas project and applies it automatically on later
38
38
  project-picker and scene Editor navigations; change the remembered mode only through the popup.
39
39
 
40
+ ## Updating pcbridge
41
+
42
+ Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
43
+ as separate components. When the user asks to update pcbridge:
44
+
45
+ 1. Ask the user to stop the foreground daemon with Ctrl+C; there is no `daemon stop` command. Record
46
+ its working directory so it can restart from the same workspace root.
47
+ 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
48
+ copied skills with `pcbridge install-skill --agent all`.
49
+ 3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
50
+ Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
51
+ directory is not enough.
52
+ 4. Restart `pcbridge daemon start` from the original workspace root and verify with `pcbridge doctor`.
53
+ 5. Update the independently published Editor build with `pcbridge frontend update`, then verify
54
+ `frontend status`. A frontend-only update does not require daemon restart, but the user must
55
+ refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
56
+ mode.
57
+
58
+ Do not claim an update is complete until required Chrome reload, page refresh, and daemon restart
59
+ steps have been acknowledged or verified.
60
+
40
61
  ## Workflow
41
62
 
42
63
  1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
@@ -54,9 +75,9 @@ project-picker and scene Editor navigations; change the remembered mode only thr
54
75
  ```text
55
76
  <workspace root>/<projectId>-<projectName>/
56
77
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # PlayCanvas folder tree; scripts eager, binary file contents lazy
78
+ assets/ # collision-safe projection of the PlayCanvas folder tree
58
79
  tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
- .pcbridge/ # internal sync state; do not edit
80
+ .pcbridge/ # internal sync state and object cache; do not edit
60
81
  ```
61
82
 
62
83
  Use:
@@ -75,21 +96,26 @@ Prefer local file operations for file-backed Assets:
75
96
  - Rename or move a local file to rename or move the same remote Asset ID.
76
97
  - Deleting a local file only removes the local lazy cache. It does not delete the remote Asset; use `pcbridge asset delete --id <id>` only when remote deletion is explicitly intended.
77
98
  - Scripts are downloaded eagerly. Binary files are lazy; run `workspace pull --asset <id>` before modifying a remote binary that is not present locally.
78
- - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs are catalog-only. Edit the source GLB, not a derivative.
99
+ - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs and font atlases are lazy, read-only projections. Edit the source Asset, not a derivative. A local derivative edit or move is quarantined under `tmp/conflicts/`, restored from `.pcbridge/objects`, and never uploaded.
79
100
 
80
101
  After a local edit, allow the watcher to react, then poll `workspace status` until it reports
81
102
  `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
82
103
  remote editing while the same file is pending. If it does not converge, run one explicit
83
104
  `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
84
105
  a conflict automatically.
85
- Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
86
- compare remote, local, and base MD5 values. The catalog is managed by pcbridge; do not edit it to
87
- request remote asset operations. Confirmed remote deletions are quarantined under
106
+ Read schema-v3 `pcbridge.project.json.assets` to resolve Asset IDs. `folder` is the remote display
107
+ path; `projectionPath` is the unique local path. Inspect `origin`, `remoteFile`, and `local` for the
108
+ source/derived role, advertised/observed/effective MD5, presence, writability, and current/base MD5.
109
+ Only collision paths gain `.__pc_<type>_<assetId>`. The catalog is managed by pcbridge; do not edit it
110
+ to request remote asset operations. Confirmed remote deletions are quarantined under
88
111
  `tmp/trash/remote/`; `tmp/conflicts/` is reserved for divergent local and remote contents.
89
112
 
90
113
  Selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
91
- dependencies, fills the workspace cache, and uploads individual S3 objects without a ZIP. Project
92
- `.env` overrides workspace-root `.env`; never read or return credential values. CLI equivalents are
114
+ dependencies, materializes missing or remote-updated primary files, texture variants, and additional
115
+ font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
116
+ schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
117
+ internal content cache. Project `.env` overrides workspace-root `.env`; never read or return
118
+ credential values. CLI equivalents are
93
119
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
94
120
  `pcbridge builder status --job <jobId>`.
95
121
 
@@ -17,6 +17,17 @@ pcbridge targets
17
17
  Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
18
18
  with local-loopback permission. If no target appears, ask the user to install/reload the extension.
19
19
 
20
+ Updates are component-specific. For an explicit update request, have the user stop the foreground
21
+ daemon with Ctrl+C and remember its workspace-root directory; there is no `daemon stop`. Run
22
+ `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
+ `pcbridge install-skill --agent all`. Regenerate the extension with
24
+ `pcbridge install-extension --no-open`; the user must manually click **Reload** in
25
+ `chrome://extensions` and refresh Editor/Launch tabs. Restart the daemon from the original workspace
26
+ root and verify `pcbridge doctor`. Update the independently published Editor build with
27
+ `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
28
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
29
+ claim completion before these manual steps are confirmed.
30
+
20
31
  The daemon start directory is the workspace root. After selecting an explicit target, run
21
32
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
22
33
  or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
@@ -24,14 +35,22 @@ operations for file-backed Assets: edit scripts under `assets/`; create files/fo
24
35
  upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
25
36
  Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
26
37
  lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before editing a missing
27
- binary. Edit source GLBs, not generated Model/Container/material derivatives. `tmp/` is never synced.
38
+ binary. Generated GLB Model/Container/material Assets and font atlases are lazy, read-only
39
+ projections: edit the source Asset. Derivative edits or moves are quarantined, restored from
40
+ `.pcbridge/objects`, and never uploaded. `tmp/` is never synced.
28
41
  After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
29
42
  If it does not converge, run one `workspace sync` and inspect status plus `tmp/conflicts/`.
30
- Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
31
- remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
43
+ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
44
+ `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
45
+ effective metadata, presence, writability, and hashes. Only collisions gain
46
+ `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
32
47
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
33
48
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
34
- overrides workspace-root `.env`.
49
+ overrides workspace-root `.env`. A build materializes every primary dependency plus texture
50
+ variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
51
+ those projected files. Schema-v3 `local.resources` records the managed read-only auxiliary files;
52
+ `.pcbridge/objects` is only an internal content cache. New builds do not use `tmp/cache/assets/`,
53
+ and compatible files left there by older versions are migrated into `assets/` when needed.
35
54
 
36
55
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
37
56
  `pcbridge frontend status`, and switch custom/official mode from the extension popup.
@@ -13,21 +13,40 @@ pcbridge targets
13
13
  Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
14
14
  with local-loopback permission. If no target is connected, install/reload the unpacked extension.
15
15
 
16
+ Updates are component-specific. For an explicit update request, have the user stop the foreground
17
+ daemon with Ctrl+C and remember its workspace-root directory; there is no `daemon stop`. Run
18
+ `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
19
+ `pcbridge install-skill --agent all`. Regenerate the extension with
20
+ `pcbridge install-extension --no-open`; the user must manually click **Reload** in
21
+ `chrome://extensions` and refresh Editor/Launch tabs. Restart the daemon from the original workspace
22
+ root and verify `pcbridge doctor`. Update the independently published Editor build with
23
+ `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
24
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
25
+ claim completion before these manual steps are confirmed.
26
+
16
27
  The daemon start directory is the workspace root. After selecting an explicit target, run
17
28
  `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
18
29
  error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
19
30
  operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
20
31
  upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
21
32
  Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
22
- lazy; use `workspace pull` before editing a missing binary. Edit source GLBs, not generated
23
- Model/Container/material derivatives. `tmp/` is never synchronized. After local writes, poll
33
+ lazy; use `workspace pull` before editing a missing binary. Generated GLB Model/Container/material
34
+ Assets and font atlases are lazy, read-only projections: edit the source Asset. Derivative edits or
35
+ moves are quarantined, restored from `.pcbridge/objects`, and never uploaded. `tmp/` is never
36
+ synchronized. After local writes, poll
24
37
  `workspace status` until `synced`; a brief `local-change` is expected. If it does not converge,
25
38
  run one `workspace sync` and inspect status plus `tmp/conflicts/`.
26
- Read `pcbridge.project.json.assets` for asset ids, types, project-relative file paths, presence, and
27
- remote/local/base MD5 values. Treat that asset catalog as pcbridge-managed. Confirmed remote
39
+ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
40
+ `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
41
+ effective metadata, presence, writability, and hashes. Only collisions gain
42
+ `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
28
43
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
29
44
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
30
- overrides workspace-root `.env`.
45
+ overrides workspace-root `.env`. A build materializes every primary dependency plus texture
46
+ variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
47
+ those projected files. Schema-v3 `local.resources` records the managed read-only auxiliary files;
48
+ `.pcbridge/objects` is only an internal content cache. New builds do not use `tmp/cache/assets/`,
49
+ and compatible files left there by older versions are migrated into `assets/` when needed.
31
50
 
32
51
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
33
52
  `pcbridge frontend status`, and switch custom/official mode from the extension popup.