playcanvas-agent-bridge-cli 0.3.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -3,12 +3,12 @@ import { spawn } from "node:child_process";
3
3
  import { realpathSync } from "node:fs";
4
4
  import { readFile, writeFile, mkdir } from "node:fs/promises";
5
5
  import { homedir } from "node:os";
6
- import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
6
+ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
  import { CONFIG_DIR, DEFAULT_FRONTEND_PORT, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
9
9
  import { createDaemonServer } from "./daemon/server.js";
10
10
  import { FrontendError, getFrontendStatus, installFrontend, listFrontends, removeFrontend, useFrontend, } from "./frontend/store.js";
11
- import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateCreateSnippet, } from "./snippets.js";
11
+ import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateApplySnippet, templateCreateSnippet, templateOverridesSnippet, } from "./snippets.js";
12
12
  import { fail, ok } from "./shared/protocol.js";
13
13
  function parseArgs(argv) {
14
14
  const parsed = { _: [], flags: {} };
@@ -68,6 +68,53 @@ function flagList(args, name) {
68
68
  }
69
69
  function print(value) {
70
70
  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
71
+ if (!value.ok)
72
+ process.exitCode = 1;
73
+ }
74
+ function nestedErrorCode(error) {
75
+ if (!error || typeof error !== "object")
76
+ return undefined;
77
+ const candidate = error;
78
+ if (typeof candidate.code === "string")
79
+ return candidate.code;
80
+ return nestedErrorCode(candidate.cause);
81
+ }
82
+ export function diagnoseDaemonConnection(error, port = DEFAULT_PORT) {
83
+ const code = nestedErrorCode(error) || "DAEMON_UNREACHABLE";
84
+ if (code === "EACCES" || code === "EPERM") {
85
+ return {
86
+ code: "LOOPBACK_ACCESS_DENIED",
87
+ message: `Daemon may be running, but this process cannot access ${DEFAULT_HOST}:${port}.`,
88
+ nextAction: "Retry from an execution context with local-loopback permission.",
89
+ };
90
+ }
91
+ if (code === "ECONNREFUSED") {
92
+ return {
93
+ code: "DAEMON_NOT_LISTENING",
94
+ message: `No pcbridge daemon is listening on ${DEFAULT_HOST}:${port}.`,
95
+ nextAction: "Run pcbridge daemon start in a terminal.",
96
+ };
97
+ }
98
+ if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
99
+ return {
100
+ code: "DAEMON_HOST_UNRESOLVED",
101
+ message: `The configured pcbridge daemon host could not be resolved (${code}).`,
102
+ nextAction: "Check the generated pcbridge session configuration.",
103
+ };
104
+ }
105
+ return {
106
+ code: "DAEMON_UNREACHABLE",
107
+ message: `The pcbridge daemon is not reachable (${code}).`,
108
+ nextAction: "Check pcbridge daemon status, then start it if no listener is running.",
109
+ };
110
+ }
111
+ class DaemonConnectionError extends Error {
112
+ diagnosis;
113
+ constructor(diagnosis, cause) {
114
+ super(diagnosis.message, { cause });
115
+ this.name = "DaemonConnectionError";
116
+ this.diagnosis = diagnosis;
117
+ }
71
118
  }
72
119
  async function readStdin() {
73
120
  const chunks = [];
@@ -82,7 +129,7 @@ async function readCode(args) {
82
129
  if (code !== undefined)
83
130
  return code;
84
131
  if (file)
85
- return readFile(file, "utf8");
132
+ return readFile(await resolveWorkspaceFile(args, file, "eval file"), "utf8");
86
133
  if (flagBool(args, "stdin"))
87
134
  return readStdin();
88
135
  throw new Error("Provide --code, --file, or --stdin.");
@@ -109,19 +156,74 @@ function parseSets(values) {
109
156
  }
110
157
  async function fetchDaemon(path, init = {}) {
111
158
  const session = await readOrCreateSession();
112
- const response = await fetch(`http://${DEFAULT_HOST}:${session.port || DEFAULT_PORT}${path}`, {
113
- ...init,
114
- headers: {
115
- "Content-Type": "application/json",
116
- "X-PCBridge-Token": session.token,
117
- ...(init.headers || {}),
118
- },
119
- });
120
- const body = (await response.json());
121
- return body;
159
+ const port = session.port || DEFAULT_PORT;
160
+ let response;
161
+ try {
162
+ response = await fetch(`http://${DEFAULT_HOST}:${port}${path}`, {
163
+ ...init,
164
+ headers: {
165
+ "Content-Type": "application/json",
166
+ "X-PCBridge-Token": session.token,
167
+ ...(init.headers || {}),
168
+ },
169
+ });
170
+ }
171
+ catch (error) {
172
+ throw new DaemonConnectionError(diagnoseDaemonConnection(error, port), error);
173
+ }
174
+ try {
175
+ return (await response.json());
176
+ }
177
+ catch {
178
+ return fail("DAEMON_INVALID_RESPONSE", `pcbridge daemon returned a non-JSON response (HTTP ${response.status}).`, undefined, { status: response.status, path });
179
+ }
180
+ }
181
+ async function resolveWorkspaceFile(args, path, label) {
182
+ const resolvedPath = resolve(path);
183
+ if (flagBool(args, "allow-external-path"))
184
+ return resolvedPath;
185
+ const target = flagString(args, "target", "current") || "current";
186
+ const response = await fetchDaemon(`/workspace/status?target=${encodeURIComponent(target)}`);
187
+ if (!response.ok)
188
+ throw new Error(response.error.message);
189
+ const status = objectJson(response.data, "workspace status");
190
+ const projectDirectory = typeof status.projectDirectory === "string"
191
+ ? resolve(status.projectDirectory)
192
+ : null;
193
+ if (!projectDirectory) {
194
+ throw new Error(`${label} requires an initialized project workspace. ` +
195
+ "Use --allow-external-path only for an intentional external file.");
196
+ }
197
+ let checkedPath = resolvedPath;
198
+ try {
199
+ checkedPath = realpathSync(resolvedPath);
200
+ }
201
+ catch {
202
+ let ancestor = dirname(resolvedPath);
203
+ while (ancestor !== dirname(ancestor)) {
204
+ try {
205
+ const realAncestor = realpathSync(ancestor);
206
+ checkedPath = resolve(realAncestor, relative(ancestor, resolvedPath));
207
+ break;
208
+ }
209
+ catch {
210
+ ancestor = dirname(ancestor);
211
+ }
212
+ }
213
+ }
214
+ const checkedProject = realpathSync(projectDirectory);
215
+ if (checkedPath !== checkedProject && !checkedPath.startsWith(`${checkedProject}${sep}`)) {
216
+ throw new Error(`${label} must be inside ${checkedProject}. ` +
217
+ "Use --allow-external-path to override this workspace guard.");
218
+ }
219
+ return resolvedPath;
122
220
  }
123
- async function rpcCall(args, method, params = {}, defaultTimeoutMs = 15000) {
124
- const timeoutMs = Number(flagString(args, "timeout-ms", String(defaultTimeoutMs)));
221
+ async function rpcCall(args, method, params = {}, defaultTimeoutMs = 15000, honorTimeoutFlag = true) {
222
+ const timeoutMs = honorTimeoutFlag
223
+ ? readTimeoutMs(args, defaultTimeoutMs)
224
+ : defaultTimeoutMs;
225
+ if (timeoutMs === null)
226
+ return invalidTimeoutEnvelope();
125
227
  return fetchDaemon("/rpc", {
126
228
  method: "POST",
127
229
  body: JSON.stringify({
@@ -135,10 +237,35 @@ async function rpcCall(args, method, params = {}, defaultTimeoutMs = 15000) {
135
237
  }),
136
238
  });
137
239
  }
240
+ function readTimeoutMs(args, defaultTimeoutMs) {
241
+ const value = Number(flagString(args, "timeout-ms", String(defaultTimeoutMs)));
242
+ return Number.isInteger(value) && value >= 1000 && value <= 120000 ? value : null;
243
+ }
244
+ function invalidTimeoutEnvelope() {
245
+ return fail("INVALID_REQUEST", "--timeout-ms must be an integer from 1000 to 120000.");
246
+ }
138
247
  async function rpcEval(args, code, commandArgs = {}, defaultTimeoutMs = 15000) {
248
+ const serializeOptions = {};
249
+ const optionFlags = [
250
+ ["max-depth", "maxDepth", 1, 20],
251
+ ["max-items", "maxArray", 1, 5000],
252
+ ["max-keys", "maxKeys", 1, 2000],
253
+ ["max-string", "maxString", 1, 100000],
254
+ ];
255
+ for (const [flag, key, minimum, maximum] of optionFlags) {
256
+ const raw = flagString(args, flag);
257
+ if (raw === undefined)
258
+ continue;
259
+ const value = Number(raw);
260
+ if (!Number.isInteger(value) || value < minimum || value > maximum) {
261
+ return fail("INVALID_REQUEST", `--${flag} must be an integer from ${minimum} to ${maximum}.`);
262
+ }
263
+ serializeOptions[key] = value;
264
+ }
139
265
  return rpcCall(args, "bridge:eval", {
140
266
  code,
141
267
  args: commandArgs,
268
+ serializeOptions: serializeOptions,
142
269
  }, defaultTimeoutMs);
143
270
  }
144
271
  function listEnvelope(raw) {
@@ -201,7 +328,8 @@ async function readJsonFlag(args, flagName) {
201
328
  const file = flagString(args, flagName);
202
329
  if (!file)
203
330
  return undefined;
204
- return JSON.parse(await readFile(file, "utf8"));
331
+ const path = await resolveWorkspaceFile(args, file, `--${flagName}`);
332
+ return JSON.parse(await readFile(path, "utf8"));
205
333
  }
206
334
  function objectJson(value, label) {
207
335
  if (value === undefined || value === null)
@@ -235,6 +363,7 @@ function resolveManifestFile(manifestPath, file) {
235
363
  return isAbsolute(file) ? file : resolve(dirname(manifestPath), file);
236
364
  }
237
365
  async function uploadAsset(args, spec) {
366
+ spec.file = await resolveWorkspaceFile(args, spec.file, "asset upload file");
238
367
  const fileBuffer = await readFile(spec.file);
239
368
  const type = spec.type || inferAssetType(spec.file);
240
369
  if (!type)
@@ -256,6 +385,8 @@ async function doctor() {
256
385
  const checks = [];
257
386
  const nextActions = [];
258
387
  const major = Number(process.versions.node.split(".", 1)[0]);
388
+ let daemonOk = false;
389
+ let connectedExtensionVersionsOk = true;
259
390
  checks.push({
260
391
  name: "node",
261
392
  ok: major >= 20,
@@ -267,20 +398,42 @@ async function doctor() {
267
398
  }
268
399
  try {
269
400
  const health = await fetchDaemon("/health");
401
+ const daemonData = health.ok ? objectJson(health.data, "daemon health") : null;
402
+ const daemonVersion = daemonData && typeof daemonData.version === "string"
403
+ ? daemonData.version
404
+ : null;
405
+ daemonOk = health.ok && daemonVersion === VERSION;
270
406
  checks.push({
271
407
  name: "daemon",
272
- ok: health.ok,
273
- message: health.ok ? "Daemon is reachable." : health.error.message,
408
+ ok: daemonOk,
409
+ code: health.ok ? null : health.error.code,
410
+ version: daemonVersion,
411
+ expectedVersion: VERSION,
412
+ message: !health.ok
413
+ ? health.error.message
414
+ : daemonVersion === VERSION
415
+ ? "Daemon is reachable and matches the CLI version."
416
+ : "Daemon is reachable but its version does not match the CLI.",
274
417
  data: health.ok ? health.data : null,
275
418
  });
419
+ if (!health.ok && health.error.code === "BAD_TOKEN") {
420
+ nextActions.push("Stop the stale daemon, start it again with this pcbridge install, then regenerate/reload the extension.");
421
+ }
422
+ else if (health.ok && daemonVersion !== VERSION) {
423
+ nextActions.push("Restart the daemon with the same pcbridge version as this CLI.");
424
+ }
276
425
  }
277
426
  catch (error) {
427
+ const diagnosis = error instanceof DaemonConnectionError
428
+ ? error.diagnosis
429
+ : diagnoseDaemonConnection(error);
278
430
  checks.push({
279
431
  name: "daemon",
280
432
  ok: false,
281
- message: "Daemon is not reachable.",
433
+ code: diagnosis.code,
434
+ message: diagnosis.message,
282
435
  });
283
- nextActions.push("Run pcbridge daemon start in a terminal.");
436
+ nextActions.push(diagnosis.nextAction);
284
437
  }
285
438
  const frontend = await getFrontendStatus();
286
439
  checks.push({
@@ -331,6 +484,7 @@ async function doctor() {
331
484
  .map((target) => (target && typeof target === "object" && !Array.isArray(target) ? target.extensionVersion : null))
332
485
  .filter(Boolean);
333
486
  const mismatched = connectedVersions.filter((version) => version !== VERSION);
487
+ connectedExtensionVersionsOk = mismatched.length === 0;
334
488
  checks.push({
335
489
  name: "connected-extension-version",
336
490
  ok: mismatched.length === 0,
@@ -350,6 +504,11 @@ async function doctor() {
350
504
  }
351
505
  return ok({
352
506
  version: VERSION,
507
+ healthy: major >= 20 &&
508
+ daemonOk &&
509
+ extensionExists &&
510
+ generatedExtensionVersion === VERSION &&
511
+ connectedExtensionVersionsOk,
353
512
  configDir: CONFIG_DIR,
354
513
  checks,
355
514
  nextActions,
@@ -372,6 +531,7 @@ async function daemon(args) {
372
531
  host: DEFAULT_HOST,
373
532
  port: session.port || DEFAULT_PORT,
374
533
  token: session.token,
534
+ workspaceRoot: process.cwd(),
375
535
  log: (message) => {
376
536
  if (flagBool(args, "json")) {
377
537
  process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), message })}\n`);
@@ -393,6 +553,7 @@ async function daemon(args) {
393
553
  version: VERSION,
394
554
  host: DEFAULT_HOST,
395
555
  port: session.port || DEFAULT_PORT,
556
+ workspaceRoot: process.cwd(),
396
557
  extensionPath: EXTENSION_INSTALL_DIR,
397
558
  frontend: await server.frontend.status(),
398
559
  }));
@@ -583,14 +744,14 @@ async function handleEntity(args) {
583
744
  const file = flagString(args, "json");
584
745
  if (!file)
585
746
  return fail("INVALID_REQUEST", "entity create requires --json <file>.");
586
- const data = JSON.parse(await readFile(file, "utf8"));
747
+ const data = JSON.parse(await readFile(await resolveWorkspaceFile(args, file, "entity JSON"), "utf8"));
587
748
  return rpcEval(args, entityCreateSnippet(), { data });
588
749
  }
589
750
  if (subcommand === "create-many") {
590
751
  const file = flagString(args, "json");
591
752
  if (!file)
592
753
  return fail("INVALID_REQUEST", "entity create-many requires --json <file>.");
593
- const data = JSON.parse(await readFile(file, "utf8"));
754
+ const data = JSON.parse(await readFile(await resolveWorkspaceFile(args, file, "entity JSON"), "utf8"));
594
755
  const entities = Array.isArray(data)
595
756
  ? data
596
757
  : objectJson(data, "entity create-many data").entities;
@@ -606,7 +767,7 @@ async function handleEntity(args) {
606
767
  const file = flagString(args, "json");
607
768
  if (!file)
608
769
  return fail("INVALID_REQUEST", "entity patch-many requires --json <file>.");
609
- const data = JSON.parse(await readFile(file, "utf8"));
770
+ const data = JSON.parse(await readFile(await resolveWorkspaceFile(args, file, "entity JSON"), "utf8"));
610
771
  const edits = Array.isArray(data)
611
772
  ? data
612
773
  : objectJson(data, "entity patch-many data").edits;
@@ -711,12 +872,17 @@ async function handleEntity(args) {
711
872
  const id = flagString(args, "id");
712
873
  if (!id)
713
874
  return fail("INVALID_REQUEST", "entity add-script requires --id.");
875
+ const scriptName = flagString(args, "script-name");
876
+ const assetId = flagString(args, "asset-id");
877
+ if (Boolean(scriptName) === Boolean(assetId)) {
878
+ return fail("INVALID_REQUEST", "entity add-script requires exactly one of --asset-id or --script-name.");
879
+ }
714
880
  const attributes = (await readJsonFlag(args, "attributes-json")) ??
715
881
  (flagString(args, "attributes") ? parseJsonValue(flagString(args, "attributes") || "{}") : {});
716
882
  return rpcEval(args, entityAddScriptSnippet(), {
717
883
  id,
718
- scriptName: flagString(args, "script-name") || null,
719
- assetId: flagString(args, "asset-id") || null,
884
+ scriptName: scriptName || null,
885
+ assetId: assetId || null,
720
886
  attributes: objectJson(attributes, "script attributes"),
721
887
  enabled: !flagBool(args, "disabled"),
722
888
  });
@@ -745,7 +911,7 @@ async function handleAsset(args) {
745
911
  const file = flagString(args, "json");
746
912
  if (!file)
747
913
  return fail("INVALID_REQUEST", "asset create requires --json <file>.");
748
- const data = JSON.parse(await readFile(file, "utf8"));
914
+ const data = JSON.parse(await readFile(await resolveWorkspaceFile(args, file, "asset JSON"), "utf8"));
749
915
  const assets = Array.isArray(data)
750
916
  ? data
751
917
  : objectJson(data, "asset create data").assets || [data];
@@ -786,7 +952,8 @@ async function handleAsset(args) {
786
952
  const manifestPath = flagString(args, "json");
787
953
  if (!manifestPath)
788
954
  return fail("INVALID_REQUEST", "asset upload-many requires --json <file>.");
789
- const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
955
+ const safeManifestPath = await resolveWorkspaceFile(args, manifestPath, "upload manifest");
956
+ const manifest = JSON.parse(await readFile(safeManifestPath, "utf8"));
790
957
  const rawItems = Array.isArray(manifest)
791
958
  ? manifest
792
959
  : objectJson(manifest, "asset upload-many manifest").assets;
@@ -798,7 +965,7 @@ async function handleAsset(args) {
798
965
  const errors = [];
799
966
  for (let index = 0; index < items.length; index += 1) {
800
967
  const spec = uploadSpecFromJson(items[index], `assets[${index}]`);
801
- spec.file = resolveManifestFile(manifestPath, spec.file);
968
+ spec.file = resolveManifestFile(safeManifestPath, spec.file);
802
969
  const result = await uploadAsset(args, spec);
803
970
  uploads.push({
804
971
  index,
@@ -906,6 +1073,52 @@ async function handleTemplate(args) {
906
1073
  id: id || null,
907
1074
  }, 60000);
908
1075
  }
1076
+ if (subcommand === "overrides") {
1077
+ const entityId = flagString(args, "entity-id") || flagString(args, "id");
1078
+ if (!entityId)
1079
+ return fail("INVALID_REQUEST", "template overrides requires --entity-id.");
1080
+ return rpcEval(args, templateOverridesSnippet(), { entityId });
1081
+ }
1082
+ if (subcommand === "apply") {
1083
+ const entityId = flagString(args, "entity-id") || flagString(args, "id");
1084
+ if (!entityId)
1085
+ return fail("INVALID_REQUEST", "template apply requires --entity-id.");
1086
+ const waitTimeoutMs = readTimeoutMs(args, 60000);
1087
+ if (waitTimeoutMs === null)
1088
+ return invalidTimeoutEnvelope();
1089
+ return rpcEval(args, templateApplySnippet(), {
1090
+ entityId,
1091
+ waitTimeoutMs,
1092
+ }, 60000);
1093
+ }
1094
+ if (subcommand === "apply-many") {
1095
+ const input = await readJsonFlag(args, "json");
1096
+ if (input === undefined) {
1097
+ return fail("INVALID_REQUEST", "template apply-many requires --json <file>.");
1098
+ }
1099
+ const values = Array.isArray(input)
1100
+ ? input
1101
+ : Array.isArray(objectJson(input, "template apply manifest").entityIds)
1102
+ ? objectJson(input, "template apply manifest").entityIds
1103
+ : [];
1104
+ const entityIds = values.map((value) => {
1105
+ if (typeof value === "string" || typeof value === "number")
1106
+ return String(value);
1107
+ const item = objectJson(value, "template apply item");
1108
+ const id = item.entityId ?? item.id;
1109
+ return typeof id === "string" || typeof id === "number" ? String(id) : "";
1110
+ }).filter(Boolean);
1111
+ if (!entityIds.length) {
1112
+ return fail("INVALID_REQUEST", "template apply-many JSON must be an array of entity ids/items or {\"entityIds\":[...] }.");
1113
+ }
1114
+ const waitTimeoutMs = readTimeoutMs(args, 120000);
1115
+ if (waitTimeoutMs === null)
1116
+ return invalidTimeoutEnvelope();
1117
+ return rpcEval(args, templateApplySnippet(), {
1118
+ entityIds: entityIds,
1119
+ waitTimeoutMs,
1120
+ }, 120000);
1121
+ }
909
1122
  return fail("UNKNOWN_COMMAND", `Unknown template command: ${subcommand || ""}`);
910
1123
  }
911
1124
  async function handleScript(args) {
@@ -916,13 +1129,18 @@ async function handleScript(args) {
916
1129
  if (!filename || !file) {
917
1130
  return fail("INVALID_REQUEST", "script upsert requires --filename and --file.");
918
1131
  }
1132
+ const waitTimeoutMs = readTimeoutMs(args, 60000);
1133
+ if (waitTimeoutMs === null)
1134
+ return invalidTimeoutEnvelope();
919
1135
  return rpcEval(args, scriptUpsertSnippet(), {
920
1136
  filename,
921
- text: await readFile(file, "utf8"),
1137
+ text: await readFile(await resolveWorkspaceFile(args, file, "script file"), "utf8"),
922
1138
  folder: flagString(args, "folder") || null,
923
1139
  folderId: flagString(args, "folder-id") || null,
924
1140
  preload: !flagBool(args, "no-preload"),
925
1141
  parse: flagBool(args, "parse"),
1142
+ wait: flagBool(args, "wait"),
1143
+ waitTimeoutMs,
926
1144
  }, 60000);
927
1145
  }
928
1146
  if (subcommand === "create") {
@@ -933,7 +1151,7 @@ async function handleScript(args) {
933
1151
  }
934
1152
  return rpcEval(args, scriptCreateSnippet(), {
935
1153
  filename,
936
- text: await readFile(file, "utf8"),
1154
+ text: await readFile(await resolveWorkspaceFile(args, file, "script file"), "utf8"),
937
1155
  folder: flagString(args, "folder") || null,
938
1156
  folderId: flagString(args, "folder-id") || null,
939
1157
  preload: !flagBool(args, "no-preload"),
@@ -945,16 +1163,26 @@ async function handleScript(args) {
945
1163
  if (!assetId || !file) {
946
1164
  return fail("INVALID_REQUEST", "script set-text requires --asset-id and --file.");
947
1165
  }
1166
+ const waitTimeoutMs = readTimeoutMs(args, 60000);
1167
+ if (waitTimeoutMs === null)
1168
+ return invalidTimeoutEnvelope();
948
1169
  return rpcEval(args, scriptSetTextSnippet(), {
949
1170
  assetId,
950
- text: await readFile(file, "utf8"),
951
- });
1171
+ filename: basename(file),
1172
+ text: await readFile(await resolveWorkspaceFile(args, file, "script file"), "utf8"),
1173
+ parse: flagBool(args, "parse"),
1174
+ wait: flagBool(args, "wait"),
1175
+ waitTimeoutMs,
1176
+ }, 60000);
952
1177
  }
953
1178
  if (subcommand === "parse") {
954
1179
  const assetId = flagString(args, "asset-id");
955
1180
  if (!assetId)
956
1181
  return fail("INVALID_REQUEST", "script parse requires --asset-id.");
957
- return rpcEval(args, scriptParseSnippet(), { assetId });
1182
+ const waitTimeoutMs = readTimeoutMs(args, 60000);
1183
+ if (waitTimeoutMs === null)
1184
+ return invalidTimeoutEnvelope();
1185
+ return rpcEval(args, scriptParseSnippet(), { assetId, waitTimeoutMs }, 60000);
958
1186
  }
959
1187
  return fail("UNKNOWN_COMMAND", `Unknown script command: ${subcommand || ""}`);
960
1188
  }
@@ -1011,6 +1239,94 @@ async function handleStore(args) {
1011
1239
  }
1012
1240
  return fail("UNKNOWN_COMMAND", `Unknown store command: ${subcommand}`);
1013
1241
  }
1242
+ async function handleTarget(args) {
1243
+ const subcommand = args._[1];
1244
+ if (subcommand === "focus") {
1245
+ if (!flagString(args, "target")) {
1246
+ return fail("INVALID_REQUEST", "target focus requires an explicit --target selector.");
1247
+ }
1248
+ return rpcCall(args, "bridge:focusTarget");
1249
+ }
1250
+ return fail("UNKNOWN_COMMAND", `Unknown target command: ${subcommand || ""}`);
1251
+ }
1252
+ function launchReadinessSuggestions(data) {
1253
+ const blockers = Array.isArray(data.readinessBlockers)
1254
+ ? data.readinessBlockers.map(String)
1255
+ : [];
1256
+ const suggestions = [];
1257
+ if (blockers.includes("tab-hidden")) {
1258
+ suggestions.push("Run pcbridge target focus with the same --target selector.");
1259
+ }
1260
+ if (blockers.includes("runtime-not-created") ||
1261
+ blockers.includes("runtime-not-started") ||
1262
+ blockers.includes("graphics-not-ready") ||
1263
+ blockers.includes("scene-not-loaded")) {
1264
+ suggestions.push("Focus the Launch tab and wait; refresh it if the state remains unchanged.");
1265
+ }
1266
+ if (blockers.includes("graphics-context-lost")) {
1267
+ suggestions.push("Refresh the Launch tab to recreate its graphics context.");
1268
+ }
1269
+ if (blockers.includes("splash-visible")) {
1270
+ suggestions.push("Wait for the PlayCanvas startup splash to finish.");
1271
+ }
1272
+ return suggestions;
1273
+ }
1274
+ async function diagnoseLaunch(args, pollTimeoutMs = 3000) {
1275
+ const raw = await rpcCall(args, "bridge:describeTarget", {}, pollTimeoutMs, false);
1276
+ if (!raw.ok)
1277
+ return raw;
1278
+ const data = objectJson(raw.data, "Launch target status");
1279
+ if (data.kind !== "launch") {
1280
+ return fail("INVALID_TARGET_KIND", `Selected target is ${String(data.kind || "unknown")}; choose launch:<sceneId> or a Launch tab:<id>.`, raw.meta, raw.data);
1281
+ }
1282
+ return ok({
1283
+ ...data,
1284
+ suggestions: launchReadinessSuggestions(data),
1285
+ }, raw.meta);
1286
+ }
1287
+ async function handleLaunch(args) {
1288
+ const subcommand = args._[1] || "diagnose";
1289
+ if (!flagString(args, "target")) {
1290
+ return fail("INVALID_REQUEST", "launch commands require an explicit --target selector.");
1291
+ }
1292
+ if (subcommand === "diagnose")
1293
+ return diagnoseLaunch(args);
1294
+ if (subcommand !== "wait-ready") {
1295
+ return fail("UNKNOWN_COMMAND", `Unknown launch command: ${subcommand}`);
1296
+ }
1297
+ const timeoutMs = readTimeoutMs(args, 30000);
1298
+ if (timeoutMs === null)
1299
+ return invalidTimeoutEnvelope();
1300
+ if (flagBool(args, "focus")) {
1301
+ const focused = await rpcCall(args, "bridge:focusTarget", {}, 5000);
1302
+ if (!focused.ok)
1303
+ return focused;
1304
+ }
1305
+ const startedAt = Date.now();
1306
+ let last = null;
1307
+ while (Date.now() - startedAt < timeoutMs) {
1308
+ const remainingMs = timeoutMs - (Date.now() - startedAt);
1309
+ last = await diagnoseLaunch(args, Math.max(1, Math.min(3000, remainingMs)));
1310
+ if (!last.ok)
1311
+ return last;
1312
+ const data = objectJson(last.data, "Launch target status");
1313
+ if (data.ready === true) {
1314
+ return ok({
1315
+ ready: true,
1316
+ waitedMs: Date.now() - startedAt,
1317
+ target: data,
1318
+ }, last.meta);
1319
+ }
1320
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
1321
+ }
1322
+ const lastData = last && last.ok
1323
+ ? objectJson(last.data, "Launch target status")
1324
+ : {};
1325
+ const blockers = Array.isArray(lastData.readinessBlockers)
1326
+ ? lastData.readinessBlockers.map(String).join(", ")
1327
+ : "unknown";
1328
+ return fail("LAUNCH_NOT_READY", `Launch did not become ready within ${timeoutMs}ms (blockers: ${blockers}).`, last?.meta, last && last.ok ? last.data : null);
1329
+ }
1014
1330
  async function handleViewport(args) {
1015
1331
  const subcommand = args._[1];
1016
1332
  if (subcommand === "focus") {
@@ -1037,7 +1353,10 @@ async function handleViewport(args) {
1037
1353
  if (!raw.ok)
1038
1354
  return raw;
1039
1355
  const data = raw.data;
1040
- const out = flagString(args, "out");
1356
+ const requestedOut = flagString(args, "out");
1357
+ const out = requestedOut
1358
+ ? await resolveWorkspaceFile(args, requestedOut, "viewport output")
1359
+ : undefined;
1041
1360
  if (out && data.base64) {
1042
1361
  await writeFile(out, Buffer.from(data.base64, "base64"));
1043
1362
  return ok({
@@ -1064,11 +1383,48 @@ async function handleLogs(args) {
1064
1383
  }
1065
1384
  return fail("UNKNOWN_COMMAND", `Unknown logs command: ${subcommand}`);
1066
1385
  }
1386
+ async function handleWorkspace(args) {
1387
+ const subcommand = args._[1] || "status";
1388
+ const target = flagString(args, "target", "current") || "current";
1389
+ if (subcommand === "status") {
1390
+ return fetchDaemon(`/workspace/status?target=${encodeURIComponent(target)}`);
1391
+ }
1392
+ if (subcommand === "path") {
1393
+ const status = await fetchDaemon(`/workspace/status?target=${encodeURIComponent(target)}`);
1394
+ if (!status.ok)
1395
+ return status;
1396
+ const data = objectJson(status.data, "workspace status");
1397
+ return ok({
1398
+ rootDirectory: data.rootDirectory || null,
1399
+ projectDirectory: data.projectDirectory || null,
1400
+ assetsDirectory: data.assetsDirectory || null,
1401
+ tmpDirectory: data.tmpDirectory || null,
1402
+ });
1403
+ }
1404
+ if (subcommand === "sync") {
1405
+ return fetchDaemon("/workspace/sync", {
1406
+ method: "POST",
1407
+ body: JSON.stringify({ target }),
1408
+ });
1409
+ }
1410
+ if (subcommand === "pull") {
1411
+ const assetId = flagString(args, "asset") || flagString(args, "asset-id") || flagString(args, "id");
1412
+ if (!assetId)
1413
+ return fail("INVALID_REQUEST", "workspace pull requires --asset <assetId>.");
1414
+ return fetchDaemon("/workspace/pull", {
1415
+ method: "POST",
1416
+ body: JSON.stringify({ target, assetId }),
1417
+ });
1418
+ }
1419
+ return fail("UNKNOWN_COMMAND", `Unknown workspace command: ${subcommand}`);
1420
+ }
1067
1421
  function help(group = "overview") {
1068
1422
  const groups = {
1069
1423
  overview: [
1070
1424
  "pcbridge help core",
1425
+ "pcbridge help workspace",
1071
1426
  "pcbridge help frontend",
1427
+ "pcbridge help target",
1072
1428
  "pcbridge help entity",
1073
1429
  "pcbridge help asset",
1074
1430
  "pcbridge help material",
@@ -1090,6 +1446,19 @@ function help(group = "overview") {
1090
1446
  "pcbridge targets",
1091
1447
  "pcbridge version",
1092
1448
  ],
1449
+ target: [
1450
+ "pcbridge target focus --target launch:<sceneId>",
1451
+ "pcbridge target focus --target tab:<id>",
1452
+ "Focus activates both the PlayCanvas tab and its Chrome window.",
1453
+ "Use editor:<sceneId> for writes and launch:<sceneId> for runtime checks; current can be ambiguous.",
1454
+ ],
1455
+ workspace: [
1456
+ "pcbridge workspace status --target editor:<sceneId>",
1457
+ "pcbridge workspace path --target editor:<sceneId>",
1458
+ "pcbridge workspace sync --target editor:<sceneId>",
1459
+ "pcbridge workspace pull --target editor:<sceneId> --asset <assetId>",
1460
+ "The directory where `pcbridge daemon start` runs is the workspace root.",
1461
+ ],
1093
1462
  frontend: [
1094
1463
  "pcbridge frontend install [latest|playcanvas-editor-v<version>-r<revision>] [--no-activate]",
1095
1464
  "pcbridge frontend update",
@@ -1100,89 +1469,103 @@ function help(group = "overview") {
1100
1469
  "The active frontend is served from http://localhost:3487 while the daemon is running.",
1101
1470
  ],
1102
1471
  entity: [
1103
- "pcbridge entity list --target current --limit 50 [--name Player] [--component render] [--tag enemy] [--full]",
1104
- "pcbridge entity get --target current --id <resource_id> [--full]",
1105
- "pcbridge entity create --target current --json ./entity.json",
1106
- "pcbridge entity create-many --target current --json ./entities.json",
1107
- "pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'",
1108
- "pcbridge entity patch-many --target current --json ./edits.json",
1109
- "pcbridge entity duplicate --target current --id <resource_id>",
1110
- "pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id> [--index 0] [--no-preserve-transform]",
1111
- "pcbridge entity add-component --target current --id <resource_id> --component render --data '{\"type\":\"box\"}'",
1112
- "pcbridge entity add-components --target current --id <resource_id> --json ./components.json",
1113
- "pcbridge entity remove-component --target current --id <resource_id> --component render",
1114
- "pcbridge entity set-material --target current --id <resource_id> --material-id <asset_id>",
1115
- "pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes-json ./attrs.json",
1116
- "pcbridge entity delete --target current --id <resource_id>",
1472
+ "pcbridge entity list --target editor:<sceneId> [--limit 50] [--offset 0] [--name Player] [--component render] [--tag enemy] [--full]",
1473
+ "pcbridge entity get --target editor:<sceneId> --id <resource_id> [--full]",
1474
+ "pcbridge entity create --target editor:<sceneId> --json ./entity.json",
1475
+ "pcbridge entity create-many --target editor:<sceneId> --json ./entities.json",
1476
+ "pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'",
1477
+ "pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json",
1478
+ "pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>",
1479
+ "pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id> [--index 0] [--no-preserve-transform]",
1480
+ "pcbridge entity add-component --target editor:<sceneId> --id <resource_id> --component render --data '{\"type\":\"box\"}'",
1481
+ "pcbridge entity add-components --target editor:<sceneId> --id <resource_id> --json ./components.json",
1482
+ "pcbridge entity remove-component --target editor:<sceneId> --id <resource_id> --component render",
1483
+ "pcbridge entity remove-components --target editor:<sceneId> --id <resource_id> --component render --component collision",
1484
+ "pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <asset_id>",
1485
+ "pcbridge entity add-script --target editor:<sceneId> --id <resource_id> (--asset-id <script_asset_id> | --script-name <registered_type>) [--attributes-json ./attrs.json] [--disabled]",
1486
+ "pcbridge entity delete --target editor:<sceneId> --id <resource_id>",
1117
1487
  ],
1118
1488
  asset: [
1119
- "pcbridge asset list --target current [--type script] [--name controller] [--tag ui] [--limit 50] [--full]",
1120
- "pcbridge asset get --target current --id <asset_id> [--full]",
1121
- "pcbridge asset create --target current --json ./assets.json",
1122
- "pcbridge asset folder ensure --target current --path \"AI Agent Bridge/Task/Textures\"",
1123
- "pcbridge asset upload --target current --file ./texture.png --folder \"AI Agent Bridge/Task/Textures\"",
1124
- "pcbridge asset upload-many --target current --json ./upload-manifest.json",
1125
- "pcbridge asset instantiate --target current --id <template_asset_id>",
1126
- "pcbridge asset delete --target current --id <asset_id>",
1489
+ "pcbridge asset list --target editor:<sceneId> [--type script] [--name controller] [--tag ui] [--limit 50] [--offset 0] [--full]",
1490
+ "pcbridge asset get --target editor:<sceneId> --id <asset_id> [--full]",
1491
+ "pcbridge asset create --target editor:<sceneId> --json ./assets.json",
1492
+ "pcbridge asset folder ensure --target editor:<sceneId> --path \"AI Agent Bridge/Task/Textures\"",
1493
+ "pcbridge asset upload --target editor:<sceneId> --file ./texture.png --folder \"AI Agent Bridge/Task/Textures\"",
1494
+ "pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json",
1495
+ "pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>",
1496
+ "pcbridge asset delete --target editor:<sceneId> --id <asset_id>",
1127
1497
  ],
1128
1498
  material: [
1129
- "pcbridge material create --target current --name Mat --diffuse-map <texture_asset_id>",
1130
- "pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'",
1131
- "pcbridge material patch --target current --asset-id <asset_id> --json ./material-data.json",
1132
- "pcbridge material set-diffuse --target current --asset-id <asset_id> --color '[1,0,0]'",
1499
+ "pcbridge material create --target editor:<sceneId> --name Mat --diffuse-map <texture_asset_id>",
1500
+ "pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'",
1501
+ "pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --json ./material-data.json",
1502
+ "pcbridge material set-diffuse --target editor:<sceneId> --asset-id <asset_id> --color '[1,0,0]'",
1133
1503
  ],
1134
1504
  template: [
1135
- "pcbridge template create --target current --entity-id <resource_id> --name TemplateName --folder \"AI Agent Bridge/Task/Templates\"",
1136
- "pcbridge template instantiate --target current --id <template_asset_id>",
1505
+ "pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TemplateName --folder \"AI Agent Bridge/Task/Templates\"",
1506
+ "pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>",
1507
+ "pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>",
1508
+ "pcbridge template apply --target editor:<sceneId> --entity-id <resource_id> [--timeout-ms 60000]",
1509
+ "pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json [--timeout-ms 120000]",
1510
+ "When apply is needed, completion requires the pipeline callback plus two zero-override observations; timeout is an error.",
1511
+ "verified covers the current Editor observer only, not persistence across a reload; apply-many runs serially.",
1137
1512
  ],
1138
1513
  script: [
1139
- "pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder \"AI Agent Bridge/Task/Scripts\" [--parse]",
1140
- "pcbridge script create --target current --filename controller.js --file ./controller.js",
1141
- "pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js",
1142
- "pcbridge script parse --target current --asset-id <asset_id>",
1514
+ "pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder \"AI Agent Bridge/Task/Scripts\" [--parse] [--wait]",
1515
+ "pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js",
1516
+ "pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js [--parse] [--wait]",
1517
+ "pcbridge script parse --target editor:<sceneId> --asset-id <asset_id> [--timeout-ms 60000]",
1518
+ "Combine --parse --wait for completion-checked updates; it verifies remote content and current Editor metadata, not a later workspace mirror sync.",
1143
1519
  ],
1144
1520
  scene: [
1145
- "pcbridge scene settings get --target current",
1146
- "pcbridge scene settings patch --target current --json ./scene-settings.json",
1147
- "pcbridge scene settings patch --target current --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
1521
+ "pcbridge scene settings get --target editor:<sceneId>",
1522
+ "pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json",
1523
+ "pcbridge scene settings patch --target editor:<sceneId> --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
1148
1524
  ],
1149
1525
  store: [
1150
- "pcbridge store search --target current --search vehicle --limit 20",
1151
- "pcbridge store get --target current --id <store_asset_id>",
1152
- "pcbridge store download --target current --id <store_asset_id> --name AssetName --license-json ./license.json",
1526
+ "pcbridge store search --target editor:<sceneId> --search vehicle --limit 20",
1527
+ "pcbridge store get --target editor:<sceneId> --id <store_asset_id>",
1528
+ "pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name AssetName --license-json ./license.json",
1153
1529
  ],
1154
1530
  viewport: [
1155
- "pcbridge viewport capture --target current --out ./tmp/viewport.png [--format png|webp]",
1156
- "pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png [--format png|webp]",
1157
- "pcbridge viewport focus --target current --id <resource_id> [--view perspective|top|bottom|front|back|left|right]",
1531
+ "pcbridge viewport capture --target editor:<sceneId> --out ./tmp/viewport.png [--format png|webp] [--max-width 1200] [--quality 0.85]",
1532
+ "pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png [--format png|webp] [--max-width 1200] [--quality 0.85]",
1533
+ "pcbridge viewport focus --target editor:<sceneId> --id <resource_id> [--view perspective|top|bottom|front|back|left|right] [--yaw 45] [--pitch -25]",
1534
+ "Capture defaults to max-width 1200 and may downscale the current canvas; it does not resize Chrome or emulate DPR.",
1158
1535
  ],
1159
1536
  launch: [
1160
1537
  "pcbridge targets",
1161
- "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }\"",
1538
+ "pcbridge launch diagnose --target launch:<sceneId>",
1539
+ "pcbridge launch wait-ready --target launch:<sceneId> [--focus] [--timeout-ms 30000]",
1540
+ "pcbridge target focus --target launch:<sceneId>",
1541
+ "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }\"",
1162
1542
  "pcbridge viewport capture --target launch:<sceneId> --out ./tmp/launch.png [--format png|webp]",
1163
1543
  "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1164
1544
  "pcbridge logs clear --target launch:<sceneId>",
1165
1545
  "Use --target tab:<id> when multiple Launch tabs are open for the same scene.",
1546
+ "ready is a best-effort heuristic requiring a visible tab, owned graphics canvas, attached scene, completed first frame, and no recognized splash.",
1547
+ "scriptsReady/scriptTypeCount are diagnostic only; they do not prove every ScriptType registered.",
1166
1548
  ],
1167
1549
  logs: [
1168
- "pcbridge logs get --target current [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1169
- "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1170
- "pcbridge logs clear --target current",
1550
+ "pcbridge logs get --target editor:<sceneId> [--limit 100] [--offset 0] [--level error|warn|info|debug] [--since <seq>]",
1551
+ "pcbridge logs get --target launch:<sceneId> [--limit 100] [--offset 0] [--level error|warn|info|debug] [--since <seq>]",
1552
+ "pcbridge logs clear --target editor:<sceneId>",
1171
1553
  "pcbridge logs clear --target launch:<sceneId>",
1172
1554
  ],
1173
1555
  log: [
1174
- "pcbridge logs get --target current [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1175
- "pcbridge logs get --target launch:<sceneId> [--limit 100] [--level error|warn|info|debug] [--since <seq>]",
1176
- "pcbridge logs clear --target current",
1556
+ "pcbridge logs get --target editor:<sceneId> [--limit 100] [--offset 0] [--level error|warn|info|debug] [--since <seq>]",
1557
+ "pcbridge logs get --target launch:<sceneId> [--limit 100] [--offset 0] [--level error|warn|info|debug] [--since <seq>]",
1558
+ "pcbridge logs clear --target editor:<sceneId>",
1177
1559
  "pcbridge logs clear --target launch:<sceneId>",
1178
1560
  ],
1179
1561
  eval: [
1180
1562
  "Use eval for custom Editor/Engine workflows, PlayCanvas Launch debugging, large multi-step scene edits, exploratory API inspection, and operations not yet structured.",
1181
- "pcbridge eval --target current --code \"return { href: location.href, hasEditor: !!editor }\"",
1182
- "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }\"",
1183
- "pcbridge eval --target current --file ./task.js",
1184
- "pcbridge eval --target current --file ./task.js --args-json ./task-args.json",
1185
- "pcbridge eval --target current --stdin",
1563
+ "pcbridge eval --target editor:<sceneId> --code \"return { href: location.href, hasEditor: !!editor }\" [--timeout-ms 15000]",
1564
+ "pcbridge eval --target launch:<sceneId> --code \"return { href: location.href, runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }\"",
1565
+ "pcbridge eval --target editor:<sceneId> --file ./task.js [--timeout-ms 15000]",
1566
+ "pcbridge eval --target editor:<sceneId> --file ./task.js --args-json ./task-args.json [--timeout-ms 15000]",
1567
+ "pcbridge eval --target editor:<sceneId> --stdin [--timeout-ms 15000]",
1568
+ "Add --max-depth <1..20>, --max-items <1..5000>, --max-keys <1..2000>, or --max-string <1..100000> only when a compact projection is insufficient.",
1186
1569
  ],
1187
1570
  };
1188
1571
  const commands = groups[group];
@@ -1226,6 +1609,12 @@ async function main() {
1226
1609
  else if (command === "targets") {
1227
1610
  print(await fetchDaemon("/targets"));
1228
1611
  }
1612
+ else if (command === "target") {
1613
+ print(await handleTarget(args));
1614
+ }
1615
+ else if (command === "workspace") {
1616
+ print(await handleWorkspace(args));
1617
+ }
1229
1618
  else if (command === "eval") {
1230
1619
  const commandArgs = await readJsonFlag(args, "args-json");
1231
1620
  print(await rpcEval(args, await readCode(args), objectJson(commandArgs, "eval args")));
@@ -1251,6 +1640,9 @@ async function main() {
1251
1640
  else if (command === "store") {
1252
1641
  print(await handleStore(args));
1253
1642
  }
1643
+ else if (command === "launch") {
1644
+ print(await handleLaunch(args));
1645
+ }
1254
1646
  else if (command === "viewport") {
1255
1647
  print(await handleViewport(args));
1256
1648
  }
@@ -1266,6 +1658,10 @@ async function main() {
1266
1658
  }
1267
1659
  }
1268
1660
  catch (error) {
1661
+ if (error instanceof DaemonConnectionError) {
1662
+ print(fail(error.diagnosis.code, error.diagnosis.message, undefined, { nextAction: error.diagnosis.nextAction }));
1663
+ return;
1664
+ }
1269
1665
  print(fail("CLI_ERROR", error instanceof Error ? error.message : String(error)));
1270
1666
  process.exitCode = 1;
1271
1667
  }