ai-team 1.0.0

package/src/cli.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+import path from "node:path";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { promises as fs } from "node:fs";
+import chalk from "chalk";
+import ora from "ora";
+import YAML from "yaml";
+import { collectInteractiveProfile } from "./lib/prompts.js";
+import { getAdapter } from "./lib/adapters.js";
+import { planSync, applySync, doctor } from "./lib/sync-engine.js";
+
+function printUsage() {
+  console.log(`${chalk.bold("ai-team")} <command> [options]
+
+Commands:
+  init      Install templates and create .agents/manifest.json
+  update    Update templates using manifest drift detection
+  plan      Dry-run preview of changes
+  diff      Alias of plan
+  doctor    Validate install health and report drift
+
+Options:
+  --ide <vscode|claude-code>
+  --team <web-product>
+  --target <path>           Default: current directory
+  --include-mcp             Include .vscode/mcp.json merge
+  --no-include-mcp          Skip MCP config
+  --force                   Overwrite locally modified copy-tracked files
+  --yes                     Non-interactive defaults
+  --migrate                 Apply legacy migration moves when safe
+  --json                    Emit machine-readable output
+`);
+}
+
+function createSpinner(values, text) {
+  const canUseSpinner = !values.json && process.stdout.isTTY;
+  return ora({ text, isEnabled: canUseSpinner }).start();
+}
+
+function canResolveProfileWithoutPrompt(values, command) {
+  if (values.yes || command === "doctor" || process.env.CI === "true") {
+    return true;
+  }
+
+  const hasIncludeMcpOption =
+    values["include-mcp"] !== undefined ||
+    values["no-include-mcp"] !== undefined;
+
+  return Boolean(values.ide && values.team && hasIncludeMcpOption);
+}
+
+function parseBooleanOption(values, key, fallback) {
+  if (values[key] === undefined) {
+    return fallback;
+  }
+
+  return Boolean(values[key]);
+}
+
+function summarizePlan(plan) {
+  const counts = { create: 0, overwrite: 0, merge: 0, unchanged: 0, skip: 0 };
+  for (const action of plan.actions) {
+    counts[action.action] = (counts[action.action] ?? 0) + 1;
+  }
+
+  return {
+    templateVersion: plan.templateVersion,
+    actions: counts,
+    conflicts: plan.conflicts.length,
+    migrationMoves: plan.legacyMoves.length,
+  };
+}
+
+function parseFrontmatterDescription(text) {
+  const normalized = text.replace(/^```[^\n]*\r?\n/, "");
+  const match = normalized.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n/);
+  if (!match) {
+    return null;
+  }
+
+  try {
+    const frontmatter = YAML.parse(match[1]);
+    if (typeof frontmatter?.description === "string") {
+      return frontmatter.description.trim();
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+async function getInstalledAgents(manifest, targetDir, writtenPaths = null) {
+  const ide = manifest?.profile?.ide ?? "vscode";
+  const isClaudeCode = ide === "claude-code" || ide === "claude";
+  const agentsPrefix = isClaudeCode ? ".claude/agents/" : ".github/agents/";
+  const agentsSuffix = isClaudeCode ? ".md" : ".agent.md";
+
+  const agentPaths = Object.keys(manifest?.files ?? {})
+    .filter(
+      (targetPath) =>
+        targetPath.startsWith(agentsPrefix) &&
+        targetPath.endsWith(agentsSuffix) &&
+        (writtenPaths === null || writtenPaths.has(targetPath)),
+    )
+    .sort();
+
+  const agents = [];
+  for (const agentPath of agentPaths) {
+    const agentName = path.basename(agentPath, agentsSuffix);
+    let description = null;
+
+    try {
+      const content = await fs.readFile(
+        path.join(targetDir, agentPath),
+        "utf8",
+      );
+      description = parseFrontmatterDescription(content);
+    } catch {
+      description = null;
+    }
+
+    agents.push({ name: agentName, description });
+  }
+
+  return agents;
+}
+
+function wrapText(text, { indent = "", maxWidth = 100 } = {}) {
+  if (!text) {
+    return [];
+  }
+
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = "";
+
+  for (const word of words) {
+    const candidate = current ? `${current} ${word}` : word;
+    if (candidate.length > maxWidth && current) {
+      lines.push(`${indent}${current}`);
+      current = word;
+      continue;
+    }
+
+    current = candidate;
+  }
+
+  if (current) {
+    lines.push(`${indent}${current}`);
+  }
+
+  return lines;
+}
+
+async function printInitAgentUsage(result, targetDir) {
+  const { manifest } = result;
+  const writtenPaths = new Set(result.written.map((w) => w.targetPath));
+  const agents = await getInstalledAgents(manifest, targetDir, writtenPaths);
+  if (agents.length === 0) {
+    return;
+  }
+
+  const columns = process.stdout.columns ?? 120;
+  const wrapWidth = Math.max(60, columns - 8);
+
+  console.log("");
+  console.log(chalk.bold.cyan("Installed agents"));
+  for (const agent of agents) {
+    console.log(`- ${chalk.greenBright(`@${agent.name}`)}`);
+
+    if (!agent.description) {
+      console.log("");
+      continue;
+    }
+
+    const wrappedDescription = wrapText(agent.description, {
+      indent: "  ",
+      maxWidth: wrapWidth,
+    });
+    for (const line of wrappedDescription) {
+      console.log(chalk.italic.white(line));
+    }
+
+    console.log("");
+  }
+
+  console.log("");
+
+  const printWrappedBullet = (text) => {
+    const wrapped = wrapText(text, { maxWidth: wrapWidth - 2 });
+    if (wrapped.length === 0) {
+      return;
+    }
+
+    console.log(`- ${wrapped[0].trim()}`);
+    for (const continuation of wrapped.slice(1)) {
+      console.log(`  ${continuation.trim()}`);
+    }
+  };
+
+  const ide = manifest?.profile?.ide ?? "vscode";
+  const isClaudeCode = ide === "claude-code" || ide === "claude";
+
+  if (isClaudeCode) {
+    console.log(chalk.bold.cyan("Quick start in Claude Code"));
+    printWrappedBullet("Run /agents to view and manage installed subagents.");
+    printWrappedBullet(
+      "Ask Claude to delegate: use the product-team-orchestrator to plan and coordinate <feature>.",
+    );
+    printWrappedBullet(
+      "Continue by naming specialist agents directly or letting the orchestrator route to them.",
+    );
+  } else {
+    console.log(chalk.bold.cyan("Quick start in VS Code Chat"));
+    printWrappedBullet(
+      "Select the product-team-orchestrator agent from the chat session and describe your feature.",
+    );
+    printWrappedBullet(
+      "The orchestrator can delegate to specialist agents automatically or you can call them directly by changing the agent selector.",
+    );
+  }
+}
+
+function printPlan(plan) {
+  const summary = summarizePlan(plan);
+  console.log(chalk.cyan(`Template version: ${summary.templateVersion}`));
+  console.log(
+    `Actions: create=${summary.actions.create} overwrite=${summary.actions.overwrite} merge=${summary.actions.merge} unchanged=${summary.actions.unchanged} skip=${summary.actions.skip}`,
+  );
+
+  if (plan.conflicts.length > 0) {
+    console.log(chalk.yellow("Conflicts:"));
+    for (const conflict of plan.conflicts) {
+      console.log(`- ${conflict.targetPath} (${conflict.reason})`);
+    }
+  }
+
+  if (plan.legacyMoves.length > 0) {
+    console.log(chalk.yellow("Legacy migration preview:"));
+    for (const move of plan.legacyMoves) {
+      console.log(`- ${move.from} -> ${move.to}`);
+    }
+  }
+}
+
+async function resolveProfile(values, command) {
+  const includeMcp = values["include-mcp"];
+  const noIncludeMcp = values["no-include-mcp"];
+  const includeMcpValue = includeMcp ? true : noIncludeMcp ? false : undefined;
+
+  const profile = await collectInteractiveProfile({
+    ide: values.ide,
+    team: values.team,
+    includeMcp: includeMcpValue,
+    yes: values.yes || command === "doctor",
+  });
+
+  getAdapter(profile.ide);
+  return profile;
+}
+
+function asJson(values, payload) {
+  if (values.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return true;
+  }
+
+  return false;
+}
+
+async function run() {
+  const [, , commandArg] = process.argv;
+  const command = commandArg === "diff" ? "plan" : commandArg;
+
+  if (!command || ["-h", "--help", "help"].includes(command)) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!["init", "update", "plan", "doctor"].includes(command)) {
+    console.error(`Unsupported command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  const { values } = parseArgs({
+    options: {
+      ide: { type: "string" },
+      team: { type: "string" },
+      target: { type: "string" },
+      force: { type: "boolean", default: false },
+      yes: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      migrate: { type: "boolean", default: false },
+      "include-mcp": { type: "boolean" },
+      "no-include-mcp": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+  const targetDir = path.resolve(values.target ?? process.cwd());
+
+  if (command === "doctor") {
+    const spinner = createSpinner(values, "Running health checks");
+    const report = await doctor({ targetDir });
+    spinner.stop();
+
+    if (asJson(values, report)) {
+      process.exit(report.ok ? 0 : 1);
+    }
+
+    if (report.issues.length === 0) {
+      console.log(chalk.green("Doctor: OK"));
+    } else {
+      console.log(chalk.red("Doctor issues:"));
+      for (const issue of report.issues) {
+        console.log(`- [${issue.level}] ${issue.code}: ${issue.message}`);
+      }
+    }
+
+    if (report.legacyMoves.length > 0) {
+      console.log("Legacy migration preview:");
+      for (const move of report.legacyMoves) {
+        console.log(`- ${move.from} -> ${move.to}`);
+      }
+    }
+
+    process.exit(report.ok ? 0 : 1);
+  }
+
+  let profile;
+  if (canResolveProfileWithoutPrompt(values, command)) {
+    const profileSpinner = createSpinner(values, "Resolving profile");
+    profile = await resolveProfile(values, command);
+    profileSpinner.succeed("Profile resolved");
+  } else {
+    profile = await resolveProfile(values, command);
+  }
+
+  const force = parseBooleanOption(values, "force", false);
+  const planSpinner = createSpinner(values, "Computing sync plan");
+  const plan = await planSync({ targetDir, profile, force, command });
+  planSpinner.succeed("Sync plan ready");
+
+  if (command === "plan") {
+    if (asJson(values, plan)) {
+      return;
+    }
+
+    printPlan(plan);
+    return;
+  }
+
+  const applySpinner = createSpinner(values, "Applying changes");
+  const result = await applySync(plan, { applyMigration: values.migrate });
+  applySpinner.succeed("Changes applied");
+
+  if (asJson(values, result)) {
+    return;
+  }
+
+  const summary = summarizePlan(plan);
+  console.log(chalk.green(`${command} completed on ${targetDir}`));
+  console.log(chalk.cyan(`Template version: ${summary.templateVersion}`));
+  console.log(
+    `Written files: ${result.written.length}, skipped: ${result.skipped.length}, conflicts: ${result.conflicts.length}`,
+  );
+
+  if (result.conflicts.length > 0) {
+    console.log(
+      chalk.yellow(
+        "Conflicts (rerun with --force to overwrite copy-tracked files):",
+      ),
+    );
+    for (const conflict of result.conflicts) {
+      console.log(`- ${conflict.targetPath} (${conflict.reason})`);
+    }
+  }
+
+  if (result.migration.length > 0) {
+    console.log(chalk.yellow("Migration results:"));
+    for (const move of result.migration) {
+      console.log(`- ${move.from} -> ${move.to} (${move.status})`);
+    }
+  }
+
+  if (command === "init") {
+    await printInitAgentUsage(result, targetDir);
+  }
+}
+
+run().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/src/lib/adapters.js

@@ -0,0 +1,41 @@
+export function createVscodeAdapter() {
+  return {
+    id: "vscode-copilot",
+    applyOverlay() {
+      return "vscode-copilot";
+    },
+    pathMap(relativePath) {
+      return relativePath;
+    },
+    postInstall() {
+      return [];
+    },
+  };
+}
+
+export function createClaudeCodeAdapter() {
+  return {
+    id: "claude-code",
+    applyOverlay() {
+      return "claude-code";
+    },
+    pathMap(relativePath) {
+      return relativePath;
+    },
+    postInstall() {
+      return [];
+    },
+  };
+}
+
+export function getAdapter(ide) {
+  if (ide === "vscode" || ide === "copilot") {
+    return createVscodeAdapter();
+  }
+
+  if (ide === "claude-code" || ide === "claude") {
+    return createClaudeCodeAdapter();
+  }
+
+  throw new Error(`Unsupported IDE adapter: ${ide}`);
+}

package/src/lib/fs-utils.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDirForFile(filePath) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+export async function readTextIfExists(filePath) {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+
+  return fs.readFile(filePath, "utf8");
+}
+
+export async function readJsonIfExists(filePath) {
+  const raw = await readTextIfExists(filePath);
+  if (raw === null) {
+    return null;
+  }
+
+  return JSON.parse(raw);
+}
+
+export async function writeText(filePath, text) {
+  await ensureDirForFile(filePath);
+  await fs.writeFile(filePath, text, "utf8");
+}
+
+export async function writeJson(filePath, data) {
+  await writeText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export async function listFilesRecursive(rootPath) {
+  const results = [];
+
+  async function walk(currentPath) {
+    const entries = await fs.readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolute = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolute);
+      } else if (entry.isFile()) {
+        results.push(absolute);
+      }
+    }
+  }
+
+  await walk(rootPath);
+  return results;
+}

package/src/lib/hash.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+export function hashText(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+export function hashBuffer(value) {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/lib/manifest.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { readJsonIfExists, writeJson } from "./fs-utils.js";
+
+export function getManifestPath(targetDir) {
+  return path.join(targetDir, ".agents/manifest.json");
+}
+
+export async function loadInstalledManifest(targetDir) {
+  const manifestPath = getManifestPath(targetDir);
+  return readJsonIfExists(manifestPath);
+}
+
+export async function writeInstalledManifest(targetDir, manifest) {
+  const manifestPath = getManifestPath(targetDir);
+  await writeJson(manifestPath, manifest);
+}
+
+export function createManifest({
+  templateVersion,
+  schemaVersion,
+  profile,
+  files,
+}) {
+  const now = new Date().toISOString();
+
+  return {
+    schemaVersion,
+    templateVersion,
+    installedAt: now,
+    updatedAt: now,
+    profile,
+    files,
+  };
+}
+
+export function bumpManifest(
+  manifest,
+  { templateVersion, schemaVersion, profile, files },
+) {
+  const now = new Date().toISOString();
+
+  return {
+    ...manifest,
+    schemaVersion,
+    templateVersion,
+    updatedAt: now,
+    profile,
+    files,
+  };
+}

package/src/lib/migration.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { pathExists } from "./fs-utils.js";
+
+export async function detectLegacyLayout(targetDir) {
+  const moves = [];
+  const legacyTeamDirs = ["web-product", "gympt"];
+
+  for (const teamDir of legacyTeamDirs) {
+    const legacyAgentsDir = path.join(
+      targetDir,
+      `.agents/teams/${teamDir}/agents`,
+    );
+    const exists = await pathExists(legacyAgentsDir);
+
+    if (!exists) {
+      continue;
+    }
+
+    const entries = await fs.readdir(legacyAgentsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".agent.md")) {
+        continue;
+      }
+
+      moves.push({
+        from: `.agents/teams/${teamDir}/agents/${entry.name}`,
+        to: `.github/agents/${entry.name}`,
+      });
+    }
+  }
+
+  return moves;
+}
+
+export async function applyLegacyMigration(targetDir, moves) {
+  const results = [];
+
+  for (const move of moves) {
+    const fromAbs = path.join(targetDir, move.from);
+    const toAbs = path.join(targetDir, move.to);
+
+    if (!(await pathExists(fromAbs))) {
+      results.push({ ...move, status: "missing-source" });
+      continue;
+    }
+
+    if (await pathExists(toAbs)) {
+      results.push({ ...move, status: "destination-exists" });
+      continue;
+    }
+
+    await fs.mkdir(path.dirname(toAbs), { recursive: true });
+    await fs.rename(fromAbs, toAbs);
+    results.push({ ...move, status: "moved" });
+  }
+
+  return results;
+}