feat(ql3): add generic worker management entry

packages/ql3-cluster-admin/test/productCli.test.cjs

@@ -284,6 +284,13 @@ function validContextFixture(t) {
     copilot: { configFile: copilotConfig },
     package: { configFile: packageConfig },
     'package-kubernetes': { configFile: packageConfig, kubernetesFile },
+    worker: {
+      configFile: config(
+        'worker-observation-client',
+        '/api/v3/workers/management',
+        'required',
+      ),
+    },
     'worker-credential': {
       configFile: config(
         'worker-client',
@@ -329,7 +336,7 @@ function validContextFixture(t) {
 
 test('catalog exposes only reviewed product entrypoints from the same package', () => {
   assert.equal(manifest.bin['ql3-cluster-admin'], 'dist/product-cli/cli.js');
-  assert.equal(QINGLONG3_CLUSTER_PRODUCT_COMMANDS.length, 11);
+  assert.equal(QINGLONG3_CLUSTER_PRODUCT_COMMANDS.length, 12);
   assert.equal(
     new Set(QINGLONG3_CLUSTER_PRODUCT_COMMANDS.map(({ name }) => name)).size,
     QINGLONG3_CLUSTER_PRODUCT_COMMANDS.length,
@@ -617,7 +624,7 @@ test('validates the complete operator context offline without operational author
     schemaVersion: 1,
     component: 'qinglong3-cluster-product-cli',
     event: 'context_valid',
-    commandCount: 8,
+    commandCount: 9,
     commands: [
       { name: 'copilot', transport: 'https', clientCertificate: 'forbidden' },
       { name: 'package', transport: 'https', clientCertificate: 'forbidden' },
@@ -627,6 +634,11 @@ test('validates the complete operator context offline without operational author
         clientCertificate: 'forbidden',
         kubernetesAuthentication: 'token',
       },
+      {
+        name: 'worker',
+        transport: 'https',
+        clientCertificate: 'required',
+      },
       {
         name: 'worker-credential',
         transport: 'https',

packages/ql3-cluster-admin/test/workerCredentialManagementHttp.test.cjs

@@ -56,6 +56,7 @@ const NEXT_CLIENT_KEY = resolve(
   'fixtures/management-service-key.pem',
 );
 const WORKER_PATH = '/api/v3/worker-credentials/management';
+const CANONICAL_WORKER_PATH = '/api/v3/workers/management';
 
 function command() {
   return {
@@ -223,7 +224,7 @@ async function requestWithClientIdentity(application, certificate, key) {
   });
 }
 
-test('serves only the fixed Worker credential management route', async () => {
+test('serves the canonical Worker route and exact credential compatibility alias', async () => {
   const calls = [];
   const application = await start(async (value, authentication) => {
     calls.push({ value, principal: await authentication.authenticate() });
@@ -245,12 +246,15 @@ test('serves only the fixed Worker credential management route', async () => {
       type: 'user',
       id: 'cluster-reviewer',
     });
+    const canonical = await request(application, CANONICAL_WORKER_PATH);
+    assert.equal(canonical.statusCode, 200);
+    assert.equal(canonical.body.result.operation, 'worker-credential.inspect');
     assert.equal(
       (await request(application, '/api/v3/plugin-packages/management'))
         .statusCode,
       404,
     );
-    assert.equal(calls.length, 1);
+    assert.equal(calls.length, 2);
   } finally {
     await application.close();
   }
@@ -312,10 +316,18 @@ test('rejects a CRL-revoked client certificate before OIDC', async () => {
 
 test('maps Worker credential management failures to stable HTTP errors', async () => {
   for (const [failure, statusCode, code] of [
-    [new WorkerCredentialManagementRequestError('invalid'), 400, 'request_invalid'],
+    [
+      new WorkerCredentialManagementRequestError('invalid'),
+      400,
+      'request_invalid',
+    ],
     [new WorkerCredentialManagementAuthorizationError(), 403, 'forbidden'],
     [new WorkerCredentialManagementConflictError('conflict'), 409, 'conflict'],
-    [new WorkerCredentialManagementQuotaExceededError(1_250), 429, 'quota_exceeded'],
+    [
+      new WorkerCredentialManagementQuotaExceededError(1_250),
+      429,
+      'quota_exceeded',
+    ],
     [new WorkerCredentialManagementUnavailableError(), 503, 'unavailable'],
   ]) {
     const application = await start(async () => {
@@ -353,6 +365,34 @@ test('rejects arbitrary management paths at configuration time', async () => {
   }
 });
 
+test('rejects arbitrary or cross-plane compatible route aliases', async () => {
+  for (const compatibleManagementPaths of [
+    ['/api/v3/automations/management'],
+    ['/api/v3/worker-credentials/management', '/api/v3/runs/management'],
+  ]) {
+    const privateKey = Buffer.from(readFileSync(SERVER_KEY));
+    try {
+      await assert.rejects(
+        startClusterPluginPackageManagementHttp({
+          host: '127.0.0.1',
+          port: 0,
+          tls: {
+            privateKey,
+            certificate: Buffer.from(readFileSync(SERVER_CERT)),
+          },
+          identities: identities(),
+          transport: { async execute() {} },
+          managementPath: CANONICAL_WORKER_PATH,
+          compatibleManagementPaths,
+        }),
+        ClusterPluginPackageManagementHttpConfigurationError,
+      );
+    } finally {
+      privateKey.fill(0);
+    }
+  }
+});
+
 test('accepts both client CAs during overlap then rejects the retired CA', async () => {
   const execute = async () => ({
     schemaVersion: 1,

packages/ql3-cluster-admin/test/workerManagementClient.test.cjs

@@ -0,0 +1,240 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const {
+  executeClusterWorkerManagementClient,
+  normalizeClusterWorkerManagementCommand,
+} = require('@qinglong/cluster-admin/worker-management-client');
+const {
+  createWorkerSessionInspectionCommand,
+  createWorkerSessionListCommand,
+  formatWorkerSessionInspectionCard,
+  formatWorkerSessionListCard,
+  projectWorkerSessionInspection,
+  projectWorkerSessionList,
+} = require('@qinglong/cluster-admin/worker-management-product');
+
+const fixtureRoot = path.resolve(
+  __dirname,
+  '../../ql3-cluster-control/test/fixtures/mtls',
+);
+const detailedWorker = Object.freeze({
+  workerId: 'worker-a',
+  sessionId: 'session-a',
+  generation: 2,
+  sessionVersion: 5,
+  lifecycle: 'online',
+  compatibility: 'default_placement',
+  architecture: 'arm64',
+  supportTier: 'tier1',
+  protocolVersion: '1.0.0',
+  operatingSystem: 'linux',
+  maxConcurrentRuns: 2,
+  availableSlots: 1,
+  registeredAtMs: 900,
+  lastHeartbeatAtMs: 1_050,
+  leaseExpiresAtMs: 2_000,
+  updatedAtMs: 1_050,
+  observedAtMs: 1_100,
+  runtimes: Object.freeze([{ name: 'node', version: '24.18.0' }]),
+  declaredCapacity: Object.freeze({
+    cpuCores: 1,
+    memoryBytes: 268_435_456,
+    diskBytes: 1_073_741_824,
+    gpuCount: 0,
+  }),
+});
+const summaryWorker = Object.freeze(
+  Object.fromEntries(
+    Object.entries(detailedWorker).filter(
+      ([key]) => key !== 'runtimes' && key !== 'declaredCapacity',
+    ),
+  ),
+);
+
+function response(result) {
+  return Object.freeze({
+    schemaVersion: 1,
+    requestId: 'transport-request-must-not-project',
+    result: Object.freeze(result),
+  });
+}
+
+function privateFile(directory, name, value) {
+  const filePath = path.join(directory, name);
+  fs.writeFileSync(filePath, value, { mode: 0o600 });
+  return fs.realpathSync(filePath);
+}
+
+test('builds only immutable inspect and bounded list commands', () => {
+  const inspect = createWorkerSessionInspectionCommand(
+    'project-a',
+    'worker-a',
+    () => 'inspection-a',
+  );
+  assert.deepEqual(inspect, {
+    schemaVersion: 1,
+    operation: 'worker-session.inspect',
+    request: {
+      authorityProjectId: 'project-a',
+      workerId: 'worker-a',
+      inspectionId: 'inspection-a',
+    },
+  });
+  assert.equal(Object.isFrozen(inspect), true);
+  assert.equal(Object.isFrozen(inspect.request), true);
+
+  const page = createWorkerSessionListCommand(
+    'project-a',
+    'worker-a',
+    () => 'inspection-b',
+  );
+  assert.deepEqual(page.request, {
+    authorityProjectId: 'project-a',
+    afterWorkerId: 'worker-a',
+    inspectionId: 'inspection-b',
+  });
+  assert.equal(Object.hasOwn(page.request, 'limit'), false);
+  assert.throws(() => createWorkerSessionListCommand('../escape'));
+  assert.throws(() =>
+    normalizeClusterWorkerManagementCommand({
+      schemaVersion: 1,
+      operation: 'worker-credential.inspect',
+      request: {
+        actionRef: 'action-a',
+        authorityProjectId: 'project-a',
+        approvalRequestId: 'approval-a',
+        inspectionId: 'inspection-a',
+      },
+    }),
+  );
+});
+
+test('projects strict low-sensitive products without transport request identity', () => {
+  const inspection = projectWorkerSessionInspection(
+    'project-a',
+    response({
+      schemaVersion: 1,
+      operation: 'worker-session.inspect',
+      observedAtMs: 1_100,
+      worker: detailedWorker,
+    }),
+  );
+  assert.equal(inspection.schema, 'qinglong/worker-session-inspection@v1');
+  assert.equal(inspection.found, true);
+  assert.equal(inspection.worker.workerId, 'worker-a');
+  assert.equal(Object.isFrozen(inspection.worker.runtimes), true);
+  assert.doesNotMatch(
+    JSON.stringify(inspection),
+    /transport-request|inspectionId/,
+  );
+  assert.match(
+    formatWorkerSessionInspectionCard(inspection),
+    /slots available/,
+  );
+
+  const page = projectWorkerSessionList(
+    'project-a',
+    response({
+      schemaVersion: 1,
+      operation: 'worker-session.list',
+      observedAtMs: 1_100,
+      workers: [summaryWorker],
+      nextCursor: 'worker-a',
+    }),
+  );
+  assert.deepEqual(
+    {
+      schema: page.schema,
+      count: page.count,
+      nextAfterWorkerId: page.nextAfterWorkerId,
+    },
+    {
+      schema: 'qinglong/worker-session-list@v1',
+      count: 1,
+      nextAfterWorkerId: 'worker-a',
+    },
+  );
+  assert.match(formatWorkerSessionListCard(page), /worker-a  online/);
+  assert.throws(() =>
+    projectWorkerSessionInspection(
+      'project-a',
+      response({
+        schemaVersion: 1,
+        operation: 'worker-session.list',
+        observedAtMs: 1_100,
+        workers: [],
+        nextCursor: null,
+      }),
+    ),
+  );
+});
+
+test('requires the canonical Worker endpoint before making a connection', async (t) => {
+  const directory = fs.realpathSync(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-worker-product-client-')),
+  );
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const caFile = privateFile(
+    directory,
+    'ca.pem',
+    fs.readFileSync(path.join(fixtureRoot, 'ca-cert.pem')),
+  );
+  const clientCertificateFile = privateFile(
+    directory,
+    'client.crt',
+    fs.readFileSync(path.join(fixtureRoot, 'client-cert.pem')),
+  );
+  const clientPrivateKeyFile = privateFile(
+    directory,
+    'client.key',
+    fs.readFileSync(path.join(fixtureRoot, 'client-key.pem')),
+  );
+  const assertionFile = privateFile(
+    directory,
+    'assertion.jwt',
+    'eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiJ1In0.c2lnbmF0dXJl',
+  );
+  const command = createWorkerSessionListCommand(
+    'project-a',
+    undefined,
+    () => 'inspection-a',
+  );
+
+  for (const [managementPath, expectedConnections] of [
+    ['/api/v3/workers/management', 1],
+    ['/api/v3/worker-credentials/management', 0],
+  ]) {
+    const configFile = privateFile(
+      directory,
+      `client-${expectedConnections}.json`,
+      JSON.stringify({
+        schemaVersion: 1,
+        endpoint: `https://manager.example.test:8443${managementPath}`,
+        servername: 'manager.example.test',
+        caFile,
+        clientCertificateFile,
+        clientPrivateKeyFile,
+        requestTimeoutMs: 1_000,
+      }),
+    );
+    let connections = 0;
+    await assert.rejects(
+      executeClusterWorkerManagementClient(
+        { configFile, assertionFile, command },
+        {
+          async connect() {
+            connections += 1;
+            throw new Error('stop-after-policy-validation');
+          },
+        },
+      ),
+    );
+    assert.equal(connections, expectedConnections);
+  }
+});

packages/ql3-cluster-admin/test/workerManagementClientCli.test.cjs

@@ -0,0 +1,256 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const { createServer } = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const packageRoot = path.resolve(__dirname, '..');
+const cliPath = path.join(
+  packageRoot,
+  'dist',
+  'worker-management',
+  'workerManagementClientCli.js',
+);
+const fixtureRoot = path.resolve(
+  packageRoot,
+  '../ql3-cluster-control/test/fixtures/mtls',
+);
+
+function privateFile(directory, name, value) {
+  const filePath = path.join(directory, name);
+  fs.writeFileSync(filePath, value, { mode: 0o600 });
+  return fs.realpathSync(filePath);
+}
+
+function runCli(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      cwd: packageRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('close', (status, signal) => {
+      resolve({
+        status,
+        signal,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      });
+    });
+  });
+}
+
+function summary(workerId) {
+  return {
+    workerId,
+    sessionId: `session-${workerId}`,
+    generation: 1,
+    sessionVersion: 1,
+    lifecycle: 'online',
+    compatibility: 'default_placement',
+    architecture: 'arm64',
+    supportTier: 'tier1',
+    protocolVersion: '1.0.0',
+    operatingSystem: 'linux',
+    maxConcurrentRuns: 1,
+    availableSlots: 1,
+    registeredAtMs: 900,
+    lastHeartbeatAtMs: 1_000,
+    leaseExpiresAtMs: 2_000,
+    updatedAtMs: 1_000,
+    observedAtMs: 1_100,
+  };
+}
+
+test('CLI performs one canonical read per invocation and rejects mutation vocabulary', async (t) => {
+  const directory = fs.realpathSync(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-worker-cli-')),
+  );
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const requests = [];
+  const server = createServer(
+    {
+      key: fs.readFileSync(path.join(fixtureRoot, 'server-key.pem')),
+      cert: fs.readFileSync(path.join(fixtureRoot, 'server-cert.pem')),
+      ca: fs.readFileSync(path.join(fixtureRoot, 'ca-cert.pem')),
+      requestCert: true,
+      rejectUnauthorized: true,
+      minVersion: 'TLSv1.3',
+      maxVersion: 'TLSv1.3',
+    },
+    (request, response) => {
+      const chunks = [];
+      request.on('data', (chunk) => chunks.push(chunk));
+      request.on('end', () => {
+        const command = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        requests.push({
+          method: request.method,
+          path: request.url,
+          authorized: request.socket.authorized,
+          command,
+        });
+        const worker = summary('worker-a');
+        const result =
+          command.operation === 'worker-session.inspect'
+            ? {
+                schemaVersion: 1,
+                operation: 'worker-session.inspect',
+                observedAtMs: 1_100,
+                worker: {
+                  ...worker,
+                  runtimes: [{ name: 'node', version: '24.18.0' }],
+                  declaredCapacity: {
+                    cpuCores: 1,
+                    memoryBytes: 268_435_456,
+                    diskBytes: 1_073_741_824,
+                    gpuCount: 0,
+                  },
+                },
+              }
+            : {
+                schemaVersion: 1,
+                operation: 'worker-session.list',
+                observedAtMs: 1_100,
+                workers: [worker],
+                nextCursor: null,
+              };
+        const body = Buffer.from(
+          JSON.stringify({
+            schemaVersion: 1,
+            requestId: 'server-request-hidden',
+            result,
+          }),
+        );
+        response.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8',
+          'content-length': String(body.length),
+        });
+        response.end(body);
+      });
+    },
+  );
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  t.after(
+    () =>
+      new Promise((resolve) => {
+        server.close(() => resolve());
+      }),
+  );
+  const address = server.address();
+  assert.notEqual(address, null);
+  assert.notEqual(typeof address, 'string');
+  const caFile = privateFile(
+    directory,
+    'ca.pem',
+    fs.readFileSync(path.join(fixtureRoot, 'ca-cert.pem')),
+  );
+  const clientCertificateFile = privateFile(
+    directory,
+    'client.crt',
+    fs.readFileSync(path.join(fixtureRoot, 'client-cert.pem')),
+  );
+  const clientPrivateKeyFile = privateFile(
+    directory,
+    'client.key',
+    fs.readFileSync(path.join(fixtureRoot, 'client-key.pem')),
+  );
+  const configFile = privateFile(
+    directory,
+    'client.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      endpoint: `https://localhost:${address.port}/api/v3/workers/management`,
+      servername: 'localhost',
+      caFile,
+      clientCertificateFile,
+      clientPrivateKeyFile,
+      requestTimeoutMs: 2_000,
+    }),
+  );
+  const assertionFile = privateFile(
+    directory,
+    'assertion.jwt',
+    'eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiJ1In0.c2lnbmF0dXJl',
+  );
+
+  const inspect = await runCli([
+    'inspect',
+    `--config=${configFile}`,
+    `--assertion=${assertionFile}`,
+    '--project=project-a',
+    '--worker=worker-a',
+    '--format=json',
+  ]);
+  assert.equal(inspect.status, 0, inspect.stderr);
+  assert.equal(inspect.stderr, '');
+  const inspection = JSON.parse(inspect.stdout);
+  assert.equal(inspection.schema, 'qinglong/worker-session-inspection@v1');
+  assert.equal(inspection.worker.workerId, 'worker-a');
+  assert.equal(inspect.stdout.includes('server-request-hidden'), false);
+
+  const list = await runCli([
+    'list',
+    `--config=${configFile}`,
+    `--assertion=${assertionFile}`,
+    '--project=project-a',
+    '--format=json',
+  ]);
+  assert.equal(list.status, 0, list.stderr);
+  assert.equal(JSON.parse(list.stdout).count, 1);
+  assert.equal(requests.length, 2);
+  assert.deepEqual(
+    requests.map(({ method, path, authorized, command }) => ({
+      method,
+      path,
+      authorized,
+      operation: command.operation,
+    })),
+    [
+      {
+        method: 'POST',
+        path: '/api/v3/workers/management',
+        authorized: true,
+        operation: 'worker-session.inspect',
+      },
+      {
+        method: 'POST',
+        path: '/api/v3/workers/management',
+        authorized: true,
+        operation: 'worker-session.list',
+      },
+    ],
+  );
+
+  const rejected = await runCli([
+    'inspect',
+    `--config=${configFile}`,
+    `--assertion=${assertionFile}`,
+    '--project=project-a',
+    '--worker=worker-a',
+    '--command=/private/mutation.json',
+  ]);
+  assert.equal(rejected.status, 64);
+  assert.equal(requests.length, 2);
+  assert.equal(rejected.stdout, '');
+  assert.equal(JSON.parse(rejected.stderr).event, 'usage_invalid');
+});
+
+test('CLI help states its bounded read contract', async () => {
+  const help = await runCli(['--help']);
+  assert.equal(help.status, 0);
+  assert.match(help.stdout, /ql3-worker-client inspect/);
+  assert.match(help.stdout, /ql3-worker-client list/);
+  assert.match(help.stdout, /never retries, polls or auto-pages/);
+  assert.doesNotMatch(help.stdout, /credential|secret|token/i);
+});