playcanvas-agent-bridge-cli 0.5.3 → 0.6.1

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.
@@ -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.3",
5
+ "version": "0.6.1",
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.3",
3
+ "version": "0.6.1",
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"
@@ -18,7 +18,8 @@ terminal. For `LOOPBACK_ACCESS_DENIED`, retry with local-loopback permission ins
18
18
  second daemon. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`,
19
19
  load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
20
20
 
21
- The directory where `pcbridge daemon start` runs is the workspace root. Each ready Editor project
21
+ The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
22
+ selects it explicitly, and `daemon stop` stops the authenticated daemon. Each ready Editor project
22
23
  is mirrored into `<projectId>-<projectName>/` below it. After choosing an explicit target, run
23
24
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
24
25
  or sync error.
@@ -28,6 +29,28 @@ published custom Editor build. The extension popup switches between custom and o
28
29
  The popup remembers that choice per PlayCanvas project and applies it automatically on later
29
30
  project-picker and scene Editor navigations; change the remembered mode only through the popup.
30
31
 
32
+ ## Updating pcbridge
33
+
34
+ The CLI/daemon, copied agent skills, generated Chrome extension, and custom Editor frontend update
35
+ independently. For an explicit update request:
36
+
37
+ 1. Record the workspace root reported by `pcbridge daemon status`.
38
+ 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
39
+ `pcbridge install-skill --agent all`.
40
+ For a custom or project-local parent directory, use
41
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
42
+ standard artifact name and cannot be combined with `--agent all`.
43
+ 3. Run `pcbridge install-extension --no-open`; the user must click **Reload** in
44
+ `chrome://extensions` and refresh every open Editor/Launch tab.
45
+ 4. Run `pcbridge daemon restart --workspace <original-root>` and verify `pcbridge doctor`. For a
46
+ one-time migration from a daemon without authenticated shutdown, have the user stop the old
47
+ daemon with Ctrl+C, then start the updated daemon with the same `--workspace` value.
48
+ 5. Use `pcbridge frontend update` plus `frontend status` for the separately published Editor build.
49
+ That update is read dynamically by a running daemon, but the user must refresh the Editor page
50
+ and choose **Use custom frontend** in the popup if official mode is selected.
51
+
52
+ Do not report completion before the required manual browser and daemon steps are confirmed.
53
+
31
54
  Use layered help to load only the command surface you need:
32
55
 
33
56
  ```bash
@@ -54,9 +77,9 @@ Workspace layout:
54
77
  ```text
55
78
  <workspace root>/<projectId>-<projectName>/
56
79
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # remote folder tree; scripts eager, binary file contents lazy
80
+ assets/ # collision-safe projection of the remote folder tree
58
81
  tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
- .pcbridge/ # internal state; do not edit
82
+ .pcbridge/ # internal state and object cache; do not edit
60
83
  ```
61
84
 
62
85
  Prefer local operations for file-backed Assets. Edit scripts under `assets/`; create files and
@@ -64,22 +87,28 @@ folders there to upload them through PlayCanvas processing; and rename or move l
64
87
  the same remote Asset ID. Deleting a local file only clears its local cache and does not delete the
65
88
  remote Asset. Use `asset delete --id <id>` only for intentional remote deletion. Scripts are eager,
66
89
  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.
90
+ <assetId>` before modifying a missing remote binary. Generated GLB Model/Container/material Assets
91
+ and font atlases are lazy, read-only projections. Edit the source Asset; derivative edits or moves
92
+ are quarantined and restored from `.pcbridge/objects`, never uploaded.
69
93
 
70
94
  After local writes, wait for the watcher and poll `workspace status` until `synced`. A brief
71
95
  `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
72
96
  `tmp/conflicts/`, and never overwrite a conflict automatically. Local file
73
97
  arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
74
98
  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
99
+ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path and
100
+ `projectionPath` is the unique local path. Inspect `origin`, `remoteFile`, and `local` for role,
101
+ advertised/observed/effective MD5, presence, writability, and current/base MD5. Only collisions gain
102
+ `.__pc_<type>_<assetId>`. Do not edit the managed catalog to request remote operations. Remote
103
+ deletions are quarantined under `tmp/trash/remote/`, while true content
78
104
  divergence remains under `tmp/conflicts/`.
79
105
 
80
106
  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
107
+ dependencies, materializes missing or remote-updated primary files, texture variants, and additional
108
+ font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
109
+ schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
110
+ internal content cache. Project `.env` overrides workspace-root `.env`; never expose credential
111
+ values. CLI equivalents are
83
112
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
84
113
  `pcbridge builder status --job <jobId>`.
85
114
 
@@ -26,8 +26,10 @@ pcbridge daemon start
26
26
  Do not start a second daemon for `LOOPBACK_ACCESS_DENIED`. That means the current execution
27
27
  environment cannot access `127.0.0.1`; retry with local-loopback permission instead.
28
28
 
29
- The directory where `pcbridge daemon start` runs is the workspace root. Choose it intentionally;
30
- each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
29
+ The directory where `pcbridge daemon start` runs is the default workspace root; use
30
+ `--workspace <directory>` to select it explicitly. Use `pcbridge daemon restart --workspace
31
+ <directory>` to switch roots safely, and `pcbridge daemon stop` to stop the authenticated daemon.
32
+ Each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
31
33
 
32
34
  If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor or Launch tab.
33
35
 
@@ -37,6 +39,31 @@ frontend modes. Load focused help with `pcbridge help frontend`.
37
39
  The popup remembers that choice per PlayCanvas project and applies it automatically on later
38
40
  project-picker and scene Editor navigations; change the remembered mode only through the popup.
39
41
 
42
+ ## Updating pcbridge
43
+
44
+ Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
45
+ as separate components. When the user asks to update pcbridge:
46
+
47
+ 1. Record the current workspace root from `pcbridge daemon status`.
48
+ 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
49
+ copied skills with `pcbridge install-skill --agent all`.
50
+ For a custom or project-local parent directory, use
51
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
52
+ standard artifact name and cannot be combined with `--agent all`.
53
+ 3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
54
+ Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
55
+ directory is not enough.
56
+ 4. Run `pcbridge daemon restart --workspace <original-root>` and verify with `pcbridge doctor`.
57
+ When migrating from a daemon version without authenticated shutdown, ask the user to stop that
58
+ old daemon once with Ctrl+C, then start the updated daemon with the same `--workspace` value.
59
+ 5. Update the independently published Editor build with `pcbridge frontend update`, then verify
60
+ `frontend status`. A frontend-only update does not require daemon restart, but the user must
61
+ refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
62
+ mode.
63
+
64
+ Do not claim an update is complete until required Chrome reload, page refresh, and daemon restart
65
+ steps have been acknowledged or verified.
66
+
40
67
  ## Workflow
41
68
 
42
69
  1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
@@ -54,9 +81,9 @@ project-picker and scene Editor navigations; change the remembered mode only thr
54
81
  ```text
55
82
  <workspace root>/<projectId>-<projectName>/
56
83
  pcbridge.project.json # project metadata and agent-readable asset catalog
57
- assets/ # PlayCanvas folder tree; scripts eager, binary file contents lazy
84
+ assets/ # collision-safe projection of the PlayCanvas folder tree
58
85
  tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
59
- .pcbridge/ # internal sync state; do not edit
86
+ .pcbridge/ # internal sync state and object cache; do not edit
60
87
  ```
61
88
 
62
89
  Use:
@@ -75,21 +102,26 @@ Prefer local file operations for file-backed Assets:
75
102
  - Rename or move a local file to rename or move the same remote Asset ID.
76
103
  - 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
104
  - 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.
105
+ - 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
106
 
80
107
  After a local edit, allow the watcher to react, then poll `workspace status` until it reports
81
108
  `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
82
109
  remote editing while the same file is pending. If it does not converge, run one explicit
83
110
  `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
84
111
  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
112
+ Read schema-v3 `pcbridge.project.json.assets` to resolve Asset IDs. `folder` is the remote display
113
+ path; `projectionPath` is the unique local path. Inspect `origin`, `remoteFile`, and `local` for the
114
+ source/derived role, advertised/observed/effective MD5, presence, writability, and current/base MD5.
115
+ Only collision paths gain `.__pc_<type>_<assetId>`. The catalog is managed by pcbridge; do not edit it
116
+ to request remote asset operations. Confirmed remote deletions are quarantined under
88
117
  `tmp/trash/remote/`; `tmp/conflicts/` is reserved for divergent local and remote contents.
89
118
 
90
119
  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
120
+ dependencies, materializes missing or remote-updated primary files, texture variants, and additional
121
+ font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
122
+ schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
123
+ internal content cache. Project `.env` overrides workspace-root `.env`; never read or return
124
+ credential values. CLI equivalents are
93
125
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
94
126
  `pcbridge builder status --job <jobId>`.
95
127
 
@@ -17,21 +17,44 @@ 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
- The daemon start directory is the workspace root. After selecting an explicit target, run
20
+ Updates are component-specific. For an explicit update request, record the workspace root from
21
+ `pcbridge daemon status`. Run
22
+ `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
+ `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
24
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
25
+ artifact name and cannot be combined with `--agent all`. Regenerate the extension with
26
+ `pcbridge install-extension --no-open`; the user must manually click **Reload** in
27
+ `chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
28
+ <original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
29
+ be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
30
+ `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
31
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
32
+ claim completion before these manual steps are confirmed.
33
+
34
+ The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
35
+ selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
21
36
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
22
37
  or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
23
38
  operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
24
39
  upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
25
40
  Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
26
41
  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.
42
+ binary. Generated GLB Model/Container/material Assets and font atlases are lazy, read-only
43
+ projections: edit the source Asset. Derivative edits or moves are quarantined, restored from
44
+ `.pcbridge/objects`, and never uploaded. `tmp/` is never synced.
28
45
  After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
29
46
  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
47
+ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
48
+ `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
49
+ effective metadata, presence, writability, and hashes. Only collisions gain
50
+ `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
32
51
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
33
52
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
34
- overrides workspace-root `.env`.
53
+ overrides workspace-root `.env`. A build materializes every primary dependency plus texture
54
+ variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
55
+ those projected files. Schema-v3 `local.resources` records the managed read-only auxiliary files;
56
+ `.pcbridge/objects` is only an internal content cache. New builds do not use `tmp/cache/assets/`,
57
+ and compatible files left there by older versions are migrated into `assets/` when needed.
35
58
 
36
59
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
37
60
  `pcbridge frontend status`, and switch custom/official mode from the extension popup.
@@ -13,21 +13,44 @@ 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
- The daemon start directory is the workspace root. After selecting an explicit target, run
16
+ Updates are component-specific. For an explicit update request, record the workspace root from
17
+ `pcbridge daemon status`. Run
18
+ `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
19
+ `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
20
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
21
+ artifact name and cannot be combined with `--agent all`. Regenerate the extension with
22
+ `pcbridge install-extension --no-open`; the user must manually click **Reload** in
23
+ `chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
24
+ <original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
25
+ be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
26
+ `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
27
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
28
+ claim completion before these manual steps are confirmed.
29
+
30
+ The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
31
+ selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
17
32
  `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
18
33
  error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
19
34
  operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
20
35
  upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
21
36
  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
37
+ lazy; use `workspace pull` before editing a missing binary. Generated GLB Model/Container/material
38
+ Assets and font atlases are lazy, read-only projections: edit the source Asset. Derivative edits or
39
+ moves are quarantined, restored from `.pcbridge/objects`, and never uploaded. `tmp/` is never
40
+ synchronized. After local writes, poll
24
41
  `workspace status` until `synced`; a brief `local-change` is expected. If it does not converge,
25
42
  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
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
28
47
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
29
48
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
30
- 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.
31
54
 
32
55
  For the optional published Editor build, use `pcbridge frontend install latest`, verify it with
33
56
  `pcbridge frontend status`, and switch custom/official mode from the extension popup.