@shanyucoder/flowgrid 0.1.0

package/bin/lib/agent-mcp.mjs

@@ -0,0 +1,70 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveAgentMcpConfigPath } from './agent-profiles.mjs';
+
+/**
+ * MCP environment variables shared by Cursor, Antigravity, and other agent installs.
+ */
+export function buildMcpEnv({
+  projectRoot = process.cwd(),
+  selectedType,
+  feDocRoot,
+  feTestRoot,
+  feAdapter,
+  beAdapter,
+  defaultLanguage,
+}) {
+  const env = {};
+  const base = path.resolve(projectRoot);
+  if (selectedType !== 'Document') {
+    if (feDocRoot) {
+      env.FLOWGRID_DOCS_ROOT = path.resolve(base, feDocRoot);
+    }
+    if (feTestRoot) {
+      env.FLOWGRID_TESTS_DOC = path.resolve(base, feTestRoot);
+    }
+  }
+  if (feAdapter) {
+    env.FLOWGRID_ADAPTER = feAdapter;
+    env.FLOWGRID_CODE_ROLE = 'fe';
+  }
+  if (beAdapter) {
+    env.FLOWGRID_BE_ADAPTER = beAdapter;
+    if (!feAdapter) {
+      env.FLOWGRID_ADAPTER = beAdapter;
+      env.FLOWGRID_CODE_ROLE = 'be';
+    }
+  }
+  if (defaultLanguage) {
+    env.FLOWGRID_DEFAULT_LANG = defaultLanguage;
+  }
+  return env;
+}
+
+function mcpServerEntry(packageRoot, scriptName, env) {
+  const entry = {
+    command: 'node',
+    args: [path.join(packageRoot, 'bin', scriptName)],
+  };
+  if (env && Object.keys(env).length > 0) {
+    entry.env = env;
+  }
+  return entry;
+}
+
+export function buildMcpConfig(packageRoot, env) {
+  return {
+    mcpServers: {
+      flowgrid: mcpServerEntry(packageRoot, 'flowgrid-mcp.mjs', env),
+    },
+  };
+}
+
+export { resolveAgentMcpConfigPath };
+
+export function writeAgentMcpConfig({ agent, agentDir, packageRoot, env }) {
+  const config = buildMcpConfig(packageRoot, env);
+  const configPath = resolveAgentMcpConfigPath(agent, agentDir);
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  return configPath;
+}

package/bin/lib/agent-profiles.mjs

@@ -0,0 +1,127 @@
+import * as path from 'node:path';
+
+/**
+ * Per-agent harness layout (common package + agent-specific overlay).
+ * Sync builds one project staging bundle, then materializes per agent dir + overlay.
+ */
+
+/** @type {Record<string, {
+ *   id: string;
+ *   dirName: string;
+ *   mcpFile: string;
+ *   label: string;
+ *   readTool: string;
+ *   writeTool: string;
+ *   overlayFile: string;
+ *   registryPathPrefix: string;
+ * }>} */
+export const AGENT_PROFILES = {
+  cursor: {
+    id: 'cursor',
+    dirName: '.cursor',
+    mcpFile: 'mcp.json',
+    label: 'Cursor',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.cursor',
+  },
+  gemini_antigravity: {
+    id: 'gemini_antigravity',
+    dirName: '.agents',
+    mcpFile: 'mcp_config.json',
+    label: 'Antigravity',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.agents',
+  },
+  claude: {
+    id: 'claude',
+    dirName: '.claude',
+    mcpFile: 'mcp.json',
+    label: 'Claude Code',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.claude',
+  },
+  codex: {
+    id: 'codex',
+    dirName: '.codex',
+    mcpFile: 'mcp.json',
+    label: 'Codex CLI',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.codex',
+  },
+  opencode: {
+    id: 'opencode',
+    dirName: '.opencode',
+    mcpFile: 'mcp.json',
+    label: 'OpenCode',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.opencode',
+  },
+  hermes: {
+    id: 'hermes',
+    dirName: '.hermes',
+    mcpFile: 'mcp.json',
+    label: 'Hermes',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.hermes',
+  },
+  kiro: {
+    id: 'kiro',
+    dirName: '.kiro',
+    mcpFile: 'mcp.json',
+    label: 'Kiro',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.kiro',
+  },
+  kilo: {
+    id: 'kilo',
+    dirName: '.kilo',
+    mcpFile: 'mcp.json',
+    label: 'Kilo Code',
+    readTool: 'Read',
+    writeTool: 'Write',
+    overlayFile: 'AGENTS.md',
+    registryPathPrefix: '.kilo',
+  },
+};
+
+const DEFAULT_PROFILE = {
+  id: 'unknown',
+  dirName: '.flowgrid-agent',
+  mcpFile: 'mcp.json',
+  label: 'Agent',
+  readTool: 'Read',
+  writeTool: 'Write',
+  overlayFile: 'AGENTS.md',
+  registryPathPrefix: '.flowgrid-agent',
+};
+
+export function getAgentProfile(agent) {
+  return AGENT_PROFILES[agent] ?? { ...DEFAULT_PROFILE, id: agent, label: agent };
+}
+
+export function resolveAgentDir(agent) {
+  return getAgentProfile(agent).dirName;
+}
+
+export function resolveAgentMcpConfigPath(agent, agentDir) {
+  const { mcpFile } = getAgentProfile(agent);
+  return path.join(agentDir, mcpFile);
+}
+
+export function agentHarnessOverlayPath(packageRoot, agent) {
+  return path.join(packageRoot, 'harness', 'agents', agent);
+}

package/bin/lib/audit-run.mjs

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+/** @type {Record<string, string>} */
+export const AUDIT_ENGINES = {
+  'audit:spec': 'engines/spec/lib/audit-bundle-gaps.mjs',
+  'audit:flow': 'engines/spec/lib/audit-flow-gaps.mjs',
+  'audit:api': 'engines/spec/lib/audit-api-gaps.mjs',
+  'audit:testcase': 'engines/spec/lib/audit-testcase-gaps.mjs',
+  'audit:legacy': 'engines/spec/lib/audit-legacy-gaps.mjs',
+  'audit:fe-be': 'engines/spec/lib/audit-fe-be-alignment.mjs',
+  'audit:scenario': 'engines/spec/lib/audit-scenario-coverage.mjs',
+  'audit:e2e': 'engines/spec/lib/audit-e2e-coverage.mjs',
+};
+
+/** Short names for `flowgrid audit <name>`. */
+export const AUDIT_SUBCOMMANDS = Object.keys(AUDIT_ENGINES).map((k) => k.replace('audit:', ''));
+
+export function printAuditHelp() {
+  const lines = [
+    'FlowGrid audit — deterministic gap scripts (JSON on stdout)',
+    '',
+    'Usage:',
+    '  flowgrid audit <kind> [engine args...]',
+    '  flowgrid audit:<kind> [engine args...]',
+    '',
+    'Kinds:',
+    '  spec       bundle YAML gaps (--type pageType)',
+    '  flow       FLOW-*.md business process sections',
+    '  api        API bundle / 01-backend-spec gaps',
+    '  testcase   TC-*.yaml (v2) or legacy plan; --bundle cross-ref bundle',
+    '  fe-be      bundle apiRef vs 01-backend-spec alignment',
+    '  scenario   cross-flow SC screens vs cases/** TC coverage',
+    '  e2e        TC YAML vs Playwright (--e2e-root, --tests-docs)',
+    '  legacy     legacy adoption / target-id gaps',
+    '',
+    'Examples:',
+    '  flowgrid audit spec surfaces/.../foo.bundle.yaml --type list',
+    '  flowgrid audit:api surfaces/.../api/01/01-backend-spec.yaml',
+    '',
+  ];
+  console.log(lines.join('\n'));
+}
+
+/**
+ * @param {string[]} argv — args after `flowgrid` (command + rest)
+ * @returns {{ command: string; argv: string[] } | null}
+ */
+export function resolveAuditInvocation(argv) {
+  const [head, ...rest] = argv;
+  if (!head) return null;
+
+  if (head === 'audit') {
+    const sub = rest[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+      return { command: '__help__', argv: [] };
+    }
+    const key = sub.startsWith('audit:') ? sub : `audit:${sub}`;
+    if (!AUDIT_ENGINES[key]) {
+      throw new Error(`Unknown audit kind "${sub}". Use: ${AUDIT_SUBCOMMANDS.join(', ')}`);
+    }
+    return { command: key, argv: rest.slice(1) };
+  }
+
+  if (AUDIT_ENGINES[head]) {
+    return { command: head, argv: rest };
+  }
+
+  return null;
+}
+
+export function runAuditCommand(command, argv) {
+  if (command === '__help__') {
+    printAuditHelp();
+    return 0;
+  }
+
+  const rel = AUDIT_ENGINES[command];
+  if (!rel) {
+    throw new Error(
+      `Unknown audit command: ${command}. Use: ${Object.keys(AUDIT_ENGINES).join(', ')}`,
+    );
+  }
+  const script = path.join(packageRoot, rel);
+  const res = spawnSync(process.execPath, [script, ...argv], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    stdio: ['inherit', 'pipe', 'pipe'],
+  });
+  if (res.stdout) process.stdout.write(res.stdout);
+  if (res.stderr) process.stderr.write(res.stderr);
+  return res.status ?? 1;
+}

package/bin/lib/cli-update.mjs

@@ -0,0 +1,254 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  NPM_PACKAGE,
+  installSourceFromPath,
+  isPackageOnRegistry,
+  registryLatestVersion,
+} from './npm-registry.mjs';
+
+const DEFAULT_REPO = 'ShanYuCoder/flowgrid';
+const GITHUB_PKG = (repo) => `github:${repo}`;
+const PNPM_ALLOW_BUILD = `--allow-build=${NPM_PACKAGE}`;
+
+function tryCommand(cmd, args) {
+  const exe = process.platform === 'win32' && !cmd.endsWith('.cmd') ? `${cmd}.cmd` : cmd;
+  const res = spawnSync(exe, args, { encoding: 'utf8', shell: process.platform === 'win32' });
+  if (res.status !== 0) return null;
+  return (res.stdout || '').trim();
+}
+
+function hasCommand(cmd) {
+  const check = process.platform === 'win32' ? 'where' : 'which';
+  const res = spawnSync(check, [cmd], { encoding: 'utf8', shell: process.platform === 'win32' });
+  return res.status === 0;
+}
+
+function readPackageVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version ?? '?';
+  } catch {
+    return '?';
+  }
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {'git-clone' | 'git-dev' | 'pnpm-global' | 'npm-global' | 'unknown'}
+ */
+export function detectInstallKind(packageRoot) {
+  const root = fs.realpathSync(packageRoot);
+  const gitDir = path.join(root, '.git');
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const installDir = process.env.FLOWGRID_INSTALL_DIR || path.join(home, '.flowgrid-cli');
+  const installReal = fs.existsSync(installDir) ? fs.realpathSync(installDir) : null;
+
+  if (fs.existsSync(gitDir)) {
+    if (installReal && (root === installReal || root.startsWith(installReal + path.sep))) {
+      return 'git-clone';
+    }
+    return 'git-dev';
+  }
+
+  const pnpmRoot = tryCommand('pnpm', ['root', '-g']);
+  if (pnpmRoot && fs.existsSync(pnpmRoot)) {
+    const pnpmReal = fs.realpathSync(pnpmRoot);
+    if (root.startsWith(pnpmReal + path.sep) || root === pnpmReal) {
+      return 'pnpm-global';
+    }
+  }
+
+  const npmPrefix = tryCommand('npm', ['prefix', '-g']);
+  if (npmPrefix) {
+    const slash = NPM_PACKAGE.indexOf('/');
+    const nm = path.join(
+      npmPrefix,
+      'node_modules',
+      NPM_PACKAGE.slice(0, slash),
+      NPM_PACKAGE.slice(slash + 1),
+    );
+    if (fs.existsSync(nm)) {
+      const nmReal = fs.realpathSync(nm);
+      if (nmReal === root) return 'npm-global';
+    }
+  }
+
+  return 'unknown';
+}
+
+function resolveLatestRef(repo) {
+  if (process.env.FLOWGRID_REF) return process.env.FLOWGRID_REF;
+  const out = spawnSync(
+    'git',
+    ['ls-remote', '--tags', '--sort=v:refname', `https://github.com/${repo}.git`],
+    { encoding: 'utf8' },
+  );
+  if (out.status === 0 && out.stdout) {
+    const lines = out.stdout.trim().split('\n').filter((l) => l && !l.includes('^{}'));
+    if (lines.length) {
+      const last = lines[lines.length - 1];
+      const tag = last.split('/').pop();
+      if (tag) return tag;
+    }
+  }
+  return 'main';
+}
+
+function runInherit(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32', ...opts });
+  if (res.status === 0) return 0;
+  return res.status ?? 1;
+}
+
+function buildPackage(packageRoot) {
+  if (hasCommand('pnpm')) {
+    if (runInherit('pnpm', ['install'], { cwd: packageRoot }) !== 0) return 1;
+    return runInherit('pnpm', ['run', 'build'], { cwd: packageRoot });
+  }
+  if (hasCommand('npm')) {
+    if (runInherit('npm', ['install'], { cwd: packageRoot }) !== 0) return 1;
+    return runInherit('npm', ['run', 'build'], { cwd: packageRoot });
+  }
+  return 1;
+}
+
+function updateGitClone(packageRoot, _repo, ref) {
+  if (ref === 'main') {
+    if (runInherit('git', ['fetch', '--depth', '1', 'origin', 'main'], { cwd: packageRoot }) !== 0) return 1;
+    if (runInherit('git', ['checkout', '-f', 'main'], { cwd: packageRoot }) !== 0) return 1;
+    if (runInherit('git', ['reset', '--hard', 'origin/main'], { cwd: packageRoot }) !== 0) return 1;
+  } else {
+    if (
+      runInherit('git', ['fetch', '--depth', '1', 'origin', `refs/tags/${ref}:refs/tags/${ref}`], {
+        cwd: packageRoot,
+      }) !== 0 &&
+      runInherit('git', ['fetch', 'origin', '--tags'], { cwd: packageRoot }) !== 0
+    ) {
+      return 1;
+    }
+    if (runInherit('git', ['checkout', '-f', ref], { cwd: packageRoot }) !== 0) return 1;
+  }
+  return buildPackage(packageRoot);
+}
+
+function updateGitDev(packageRoot) {
+  if (runInherit('git', ['pull', '--ff-only'], { cwd: packageRoot }) !== 0) {
+    return runInherit('git', ['pull'], { cwd: packageRoot });
+  }
+  return buildPackage(packageRoot);
+}
+
+function updatePnpmFromGithub(repo) {
+  return runInherit('pnpm', ['add', '-g', GITHUB_PKG(repo), PNPM_ALLOW_BUILD]);
+}
+
+function updatePnpmFromRegistry() {
+  return runInherit('pnpm', ['add', '-g', `${NPM_PACKAGE}@latest`]);
+}
+
+function updateNpmFromGithub(repo) {
+  return runInherit('npm', ['install', '-g', GITHUB_PKG(repo)]);
+}
+
+function updateNpmFromRegistry() {
+  return runInherit('npm', ['install', '-g', `${NPM_PACKAGE}@latest`]);
+}
+
+/**
+ * @param {'pnpm' | 'npm'} tool
+ * @param {string} packageRoot
+ * @param {string} repo
+ */
+function updateGlobalPackageManager(tool, packageRoot, repo) {
+  if (installSourceFromPath(packageRoot) === 'registry' && isPackageOnRegistry()) {
+    return tool === 'pnpm' ? updatePnpmFromRegistry() : updateNpmFromRegistry();
+  }
+  return tool === 'pnpm' ? updatePnpmFromGithub(repo) : updateNpmFromGithub(repo);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.packageRoot
+ * @param {string[]} [opts.argv]
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {number} exit code
+ */
+export function runCliUpdate(opts) {
+  const { packageRoot, argv = [] } = opts;
+  const log = opts.log ?? console.log;
+  const repo = process.env.FLOWGRID_REPO || DEFAULT_REPO;
+  const before = readPackageVersion(packageRoot);
+  const kind = detectInstallKind(packageRoot);
+  const registryVer = registryLatestVersion();
+
+  if (argv.includes('--check')) {
+    log(`FlowGrid v${before} (${kind}, nguồn: ${installSourceFromPath(packageRoot)})`);
+    if (registryVer) {
+      log(`npm registry: ${NPM_PACKAGE}@${registryVer}`);
+    } else {
+      log(`npm registry: chưa publish — fallback GitHub github:${repo}`);
+    }
+    log('Chạy `flowgrid update` để nâng cấp.');
+    return 0;
+  }
+
+  log(`Đang cập nhật FlowGrid (hiện tại v${before}, cách cài: ${kind})…`);
+
+  let code = 1;
+  switch (kind) {
+    case 'git-clone': {
+      const ref = resolveLatestRef(repo);
+      log(`Git fetch github.com/${repo} @ ${ref}`);
+      code = updateGitClone(packageRoot, repo, ref);
+      break;
+    }
+    case 'git-dev':
+      log('Git pull + build (bản clone toolkit / pnpm link).');
+      code = updateGitDev(packageRoot);
+      break;
+    case 'pnpm-global':
+      if (isPackageOnRegistry() && installSourceFromPath(packageRoot) === 'registry') {
+        log(`pnpm add -g ${NPM_PACKAGE}@latest`);
+      } else if (isPackageOnRegistry()) {
+        log(`pnpm add -g ${NPM_PACKAGE}@latest (fallback GitHub nếu lỗi)`);
+      } else {
+        log(`pnpm add -g ${GITHUB_PKG(repo)}`);
+      }
+      code = updateGlobalPackageManager('pnpm', packageRoot, repo);
+      break;
+    case 'npm-global':
+      if (isPackageOnRegistry()) {
+        log(`npm install -g ${NPM_PACKAGE}@latest`);
+      } else {
+        log(`npm install -g ${GITHUB_PKG(repo)}`);
+      }
+      code = updateGlobalPackageManager('npm', packageRoot, repo);
+      break;
+    default:
+      log('Không xác định được cách cài. Thử một trong các lệnh sau:');
+      if (isPackageOnRegistry()) {
+        log(`  pnpm add -g ${NPM_PACKAGE}`);
+        log(`  npm install -g ${NPM_PACKAGE}`);
+      } else {
+        log(`  pnpm add -g ${GITHUB_PKG(repo)} ${PNPM_ALLOW_BUILD}`);
+        log(`  npm install -g ${GITHUB_PKG(repo)}`);
+      }
+      log('  Hoặc chạy lại install.sh (Linux/WSL) sau khi đã gỡ bản cũ.');
+      return 1;
+  }
+
+  if (code !== 0) {
+    return code;
+  }
+
+  const after = readPackageVersion(packageRoot);
+  if (kind === 'pnpm-global' || kind === 'npm-global') {
+    log('Hoàn tất. Chạy `flowgrid --version` trong terminal mới nếu bin chưa đổi.');
+  } else {
+    log(`Hoàn tất. FlowGrid v${before} → v${after}`);
+  }
+  return 0;
+}