@quenty/nevermore-cli 4.42.0 → 4.42.1-canary.783.30683606415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/dist/args/global-args.d.ts +13 -0
  3. package/dist/args/global-args.d.ts.map +1 -1
  4. package/dist/commands/batch-command/batch-deploy-command.d.ts +3 -0
  5. package/dist/commands/batch-command/batch-deploy-command.d.ts.map +1 -1
  6. package/dist/commands/batch-command/batch-deploy-command.js +90 -1
  7. package/dist/commands/batch-command/batch-deploy-command.js.map +1 -1
  8. package/dist/commands/batch-command/batch-test-command.d.ts.map +1 -1
  9. package/dist/commands/batch-command/batch-test-command.js +7 -2
  10. package/dist/commands/batch-command/batch-test-command.js.map +1 -1
  11. package/dist/commands/deploy-command/deploy-init.js +1 -1
  12. package/dist/commands/deploy-command/deploy-init.js.map +1 -1
  13. package/dist/commands/deploy-command/index.d.ts +3 -0
  14. package/dist/commands/deploy-command/index.d.ts.map +1 -1
  15. package/dist/commands/deploy-command/index.js +301 -60
  16. package/dist/commands/deploy-command/index.js.map +1 -1
  17. package/dist/commands/deploy-command/select-target.js +1 -1
  18. package/dist/commands/deploy-command/select-target.js.map +1 -1
  19. package/dist/commands/deploy-command/version-command.d.ts.map +1 -1
  20. package/dist/commands/deploy-command/version-command.js +138 -12
  21. package/dist/commands/deploy-command/version-command.js.map +1 -1
  22. package/dist/commands/test-command/test-command.d.ts.map +1 -1
  23. package/dist/commands/test-command/test-command.js +17 -7
  24. package/dist/commands/test-command/test-command.js.map +1 -1
  25. package/dist/nevermore.js +17 -0
  26. package/dist/nevermore.js.map +1 -1
  27. package/dist/utils/batch/changed-packages-utils.d.ts +1 -1
  28. package/dist/utils/batch/changed-packages-utils.d.ts.map +1 -1
  29. package/dist/utils/batch/changed-packages-utils.js +1 -1
  30. package/dist/utils/batch/changed-packages-utils.js.map +1 -1
  31. package/dist/utils/build/base-place-resolver-factory.d.ts +25 -0
  32. package/dist/utils/build/base-place-resolver-factory.d.ts.map +1 -0
  33. package/dist/utils/build/base-place-resolver-factory.js +40 -0
  34. package/dist/utils/build/base-place-resolver-factory.js.map +1 -0
  35. package/dist/utils/build/build.d.ts +13 -2
  36. package/dist/utils/build/build.d.ts.map +1 -1
  37. package/dist/utils/build/build.js.map +1 -1
  38. package/dist/utils/build/upload.d.ts +1 -1
  39. package/dist/utils/build/upload.d.ts.map +1 -1
  40. package/dist/utils/deploy/deploy-metadata.d.ts +1 -1
  41. package/dist/utils/deploy/deploy-metadata.d.ts.map +1 -1
  42. package/dist/utils/job-context/base-job-context.d.ts +3 -1
  43. package/dist/utils/job-context/base-job-context.d.ts.map +1 -1
  44. package/dist/utils/job-context/base-job-context.js +45 -6
  45. package/dist/utils/job-context/base-job-context.js.map +1 -1
  46. package/dist/utils/job-context/batch-script-job-context.d.ts +6 -0
  47. package/dist/utils/job-context/batch-script-job-context.d.ts.map +1 -1
  48. package/dist/utils/job-context/batch-script-job-context.js +13 -0
  49. package/dist/utils/job-context/batch-script-job-context.js.map +1 -1
  50. package/dist/utils/job-context/cloud-job-context.d.ts +2 -1
  51. package/dist/utils/job-context/cloud-job-context.d.ts.map +1 -1
  52. package/dist/utils/job-context/cloud-job-context.js +2 -2
  53. package/dist/utils/job-context/cloud-job-context.js.map +1 -1
  54. package/dist/utils/job-context/local-job-context.d.ts +2 -1
  55. package/dist/utils/job-context/local-job-context.d.ts.map +1 -1
  56. package/dist/utils/job-context/local-job-context.js +2 -2
  57. package/dist/utils/job-context/local-job-context.js.map +1 -1
  58. package/dist/utils/open-cloud/open-cloud-client.d.ts +20 -2
  59. package/dist/utils/open-cloud/open-cloud-client.d.ts.map +1 -1
  60. package/dist/utils/open-cloud/open-cloud-client.js +74 -20
  61. package/dist/utils/open-cloud/open-cloud-client.js.map +1 -1
  62. package/dist/utils/open-cloud/open-cloud-client.test.js +89 -12
  63. package/dist/utils/open-cloud/open-cloud-client.test.js.map +1 -1
  64. package/dist/utils/testing/runner/combined-project-generator.d.ts +1 -1
  65. package/dist/utils/testing/runner/combined-project-generator.d.ts.map +1 -1
  66. package/dist/utils/testing/runner/test-runner.d.ts +1 -1
  67. package/dist/utils/testing/runner/test-runner.d.ts.map +1 -1
  68. package/dist/utils/watch/github-context.d.ts +50 -0
  69. package/dist/utils/watch/github-context.d.ts.map +1 -0
  70. package/dist/utils/watch/github-context.js +125 -0
  71. package/dist/utils/watch/github-context.js.map +1 -0
  72. package/dist/utils/watch/github-context.test.d.ts +2 -0
  73. package/dist/utils/watch/github-context.test.d.ts.map +1 -0
  74. package/dist/utils/watch/github-context.test.js +112 -0
  75. package/dist/utils/watch/github-context.test.js.map +1 -0
  76. package/dist/utils/watch/http-watch-registry.d.ts +40 -0
  77. package/dist/utils/watch/http-watch-registry.d.ts.map +1 -0
  78. package/dist/utils/watch/http-watch-registry.js +262 -0
  79. package/dist/utils/watch/http-watch-registry.js.map +1 -0
  80. package/dist/utils/watch/http-watch-registry.test.d.ts +2 -0
  81. package/dist/utils/watch/http-watch-registry.test.d.ts.map +1 -0
  82. package/dist/utils/watch/http-watch-registry.test.js +211 -0
  83. package/dist/utils/watch/http-watch-registry.test.js.map +1 -0
  84. package/dist/utils/watch/local-watch-loop.d.ts +50 -0
  85. package/dist/utils/watch/local-watch-loop.d.ts.map +1 -0
  86. package/dist/utils/watch/local-watch-loop.js +103 -0
  87. package/dist/utils/watch/local-watch-loop.js.map +1 -0
  88. package/dist/utils/watch/local-watch-loop.test.d.ts +2 -0
  89. package/dist/utils/watch/local-watch-loop.test.d.ts.map +1 -0
  90. package/dist/utils/watch/local-watch-loop.test.js +170 -0
  91. package/dist/utils/watch/local-watch-loop.test.js.map +1 -0
  92. package/dist/utils/watch/register-notify-watches.d.ts +41 -0
  93. package/dist/utils/watch/register-notify-watches.d.ts.map +1 -0
  94. package/dist/utils/watch/register-notify-watches.js +159 -0
  95. package/dist/utils/watch/register-notify-watches.js.map +1 -0
  96. package/dist/utils/watch/register-notify-watches.test.d.ts +2 -0
  97. package/dist/utils/watch/register-notify-watches.test.d.ts.map +1 -0
  98. package/dist/utils/watch/register-notify-watches.test.js +225 -0
  99. package/dist/utils/watch/register-notify-watches.test.js.map +1 -0
  100. package/dist/utils/watch/register-watches.d.ts +68 -0
  101. package/dist/utils/watch/register-watches.d.ts.map +1 -0
  102. package/dist/utils/watch/register-watches.js +221 -0
  103. package/dist/utils/watch/register-watches.js.map +1 -0
  104. package/dist/utils/watch/register-watches.test.d.ts +2 -0
  105. package/dist/utils/watch/register-watches.test.d.ts.map +1 -0
  106. package/dist/utils/watch/register-watches.test.js +576 -0
  107. package/dist/utils/watch/register-watches.test.js.map +1 -0
  108. package/dist/utils/watch/stream-watch-loop.d.ts +54 -0
  109. package/dist/utils/watch/stream-watch-loop.d.ts.map +1 -0
  110. package/dist/utils/watch/stream-watch-loop.js +282 -0
  111. package/dist/utils/watch/stream-watch-loop.js.map +1 -0
  112. package/dist/utils/watch/stream-watch-loop.test.d.ts +2 -0
  113. package/dist/utils/watch/stream-watch-loop.test.d.ts.map +1 -0
  114. package/dist/utils/watch/stream-watch-loop.test.js +392 -0
  115. package/dist/utils/watch/stream-watch-loop.test.js.map +1 -0
  116. package/dist/utils/watch/websocket-watch-stream.d.ts +25 -0
  117. package/dist/utils/watch/websocket-watch-stream.d.ts.map +1 -0
  118. package/dist/utils/watch/websocket-watch-stream.js +306 -0
  119. package/dist/utils/watch/websocket-watch-stream.js.map +1 -0
  120. package/dist/utils/watch/websocket-watch-stream.test.d.ts +2 -0
  121. package/dist/utils/watch/websocket-watch-stream.test.d.ts.map +1 -0
  122. package/dist/utils/watch/websocket-watch-stream.test.js +475 -0
  123. package/dist/utils/watch/websocket-watch-stream.test.js.map +1 -0
  124. package/package.json +7 -4
  125. package/src/args/global-args.ts +13 -0
  126. package/src/commands/batch-command/batch-deploy-command.ts +105 -1
  127. package/src/commands/batch-command/batch-test-command.ts +8 -2
  128. package/src/commands/deploy-command/deploy-init.ts +1 -1
  129. package/src/commands/deploy-command/index.ts +331 -32
  130. package/src/commands/deploy-command/select-target.ts +1 -1
  131. package/src/commands/deploy-command/version-command.ts +215 -21
  132. package/src/commands/test-command/test-command.ts +24 -18
  133. package/src/nevermore.ts +19 -0
  134. package/src/utils/batch/changed-packages-utils.ts +1 -1
  135. package/src/utils/build/base-place-resolver-factory.ts +49 -0
  136. package/src/utils/build/build.ts +13 -2
  137. package/src/utils/build/upload.ts +1 -1
  138. package/src/utils/deploy/deploy-metadata.ts +1 -1
  139. package/src/utils/job-context/base-job-context.ts +68 -6
  140. package/src/utils/job-context/batch-script-job-context.ts +18 -0
  141. package/src/utils/job-context/cloud-job-context.ts +7 -2
  142. package/src/utils/job-context/local-job-context.ts +7 -2
  143. package/src/utils/open-cloud/open-cloud-client.test.ts +133 -14
  144. package/src/utils/open-cloud/open-cloud-client.ts +127 -34
  145. package/src/utils/testing/runner/combined-project-generator.ts +1 -1
  146. package/src/utils/testing/runner/test-runner.ts +1 -1
  147. package/src/utils/watch/github-context.test.ts +154 -0
  148. package/src/utils/watch/github-context.ts +184 -0
  149. package/src/utils/watch/http-watch-registry.test.ts +330 -0
  150. package/src/utils/watch/http-watch-registry.ts +341 -0
  151. package/src/utils/watch/local-watch-loop.test.ts +197 -0
  152. package/src/utils/watch/local-watch-loop.ts +190 -0
  153. package/src/utils/watch/register-notify-watches.test.ts +282 -0
  154. package/src/utils/watch/register-notify-watches.ts +226 -0
  155. package/src/utils/watch/register-watches.test.ts +696 -0
  156. package/src/utils/watch/register-watches.ts +369 -0
  157. package/src/utils/watch/stream-watch-loop.test.ts +625 -0
  158. package/src/utils/watch/stream-watch-loop.ts +411 -0
  159. package/src/utils/watch/websocket-watch-stream.test.ts +581 -0
  160. package/src/utils/watch/websocket-watch-stream.ts +403 -0
  161. package/tsconfig.json +19 -6
  162. package/tsconfig.tsbuildinfo +1 -1
  163. package/dist/utils/build/deploy-config.d.ts +0 -71
  164. package/dist/utils/build/deploy-config.d.ts.map +0 -1
  165. package/dist/utils/build/deploy-config.js +0 -164
  166. package/dist/utils/build/deploy-config.js.map +0 -1
  167. package/dist/utils/build/deploy-config.test.d.ts +0 -2
  168. package/dist/utils/build/deploy-config.test.d.ts.map +0 -1
  169. package/dist/utils/build/deploy-config.test.js +0 -126
  170. package/dist/utils/build/deploy-config.test.js.map +0 -1
  171. package/src/utils/build/deploy-config.test.ts +0 -149
  172. package/src/utils/build/deploy-config.ts +0 -259
@@ -28,6 +28,10 @@ import {
28
28
  import { OpenCloudClient } from '../../utils/open-cloud/open-cloud-client.js';
29
29
  import { RateLimiter } from '../../utils/open-cloud/rate-limiter.js';
30
30
  import { CloudJobContext } from '../../utils/job-context/cloud-job-context.js';
31
+ import {
32
+ createBasePlaceResolver,
33
+ createLockOnlyBasePlaceResolver,
34
+ } from '../../utils/build/base-place-resolver-factory.js';
31
35
  import {
32
36
  type BatchTarget,
33
37
  discoverAllTargetPackagesAsync,
@@ -39,6 +43,8 @@ import {
39
43
  readPackageVersionAsync,
40
44
  } from '../../utils/nevermore-cli-utils.js';
41
45
  import { parseTestLogs } from '../../utils/testing/test-log-parser.js';
46
+ import { parseWatchOption } from '@quenty/nevermore-deploy';
47
+ import { registerWatchesAsync } from '../../utils/watch/register-watches.js';
42
48
 
43
49
  const SMOKE_TEST_SCRIPT_PATH = resolvePackagePath(
44
50
  import.meta.url,
@@ -57,6 +63,9 @@ interface BatchDeployArgs extends NevermoreGlobalArgs {
57
63
  logs?: boolean;
58
64
  target?: string;
59
65
  smokeTest?: boolean;
66
+ watch?: string;
67
+ watchShareApiKey?: boolean;
68
+ watchUseGhAuth?: boolean;
60
69
  }
61
70
 
62
71
  export const batchDeployCommand: CommandModule<
@@ -115,6 +124,28 @@ export const batchDeployCommand: CommandModule<
115
124
  '(executes server scripts via Open Cloud and waits for errors)',
116
125
  type: 'boolean',
117
126
  default: false,
127
+ })
128
+ .option('watch', {
129
+ describe:
130
+ 'After deploying, register a cloud watch for every place with a "watch" field, ' +
131
+ 'so it rebuilds when its base place changes. Takes the register endpoint ' +
132
+ 'URL, ending in the lease: https://<watch-service>/v1/register/7d',
133
+ type: 'string',
134
+ })
135
+ .option('watch-use-gh-auth', {
136
+ describe:
137
+ 'Let the GitHub CLI supply the watch token when no environment variable does. ' +
138
+ 'Off by default: registering sends the token to the watch service, so it should be one you handed over.',
139
+ type: 'boolean',
140
+ default: false,
141
+ })
142
+ .option('watch-share-api-key', {
143
+ describe:
144
+ 'Share the Open Cloud API key with the watch service, so it can read private base places, ' +
145
+ 'see "saved" versions, and report versions in the same vocabulary as the lock file. ' +
146
+ 'Off by default — the key is stored by the service.',
147
+ type: 'boolean',
148
+ default: false,
118
149
  });
119
150
  },
120
151
  handler: async (args) => {
@@ -129,6 +160,9 @@ export const batchDeployCommand: CommandModule<
129
160
 
130
161
  async function _runAsync(args: BatchDeployArgs): Promise<void> {
131
162
  const targetName = args.target ?? 'test';
163
+ // Parsed up front so a typo'd duration fails before anything is deployed.
164
+ const watchOption =
165
+ args.watch == null ? undefined : parseWatchOption(args.watch);
132
166
 
133
167
  const discovered = args.all
134
168
  ? await discoverAllTargetPackagesAsync(targetName)
@@ -159,6 +193,46 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
159
193
  OutputHelper.info(
160
194
  `[DRYRUN] Would deploy ${batchTargets.length} targets: ${names}`
161
195
  );
196
+ // Registration is idempotent and derives from committed config plus the
197
+ // lock file, so it runs for real even on a dryrun — that is what makes the
198
+ // watch path testable without shipping a build.
199
+ if (watchOption) {
200
+ OutputHelper.info(
201
+ '[DRYRUN] Registering separate dryrun watches and firing them, to ' +
202
+ 'prove routing works. This does not build or upload here — but ' +
203
+ 'firing really does dispatch the workflow once per package, and ' +
204
+ 'each of those runs a real deploy on the runner.'
205
+ );
206
+ if (args.watchShareApiKey) {
207
+ OutputHelper.warn(
208
+ '[DRYRUN] Registering without the Open Cloud key, so a "saved" base ' +
209
+ 'place is skipped here even though a real run would watch it.'
210
+ );
211
+ }
212
+ const allPackages = await discoverAllTargetPackagesAsync(targetName);
213
+ // Under its own monitor name, never the one a real run owns.
214
+ //
215
+ // Re-registering replaces a monitor's entire watch list, and a dryrun
216
+ // cannot reproduce a real registration: the Open Cloud key is resolved
217
+ // after this point, so it would register anonymously — stripping the key
218
+ // from the live monitor, moving every source back to the anonymous
219
+ // driver and its content-hash vocabulary, dropping the baselines, and
220
+ // deleting any "saved" watch outright, because an anonymous
221
+ // registration skips those.
222
+ await registerWatchesAsync({
223
+ option: watchOption,
224
+ monitorName: `${targetName}/dryrun`,
225
+ resolver: createLockOnlyBasePlaceResolver(),
226
+ useGhAuth: args.watchUseGhAuth,
227
+ triggerAfterRegister: true,
228
+ candidates: flattenToBatchTargets(allPackages).map((buildTarget) => ({
229
+ targetName,
230
+ packageName: buildTarget.packageName,
231
+ packagePath: buildTarget.path,
232
+ place: buildTarget.target,
233
+ })),
234
+ });
235
+ }
162
236
  return;
163
237
  }
164
238
 
@@ -214,7 +288,8 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
214
288
  apiKey,
215
289
  rateLimiter: new RateLimiter(),
216
290
  });
217
- const context = new CloudJobContext(reporter, client);
291
+ const basePlaceResolver = createBasePlaceResolver(client, args);
292
+ const context = new CloudJobContext(reporter, client, basePlaceResolver);
218
293
 
219
294
  // Gathered once so every deployed package shares one timestamp and commit.
220
295
  const deployGitInfo = gatherGitDeployInfo();
@@ -309,6 +384,35 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
309
384
  },
310
385
  });
311
386
  if (results.summary.failed > 0) exitCode = 1;
387
+
388
+ // Only after a clean run, matching `deploy run`. A package that resolved its
389
+ // base place and then failed to upload has a lock naming a version it never
390
+ // shipped; registering that as the baseline tells the service the watch is
391
+ // up to date, so the rebuild never fires and the next successful run
392
+ // re-registers the same wrong baseline. The failure becomes permanent and
393
+ // invisible.
394
+ if (watchOption && results.summary.failed === 0) {
395
+ // Deliberately every package with this target, not just the ones that
396
+ // deployed. One monitor holds the repo's watches for a target and a
397
+ // re-apply replaces its whole list, so registering only what changed
398
+ // would delete the watches of every package that happened not to change
399
+ // this run. Packages that did not deploy still have a lock entry, which
400
+ // is the correct baseline for them.
401
+ const allPackages = await discoverAllTargetPackagesAsync(targetName);
402
+ await registerWatchesAsync({
403
+ option: watchOption,
404
+ monitorName: targetName,
405
+ resolver: basePlaceResolver,
406
+ useGhAuth: args.watchUseGhAuth,
407
+ robloxApiKey: args.watchShareApiKey ? apiKey : undefined,
408
+ candidates: flattenToBatchTargets(allPackages).map((buildTarget) => ({
409
+ targetName,
410
+ packageName: buildTarget.packageName,
411
+ packagePath: buildTarget.path,
412
+ place: buildTarget.target,
413
+ })),
414
+ });
415
+ }
312
416
  } catch (err) {
313
417
  OutputHelper.error(err instanceof Error ? err.message : String(err));
314
418
  exitCode = 1;
@@ -8,6 +8,7 @@ import {
8
8
  import { NevermoreGlobalArgs } from '../../args/global-args.js';
9
9
  import { getApiKeyAsync } from '@quenty/nevermore-cli-helpers';
10
10
  import { runBatchAsync } from '../../utils/batch/batch-runner.js';
11
+ import { createBasePlaceResolver } from '../../utils/build/base-place-resolver-factory.js';
11
12
  import {
12
13
  type JobContext,
13
14
  BatchScriptJobContext,
@@ -234,9 +235,14 @@ async function _runAsync(args: BatchTestArgs): Promise<void> {
234
235
  ? _createBroadcastReporter(reporter, packageNames)
235
236
  : reporter;
236
237
 
238
+ // Local runs get a resolver too — a package with a basePlace still has to
239
+ // merge it, and the client resolves its API key lazily so a run that never
240
+ // touches one is not prompted for credentials.
241
+ const basePlaceResolver = createBasePlaceResolver(client, args);
242
+
237
243
  const innerContext: JobContext = cloud
238
- ? new CloudJobContext(innerReporter, client)
239
- : new LocalJobContext(innerReporter, client);
244
+ ? new CloudJobContext(innerReporter, client, basePlaceResolver)
245
+ : new LocalJobContext(innerReporter, client, basePlaceResolver);
240
246
 
241
247
  const context: JobContext = args.aggregated
242
248
  ? new BatchScriptJobContext(innerContext, packages, {
@@ -5,7 +5,7 @@ import { OutputHelper } from '@quenty/cli-output-helpers';
5
5
  import {
6
6
  DeployConfig,
7
7
  discoverUniverseIdAsync,
8
- } from '../../utils/build/deploy-config.js';
8
+ } from '@quenty/nevermore-deploy';
9
9
  import {
10
10
  getRobloxCookieAsync,
11
11
  createPlaceInUniverseAsync,
@@ -15,6 +15,10 @@ import {
15
15
  import { NevermoreGlobalArgs } from '../../args/global-args.js';
16
16
  import { getApiKeyAsync } from '@quenty/nevermore-cli-helpers';
17
17
  import { uploadPlaceAsync } from '../../utils/build/upload.js';
18
+ import {
19
+ createBasePlaceResolver,
20
+ createLockOnlyBasePlaceResolver,
21
+ } from '../../utils/build/base-place-resolver-factory.js';
18
22
  import {
19
23
  type BatchDeployResult,
20
24
  createDeployCommentConfig,
@@ -35,11 +39,31 @@ import {
35
39
  readPackageVersionAsync,
36
40
  } from '../../utils/nevermore-cli-utils.js';
37
41
  import {
42
+ formatTargetSelector,
43
+ isBasePlaceVersionKeyword,
38
44
  loadDeployConfigAsync,
45
+ parseTargetSelector,
46
+ parseWatchOption,
39
47
  resolveDeployConfigPath,
40
48
  resolveDeployTargetPlaces,
41
49
  toManifestPlaceInfo,
42
- } from '../../utils/build/deploy-config.js';
50
+ type BasePlaceResolver,
51
+ type DeployConfig,
52
+ } from '@quenty/nevermore-deploy';
53
+ import {
54
+ registerWatchesAsync,
55
+ type RegisterWatchesResult,
56
+ } from '../../utils/watch/register-watches.js';
57
+ import {
58
+ runLocalWatchLoopAsync,
59
+ type LocalWatchEntry,
60
+ } from '../../utils/watch/local-watch-loop.js';
61
+ import {
62
+ describeNotifyWatchFallback,
63
+ tryRegisterNotifyWatchesAsync,
64
+ } from '../../utils/watch/register-notify-watches.js';
65
+ import { runStreamWatchLoopAsync } from '../../utils/watch/stream-watch-loop.js';
66
+ import { WebSocketWatchStream } from '../../utils/watch/websocket-watch-stream.js';
43
67
  import { handleInitAsync } from './deploy-init.js';
44
68
  import {
45
69
  handleVersionUpgradeAsync,
@@ -50,6 +74,48 @@ import { selectTargetAsync } from './select-target.js';
50
74
 
51
75
  const MULTI_PLACE_CONCURRENCY = 10;
52
76
 
77
+ /**
78
+ * Which base places a local watch polls.
79
+ *
80
+ * Deliberately looser than the cloud plan. `watch` is a GitHub workflow path —
81
+ * a dispatch address — and nothing is dispatched locally, so requiring it would
82
+ * only stop a developer hot-reloading a place that never intends to use CI.
83
+ * `"saved"` is fair game too: the service cannot poll it yet, but this machine
84
+ * has Open Cloud credentials and can.
85
+ *
86
+ * An exact version pin is still excluded, for the same reason as always: it
87
+ * means "hold this still", so there is nothing to follow.
88
+ */
89
+ async function _buildLocalWatchEntriesAsync(
90
+ config: DeployConfig,
91
+ targetName: string,
92
+ packagePath: string,
93
+ resolver: BasePlaceResolver
94
+ ): Promise<LocalWatchEntry[]> {
95
+ const entries: LocalWatchEntry[] = [];
96
+ for (const place of resolveDeployTargetPlaces(config, targetName)) {
97
+ const basePlace = place.basePlace;
98
+ if (basePlace == null) {
99
+ continue;
100
+ }
101
+ if (
102
+ basePlace.version != null &&
103
+ !isBasePlaceVersionKeyword(basePlace.version)
104
+ ) {
105
+ continue;
106
+ }
107
+ const versionType = basePlace.version ?? 'published';
108
+ entries.push({
109
+ label: formatTargetSelector({ targetName, placeName: place.name }),
110
+ universeId: basePlace.universeId,
111
+ placeId: basePlace.placeId,
112
+ versionType,
113
+ baseline: await resolver.peekAsync(packagePath, basePlace),
114
+ });
115
+ }
116
+ return entries;
117
+ }
118
+
53
119
  export interface DeployArgs extends NevermoreGlobalArgs {
54
120
  apiKey?: string;
55
121
  publish?: boolean;
@@ -63,6 +129,9 @@ export interface DeployArgs extends NevermoreGlobalArgs {
63
129
  placeFile?: string;
64
130
  output?: string;
65
131
  logs?: boolean;
132
+ watch?: string;
133
+ watchShareApiKey?: boolean;
134
+ watchUseGhAuth?: boolean;
66
135
  }
67
136
 
68
137
  export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
@@ -126,7 +195,7 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
126
195
  return yargs
127
196
  .command(
128
197
  'upgrade [target]',
129
- 'Re-pin every basePlace to its latest published version',
198
+ 'Re-pin every numeric basePlace to its latest published version',
130
199
  (upgradeYargs) => {
131
200
  return upgradeYargs
132
201
  .positional('target', {
@@ -227,6 +296,27 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
227
296
  describe: 'Show build/upload logs (not just on failure)',
228
297
  type: 'boolean',
229
298
  default: false,
299
+ })
300
+ .option('watch', {
301
+ describe:
302
+ 'After deploying, register a cloud watch so this target rebuilds when its base place changes. ' +
303
+ 'Takes the register endpoint URL, ending in the lease: https://<watch-service>/v1/register/7d',
304
+ type: 'string',
305
+ })
306
+ .option('watch-use-gh-auth', {
307
+ describe:
308
+ 'Let the GitHub CLI supply the watch token when no environment variable does. ' +
309
+ 'Off by default: registering sends the token to the watch service, so it should be one you handed over.',
310
+ type: 'boolean',
311
+ default: false,
312
+ })
313
+ .option('watch-share-api-key', {
314
+ describe:
315
+ 'Share the Open Cloud API key with the watch service, so it can read a private base place, ' +
316
+ 'see "saved" versions, and report versions in the same vocabulary as the lock file. ' +
317
+ 'Off by default — the key is stored by the service.',
318
+ type: 'boolean',
319
+ default: false,
230
320
  });
231
321
  },
232
322
  async (runArgs) => {
@@ -245,10 +335,10 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
245
335
  public handler = async () => {};
246
336
 
247
337
  private static async _handleRunAsync(args: DeployArgs): Promise<void> {
248
- if (args.dryrun) {
249
- OutputHelper.info(`[DRYRUN] Would build and upload`);
250
- return;
251
- }
338
+ // Parsed before anything is built so a typo'd duration fails immediately
339
+ // rather than after a full deploy has already shipped.
340
+ const watchOption =
341
+ args.watch == null ? undefined : parseWatchOption(args.watch);
252
342
 
253
343
  const cwd = process.cwd();
254
344
  const packageName = (await readPackageNameAsync(cwd)) ?? path.basename(cwd);
@@ -299,6 +389,54 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
299
389
  },
300
390
  ];
301
391
 
392
+ // Registering a watch is idempotent and derives entirely from committed
393
+ // config and the lock file, so it is safe to do for real on a dryrun — and
394
+ // doing it for real is the only way to exercise the watch path without
395
+ // shipping a build.
396
+ if (args.dryrun) {
397
+ OutputHelper.info('[DRYRUN] Would build and upload');
398
+ if (watchOption) {
399
+ OutputHelper.info(
400
+ '[DRYRUN] Registering a separate dryrun watch and firing it, to ' +
401
+ 'prove routing works. This does not build or upload here — but ' +
402
+ 'firing really does dispatch the workflow, which runs a real ' +
403
+ 'deploy on the runner. That is the half being proved.'
404
+ );
405
+ if (args.watchShareApiKey) {
406
+ OutputHelper.warn(
407
+ '[DRYRUN] Registering without the Open Cloud key, so a "saved" ' +
408
+ 'base place is skipped here even though a real run would watch it.'
409
+ );
410
+ }
411
+ const watchedTarget = parseTargetSelector(targetName).targetName;
412
+ // Under its own monitor name, never the one a real run owns.
413
+ //
414
+ // Re-registering replaces a monitor's entire watch list, and a dryrun
415
+ // cannot reproduce a real registration: the Open Cloud key is resolved
416
+ // after this point, so it would register anonymously — stripping the key
417
+ // from the live monitor, moving every source back to the anonymous
418
+ // driver and its content-hash vocabulary, dropping the baselines, and
419
+ // deleting any "saved" watch outright, because an anonymous
420
+ // registration skips those.
421
+ await registerWatchesAsync({
422
+ option: watchOption,
423
+ monitorName: `${packageName}/${watchedTarget}/dryrun`,
424
+ resolver: createLockOnlyBasePlaceResolver(),
425
+ useGhAuth: args.watchUseGhAuth,
426
+ triggerAfterRegister: true,
427
+ candidates: resolveDeployTargetPlaces(config, watchedTarget).map(
428
+ (place) => ({
429
+ targetName: watchedTarget,
430
+ packageName,
431
+ packagePath: cwd,
432
+ place,
433
+ })
434
+ ),
435
+ });
436
+ }
437
+ return;
438
+ }
439
+
302
440
  const publish = args.publish ?? false;
303
441
  const showLogs = args.logs ?? false;
304
442
 
@@ -322,9 +460,46 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
322
460
  OutputHelper.info(`Using target '${targetName}'.`);
323
461
  }
324
462
 
325
- const reporter = new CompositeReporter(
326
- targetNames,
327
- (state: LiveStateTracker) => {
463
+ const apiKey = await getApiKeyAsync(args);
464
+ const client = new OpenCloudClient({
465
+ apiKey,
466
+ rateLimiter: new RateLimiter(),
467
+ });
468
+
469
+ // Captured only for the success message printed after the run.
470
+ let publishedVersion: number | undefined;
471
+ let publishedPlaceId: number | undefined;
472
+
473
+ // One deploy, start to finish. Factored out because a local watch runs it
474
+ // again on every base place change, and each pass needs its own reporter,
475
+ // resolver and job context — sharing them across passes would replay a
476
+ // finished progress display and reuse an already-flushed lock.
477
+ const runDeployPassAsync = async (
478
+ refresh: boolean
479
+ ): Promise<{ failed: number; resolver: BasePlaceResolver }> => {
480
+ const reporter = _buildReporter();
481
+ // A rebuild triggered by the base place moving must re-resolve the pin,
482
+ // or it rebuilds the version it already shipped.
483
+ const basePlaceResolver = createBasePlaceResolver(client, {
484
+ frozenLockfile: refresh ? false : args.frozenLockfile,
485
+ refreshBasePlace: refresh || args.refreshBasePlace,
486
+ });
487
+ const context = new CloudJobContext(reporter, client, basePlaceResolver);
488
+
489
+ await reporter.startAsync();
490
+ let failed = 0;
491
+ try {
492
+ const results = await _runBatchAsync(context, reporter);
493
+ failed = results.summary.failed;
494
+ } finally {
495
+ await context.disposeAsync();
496
+ }
497
+ await reporter.stopAsync();
498
+ return { failed, resolver: basePlaceResolver };
499
+ };
500
+
501
+ function _buildReporter(): CompositeReporter {
502
+ return new CompositeReporter(targetNames, (state: LiveStateTracker) => {
328
503
  const reporters: Reporter[] = [];
329
504
  if (isMultiPlace) {
330
505
  reporters.push(
@@ -377,25 +552,11 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
377
552
  );
378
553
  }
379
554
  return reporters;
380
- }
381
- );
382
-
383
- const apiKey = await getApiKeyAsync(args);
384
- const client = new OpenCloudClient({
385
- apiKey,
386
- rateLimiter: new RateLimiter(),
387
- });
388
- const context = new CloudJobContext(reporter, client);
389
-
390
- await reporter.startAsync();
391
-
392
- let exitCode = 0;
393
- // Captured only for the single-place success message printed after the run.
394
- let publishedVersion: number | undefined;
395
- let publishedPlaceId: number | undefined;
555
+ });
556
+ }
396
557
 
397
- try {
398
- const results = await runBatchAsync<BatchTarget, BatchDeployResult>({
558
+ function _runBatchAsync(context: CloudJobContext, reporter: Reporter) {
559
+ return runBatchAsync<BatchTarget, BatchDeployResult>({
399
560
  items: batchTargets,
400
561
  concurrency: isMultiPlace ? MULTI_PLACE_CONCURRENCY : 1,
401
562
  reporter,
@@ -460,16 +621,147 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
460
621
  };
461
622
  },
462
623
  });
463
- if (results.summary.failed > 0) exitCode = 1;
624
+ }
625
+
626
+ let exitCode = 0;
627
+ let watchResult: RegisterWatchesResult | undefined;
628
+ const watchedTarget = parseTargetSelector(targetName).targetName;
629
+
630
+ try {
631
+ const first = await runDeployPassAsync(args.refreshBasePlace ?? false);
632
+ if (first.failed > 0) exitCode = 1;
633
+
634
+ // Only after a clean deploy: what happens next records the base place
635
+ // version that just shipped, which is not a fact yet if the deploy failed.
636
+ if (watchOption && first.failed === 0) {
637
+ if (isCI()) {
638
+ // The monitor is named for the whole target, so it has to carry every
639
+ // place in that target — not just the ones this invocation deployed.
640
+ // Re-registering replaces its watch list, so a narrowed selector
641
+ // (`integration.places.hub`) would otherwise delete the sibling
642
+ // places' watches. Places that did not deploy keep their lock baseline.
643
+ watchResult = await registerWatchesAsync({
644
+ option: watchOption,
645
+ // Scoped to this package and target, so deploying one package can
646
+ // never replace the watch list another package registered.
647
+ monitorName: `${packageName}/${watchedTarget}`,
648
+ resolver: first.resolver,
649
+ useGhAuth: args.watchUseGhAuth,
650
+ robloxApiKey: args.watchShareApiKey ? apiKey : undefined,
651
+ candidates: resolveDeployTargetPlaces(config, watchedTarget).map(
652
+ (place) => ({
653
+ targetName: watchedTarget,
654
+ packageName,
655
+ packagePath: cwd,
656
+ place,
657
+ })
658
+ ),
659
+ });
660
+ } else {
661
+ // Locally the rebuild belongs here, not on a runner, so the watch
662
+ // asks to be told rather than to dispatch. Being told beats polling —
663
+ // no Open Cloud quota per developer, and the rebuild starts when the
664
+ // change lands — but polling still works everywhere, so it is what
665
+ // this falls back to.
666
+ const localEntries = await _buildLocalWatchEntriesAsync(
667
+ config,
668
+ watchedTarget,
669
+ cwd,
670
+ first.resolver
671
+ );
672
+ const redeployAsync = async () => {
673
+ const pass = await runDeployPassAsync(true);
674
+ if (pass.failed > 0) {
675
+ throw new Error('deploy failed');
676
+ }
677
+ };
678
+
679
+ const notify = await tryRegisterNotifyWatchesAsync({
680
+ option: watchOption,
681
+ monitorName: `${packageName}/${watchedTarget}`,
682
+ entries: localEntries,
683
+ useGhAuth: args.watchUseGhAuth,
684
+ robloxApiKey: args.watchShareApiKey ? apiKey : undefined,
685
+ });
686
+
687
+ // Streaming is preferred but never required: whatever the reason it
688
+ // is unavailable, polling from here still works.
689
+ let pollInstead = true;
690
+ if (notify.success) {
691
+ // Anything the stream throws is still just "streaming did not
692
+ // work", and the promise above says polling covers that however it
693
+ // happens. Letting it escape to the handler's catch would exit the
694
+ // run instead — reporting a failure for a watch that could simply
695
+ // have carried on here.
696
+ let loop;
697
+ try {
698
+ loop = await runStreamWatchLoopAsync({
699
+ entries: notify.entries,
700
+ stream: new WebSocketWatchStream({
701
+ registerUrl: watchOption.registerUrl,
702
+ }),
703
+ // The stream says a place moved; Open Cloud says what it moved
704
+ // to. The two speak different version vocabularies, and only
705
+ // this one matches what the lock records.
706
+ source: client,
707
+ monitorId: notify.monitorId,
708
+ credential: notify.credential,
709
+ redeployAsync,
710
+ });
711
+ } catch (err) {
712
+ OutputHelper.warn(
713
+ 'Could not hold the watch stream: ' +
714
+ (err instanceof Error ? err.message : String(err))
715
+ );
716
+ loop = undefined;
717
+ }
718
+ if (loop && loop.failures > 0) exitCode = 1;
719
+ // The service could not read any of these places — a private base
720
+ // place, say. This machine has credentials it does not, so the
721
+ // watch carries on here rather than waiting on a socket that will
722
+ // never say anything.
723
+ //
724
+ // A lapsed lease or a refused handshake ends the stream just as
725
+ // finally, and the user asked to keep watching either way — exiting
726
+ // there would report success while silently doing nothing.
727
+ pollInstead =
728
+ loop == null ||
729
+ loop.unobservable ||
730
+ loop.monitorGone ||
731
+ loop.rejected;
732
+ if (pollInstead) {
733
+ OutputHelper.info(
734
+ 'Watching from here instead, using your own Open Cloud key.'
735
+ );
736
+ }
737
+ } else if (notify.reason !== 'no_entries') {
738
+ // Not cosmetic, so not verbose-only: polling spends this machine's
739
+ // Open Cloud quota on a timer and notices a change up to an
740
+ // interval late, and the usual cause is one flag away from being
741
+ // fixed. A user who never sees why cannot choose.
742
+ OutputHelper.info(
743
+ `Watching by polling rather than streaming: ${describeNotifyWatchFallback(
744
+ notify
745
+ )}.`
746
+ );
747
+ }
748
+
749
+ if (pollInstead) {
750
+ const loop = await runLocalWatchLoopAsync({
751
+ entries: localEntries,
752
+ source: client,
753
+ durationMs: watchOption.durationMs,
754
+ redeployAsync,
755
+ });
756
+ if (loop.failures > 0) exitCode = 1;
757
+ }
758
+ }
759
+ }
464
760
  } catch (err) {
465
761
  OutputHelper.error(err instanceof Error ? err.message : String(err));
466
762
  exitCode = 1;
467
- } finally {
468
- await context.disposeAsync();
469
763
  }
470
764
 
471
- await reporter.stopAsync();
472
-
473
765
  if (publishedVersion !== undefined) {
474
766
  const placeUrl =
475
767
  publishedPlaceId !== undefined
@@ -491,6 +783,13 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
491
783
  }
492
784
  }
493
785
 
786
+ if (watchResult && watchResult.registered > 0) {
787
+ OutputHelper.hint(
788
+ 'The watch rebuilds this target when its base place moves. Re-run ' +
789
+ 'with --watch to renew the lease before it expires.'
790
+ );
791
+ }
792
+
494
793
  if (exitCode !== 0) process.exit(exitCode);
495
794
  }
496
795
  }
@@ -5,7 +5,7 @@ import {
5
5
  resolveDefaultTargetName,
6
6
  resolveDeployConfigPath,
7
7
  resolveDeployTargetPlaces,
8
- } from '../../utils/build/deploy-config.js';
8
+ } from '@quenty/nevermore-deploy';
9
9
 
10
10
  export interface SelectTargetOptions {
11
11
  explicitTarget?: string;