Merge pull request #72 from 1012839419a-alt/feat/dev-toolchain

chore(dev): dev environment doctor + standardized dev commands + CI uv migration

Author: 2233admin

scripts/dev-environment.mjs

@@ -6,6 +6,7 @@ const root = process.cwd()
 const args = process.argv.slice(2)
 const envFileArg = args.find((arg) => arg.startsWith('--env-file='))
 const profilesArg = args.find((arg) => arg.startsWith('--profiles='))
+const skipTools = args.includes('--skip-tools')
 const envFile = path.resolve(root, envFileArg?.slice('--env-file='.length) || '.env')
 
 function parseEnv(file) {
@@ -95,11 +96,24 @@ const rules = {
     for (const name of ['POSTGRES_DB', 'POSTGRES_USER', 'POSTGRES_PASSWORD']) requireValue(name, 'postgres')
   },
   agent() {
-    requireValue('CENTRAL_API_URL', 'agent')
-    requireValue('API_AUTH_TOKEN', 'agent')
-    const registration = value('AGENT_REGISTER') || 'http'
-    if (!['http', 'ws'].includes(registration)) errors.push('[agent] AGENT_REGISTER must be http or ws')
-    if (registration === 'http') requireValue('AGENT_ADVERTISE_URL', 'agent')
+    const registration = (value('AGENT_REGISTER') || 'http').toLowerCase()
+    if (!['http', 'ws', 'off'].includes(registration)) {
+      errors.push('[agent] AGENT_REGISTER must be http, ws, or off')
+      return
+    }
+    if (registration === 'off') return
+
+    const agentToken = value('AGENT_API_TOKEN') || value('API_AUTH_TOKEN')
+    if (!agentToken) errors.push('[agent] configure AGENT_API_TOKEN or API_AUTH_TOKEN')
+
+    const centralApiUrl = value('CENTRAL_API_URL')
+    if (!centralApiUrl) {
+      notes.push('[agent] CENTRAL_API_URL is empty; auto-registration is disabled')
+      return
+    }
+    if (!value('AGENT_ADVERTISE_URL')) {
+      notes.push('[agent] AGENT_ADVERTISE_URL is empty; the agent URL will be auto-detected')
+    }
   },
   'embedded-chrome'() {
     requireExact('CHROME_SUFFIX', '-chrome', 'embedded-chrome')
@@ -133,9 +147,15 @@ const expectedNode = existsSync(path.join(root, '.nvmrc')) ? readFileSync(path.j
 if (expectedNode && nodeVersion.split('.')[0] !== expectedNode.split('.')[0]) {
   errors.push(`[tools] Node ${expectedNode}.x required; active version is ${nodeVersion}`)
 }
-checkCommand('uv', ['--version'], 'uv')
-checkCommand('uv', ['lock', '--check'], 'uv lock')
-checkCommand('docker', ['compose', '--env-file', envFile, '-f', 'docker-compose.yml', '-f', 'docker-compose.build.yml', 'config', '--quiet'], 'Docker Compose configuration')
+if (!skipTools) {
+  checkCommand('uv', ['--version'], 'uv')
+  checkCommand('uv', ['lock', '--check'], 'uv lock')
+  checkCommand(
+    'docker',
+    ['compose', '--env-file', envFile, '-f', 'docker-compose.yml', '-f', 'docker-compose.build.yml', 'config', '--quiet'],
+    'Docker Compose configuration',
+  )
+}
 
 for (const note of notes) console.log(`NOTE ${note}`)
 if (errors.length) {

scripts/dev-environment.test.mjs

@@ -16,29 +16,75 @@ function envFile(contents) {
   return file
 }
 
+function doctorArgs(file, ...extraArgs) {
+  return [script, `--env-file=${file}`, '--skip-tools', ...extraArgs]
+}
+
 test('accepts the default core profile with an empty Chrome suffix', () => {
-  const output = execFileSync(process.execPath, [script, `--env-file=${envFile(validCore)}`], {
+  const output = execFileSync(process.execPath, doctorArgs(envFile(validCore)), {
     cwd: root,
     encoding: 'utf8',
   })
   assert.match(output, /Environment ready: core/)
 })
 
 test('rejects embedded Chrome without the image suffix', () => {
-  const result = spawnSync(process.execPath, [script, `--env-file=${envFile(validCore)}`, '--profiles=embedded-chrome'], {
+  const result = spawnSync(
+    process.execPath,
+    doctorArgs(envFile(validCore), '--profiles=embedded-chrome'),
+    {
+      cwd: root,
+      encoding: 'utf8',
+    },
+  )
+  assert.notEqual(result.status, 0)
+  assert.match(result.stderr, /CHROME_SUFFIX (?:is required|must be -chrome)/)
+})
+
+test('accepts AGENT_REGISTER=off without a central URL', () => {
+  const file = envFile(`${validCore}AGENT_REGISTER=off\n`)
+  const output = execFileSync(process.execPath, doctorArgs(file, '--profiles=agent'), {
     cwd: root,
     encoding: 'utf8',
   })
-  assert.notEqual(result.status, 0)
-  assert.match(result.stderr, /CHROME_SUFFIX (?:is required|must be -chrome)/)
+  assert.match(output, /Environment ready: core, agent/)
+})
+
+test('allows active registration modes to skip auto-registration without a central URL', () => {
+  for (const registration of ['http', 'ws']) {
+    const file = envFile(`${validCore}AGENT_REGISTER=${registration}\n`)
+    const output = execFileSync(process.execPath, doctorArgs(file, '--profiles=agent'), {
+      cwd: root,
+      encoding: 'utf8',
+    })
+    assert.match(output, /CENTRAL_API_URL is empty; auto-registration is disabled/)
+  }
 })
 
-test('rejects HTTP agent registration without an advertised URL', () => {
+test('accepts HTTP registration with an auto-detected advertised URL', () => {
   const file = envFile(`${validCore}CENTRAL_API_URL=http://center:8031\nAGENT_REGISTER=http\n`)
-  const result = spawnSync(process.execPath, [script, `--env-file=${file}`, '--profiles=agent'], {
+  const output = execFileSync(process.execPath, doctorArgs(file, '--profiles=agent'), {
+    cwd: root,
+    encoding: 'utf8',
+  })
+  assert.match(output, /AGENT_ADVERTISE_URL is empty; the agent URL will be auto-detected/)
+})
+
+test('accepts WS registration with an auto-detected advertised URL', () => {
+  const file = envFile(`${validCore}CENTRAL_API_URL=http://center:8031\nAGENT_REGISTER=ws\n`)
+  const output = execFileSync(process.execPath, doctorArgs(file, '--profiles=agent'), {
+    cwd: root,
+    encoding: 'utf8',
+  })
+  assert.match(output, /Environment ready: core, agent/)
+})
+
+test('rejects an unsupported agent registration mode', () => {
+  const file = envFile(`${validCore}AGENT_REGISTER=udp\n`)
+  const result = spawnSync(process.execPath, doctorArgs(file, '--profiles=agent'), {
     cwd: root,
     encoding: 'utf8',
   })
   assert.notEqual(result.status, 0)
-  assert.match(result.stderr, /AGENT_ADVERTISE_URL is required/)
+  assert.match(result.stderr, /AGENT_REGISTER must be http, ws, or off/)
 })