@minhkhoa/aimanagement 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minhkhoa99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# AI Team (aimanagement)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Nền tảng điều phối nhiều agent AI theo phòng ban, chạy hoàn toàn trên máy của bạn.
+Agent dùng Claude Code, Codex (bằng tài khoản đã đăng nhập) hoặc Custom API.
+
+## Cài đặt và chạy
+
+Cần Node LTS đã vá bảo mật: 22.23.4+, 24.22.1+ hoặc 26.12.1+ ([tải Node](https://nodejs.org/en/download)).
+
+```
+npm i -g @minhkhoa/aimanagement
+aimanagement
+```
+
+Lệnh mở trình duyệt tại `http://127.0.0.1:7419` (cổng bận thì tự dùng cổng trống kế tiếp, URL thật
+được in ra). Không cần tải mã nguồn: gói đã có sẵn server bundle và giao diện tĩnh, không có
+dependency nào phải cài thêm.
+
+```
+aimanagement --port 8080      # chọn cổng khác
+aimanagement --no-open        # không tự mở trình duyệt
+aimanagement doctor           # kiểm tra node, git, Claude Code, Codex
+```
+
+- Dữ liệu và log nằm ở `~/.aiteam` (đổi bằng biến `AITEAM_HOME`); cổng ưu tiên đổi bằng `AITEAM_PORT`.
+- Server chỉ nghe `127.0.0.1`; chỉ trình duyệt mở bằng liên kết lệnh in ra mới vào được.
+- Agent chạy bằng Claude Code hoặc Codex cần CLI tương ứng đã cài và đăng nhập (`aimanagement doctor`).
+- Cập nhật: `npm i -g @minhkhoa/aimanagement@latest`. Gỡ: `npm rm -g @minhkhoa/aimanagement` (dữ liệu ở `~/.aiteam` vẫn giữ).
+
+## Phát triển
+
+```
+npm install
+npm run build
+node bin/aiteam.mjs          # như lệnh aimanagement, chạy từ mã nguồn
+npm run lint && npm test     # kiểm tra
+npm run test:smoke           # chạy thử bản build
+npm pack                     # tạo gói .tgz (tự build và chạy thử trước)
+```
+
+Quy tắc code: [CLAUDE.md](CLAUDE.md).
+
+- [Kế hoạch thực hiện](docs/IMPLEMENTATION_PLAN.md)
+- [Kế hoạch mapping giao diện](docs/UI_MAPPING.md)
+- [Giao diện mẫu tương tác](docs/design/aiteam-ui.html) (tải về rồi mở bằng trình duyệt)
+
+Công nghệ: NestJS, Next.js, SQLite (`node:sqlite`). Giấy phép: [MIT](LICENSE).

package/bin/aiteam.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// Launcher of the `aimanagement` command (AI Team). Four jobs only: check Node, prepare ~/.aiteam, load the bundled server
+// (which applies migrations and listens on 127.0.0.1), open the browser.
+// Sub-command: `aimanagement doctor` checks the local toolchain.
+import { evaluateNodeVersion } from './node-version-policy.mjs';
+
+const nodeVerdict = evaluateNodeVersion(process.version);
+if (!nodeVerdict.accepted && process.argv[2] !== 'doctor') {
+  console.error(`aimanagement: ${nodeVerdict.reason}`);
+  console.error('Tải bản vá tại https://nodejs.org/en/download');
+  process.exit(1);
+}
+
+// node:sqlite prints an ExperimentalWarning on every start. Hide exactly that one; every other
+// process warning is still printed.
+process.removeAllListeners('warning');
+process.on('warning', (warning) => {
+  const isSqliteExperimentalWarning =
+    warning.name === 'ExperimentalWarning' && /SQLite/i.test(warning.message);
+  if (!isSqliteExperimentalWarning) {
+    console.warn(`${warning.name}: ${warning.message}`);
+  }
+});
+
+const { spawn, spawnSync } = await import('node:child_process');
+const { randomBytes } = await import('node:crypto');
+const { existsSync, mkdirSync, readFileSync } = await import('node:fs');
+const { createRequire } = await import('node:module');
+const { homedir } = await import('node:os');
+const path = (await import('node:path')).default;
+const { fileURLToPath } = await import('node:url');
+const { parseArgs } = await import('node:util');
+
+const SESSION_TOKEN_BYTES = 32;
+const DOCTOR_COMMAND_TIMEOUT_MS = 15_000;
+
+const binDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(binDirectory, '..');
+const serverBundlePath = path.join(packageRoot, 'dist', 'server', 'aiteam-server.cjs');
+const webRootDirectory = path.join(packageRoot, 'dist', 'web');
+
+function readPackageVersion() {
+  const packageManifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  return packageManifest.version;
+}
+
+function printUsage() {
+  console.log(`Cách dùng:
+  aimanagement [--port <số>] [--no-open]   Khởi động AI Team và mở trình duyệt
+  aimanagement doctor                      Kiểm tra Node, git, Claude Code, Codex
+
+Cổng: --port, nếu không có thì AITEAM_PORT, nếu không có thì 7419.
+Cổng đang bận thì tự thử cổng trống kế tiếp; URL in ra là cổng thật.
+
+Biến môi trường:
+  AITEAM_HOME   Thư mục dữ liệu (mặc định ~/.aiteam)
+  AITEAM_PORT   Cổng ưu tiên`);
+}
+
+function parseLauncherArguments(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      port: { type: 'string' },
+      'no-open': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  return {
+    subcommand: positionals[0],
+    portOverride: values.port,
+    shouldOpenBrowser: !values['no-open'],
+    shouldPrintHelp: values.help,
+  };
+}
+
+/** --port wins over AITEAM_PORT, which wins over the default port. */
+function resolvePreferredPort(portOverride, defaultPort) {
+  const [sourceLabel, rawPort] =
+    portOverride !== undefined
+      ? ['--port', portOverride]
+      : process.env.AITEAM_PORT !== undefined && process.env.AITEAM_PORT !== ''
+        ? ['AITEAM_PORT', process.env.AITEAM_PORT]
+        : ['mặc định', String(defaultPort)];
+  const port = Number(rawPort);
+  if (!/^\d+$/.test(rawPort) || port < 1 || port > 65_535) {
+    throw new Error(`${sourceLabel} phải là số nguyên 1-65535, nhận được "${rawPort}".`);
+  }
+  return port;
+}
+
+function resolveAiteamHome() {
+  return process.env.AITEAM_HOME ?? path.join(homedir(), '.aiteam');
+}
+
+function prepareDataDirectories(aiteamHome) {
+  const directories = {
+    dataDirectory: path.join(aiteamHome, 'data'),
+    logDirectory: path.join(aiteamHome, 'logs'),
+  };
+  for (const directory of Object.values(directories)) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+  return directories;
+}
+
+function openBrowser(url) {
+  const [command, args] =
+    process.platform === 'win32'
+      ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  const browserProcess = spawn(command, args, { detached: true, stdio: 'ignore' });
+  browserProcess.on('error', (error) => {
+    console.warn(`Không mở được trình duyệt (${error.message}). Hãy tự mở URL ở trên.`);
+  });
+  browserProcess.unref();
+}
+
+async function startApplication(options) {
+  if (!existsSync(serverBundlePath)) {
+    throw new Error(`Không tìm thấy ${serverBundlePath}. Chạy "npm run build" trước.`);
+  }
+  const aiteamHome = resolveAiteamHome();
+  const { dataDirectory, logDirectory } = prepareDataDirectories(aiteamHome);
+  const version = readPackageVersion();
+  const sessionToken = randomBytes(SESSION_TOKEN_BYTES).toString('base64url');
+
+  const { startAiteamServer, DEFAULT_SERVER_PORT, SESSION_QUERY_PARAM } = createRequire(
+    import.meta.url,
+  )(serverBundlePath);
+  const preferredPort = resolvePreferredPort(options.portOverride, DEFAULT_SERVER_PORT);
+  const runningServer = await startAiteamServer({
+    preferredPort,
+    version,
+    sessionToken,
+    dataDirectory,
+    logDirectory,
+    secretKeyFilePath: path.join(aiteamHome, 'secret.key'),
+    webRootDirectory,
+    installFatalErrorHandlers: true,
+  });
+
+  // Opened once: the server swaps the token for an HttpOnly cookie and redirects to /.
+  const openUrl = `${runningServer.baseUrl}/?${SESSION_QUERY_PARAM}=${sessionToken}`;
+  const portNotice =
+    runningServer.listenPort === preferredPort
+      ? ''
+      : `
+  Cổng ${preferredPort} đang bận, dùng cổng ${runningServer.listenPort}.`;
+  const readyAfterMs = Math.round(performance.now());
+  console.log(`AI Team v${version} đang chạy
+  Mở:       ${openUrl}
+  Dữ liệu:  ${aiteamHome}
+  Log:      ${path.join(logDirectory, 'aiteam.log')}
+  Sẵn sàng sau ${readyAfterMs} ms. Nhấn Ctrl+C để dừng.${portNotice}`);
+
+  if (options.shouldOpenBrowser) {
+    openBrowser(openUrl);
+  }
+
+  let isStopping = false;
+  const stopOnSignal = (signal) => {
+    if (isStopping) {
+      console.error('Buộc dừng.');
+      process.exit(1);
+    }
+    isStopping = true;
+    console.log(`\nNhận ${signal}, đang dừng...`);
+    runningServer.stopServer().then(
+      () => process.exit(0),
+      (error) => {
+        console.error('Lỗi khi dừng server:', error);
+        process.exit(1);
+      },
+    );
+  };
+  process.on('SIGINT', stopOnSignal);
+  process.on('SIGTERM', stopOnSignal);
+}
+
+/** Runs a fixed, trusted command line (no user input) and returns its first output line. */
+function probeCommand(commandLine) {
+  // shell is required on Windows to resolve .cmd shims (npm-installed CLIs); the command line is
+  // a constant from this file, never user input.
+  const result = spawnSync(commandLine, {
+    shell: true,
+    encoding: 'utf8',
+    timeout: DOCTOR_COMMAND_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+  const firstLine = output.split(/\r?\n/).find((line) => line.trim().length > 0) ?? '';
+  if (result.error !== undefined) {
+    return { passed: false, detail: result.error.message };
+  }
+  return { passed: result.status === 0, detail: firstLine || `exit code ${result.status}` };
+}
+
+function runDoctorChecks() {
+  const checks = [
+    { label: 'node', outcome: { passed: nodeVerdict.accepted, detail: nodeVerdict.reason } },
+    { label: 'git', outcome: probeCommand('git --version') },
+    { label: 'claude --version', outcome: probeCommand('claude --version') },
+    { label: 'codex --version', outcome: probeCommand('codex --version') },
+    { label: 'codex login status', outcome: probeCommand('codex login status') },
+  ];
+
+  console.log('aimanagement doctor');
+  for (const { label, outcome } of checks) {
+    console.log(`  ${outcome.passed ? '[ok]  ' : '[lỗi]'} ${label.padEnd(20)} ${outcome.detail}`);
+  }
+  const failedCount = checks.filter((check) => !check.outcome.passed).length;
+  console.log(failedCount === 0 ? 'Mọi kiểm tra đều đạt.' : `${failedCount} kiểm tra chưa đạt.`);
+  return failedCount === 0 ? 0 : 1;
+}
+
+try {
+  const options = parseLauncherArguments(process.argv.slice(2));
+  if (options.shouldPrintHelp) {
+    printUsage();
+  } else if (options.subcommand === 'doctor') {
+    process.exitCode = runDoctorChecks();
+  } else if (options.subcommand === undefined) {
+    await startApplication(options);
+  } else {
+    printUsage();
+    process.exitCode = 1;
+  }
+} catch (error) {
+  const code = error?.code === undefined ? '' : ` [${error.code}]`;
+  console.error(`aimanagement: ${error?.message ?? error}${code}`);
+  process.exitCode = 1;
+}

package/bin/node-version-policy.mjs

@@ -0,0 +1,71 @@
+// Minimum Node.js version accepted per release line. Only LTS lines that still receive security
+// fixes are allowed, each at its latest security release.
+//
+// Current floor: October 2026 security release (CVE-2026-111497 "Node2Shell" Brotli RCE and
+// 9 other CVEs): 22.23.4, 24.22.1, 26.12.1.
+// Update this table (and package.json "engines", .nvmrc, CLAUDE.md) on every Node security release.
+//
+// Keep this file plain ES2015+ without newer syntax: it must run on old Node to print a clear error.
+
+export const MINIMUM_PATCHED_VERSION_BY_MAJOR = {
+  22: '22.23.4',
+  24: '24.22.1',
+  26: '26.12.1',
+};
+
+/** Release lines newer than the newest known LTS are accepted (future LTS / current releases). */
+const NEWEST_KNOWN_MAJOR = 26;
+
+function parseNodeVersion(versionText) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(versionText);
+  if (match === null) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function compareVersionParts(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) {
+      return left[index] - right[index];
+    }
+  }
+  return 0;
+}
+
+/**
+ * @param {string} versionText e.g. process.version ("v22.23.4")
+ * @returns {{ accepted: boolean, reason: string }}
+ */
+export function evaluateNodeVersion(versionText) {
+  const version = parseNodeVersion(versionText);
+  if (version === null) {
+    return { accepted: false, reason: `Không đọc được phiên bản Node "${versionText}".` };
+  }
+  const major = version[0];
+  const supportedLines = Object.values(MINIMUM_PATCHED_VERSION_BY_MAJOR).join(', ');
+
+  if (major > NEWEST_KNOWN_MAJOR) {
+    return { accepted: true, reason: `Node ${versionText} mới hơn các dòng LTS đã biết.` };
+  }
+
+  const minimumText = MINIMUM_PATCHED_VERSION_BY_MAJOR[major];
+  if (minimumText === undefined) {
+    return {
+      accepted: false,
+      reason: `Node ${versionText} không thuộc dòng LTS còn được vá bảo mật. Hãy cài một trong: ${supportedLines} (hoặc mới hơn trong cùng dòng).`,
+    };
+  }
+
+  const minimum = parseNodeVersion(minimumText);
+  if (compareVersionParts(version, minimum) < 0) {
+    return {
+      accepted: false,
+      reason: `Node ${versionText} thiếu bản vá bảo mật. Cần tối thiểu v${minimumText} cho dòng ${major}.x.`,
+    };
+  }
+  return {
+    accepted: true,
+    reason: `Node ${versionText} đã có bản vá bảo mật mới nhất của dòng ${major}.x.`,
+  };
+}