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.
- package/README.md +91 -12
- package/README.zh-CN.md +85 -11
- package/dist/builder/manager.js +141 -59
- package/dist/config.js +1 -1
- package/dist/workspace/manager.js +697 -118
- package/extension/icons/icon-128.png +0 -0
- package/extension/icons/icon-16.png +0 -0
- package/extension/icons/icon-32.png +0 -0
- package/extension/icons/icon-48.png +0 -0
- package/extension/manifest.json +1 -1
- package/package.json +6 -1
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +33 -9
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +34 -8
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +23 -4
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +24 -5
- package/extension/icons/concepts/pcbridge-bridge.png +0 -0
- package/extension/icons/concepts/pcbridge-cube.png +0 -0
- package/extension/icons/concepts/pcbridge-p-active.png +0 -0
- package/extension/icons/concepts/pcbridge-p-arch.png +0 -0
- package/extension/icons/concepts/pcbridge-p-bridge.png +0 -0
- package/extension/icons/concepts/pcbridge-p-emblem.png +0 -0
- package/extension/icons/concepts/pcbridge-signal.png +0 -0
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/extension/manifest.json
CHANGED
|
@@ -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
|
+
"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.
|
|
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/ #
|
|
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.
|
|
68
|
-
|
|
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`
|
|
76
|
-
|
|
77
|
-
|
|
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,
|
|
82
|
-
|
|
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/ #
|
|
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
|
|
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
|
|
86
|
-
|
|
87
|
-
|
|
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,
|
|
92
|
-
|
|
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.
|
|
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`
|
|
31
|
-
|
|
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.
|
|
23
|
-
|
|
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`
|
|
27
|
-
|
|
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.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|