playcanvas-agent-bridge-cli 0.6.0 → 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.
package/README.md CHANGED
@@ -20,7 +20,7 @@ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
20
  pcbridge install-skill --agent all
21
21
  ```
22
22
 
23
- The commands documented below track repository version `0.6.0`. npm installs the latest stable
23
+ The commands documented below track repository version `0.6.1`. npm installs the latest stable
24
24
  release; use the GitHub install when testing changes that have not been released yet.
25
25
 
26
26
  One-shot with npx:
@@ -37,22 +37,22 @@ frontend are separate local components. Updating one does not update the others
37
37
 
38
38
  ### Update the CLI, daemon, and agent skills
39
39
 
40
- First stop the running daemon with **Ctrl+C in the terminal where it was started**. There is no
41
- `pcbridge daemon stop` command. Remember that terminal's working directory because it is the
42
- workspace root and must be reused when the daemon starts again.
43
-
44
40
  ```bash
45
41
  npm install -g playcanvas-agent-bridge-cli@latest
46
42
  pcbridge version
47
43
  pcbridge install-skill --agent all
48
- cd /the/same/workspace/root
49
- pcbridge daemon start
44
+ pcbridge daemon restart --workspace /the/workspace/root
50
45
  ```
51
46
 
52
47
  Installing the npm package replaces the CLI files, but an already-running daemon remains the old
53
- in-memory version until it is restarted. Installed Codex, Claude, Cursor, and Windsurf skills are
54
- also copies, so rerun `install-skill`; start a new agent task/session if the client has already
55
- loaded the old skill.
48
+ in-memory version until it is restarted. `daemon restart` authenticates the existing pcbridge
49
+ listener, shuts it down gracefully, waits for the port to be released, and starts the new daemon in
50
+ the current terminal. It never kills an unverified process merely because that process occupies the
51
+ configured port. When upgrading from a version that predates authenticated shutdown, stop that old
52
+ daemon once with **Ctrl+C**, then use `daemon restart` for later switches and upgrades.
53
+
54
+ Installed Codex, Claude, Cursor, and Windsurf skills are also copies, so rerun `install-skill`;
55
+ start a new agent task/session if the client has already loaded the old skill.
56
56
 
57
57
  ### Update the Chrome extension
58
58
 
@@ -154,13 +154,27 @@ until another installed release is selected.
154
154
 
155
155
  ## Start the bridge
156
156
 
157
- Change into the directory that should become the local workspace root before starting the daemon:
157
+ Use the current directory as the workspace root, or pass it explicitly:
158
158
 
159
159
  ```bash
160
160
  cd /path/to/my-playcanvas-workspace
161
161
  pcbridge daemon start
162
+
163
+ # Equivalent from any directory
164
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
165
+
166
+ # Stop the current daemon and switch workspace roots
167
+ pcbridge daemon restart --workspace /path/to/another-workspace
168
+
169
+ # Gracefully stop the authenticated pcbridge daemon
170
+ pcbridge daemon stop
162
171
  ```
163
172
 
173
+ `daemon restart` and `daemon stop` first verify the token-protected `/health` response. A token
174
+ mismatch or a non-pcbridge listener fails without terminating the process on that port. Both
175
+ `start` and `restart` run the daemon in the foreground so logs remain visible and **Ctrl+C** still
176
+ works.
177
+
164
178
  When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` automatically:
165
179
 
166
180
  ```text
@@ -439,6 +453,20 @@ pcbridge install-skill --agent windsurf
439
453
  pcbridge install-skill --agent all
440
454
  ```
441
455
 
456
+ Use `--path` to install one agent's skill or rule under a custom parent directory. Relative paths
457
+ are resolved from the current working directory, and pcbridge appends the standard directory or
458
+ filename so the parent itself is never cleared:
459
+
460
+ ```bash
461
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
462
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
463
+ ```
464
+
465
+ These create `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` and
466
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`. Quote Windows paths that contain spaces.
467
+ `--agent all --path ...` is rejected because the supported agents use different artifact layouts;
468
+ run one command per agent for custom locations.
469
+
442
470
  Installed locations:
443
471
 
444
472
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
package/README.zh-CN.md CHANGED
@@ -13,7 +13,7 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
- 下文命令跟随仓库版 `0.6.0`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
16
+ 下文命令跟随仓库版 `0.6.1`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
17
17
  GitHub 安装。
18
18
 
19
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
@@ -37,18 +37,18 @@ CLI/daemon、已安装的 Agent 技能、生成的 Chrome 插件和可选的本
37
37
 
38
38
  ### 更新 CLI、daemon 和 Agent 技能
39
39
 
40
- 先在启动 daemon 的终端中按 **Ctrl+C 手动停止 daemon**。目前没有 `pcbridge daemon stop`
41
- 命令。请记住该终端的工作目录,它就是 workspace 根目录,升级后必须回到同一目录启动。
42
-
43
40
  ```bash
44
41
  npm install -g playcanvas-agent-bridge-cli@latest
45
42
  pcbridge version
46
43
  pcbridge install-skill --agent all
47
- cd /原来的/workspace/根目录
48
- pcbridge daemon start
44
+ pcbridge daemon restart --workspace /原来的/workspace/根目录
49
45
  ```
50
46
 
51
47
  npm 全局安装会替换 CLI 文件,但已经运行的 daemon 仍然是内存中的旧版本,必须重启才会生效。
48
+ `daemon restart` 会先认证当前 pcbridge 服务,优雅关闭并等待端口释放,再在当前终端启动新
49
+ daemon。它不会因为某个进程占用了配置端口就直接杀掉该进程。从不支持认证关闭的旧版本升级
50
+ 时,第一次仍需在旧 daemon 终端按 **Ctrl+C**;完成这次迁移后即可使用 restart 切换和升级。
51
+
52
52
  Codex、Claude、Cursor 和 Windsurf 的技能文件也是安装时复制出去的,因此需要重新执行
53
53
  `install-skill`;如果当前 Agent 任务已经加载了旧技能,请新建一个任务或会话再使用新技能。
54
54
 
@@ -151,13 +151,26 @@ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
151
151
 
152
152
  ## 启动桥接
153
153
 
154
- 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
154
+ 可以使用当前目录作为 workspace 根目录,也可以显式指定目录:
155
155
 
156
156
  ```bash
157
157
  cd /path/to/my-playcanvas-workspace
158
158
  pcbridge daemon start
159
+
160
+ # 在任意目录执行,效果相同
161
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
162
+
163
+ # 停止当前 daemon 并切换 workspace
164
+ pcbridge daemon restart --workspace /path/to/another-workspace
165
+
166
+ # 优雅停止经过认证的 pcbridge daemon
167
+ pcbridge daemon stop
159
168
  ```
160
169
 
170
+ `daemon restart` 和 `daemon stop` 都会先校验带 token 的 `/health` 响应。token 不匹配或端口上
171
+ 不是 pcbridge 服务时,命令会报错且不会终止占用端口的进程。`start` 和 `restart` 都以前台
172
+ 方式运行,日志仍然直接显示在终端中,也仍然可以使用 **Ctrl+C** 停止。
173
+
161
174
  连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
162
175
 
163
176
  ```text
@@ -430,6 +443,18 @@ pcbridge install-skill --agent windsurf
430
443
  pcbridge install-skill --agent all
431
444
  ```
432
445
 
446
+ 使用 `--path` 可以把单个 Agent 的 skill 或 rule 安装到自定义父目录。相对路径从当前工作目录
447
+ 解析;pcbridge 会自动追加标准目录名或文件名,因此不会清空用户传入的父目录:
448
+
449
+ ```bash
450
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
451
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
452
+ ```
453
+
454
+ 以上命令分别生成 `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` 和
455
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`。Windows 路径包含空格时必须使用引号。
456
+ 由于不同 Agent 的产物布局不同,`--agent all --path ...` 会被拒绝;自定义位置时请逐个安装。
457
+
433
458
  安装位置:
434
459
 
435
460
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
@@ -244,12 +244,17 @@ export class BuilderManager {
244
244
  #requestTarget;
245
245
  #workspace;
246
246
  #jobs = new Map();
247
+ #activeRuns = new Set();
248
+ #activeClients = new Set();
249
+ #closing = false;
247
250
  constructor(options) {
248
251
  this.rootDir = options.rootDir;
249
252
  this.#requestTarget = options.requestTarget;
250
253
  this.#workspace = options.workspace;
251
254
  }
252
255
  start(info, templateAssetId, options = {}) {
256
+ if (this.#closing)
257
+ throw new Error("Tiny Builder is stopping with the daemon.");
253
258
  const now = new Date().toISOString();
254
259
  const job = {
255
260
  id: `build_${randomUUID()}`,
@@ -271,9 +276,17 @@ export class BuilderManager {
271
276
  this.#jobs.set(job.id, job);
272
277
  while (this.#jobs.size > 100)
273
278
  this.#jobs.delete(this.#jobs.keys().next().value);
274
- void this.#run(job);
279
+ const run = this.#run(job);
280
+ this.#activeRuns.add(run);
281
+ void run.finally(() => this.#activeRuns.delete(run));
275
282
  return this.#publicJob(job);
276
283
  }
284
+ async close() {
285
+ this.#closing = true;
286
+ for (const client of this.#activeClients)
287
+ client.destroy();
288
+ await Promise.allSettled(this.#activeRuns);
289
+ }
277
290
  get(jobId) {
278
291
  const job = this.#jobs.get(jobId);
279
292
  return job ? this.#publicJob(job) : null;
@@ -294,6 +307,8 @@ export class BuilderManager {
294
307
  async #run(job) {
295
308
  let activeClient = null;
296
309
  try {
310
+ if (this.#closing)
311
+ throw new Error("Build cancelled because the daemon is stopping.");
297
312
  this.#update(job, { state: "collecting", message: "Collecting Template dependencies" });
298
313
  const descriptors = new Map();
299
314
  const visit = async (assetId, stack) => {
@@ -354,6 +369,9 @@ export class BuilderManager {
354
369
  ]));
355
370
  const settings = await loadS3Settings(this.rootDir, prepared.projectDirectory);
356
371
  activeClient = settings.client;
372
+ this.#activeClients.add(activeClient);
373
+ if (this.#closing)
374
+ throw new Error("Build cancelled because the daemon is stopping.");
357
375
  job.configSource = settings.source;
358
376
  const prefix = normalizePrefix(job.options.prefix || settings.defaultPrefix);
359
377
  const uploads = new Map();
@@ -504,6 +522,8 @@ export class BuilderManager {
504
522
  const uploadFiles = [...uploads.values()];
505
523
  this.#update(job, { state: "uploading", message: `Uploading 0/${uploadFiles.length} files` });
506
524
  await mapWithConcurrency(uploadFiles, 4, async (file) => {
525
+ if (this.#closing)
526
+ throw new Error("Build cancelled because the daemon is stopping.");
507
527
  const info = await stat(file.path);
508
528
  const input = {
509
529
  Bucket: settings.bucket,
@@ -535,7 +555,10 @@ export class BuilderManager {
535
555
  });
536
556
  }
537
557
  finally {
538
- activeClient?.destroy();
558
+ if (activeClient) {
559
+ this.#activeClients.delete(activeClient);
560
+ activeClient.destroy();
561
+ }
539
562
  }
540
563
  }
541
564
  }
package/dist/cli.js CHANGED
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { spawn } from "node:child_process";
3
3
  import { realpathSync } from "node:fs";
4
- import { readFile, writeFile, mkdir } from "node:fs/promises";
4
+ import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
5
+ import { createConnection } from "node:net";
5
6
  import { homedir } from "node:os";
6
7
  import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
7
8
  import { fileURLToPath } from "node:url";
@@ -523,40 +524,182 @@ async function pathExists(path) {
523
524
  return false;
524
525
  }
525
526
  }
527
+ async function resolveDaemonWorkspace(args) {
528
+ const hasWorkspace = Object.prototype.hasOwnProperty.call(args.flags, "workspace");
529
+ const requested = flagString(args, "workspace")?.trim();
530
+ if (hasWorkspace && !requested) {
531
+ throw new Error("daemon --workspace requires a directory.");
532
+ }
533
+ const workspaceRoot = resolve(requested || process.cwd());
534
+ let info;
535
+ try {
536
+ info = await stat(workspaceRoot);
537
+ }
538
+ catch {
539
+ throw new Error(`Daemon workspace does not exist: ${workspaceRoot}`);
540
+ }
541
+ if (!info.isDirectory()) {
542
+ throw new Error(`Daemon workspace is not a directory: ${workspaceRoot}`);
543
+ }
544
+ return workspaceRoot;
545
+ }
546
+ function daemonLog(args, message) {
547
+ if (flagBool(args, "json")) {
548
+ process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), message })}\n`);
549
+ }
550
+ else {
551
+ process.stderr.write(`[pcbridge] ${message}\n`);
552
+ }
553
+ }
554
+ async function runDaemon(args, workspaceRoot, restarted) {
555
+ const session = await readOrCreateSession();
556
+ const port = session.port || DEFAULT_PORT;
557
+ const server = createDaemonServer({
558
+ host: DEFAULT_HOST,
559
+ port,
560
+ token: session.token,
561
+ workspaceRoot,
562
+ log: (message) => daemonLog(args, message),
563
+ });
564
+ try {
565
+ await server.listen();
566
+ }
567
+ catch (error) {
568
+ print(fail("PORT_BUSY", `Cannot listen on ${DEFAULT_HOST}:${port}. ${String(error)}`));
569
+ return;
570
+ }
571
+ const handleSignal = (signal) => {
572
+ daemonLog(args, `received ${signal}; stopping daemon`);
573
+ void server.close().catch((error) => {
574
+ daemonLog(args, `daemon shutdown failed: ${String(error)}`);
575
+ process.exitCode = 1;
576
+ });
577
+ };
578
+ const handleSigint = () => handleSignal("SIGINT");
579
+ const handleSigterm = () => handleSignal("SIGTERM");
580
+ process.once("SIGINT", handleSigint);
581
+ process.once("SIGTERM", handleSigterm);
582
+ print(ok({
583
+ version: VERSION,
584
+ host: DEFAULT_HOST,
585
+ port,
586
+ workspaceRoot,
587
+ restarted,
588
+ extensionPath: EXTENSION_INSTALL_DIR,
589
+ frontend: await server.frontend.status(),
590
+ }));
591
+ try {
592
+ await server.closed;
593
+ }
594
+ finally {
595
+ process.off("SIGINT", handleSigint);
596
+ process.off("SIGTERM", handleSigterm);
597
+ }
598
+ }
599
+ function isPortListening(port) {
600
+ return new Promise((resolveListening) => {
601
+ const socket = createConnection({ host: DEFAULT_HOST, port });
602
+ let settled = false;
603
+ const finish = (listening) => {
604
+ if (settled)
605
+ return;
606
+ settled = true;
607
+ socket.destroy();
608
+ resolveListening(listening);
609
+ };
610
+ socket.setTimeout(500);
611
+ socket.once("connect", () => finish(true));
612
+ socket.once("error", () => finish(false));
613
+ socket.once("timeout", () => finish(true));
614
+ });
615
+ }
616
+ async function waitForPortRelease(port, timeoutMs = 10000) {
617
+ const deadline = Date.now() + timeoutMs;
618
+ while (Date.now() < deadline) {
619
+ if (!await isPortListening(port))
620
+ return true;
621
+ await new Promise((resolveWait) => setTimeout(resolveWait, 50));
622
+ }
623
+ return !await isPortListening(port);
624
+ }
625
+ async function stopDaemon() {
626
+ const session = await readOrCreateSession();
627
+ const port = session.port || DEFAULT_PORT;
628
+ let health;
629
+ try {
630
+ health = await fetchDaemon("/health");
631
+ }
632
+ catch (error) {
633
+ if (error instanceof DaemonConnectionError &&
634
+ error.diagnosis.code === "DAEMON_NOT_LISTENING") {
635
+ return ok({ stopped: false, alreadyStopped: true, host: DEFAULT_HOST, port });
636
+ }
637
+ if (error instanceof DaemonConnectionError) {
638
+ return fail(error.diagnosis.code, error.diagnosis.message, undefined, { nextAction: error.diagnosis.nextAction });
639
+ }
640
+ return fail("DAEMON_UNREACHABLE", String(error));
641
+ }
642
+ if (!health.ok) {
643
+ if (health.error.code === "DAEMON_INVALID_RESPONSE") {
644
+ return fail("NOT_PCBRIDGE_DAEMON", `The listener on ${DEFAULT_HOST}:${port} is not a pcbridge daemon; it was not stopped.`);
645
+ }
646
+ return health;
647
+ }
648
+ const healthData = health.data && typeof health.data === "object" && !Array.isArray(health.data)
649
+ ? health.data
650
+ : {};
651
+ if (healthData.service !== "pcbridge-daemon") {
652
+ if (typeof healthData.version === "string" && typeof healthData.workspaceRoot === "string") {
653
+ return fail("DAEMON_SHUTDOWN_UNSUPPORTED", "The running pcbridge daemon does not support authenticated shutdown. Stop it once with Ctrl+C, then start the updated daemon.");
654
+ }
655
+ return fail("NOT_PCBRIDGE_DAEMON", `The listener on ${DEFAULT_HOST}:${port} is not a restartable pcbridge daemon; it was not stopped.`);
656
+ }
657
+ let response;
658
+ try {
659
+ response = await fetchDaemon("/shutdown", { method: "POST" });
660
+ }
661
+ catch (error) {
662
+ if (error instanceof DaemonConnectionError) {
663
+ return fail(error.diagnosis.code, error.diagnosis.message);
664
+ }
665
+ return fail("DAEMON_STOP_FAILED", String(error));
666
+ }
667
+ if (!response.ok)
668
+ return response;
669
+ if (!await waitForPortRelease(port)) {
670
+ return fail("DAEMON_STOP_TIMEOUT", `pcbridge daemon accepted shutdown, but ${DEFAULT_HOST}:${port} is still occupied. No process was forcefully terminated.`);
671
+ }
672
+ return ok({
673
+ stopped: true,
674
+ alreadyStopped: false,
675
+ host: DEFAULT_HOST,
676
+ port,
677
+ previousVersion: healthData.version || null,
678
+ previousWorkspaceRoot: healthData.workspaceRoot || null,
679
+ });
680
+ }
526
681
  async function daemon(args) {
527
682
  const subcommand = args._[1] || "status";
528
- if (subcommand === "start") {
529
- const session = await readOrCreateSession();
530
- const server = createDaemonServer({
531
- host: DEFAULT_HOST,
532
- port: session.port || DEFAULT_PORT,
533
- token: session.token,
534
- workspaceRoot: process.cwd(),
535
- log: (message) => {
536
- if (flagBool(args, "json")) {
537
- process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), message })}\n`);
538
- }
539
- else {
540
- process.stderr.write(`[pcbridge] ${message}\n`);
541
- }
542
- },
543
- });
683
+ if (subcommand === "start" || subcommand === "restart") {
684
+ let workspaceRoot;
544
685
  try {
545
- await server.listen();
686
+ workspaceRoot = await resolveDaemonWorkspace(args);
546
687
  }
547
688
  catch (error) {
548
- print(fail("PORT_BUSY", `Cannot listen on ${DEFAULT_HOST}:${session.port || DEFAULT_PORT}. ${String(error)}`));
549
- process.exitCode = 1;
689
+ print(fail("INVALID_WORKSPACE", String(error)));
550
690
  return;
551
691
  }
552
- print(ok({
553
- version: VERSION,
554
- host: DEFAULT_HOST,
555
- port: session.port || DEFAULT_PORT,
556
- workspaceRoot: process.cwd(),
557
- extensionPath: EXTENSION_INSTALL_DIR,
558
- frontend: await server.frontend.status(),
559
- }));
692
+ if (subcommand === "restart") {
693
+ const stopped = await stopDaemon();
694
+ if (!stopped.ok) {
695
+ print(stopped);
696
+ return;
697
+ }
698
+ }
699
+ await runDaemon(args, workspaceRoot, subcommand === "restart");
700
+ }
701
+ else if (subcommand === "stop") {
702
+ print(await stopDaemon());
560
703
  }
561
704
  else if (subcommand === "status") {
562
705
  try {
@@ -686,39 +829,49 @@ function openChromeExtensions() {
686
829
  }
687
830
  async function installSkill(args) {
688
831
  const agent = flagString(args, "agent", "codex") || "codex";
832
+ const supportedAgents = new Set(["codex", "claude", "cursor", "windsurf"]);
833
+ if (agent !== "all" && !supportedAgents.has(agent)) {
834
+ return fail("UNKNOWN_AGENT", `Unsupported agent: ${agent}. Use codex, claude, cursor, windsurf, or all.`);
835
+ }
836
+ const hasCustomPath = Object.prototype.hasOwnProperty.call(args.flags, "path");
837
+ const customPath = flagString(args, "path")?.trim();
838
+ if (hasCustomPath && !customPath) {
839
+ return fail("INVALID_REQUEST", "install-skill --path requires a parent directory.");
840
+ }
841
+ if (customPath && agent === "all") {
842
+ return fail("INVALID_REQUEST", "install-skill --path requires one explicit agent, not --agent all.");
843
+ }
844
+ const customParent = customPath ? resolve(customPath) : null;
689
845
  const root = await findPackageRoot();
690
846
  const installed = [];
691
847
  const agents = agent === "all" ? ["codex", "claude", "cursor", "windsurf"] : [agent];
692
848
  for (const item of agents) {
693
849
  if (item === "codex") {
694
- const dest = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
850
+ const dest = customParent || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
695
851
  const source = join(root, "skills", "codex", "playcanvas-agent-bridge-cli");
696
852
  const target = join(dest, "playcanvas-agent-bridge-cli");
697
853
  await copyDir(source, target, { clean: true });
698
854
  installed.push({ agent: item, path: target });
699
855
  }
700
856
  else if (item === "claude") {
701
- const target = join(homedir(), ".claude", "skills", "playcanvas-agent-bridge-cli");
857
+ const target = join(customParent || join(homedir(), ".claude", "skills"), "playcanvas-agent-bridge-cli");
702
858
  await copyDir(join(root, "skills", "claude", "playcanvas-agent-bridge-cli"), target, {
703
859
  clean: true,
704
860
  });
705
861
  installed.push({ agent: item, path: target });
706
862
  }
707
863
  else if (item === "cursor") {
708
- const target = join(homedir(), ".cursor", "rules", "playcanvas-agent-bridge-cli.mdc");
864
+ const target = join(customParent || join(homedir(), ".cursor", "rules"), "playcanvas-agent-bridge-cli.mdc");
709
865
  await mkdir(dirname(target), { recursive: true });
710
866
  await writeFile(target, await readFile(join(root, "skills", "cursor", "playcanvas-agent-bridge-cli.mdc")));
711
867
  installed.push({ agent: item, path: target });
712
868
  }
713
869
  else if (item === "windsurf") {
714
- const target = join(homedir(), ".windsurf", "rules", "playcanvas-agent-bridge-cli.md");
870
+ const target = join(customParent || join(homedir(), ".windsurf", "rules"), "playcanvas-agent-bridge-cli.md");
715
871
  await mkdir(dirname(target), { recursive: true });
716
872
  await writeFile(target, await readFile(join(root, "skills", "windsurf", "playcanvas-agent-bridge-cli.md")));
717
873
  installed.push({ agent: item, path: target });
718
874
  }
719
- else {
720
- return fail("UNKNOWN_AGENT", `Unsupported agent: ${item}. Use codex, claude, cursor, windsurf, or all.`);
721
- }
722
875
  }
723
876
  return ok(installed);
724
877
  }
@@ -1468,8 +1621,11 @@ function help(group = "overview") {
1468
1621
  core: [
1469
1622
  "pcbridge doctor",
1470
1623
  "pcbridge install-extension",
1471
- "pcbridge install-skill --agent codex|claude|cursor|windsurf|all",
1472
- "pcbridge daemon start",
1624
+ "pcbridge install-skill --agent codex|claude|cursor|windsurf|all [--path <parent_directory>]",
1625
+ "--path is allowed only with one agent and appends the standard skill/rule name.",
1626
+ "pcbridge daemon start [--workspace <directory>]",
1627
+ "pcbridge daemon restart [--workspace <directory>]",
1628
+ "pcbridge daemon stop",
1473
1629
  "pcbridge daemon status",
1474
1630
  "pcbridge targets",
1475
1631
  "pcbridge version",
@@ -1485,7 +1641,7 @@ function help(group = "overview") {
1485
1641
  "pcbridge workspace path --target editor:<sceneId>",
1486
1642
  "pcbridge workspace sync --target editor:<sceneId>",
1487
1643
  "pcbridge workspace pull --target editor:<sceneId> --asset <assetId>",
1488
- "The directory where `pcbridge daemon start` runs is the workspace root.",
1644
+ "daemon start/restart uses --workspace when provided, otherwise the current directory.",
1489
1645
  ],
1490
1646
  builder: [
1491
1647
  "pcbridge builder start --target editor:<sceneId> --asset <template_asset_id> [--suffix '-${time}'] [--prefix assets]",
package/dist/config.js CHANGED
@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
4
4
  import { homedir } from "node:os";
5
5
  import { dirname, join, resolve } from "node:path";
6
6
  import { fileURLToPath } from "node:url";
7
- export const VERSION = "0.6.0";
7
+ export const VERSION = "0.6.1";
8
8
  export const DEFAULT_HOST = "127.0.0.1";
9
9
  export const DEFAULT_PORT = 17329;
10
10
  export const DEFAULT_FRONTEND_PORT = 3487;
@@ -114,6 +114,11 @@ export function createDaemonServer(options) {
114
114
  }),
115
115
  workspace,
116
116
  });
117
+ let resolveClosed;
118
+ const closed = new Promise((resolvePromise) => {
119
+ resolveClosed = resolvePromise;
120
+ });
121
+ let closePromise = null;
117
122
  const server = http.createServer(async (req, res) => {
118
123
  try {
119
124
  const url = new URL(req.url || "/", `http://${req.headers.host || `${host}:${port}`}`);
@@ -124,6 +129,7 @@ export function createDaemonServer(options) {
124
129
  }
125
130
  const frontendStatus = await frontend.status();
126
131
  writeJson(res, 200, ok({
132
+ service: "pcbridge-daemon",
127
133
  version: VERSION,
128
134
  host,
129
135
  port: actualPort,
@@ -133,6 +139,26 @@ export function createDaemonServer(options) {
133
139
  }));
134
140
  return;
135
141
  }
142
+ if (url.pathname === "/shutdown" && req.method === "POST") {
143
+ if (!requireToken(req)) {
144
+ writeJson(res, 403, fail("BAD_TOKEN", "Invalid pcbridge token."));
145
+ return;
146
+ }
147
+ writeJson(res, 200, ok({
148
+ service: "pcbridge-daemon",
149
+ stopping: true,
150
+ version: VERSION,
151
+ workspaceRoot: workspace.rootDir,
152
+ }));
153
+ res.once("finish", () => {
154
+ setImmediate(() => {
155
+ void closeDaemon().catch((error) => {
156
+ log(`daemon shutdown failed: ${String(error)}`);
157
+ });
158
+ });
159
+ });
160
+ return;
161
+ }
136
162
  if (url.pathname === "/frontend/status" && req.method === "GET") {
137
163
  if (!requireToken(req)) {
138
164
  writeJson(res, 403, fail("BAD_TOKEN", "Invalid pcbridge token."));
@@ -373,6 +399,50 @@ export function createDaemonServer(options) {
373
399
  }
374
400
  });
375
401
  });
402
+ function closeDaemon() {
403
+ if (closePromise)
404
+ return closePromise;
405
+ closePromise = (async () => {
406
+ clearInterval(pingTimer);
407
+ for (const waiter of pending.values()) {
408
+ clearTimeout(waiter.timer);
409
+ waiter.resolve(fail("DAEMON_STOPPING", "pcbridge daemon is stopping."));
410
+ }
411
+ pending.clear();
412
+ const builderCleanup = await Promise.allSettled([builder.close()]);
413
+ const cleanupResults = [
414
+ ...builderCleanup,
415
+ ...await Promise.allSettled([
416
+ workspace.close(),
417
+ frontend.close(),
418
+ ]),
419
+ ];
420
+ for (const client of wss.clients) {
421
+ client.close(1001, "pcbridge daemon is stopping");
422
+ }
423
+ const forceCloseTimer = setTimeout(() => {
424
+ for (const client of wss.clients)
425
+ client.terminate();
426
+ }, 250);
427
+ await Promise.all([
428
+ new Promise((resolveClose) => {
429
+ wss.close(() => resolveClose());
430
+ }),
431
+ new Promise((resolveClose) => {
432
+ if (!server.listening) {
433
+ resolveClose();
434
+ return;
435
+ }
436
+ server.close(() => resolveClose());
437
+ }),
438
+ ]);
439
+ clearTimeout(forceCloseTimer);
440
+ const failedCleanup = cleanupResults.find((result) => result.status === "rejected");
441
+ if (failedCleanup)
442
+ throw failedCleanup.reason;
443
+ })().finally(resolveClosed);
444
+ return closePromise;
445
+ }
376
446
  return {
377
447
  host,
378
448
  get port() {
@@ -382,6 +452,7 @@ export function createDaemonServer(options) {
382
452
  frontend,
383
453
  workspace,
384
454
  builder,
455
+ closed,
385
456
  listen: async () => {
386
457
  await new Promise((resolveListen, reject) => {
387
458
  server.once("error", reject);
@@ -400,14 +471,6 @@ export function createDaemonServer(options) {
400
471
  log(`frontend server unavailable: ${String(error)}`);
401
472
  }
402
473
  },
403
- close: async () => {
404
- clearInterval(pingTimer);
405
- await workspace.close();
406
- await frontend.close();
407
- await new Promise((resolveClose) => {
408
- wss.close();
409
- server.close(() => resolveClose());
410
- });
411
- },
474
+ close: closeDaemon,
412
475
  };
413
476
  }
@@ -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.6.0",
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.6.0",
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",
@@ -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.
@@ -33,13 +34,17 @@ project-picker and scene Editor navigations; change the remembered mode only thr
33
34
  The CLI/daemon, copied agent skills, generated Chrome extension, and custom Editor frontend update
34
35
  independently. For an explicit update request:
35
36
 
36
- 1. Have the user stop the foreground daemon with Ctrl+C and preserve its working directory; no
37
- `daemon stop` command exists.
37
+ 1. Record the workspace root reported by `pcbridge daemon status`.
38
38
  2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
39
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`.
40
43
  3. Run `pcbridge install-extension --no-open`; the user must click **Reload** in
41
44
  `chrome://extensions` and refresh every open Editor/Launch tab.
42
- 4. Restart the daemon from the same workspace root and verify `pcbridge doctor`.
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.
43
48
  5. Use `pcbridge frontend update` plus `frontend status` for the separately published Editor build.
44
49
  That update is read dynamically by a running daemon, but the user must refresh the Editor page
45
50
  and choose **Use custom frontend** in the popup if official mode is selected.
@@ -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
 
@@ -42,14 +44,18 @@ project-picker and scene Editor navigations; change the remembered mode only thr
42
44
  Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
43
45
  as separate components. When the user asks to update pcbridge:
44
46
 
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
+ 1. Record the current workspace root from `pcbridge daemon status`.
47
48
  2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
48
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`.
49
53
  3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
50
54
  Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
51
55
  directory is not enough.
52
- 4. Restart `pcbridge daemon start` from the original workspace root and verify with `pcbridge doctor`.
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.
53
59
  5. Update the independently published Editor build with `pcbridge frontend update`, then verify
54
60
  `frontend status`. A frontend-only update does not require daemon restart, but the user must
55
61
  refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
@@ -17,18 +17,22 @@ 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
20
+ Updates are component-specific. For an explicit update request, record the workspace root from
21
+ `pcbridge daemon status`. Run
22
22
  `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
- `pcbridge install-skill --agent all`. Regenerate the extension with
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
24
26
  `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
+ `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
27
30
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
28
31
  but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
29
32
  claim completion before these manual steps are confirmed.
30
33
 
31
- The daemon start directory is the workspace root. After selecting an explicit target, run
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
32
36
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
33
37
  or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
34
38
  operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
@@ -13,18 +13,22 @@ 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
16
+ Updates are component-specific. For an explicit update request, record the workspace root from
17
+ `pcbridge daemon status`. Run
18
18
  `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
19
- `pcbridge install-skill --agent all`. Regenerate the extension with
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
20
22
  `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
+ `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
23
26
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
24
27
  but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
25
28
  claim completion before these manual steps are confirmed.
26
29
 
27
- The daemon start directory is the workspace root. After selecting an explicit target, run
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
28
32
  `pcbridge workspace status --target editor:<sceneId>` and stop if it reports a conflict or sync
29
33
  error. Each project is mirrored under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
30
34
  operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to